# Welcome to Starwind UI

Starwind UI is a layered component system for Astro, React, 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.

## Start With A Styled Component

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

```astro
<Button>Hello World</Button>
```

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` or `@starwind-ui/react` 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 show the Behavior Foundation and Framework Availability near the top so you can see that relationship without leaving the styled docs.

## Deeper References

- [Installation](/docs/getting-started/installation/) covers recommended CLI initialization, current manual setup, and the first rendered styled component.
- [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 framework availability for each 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` or `@starwind-ui/react` 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.