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.

Start With A Styled Component

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

---
import { Button } from "@/components/starwind/button";
---

<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 covers recommended CLI initialization, current manual setup, and the first rendered styled component.
• Primitives explains package imports, vendored source, ownership, and framework targeting.
• Primitive API Reference is the behavior-first reference for individual Primitive adapters.
• Runtime And Raw HTML documents low-level Runtime APIs and the raw HTML surface.
• 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 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.