# Welcome to Starwind UI

Starwind UI is a layered component system for Astro, React, the Vue public beta, and plain HTML. Start by rendering a styled component. Reach for Primitive adapters, Runtime APIs, raw HTML, or component-level customization only when you need that level of control.

> **Info:** The beginner path is still source-first: add a styled component, render it, and customize the code in your app.

[Choose your framework](/docs/getting-started/installation/#choose-your-framework) to open the
installation guide for your host framework.

Astro and React adapters are stable. **Vue 3.5 is in public beta**, with editable Styled components
and Primitive adapters. Choose a [Vue host guide](/docs/getting-started/installation/#vue-beta).

## Start With A Styled Component

Install the project defaults, add `Button`, and render it in your app.

<FrameworkCodeSwitcher>
<div slot="astro">
```astro
<Button>Hello World</Button>
```
</div>
<div slot="react">
```tsx
import { Button } from "@/components/starwind/button";

export function Example() {
  return <Button>Hello World</Button>;
}
```
</div>
<div slot="vue">
```vue
<script setup lang="ts">
import { Button } from "@/components/starwind/button";
</script>

<template>
  <Button>Hello World</Button>
</template>
```
</div>
</FrameworkCodeSwitcher>

For most projects this is the right first step. The styled component owns the public Starwind ergonomics, styling variants, and default markup for your framework.

## Choose Your Path

- **Styled components**: Use the CLI and component docs when you want ready-to-render UI that you can edit in your project.
- **Primitive adapter**: Use `@starwind-ui/astro`, `@starwind-ui/react`, or the beta `@starwind-ui/vue` when you want behavior and anatomy without the styled wrapper.
- **Runtime/raw HTML**: Use `@starwind-ui/runtime` and `initStarwind` when you are rendering static markup or integrating outside a framework adapter.
- **Theming and component APIs**: Use the Theming guide for tokens and component pages for slots, variants, and state selectors.

## Naming Rule

Styled components are named for Starwind ergonomics; primitives are named for behavior and anatomy.

That means a styled component can combine multiple primitives, rename a primitive, or have no primitive at all. Component pages identify that Behavior Foundation and link to the lower-level references so you can follow the relationship without leaving the styled docs.

## Deeper References

- [Installation](/docs/getting-started/installation/) covers CLI initialization, framework choices, and the first rendered styled component.
- [Manual Setup](/docs/getting-started/manual-setup/) covers the shared packages, config, source paths, and base stylesheet.
- [Primitives](/docs/getting-started/primitives/) explains package imports, vendored source, ownership, and framework targeting.
- [Primitive API Reference](/docs/primitives/) is the behavior-first reference for individual Primitive adapters.
- [Runtime And Raw HTML](/docs/runtime/) documents low-level Runtime APIs and the raw HTML surface.
- [Theming](/docs/getting-started/theming/) covers CSS variables, Tailwind integration, and theme customization.
- Component pages cover slots, variants, state selectors, and any framework-specific guidance that affects how you use a styled component.
- [Migration Guide](/docs/getting-started/migration/) explains how the old Astro styled-component docs map into the layered model.

## Glossary

- **Styled adapter contract**: The generated contract that connects a styled component to framework support, exported files, variants, slots, and any behavior foundation.
- **Primitive adapter**: A framework package such as `@starwind-ui/astro`, `@starwind-ui/react`, or the beta `@starwind-ui/vue` that renders Runtime-backed behavior and anatomy.
- **Runtime**: The framework-agnostic package that owns DOM behavior, state, events, cleanup, and theme helpers.
- **raw HTML surface**: Static markup that uses `data-sw-*` discovery hooks and is initialized by the Runtime.