# Astralis UI: full documentation

React 19 component library on semantic design tokens. Server-first: static components are true Server Components that ship zero client JavaScript (enforced by a build gate, labeled per component in system-spec.json's client field). Precompiled, prefix-isolated CSS (value props deliver through CSS custom properties); no build tooling required in the consuming app.

---

<!-- Getting Started / Installation: /docs/installation -->

# Installation

Install the package, import one stylesheet, wrap your app. That's the whole setup.

## Requirements

| | |
| --- | --- |
| React | `^19.1` (with `react-dom`) |
| Build tooling | None: no plugins, no preprocessors, no theme compiler |

Astralis ships **precompiled CSS**: every class any component can emit is
already in the stylesheet, generated and verified at the library's own build
time. Your bundler just serves a `.css` file.

## The short way

The [CLI](/docs/cli) does all three steps below for you. For a new project:

```bash
npx astralis-cli create my-app
```

It runs the official `create-next-app` or `create-vite` prompts, then wires
Astralis into the result: stylesheet imported, provider mounted, ready to
run. For a project you already have:

```bash
npx astralis-cli init
```

Same edits, made in place. Pass `--dry-run` to see them first.

If you'd rather do it by hand, or the CLI doesn't recognise your setup, the
three steps are below. That's all `init` is doing.

## 1. Install the package

```bash
pnpm add astralis-ui
# or: npm install astralis-ui / yarn add astralis-ui
```

## 2. Import the stylesheet (once)

```tsx
import "astralis-ui/styles.css";
```

Do this at your app's entry point (root layout in Next.js, `main.tsx` in
Vite). One import covers every component, both themes and all responsive
variants.

## 3. Wrap your app in the provider

```tsx
import { AstralisProvider } from "astralis-ui";

export function App({ children }) {
  return <AstralisProvider defaultTheme="system">{children}</AstralisProvider>;
}
```

`AstralisProvider` owns theming: it resolves light/dark (including the
`"system"` preference), persists the user's choice to `localStorage`, and,
if you pass a brand color, derives the full shade scale at runtime. Details
on the [Theming](/docs/theming) page.

## Next.js (App Router)

Import the stylesheet and mount the provider in your root layout. The
provider is a client component, but your pages stay server components:
children pass straight through.

```tsx
// app/layout.tsx
import { AstralisProvider } from "astralis-ui";
import "astralis-ui/styles.css";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <AstralisProvider defaultTheme="system">{children}</AstralisProvider>
      </body>
    </html>
  );
}
```

### Avoiding the dark-mode flash

The provider applies the `.astralis-dark` class after hydration, so a user
who prefers dark can see one light-themed frame first. To paint dark from the
very first frame, run this tiny inline script before the body renders (it
reads the same storage key the provider uses):

```tsx
const themeInit = `(function(){try{var t=localStorage.getItem("astralis-ui-theme");var d=t==="dark"||((!t||t==="system")&&window.matchMedia("(prefers-color-scheme: dark)").matches);if(d)document.documentElement.classList.add("astralis-dark");}catch(e){}})();`;

// inside <body>, before your app:
<script dangerouslySetInnerHTML={{ __html: themeInit }} />
```

This documentation site uses exactly this pattern.

## Vite / SPA

```tsx
// src/main.tsx
import { createRoot } from "react-dom/client";
import { AstralisProvider } from "astralis-ui";
import "astralis-ui/styles.css";
import { App } from "./App";

createRoot(document.getElementById("root")!).render(
  <AstralisProvider defaultTheme="system">
    <App />
  </AstralisProvider>,
);
```

## Using Astralis alongside your own styling

Whatever your app already uses (a utility framework, CSS Modules, plain
stylesheets), Astralis coexists with it. Every Astralis class is namespaced
under an `astralis:` prefix internally, so the library's styles can never
collide with your own, and your styling setup never needs to know Astralis
exists. You can also pass your own classes to any component via `className`;
see [Style Props](/docs/style-props) for how conflicts are resolved.

## Tree-shaking

The package publishes one ES module per component with a `sideEffects`
declaration, so bundlers drop everything you don't import. Importing a
Button ships the Button, not the library.

## Tooling

Two things worth setting up once, both covered on their own pages:

- **[The CLI](/docs/cli)**: beyond `create` and `init`, it copies
  [blocks](/blocks) into your project (`npx astralis-cli add dashboard-01`) and
  generates a static theme stylesheet from a brand seed.
- **[AI agents](/docs/ai-agents)**: `npx astralis-cli connect-mcp` points
  your coding agent at a server that serves these docs, so it writes against
  the current component API instead of guessing at one.

Next: the [Quick Start](/docs/quick-start) builds a working form in about
twenty lines.

---

<!-- Getting Started / Quick Start: /docs/quick-start -->

# Quick Start

A working form, theming and responsive layout in about twenty lines. This
assumes Astralis is installed, via either the three
[installation](/docs/installation) steps, or one command:

```bash
npx astralis-cli create my-app   # new project
npx astralis-cli init            # existing one
```

## Your first component

Everything imports from one place:

```tsx
import { Button } from "astralis-ui";

<Button colorScheme="blue">Save changes</Button>;
```

Every interactive component ships styled and accessible out of the box:
hover, focus ring, keyboard behavior and dark mode are already handled.

## A real slice of UI

Here's a small signup card combining a compound component (`Card`), form
plumbing (`Field` + `Input`), layout (`VStack`) and feedback (`Alert`).
Note what's absent: no CSS file, no class soup, no wiring between the label,
help text and input: `Field` connects them (including `aria-describedby`)
automatically.

```tsx
"use client";

import { useState } from "react";
import { Alert, Box, Button, Card, Field, Input, VStack } from "astralis-ui";

export function QuickStartForm() {
  const [sent, setSent] = useState(false);

  return (
    <Box w="full" maxW="sm">
      <Card>
        <Card.Header>
          <Card.Title>Create account</Card.Title>
          <Card.Description>Start your 14-day trial.</Card.Description>
        </Card.Header>
        <Card.Body>
          <form
            onSubmit={(event) => {
              event.preventDefault();
              setSent(true);
            }}
          >
            <VStack gap="4" alignItems="stretch">
              <Field required>
                <Field.Label>Email</Field.Label>
                <Input type="email" name="email" placeholder="you@example.com" />
                <Field.HelpText>We&apos;ll send a confirmation link.</Field.HelpText>
              </Field>
              {sent && (
                <Alert status="success">
                  <Alert.Title>Check your inbox</Alert.Title>
                </Alert>
              )}
              <Button type="submit" fullWidth>
                Sign up
              </Button>
            </VStack>
          </form>
        </Card.Body>
      </Card>
    </Box>
  );
}
```

## Recolor anything

Components take a `colorScheme` prop: eleven hues plus four status aliases
(`error`, `warning`, `success`, `info`), with no extra CSS shipped for any of
them:

```tsx
<Button colorScheme="purple">Purple</Button>
<Badge colorScheme="green">Active</Badge>
<Tabs colorScheme="teal">…</Tabs>
```

And the whole library recolors at once if you hand the provider your brand
color. Shades, hover states and a readable text color are derived at
runtime:

```tsx
<AstralisProvider tokens={{ brandColor: "#8b5cf6" }}>
```

How both of these work is the [Theming](/docs/theming) page.

## Layout with style props

Layout primitives (`Box`, `Flex`, `Stack`, `Grid`, …) expose the design
scale as typed props, and every one of them accepts a responsive map:

```tsx
<Flex
  direction={{ base: "column", md: "row" }}
  gap={{ base: "4", lg: "8" }}
  p="6"
  rounded="xl"
  bg="subtle"
>
  <Box flex="1">Main</Box>
  <Box w={{ base: "full", md: "64" }}>Sidebar</Box>
</Flex>
```

Values autocomplete in your editor, and anything off the scale is a type
error. See [Style Props](/docs/style-props) and
[Responsive Props](/docs/responsive).

## Dark mode

Already working. The provider tracks the system preference by default; to
give users a control, drop in the ready-made
[Theme Toggle](/docs/components/theme-toggle), or read and set it yourself:

```tsx
import { useTheme } from "astralis-ui";

const { resolvedTheme, setTheme } = useTheme();
setTheme(resolvedTheme === "dark" ? "light" : "dark");
```

## Don't build the page from scratch

[Blocks](/blocks) are whole sections (navbars, pricing tables, dashboard
shells) assembled from the same components. The CLI copies one into your
project as source you own:

```bash
npx astralis-cli add pricing-01
```

## Where to go next

- [Theming](/docs/theming): how tokens, dark mode and the brand color work.
- [Style Props](/docs/style-props): the full prop-based styling system.
- [CLI](/docs/cli): scaffolding, blocks, and static theme generation.
- [AI agents](/docs/ai-agents): point your coding agent at these docs so it
  writes against the real API.
- Any component page in the sidebar: each pairs live examples with the
  exact source that renders them.

---

<!-- Foundations / Theming: /docs/theming -->

# Theming

How tokens, dark mode, the brand color and `colorScheme` fit together: one
mental model, four layers.

## The mental model

Astralis components never hard-code a color. They paint with **role tokens**,
CSS variables named for a job, not a color:

```css
/* what a component actually uses */
background: var(--astralis-color-surface-base);
color: var(--astralis-color-label-base);
border-color: var(--astralis-color-stroke-base);
```

Each role points at a **primitive** (a raw shade like `gray-100`), and the
pointer is different in light and dark. Theming, all of it, is re-pointing
those variables at runtime. Nothing re-renders; the browser just repaints.

| Layer | Examples | Job |
| --- | --- | --- |
| Primitives | `gray-100`, `blue-600`, `brand-500` | Raw shades: 11 palettes × 11 steps |
| Semantic roles | `surface-base`, `label-muted`, `stroke-base` | Neutral UI jobs, light/dark aware |
| Palette roles | `blue-solid`, `blue-subtle`, `blue-ring`, … | Same 8-role vocabulary for every hue |
| Accent channel | `accent-solid`, `accent-ring`, … | A virtual palette: whatever `colorScheme` says |

The full palette and role reference lives on the [Colors](/docs/colors)
page; the raw scales on [Design Tokens](/docs/tokens).

## Dark mode

Dark mode is one class, `.astralis-dark` on `<html>`, under which every
semantic role is re-declared with its dark value. The provider manages the
class for you:

```tsx
<AstralisProvider defaultTheme="system">
```

- `defaultTheme` is `"light"`, `"dark"` or `"system"` (follows the OS, live).
- The user's explicit choice persists to `localStorage` and wins on the next visit.
- Read or change it anywhere with the `useTheme` hook, or drop in the
  prebuilt [Theme Toggle](/docs/components/theme-toggle).

```tsx
const { theme, resolvedTheme, setTheme } = useTheme();
// theme: "light" | "dark" | "system"   resolvedTheme: "light" | "dark"
```

Because components only ever reference roles, **dark mode costs you
nothing**: anything you build from Astralis components and semantic tokens
is dark-ready automatically.

## Brand color: one hex, a whole theme

Hand the provider a single color and the library derives everything else at
runtime:

```tsx
<AstralisProvider tokens={{ brandColor: "#8b5cf6" }}>
```

Try it live:

```tsx
"use client";

import { useState } from "react";
import { Badge, Box, Button, HStack, Tag, Text, VStack, generateBrandTokens, useTheme } from "astralis-ui";

const PRESETS = [
  { name: "Default", color: undefined },
  { name: "Violet", color: "#8b5cf6" },
  { name: "Ocean", color: "#0284c7" },
  { name: "Emerald", color: "#059669" },
  { name: "Rose", color: "#e11d48" },
];

export function BrandTheming() {
  const [brand, setBrand] = useState<string | undefined>("#8b5cf6");
  const { resolvedTheme } = useTheme();

  return (
    <VStack gap="5" alignItems="stretch" w="full" maxW="md">
      <HStack gap="2" wrap="wrap">
        {PRESETS.map((preset) => (
          <Button
            key={preset.name}
            size="xs"
            variant={brand === preset.color ? "solid" : "outline"}
            colorScheme="gray"
            onClick={() => setBrand(preset.color)}
          >
            {preset.name}
          </Button>
        ))}
        <input
          type="color"
          aria-label="Pick a custom brand color"
          value={brand ?? "#eab308"}
          onChange={(event) => setBrand(event.target.value)}
        />
      </HStack>

      {/* The same vars the provider injects for tokens={{ brandColor }} */}
      <Box p="5" rounded="xl" bg="subtle" style={generateBrandTokens(brand, resolvedTheme)}>
        <VStack gap="3" alignItems="start">
          <HStack gap="2" wrap="wrap">
            <Button size="sm">Primary</Button>
            <Button size="sm" variant="subtle">Subtle</Button>
            <Button size="sm" variant="outline">Outline</Button>
          </HStack>
          <HStack gap="2">
            <Badge>Badge</Badge>
            <Tag>Tag</Tag>
          </HStack>
          <Text size="sm" color="muted">
            One hex in, a full palette out: shades, hover states and a
            readable text color are all derived at runtime.
          </Text>
        </VStack>
      </Box>
    </VStack>
  );
}
```

What happens under the hood:

1. Your color becomes the `500` step, and ten shades (`50`–`900`) are
   computed in **OKLCH**, a perceptual color space where lightness moves
   without shifting the hue, so a violet stays violet at both ends instead
   of washing toward grey.
2. The brand **role tokens** (`brand-solid`, `brand-subtle`, `brand-ring`, …)
   are re-derived from those shades, with different recipes for light and
   dark.
3. Text-on-brand (`brand-contrast`) is chosen automatically: black or white,
   whichever is readable on your color.

The demo above uses the same exported function the provider uses,
`generateBrandTokens(color, resolvedTheme)`, so you can scope a brand
override to any subtree by spreading its result into a `style` prop.

## colorScheme: the accent channel

Every themeable component takes a `colorScheme` prop:

```tsx
<Button colorScheme="teal">Confirm</Button>
```

Here's the trick: components are **not** styled per hue. They paint with a
single virtual palette: `accent-solid`, `accent-subtle`, `accent-ring`, and
so on. By default the accent channel points at your brand. `colorScheme`
simply adds one scope class (like `astralis-accent-teal`) that re-points all
eight accent variables at teal's role tokens for that subtree.

```tsx
import { Button, Text, VStack, HStack } from "astralis-ui";

const variants = ["solid", "subtle", "surface", "outline", "text", "link"] as const;
const schemes = [
  "brand", "gray", "red", "orange", "yellow", "green",
  "teal", "blue", "cyan", "purple", "pink",
] as const;

export function ButtonColorSchemes() {
  return (
    <VStack gap="6" alignItems="stretch">
      {variants.map((variant) => (
        <VStack key={variant} gap="2" alignItems="stretch">
          <Text as="span" size="xs" weight="medium" color="muted">
            {variant}
          </Text>
          <HStack gap="2" wrap="wrap">
            {schemes.map((scheme) => (
              <Button key={scheme} size="xs" variant={variant} colorScheme={scheme}>
                {scheme}
              </Button>
            ))}
          </HStack>
        </VStack>
      ))}
    </VStack>
  );
}
```

Two consequences worth knowing:

- **Zero cost per hue.** Each scheme ships as a few lines of variable
  re-binding, not another copy of every component's CSS.
- **Theme-aware for free.** Each scheme points at role tokens that already
  flip for dark mode, so `colorScheme="purple"` looks right in both themes
  without any extra work.

Available schemes: eleven hues (`brand`, `gray`, `red`, `orange`, `yellow`,
`green`, `teal`, `blue`, `cyan`, `purple`, `pink`) plus four status aliases
(`error`, `warning`, `success`, `info`) that follow your theme's status
colors.

## Overriding tokens yourself

Every token is a documented CSS variable, so your own stylesheet can retune
the system globally:

```css
:root {
  --astralis-border-radius-lg: 0.75rem;            /* chunkier corners */
  --astralis-color-surface-base: #fafaf9;          /* warmer page background */
}

.astralis-dark {
  --astralis-color-surface-base: #0c0a09;
}
```

One caveat for **subtree** overrides: CSS variables resolve where they're
declared, so overriding a *primitive* (like `--astralis-color-brand-500`) on
a nested element won't reach components: they read *role* tokens that were
already resolved higher up. Override the role tokens themselves, or use
`generateBrandTokens` as shown above, which handles exactly this.

## Build a theme by eye

The [Theme builder](/theme-builder) tunes the brand, neutral and status
colors, radius, spacing, type scale, fonts and motion against a live canvas of
real components. It hands you a stylesheet to import after
`astralis-ui/styles.css`, or the same seed as `<AstralisProvider tokens={…}>`
props, plus a link that reopens the theme exactly as you left it.
[`npx astralis-cli theme`](/docs/cli) writes the same stylesheet from the
command line.

---

<!-- Foundations / Colors: /docs/colors -->

# Colors

The palettes, the role vocabulary every hue shares, and where each is meant
to be used.

## The palettes

Ten hues plus `brand`, each with eleven steps from `50` (near white) to
`950` (near black). These are the **primitives**, the only real color
values in the system; everything else is a pointer to one of these.

```tsx
import { Box, Grid, HStack, Text, VStack } from "astralis-ui";

const HUES = [
  "gray", "red", "orange", "yellow", "green",
  "teal", "blue", "cyan", "purple", "pink",
] as const;

const STEPS = ["50", "100", "200", "300", "400", "500", "600", "700", "800", "900", "950"] as const;

export function PaletteGrid() {
  return (
    <VStack gap="2" alignItems="stretch" w="full">
      {HUES.map((hue) => (
        <HStack key={hue} gap="3" alignItems="center">
          <Box w="16">
            <Text as="span" size="xs" weight="medium" color="muted">
              {hue}
            </Text>
          </Box>
          <Grid columns="11" gap="1" w="full">
            {STEPS.map((step) => (
              <Box
                key={step}
                h="8"
                rounded="md"
                title={`${hue}-${step}`}
                style={{ background: `var(--astralis-color-${hue}-${step})` }}
              />
            ))}
          </Grid>
        </HStack>
      ))}
    </VStack>
  );
}
```

`brand` is special: by default it aliases the gold palette, but it's the one
palette that can be **replaced at runtime**: pass
`tokens={{ brandColor }}` to the provider and all ten brand steps are
recomputed from your color (see [Theming](/docs/theming)).

## Roles: how components actually pick colors

Components rarely touch a raw step like `blue-600`. Every palette exposes
the same seven **roles**, and those are what variant styles are written
against:

| Role | Job | Example use |
| --- | --- | --- |
| `solid` | The strong fill | Solid button background |
| `contrast` | Text on top of `solid` | Solid button label |
| `label` | Tinted text on neutral backgrounds | Link text, subtle-button label |
| `subtle` | Faint tinted background | Badge background, hover wash |
| `muted` | A step stronger than subtle | Subtle-button hover |
| `stroke` | Tinted border | Outline button border |
| `ring` | Focus ring | Any focused control |

Two things make this vocabulary powerful:

- **Light and dark values differ per role.** In light mode `blue-subtle`
  points at `blue-100`; in dark mode it re-points at a deep step. Write
  against roles and dark mode is automatic.
- **Every hue answers the same questions.** Because all palettes share the
  vocabulary, one set of component styles can be recolored to any hue.
  That's what makes `colorScheme` possible.

## The accent channel

`accent-*` is a *virtual* palette. It has the same seven roles but
no colors of its own: it forwards to whichever real palette the nearest
`colorScheme` chose (brand by default). Components are written once against
`accent-*` and recolor through it. The full mechanism is explained on the
[Theming](/docs/theming) page.

## Neutral semantic tokens

For everyday UI structure (page backgrounds, text, borders), use the
neutral roles instead of any palette:

| Family | Tokens | Job |
| --- | --- | --- |
| Surface | `base` · `subtle` · `muted` · `raised` · `inverted` | See the ladder below |
| Label | `base` · `muted` · `subtle` · `inverted` | See the label ladder below |
| Stroke | `base` · `subtle` · `muted` · `inverted` | See the stroke ladder below |

### The surface ladder

Three neutrals, one rule each. You should never have to guess which to reach for.

| Token | When |
| --- | --- |
| `base` | The page, and any control at rest: an input, a checkbox, an active tab |
| `subtle` | Something sitting on the page but not floating: a card, a table header, an inactive item |
| `muted` | Not interactive: disabled controls (with reduced opacity), and inert parts like a progress track or slider rail |

**Hover is one step up the ladder from wherever the element rests.** A control
resting on `base` hovers to `subtle`; something already at `subtle` hovers to
`muted`. There is no separate hover token to memorise, and no component gets to
pick its own answer.

Two things the ladder does not cover. **`raised` is not a fourth neutral**: it
is identical to `base` in light mode and one step lighter in dark, where a
shadow cannot read. Floating layers only: menus, toasts, popovers, modals,
drawers, listboxes. Cards never use it. And **`inverted`** is for the few things
that must read against any surface at all: tooltips, the slider value bubble.

### The label ladder

Three tiers of text, ordered by contrast against the page.

| Token | When |
| --- | --- |
| `base` | Body copy, headings, anything you actually read |
| `muted` | Secondary text: descriptions, captions, help text |
| `subtle` | The faintest tier that is still content: placeholders, empty states, listbox group headers, calendar weekday rows |

**Every tier clears WCAG AA (4.5:1) on the page it sits on**, in both modes.
`subtle` is deliberately the floor rather than "as light as it can go": it
paints placeholder text, and a placeholder nobody can read is a bug, not a
style. If you want something genuinely decorative and unreadable, reach for
`opacity`, not a lighter label token.

One asymmetry worth knowing: dark is spaced one ramp step wider than light.
The neutral ramp has nothing between gray-400 and gray-500 on a near-black
page, so holding `muted` where light has it would have pushed `subtle` under
the AA line.

`inverted` is the fourth: text on an inverted surface, used by Tooltip and the
slider value bubble.

### The stroke ladder

Strokes work differently, and the difference is deliberate. A default
*background* is the absence of tint, so surfaces can only ever step up from
`base`. A default *border* has to be visible, so `stroke-base` sits in the
middle, with one step either side of it.

| Token | When |
| --- | --- |
| `subtle` | A dividing line inside something that is already bordered: a card header rule, a drawer footer |
| `base` | Every default border, and every control outline: cards, tables, inputs, checkboxes, panels, Separator |
| `muted` | Stronger than the default: the hover border on an outline input |

So the direction reads `subtle < base < muted`, ordered by contrast against the
page in both light and dark. Hovering an outline control still means "one step
up", exactly as it does for surfaces. It just starts from `base` rather than
ending there.

### Status colours are palettes, not neutrals

`error`, `warning`, `success` and `info` are **not** part of the three families
above. Those families are ladders measuring emphasis; a status colour carries
meaning, which is a different axis entirely. So status lives where every other
colour lives: as a palette with the same seven roles:

```jsx
<Text color="error" />       {/* error-label: the text role    */}
<Box bg="success" />         {/* success-solid: the fill role   */}
<Box borderColor="warning" />{/* warning-stroke: the line role  */}
```

These are the same tokens `colorScheme="error"` rebinds onto the accent
channel, so Alert, Toast and form validation all resolve to one set of values
rather than two that drift apart.

### Naming a hue picks the role that fits the property

Every palette works this way, not just the status ones. The bare hue resolves
to whichever role the CSS property actually wants (`solid` for a fill, `label`
for text, `stroke` for a line), so the common case is one word:

| | Bare form | Also available |
| --- | --- | --- |
| `bg` | `"blue"` → `blue-solid` | `blue-subtle` · `blue-muted` · `blue-50`–`blue-950` |
| `color` | `"blue"` → `blue-label` | `blue-solid` · `blue-contrast` · `blue-50`–`blue-950` |
| `borderColor` | `"blue"` → `blue-stroke` | `blue-50`–`blue-950` |

Two things worth knowing. **`gray` has no bare form**: its `solid` is
near-black in light and white in dark, which is never what `bg="gray"` would
suggest, and the neutral ladder already covers those cases. And the numbered
shades are the escape hatch, not the default: they are the only colour tokens
that do **not** re-point in dark mode, so `bg="blue-500"` freezes one mode's
decision into both.

## Using colors in your own code

Style props accept all three tiers:

```tsx
<Box bg="subtle" />            {/* neutral semantic role */}
<Box bg="blue-subtle" />       {/* palette role */}
<Box bg="blue-100" />          {/* raw primitive, last resort */}
<Text color="muted" />         {/* neutral label role */}
```

Prefer the highest tier that says what you mean: semantic roles adapt to
both themes on their own, palette roles adapt within their hue, and raw
steps don't adapt at all. In custom CSS, the same values are available as
variables: `var(--astralis-color-blue-subtle)`, exactly like the swatch
grid demo above does.

---

<!-- Foundations / Responsive Props: /docs/responsive -->

# Responsive Props

Every style prop accepts a breakpoint map: mobile-first, precompiled, zero
runtime cost.

## The syntax

Anywhere a style prop takes a token, it also takes an object keyed by
breakpoint:

```tsx
<Box p="4" />                                {/* scalar */}
<Box p={{ base: "2", md: "4", xl: "8" }} />  {/* responsive map */}
```

```tsx
import { Box, Text } from "astralis-ui";

export function BoxResponsive() {
  return (
    <Box
      bg="green-subtle"
      rounded={{ base: "md", md: "2xl" }}
      p={{ base: "4", md: "8", lg: "12" }}
    >
      <Text size="sm" color="muted">
        Resize the window: padding and radius step up at md and lg.
      </Text>
    </Box>
  );
}
```

## Breakpoints

| Key | Min-width | Typical device |
| --- | --- | --- |
| `base` | None | Everything (mobile first) |
| `sm` | 40rem / 640px | Large phones |
| `md` | 48rem / 768px | Tablets |
| `lg` | 64rem / 1024px | Laptops |
| `xl` | 80rem / 1280px | Desktops |

**Mobile-first means each key applies from that width up.** `base` is your
mobile value; `md` overrides it from 768px onward and keeps applying at `lg`
and `xl` unless you override again. You only write the breakpoints where
something *changes*:

```tsx
{/* column on phones, row from tablets up, nothing else needed */}
<Flex direction={{ base: "column", md: "row" }} />
```

Omitting `base` is fine too: the prop's normal default fills in below your
first breakpoint.

## What's responsive

All layout style props (spacing, sizing, colors, radius, display,
position: everything on [Style Props](/docs/style-props)) plus the
layout-shaping variant props of the primitives:

```tsx
<Grid columns={{ base: "1", sm: "2", lg: "4" }} gap={{ base: "3", lg: "6" }}>
<Stack direction={{ base: "vertical", md: "horizontal" }}>
<Text size={{ base: "sm", md: "md" }}>
<Separator orientation={{ base: "horizontal", md: "vertical" }} />
```

The common recipes:

```tsx
{/* hide on mobile, show from md */}
<Box display={{ base: "hidden", md: "block" }} />

{/* full-width mobile, fixed sidebar on desktop */}
<Box w={{ base: "full", md: "64" }} />

{/* tighter type and padding on small screens */}
<Heading size={{ base: "lg", md: "2xl" }} />
```

## Container queries

Every responsive key has a container-query twin, written with an `@` prefix:
`@sm`, `@md`, `@lg`, `@xl`. Same names, same widths, but measured against the
**nearest ancestor marked `container`** instead of the browser window.

```tsx
<Box container>
  <Card size={{ base: "sm", "@md": "lg" }} />
</Box>
```

The card is `lg` when *the Box* is at least 48rem wide. Drop the same card
into a narrow sidebar and it renders `sm`, on the same screen, with no extra
code. That is the promise viewport breakpoints can't keep: a component styled
by the space it actually has, wherever it lands.

Everything responsive works with `@` keys (keyword props, value props,
arbitrary values), and viewport and container keys mix freely in one map:

```tsx
<Flex container direction="column" gap="2">
  {/* hidden on phones (viewport), row layout once the panel is wide (container) */}
  <Flex display={{ base: "hidden", sm: "flex" }} direction={{ base: "column", "@md": "row" }} />
</Flex>
```

Two rules to remember:

- **Something must be the container.** `@` keys measure the nearest ancestor
  with the `container` prop (any layout primitive takes it). With no container
  ancestor, `@` values simply never fire.
- `container` uses `container-type: inline-size`. The element sizes from its
  context as usual, but note it no longer contributes its intrinsic width to
  `max-content` ancestors.

## How it works (and why it's fast)

Nothing is computed in the browser. A value-bearing prop resolves to one
**fixed class per breakpoint** plus a CSS custom property carrying the value:

```html
<!-- p={{ base: "2", md: "4" }} renders as -->
<div
  class="astralis-p astralis-p-md"
  style="--astralis-p: var(--astralis-spacing-2); --astralis-p-md: var(--astralis-spacing-4)"
/>
```

The classes already exist in the stylesheet you imported: `.astralis-p`
reads `var(--astralis-p)`, and `.astralis-p-md` does the same inside a
`min-width: 48rem` media query. The class says *where* the value lands; the
variable says *what* it is. Because the value travels as a token variable
rather than being baked into a class name, the stylesheet stays small no
matter how many values exist, and theming keeps cascading through the same
tokens.

Keyword props (`display`, `position`, alignment, ...) are small closed sets
and resolve to pre-generated classes per breakpoint instead
(`astralis:hidden astralis:md:flex`). A build gate verifies every class
(fixed rules and keyword variants alike) landed in the compiled CSS.
From there it's ordinary media queries, handled natively by the browser.

Two practical consequences:

- **No resize listeners, no JS at breakpoints, no flash**: server-rendered
  HTML is responsive before hydration (custom properties in `style` are
  plain HTML attributes).
- **Values are unbounded.** Because only the class must exist at build time,
  a breakpoint entry can be a scale token *or* any CSS value:
  `p={{ base: "5vw", md: "4" }}` mixes both. See
  [Arbitrary values](/docs/style-props#arbitrary-values).

---

<!-- Foundations / Style Props: /docs/style-props -->

# Style Props

The design scale as typed props: spacing, color, radius and more on every
layout primitive.

## The idea

Instead of writing CSS (or utility class strings) for everyday styling, you
pass tokens as props:

```tsx
<Box p="6" bg="subtle" rounded="xl" shadow="sm" maxW="md" />
```

Three things distinguish this from a `style` attribute:

- **Values come from the design scale first**: `p="6"` is the spacing token
  `6`, `bg="subtle"` is a semantic color role. Your editor autocompletes the
  tokens, so consistency is the default, not a discipline.
- **The scale is a vocabulary, not a ceiling.** When no token fits, pass the
  CSS value itself (`p="37px"`, `w="calc(100vw - 200px)"`) and it rides the
  same delivery. See [Arbitrary values](#arbitrary-values).
- **Every prop is responsive.** Any value can be a breakpoint map. See
  [Responsive Props](/docs/responsive).

```tsx
import { Box, HStack } from "astralis-ui";

export function BoxStyleProps() {
  return (
    <HStack gap="4" wrap="wrap" justifyContent="center">
      <Box bg="brand-subtle" size="16" rounded="md" />
      <Box bg="brand-muted" size="16" rounded="lg" />
      <Box bg="brand" size="16" rounded="xl" shadow="md" />
      <Box bg="transparent" size="16" rounded="xl" border="thick" borderColor="brand" />
      <Box bg="inverted" size="16" rounded="full" />
    </HStack>
  );
}
```

## Where style props live

[Box](/docs/components/box) is the host: a polymorphic `div` exposing the
full set. Every other layout primitive (**Flex, Stack, Grid, Center,
Container, AspectRatio, Float**) extends Box, so all of them accept all of
these props on top of their own. Typography components (**Text, Heading**)
carry the relevant subset.

## Paint and placement

Everything else follows one rule:

> **A component owns how it looks. Its parent owns where it sits and how big it is.**

**Paint** is how something looks on its own: `bg`, `color`, `borderColor`,
`rounded`, `shadow`, and the padding *inside* it. Higher-level components
(Button, Card, Select, Alert…) do **not** take these. Their appearance is the
design system's job, adjusted through `variant`, `size` and `colorScheme`.
Repainting one from the outside would defeat the variants it ships with.

**Placement** is how big something is and where it sits *inside its parent*:
width and height, the flex-item props, and margin. A component cannot know
these: only the composition can. So every component that can be a child
accepts them.

The test, if you're unsure which one you're reaching for:

> If I moved this component to a different page, would the prop still be right?

`variant="outline"` still is. That's paint. `w="full"` depends entirely on
what's around it. That's placement.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `w · minW · maxW` | "0" – "96", "full", "screen", fractions, "xs" – "7xl" | None | How much horizontal room the component takes in its parent. |
| `h · minH · maxH` | "0" – "96", "full", "screen", fractions | None | The same vertically. |
| `flex · basis · grow · shrink` | "1", "auto", "initial", "none" · spacing scale | None | How the component behaves as a flex child: whether it fills, holds, or shrinks. |
| `order · alignSelf` | "first" \| "last" \| "none" · "start" \| "center" \| "end" \| "stretch" \| "baseline" | None | Where it sits among its siblings, overriding the parent's alignment for one child. |
| `m · mx · my · mt/mb/ml/mr` | "0" – "96" (spacing scale) \| "auto" | None | Space between the component and its siblings. auto is the layout tool: ml="auto" pushes a flex item to the far edge, mx="auto" centres a fixed-width block. |

Padding is paint but margin is placement, which looks inconsistent until you
say it out loud: padding is space *inside* a component, which its recipe owns;
margin is space *between* it and its siblings, which only the parent can
decide.

### One name, two meanings

`size` is the exception worth knowing. On Box it sets width **and** height. On
a component with its own scale (Card, Button, Badge), it selects that scale.
They are different props that happen to share a name, so a component with a
recipe `size` does not inherit Box's.

Container has no scale of its own, so `size` there used to fall through to
Box's and silently constrain the height. It is now a type error; use `maxW`.

```tsx
<Container size="lg">   {/* error: Container has no size */}
<Container maxW="4xl">  {/* what you meant */}
```

## The prop families

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `p · px · py · pt/pb/pl/pr` | "0" – "96" (spacing scale) | None | Padding: all sides, per axis, or per edge. |
| `m · mx · my · mt/mb/ml/mr` | "0" – "96" (spacing scale) \| "auto" | None | Margin: all sides, per axis, or per edge. auto pushes a flex item to the far edge or centres a fixed-width block. |
| `w · h · size · minW/maxW · minH/maxH` | spacing scale \| "xs"–"8xl" \| fractions \| "auto" \| "full" \| "fit" \| "prose" … | None | Sizing. size sets width and height at once. |
| `bg` | "base" \| "subtle" \| "muted" \| "raised" \| "inverted" \| "{hue}" (solid) \| "{hue}-subtle" \| "{hue}-muted" \| "{hue}-50"–"{hue}-950" | None | Background from semantic roles, palette roles, or raw shades. Transparent by default. base is the page, subtle the thing sitting on it, muted a filled control; raised is for floating layers only. |
| `color` | "base" \| "muted" \| "subtle" \| "inverted" \| "{hue}" (label) \| "{hue}-solid" \| "{hue}-contrast" | None | Text color token; children inherit it. |
| `border (+ borderT/R/B/L) · borderStyle · borderColor` | "normal"–"thickest" · CSS styles · "base" \| "subtle" \| "muted" \| "{hue}" (stroke) | None | Border width, style and color tokens. Per-side widths mirror rounded: borderB is a header rule, borderT a footer one. |
| `rounded (+ roundedT/R/B/L, roundedTl/Tr/Br/Bl)` | "none" \| "2xs"–"4xl" \| "full" | None | Corner radius: all corners, per side, or per corner. |
| `display` | "block" \| "flex" \| "grid" \| "hidden" \| … | None | CSS display. |
| `position · inset · top/right/bottom/left · zIndex` | position tokens + offset scale | None | Positioning. |
| `shadow` | "none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "inner" | None | Box shadow token. |
| `opacity · overflow(X/Y) · cursor · pointerEvents · aspectRatio` | token maps | None | Misc utilities, all typed. |
| `basis · flex · grow · shrink · order · alignSelf` | sizing scale · "1" \| "auto" \| "initial" \| "none" · boolean \| "0" \| "1" · "1"–"12" · "auto" \| "start" \| "center" \| "end" \| "stretch" \| "baseline" | None | How the element behaves as a child of a flex or grid parent. On Box, so any primitive can size itself without a Flex.Item wrapper. |
| `container` | boolean | `false` | Makes this element the query container that descendants' @sm–@xl responsive keys measure against, instead of the viewport. |
| `as` | ElementType | `"div"` | Element or component to render; HTML props follow it type-safely. |

## Arbitrary values

Every **value** prop (spacing, sizing, gap, radius, offsets, colors, shadow,
opacity: everything that isn't a closed keyword set) accepts any CSS value
alongside its tokens. A string that isn't a token is delivered through the
same custom property the token would have used:

```tsx
<Box p="37px" />                          {/* raw length */}
<Box w="calc(100vw - 200px)" />           {/* calc, clamp, min, max */}
<Box bg="#0ea5e9" borderColor="oklch(0.7 0.1 200)" />
<Box p={{ base: "5vw", md: "4" }} />      {/* mix raw and tokens per breakpoint */}
<Box hover={{ bg: "rebeccapurple" }} />   {/* states take them too */}
```

Two things to know:

- **Tokens win.** If the string is a token, you get the token's variable:
  `p="4"` is always `var(--astralis-spacing-4)`, never the literal `4`.
- **Units are on you.** A bare number like `p="37"` isn't valid CSS for a
  length, so Astralis warns in development and passes it through unchanged.
  Write `p="37px"` (or use a token).

**Keyword props stay closed.** `display`, alignment, overflow and friends are
finite CSS vocabularies backed by build-time classes. An unknown value there
resolves to nothing, exactly as before.

## Escape hatches

Arbitrary values cover most "outside the scale" needs. For everything else,
drop down a level, in this order:

**1. `style`**: for dynamic values and properties that aren't props. Value
props deliver through CSS custom properties, and your `style` always wins
over them:

```tsx
<Box style={{ transform: `translateX(${offset}px)` }} />
<Box p="4" style={{ paddingTop: "13px" }} />  {/* one-off beats the prop */}
```

Reach for the token variables inside `style` to stay on the scale:

```tsx
<Box style={{ gap: "var(--astralis-spacing-1)" }} />
```

**2. `className`**: every component forwards it. Astralis's internal
classes are prefixed (`astralis:*`), so your own utility classes, whatever
generates them, can't collide. Note that Astralis ships utility classes
only for **keyword** props (`display`, alignment, overflow, ...); since the
var-channel migration there is no per-value class like `astralis:p-4` to
reach for. Value styling belongs to the props or to `style`.

```tsx
<Box p="4" className="my-fancy-gradient" />
```

**3. Plain CSS**: Astralis renders ordinary DOM elements, and every design
token is a documented CSS variable, so your stylesheets can target
components and stay on the scale:

```css
.sidebar {
  padding: var(--astralis-spacing-6);
  background: var(--astralis-color-surface-subtle);
}
```

## Why tokens?

Astralis ships **precompiled CSS**. Value props resolve to a fixed rule per
prop that reads a custom property (see [Responsive Props](/docs/responsive)
for the mechanics), and keyword props resolve to pre-generated classes. A
build-time coverage gate verifies every rule, class, and token value has CSS
behind it. Because values ride custom properties rather than classes, they
don't need to exist at build time (which is what makes arbitrary values
free), and everything stays zero-runtime: no style engine executes in the
browser.

---

<!-- Foundations / Design Tokens: /docs/tokens -->

# Design Tokens

The complete reference of every scale in the system. Each token is a CSS
variable (prefixed `--astralis-`) *and* a typed prop value. The same name
works in both worlds:

```tsx
<Box p="6" />                             {/* as a prop */}
```

```css
padding: var(--astralis-spacing-6);       /* as a variable */
```

Color tokens have their own page. See [Colors](/docs/colors).

## Spacing

Used by padding, margin and gap props. A 4px-based scale: the token number
× 0.25rem, with half steps at the small end.

| Tokens | Values |
| --- | --- |
| `0.5` – `4.5` (half steps) | 0.125rem – 1.125rem (2px – 18px) |
| `1` – `12` (every integer) | 0.25rem – 3rem (4px – 48px) |
| `14` `16` `20` `24` `28` `32` `36` `40` `44` `48` `52` `56` `60` `64` `72` `80` `96` | 3.5rem – 24rem (56px – 384px) |

Variables: `--astralis-spacing-{token}`.

## Sizing

Used by `w`, `h`, `size`, `minW`/`maxW`, `minH`/`maxH`. Four vocabularies,
all valid anywhere a size is accepted:

| Vocabulary | Tokens | Values |
| --- | --- | --- |
| Numeric | same numbers as spacing | `4` = 1rem … `96` = 24rem |
| T-shirt | `3xs` `2xs` `xs` `sm` `md` `lg` `xl` `2xl` – `8xl` | 14rem, 16rem, 20rem, 24rem, 28rem, 32rem, 36rem, 42rem – 90rem |
| Fractions | `1/2` `1/3` `2/3` `1/4` `3/4` fifths, sixths, twelfths | percentages |
| Keywords | `full` `fit` `min` `max` `auto` | `100%`, `fit-content`, `min-content`, `max-content`, `auto` |

Plus viewport units: `vw` `vh` and the small/large/dynamic variants
(`dvh` `svh` `lvh` `dvw` `svw` `lvw`). Variables: `--astralis-size-{token}`.

## Typography

| Scale | Tokens |
| --- | --- |
| Font size | `3xs` (0.5rem) `2xs` `xs` `sm` `md` (1rem) `lg` `xl` `2xl` `3xl` `4xl` `5xl` `6xl` `7xl` `8xl` `9xl` (8rem) |
| Weight | `thin` `extralight` `light` `normal` `medium` `semibold` `bold` `extrabold` `black` |
| Letter spacing | `tighter` `tight` `normal` `wide` `wider` `widest` |
| Line height | `none` (1) `tight` (1.25) `snug` (1.375) `normal` (1.5) `relaxed` (1.625) `loose` (2) |

Font families are theme hooks: set `--astralis-font-heading` and
`--astralis-font-body` in your CSS to give the whole library your
typefaces. The [Text](/docs/components/text) and
[Heading](/docs/components/heading) components pick them up automatically.

## Radius

Used by `rounded` and its per-side/per-corner variants.

| Token | `none` | `2xs` | `xs` | `sm` | `md` | `lg` | `xl` | `2xl` | `3xl` | `4xl` | `full` |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Value | 0 | 1px | 2px | 4px | 6px | 8px | 12px | 16px | 24px | 32px | 9999px |

Variables: `--astralis-border-radius-{token}`.

## Borders

| Scale | Tokens |
| --- | --- |
| Width (`border`) | `normal` (1px) `moderate` (2px) `thick` (4px) `thicker` (8px) `thickest` (12px) |
| Style (`borderStyle`) | `solid` `dashed` `dotted` `double` `hidden` `none` |

Border *colors* come from the stroke tokens on the [Colors](/docs/colors)
page.

## Shadows

Used by the `shadow` prop: `none` `xs` `sm` `md` `lg` `xl` `2xl` `inner`.
Shadows are theme-aware: dark mode automatically swaps in deeper values so
elevation stays legible on dark surfaces. Variables:
`--astralis-shadow-{token}`.

## Motion

Durations used by every component transition:

| Token | `fastest` | `faster` | `fast` | `moderate` | `slow` | `slower` | `slowest` |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Value | 50ms | 100ms | 150ms | 200ms | 300ms | 400ms | 500ms |

Variables: `--astralis-duration-{token}`. Components honor
`prefers-reduced-motion`: continuous animations (Marquee, Carousel
autoplay) pause for users who ask for less motion.

## Breakpoints

The responsive-prop keys: `sm` 640px · `md` 768px · `lg` 1024px ·
`xl` 1280px. Details on [Responsive Props](/docs/responsive).

## Overriding tokens

Every token above is a plain CSS variable, so retuning the system globally
is one declaration (no build step, no config file):

```css
:root {
  --astralis-border-radius-lg: 0.75rem;   /* every "lg" corner in the app */
  --astralis-font-heading: "Fraunces", serif;
  --astralis-duration-moderate: 150ms;    /* snappier default transitions */
}
```

For color-token overrides (which have a light/dark subtlety), see
[Theming](/docs/theming#overriding-tokens-yourself).

---

<!-- Tooling / CLI: /docs/cli -->

# CLI

Scaffold a project, add blocks, generate a static brand theme, validate code
against the design system, and connect AI agents with the `astralis`
command-line tool.

## Running it

Every command runs through `npx`, so there's nothing to install:

```bash
npx astralis-cli <command> [options]
```

Or install it once and call `astralis` directly:

```bash
pnpm add -g astralis-cli
astralis <command>
```

It needs Node `^22.18` or `>=24.11`. Run `astralis --help` for the command
list, or `astralis <command> --help` for a command's options. The option
tables on this page are generated from the same source as `--help`.

## `create`: start a new project

Scaffolds a fresh app with the official `create-next-app` / `create-vite`
prompts, then wires Astralis into it.

```bash
npx astralis-cli create my-app
```

It asks which framework you want (Next.js, or React via Vite), then hands
off to that scaffolder's own prompts, so you get the official setup rather
than a copy of it that drifts. When it finishes, the stylesheet is imported,
the provider is mounted, and a welcome page you can delete replaces the
scaffolder's demo. Run `npm run dev` (or your package manager's equivalent)
inside the new folder to start it.

| Option | |
| --- | --- |
| `--framework <next\|vite>` | Skip the framework prompt. |
| `--no-starter` | Keep the scaffolder's demo page instead of the Astralis welcome screen. |
| `--no-devtools` | Leave out the Astralis DevTools overlay, which new projects get in development. |

With `--yes` it asks nothing: pass `--framework`, and it tells the scaffolder
to take its defaults too.

## `init`: add Astralis to an existing project

Wires `astralis-ui` into a project you already have (Next.js or Vite): installs
the package, adds the `astralis-ui/styles.css` import, and mounts
`<AstralisProvider>` at your app's entry point: the same [manual
steps](/docs/installation), done for you.

```bash
npx astralis-cli init
```

| Option | |
| --- | --- |
| `--dry-run` | Show the changes without writing anything. |
| `--ci` | Also check every pull request: pin astralis-cli, add a validate script and write a GitHub Actions workflow. |
| `--force` | With --ci, replace an existing astralis-validate.yml. |
| `--devtools` | Also add the Astralis DevTools overlay (development only): install astralis-devtools and wire it into the root layout or vite.config. |

It reads your entry file rather than pattern-matching it, so an import that is
already there (however it's quoted or wrapped) isn't added twice, and it never
writes a file that no longer parses. If your entry file is a shape it can't
edit safely, it prints the manual steps instead. Running it twice is safe.

With `--ci` it also sets up a check on every pull request: it pins
`astralis-cli` as a devDependency, adds a `validate` script and writes a GitHub
Actions workflow. [Validate in CI](/docs/validate-in-ci) covers that, and a
pre-commit hook.

## `add`: copy a block into your project

Writes a [block](/blocks)'s source into your codebase. Blocks aren't imported
from a package: the file lands in your repo and you own it, so editing it is
editing your own code.

```bash
npx astralis-cli add dashboard-01
```

Name as many as you like. To see what's available without opening the
browser:

```bash
npx astralis-cli add --list
```

| Option | |
| --- | --- |
| `--list` | Print every available block, by category, and exit. |
| `--dir <path>` | Where to write. Default: src/components/blocks, or components/blocks without a src/. |
| `--overwrite` | Replace existing files without asking. |
| `--dry-run` | Show what would be written; write nothing. |
| `--registry <url>` | Read blocks from a different registry host. |

This command is deliberately small compared with the equivalent in other
libraries, and the reason is architectural: a block imports only
`astralis-ui`, React, or a sibling file (the registry builder rejects
anything else), and the stylesheet is precompiled. So there are no import
paths to rewrite, no dependency graph between blocks, and no Tailwind config
to merge. It fetches text and writes files, and refuses any file path that
would land outside the target folder.

## `theme`: generate a static theme

Produces a plain CSS stylesheet from a brand seed, for when you want your theme
baked into a file rather than derived at runtime by the provider. See
[Theming](/docs/theming) for how the two approaches compare, or build a seed
visually in the [theme builder](/theme-builder).

```bash
npx astralis-cli theme "#6d3bf5"
```

| Option | |
| --- | --- |
| `--brand <hex>` | Brand hue, e.g. "#8b5cf6". A bare hex argument means the same. |
| `--gray <hex>` | Neutral hue: every surface, label and border. |
| `--error <hex>` | Seeds the error palette. Default: red. |
| `--warning <hex>` | Seeds the warning palette. Default: orange. |
| `--success <hex>` | Seeds the success palette. Default: green. |
| `--info <hex>` | Seeds the info palette. Default: blue. |
| `--font-heading <stack>` | Heading font stack. |
| `--font-body <stack>` | Body font stack. |
| `--font-mono <stack>` | Monospace font stack. |
| `--radius <n>` | Border-radius multiplier. Default: 1. |
| `--spacing <n>` | Spacing multiplier: the density dial. Default: 1. |
| `--font-scale <n>` | Font-size multiplier. Default: 1. |
| `--motion <n>` | Duration multiplier; 0 turns transitions off. Default: 1. |
| `--out <file>` | Where to write the stylesheet. Default: src/astralis-theme.css, or astralis-theme.css without a src/. |
| `--force` | Overwrite an existing file. |
| `--no-import` | Write the file but leave the entry file alone. |
| `--strict-contrast` | Exit 1, writing nothing, if any promised pairing fails WCAG AA. |

It uses your project's own `astralis-ui` for the colour maths, so the file
matches the version it's loaded next to, and imports the file into your entry
point after the library stylesheet. Before writing, it checks every text and
fill pairing the theme promises against WCAG AA in light and dark mode;
failures are warnings unless you pass `--strict-contrast`.

## `validate`: check code against the design system

Checks your TSX and JSX against the machine-readable spec of the `astralis-ui`
version you have installed. It catches what type-checks and still fails:
components and compound parts that don't exist, prop values outside their
token sets, `astralis:*` classes missing from the compiled CSS (they render as
nothing), undeclared token variables, illegal breakpoint and state keys,
compound parts outside their root, Tabs triggers with no panel, and
accessibility mistakes such as misspelled `aria-*` attributes, invalid roles,
and images with no `alt`.

```bash
npx astralis-cli validate              # the current directory
npx astralis-cli validate src/app      # a folder, or single files
npx astralis-cli validate --json       # one JSON report, for CI and tools
```

| Option | |
| --- | --- |
| `--format <text\|json\|github>` | How to report: text for people, json for tools, github for inline pull-request annotations. Default: github inside GitHub Actions, text elsewhere. |
| `--json` | Same as --format json. |
| `--spec <path>` | Validate against this system-spec.json. Default: the installed astralis-ui's. |
| `--strict-tokens` | Also warn on raw colors that bypass the tokens. |

It skips `node_modules`, `.git`, `.next`, `dist`, `build` and `out`. Each
finding names the file, line and column, a rule code, and, where there's a
closed set, the nearest valid value.

### Exit codes

| Code | Meaning |
| --- | --- |
| `0` | No errors. Warnings alone never fail the run. |
| `1` | At least one error, or the run couldn't start: no spec found, no `.tsx`/`.jsx` files, a path that doesn't exist. |

### JSON output

`--json` prints a single object. `results` lists only files with findings;
every finding has the same five fields.

```json
{
  "spec": { "name": "astralis-ui", "version": "0.8.0", "specVersion": 3 },
  "files": 12,
  "errors": 1,
  "warnings": 0,
  "results": [
    {
      "file": "src/app/page.tsx",
      "errors": [
        {
          "code": "invalid-recipe-value",
          "file": "src/app/page.tsx",
          "line": 8,
          "column": 15,
          "message": "Button: \"primary\" is not a variant value (valid: link, text, subtle, solid, surface, outline)"
        }
      ],
      "warnings": []
    }
  ]
}
```

### Raw colours: `--strict-tokens`

Arbitrary values are a feature: `bg="#ff0000"` is valid CSS and renders. But
a raw colour won't follow the theme or dark mode. `--strict-tokens` adds an
`off-token-color` warning for each one, as a drift check, without failing the
run.

To run it on every pull request and before each commit, see [Validate in
CI](/docs/validate-in-ci).

The same validator runs inside the [MCP server](/docs/ai-agents) as the
`validate_code` tool, so an AI agent checks its own output against the rules
you run in CI.

## `report`: report a problem to the maintainers

Builds an issue snapshot from the files that show the problem and sends it to
[the Astralis issue platform](/issues) as a draft, where you sign in with
GitHub, check it and submit it. The snapshot records the `astralis-ui` components in those files
with their literal props, the validator's findings for them, and the versions
of `astralis-ui`, your framework and React. It is the same snapshot the
[DevTools](/docs/devtools) build from a page.

```bash
npx astralis-cli report app/page.tsx
npx astralis-cli report src/App.tsx --title "Card loses its border" --out snapshot.json
```

| Option | |
| --- | --- |
| `--title <text>` | The report's title. Asked for when omitted; required with --yes. |
| `--happened <text>` | What happened. |
| `--expected <text>` | What you expected instead. |
| `--include-text` | Keep the text in your JSX; by default it is replaced by placeholders. |
| `--no-findings` | Leave out the validator's findings for these files. |
| `--out <file>` | Write the snapshot to a file instead of sending it. |
| `--dry-run` | Print the snapshot and send nothing. |
| `--spec <path>` | Build against this system-spec.json. Default: the installed astralis-ui's. |

It prints the exact JSON first and sends nothing until you confirm. Only props
the spec describes are recorded, and only literal values: a value computed at
run time, a link, an image source or an event handler never is. Text in your
JSX becomes a placeholder unless you pass `--include-text`.

## `connect-mcp`: connect an AI coding agent

Connects one AI client to the Astralis [MCP server](/docs/ai-agents) so its
agent reads your current component docs instead of guessing. It prompts for the
client, tells you exactly what it will do, and, once you confirm, does it.

```bash
npx astralis-cli connect-mcp
```

| Option | |
| --- | --- |
| `--client <claude-code\|codex\|cursor\|claude-desktop\|antigravity>` | Skip the prompt and configure this client. |

For Claude Code and Codex it runs the client's own `mcp add` command; for
Cursor, Claude Desktop, and Antigravity it writes the client's JSON config
(backing up any existing one first, never over an earlier backup). Full
details on the [AI Agents](/docs/ai-agents) page.

## Global options

Every command takes these, and `astralis --version` prints the CLI's version.

| Option | |
| --- | --- |
| `-y, --yes` | Never prompt; take the default answer. Replacing files still needs --overwrite or --force. |
| `-h, --help` | Show this command's options. |
| `--debug` | Print the stack trace if something fails unexpectedly. |

Without a terminal (in CI, say), a command that needs an answer stops and
tells you which flag supplies it, rather than guessing.

---

<!-- Tooling / Validate in CI: /docs/validate-in-ci -->

# Validate in CI

Run `astralis validate` before code is committed and on every pull request, so a
design-system mistake cannot be merged.

## Two gates

A team's workflow puts checks in front of version control in two places:

- **A pre-commit hook** runs on your machine, on the files you are committing,
  and stops a bad commit before it is made. It is fast feedback, but it can be
  skipped with `git commit --no-verify`.
- **A required check on the pull request** runs in CI on every change. It
  cannot be skipped: once branch protection marks it as required, nothing is
  merged until it passes.

Use the hook for speed and the CI check as the authority. Both run the same
command, so they never disagree.

The validator exits with status `1` only when it finds **errors**. Warnings,
such as a raw colour under `--strict-tokens`, are reported without failing the
run. It parses your code and never executes it.

## Set up CI in one command

From your project's root:

```bash
npx astralis-cli init --ci
```

On top of what [`init`](/docs/cli#init-add-astralis-to-an-existing-project)
already does, `--ci`:

1. installs `astralis-cli` as a devDependency, so CI and your hook run the
   version you tested with, not whatever is newest;
2. adds a `"validate": "astralis validate"` script to `package.json` (or
   `"astralis:validate"`, if you already have a `validate` script that does
   something else);
3. writes `.github/workflows/astralis-validate.yml` for your package manager:
   npm, pnpm, yarn or bun, read from your lockfile.

Running it again changes nothing. A workflow you have edited is never replaced
unless you pass `--force`.

### The workflow

For an npm project it writes exactly this. The pnpm, yarn and bun versions add
their own setup step and install command.

```yaml
# Checks every pull request against the astralis-ui design system; written by
# `astralis init --ci`. Make "Astralis validate" a required status check so a
# failing run blocks the merge: GitHub → Settings → Rules (or Branches).
name: Astralis validate

on:
  pull_request:
  push:
    branches: [main, master]

permissions:
  contents: read

jobs:
  validate:
    name: Astralis validate
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run validate
```

Inside GitHub Actions the validator reports in GitHub's annotation format, so
each finding appears on the changed line of the pull request, with its rule
code. If your project sits in a subfolder of the repository, `init --ci` puts
the workflow at the repository root and runs it in your folder, and annotations
still point at the right file.

### Make the check required

The workflow reports; branch protection is what blocks. Push the workflow once
so GitHub has seen the check, then:

1. Open the repository's **Settings → Rules → Rulesets** (or **Settings →
   Branches** for a classic branch protection rule).
2. Target your default branch.
3. Turn on **Require status checks to pass** and add **Astralis validate**.

From then on a pull request with a validator error cannot be merged.

## Add a pre-commit hook

The hook validates only the files being committed, using
[husky](https://typicode.github.io/husky/) to install the hook and
[lint-staged](https://github.com/lint-staged/lint-staged) to pass it the staged
files. It needs `astralis-cli` in your devDependencies; `init --ci` adds it, or
run `npm install -D astralis-cli`.

```bash
npm install -D husky lint-staged
npx husky init
```

Replace the contents of `.husky/pre-commit` with:

```bash
npx lint-staged
```

And add to `package.json`:

```json
{
  "lint-staged": {
    "*.{tsx,jsx}": "astralis validate"
  }
}
```

Now a commit that stages a `.tsx` or `.jsx` file with an error is refused, with
the finding printed in the terminal. A commit that stages no `.tsx` or `.jsx`
files skips the check entirely, and warnings never block a commit.

## Other CI systems

Any CI system can run the same command. It needs Node `^22.18` or `>=24.11`, and
it fails the job through the exit code:

```bash
npx astralis-cli validate
```

With `astralis-cli` in your devDependencies, `npx` runs that pinned copy;
without it, `npx` downloads the latest release on every run. For a
machine-readable result (to post a comment, or to fail on warnings as well),
use `--json`, which prints a single report in [this
shape](/docs/cli#json-output).

---

<!-- Tooling / DevTools: /docs/devtools -->

# DevTools

A development overlay for your app. A button in the corner of the page opens
three tabs: **Inspect** tells you what any Astralis component on the page is,
**Findings** shows the validator's findings for your project, live, as you
save, and **Report** sends a problem to the Astralis maintainers with the
evidence they need to reproduce it.

It runs in development only. A production build contains none of it.

## Why a UI library needs its own

React DevTools shows the component tree, but it can only show what hydrates in
the browser, and many Astralis components never do: 91 of the 238 components
and parts in the system spec are Server Components that ship no JavaScript. It also knows nothing about your
design system, such as which props a component was configured with, whether
those values are valid, or where the component is documented.

The Astralis DevTools read the library itself. In development every component
names itself on the element it renders, and a bridge in your dev server runs
the same validator as [`astralis validate`](/docs/cli#validate-check-code-against-the-design-system)
and [CI](/docs/validate-in-ci).

## Set up

From your project's root:

```bash
npx astralis-cli init --devtools
```

It installs `astralis-devtools` as a devDependency and wires it in:

- **Next.js:** `<AstralisDevTools />` goes at the end of `<body>` in your root
  layout, and the bridge's route is written to
  `app/api/astralis-devtools/[...path]/route.ts`.
- **Vite:** `astralisDevtools()` is added to the `plugins` of your
  `vite.config`.

Projects made with `npm create astralis` have the DevTools already; pass
`--no-devtools` to leave them out. Running `init --devtools` again changes
nothing.

### By hand

For **Next.js**, add the component to the root layout:

```tsx
import { AstralisDevTools } from "astralis-devtools/next";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <AstralisDevTools />
      </body>
    </html>
  );
}
```

Then create `app/api/astralis-devtools/[...path]/route.ts`:

```ts
export { GET, POST } from "astralis-devtools/next/route";
```

For **Vite**, add the plugin:

```ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { astralisDevtools } from "astralis-devtools/vite";

export default defineConfig({
  plugins: [react(), astralisDevtools()],
});
```

## Inspect

Press **Pick a component**, hover the page, and click. Clicks while picking go
to the DevTools, not to your app, so a link does not navigate and a trigger
does not open its menu. Press `Esc` to stop.

For the component you pick you see:

- **Its name,** as you would write it: `Card.Body`, not `div`.
- **The props it was given:** variant, size, colour scheme and style props,
  including responsive values such as `p={{ base: "4", md: "8" }}`. Children,
  text, links and event handlers are never shown.
- **How it reaches the browser,** from the system spec:

  | Label | Meaning |
  |---|---|
  | Server Component | Renders on the server and ships no library JavaScript |
  | Server shell, client island | Renders on the server; a small interactive part hydrates |
  | Client Component | Hydrates in the browser to be interactive |

  A Vite app renders everything in the browser, so there the label tells you
  what the component would ship in a server-rendered app.

- **A link to its documentation.**
- **What it sits inside:** the Astralis components around it, each one click
  away.

When one component renders through another onto the same element, you see the
whole chain. A `Modal.Trigger` wrapping a `Button` shows as
`Modal.Trigger → Button`, with each one's props.

## Findings

The Findings tab lists every error and warning `astralis validate` would report
for your project, with file, line and rule. It updates as you save, usually in
well under a second. The badge on the button counts the errors, or the warnings
when there are no errors.

On Next.js, the files that render the page you are looking at (its `page`
file and every `layout` and `template` above it) are listed first, under **This
page**.

## Report

When something in Astralis looks wrong, pick the component it is in and press
**Report a problem here**, or open the **Report** tab. Write a title and, if you
like, what happened and what you expected. The tab builds an issue snapshot:

- the Astralis components under the one you picked, each with the props it was
  given (only those the spec describes; never links, image sources or event
  handlers);
- the versions of `astralis-ui`, your framework and React, your browser and
  window size, and whether the page is light or dark;
- the page's path, without its query string;
- the validator's findings for the files that render the page (on Vite, for the
  project), unless you untick them.

Page text is replaced by placeholders unless you tick **Include page text**.
Console errors from this session and a screenshot are left out unless you add
them.

Below the form is **exactly** the JSON that would be sent, updated as you type.
Nothing leaves your machine until you press **Send**; the snapshot then goes to
[Issues & Contributions](/issues), the Astralis issue platform, as a private
draft, and its page opens so you can sign in with GitHub and submit it. A draft
nobody submits is deleted after 24 hours. **Copy JSON** and **Download** keep
the snapshot without sending it.

From the terminal, [`astralis report`](/docs/cli#report-report-a-problem-to-the-maintainers)
builds the same snapshot from your source files.

The snapshot's component tree is also a reproduction: the platform turns it
into a small `repro.tsx` and runs the validator on it again. Before you submit,
it compares the report with open issues: one with the same component, the same
rule codes in its findings and the same minor version of `astralis-ui` is
offered as the likely duplicate, and adding your report to it raises its report
count instead of opening a second issue.

## How it works

In development, every astralis-ui component adds two attributes to the element
it renders:

```html
<div data-astralis="Card.Body" data-astralis-props='[{}]'>
```

They are part of the server-rendered HTML, which is how Server Components can
be inspected. In production the attributes are never rendered: the library's
production HTML is byte-for-byte what it would be without the DevTools, and a
test holds it to that for every component.

The bridge runs inside your dev server. On Next.js that is the route handler
above; on Vite it is dev-server middleware, fed by Vite's own file watcher. It
validates your `.tsx` and `.jsx` files against the installed astralis-ui's
[system spec](/docs/ai-agents), re-validates each file when you save it, and
streams the findings to the overlay.

## Privacy and security

- **Nothing leaves your machine unless you send it.** The overlay talks only to
  your own dev server, and there is no telemetry or background request. The one
  request that leaves is a report you have read and pressed **Send** on.
- **The bridge answers this machine only.** A request from another device, or
  from a page on another site, is refused, even when the dev server is open to
  your network (`next dev -H 0.0.0.0`).
- **Nothing runs in production.** In a production build the Next.js route
  answers `404` without loading the bridge, and the Vite plugin applies only to
  `vite dev`.

---

<!-- Tooling / AI Agents: /docs/ai-agents -->

# AI Agents

An MCP server that feeds coding agents Astralis's current component APIs, props,
and theming, instead of guesses.

## The problem it solves

Ask an AI agent to write Astralis code and it may invent props, guess
variants, and reach for APIs that don't exist, working from stale or
second-hand knowledge instead of the real component contracts. The
`astralis-mcp` server closes that gap: it exposes the **live** documentation
over the [Model Context Protocol](https://modelcontextprotocol.io), so the agent
reads the same component docs you do (current props tables, demo source, and
theming guides) at the moment it writes code.

## Setup

The fastest path is the [CLI](/docs/cli), which walks you through connecting one
client:

```bash
npx astralis-cli connect-mcp
```

It supports Claude Code, Codex, Cursor, Claude Desktop, and Antigravity, and
configures the one you pick: running its `mcp add` command, or writing its JSON
config with your existing config backed up first.

### Configure a client by hand

Claude Code (and Codex) take an `mcp add` command directly:

```bash
claude mcp add astralis -- npx -y astralis-mcp
```

Any other MCP client takes the same server entry in its config file:

```json
{
  "mcpServers": {
    "astralis": {
      "command": "npx",
      "args": ["-y", "astralis-mcp"]
    }
  }
}
```

## What the agent gets

The server exposes eight tools:

| Tool | Returns |
| --- | --- |
| `list_components` | Every docs page (components and guides) with slug, title, description, section, and kind. The agent calls this first to discover what exists. |
| `get_component` | Full docs for one component: usage, the complete props table, accessibility notes, and runnable demo source. |
| `get_guide` | One guide page (installation, theming, tokens, and the rest) as markdown. |
| `search_docs` | Full-text search across all documentation, with a snippet around each hit. |
| `get_theming` | The complete theming reference: token system, dark mode, runtime brand color, the accent channel, and every design-token scale. |
| `list_blocks` | Every block (prebuilt page sections) with id, description, category, and the components it composes. |
| `get_block` | One block's metadata plus the complete source of its files, ready to write into a project. |
| `validate_code` | A verdict on Astralis TSX the agent wrote, checked against the design system's machine-readable spec: unknown components or parts, off-token values, invalid recipe values (`variant="primary"` is a Chakra habit, not a Button variant), dead `astralis:*` classes, broken compound anatomy, a11y mistakes. Errors name the valid alternatives, so the agent fixes its own code and validates again before showing it to you. |

The last one is the difference between retrieval and verification: the other
tools help the agent *write* against the system; `validate_code` proves what
it wrote is *inside* the system. Validation is pure computation: it runs
locally in the server process, uses no model, and prefers the spec of the
astralis-ui version installed in your project. It is the same validator as
[`astralis validate`](/docs/cli#validate-check-code-against-the-design-system),
so the rules the agent checks against are the ones you run in CI.

The spec itself (`dist/system-spec.json` in the installed package, or
[/system-spec.json](https://astralis-ui.com/system-spec.json) on this
site) also records each component's `client` field (`none`, `leaf`, or
`required`), classified from the shipped module graph at build time. No tool
returns it yet, but an agent that reads the spec can check whether a component
ships client JavaScript before putting it in a Server Component.

## How it stays current

The server holds no copy of the docs. It reads them from this site's
machine-readable endpoints, the same single pipeline that renders the pages you
are reading now, so its answers can never drift from what's published. Ship a
doc update and every connected agent sees it. If the site can't be reached,
every tool returns an error that says so, never an answer the agent might
trust, such as a real component reported as unknown.

When you're working on unpublished docs, point the server at a local build:

```bash
ASTRALIS_DOCS_URL=http://localhost:3000
```

## Browsing agents

An agent that browses the web rather than speaking MCP can read the docs
directly: [llms.txt](https://astralis-ui.com/llms.txt) is the index of
every page, and [llms-full.txt](https://astralis-ui.com/llms-full.txt)
is the entire documentation inlined into one file.

---

<!-- Buttons / Button: /docs/components/button -->

# Button

A polymorphic button with six variants, eleven color schemes, icon slots and built-in loading states.

```tsx
"use client";

import { Button, Icon, HStack } from "astralis-ui";
import { Sparkles } from "lucide-react";

export function ButtonDemo() {
  return (
    <HStack gap="3" wrap="wrap" justifyContent="center">
      <Button leftIcon={<Icon as={Sparkles} size="xs" />}>Get started</Button>
      <Button variant="subtle">Learn more</Button>
      <Button variant="outline" colorScheme="gray">
        Cancel
      </Button>
    </HStack>
  );
}
```

## Import

```tsx
import { Button } from "astralis-ui";
```

## Usage

The default button is `solid` in the brand color at size `md`. Every visual
decision (variant, hue, size, radius) is one prop away.

```tsx
import { Button, HStack } from "astralis-ui";

export function ButtonVariants() {
  return (
    <HStack gap="3" wrap="wrap" justifyContent="center">
      <Button variant="solid">Solid</Button>
      <Button variant="subtle">Subtle</Button>
      <Button variant="surface">Surface</Button>
      <Button variant="outline">Outline</Button>
      <Button variant="text">Text</Button>
      <Button variant="link">Link</Button>
    </HStack>
  );
}
```

- **solid**: the signature fill. Use it for the single primary action on a screen.
- **subtle**: a tinted fill with no border, for secondary actions.
- **surface**: the bordered sibling of `subtle`.
- **outline**: border only; fills with a faint tint on hover.
- **text**: no chrome until hover (a ghost button).
- **link**: an inline-link affordance with an underline on hover.

## Color schemes

Every variant paints through the accent channel, so a single `colorScheme`
prop recolors any button, including [runtime brand colors](/docs/theming).
Use `gray` for neutral actions and `red` for destructive ones. The full
matrix below shows all six variants across all fifteen schemes.

```tsx
import { Button, Text, VStack, HStack } from "astralis-ui";

const variants = ["solid", "subtle", "surface", "outline", "text", "link"] as const;
const schemes = [
  "brand", "gray", "red", "orange", "yellow", "green",
  "teal", "blue", "cyan", "purple", "pink",
] as const;

export function ButtonColorSchemes() {
  return (
    <VStack gap="6" alignItems="stretch">
      {variants.map((variant) => (
        <VStack key={variant} gap="2" alignItems="stretch">
          <Text as="span" size="xs" weight="medium" color="muted">
            {variant}
          </Text>
          <HStack gap="2" wrap="wrap">
            {schemes.map((scheme) => (
              <Button key={scheme} size="xs" variant={variant} colorScheme={scheme}>
                {scheme}
              </Button>
            ))}
          </HStack>
        </VStack>
      ))}
    </VStack>
  );
}
```

## Sizes

Five sizes, from compact toolbars to hero calls-to-action. Height, padding,
font size and icon gap scale together.

```tsx
import { Button, HStack } from "astralis-ui";

export function ButtonSizes() {
  return (
    <HStack gap="3" wrap="wrap" justifyContent="center">
      <Button size="xs">Extra small</Button>
      <Button size="sm">Small</Button>
      <Button size="md">Medium</Button>
      <Button size="lg">Large</Button>
      <Button size="xl">Extra large</Button>
    </HStack>
  );
}
```

## Rounded

The corner radius is independent of size: go from sharp to pill with the
`rounded` prop.

```tsx
import { Button, HStack } from "astralis-ui";

export function ButtonRounded() {
  return (
    <HStack gap="3" wrap="wrap" justifyContent="center">
      <Button variant="surface" rounded="none">None</Button>
      <Button variant="surface" rounded="sm">Small</Button>
      <Button variant="surface" rounded="lg">Large</Button>
      <Button variant="surface" rounded="2xl">2XL</Button>
      <Button variant="surface" rounded="full">Full</Button>
    </HStack>
  );
}
```

## Icons

Pass any element to `leftIcon` or `rightIcon`. Omit the label and the button
becomes a perfect square. Icon-only buttons **must** carry an `aria-label`
(the library warns in development if one is missing).

```tsx
"use client";

import { Button, Icon, HStack } from "astralis-ui";
import { Search, ChevronDown, Settings, Trash2 } from "lucide-react";

export function ButtonIcons() {
  return (
    <HStack gap="3" wrap="wrap" justifyContent="center">
      <Button leftIcon={<Icon as={Search} size="xs" />}>Search</Button>
      <Button variant="outline" rightIcon={<Icon as={ChevronDown} size="xs" />}>
        Open menu
      </Button>
      {/* Icon-only buttons need an aria-label for assistive tech. */}
      <Button variant="subtle" leftIcon={<Icon as={Settings} size="xs" />} aria-label="Settings" />
      <Button
        variant="subtle"
        colorScheme="red"
        leftIcon={<Icon as={Trash2} size="xs" />}
        aria-label="Delete"
      />
    </HStack>
  );
}
```

## Loading state

`loading` swaps in a spinner and blocks interaction without a layout shift.
`loadingText` replaces the label while pending, and `loaderPlacement` moves
the spinner to either side. Bring your own spinner via `loader`.

```tsx
"use client";

import { useState } from "react";
import { Button, HStack } from "astralis-ui";

export function ButtonLoading() {
  const [saving, setSaving] = useState(false);

  const save = () => {
    setSaving(true);
    setTimeout(() => setSaving(false), 2000);
  };

  return (
    <HStack gap="3" wrap="wrap" justifyContent="center">
      <Button loading>Loading</Button>
      <Button variant="outline" loading loadingText="Submitting…" />
      <Button variant="subtle" loading loaderPlacement="end" loadingText="Uploading" />
      <Button onClick={save} loading={saving} loadingText="Saving…">
        Click to save
      </Button>
    </HStack>
  );
}
```

## Full width

`fullWidth` stretches the button to its container, typical for checkout
flows and dialog footers.

```tsx
"use client";

import { Button, Icon, VStack } from "astralis-ui";
import { CreditCard } from "lucide-react";

export function ButtonFullWidth() {
  return (
    <VStack gap="3" w="full" maxW="sm">
      <Button fullWidth leftIcon={<Icon as={CreditCard} size="xs" />}>
        Complete checkout
      </Button>
      <Button fullWidth variant="outline" colorScheme="gray">
        Continue shopping
      </Button>
    </VStack>
  );
}
```

## Rendering as a link

Button is polymorphic: pass `as` to change the underlying element and the
accepted props follow along type-safely. Disabled non-button elements get
`aria-disabled` and leave the tab order instead of the `disabled` attribute.

```tsx
"use client";

import { Button, Icon, HStack } from "astralis-ui";
import { ExternalLink } from "lucide-react";

export function ButtonAsLink() {
  return (
    <HStack gap="3" wrap="wrap" justifyContent="center">
      {/* Renders a real <a>; href/target come from the anchor's prop types. */}
      <Button
        as="a"
        href="https://github.com"
        target="_blank"
        variant="surface"
        rightIcon={<Icon as={ExternalLink} size="xs" />}
      >
        View on GitHub
      </Button>
      <Button as="a" href="#usage" variant="link">
        Jump to usage
      </Button>
    </HStack>
  );
}
```

Buttons compose with a surrounding [Button Group](/docs/components/button-group),
which supplies shared `variant`, `colorScheme`, `size` and `disabled` defaults.
An explicit prop on a child always wins.

## Props

Button also accepts every prop of the element it renders as (`button` by default).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | "solid" \| "subtle" \| "surface" \| "outline" \| "text" \| "link" | `"solid"` | Visual style. surface is the bordered sibling of subtle; text is the ghost style. |
| `colorScheme` | all 15 schemes | `"brand"` | Hue the variant paints with. Use gray for a neutral button. |
| `size` | "xs" \| "sm" \| "md" \| "lg" \| "xl" | `"md"` | Height, padding, font size and icon gap scale together. |
| `rounded` | "none" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "full" | `"lg"` | Corner radius. |
| `fullWidth` | boolean | `false` | Stretches the button to fill its container. |
| `disabled` | boolean | `false` | Disables the button. On non-button elements this maps to aria-disabled and removes it from the tab order. |
| `loading` | boolean | `false` | Shows a spinner and disables interaction. |
| `loadingText` | ReactNode | None | Replaces the label while loading (e.g. “Saving…”); the spinner still shows. |
| `loaderPlacement` | "start" \| "end" | `"start"` | Which side the spinner renders on. |
| `loader` | ReactNode | None | Custom spinner element, replacing the built-in one. |
| `leftIcon` | ReactNode | None | Icon rendered before the label. With no label the button becomes icon-only. |
| `rightIcon` | ReactNode | None | Icon rendered after the label. |
| `as` | ElementType | `"button"` | Element or component to render. Forwarded HTML props follow the chosen element automatically. |

## Accessibility

- Renders a native `<button>` by default, so keyboard and screen-reader
  semantics come for free.
- Icon-only buttons need an `aria-label`; a development-mode warning fires
  when it's missing.
- `disabled` and `loading` on non-button elements map to `aria-disabled` and
  `tabIndex={-1}` rather than the invalid `disabled` attribute.
- Focus is always visible: a two-pixel outline in the active color scheme's
  ring token, offset from the button edge.

---

<!-- Buttons / Button Group: /docs/components/button-group -->

# Button Group

Groups related buttons, shares its styling with every child, and optionally welds them into a segmented control.

```tsx
import { Button, ButtonGroup } from "astralis-ui";

export function ButtonGroupDemo() {
  return (
    <ButtonGroup variant="outline" colorScheme="gray">
      <Button>Save draft</Button>
      <Button>Preview</Button>
      {/* An explicit prop on a child always wins over the group default. */}
      <Button variant="solid" colorScheme="brand">
        Publish
      </Button>
    </ButtonGroup>
  );
}
```

## Import

```tsx
import { ButtonGroup, Button } from "astralis-ui";
```

## Usage

Set `variant`, `colorScheme`, `size` or `disabled` once on the group and every
direct child [Button](/docs/components/button) inherits it. The group hands
the props down during server render, so the sharing costs no client
JavaScript. An explicit prop on a child always wins, which is how the
"Publish" button above breaks out of its group's outline style.

## Attached

`attached` collapses the gap, the inner corner radii, and the doubled-up
borders between neighbors, producing a single segmented control. Classic uses:
toolbars and pagination.

```tsx
"use client";

import { Button, ButtonGroup, Icon, VStack } from "astralis-ui";
import { AlignLeft, AlignCenter, AlignRight, ChevronLeft, ChevronRight } from "lucide-react";

export function ButtonGroupAttached() {
  return (
    <VStack gap="4" alignItems="start">
      <ButtonGroup attached variant="outline" colorScheme="gray">
        <Button leftIcon={<Icon as={AlignLeft} size="xs" />} aria-label="Align left" />
        <Button leftIcon={<Icon as={AlignCenter} size="xs" />} aria-label="Align center" />
        <Button leftIcon={<Icon as={AlignRight} size="xs" />} aria-label="Align right" />
      </ButtonGroup>

      <ButtonGroup attached variant="subtle">
        <Button leftIcon={<Icon as={ChevronLeft} size="xs" />}>Previous</Button>
        <Button rightIcon={<Icon as={ChevronRight} size="xs" />}>Next</Button>
      </ButtonGroup>
    </VStack>
  );
}
```

## Orientation

`orientation="vertical"` stacks the buttons. It composes with `attached` for
vertical segmented controls.

```tsx
import { Button, ButtonGroup, HStack } from "astralis-ui";

export function ButtonGroupOrientation() {
  return (
    <HStack gap="8" alignItems="start">
      <ButtonGroup orientation="vertical" variant="surface">
        <Button>Profile</Button>
        <Button>Settings</Button>
        <Button>Sign out</Button>
      </ButtonGroup>

      <ButtonGroup orientation="vertical" attached variant="outline" colorScheme="gray">
        <Button>Day</Button>
        <Button>Week</Button>
        <Button>Month</Button>
      </ButtonGroup>
    </HStack>
  );
}
```

## Spacing

When not attached, `spacing` controls the gap between buttons.

```tsx
import { Button, ButtonGroup, Text, VStack } from "astralis-ui";

const spacings = ["none", "sm", "md", "lg"] as const;

export function ButtonGroupSpacing() {
  return (
    <VStack gap="5" alignItems="stretch">
      {spacings.map((spacing) => (
        <VStack key={spacing} gap="2" alignItems="stretch">
          <Text as="span" size="xs" weight="medium" color="muted">
            {spacing}
          </Text>
          <ButtonGroup spacing={spacing} variant="subtle" size="sm">
            <Button>One</Button>
            <Button>Two</Button>
            <Button>Three</Button>
          </ButtonGroup>
        </VStack>
      ))}
    </VStack>
  );
}
```

## Disabled

Disabling the group disables every button in it, handy while a form section
is pending.

```tsx
import { Button, ButtonGroup } from "astralis-ui";

export function ButtonGroupDisabled() {
  return (
    <ButtonGroup disabled variant="outline" colorScheme="gray">
      <Button>Cut</Button>
      <Button>Copy</Button>
      <Button>Paste</Button>
    </ButtonGroup>
  );
}
```

## Props

Button Group renders a `div` and accepts all its standard attributes.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | "horizontal" \| "vertical" | `"horizontal"` | Lays the buttons out in a row or a column. |
| `attached` | boolean | `false` | Welds the buttons into one segmented control: inner radii collapse and adjacent borders merge. spacing is ignored. |
| `spacing` | "none" \| "sm" \| "md" \| "lg" | `"md"` | Gap between buttons when not attached. |
| `variant` | "solid" \| "subtle" \| "surface" \| "outline" \| "text" \| "link" | None | Shared visual style pushed onto every child Button. |
| `colorScheme` | all 15 schemes | None | Shared hue pushed onto every child Button. |
| `size` | "xs" \| "sm" \| "md" \| "lg" \| "xl" | None | Shared size pushed onto every child Button. |
| `disabled` | boolean | `false` | Disables every child Button at once. |

## Accessibility

- Renders with `role="group"` by default; pass a `role` (e.g. `toolbar`) and
  an `aria-label` to describe the set when the context isn't obvious.
- Attached icon-only buttons still need individual `aria-label`s. See the
  alignment toolbar demo.

---

<!-- Buttons / Floating Button: /docs/components/floating-button -->

# Floating Button

A button pinned above the page, anchored to a corner or edge midpoint by
default, and draggable anywhere. Built on [Button](/docs/components/button),
so every variant, size and `colorScheme` comes along.

```tsx
"use client";

import { Box, FloatingButton, Icon, Text, VStack } from "astralis-ui";
import { MessageCircle } from "lucide-react";

/*
 * The `transform: translateZ(0)` on the panel is load-bearing: a transformed
 * ancestor becomes the containing block for `position: fixed`, so the button
 * pins to this panel instead of the real viewport. Dragging is disabled in
 * these contained demos: the drag math works in viewport coordinates, which a
 * containing block deliberately breaks.
 */
export function FloatingButtonDemo() {
  return (
    <Box
      position="relative"
      h="56"
      w="full"
      maxW="md"
      overflow="hidden"
      rounded="xl"
      border="normal"
      borderColor="subtle"
      bg="subtle"
      style={{ transform: "translateZ(0)" }}
    >
      <VStack gap="2" p="5" alignItems="start">
        <Text size="xl" weight="medium">
          Your app
        </Text>
        <Text size="sm" color="muted">
          The button floats above the content, pinned to a corner.
        </Text>
      </VStack>
      <FloatingButton
        draggable={false}
        aria-label="Open chat"
        leftIcon={<Icon as={MessageCircle} size="sm" />}
      >
        Chat
      </FloatingButton>
    </Box>
  );
}
```

## Import

```tsx
import { FloatingButton } from "astralis-ui";
```

## Usage

The default is a `solid` brand pill resting in the bottom-right corner, with
elevation and a full radius: the affordance of something sitting *above* the
page rather than in it. It renders in a `position: fixed` wrapper just under
the overlay layer, so it clears page chrome but stays beneath modals and
drawers.

The demos on this page are fenced into their panels (a transformed ancestor
becomes the containing block for `fixed`), so they rest against the panel
instead of your screen.

## Placement

Six resting anchors: the four corners plus the two horizontal edge midpoints.
`offset` controls how far it sits from the edges.

```tsx
"use client";

import { Box, FloatingButton } from "astralis-ui";

const anchors = [
  { placement: "top-left", colorScheme: "teal" },
  { placement: "center-top", colorScheme: "blue" },
  { placement: "top-right", colorScheme: "purple" },
  { placement: "bottom-left", colorScheme: "pink" },
  { placement: "center-bottom", colorScheme: "brand" },
  { placement: "bottom-right", colorScheme: "green" },
] as const;

/* One panel, six resting anchors: four corners plus the two edge midpoints.
   The transform scopes `fixed` to the panel; see floating-button-demo.tsx. */
export function FloatingButtonPlacements() {
  return (
    <Box
      position="relative"
      h="64"
      w="full"
      overflow="hidden"
      rounded="xl"
      border="normal"
      borderColor="subtle"
      bg="subtle"
      style={{ transform: "translateZ(0)" }}
    >
      {anchors.map(({ placement, colorScheme }) => (
        <FloatingButton
          key={placement}
          placement={placement}
          colorScheme={colorScheme}
          offset="sm"
          size="xs"
          draggable={false}
          aria-label={placement}
        >
          {placement}
        </FloatingButton>
      ))}
    </Box>
  );
}
```

## Icon-only

Omit the label and Button's icon-only behavior kicks in: a square frame that
the default `rounded="full"` turns into the classic circular FAB. Icon-only
buttons **must** carry an `aria-label`. The library warns in development
when one is missing.

```tsx
"use client";

import { Box, FloatingButton, Icon } from "astralis-ui";
import { Plus, Pencil, ArrowUp } from "lucide-react";

/* Icon-only: with no label, Button gives the FAB a square frame, and the
   default `rounded="full"` turns it into the classic circle. */
export function FloatingButtonIcon() {
  return (
    <Box
      position="relative"
      h="56"
      w="full"
      maxW="md"
      overflow="hidden"
      rounded="xl"
      border="normal"
      borderColor="subtle"
      bg="subtle"
      style={{ transform: "translateZ(0)" }}
    >
      <FloatingButton
        placement="bottom-right"
        size="lg"
        draggable={false}
        aria-label="Create"
        leftIcon={<Icon as={Plus} size="md" />}
      />
      <FloatingButton
        placement="center-bottom"
        colorScheme="gray"
        variant="surface"
        draggable={false}
        aria-label="Compose"
        leftIcon={<Icon as={Pencil} size="sm" />}
      />
      <FloatingButton
        placement="bottom-left"
        size="sm"
        colorScheme="teal"
        draggable={false}
        aria-label="Back to top"
        leftIcon={<Icon as={ArrowUp} size="sm" />}
      />
    </Box>
  );
}
```

## Dragging

Dragging is on by default and pointer-based, so mouse, touch and pen all work
from one path. A press only becomes a drag past `dragThreshold`. Below that
it stays a click, so a slightly shaky tap still fires the action. With the
button focused, arrow keys nudge it 8px per press (1px with Shift held),
which keeps repositioning reachable without a pointer.

The launcher floating on this very site is a draggable `FloatingButton`. Try
moving it. The contained demos above disable dragging because the drag math
works in viewport coordinates, which the demo panels deliberately break.

Set `draggable={false}` when the position is part of the design.

## Controlled position

Pass `position` with `onPositionChange` to own the position yourself, for
example to restore it across visits. `onPositionCommit` fires once when a
drag ends, which is the hook for persisting; `onPositionChange` fires every
frame, which is not.

```tsx
const [position, setPosition] = useState<FloatingButtonPosition | null>(
  () => readSavedPosition(), // null = rest at `placement`
);

<FloatingButton
  position={position}
  onPositionChange={setPosition}
  onPositionCommit={savePosition}
  aria-label="Open chat"
>
  Chat
</FloatingButton>;
```

A dragged position is clamped to the viewport (minus `edgePadding`) during
the drag and again on window resize, so a shrinking window can never strand
the button off-screen.

## Props

FloatingButton extends [Button](/docs/components/button), so `variant`,
`colorScheme`, `size`, `rounded`, icons and loading states all apply:
everything except `fullWidth`, which makes no sense on a floating element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `placement` | "bottom-right" \| "bottom-left" \| "top-right" \| "top-left" \| "center-bottom" \| "center-top" | `"bottom-right"` | Anchor the button rests at until it is dragged: a corner or an edge midpoint. |
| `offset` | "sm" \| "md" \| "lg" | `"md"` | Distance from the viewport edges at rest. |
| `draggable` | boolean | `true` | Allow repositioning by pointer drag and arrow keys. Disable for a button that must stay put. |
| `position` | { x: number; y: number } \| null | None | Controlled position in viewport pixels. Pass with onPositionChange to own the position yourself; omit to let the button track it internally. |
| `onPositionChange` | (position: { x: number; y: number }) => void | None | Fires on every drag frame, and on keyboard repositioning. |
| `onPositionCommit` | (position: { x: number; y: number }) => void | None | Fires once when a drag ends, the right hook for persisting a position. |
| `edgePadding` | number | `8` | Clearance kept between the button and the viewport edges when clamping. |
| `dragThreshold` | number | `4` | Pointer travel (px) before a press becomes a drag. Below it the gesture is still a click, so a shaky tap does not swallow the action. |
| `wrapperClassName` | string | None | Class for the fixed wrapper element; className still targets the button itself. |

## Accessibility

- A real `<button>` via Button, so keyboard and screen-reader semantics come
  for free.
- Arrow-key repositioning works whenever the button has focus; Shift steps by
  1px for fine placement.
- The click that browsers fire after a drag is swallowed, so repositioning
  never accidentally triggers the action.
- Icon-only usage requires an `aria-label`; a development-mode warning fires
  when it's missing.

---

<!-- Buttons / Theme Toggle: /docs/components/theme-toggle -->

# Theme Toggle

A ready-made light/dark switch built on Button, with a cross-fading sun and moon.

```tsx
import { ThemeToggle } from "astralis-ui";

export function ThemeToggleDemo() {
  return <ThemeToggle />;
}
```

## Import

```tsx
import { ThemeToggle } from "astralis-ui";
```

## Usage

Drop it anywhere inside an `AstralisProvider`: it reads and writes the theme
through the same context the whole library uses, and persists the choice to
`localStorage`. Every demo on this page is live: clicking one switches this
site's theme, and the icon rotates a quarter turn as sun and moon cross-fade.

The one in this site's header is this exact component.

## With a label

`showLabel` adds a text label that names the mode a click switches **to**.
Sizing follows Button's scale, and the icon scales with it.

```tsx
import { ThemeToggle, HStack } from "astralis-ui";

export function ThemeToggleLabel() {
  return (
    <HStack gap="3" wrap="wrap" justifyContent="center">
      <ThemeToggle showLabel size="sm" />
      <ThemeToggle showLabel />
      <ThemeToggle showLabel size="lg" />
    </HStack>
  );
}
```

## Variants

Theme Toggle extends [Button](/docs/components/button), so every variant,
`colorScheme`, `size` and `rounded` value works.

```tsx
import { ThemeToggle, HStack } from "astralis-ui";

export function ThemeToggleVariants() {
  return (
    <HStack gap="3" wrap="wrap" justifyContent="center">
      <ThemeToggle variant="solid" />
      <ThemeToggle variant="subtle" />
      <ThemeToggle variant="outline" />
      <ThemeToggle variant="text" />
      <ThemeToggle variant="subtle" colorScheme="purple" showLabel />
      <ThemeToggle variant="outline" colorScheme="gray" rounded="full" />
    </HStack>
  );
}
```

## Reading the theme yourself

For custom controls, the same context is available via the `useTheme` hook:

```tsx
import { useTheme } from "astralis-ui";

function CustomSwitch() {
  const { theme, resolvedTheme, setTheme } = useTheme();
  // theme: "light" | "dark" | "system" (the user's setting)
  // resolvedTheme: "light" | "dark" (what's actually applied)
  return (
    <button onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}>
      Switch to {resolvedTheme === "dark" ? "light" : "dark"}
    </button>
  );
}
```

## Props

Theme Toggle accepts every [Button](/docs/components/button) prop except
`children` and `onClick` (it owns both). The most relevant:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showLabel` | boolean | `false` | Shows a text label next to the icon: “Light Mode” or “Dark Mode”, reflecting what a click switches to. |
| `variant` | "solid" \| "subtle" \| "surface" \| "outline" \| "text" \| "link" | `"outline"` | Inherited from Button. Every Button variant works. |
| `size` | "xs" \| "sm" \| "md" \| "lg" \| "xl" | `"md"` | Inherited from Button; the icon scales with it. |

## Accessibility

- Without a label it carries `aria-label="Toggle theme"` automatically; with
  `showLabel` the visible text is the accessible name.
- Must be rendered inside an `AstralisProvider`: `useTheme` throws otherwise.

---

<!-- Buttons / Copy Button: /docs/components/copy-button -->

# Copy Button

A [Button](/docs/components/button) that writes `value` to the clipboard and
confirms with a transient copied state. It is the general-purpose sibling of
`CodeBlock.CopyTrigger`. Every Button prop (variant, size, colorScheme, …)
passes straight through.

```tsx
import { CopyButton, HStack } from "astralis-ui";

export function CopyButtonDemo() {
  return (
    <HStack gap="3">
      <CopyButton value="npm install astralis-ui" />
      <CopyButton value="https://astralis.dev" variant="outline" colorScheme="gray" size="sm">
        Copy link
      </CopyButton>
    </HStack>
  );
}
```

## Import

```tsx
import { CopyButton } from "astralis-ui";
```

## Usage

`value` is what lands on the clipboard; the label is separate, so a button
can say "Copy link" while copying the full URL. After a successful copy the
label swaps to `copiedLabel` for `timeout` milliseconds, and the button
carries a `data-copied` attribute you can style against. If the browser
refuses clipboard access, the label stays put rather than claiming a copy
that didn't happen.

```tsx
import { CopyButton } from "astralis-ui";

export function CopyButtonLabels() {
  return (
    <CopyButton value="AST-7F3K-92QD" copiedLabel="Invite code copied" timeout={3000} variant="subtle">
      Copy invite code
    </CopyButton>
  );
}
```

## Props

Takes every [Button](/docs/components/button) prop except `leftIcon`, which
the copied state owns. The ones that matter most:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | None | The text written to the clipboard. Required. |
| `children` | ReactNode | `"Copy"` | Label at rest. |
| `copiedLabel` | ReactNode | `"Copied"` | Label while the copied state lasts. |
| `timeout` | number | `1600` | How long the copied state lasts, in milliseconds. |
| `variant` | "solid" \| "subtle" \| "surface" \| "outline" \| "text" \| "link" | `"solid"` | Button style, as on Button. |
| `size` | "xs" \| "sm" \| "md" \| "lg" \| "xl" | `"md"` | Button size, as on Button. |
| `colorScheme` | all 15 schemes | `"brand"` | Button hue, as on Button. |

## Accessibility

The copied state changes the button's label, but it isn't a live region, so a
screen reader reports it only when the button is read again. Keep
`copiedLabel` meaningful on its own ("Link copied" rather than "Done").

---

<!-- Buttons / Toolbar: /docs/components/toolbar -->

# Toolbar

A `role="toolbar"` container for grouped controls, on the APG toolbar
pattern: arrow keys move focus between the focusable children, Home/End
jump to the edges. Compose it with [Button](/docs/components/button),
[SegmentedControl](/docs/components/segmented-control),
[CopyButton](/docs/components/copy-button), or anything focusable.

```tsx
import { Toolbar, Button } from "astralis-ui";
import { Bold, Italic, Underline, Link2, List, ListOrdered } from "lucide-react";

export function ToolbarDemo() {
  return (
    <Toolbar label="Text formatting">
      <Toolbar.Group aria-label="Style">
        <Button size="sm" variant="text" colorScheme="gray" aria-label="Bold">
          <Bold size={16} />
        </Button>
        <Button size="sm" variant="text" colorScheme="gray" aria-label="Italic">
          <Italic size={16} />
        </Button>
        <Button size="sm" variant="text" colorScheme="gray" aria-label="Underline">
          <Underline size={16} />
        </Button>
      </Toolbar.Group>
      <Toolbar.Separator />
      <Toolbar.Group aria-label="Lists">
        <Button size="sm" variant="text" colorScheme="gray" aria-label="Bulleted list">
          <List size={16} />
        </Button>
        <Button size="sm" variant="text" colorScheme="gray" aria-label="Numbered list">
          <ListOrdered size={16} />
        </Button>
      </Toolbar.Group>
      <Toolbar.Separator />
      <Button size="sm" variant="text" colorScheme="gray" aria-label="Insert link">
        <Link2 size={16} />
      </Button>
    </Toolbar>
  );
}
```

## Import

```tsx
import { Toolbar } from "astralis-ui";
```

## Accessibility

- Give every toolbar a `label`: a toolbar without a name is just a row of
  buttons.
- Icon-only controls need their own `aria-label` (or a
  [VisuallyHidden](/docs/components/visually-hidden) text).

## Props

Extends `div` props:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | string | None | Accessible name, set as aria-label. A toolbar without one is just a row of buttons. |
| `orientation` | "horizontal" \| "vertical" | `"horizontal"` | Layout direction, and which arrow keys move focus. |

### Parts

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Toolbar.Group` | div props | None | A cluster of related controls with the group role. Give it an aria-label. |
| `Toolbar.Separator` | div props | None | A vertical rule between groups. |

## Keyboard

With focus on a control in the toolbar:

| Key | Action |
| --- | --- |
| `←` / `→` | Previous / next control (horizontal; wraps at the ends) |
| `↑` / `↓` | Previous / next control (vertical; wraps at the ends) |
| `Home` / `End` | First / last control |
| `Tab` | Next control, or out of the toolbar after the last one |

Disabled controls are skipped. Every control keeps its own tab stop, so `Tab`
also walks through them one by one.

---

<!-- Layout / Box: /docs/components/box -->

# Box

The foundational layout primitive: a polymorphic `div` with every style token as a typed prop.

```tsx
import { Box, Text } from "astralis-ui";

export function BoxDemo() {
  return (
    <Box bg="subtle" p="6" rounded="xl" border="normal" borderColor="base" shadow="sm" maxW="sm">
      <Text weight="semibold">A humble Box</Text>
      <Text size="sm" color="muted">
        Every layout primitive in Astralis builds on this: spacing, sizing,
        color, borders and radius as typed token props.
      </Text>
    </Box>
  );
}
```

## Import

```tsx
import { Box } from "astralis-ui";
```

## Usage

Box turns the design system's tokens into props: spacing, sizing, color,
borders, radius, shadows and positioning, all typed: your editor
autocompletes the valid values, and anything off-scale is a type error.
Every other layout component ([Flex](/docs/components/flex),
[Stack](/docs/components/stack), [Grid](/docs/components/grid), …) extends
Box, so everything on this page applies to all of them.

```tsx
import { Box, HStack } from "astralis-ui";

export function BoxStyleProps() {
  return (
    <HStack gap="4" wrap="wrap" justifyContent="center">
      <Box bg="brand-subtle" size="16" rounded="md" />
      <Box bg="brand-muted" size="16" rounded="lg" />
      <Box bg="brand" size="16" rounded="xl" shadow="md" />
      <Box bg="transparent" size="16" rounded="xl" border="thick" borderColor="brand" />
      <Box bg="inverted" size="16" rounded="full" />
    </HStack>
  );
}
```

## Responsive props

Every style prop also accepts a breakpoint map with `base`, `sm`, `md`, `lg`
and `xl` keys, resolved to precompiled classes, no runtime style computation.

```tsx
import { Box, Text } from "astralis-ui";

export function BoxResponsive() {
  return (
    <Box
      bg="green-subtle"
      rounded={{ base: "md", md: "2xl" }}
      p={{ base: "4", md: "8", lg: "12" }}
    >
      <Text size="sm" color="muted">
        Resize the window: padding and radius step up at md and lg.
      </Text>
    </Box>
  );
}
```

```tsx
<Box p={{ base: "4", md: "8", lg: "12" }} rounded={{ base: "md", md: "2xl" }} />
```

To respond to the space a component actually has rather than the window, mark
an ancestor with `container` and use the `@sm`–`@xl` keys, which measure that
ancestor. [Container queries](/docs/responsive#container-queries) covers the
details.

```tsx
<Box container>
  <Flex direction={{ base: "column", "@md": "row" }} gap="4">…</Flex>
</Box>
```

## Polymorphism

`as` swaps the rendered element. Reach for it whenever the semantic element
matters (`section`, `aside`, `nav`, `figure` …).

```tsx
import { Box, Text } from "astralis-ui";

export function BoxAs() {
  return (
    /* Renders a semantic <aside>; any element or component works. */
    <Box as="aside" bg="blue-subtle" p="5" rounded="lg" maxW="md">
      <Text size="sm" weight="medium">
        Did you know?
      </Text>
      <Text size="sm" color="muted">
        Box is polymorphic: the `as` prop swaps the rendered element while
        keeping every style prop.
      </Text>
    </Box>
  );
}
```

## Props

Box is transparent and unstyled by default: every prop below is opt-in.
Grouped by family; each family's values come straight from the token scale
(the full reference will live on the Design Tokens page).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `p · px · py · pt/pb/pl/pr` | "0" – "96" (spacing scale) | None | Padding: all sides, per axis, or per edge. |
| `m · mx · my · mt/mb/ml/mr` | "0" – "96" (spacing scale) \| "auto" | None | Margin: all sides, per axis, or per edge. auto pushes a flex item to the far edge or centres a fixed-width block. |
| `w · h · size · minW/maxW · minH/maxH` | spacing scale \| "xs"–"8xl" \| fractions \| "auto" \| "full" \| "fit" \| "prose" … | None | Sizing. size sets width and height at once. |
| `bg` | "base" \| "subtle" \| "muted" \| "raised" \| "inverted" \| "{hue}" (solid) \| "{hue}-subtle" \| "{hue}-muted" \| "{hue}-50"–"{hue}-950" | None | Background from semantic roles, palette roles, or raw shades. Transparent by default. base is the page, subtle the thing sitting on it, muted a filled control; raised is for floating layers only. |
| `color` | "base" \| "muted" \| "subtle" \| "inverted" \| "{hue}" (label) \| "{hue}-solid" \| "{hue}-contrast" | None | Text color token; children inherit it. |
| `border (+ borderT/R/B/L) · borderStyle · borderColor` | "normal"–"thickest" · CSS styles · "base" \| "subtle" \| "muted" \| "{hue}" (stroke) | None | Border width, style and color tokens. Per-side widths mirror rounded: borderB is a header rule, borderT a footer one. |
| `rounded (+ roundedT/R/B/L, roundedTl/Tr/Br/Bl)` | "none" \| "2xs"–"4xl" \| "full" | None | Corner radius: all corners, per side, or per corner. |
| `display` | "block" \| "flex" \| "grid" \| "hidden" \| … | None | CSS display. |
| `position · inset · top/right/bottom/left · zIndex` | position tokens + offset scale | None | Positioning. |
| `shadow` | "none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "inner" | None | Box shadow token. |
| `opacity · overflow(X/Y) · cursor · pointerEvents · aspectRatio` | token maps | None | Misc utilities, all typed. |
| `basis · flex · grow · shrink · order · alignSelf` | sizing scale · "1" \| "auto" \| "initial" \| "none" · boolean \| "0" \| "1" · "1"–"12" · "auto" \| "start" \| "center" \| "end" \| "stretch" \| "baseline" | None | How the element behaves as a child of a flex or grid parent. On Box, so any primitive can size itself without a Flex.Item wrapper. |
| `container` | boolean | `false` | Makes this element the query container that descendants' @sm–@xl responsive keys measure against, instead of the viewport. |
| `as` | ElementType | `"div"` | Element or component to render; HTML props follow it type-safely. |

---

<!-- Layout / Flex: /docs/components/flex -->

# Flex

A [Box](/docs/components/box) with flexbox layout props: direction, alignment, wrap and gap as typed tokens.

```tsx
import { Flex, Box, Text, Button } from "astralis-ui";

export function FlexDemo() {
  return (
    <Flex
      justifyContent="between"
      alignItems="center"
      gap="4"
      w="full"
      maxW="lg"
      bg="subtle"
      p="4"
      rounded="xl"
      border="normal"
      borderColor="base"
    >
      <Flex alignItems="center" gap="3">
        <Box size="10" bg="brand" rounded="full" />
        <Box>
          <Text size="sm" weight="semibold">Nova Starling</Text>
          <Text size="xs" color="muted">Product designer</Text>
        </Box>
      </Flex>
      <Button size="sm" variant="outline" colorScheme="gray">
        Follow
      </Button>
    </Flex>
  );
}
```

## Import

```tsx
import { Flex } from "astralis-ui";
// Flex.Item is available on the component itself
```

## Alignment

`justifyContent` distributes children along the main axis, `alignItems` along
the cross axis, the same vocabulary as CSS, minus the `flex-` prefixes.

```tsx
import { Flex, Box, Text, VStack } from "astralis-ui";

const justifyValues = ["start", "center", "end", "between", "around", "evenly"] as const;

export function FlexAlign() {
  return (
    <VStack gap="4" alignItems="stretch" w="full" maxW="md">
      {justifyValues.map((justify) => (
        <VStack key={justify} gap="1" alignItems="stretch">
          <Text as="span" size="xs" color="muted">
            justifyContent=&quot;{justify}&quot;
          </Text>
          <Flex justifyContent={justify} gap="2" bg="subtle" p="2" rounded="lg">
            <Box size="8" bg="brand" rounded="md" />
            <Box size="8" bg="brand-muted" rounded="md" />
            <Box size="8" bg="brand-subtle" rounded="md" />
          </Flex>
        </VStack>
      ))}
    </VStack>
  );
}
```

Left alone, `alignItems` is CSS's `stretch`: children fill the cross size, so a
row gives you equal-height cards and a column gives you equal-width rows. That
is usually what you want for a page skeleton (a sidebar reaching the full
height of the row it sits in), and it is why a bare `<Flex>` behaves exactly
like `display: flex` and nothing more. When you want children to keep their
natural size, say so:

```tsx
{/* chips that keep their own height instead of matching the tallest */}
<Flex alignItems="start" gap="2">
```

## Flex items

`basis`, `flex`, `grow`, `shrink`, `order` and `alignSelf` describe how an
element behaves as a *child*, so they live on [Box](/docs/components/box) and
work on any primitive: `<Flex shrink="0">` needs no wrapper. `Flex.Item`
declares the same props and stays the clearer spelling when a plain `div` is
all you wanted.

```tsx
"use client";

import { Flex, Center, Text } from "astralis-ui";

export function FlexItem() {
  return (
    <Flex gap="3" w="full" maxW="md">
      <Flex.Item basis="24">
        <Center bg="brand-subtle" p="3" rounded="lg">
          <Text size="xs">basis 24</Text>
        </Center>
      </Flex.Item>
      <Flex.Item grow>
        <Center bg="brand-muted" p="3" rounded="lg">
          <Text size="xs">grow</Text>
        </Center>
      </Flex.Item>
      <Flex.Item order="first">
        <Center bg="brand" p="3" rounded="lg">
          <Text size="xs" color="inverted">order first</Text>
        </Center>
      </Flex.Item>
    </Flex>
  );
}
```

## Responsive direction

Every layout prop accepts a breakpoint map. The classic: stack on mobile,
row on desktop.

```tsx
import { Flex, Box, Text } from "astralis-ui";

export function FlexResponsive() {
  return (
    /* Column on mobile, row from md up. */
    <Flex direction={{ base: "column", md: "row" }} gap="3" w="full" maxW="md">
      <Box bg="teal-subtle" p="4" rounded="lg">
        <Text size="sm">One</Text>
      </Box>
      <Box bg="teal-muted" p="4" rounded="lg">
        <Text size="sm">Two</Text>
      </Box>
      <Box bg="teal-muted" p="4" rounded="lg">
        <Text size="sm">Three</Text>
      </Box>
    </Flex>
  );
}
```

For simple one-direction stacking, [Stack](/docs/components/stack) is the
shorter spelling.

## Props

Flex extends [Box](/docs/components/box), so every style prop works here too.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `direction` | "row" \| "column" \| "row-reverse" \| "column-reverse" | `"row"` | Main-axis direction. |
| `justifyContent` | "start" \| "center" \| "end" \| "between" \| "around" \| "evenly" | `"start"` | Distribution along the main axis. |
| `alignItems` | "start" \| "center" \| "end" \| "baseline" \| "stretch" | `"stretch"` | Alignment along the cross axis. Unset, it is CSS's stretch (children fill the cross size), so a row gives equal heights and a column gives equal widths. |
| `wrap` | "wrap" \| "nowrap" \| "wrap-reverse" | `"nowrap"` | Whether children wrap onto new lines. |
| `gap · rowGap · columnGap` | "0" – "96" (spacing scale) | None | Gap between children, together or per axis. |
| `alignContent · placeContent` | "start" \| "center" \| "end" \| "between" \| "around" \| "evenly" \| "stretch" | None | Multi-line / shorthand content alignment. |

### Flex.Item

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `basis` | spacing scale \| "3xs"–"8xl" \| fractions \| "auto" \| "full" \| "min" \| "max" \| "fit" | None | flex-basis: the item's starting size. |
| `flex` | "1" \| "auto" \| "initial" \| "none" | None | The flex shorthand. |
| `grow · shrink` | boolean \| "0" \| "1" | None | Whether the item grows into / gives up free space. |
| `order` | "1" – "12" \| "first" \| "last" \| "none" | None | Visual order, independent of source order. |
| `alignSelf` | "auto" \| "start" \| "end" \| "center" \| "stretch" \| "baseline" | None | Overrides the container's alignItems for this item. |

---

<!-- Layout / Stack: /docs/components/stack -->

# Stack

One-dimensional stacking with a consistent gap, plus the `HStack` and `VStack` presets.

```tsx
import { VStack, Box, Text } from "astralis-ui";

export function StackDemo() {
  return (
    <VStack gap="3" alignItems="stretch" w="full" maxW="sm">
      {["Design review at 10:00", "Ship the docs site", "Water the plants"].map((task) => (
        <Box key={task} bg="subtle" p="4" rounded="lg" border="normal" borderColor="base">
          <Text size="sm">{task}</Text>
        </Box>
      ))}
    </VStack>
  );
}
```

## Import

```tsx
import { Stack, HStack, VStack } from "astralis-ui";
```

## Usage

Stack is the shorthand for the most common flex layout: children in one
direction with even spacing. `VStack` stacks vertically, `HStack` lays out
horizontally **and centers its children on the cross axis**, usually what
you want for rows of mixed-height content.

```tsx
import { HStack, Box, Text, Button } from "astralis-ui";

export function StackHorizontal() {
  return (
    /* HStack centers its children vertically by default. */
    <HStack gap="4" bg="subtle" p="4" rounded="xl" border="normal" borderColor="base">
      <Box size="12" bg="purple" rounded="full" />
      <Box>
        <Text size="sm" weight="semibold">Orbit weekly</Text>
        <Text size="xs" color="muted">12 unread updates</Text>
      </Box>
      <Button size="sm" variant="subtle" colorScheme="purple">
        Open
      </Button>
    </HStack>
  );
}
```

## Direction

The base `Stack` takes a `direction` prop if you'd rather not pick a preset.
It speaks in axes (`"vertical"` and `"horizontal"`) rather than CSS's
`column` and `row`.

```tsx
import { Stack, Box, Text, VStack } from "astralis-ui";

export function StackDirection() {
  return (
    <VStack gap="5" alignItems="stretch">
      <VStack gap="1" alignItems="stretch">
        <Text as="span" size="xs" color="muted">vertical (default)</Text>
        <Stack gap="2">
          <Box bg="cyan-subtle" px="4" py="2" rounded="md"><Text size="xs">One</Text></Box>
          <Box bg="cyan-muted" px="4" py="2" rounded="md"><Text size="xs">Two</Text></Box>
        </Stack>
      </VStack>
      <VStack gap="1" alignItems="stretch">
        <Text as="span" size="xs" color="muted">horizontal</Text>
        <Stack direction="horizontal" gap="2">
          <Box bg="cyan-subtle" px="4" py="2" rounded="md"><Text size="xs">One</Text></Box>
          <Box bg="cyan-muted" px="4" py="2" rounded="md"><Text size="xs">Two</Text></Box>
        </Stack>
      </VStack>
    </VStack>
  );
}
```

`direction` is responsive like every other style prop, so the most common
layout of all (stacked on mobile, side by side on desktop) is one prop:

```tsx
import { Stack, Box, Text } from "astralis-ui";

export function StackResponsive() {
  return (
    /* Resize the window: vertical below md, horizontal from md up. */
    <Stack
      direction={{ base: "vertical", md: "horizontal" }}
      gap="3"
      w="full"
      maxW="md"
    >
      <Box bg="cyan-subtle" px="4" py="3" rounded="lg">
        <Text size="xs">One</Text>
      </Box>
      <Box bg="cyan-muted" px="4" py="3" rounded="lg">
        <Text size="xs">Two</Text>
      </Box>
      <Box bg="cyan-muted" px="4" py="3" rounded="lg">
        <Text size="xs">Three</Text>
      </Box>
    </Stack>
  );
}
```

For two-dimensional layouts or per-child control, step up to
[Flex](/docs/components/flex) or [Grid](/docs/components/grid).

## Props

Stack extends [Flex](/docs/components/flex) (and therefore [Box](/docs/components/box)).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `direction` | "horizontal" \| "vertical" | `"vertical"` | Stacking axis, responsive like every other style prop: direction={{ base: "vertical", md: "horizontal" }} is stack-on-mobile, row-on-desktop. HStack and VStack are presets with this fixed (HStack also centres on the cross axis). |
| `gap` | "0" – "96" (spacing scale) | None | Space between children. |
| `alignItems · justifyContent · wrap …` | Flex props | None | Stack is a Flex preset: every Flex and Box prop works. |

---

<!-- Layout / Grid: /docs/components/grid -->

# Grid

CSS Grid as a [Box](/docs/components/box): tokenized columns, rows, gaps and alignment, with `Grid.Item` for placement.

```tsx
import { Grid, Center, Text } from "astralis-ui";

export function GridDemo() {
  return (
    <Grid columns="3" gap="3" w="full" maxW="md">
      {[1, 2, 3, 4, 5, 6].map((n) => (
        <Center key={n} bg="brand-subtle" p="4" rounded="lg">
          <Text size="sm">{n}</Text>
        </Center>
      ))}
    </Grid>
  );
}
```

## Import

```tsx
import { Grid } from "astralis-ui";
// Grid.Item is available on the component itself
```

## Spanning

`Grid.Item` places children explicitly: `colSpan`/`rowSpan` for size,
`colStart`/`rowStart` for position, the dashboard staples.

```tsx
"use client";

import { Grid, Center, Text } from "astralis-ui";

export function GridSpan() {
  return (
    <Grid columns="4" rows="2" gap="3" w="full" maxW="md">
      <Grid.Item colSpan="2" rowSpan="2">
        <Center bg="orange" rounded="lg" size="full" minH="24">
          <Text size="sm" color="inverted">2 × 2</Text>
        </Center>
      </Grid.Item>
      <Grid.Item colSpan="2">
        <Center bg="orange-muted" rounded="lg" p="4">
          <Text size="sm">2 × 1</Text>
        </Center>
      </Grid.Item>
      <Center bg="orange-subtle" rounded="lg" p="4">
        <Text size="sm">1</Text>
      </Center>
      <Center bg="orange-subtle" rounded="lg" p="4">
        <Text size="sm">1</Text>
      </Center>
    </Grid>
  );
}
```

## Responsive columns

`columns` (like every layout prop) accepts a breakpoint map, the standard
card-grid recipe.

```tsx
import { Grid, Center, Text } from "astralis-ui";

export function GridResponsive() {
  return (
    /* 1 column on mobile, 2 from md, 3 from lg. */
    <Grid columns={{ base: "1", md: "2", lg: "3" }} gap="3" w="full" maxW="md">
      {["Mercury", "Venus", "Earth", "Mars", "Jupiter", "Saturn"].map((planet) => (
        <Center key={planet} bg="blue-subtle" p="4" rounded="lg">
          <Text size="sm">{planet}</Text>
        </Center>
      ))}
    </Grid>
  );
}
```

## Named template areas

For genuinely custom layouts, `templateAreas`, `templateColumns` and
`templateRows` accept raw CSS strings (applied as inline styles), and
`Grid.Item area` snaps children to the named cells.

```tsx
"use client";

import { Grid, Center, Text } from "astralis-ui";

export function GridTemplate() {
  return (
    /* templateAreas + Grid.Item area: the escape hatch for named layouts. */
    <Grid
      templateAreas={`"header header" "sidebar main" "footer footer"`}
      templateColumns="8rem 1fr"
      gap="3"
      w="full"
      maxW="md"
    >
      <Grid.Item area="header">
        <Center bg="green" p="3" rounded="lg">
          <Text size="xs" color="inverted">header</Text>
        </Center>
      </Grid.Item>
      <Grid.Item area="sidebar">
        <Center bg="green-muted" p="3" rounded="lg" size="full" minH="20">
          <Text size="xs">sidebar</Text>
        </Center>
      </Grid.Item>
      <Grid.Item area="main">
        <Center bg="green-subtle" p="3" rounded="lg" size="full">
          <Text size="xs">main</Text>
        </Center>
      </Grid.Item>
      <Grid.Item area="footer">
        <Center bg="green-muted" p="3" rounded="lg">
          <Text size="xs">footer</Text>
        </Center>
      </Grid.Item>
    </Grid>
  );
}
```

## Props

Grid extends [Box](/docs/components/box), so every style prop works here too.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | "1" – "12" \| "none" | None | Number of equal columns. |
| `rows` | "1" – "6" \| "none" | None | Number of equal rows. |
| `gap · rowGap · columnGap` | "0" – "96" (spacing scale) | None | Track gaps, together or per axis. |
| `flow` | "row" \| "col" \| "dense" \| "col-dense" | `"row"` | Auto-placement direction. |
| `autoColumns · autoRows` | "auto" \| "min" \| "max" \| "fr" | None | Sizing for implicitly created tracks. |
| `justifyItems · alignItems · placeItems` | "start" \| "center" \| "end" \| "stretch" (+ "baseline" for alignItems) | None | Item alignment within their cells. |
| `justifyContent · alignContent · placeContent` | "start" \| "center" \| "end" \| "between" \| "around" \| "evenly" \| "stretch" | None | Track alignment within the container. |
| `templateColumns · templateRows · templateAreas` | string | None | Escape hatches: arbitrary track/area templates, applied as inline styles. |

### Grid.Item

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `colSpan · rowSpan` | "1" – "12" \| "full" | None | How many tracks the item spans. |
| `colStart/colEnd · rowStart/rowEnd` | "1" – "13" \| "auto" | None | Explicit grid-line placement. |
| `area` | string | None | Named area matching the container's templateAreas. |
| `order` | "1" – "12" \| "first" \| "last" \| "none" | None | Visual order, independent of source order. |
| `alignSelf · justifySelf · placeSelf` | "auto" \| "start" \| "end" \| "center" \| "stretch" | None | Per-item alignment override. |

---

<!-- Layout / Center: /docs/components/center -->

# Center

A [Box](/docs/components/box) that centers its children on both axes.

```tsx
import { Center, Text } from "astralis-ui";

export function CenterDemo() {
  return (
    <Center bg="brand-subtle" w="full" maxW="sm" h="32" rounded="xl">
      <Text size="sm">Perfectly centered, both axes</Text>
    </Center>
  );
}
```

## Import

```tsx
import { Center } from "astralis-ui";
```

## Usage

Center is `display: flex; align-items: center; justify-content: center` as a
component, no props to remember. Give it a size and it becomes the standard
recipe for icon chips, avatars and count badges.

```tsx
"use client";

import { Center, Icon, HStack, Text } from "astralis-ui";
import { Star, Bell, Rocket } from "lucide-react";

export function CenterBadges() {
  return (
    /* The classic Center use: fixed-size icon chips. */
    <HStack gap="4">
      <Center size="12" bg="yellow-subtle" rounded="full">
        <Icon as={Star} size="sm" />
      </Center>
      <Center size="12" bg="red-subtle" rounded="xl">
        <Icon as={Bell} size="sm" />
      </Center>
      <Center size="12" bg="purple" rounded="lg">
        <Icon as={Rocket} size="sm" color="inverted" />
      </Center>
      <Center px="3" h="8" bg="subtle" rounded="full">
        <Text size="xs">42 stars</Text>
      </Center>
    </HStack>
  );
}
```

## Props

Center adds no props of its own: it accepts everything
[Box](/docs/components/box) does (`size`, `bg`, `rounded`, `as`, …).

---

<!-- Layout / Container: /docs/components/container -->

# Container

A centered, max-width wrapper for page and section content.

```tsx
import { Container, Box, Text } from "astralis-ui";

export function ContainerDemo() {
  return (
    <Box bg="subtle" w="full" py="6" rounded="xl">
      <Container maxW="md" bg="subtle" py="5" rounded="lg" border="normal" borderColor="base">
        <Text size="sm" weight="semibold">Centered content</Text>
        <Text size="sm" color="muted">
          A Container caps its width, centers itself with auto margins, and
          keeps gutter padding on small screens.
        </Text>
      </Container>
    </Box>
  );
}
```

## Import

```tsx
import { Container } from "astralis-ui";
```

## Sizes

`maxW` takes the sizing scale. Pick per context: `xs`–`sm` for forms and
prose, `5xl` (the default) for typical pages, larger for dashboards.

```tsx
import { Container, Text, VStack } from "astralis-ui";

const sizes = ["xs", "md", "2xl"] as const;

export function ContainerSizes() {
  return (
    <VStack gap="3" w="full" alignItems="stretch">
      {sizes.map((size) => (
        <Container key={size} maxW={size} bg="teal-subtle" py="3" rounded="lg">
          <Text size="xs">maxW=&quot;{size}&quot;</Text>
        </Container>
      ))}
    </VStack>
  );
}
```

## Props

Container extends [Box](/docs/components/box); its three own props just set
sensible page-wrapper defaults (`w="full"`, auto inline margins).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `maxW` | "xs" – "8xl" \| any Box width token | `"5xl"` | Width cap; the container centers itself with auto inline margins. |
| `px` | "0" – "96" (spacing scale) | `"4"` | Gutter padding so content never touches the viewport edge. |
| `centerContent` | boolean | `false` | Also stacks and centers the children themselves (flex column, centered). |

---

<!-- Layout / Aspect Ratio: /docs/components/aspect-ratio -->

# Aspect Ratio

Locks its child to a fixed aspect ratio, for media, embeds and placeholders.

```tsx
import { AspectRatio, Box, Image } from "astralis-ui";

export function AspectRatioDemo() {
  return (
    <Box w="full" maxW="sm">
      <AspectRatio ratio="wide" rounded="xl" overflow="hidden">
        {/* The single child stretches to fill the frame; img/video get object-cover. */}
        <Image src="/placeholder.svg" alt="A starfield gradient" />
      </AspectRatio>
    </Box>
  );
}
```

## Import

```tsx
import { AspectRatio } from "astralis-ui";
```

## Usage

The single child is absolutely positioned to fill the frame; images and
videos are `object-cover` by default, so any source fills the ratio without
distortion. The frame clips overflow. Pair with `rounded` for media cards.

## Ratios

Named ratios instead of magic numbers: `square` (1:1), `landscape` (4:3),
`portrait` (3:4), `wide` (16:9, the default), `ultrawide` (21:9), `golden`
(1.618:1), and `auto`.

```tsx
import { AspectRatio, Center, Text, Grid, VStack } from "astralis-ui";

const ratios = ["square", "landscape", "portrait", "wide", "golden"] as const;

export function AspectRatioRatios() {
  return (
    <Grid columns={{ base: "2", md: "3" }} gap="4" w="full" maxW="md" alignItems="end">
      {ratios.map((ratio) => (
        <VStack key={ratio} gap="1" alignItems="stretch">
          <Text as="span" size="xs" color="muted">{ratio}</Text>
          <AspectRatio ratio={ratio} rounded="lg" overflow="hidden">
            <Center bg="pink-subtle">
              <Text size="xs" color="muted">{ratio}</Text>
            </Center>
          </AspectRatio>
        </VStack>
      ))}
    </Grid>
  );
}
```

## Props

Aspect Ratio extends [Box](/docs/components/box) and adds one prop:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ratio` | "auto" \| "square" \| "landscape" \| "portrait" \| "wide" \| "ultrawide" \| "golden" | `"wide"` | The frame's width-to-height ratio. Responsive. |

---

<!-- Layout / Float: /docs/components/float -->

# Float

Anchors content to an edge or corner of its positioned parent: badges, dots, close buttons.

```tsx
import { Float, Center, Box, Text } from "astralis-ui";

export function FloatDemo() {
  return (
    /* Float anchors to the nearest positioned ancestor. */
    <Box position="relative" bg="subtle" p="6" rounded="xl" border="normal" borderColor="base" maxW="3xs">
      <Text size="sm" weight="semibold">Inbox</Text>
      <Text size="xs" color="muted">3 unread messages</Text>
      <Float placement="top-end">
        <Center bg="red" size="6" rounded="full">
          <Text size="xs" color="inverted">3</Text>
        </Center>
      </Float>
    </Box>
  );
}
```

## Import

```tsx
import { Float } from "astralis-ui";
```

## Usage

Float is absolutely positioned, so its parent needs `position="relative"`
(one Box prop away). The floated element is translated 50% past the anchor
point so it **centers on** the edge: the badge-on-a-corner look, no manual
offset math.

## Placements

Nine anchors: three per row across `top`, `middle` and `bottom`.

```tsx
import { Float, Box, Center, Text } from "astralis-ui";

const placements = [
  "top-start", "top-center", "top-end",
  "middle-start", "middle-center", "middle-end",
  "bottom-start", "bottom-center", "bottom-end",
] as const;

export function FloatPlacements() {
  return (
    <Box position="relative" bg="subtle" w="full" maxW="sm" h="40" rounded="xl">
      {placements.map((placement) => (
        <Float key={placement} placement={placement}>
          <Center bg="brand" px="2" h="5" rounded="full">
            <Text size="xs" color="inverted">{placement}</Text>
          </Center>
        </Float>
      ))}
    </Box>
  );
}
```

## Props

Float extends [Box](/docs/components/box) and adds one prop:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `placement` | "top-start" \| "top-center" \| "top-end" \| "middle-start" \| "middle-center" \| "middle-end" \| "bottom-start" \| "bottom-center" \| "bottom-end" | `"top-end"` | The edge or corner of the positioned parent to anchor to. Responsive. |

---

<!-- Layout / Separator: /docs/components/separator -->

# Separator

A dividing line between content: horizontal or vertical, with semantic role built in.

```tsx
import { Separator, Text, VStack } from "astralis-ui";

export function SeparatorDemo() {
  return (
    <VStack gap="3" alignItems="stretch" w="full" maxW="sm">
      <Text size="sm" weight="semibold">Astralis UI</Text>
      <Separator />
      <Text size="sm" color="muted">
        A dividing line with the separator role built in: horizontal by
        default, one prop to go vertical.
      </Text>
    </VStack>
  );
}
```

## Import

```tsx
import { Separator } from "astralis-ui";
```

## Vertical

`orientation="vertical"` flips it; it stretches to its container's cross
axis, so give the row a height (or let alignment do it).

```tsx
import { Separator, Text, HStack } from "astralis-ui";

export function SeparatorVertical() {
  return (
    <HStack gap="4" h="6">
      <Text size="sm">Docs</Text>
      <Separator orientation="vertical" />
      <Text size="sm">Components</Text>
      <Separator orientation="vertical" />
      <Text size="sm">Changelog</Text>
    </HStack>
  );
}
```

## Variants

Line style via `variant`; color and thickness come from the Box border props.

```tsx
import { Separator, Text, VStack } from "astralis-ui";

export function SeparatorVariants() {
  return (
    <VStack gap="5" alignItems="stretch" w="full" maxW="sm">
      <VStack gap="1" alignItems="stretch">
        <Text as="span" size="xs" color="muted">solid</Text>
        <Separator variant="solid" />
      </VStack>
      <VStack gap="1" alignItems="stretch">
        <Text as="span" size="xs" color="muted">dashed</Text>
        <Separator variant="dashed" />
      </VStack>
      <VStack gap="1" alignItems="stretch">
        <Text as="span" size="xs" color="muted">dotted</Text>
        <Separator variant="dotted" />
      </VStack>
      <VStack gap="1" alignItems="stretch">
        <Text as="span" size="xs" color="muted">colored via borderColor</Text>
        <Separator borderColor="brand" border="moderate" />
      </VStack>
    </VStack>
  );
}
```

## Props

Separator extends [Box](/docs/components/box). Use `borderColor` / `border`
to restyle the line.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | "horizontal" \| "vertical" | `"horizontal"` | Line direction; also sets `aria-orientation`. |
| `variant` | "solid" \| "dashed" \| "dotted" | `"solid"` | Line style. |

## Accessibility

Renders with `role="separator"` and the matching `aria-orientation`, so
screen readers announce the division without any extra work.

---

<!-- Layout / Visually Hidden: /docs/components/visually-hidden -->

# Visually Hidden

Renders content for assistive technology only: visually removed from the
page, still present in the accessibility tree. The standard companion for
icon-only buttons, table-header context and skip-link patterns. Zero client
JavaScript: it is a single styled `<span>`.

```tsx
import { Button, VisuallyHidden } from "astralis-ui";
import { Settings } from "lucide-react";

// The icon is decorative; the VisuallyHidden text is the button's real name,
// visible to screen readers, invisible on screen.
export function VisuallyHiddenDemo() {
  return (
    <Button variant="outline" colorScheme="gray">
      <Settings size={16} aria-hidden="true" />
      <VisuallyHidden>Open settings</VisuallyHidden>
    </Button>
  );
}
```

## Import

```tsx
import { VisuallyHidden } from "astralis-ui";
```

## When to use it

- An icon-only control whose meaning sighted users infer from the glyph:
  the hidden text becomes the accessible name.
- Extra context that would be visual noise on screen but matters when
  linearised ("opens in a new tab", column units in dense tables).

Prefer `aria-label` when the target element accepts one; `VisuallyHidden`
wins when the name should be part of the content (translated with the page,
findable by tests, composed of markup).

## Props

Extends `span` props. There is nothing else. The styling is the `sr-only`
clip pattern.

---

<!-- Layout / Scroll Area: /docs/components/scroll-area -->

# Scroll Area

A scroll container with scrollbars that match the theme. The scrollbars are
the **platform's own**, restyled with CSS (`::-webkit-scrollbar` +
`scrollbar-width`/`scrollbar-color`): no JavaScript thumb, no
ResizeObserver, no synthetic scrolling. Keyboard scrolling, momentum and RTL
stay native, and the component ships **zero client JavaScript**.

```tsx
import { ScrollArea, Box, Text, VStack } from "astralis-ui";

// No "use client": the scrollbars are the platform's own, restyled with CSS.
export function ScrollAreaDemo() {
  return (
    <ScrollArea style={{ width: "18rem", height: "12rem" }}>
      <VStack gap="0" alignItems="stretch">
        {Array.from({ length: 20 }, (_, i) => (
          <Box key={i} px="3" py="2" bg={i % 2 ? undefined : "subtle"}>
            <Text size="sm">Release note {String(i + 1).padStart(2, "0")}</Text>
          </Box>
        ))}
      </VStack>
    </ScrollArea>
  );
}
```

## Import

```tsx
import { ScrollArea } from "astralis-ui";
```

## Sizing

Give it a `height` or `maxHeight` through `style`. Without one the area grows
with its content and there is nothing to scroll.

## Props

Extends `div` props:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `direction` | "vertical" \| "horizontal" \| "both" | `"vertical"` | Which axis scrolls. |
| `hideScrollbar` | boolean | `false` | Hides the bar entirely; the content still scrolls. |

---

<!-- Layout / Splitter: /docs/components/splitter -->

# Splitter

A two-panel split with a draggable divider. The handle is a real
`role="separator"` with the APG window-splitter keyboard contract (arrows
step the split, Home/End jump to the limits), and dragging uses pointer
capture, so fast drags never lose the handle.

```tsx
import { Splitter, Box, Center, Text } from "astralis-ui";

export function SplitterDemo() {
  return (
    <Box w="full" h="40" border="normal" borderColor="base" rounded="lg" overflow="hidden">
      <Splitter defaultSize={35} minSize={20} maxSize={80} style={{ height: "100%" }}>
        <Splitter.Panel>
          <Center h="full" bg="subtle">
            <Text size="sm" color="muted">Sidebar</Text>
          </Center>
        </Splitter.Panel>
        <Splitter.Handle aria-label="Resize sidebar" />
        <Splitter.Panel>
          <Center h="full">
            <Text size="sm" color="muted">Content: drag the divider, or focus it and use arrow keys</Text>
          </Center>
        </Splitter.Panel>
      </Splitter>
    </Box>
  );
}
```

## Import

```tsx
import { Splitter } from "astralis-ui";
```

## How sizing works

The first panel's share rides a CSS variable on the root; panels are
addressed by DOM order (`Panel / Handle / Panel`), so there is no
registration protocol. The second panel takes the rest.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | "horizontal" \| "vertical" | `"horizontal"` | Split axis. horizontal puts the panels side by side. |
| `size · defaultSize · onResize` | number · number · (size: number) => void | `None · 50 · None` | Controlled / initial share of the first panel, in percent, and the change callback. |
| `minSize` | number | `10` | Smallest share the first panel can shrink to, in percent. |
| `maxSize` | number | `90` | Largest share the first panel can grow to, in percent. |

### Parts

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Splitter.Panel` | div props | None | One of the two panes, addressed by DOM order. The second takes the remaining space. |
| `Splitter.Handle` | div props | None | The draggable divider between the panels. Give it an aria-label. |

## Keyboard

The handle is a single tab stop. With it focused:

| Key | Action |
| --- | --- |
| `←` / `→` | Shrink / grow the first panel by 2% (horizontal) |
| `↑` / `↓` | Shrink / grow the first panel by 2% (vertical) |
| `Home` | Shrink the first panel to `minSize` |
| `End` | Grow the first panel to `maxSize` |

## Accessibility

The handle renders `role="separator"` with `aria-valuenow`, `aria-valuemin`
and `aria-valuemax`, so assistive technology announces the split as a
percentage. Label it with `aria-label` ("Resize sidebar").

---

<!-- Typography / Text: /docs/components/text -->

# Text

The prose primitive: size, weight, color and rhythm as typed tokens, all responsive.

```tsx
import { Text, VStack } from "astralis-ui";

export function TextDemo() {
  return (
    <VStack gap="1" maxW="md">
      <Text size="lg" weight="semibold">
        Typography that stays on scale
      </Text>
      <Text color="muted">
        Text is the prose primitive: size, weight, color and spacing come
        from the token scale, and every prop takes a responsive map.
      </Text>
      <Text size="sm" color="subtle" fontStyle="italic">
        Last updated three minutes ago
      </Text>
    </VStack>
  );
}
```

## Import

```tsx
import { Text } from "astralis-ui";
```

## Sizes

Thirteen steps from `xs` to `9xl`; the first eight cover almost all prose.

```tsx
import { Text, VStack } from "astralis-ui";

const sizes = ["xs", "sm", "md", "lg", "xl", "2xl", "3xl", "4xl"] as const;

export function TextSizes() {
  return (
    <VStack gap="2" alignItems="start">
      {sizes.map((size) => (
        <Text key={size} size={size}>
          The quick brown fox ({size})
        </Text>
      ))}
    </VStack>
  );
}
```

## Weights

```tsx
import { Text, VStack } from "astralis-ui";

const weights = ["light", "normal", "medium", "semibold", "bold", "extrabold"] as const;

export function TextWeights() {
  return (
    <VStack gap="1" alignItems="start">
      {weights.map((weight) => (
        <Text key={weight} weight={weight}>
          Weight {weight}
        </Text>
      ))}
    </VStack>
  );
}
```

## Truncation

`truncate` for one-line ellipsis, `lineClamp` for multi-line, no CSS needed
on your side.

```tsx
import { Text, VStack, Box } from "astralis-ui";

const long =
  "Space is big. You just won't believe how vastly, hugely, mind-bogglingly big it is. You may think it's a long way down the road to the chemist's, but that's just peanuts to space.";

export function TextTruncation() {
  return (
    <VStack gap="4" alignItems="stretch" w="full" maxW="xs">
      <Box>
        <Text size="xs" color="subtle" gutterBottom>truncate: one line, ellipsis</Text>
        <Text size="sm" truncate>{long}</Text>
      </Box>
      <Box>
        <Text size="xs" color="subtle" gutterBottom>lineClamp=&quot;3&quot;</Text>
        <Text size="sm" lineClamp="3">{long}</Text>
      </Box>
    </VStack>
  );
}
```

## Styling

Casing, tracking, decoration, family and the status colors compose freely.

```tsx
import { Text, VStack } from "astralis-ui";

export function TextStyling() {
  return (
    <VStack gap="2" alignItems="start">
      <Text casing="uppercase" letterSpacing="widest" size="xs" weight="medium" color="muted">
        Overline label
      </Text>
      <Text textDecoration="underline">Underlined for emphasis</Text>
      <Text textDecoration="line-through" color="subtle">
        Crossed off the list
      </Text>
      <Text fontFamily="mono" size="sm">
        fontFamily=&quot;mono&quot; without reaching for Code
      </Text>
      <Text color="success" weight="medium">
        Status colors come from the same token map
      </Text>
    </VStack>
  );
}
```

## Responsive

Every prop on this page accepts a breakpoint map:

```tsx
<Text size={{ base: "sm", md: "md", lg: "lg" }} align={{ base: "center", md: "left" }}>
  Scales with the viewport
</Text>
```

## Props

Text renders a `p` by default and forwards all standard HTML props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | "xs" – "9xl" (type scale) | `"md"` | Font size token. |
| `weight` | "thin" \| "extralight" \| "light" \| "normal" \| "medium" \| "semibold" \| "bold" \| "extrabold" \| "black" | None | Font weight token. |
| `color` | "base" \| "muted" \| "subtle" \| "inverted" \| status tokens \| palette shades | `"base"` | Text color from semantic roles or raw palette shades. |
| `align` | "left" \| "center" \| "right" \| "justify" | None | Text alignment. |
| `casing` | "uppercase" \| "lowercase" \| "capitalize" \| "normal" | None | Text transform. |
| `lineHeight` | "none" \| "tight" \| "snug" \| "normal" \| "relaxed" \| "loose" | None | Leading token. |
| `letterSpacing` | "tighter" \| "tight" \| "normal" \| "wide" \| "wider" \| "widest" | None | Tracking token. |
| `fontFamily` | "heading" \| "body" \| "sans" \| "serif" \| "mono" | None | Font family token. |
| `fontStyle · textDecoration` | "italic" · "underline" \| "line-through" \| "overline" \| "none" | None | Style and decoration. |
| `truncate` | boolean | `false` | Single-line ellipsis overflow. |
| `lineClamp` | "1" – "6" | None | Multi-line clamp with ellipsis (ignored when truncate is set). |
| `gutterBottom · paragraph` | boolean | `false` | Rhythm helpers: small / paragraph-sized bottom margin (paragraph also forces a <p>). |
| `as` | ElementType | `"p"` | Rendered element: span, label, figcaption, … |

---

<!-- Typography / Heading: /docs/components/heading -->

# Heading

Semantic headings built on [Text](/docs/components/text), with per-level size and weight defaults.

```tsx
import { Heading, VStack } from "astralis-ui";

const levels = ["h1", "h2", "h3", "h4", "h5", "h6"] as const;

export function HeadingDemo() {
  return (
    <VStack gap="2" alignItems="start">
      {levels.map((level) => (
        <Heading key={level} as={level}>
          Heading {level}
        </Heading>
      ))}
    </VStack>
  );
}
```

## Import

```tsx
import { Heading } from "astralis-ui";
```

## Usage

`as` picks the heading level (`h1`–`h6`, default `h2`) and brings a matching
default size (`4xl` → `md`) and weight (bold for h1–h3, semibold below).
Heading also presets the `heading` font family, tight leading and tight
tracking. Override any of it with the regular Text props.

## Decoupling size from level

Heading levels are for the document outline; size is for the design. Override
`size` freely without breaking semantics or accessibility.

```tsx
import { Heading, Text, VStack } from "astralis-ui";

export function HeadingSizeOverride() {
  return (
    /* Semantics and visuals are independent: pick the level for the
       document outline, the size for the design. */
    <VStack gap="1" alignItems="start">
      <Heading as="h2" size="6xl" letterSpacing="tighter">
        Visually huge
      </Heading>
      <Text color="muted" size="sm">
        …but still an h2 in the document outline.
      </Text>
    </VStack>
  );
}
```

## Props

Heading accepts every [Text](/docs/components/text) prop except `paragraph`,
plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | "h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" | `"h2"` | Heading level; sets the default size and weight. |
| `size` | Text sizes | `per level` | `h1` → `4xl`, `h2` → `3xl`, `h3` → `2xl`, `h4` → `xl`, `h5` → `lg`, `h6` → `md`. |
| `weight` | Text weights | `per level` | Bold for h1–h3, semibold for h4–h6. |

---

<!-- Typography / Blockquote: /docs/components/blockquote -->

# Blockquote

A quotation block with an accent rule and optional attribution.

```tsx
import { Blockquote } from "astralis-ui";

export function BlockquoteDemo() {
  return (
    <Blockquote cite="Carl Sagan, Cosmos" maxW="md">
      The cosmos is within us. We are made of star-stuff. We are a way for the
      universe to know itself.
    </Blockquote>
  );
}
```

## Import

```tsx
import { Blockquote } from "astralis-ui";
```

## Variants

`plain` is just the leading rule; `subtle` adds a tinted panel. The rule
recolors via the `borderColor` Box prop.

```tsx
import { Blockquote, VStack } from "astralis-ui";

export function BlockquoteVariants() {
  return (
    <VStack gap="5" alignItems="stretch" w="full" maxW="md">
      <Blockquote variant="plain">
        plain: a leading rule and nothing else.
      </Blockquote>
      <Blockquote variant="subtle">
        subtle: the rule plus a tinted panel behind the quote.
      </Blockquote>
      <Blockquote variant="subtle" borderColor="brand">
        The rule color is just a Box prop. Recolor it with borderColor.
      </Blockquote>
    </VStack>
  );
}
```

## Attribution

`cite` renders a visible attribution line (an actual `<cite>` element);
`citeUrl` sets the semantic `cite` attribute for machines:

```tsx
<Blockquote cite="Carl Sagan, Cosmos" citeUrl="https://en.wikipedia.org/wiki/Cosmos_(Sagan_book)">
  The cosmos is within us.
</Blockquote>
```

## Props

Blockquote extends [Box](/docs/components/box):

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | "plain" \| "subtle" | `"plain"` | The leading rule alone, or the rule on a tinted panel. Responsive. |
| `cite` | ReactNode | None | Visible attribution, rendered under the quote in a cite element. |
| `citeUrl` | string | None | URL of the source, set as the blockquote element's native cite attribute. |

---

<!-- Typography / Code: /docs/components/code -->

# Code

An inline code chip for identifiers and commands in prose.

```tsx
import { Code, Text, Box } from "astralis-ui";

export function CodeDemo() {
  return (
    <Box maxW="md">
      <Text>
        Install with <Code>pnpm add astralis-ui</Code>, import the stylesheet
        once, and wrap your app in <Code>AstralisProvider</Code>.
      </Text>
    </Box>
  );
}
```

## Import

```tsx
import { Code } from "astralis-ui";
```

## Variants and sizes

```tsx
import { Code, HStack, VStack, Text } from "astralis-ui";

export function CodeVariants() {
  return (
    <VStack gap="5" alignItems="start">
      <VStack gap="1" alignItems="start">
        <Text as="span" size="xs" color="subtle">variants</Text>
        <HStack gap="3">
          <Code variant="subtle">subtle</Code>
          <Code variant="solid">solid</Code>
          <Code variant="outline">outline</Code>
        </HStack>
      </VStack>
      <VStack gap="1" alignItems="start">
        <Text as="span" size="xs" color="subtle">sizes</Text>
        <HStack gap="3" alignItems="center">
          <Code size="sm">size sm</Code>
          <Code size="md">size md</Code>
          <Code size="lg">size lg</Code>
        </HStack>
      </VStack>
    </VStack>
  );
}
```

For multi-line snippets, use [Code Block](/docs/components/code-block).

## Props

Code extends [Box](/docs/components/box).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | "subtle" \| "solid" \| "outline" | `"subtle"` | Tinted, strongly tinted, or bordered. All track the active theme. |
| `size` | "sm" \| "md" \| "lg" | `"sm"` | Font size step. |

---

<!-- Typography / Code Block: /docs/components/code-block -->

# Code Block

A compound multi-line code container with header, copy button and editor chrome.

```tsx
"use client";

import { Box, CodeBlock } from "astralis-ui";

const example = `import { AstralisProvider } from "astralis-ui";
import "astralis-ui/styles.css";

export function App({ children }) {
  return <AstralisProvider>{children}</AstralisProvider>;
}`;

export function CodeBlockDemo() {
  return (
    <Box w="full">
      <CodeBlock.Root variant="solid" code={example}>
        <CodeBlock.Header>
          <CodeBlock.WindowControls />
          <CodeBlock.Title>App.tsx</CodeBlock.Title>
          <CodeBlock.Control>
            <CodeBlock.CopyTrigger />
          </CodeBlock.Control>
        </CodeBlock.Header>
        <CodeBlock.Content>
          <CodeBlock.Code />
        </CodeBlock.Content>
      </CodeBlock.Root>
    </Box>
  );
}
```

## Import

```tsx
import { CodeBlock } from "astralis-ui";
// CodeBlock.Root, .Header, .Title, .Control, .CopyTrigger,
// .WindowControls, .Content, .Code
```

## Anatomy

`Root` holds the source string via `code` and hands it to its parts during
server render: `Code` renders it when given no children, and `CopyTrigger`,
the compound's only client part, copies the rendered code to the clipboard. `Header` is an optional top row for `Title`,
`WindowControls` (the macOS traffic lights) and a trailing `Control` slot;
`Content` is the scrollable `<pre>` wrapping `Code`.

```tsx
<CodeBlock.Root variant="solid" code={source}>
  <CodeBlock.Header>
    <CodeBlock.WindowControls />
    <CodeBlock.Title>App.tsx</CodeBlock.Title>
    <CodeBlock.Control>
      <CodeBlock.CopyTrigger />
    </CodeBlock.Control>
  </CodeBlock.Header>
  <CodeBlock.Content>
    <CodeBlock.Code />
  </CodeBlock.Content>
</CodeBlock.Root>
```

## Variants

The same three-variant family as [Code](/docs/components/code); `solid` is
the strongest surface: it tracks the active theme (dark block in dark mode,
light in light) and pairs well with `WindowControls`.

```tsx
"use client";

import { CodeBlock, VStack } from "astralis-ui";

const variants = ["subtle", "outline", "solid"] as const;

export function CodeBlockVariants() {
  return (
    <VStack gap="4" alignItems="stretch" w="full" maxW="md">
      {variants.map((variant) => (
        <CodeBlock.Root key={variant} variant={variant} size="sm" code={`pnpm add astralis-ui  # ${variant}`}>
          <CodeBlock.Content>
            <CodeBlock.Code />
          </CodeBlock.Content>
        </CodeBlock.Root>
      ))}
    </VStack>
  );
}
```

## Syntax highlighting

Code Block renders plain text by itself: bring your own highlighter and pass
its output as `highlightedHtml` on `Code`. The blocks on this very site are
Shiki output rendered this way:

```tsx
import { codeToHtml } from "shiki";

const html = await codeToHtml(source, { lang: "tsx", theme: "github-dark" });

<CodeBlock.Root variant="solid" code={source}>
  <CodeBlock.Content>
    <CodeBlock.Code highlightedHtml={html} />
  </CodeBlock.Content>
</CodeBlock.Root>
```

Keep passing the raw string as `code` on `Root` so `CopyTrigger` copies the
unhighlighted source.

## Props

`CodeBlock.Root`:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | "subtle" \| "solid" \| "outline" | `"subtle"` | Container style. Every variant follows the active light or dark theme. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Font size and padding of the content. |
| `code` | string | None | The source. Code renders it when given no children, and CopyTrigger copies it. |

### Parts

Every part also takes its element's native attributes and `className`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `CodeBlock.Header` | div props | None | Optional top row for Title, WindowControls and a trailing Control slot. |
| `CodeBlock.Title` | span props | None | File name or caption in the header. |
| `CodeBlock.WindowControls` | span props | None | Three decorative window dots, hidden from assistive technology. |
| `CodeBlock.Control` | div props | None | Trailing header slot, usually holding the CopyTrigger. |
| `CodeBlock.CopyTrigger` | code?: string · children?: ReactNode \| ((copied: boolean) => ReactNode) | None | Copies the Root's code, or its own code override. A render function replaces the default copy and check glyphs. |
| `CodeBlock.Content` | pre props | None | The scrollable pre element that wraps Code. |
| `CodeBlock.Code` | highlightedHtml?: string | None | Renders the Root's code as plain text, or your highlighter's HTML when highlightedHtml is set. |

---

<!-- Typography / Highlight: /docs/components/highlight -->

# Highlight

Wraps matches of a query in styled `<mark>` elements: search-result emphasis in prose.

```tsx
import { Highlight, Text, Box } from "astralis-ui";

export function HighlightDemo() {
  return (
    <Box maxW="md">
      <Text>
        <Highlight query="semantic tokens">
          Astralis paints every component with semantic tokens, so one brand
          color and a dark-mode class restyle the whole library.
        </Highlight>
      </Text>
    </Box>
  );
}
```

## Import

```tsx
import { Highlight } from "astralis-ui";
```

## Usage

Give it a plain string as children plus a `query` (string or array), and each
match becomes a real `<mark>`: semantic emphasis that screen readers can
announce. Matching is case-insensitive by default.

```tsx
import { Highlight, Text, VStack } from "astralis-ui";

export function HighlightVariants() {
  return (
    <VStack gap="3" alignItems="start" maxW="md">
      <Text>
        <Highlight query={["planets", "moons"]}>
          Multiple queries: eight planets, hundreds of moons.
        </Highlight>
      </Text>
      <Text>
        <Highlight query="solid" variant="solid">
          The solid variant fills the mark with the full yellow.
        </Highlight>
      </Text>
      <Text>
        <Highlight query="CASE" ignoreCase={false}>
          Set ignoreCase to false and only exact CASE matches (not case) light up.
        </Highlight>
      </Text>
    </VStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | string | None | The plain text to scan. Required. |
| `query` | string \| string[] | None | The substring or substrings to wrap in mark elements. Required. |
| `variant` | "subtle" \| "solid" | `"subtle"` | Tinted or fully filled marks. |
| `ignoreCase` | boolean | `true` | Match regardless of letter case. |
| `markClassName` | string | None | Extra class for each mark element. |

---

<!-- Typography / List: /docs/components/list -->

# List

Semantic lists with tokenized markers, rhythm, and per-item icons.

```tsx
"use client";

import { List } from "astralis-ui";

export function ListDemo() {
  return (
    <List>
      <List.Item>Semantic tokens over raw colors</List.Item>
      <List.Item>Responsive props on every primitive</List.Item>
      <List.Item>Precompiled CSS, no build step</List.Item>
    </List>
  );
}
```

## Import

```tsx
import { List } from "astralis-ui";
// List.Item is available on the component itself
```

## Marker styles

`styleType` covers bullets and numbering; pair the numbered ones with
`as="ol"` so the semantics match the visuals.

```tsx
"use client";

import { List, Text, Grid, VStack } from "astralis-ui";

const styleTypes = ["disc", "circle", "square", "decimal", "lower-alpha", "upper-roman"] as const;

export function ListStyleTypes() {
  return (
    <Grid columns={{ base: "2", md: "3" }} gap="6" w="full" maxW="md">
      {styleTypes.map((styleType) => (
        <VStack key={styleType} gap="1" alignItems="start">
          <Text as="span" size="xs" color="subtle">{styleType}</Text>
          {/* Ordered markers belong on an <ol>: as swaps the element. */}
          <List styleType={styleType} as={styleType === "disc" || styleType === "circle" || styleType === "square" ? "ul" : "ol"} spacing="1">
            <List.Item>One</List.Item>
            <List.Item>Two</List.Item>
            <List.Item>Three</List.Item>
          </List>
        </VStack>
      ))}
    </Grid>
  );
}
```

## Icon lists

`styleType="none"` plus a per-item `icon` replaces markers entirely, the
feature-list and changelog staple.

```tsx
"use client";

import { List, Icon } from "astralis-ui";
import { CircleCheck, CircleAlert, CircleX } from "lucide-react";

export function ListIcons() {
  return (
    /* styleType="none" + per-item icons: the changelog/feature-list recipe. */
    <List styleType="none" spacing="2.5">
      <List.Item icon={<Icon as={CircleCheck} size="sm" color="success" />}>
        Layout category fully documented
      </List.Item>
      <List.Item icon={<Icon as={CircleCheck} size="sm" color="success" />}>
        Typography in progress
      </List.Item>
      <List.Item icon={<Icon as={CircleAlert} size="sm" color="warning" />}>
        Overlay components waiting on rework
      </List.Item>
      <List.Item icon={<Icon as={CircleX} size="sm" color="error" />}>
        Time machine still not shipping
      </List.Item>
    </List>
  );
}
```

## Props

Both parts extend [Box](/docs/components/box).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `styleType` | "disc" \| "circle" \| "square" \| "decimal" \| "lower-alpha" \| "upper-roman" \| "none" | `"disc"` | Marker style; `none` removes marker and indent. |
| `spacing` | "0" \| "1" \| "1.5" \| "2" \| "2.5" \| "3" \| "4" \| "5" \| "6" \| "8" | `"2"` | Vertical rhythm between items. |
| `as` | ElementType | `"ul"` | Use `"ol"` for numbered lists. |

### List.Item

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | ReactNode | None | Leading icon. Replaces the native marker and aligns the content beside it. |
| `as` | ElementType | `"li"` | Element to render. |

---

<!-- Typography / Kbd: /docs/components/kbd -->

# Kbd

A keyboard-key cap for documenting shortcuts.

```tsx
import { HStack, Kbd, Text } from "astralis-ui";

export function KbdDemo() {
  return (
    <HStack gap="6" alignItems="center" wrap="wrap">
      <HStack gap="1" alignItems="center">
        <Kbd>⌘</Kbd>
        <Kbd>K</Kbd>
      </HStack>
      <HStack gap="1" alignItems="center">
        <Kbd>Ctrl</Kbd>
        <Text size="xs" color="subtle">+</Text>
        <Kbd>Shift</Kbd>
        <Text size="xs" color="subtle">+</Text>
        <Kbd>P</Kbd>
      </HStack>
      <HStack gap="1" alignItems="center">
        <Kbd size="sm">esc</Kbd>
        <Kbd size="md">tab</Kbd>
        <Kbd size="lg">enter</Kbd>
      </HStack>
    </HStack>
  );
}
```

## Import

```tsx
import { Kbd } from "astralis-ui";
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Cap size. |

Renders a semantic `<kbd>` element. Screen readers announce it as keyboard
input, and the mono font plus bottom-weighted border give it the keycap depth.

---

<!-- Typography / Link: /docs/components/link -->

# Link

An inline text link with accent-channel coloring and external-link handling.

```tsx
import { Link, Text, VStack } from "astralis-ui";

export function LinkDemo() {
  return (
    <VStack gap="2" alignItems="start">
      <Text>
        Read the <Link href="/docs">getting-started guide</Link> before launch.
      </Text>
      <Text>
        Always underlined: <Link href="/docs" variant="underline">theming reference</Link>.
      </Text>
      <Text>
        External: <Link href="https://react.dev" external>react.dev</Link> (new tab, safe rel).
      </Text>
      <Text>
        Any hue: <Link href="/docs" colorScheme="purple">purple link</Link>,{" "}
        <Link href="/docs" colorScheme="green">green link</Link>.
      </Text>
    </VStack>
  );
}
```

## Import

```tsx
import { Link } from "astralis-ui";
```

For client-side routing, pass your router's component:
`<Link as={NextLink} href="/docs">`.

## Line clamp

`lineClamp` cuts a long link off after that many lines with an ellipsis, which
keeps card titles and list rows even. The full text stays in the DOM, so screen
readers and search still get all of it.

```tsx
import { Box, Link } from "astralis-ui";

export function LinkLineClamp() {
  return (
    <Box maxW="xs">
      <Link href="/docs/theming" lineClamp="2" weight="medium">
        Theming Astralis for a brand that ships light and dark palettes, runtime accent
        colors and per-component overrides
      </Link>
    </Box>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | "underline" \| "hover" \| "plain" | `"hover"` | Underline behavior. |
| `colorScheme` | all 15 schemes | `"brand"` | Hue (via the accent channel). |
| `external` | boolean | `false` | New tab + `rel="noopener noreferrer"` + ↗ marker. |
| `lineClamp` | "1" \| "2" \| "3" \| "4" \| "5" \| "6" | None | Truncates a long link to this many lines with an ellipsis. Responsive. |
| `as` | ElementType | `"a"` | Router link component. |

A link is text with special highlighting, so it also takes every
[Text](/docs/components/text) typography prop (`size`, `weight`, `color`,
`casing`, `align`, `lineHeight`, `letterSpacing`), each responsive.

Unlike Text it defaults none of them. A bare `<Link>` emits no type classes at
all, so it inherits from the paragraph around it, which is what an inline link
should do:

```jsx
<Text size="sm">
  Small copy with an <Link href="#">inline link</Link> that stays small.
</Text>

<Link href="#" size="lg" weight="semibold">A large standalone link</Link>
```

Setting `color` explicitly holds it in **both** states: the hover colour shift
is dropped rather than swapping your colour out from under you, and `variant`'s
underline carries the affordance instead. That is what makes a link usable on a
surface the accent channel does not cover:

```jsx
<Box bg="inverted" p="6">
  <Link href="#" color="inverted" variant="hover">Readable on the inverted fill</Link>
</Box>
```

---

<!-- Disclosure / Accordion: /docs/components/accordion -->

# Accordion

Stacked sections that expand and collapse: single or multiple open, five visual variants.

```tsx
"use client";

import { Accordion, Box } from "astralis-ui";

export function AccordionDemo() {
  return (
    <Box w="full" maxW="md">
      <Accordion type="single" defaultValue="tokens" collapsible>
        <Accordion.Item value="tokens">
          <Accordion.Trigger>What are semantic tokens?</Accordion.Trigger>
          <Accordion.Content>
            Named colors like surface, label and stroke that resolve differently
            in light and dark mode. Components never reference raw hex values.
          </Accordion.Content>
        </Accordion.Item>
        <Accordion.Item value="build">
          <Accordion.Trigger>Do I need a build step?</Accordion.Trigger>
          <Accordion.Content>
            No. The library ships precompiled CSS: import one stylesheet and
            every component works.
          </Accordion.Content>
        </Accordion.Item>
        <Accordion.Item value="theming">
          <Accordion.Trigger>How does brand theming work?</Accordion.Trigger>
          <Accordion.Content>
            Pass a brand color to AstralisProvider and the full shade scale is
            generated at runtime.
          </Accordion.Content>
        </Accordion.Item>
      </Accordion>
    </Box>
  );
}
```

## Import

```tsx
import { Accordion } from "astralis-ui";
// Accordion.Item, Accordion.Trigger, Accordion.Content
```

## Anatomy

```tsx
<Accordion type="single" collapsible>
  <Accordion.Item value="unique-id">
    <Accordion.Trigger>Heading</Accordion.Trigger>
    <Accordion.Content>Body</Accordion.Content>
  </Accordion.Item>
</Accordion>
```

## Variants

```tsx
"use client";

import { Accordion, Text, VStack } from "astralis-ui";

const variants = ["enclosed", "outline", "separated", "subtle", "plain"] as const;

export function AccordionVariants() {
  return (
    <VStack gap="6" alignItems="stretch" w="full" maxW="md">
      {variants.map((variant) => (
        <VStack key={variant} gap="2" alignItems="stretch">
          <Text as="span" size="xs" weight="medium" color="muted">
            {variant}
          </Text>
          <Accordion variant={variant} type="single" defaultValue="one" collapsible>
            <Accordion.Item value="one">
              <Accordion.Trigger>First section</Accordion.Trigger>
              <Accordion.Content>Content of the first section.</Accordion.Content>
            </Accordion.Item>
            <Accordion.Item value="two">
              <Accordion.Trigger>Second section</Accordion.Trigger>
              <Accordion.Content>Content of the second section.</Accordion.Content>
            </Accordion.Item>
          </Accordion>
        </VStack>
      ))}
    </VStack>
  );
}
```

## Multiple open

`type="multiple"` lets any number of items stay open; `value`/`defaultValue`
become arrays.

```tsx
"use client";

import { Accordion, Box } from "astralis-ui";

export function AccordionMultiple() {
  return (
    <Box w="full" maxW="md">
      <Accordion type="multiple" defaultValue={["a", "b"]} variant="separated">
        <Accordion.Item value="a">
          <Accordion.Trigger>Open by default</Accordion.Trigger>
          <Accordion.Content>Several items can be open at once.</Accordion.Content>
        </Accordion.Item>
        <Accordion.Item value="b">
          <Accordion.Trigger>Also open by default</Accordion.Trigger>
          <Accordion.Content>defaultValue takes an array in multiple mode.</Accordion.Content>
        </Accordion.Item>
        <Accordion.Item value="c">
          <Accordion.Trigger>Closed until clicked</Accordion.Trigger>
          <Accordion.Content>Opening this one closes nothing else.</Accordion.Content>
        </Accordion.Item>
      </Accordion>
    </Box>
  );
}
```

## Controlled

Pass `value` + `onValueChange` to own the state, useful for "expand from
elsewhere" flows like deep links or wizards.

```tsx
"use client";

import { useState } from "react";
import { Accordion, Button, ButtonGroup, VStack } from "astralis-ui";

export function AccordionControlled() {
  const [open, setOpen] = useState<string | string[]>("shipping");

  return (
    <VStack gap="4" alignItems="stretch" w="full" maxW="md">
      <ButtonGroup size="sm" variant="outline" colorScheme="gray">
        <Button onClick={() => setOpen("shipping")}>Open shipping</Button>
        <Button onClick={() => setOpen("returns")}>Open returns</Button>
        <Button onClick={() => setOpen("")}>Close all</Button>
      </ButtonGroup>

      <Accordion type="single" collapsible value={open} onValueChange={setOpen}>
        <Accordion.Item value="shipping">
          <Accordion.Trigger>Shipping</Accordion.Trigger>
          <Accordion.Content>Ships worldwide within 3–5 days.</Accordion.Content>
        </Accordion.Item>
        <Accordion.Item value="returns">
          <Accordion.Trigger>Returns</Accordion.Trigger>
          <Accordion.Content>Free returns within 30 days.</Accordion.Content>
        </Accordion.Item>
      </Accordion>
    </VStack>
  );
}
```

## Custom indicator

Swap the chevron, move it to the leading edge, recolor with `colorScheme`,
or disable individual items.

```tsx
"use client";

import { Accordion, Icon, Box } from "astralis-ui";
import { Plus } from "lucide-react";

export function AccordionCustom() {
  return (
    <Box w="full" maxW="md">
      <Accordion
        variant="outline"
        colorScheme="purple"
        indicator={<Icon as={Plus} size="xs" />}
        indicatorPosition="start"
        type="single"
        collapsible
      >
        <Accordion.Item value="one">
          <Accordion.Trigger>Custom indicator, leading position</Accordion.Trigger>
          <Accordion.Content>
            The indicator rotates as the item opens; colorScheme drives the
            focus ring and accents.
          </Accordion.Content>
        </Accordion.Item>
        <Accordion.Item value="two" disabled>
          <Accordion.Trigger>A disabled item</Accordion.Trigger>
          <Accordion.Content>Unreachable.</Accordion.Content>
        </Accordion.Item>
      </Accordion>
    </Box>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | "single" \| "multiple" | `"single"` | One open item at a time, or any number. |
| `variant` | "enclosed" \| "outline" \| "separated" \| "subtle" \| "plain" | `"enclosed"` | Container styling family. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Trigger and content density. |
| `colorScheme` | all 15 schemes | `"gray"` | Accent hue for focus rings and highlights. |
| `value · defaultValue` | string \| string[] | None | Controlled / initial open item(s), an array in multiple mode. |
| `onValueChange` | (value: string \| string[]) => void | None | Fires with the next open value(s). |
| `collapsible` | boolean | `false` | In single mode, allows closing the open item. |
| `disabled` | boolean | `false` | Disables every item. |
| `keepMounted` | boolean | `false` | Render content in the DOM before first open (SEO / heavy content). |
| `indicator · indicatorPosition · hideIndicator` | ReactNode · "start" \| "end" · boolean | `chevron · "end" · false` | Customize or hide the rotating open indicator. |
| `headingLevel` | 1 – 6 | `3` | Heading level wrapping each trigger, for the document outline. |

### Accordion.Item

`Accordion.Trigger` and `Accordion.Content` take only `className` (Trigger
can also override `indicator`/`hideIndicator` per item).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | None | Required: identifies the item in value/defaultValue. |
| `disabled` | boolean | `false` | Disables just this item. |

## Keyboard

| Key | Action |
| --- | --- |
| `Enter` / `Space` | Toggle the focused trigger |
| `↓` / `↑` | Next / previous trigger (wraps) |
| `Home` / `End` | First / last trigger |

## Accessibility

- Triggers are real buttons wrapped in headings (`headingLevel`), with
  `aria-expanded` and `aria-controls`.
- Content regions use `role="region"` + `aria-labelledby`.

---

<!-- Disclosure / Carousel: /docs/components/carousel -->

# Carousel

A slide deck with swipe, keyboard nav, autoplay, fractional slides-per-view and fade mode.

```tsx
"use client";

import { Carousel, Center, Text, Box } from "astralis-ui";

const slides = [
  { label: "Slide one", bg: "brand-subtle" },
  { label: "Slide two", bg: "teal-subtle" },
  { label: "Slide three", bg: "purple-subtle" },
] as const;

export function CarouselDemo() {
  return (
    <Box w="full" maxW="md">
      <Carousel>
        <Carousel.Track>
          {slides.map((slide) => (
            <Carousel.Slide key={slide.label}>
              <Center bg={slide.bg} h="40" rounded="xl">
                <Text weight="medium">{slide.label}</Text>
              </Center>
            </Carousel.Slide>
          ))}
        </Carousel.Track>
        <Carousel.Control>
          <Carousel.Prev />
          <Carousel.Indicators />
          <Carousel.Next />
        </Carousel.Control>
      </Carousel>
    </Box>
  );
}
```

## Import

```tsx
import { Carousel } from "astralis-ui";
// Carousel.Track, .Slide, .Control, .Prev, .Next,
// .Indicators, .ProgressText, .AutoPlayTrigger
```

## Anatomy

The compound parts compose freely. Put controls above, below, or skip them:

```tsx
<Carousel loop>
  <Carousel.Track>
    <Carousel.Slide>…</Carousel.Slide>
  </Carousel.Track>
  <Carousel.Control>
    <Carousel.Prev />
    <Carousel.Indicators />
    <Carousel.Next />
  </Carousel.Control>
</Carousel>
```

## Autoplay

`autoPlay` advances on an interval and pauses on hover by default;
`AutoPlayTrigger` gives users a play/pause control and `ProgressText` a
screen-reader-friendly readout.

```tsx
"use client";

import { Carousel, Center, Text, Box } from "astralis-ui";

export function CarouselAutoplay() {
  return (
    <Box w="full" maxW="md">
      <Carousel autoPlay autoPlayInterval={2500} loop>
        <Carousel.Track>
          {["Aurora", "Nebula", "Quasar"].map((name) => (
            <Carousel.Slide key={name}>
              <Center bg="blue-subtle" h="32" rounded="xl">
                <Text weight="medium">{name}</Text>
              </Center>
            </Carousel.Slide>
          ))}
        </Carousel.Track>
        <Carousel.Control>
          <Carousel.AutoPlayTrigger />
          <Carousel.Indicators variant="line" />
          <Carousel.ProgressText />
        </Carousel.Control>
      </Carousel>
    </Box>
  );
}
```

## Multiple slides per view

Fractional `slidesPerView` peeks the next slide, the strongest "you can
swipe this" cue there is.

```tsx
"use client";

import { Carousel, Center, Text, Box } from "astralis-ui";

export function CarouselMulti() {
  return (
    <Box w="full" maxW="md">
      {/* Fractional slidesPerView peeks the next slide, a strong swipe cue. */}
      <Carousel slidesPerView={1.5} slideGap={12} loop>
        <Carousel.Track>
          {[1, 2, 3, 4, 5].map((n) => (
            <Carousel.Slide key={n}>
              <Center bg="green-subtle" h="28" rounded="xl">
                <Text weight="medium">{n}</Text>
              </Center>
            </Carousel.Slide>
          ))}
        </Carousel.Track>
        <Carousel.Control>
          <Carousel.Prev />
          <Carousel.Indicators variant="number" />
          <Carousel.Next />
        </Carousel.Control>
      </Carousel>
    </Box>
  );
}
```

## Fade

`animation="fade"` cross-fades in place instead of translating the track,
which is better for hero imagery.

```tsx
"use client";

import { Carousel, Center, Text, Box } from "astralis-ui";

export function CarouselFade() {
  return (
    <Box w="full" maxW="md">
      <Carousel animation="fade" speed={500} loop colorScheme="pink">
        <Carousel.Track>
          {["First", "Second", "Third"].map((label) => (
            <Carousel.Slide key={label}>
              <Center bg="pink-subtle" h="32" rounded="xl">
                <Text weight="medium">{label} slide</Text>
              </Center>
            </Carousel.Slide>
          ))}
        </Carousel.Track>
        <Carousel.Control>
          <Carousel.Prev />
          <Carousel.Indicators />
          <Carousel.Next />
        </Carousel.Control>
      </Carousel>
    </Box>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `index · defaultIndex · onIndexChange` | number · number · (index: number) => void | `None · 0 · None` | Controlled / initial slide, and the change callback. |
| `slidesPerView` | number | `1` | Visible slides; fractional values (1.5) peek the next slide. |
| `slidesToScroll` | number | `1` | Slides advanced per step. |
| `slideGap` | number | `0` | Pixel gap between slides. |
| `loop` | boolean | `false` | Wraps from the last slide back to the first. |
| `autoPlay · autoPlayInterval · pauseOnHover` | boolean · number · boolean | `false · 3000 · true` | Automatic advancing, its cadence, and hover pause. |
| `animation` | "slide" \| "fade" | `"slide"` | Translate the track, or cross-fade in place. |
| `orientation` | "horizontal" \| "vertical" | `"horizontal"` | Slide axis; keyboard arrows follow it. |
| `speed · easing` | number · string | `300 · "ease-out"` | Transition duration (ms) and CSS easing. |
| `disabled` | boolean | `false` | Freezes the carousel: slide changes, gestures and autoplay all stop. |
| `swipeable · draggable` | boolean | `true · false` | Touch swipe and mouse drag gestures. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Control and indicator sizing. |
| `colorScheme` | all 15 schemes | `"brand"` | Active indicator and focus-ring hue. |
| `beforeChange · afterChange` | (from, to) => void · (current) => void | None | Transition lifecycle hooks. |

### Parts

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Carousel.Track / Carousel.Slide` | children | None | The scroller and each slide (role=group with slide labels). |
| `Carousel.Prev / Carousel.Next` | icon?: ReactNode | None | Step buttons; default chevrons follow the orientation. |
| `Carousel.Indicators` | variant?: "dot" \| "line" \| "number" | `"dot"` | One indicator per slide, rendered as an accessible tablist. |
| `Carousel.ProgressText` | format?: (index, total) => ReactNode | `"1 / 3"` | Live-region progress readout. |
| `Carousel.AutoPlayTrigger` | children?: (isPlaying) => ReactNode | None | Play/pause toggle for autoPlay. |

## Keyboard

With focus anywhere inside the carousel:

| Key | Action |
| --- | --- |
| `←` / `→` | Previous / next page (horizontal) |
| `↑` / `↓` | Previous / next page (vertical) |

## Accessibility

- The root is a `region` with `aria-roledescription="carousel"`; slides are
  labeled groups ("Slide 2 of 5").
- Off-screen slides are `aria-hidden` and `inert`, so focus can't leak into
  them.
- Indicators form a real tablist.

---

<!-- Disclosure / Collapsible: /docs/components/collapsible -->

# Collapsible

A single disclosure that ships **zero JavaScript**. The open state is the
browser's (`<details>`), toggling is the browser's, and the expanded /
collapsed state is announced natively to assistive technology. It renders as
a Server Component and works with JavaScript disabled.

```tsx
import { Collapsible, Box } from "astralis-ui";

// No "use client": this demo IS a Server Component. The open/close behavior
// you're using is the browser's <details> element, not JavaScript.
export function CollapsibleDemo() {
  return (
    <Box w="full" maxW="md">
      <Collapsible defaultOpen>
        <Collapsible.Trigger>What ships to the browser?</Collapsible.Trigger>
        <Collapsible.Content>
          Nothing. This entire component renders to HTML on the server. The
          toggle you just used is the native details element.
        </Collapsible.Content>
      </Collapsible>
      <Collapsible>
        <Collapsible.Trigger>Does it work with JavaScript disabled?</Collapsible.Trigger>
        <Collapsible.Content>
          Yes: open, close, keyboard, and screen-reader state announcements
          are all platform behavior.
        </Collapsible.Content>
      </Collapsible>
    </Box>
  );
}
```

## Import

```tsx
import { Collapsible } from "astralis-ui";
```

## Exclusive groups (accordion, no JS)

Collapsibles sharing a `name` form a native exclusive accordion: opening one
closes its siblings via the `<details name>` attribute:

```tsx
import { Collapsible, Box } from "astralis-ui";

// Collapsibles sharing a `name` form a native exclusive accordion: opening
// one closes its siblings, with zero JavaScript (`<details name>`).
export function CollapsibleExclusive() {
  return (
    <Box w="full" maxW="md">
      <Collapsible name="faq" defaultOpen>
        <Collapsible.Trigger>Only one of us stays open</Collapsible.Trigger>
        <Collapsible.Content>Open my sibling and I close.</Collapsible.Content>
      </Collapsible>
      <Collapsible name="faq">
        <Collapsible.Trigger>Try me</Collapsible.Trigger>
        <Collapsible.Content>The grouping is the name attribute.</Collapsible.Content>
      </Collapsible>
      <Collapsible name="faq">
        <Collapsible.Trigger>Or me</Collapsible.Trigger>
        <Collapsible.Content>Still no JavaScript.</Collapsible.Content>
      </Collapsible>
    </Box>
  );
}
```

## Uncontrolled by design

There is no `open`/`onOpenChange` pair: a controlled variant would move the
state into React and forfeit exactly the property this component exists for.
Use `defaultOpen` for the initial state; if you need programmatic control,
[Accordion](/docs/components/accordion) is the stateful sibling.

## Accessibility

- The trigger stays a real `<summary>` with its native `list-item` display:
  only the marker is hidden. Restyling summary's display is the documented
  way to lose expanded/collapsed announcements in some screen readers, so the
  layout row is an inner span instead.
- Find-in-page can auto-open a collapsed section in Chromium: content is
  searchable, not trapped.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultOpen` | boolean | `false` | Open on first render. There is no controlled open prop: the state belongs to the browser. |
| `name` | string | None | Collapsibles sharing a name form a native exclusive group, where opening one closes the others. |

### Collapsible.Trigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `hideIndicator` | boolean | `false` | Hides the built-in chevron, for when you draw your own. |

### Parts

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Collapsible.Trigger` | summary props | None | The always-visible summary line that toggles the content. |
| `Collapsible.Content` | div props | None | The content shown while open. Adds spacing and typography only. |

## Keyboard

The trigger is a native `<summary>`, so it is a tab stop that toggles with
`Enter` or `Space`, with or without JavaScript.

---

<!-- Disclosure / Pagination: /docs/components/pagination -->

# Pagination

Page navigation with smart ellipses, jump controls and a quick-jump input.

```tsx
"use client";

import { Pagination } from "astralis-ui";

export function PaginationDemo() {
  return (
    <Pagination totalPages={10} defaultPage={3}>
      <Pagination.List>
        <Pagination.Prev />
        <Pagination.Pages />
        <Pagination.Next />
      </Pagination.List>
    </Pagination>
  );
}
```

## Import

```tsx
import { Pagination } from "astralis-ui";
// Pagination.List, .Pages, .Item, .Prev, .Next,
// .First, .Last, .PageText, .Jumper
```

## Variants

```tsx
"use client";

import { Pagination, Text, VStack } from "astralis-ui";

const variants = ["solid", "outline", "subtle", "plain"] as const;

export function PaginationVariants() {
  return (
    <VStack gap="5" alignItems="start">
      {variants.map((variant) => (
        <VStack key={variant} gap="1" alignItems="start">
          <Text as="span" size="xs" color="muted">{variant}</Text>
          <Pagination totalPages={5} defaultPage={2} variant={variant} size="sm">
            <Pagination.List>
              <Pagination.Prev />
              <Pagination.Pages />
              <Pagination.Next />
            </Pagination.List>
          </Pagination>
        </VStack>
      ))}
    </VStack>
  );
}
```

## Everything on

Derive the page count from an item `count` + `pageSize`, pin boundary pages,
and compose every control: `Pages` handles the ellipses automatically.

```tsx
"use client";

import { Pagination } from "astralis-ui";

export function PaginationFull() {
  return (
    /* Derive pages from an item count, pin boundaries, and add every control. */
    <Pagination count={195} pageSize={10} defaultPage={7} colorScheme="teal">
      <Pagination.List>
        <Pagination.First />
        <Pagination.Prev />
        <Pagination.Pages siblings={1} boundaryCount={1} />
        <Pagination.Next />
        <Pagination.Last />
        <Pagination.Jumper />
      </Pagination.List>
    </Pagination>
  );
}
```

## Controlled

`page` + `onPageChange` for server-driven data, the usual case.

```tsx
"use client";

import { useState } from "react";
import { Pagination, Text, VStack } from "astralis-ui";

export function PaginationControlled() {
  const [page, setPage] = useState(1);

  return (
    <VStack gap="3" alignItems="start">
      <Pagination totalPages={8} page={page} onPageChange={setPage} variant="subtle">
        <Pagination.List>
          <Pagination.Prev />
          <Pagination.Pages />
          <Pagination.Next />
          <Pagination.PageText />
        </Pagination.List>
      </Pagination>
      <Text size="sm" color="muted">
        Fetching results for page {page}…
      </Text>
    </VStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `page · defaultPage · onPageChange` | number · number · (page: number) => void | `None · 1 · None` | Controlled / initial page, and the change callback. |
| `totalPages` | number | None | Explicit page count. Use this OR count + pageSize. |
| `count · pageSize` | number · number | `None · 10` | Total items; the page count is derived. |
| `variant` | "solid" \| "outline" \| "subtle" \| "plain" | `"solid"` | Page-button styling; the active page carries the accent. |
| `size` | "xs" \| "sm" \| "md" \| "lg" | `"md"` | Button sizing. |
| `rounded` | "none" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "full" | `"md"` | Button corner radius. |
| `colorScheme` | all 15 schemes | `"brand"` | Active page and focus-ring hue. |
| `disabled` | boolean | `false` | Disables the whole control. |

### Parts

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Pagination.Pages` | siblings?: number · boundaryCount?: number | `1 · 1` | Page buttons around the current page and pinned at the ends, with ellipses between. |
| `Pagination.Prev / Next / First / Last` | icon?: ReactNode | None | Step and jump buttons; default chevron icons. |
| `Pagination.PageText` | format?: (state) => ReactNode | `"Page 3 of 8"` | Live-region readout of the current state. |
| `Pagination.Jumper` | label?: ReactNode | `"Go to"` | Number input that jumps straight to a page. |
| `Pagination.Item` | page: number | None | A single page button, for fully manual layouts. |

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Move between the page and prev/next buttons |
| `Enter` / `Space` | Activate the focused button |
| `Enter` in the Jumper | Jump to the typed page (clamped to range) |

## Accessibility

- Renders a `nav` landmark labeled "Pagination"; the active page carries
  `aria-current="page"`.
- `PageText` is an `aria-live` region, so page changes are announced.
- The `Jumper` input has an accessible label and clamps to valid pages.

---

<!-- Navigation / Tabs: /docs/components/tabs -->

# Tabs

Switchable panels with an animated indicator, five variants and full keyboard support.

```tsx
"use client";

import { Tabs, Text, Box } from "astralis-ui";

export function TabsDemo() {
  return (
    <Box w="full" maxW="md">
      <Tabs defaultValue="overview">
        <Tabs.List>
          <Tabs.Trigger value="overview">Overview</Tabs.Trigger>
          <Tabs.Trigger value="activity">Activity</Tabs.Trigger>
          <Tabs.Trigger value="settings">Settings</Tabs.Trigger>
        </Tabs.List>
        <Box pt="4">
          <Tabs.Content value="overview">
            <Text size="sm" color="muted">
              The line variant slides its indicator between triggers.
            </Text>
          </Tabs.Content>
          <Tabs.Content value="activity">
            <Text size="sm" color="muted">Recent activity shows here.</Text>
          </Tabs.Content>
          <Tabs.Content value="settings">
            <Text size="sm" color="muted">Settings panel.</Text>
          </Tabs.Content>
        </Box>
      </Tabs>
    </Box>
  );
}
```

## Import

```tsx
import { Tabs } from "astralis-ui";
// Tabs.List, Tabs.Trigger, Tabs.Content
```

## Variants

`line` slides a measured indicator under the active trigger; `segmented`
raises it on a track; `outline` gives folder tabs. Individual triggers can
be disabled.

```tsx
"use client";

import { Tabs, Text, VStack } from "astralis-ui";

const variants = ["line", "subtle", "segmented", "outline", "plain"] as const;

export function TabsVariants() {
  return (
    <VStack gap="5" alignItems="start">
      {variants.map((variant) => (
        <VStack key={variant} gap="1" alignItems="start">
          <Text as="span" size="xs" color="muted">{variant}</Text>
          <Tabs variant={variant} size="sm" defaultValue="one">
            <Tabs.List>
              <Tabs.Trigger value="one">First</Tabs.Trigger>
              <Tabs.Trigger value="two">Second</Tabs.Trigger>
              <Tabs.Trigger value="three" disabled>Disabled</Tabs.Trigger>
            </Tabs.List>
          </Tabs>
        </VStack>
      ))}
    </VStack>
  );
}
```

## Vertical

`orientation="vertical"` stacks the list and flips the arrow-key axis, the
settings-page classic.

```tsx
"use client";

import { Tabs, Text, HStack, Box } from "astralis-ui";

export function TabsVertical() {
  return (
    <Tabs orientation="vertical" variant="subtle" defaultValue="profile">
      <HStack gap="6" alignItems="start">
        <Tabs.List>
          <Tabs.Trigger value="profile">Profile</Tabs.Trigger>
          <Tabs.Trigger value="security">Security</Tabs.Trigger>
          <Tabs.Trigger value="billing">Billing</Tabs.Trigger>
        </Tabs.List>
        <Box minW="3xs">
          <Tabs.Content value="profile">
            <Text size="sm" color="muted">Name, avatar, bio.</Text>
          </Tabs.Content>
          <Tabs.Content value="security">
            <Text size="sm" color="muted">Password and sessions.</Text>
          </Tabs.Content>
          <Tabs.Content value="billing">
            <Text size="sm" color="muted">Plan and invoices.</Text>
          </Tabs.Content>
        </Box>
      </HStack>
    </Tabs>
  );
}
```

## Fitted and rounded

`fitted` stretches triggers across the list; with `segmented` + `rounded` it
becomes the familiar pill switcher.

```tsx
"use client";

import { Tabs, Box } from "astralis-ui";

export function TabsFitted() {
  return (
    /* fitted stretches triggers across the list; rounded makes it a pill. */
    <Box w="full" maxW="sm">
      <Tabs variant="segmented" fitted rounded defaultValue="day">
        <Tabs.List>
          <Tabs.Trigger value="day">Day</Tabs.Trigger>
          <Tabs.Trigger value="week">Week</Tabs.Trigger>
          <Tabs.Trigger value="month">Month</Tabs.Trigger>
        </Tabs.List>
      </Tabs>
    </Box>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value · defaultValue · onValueChange` | string · string · (value: string) => void | None | Controlled / initial tab, and the change callback. |
| `variant` | "line" \| "subtle" \| "segmented" \| "outline" \| "plain" | `"line"` | Underline with sliding indicator, filled pill, raised track, folder tabs, or minimal. |
| `colorScheme` | all 15 schemes | `"brand"` | Hue for the active tab, sliding indicator, and focus rings (via the accent channel). |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Trigger padding and text size. |
| `orientation` | "horizontal" \| "vertical" | `"horizontal"` | Layout and arrow-key axis. |
| `fitted` | boolean | `false` | Stretch triggers to fill the list width. |
| `rounded` | boolean | `false` | Pill radii for the subtle/segmented/outline variants. |
| `activationMode` | "automatic" \| "manual" | `"automatic"` | Whether arrow-key focus selects immediately, or Enter/Space confirms. |
| `keepMounted` | boolean | `false` | Hide inactive panels instead of unmounting them. |
| `loop` | boolean | `true` | Arrow-key focus wraps around the ends. |

### Parts

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Tabs.Trigger` | value: string · disabled?: boolean | None | One tab button; value links it to its panel. |
| `Tabs.Content` | value: string | None | The panel shown while its value is active. |

## Keyboard

| Key | Action |
| --- | --- |
| `←` / `→` | Move focus between tabs (`↑` / `↓` when vertical); wraps with `loop` |
| `Home` / `End` | First / last tab |
| `Enter` / `Space` | Select the focused tab |

With `activationMode="automatic"` (the default), moving focus also selects.
With `"manual"`, focus moves freely and Enter/Space commits. Use it for
panels that are expensive to switch.

## Accessibility

- Real `tablist`/`tab`/`tabpanel` roles with `aria-selected` and
  `aria-controls` wiring.
- Roving tabindex: one Tab stop for the whole list, arrows move within it.

---

<!-- Navigation / Steps: /docs/components/steps -->

# Steps

Multi-step flows with derived statuses, error states and built-in wizard navigation.

```tsx
"use client";

import { useState } from "react";
import { Steps, Text, Box, HStack, VStack } from "astralis-ui";

export function StepsDemo() {
  const [step, setStep] = useState(0);

  return (
    <VStack gap="6" alignItems="stretch" w="full" maxW="md">
      <Steps step={step} onStepChange={setStep}>
        <Steps.List>
          <Steps.Item>
            <Steps.Indicator />
            <Steps.Title>Account</Steps.Title>
          </Steps.Item>
          <Steps.Item>
            <Steps.Indicator />
            <Steps.Title>Shipping</Steps.Title>
          </Steps.Item>
          <Steps.Item>
            <Steps.Indicator />
            <Steps.Title>Confirm</Steps.Title>
          </Steps.Item>
        </Steps.List>

        <Box minH="16" pt="4">
          <Steps.Content index={0}>
            <Text size="sm" color="muted">Email and password.</Text>
          </Steps.Content>
          <Steps.Content index={1}>
            <Text size="sm" color="muted">Where should we ship?</Text>
          </Steps.Content>
          <Steps.Content index={2}>
            <Text size="sm" color="muted">Review your order.</Text>
          </Steps.Content>
          <Steps.Completed>
            <Text size="sm" color="success" weight="medium">Order placed. All steps complete.</Text>
          </Steps.Completed>
        </Box>

        <HStack gap="3">
          <Steps.Prev />
          <Steps.Next />
        </HStack>
      </Steps>
    </VStack>
  );
}
```

## Import

```tsx
import { Steps } from "astralis-ui";
// Steps.List, .Item, .Indicator, .Title, .Description,
// .Content, .Completed, .Prev, .Next
```

## Usage

Each item's status (completed, active, upcoming, error) is derived from the
active index; indicators show a number, a check, or an error mark
accordingly. `Steps.Prev`/`Steps.Next` come pre-wired with end-of-flow
disabling, and `Steps.Completed` renders after the final step.

## Variants

```tsx
"use client";

import { Steps, Text, VStack } from "astralis-ui";

const variants = ["solid", "subtle", "dot"] as const;

export function StepsVariants() {
  return (
    <VStack gap="6" alignItems="stretch" w="full" maxW="md">
      {variants.map((variant) => (
        <VStack key={variant} gap="2" alignItems="stretch">
          <Text as="span" size="xs" color="muted">{variant}</Text>
          <Steps variant={variant} defaultStep={1} size="sm">
            <Steps.List>
              <Steps.Item>
                <Steps.Indicator />
                <Steps.Title>Done</Steps.Title>
              </Steps.Item>
              <Steps.Item>
                <Steps.Indicator />
                <Steps.Title>Active</Steps.Title>
              </Steps.Item>
              <Steps.Item>
                <Steps.Indicator />
                <Steps.Title>Upcoming</Steps.Title>
              </Steps.Item>
            </Steps.List>
          </Steps>
        </VStack>
      ))}
    </VStack>
  );
}
```

## Vertical with descriptions

Vertical orientation suits timelines and long flows; `error` on an item
flags it without breaking the sequence.

```tsx
"use client";

import { Steps } from "astralis-ui";

export function StepsVertical() {
  return (
    <Steps orientation="vertical" defaultStep={2}>
      <Steps.List>
        <Steps.Item>
          <Steps.Indicator />
          <Steps.Title>Repository created</Steps.Title>
          <Steps.Description>astralis/astralis-ui</Steps.Description>
        </Steps.Item>
        <Steps.Item error>
          <Steps.Indicator />
          <Steps.Title>CI failed</Steps.Title>
          <Steps.Description>error marks a step red</Steps.Description>
        </Steps.Item>
        <Steps.Item>
          <Steps.Indicator />
          <Steps.Title>Fix and re-run</Steps.Title>
          <Steps.Description>You are here</Steps.Description>
        </Steps.Item>
        <Steps.Item>
          <Steps.Indicator />
          <Steps.Title>Deploy</Steps.Title>
          <Steps.Description>Upcoming</Steps.Description>
        </Steps.Item>
      </Steps.List>
    </Steps>
  );
}
```

## Clickable with bottom labels

`clickable` turns indicators into jump buttons (`linear` restricts jumping
ahead); `labelPlacement="bottom"` centers titles under the track.

```tsx
"use client";

import { Steps, Box } from "astralis-ui";

export function StepsClickable() {
  return (
    /* clickable indicators jump straight to a step; labels sit beneath. */
    <Box w="full" maxW="md">
      <Steps clickable labelPlacement="bottom" defaultStep={1} variant="subtle">
        <Steps.List>
          <Steps.Item>
            <Steps.Indicator />
            <Steps.Title>Cart</Steps.Title>
          </Steps.Item>
          <Steps.Item>
            <Steps.Indicator />
            <Steps.Title>Payment</Steps.Title>
          </Steps.Item>
          <Steps.Item>
            <Steps.Indicator />
            <Steps.Title>Receipt</Steps.Title>
          </Steps.Item>
        </Steps.List>
      </Steps>
    </Box>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `step · defaultStep · onStepChange` | number · number · (step: number) => void | `None · 0 · None` | Controlled / initial step (0-based), and the change callback. |
| `variant` | "solid" \| "subtle" \| "dot" | `"solid"` | Filled circles, outlined circles, or minimal dots. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Indicator and typography scale together. |
| `orientation` | "horizontal" \| "vertical" | `"horizontal"` | Step layout direction. |
| `labelPlacement` | "inline" \| "bottom" | `"inline"` | Horizontal only: titles beside or centered beneath indicators. |
| `clickable` | boolean | `false` | Indicators become buttons that jump to their step. |
| `linear` | boolean | `false` | Restricts navigation to one step forward, no skipping ahead. |
| `count` | number | None | Total steps; usually auto-counted from Steps.List children. |

### Parts

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Steps.Item` | disabled?: boolean · error?: boolean | None | One step; status (completed/active/upcoming/error) is derived from the active index. |
| `Steps.Indicator` | children?: ReactNode | None | Circle/dot: shows the number, a check when completed, or ! on error. Children override. |
| `Steps.Title / Steps.Description` | children | None | Labels that recolor with the step's status. |
| `Steps.Content` | index: number | None | Panel shown while its index is active. |
| `Steps.Completed` | children | None | Shown once the flow advances past the last step. |
| `Steps.Prev / Steps.Next` | children?: ReactNode · disabled?: boolean | `"Back" / "Next"` | Navigation buttons with automatic disabling at the ends. |

## Accessibility

- The list is a real `ol`; the active indicator carries
  `aria-current="step"`.
- Connectors are decorative (`aria-hidden`); statuses are exposed as data
  attributes for styling.
- Prev/Next are plain buttons. Keyboard access comes for free.

---

<!-- Navigation / Breadcrumb: /docs/components/breadcrumb -->

# Breadcrumb

A hierarchy trail with automatic separators and current-page semantics.

```tsx
"use client";

import { Breadcrumb } from "astralis-ui";

export function BreadcrumbDemo() {
  return (
    <Breadcrumb>
      <Breadcrumb.Item>
        <Breadcrumb.Link href="#">Home</Breadcrumb.Link>
      </Breadcrumb.Item>
      <Breadcrumb.Item>
        <Breadcrumb.Link href="#">Components</Breadcrumb.Link>
      </Breadcrumb.Item>
      <Breadcrumb.Item>
        <Breadcrumb.Link isCurrent>Breadcrumb</Breadcrumb.Link>
      </Breadcrumb.Item>
    </Breadcrumb>
  );
}
```

## Import

```tsx
import { Breadcrumb } from "astralis-ui";
```

Separators are inserted automatically between items. You never render them
by hand, so they can't drift out of sync.

## Custom separator

```tsx
"use client";

import { Breadcrumb, Text } from "astralis-ui";

export function BreadcrumbSeparator() {
  return (
    <Breadcrumb separator={<Text size="sm" color="subtle">/</Text>}>
      <Breadcrumb.Item>
        <Breadcrumb.Link href="#">astralis</Breadcrumb.Link>
      </Breadcrumb.Item>
      <Breadcrumb.Item>
        <Breadcrumb.Link href="#">packages</Breadcrumb.Link>
      </Breadcrumb.Item>
      <Breadcrumb.Item>
        <Breadcrumb.Link isCurrent>astralis-ui</Breadcrumb.Link>
      </Breadcrumb.Item>
    </Breadcrumb>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `separator` | ReactNode | `chevron` | Glyph between items (rendered `aria-hidden`). A string such as "/" works too. |

### Parts

| Part | Renders | Notes |
| --- | --- | --- |
| `Breadcrumb.Item` | `li` | One trail entry. |
| `Breadcrumb.Link` | `a` (or `as={Link}`) | `isCurrent` renders a non-interactive `<span aria-current="page">`. Pass your router's Link via `as`. |

## Accessibility

- The root is `<nav aria-label="Breadcrumb">` with an ordered list inside:
  the APG breadcrumb pattern.
- The current page is marked with `aria-current="page"` and rendered
  non-interactive; separators are `aria-hidden`.

---

<!-- Navigation / Menu: /docs/components/menu -->

# Menu

An action menu on the APG menu-button pattern: roving focus, typeahead, and full keyboard support.

```tsx
"use client";

import { Button, Kbd, Menu, toast, Toaster } from "astralis-ui";
import { Copy, Pencil, Settings, Trash2 } from "lucide-react";

export function MenuDemo() {
  const did = (what: string) => toast.info(what);

  return (
    <>
      <Toaster />
      <Menu>
        <Menu.Trigger>
          <Button variant="outline" colorScheme="gray">Actions</Button>
        </Menu.Trigger>
        <Menu.Content>
          <Menu.Label>Mission</Menu.Label>
          <Menu.Item icon={<Pencil style={{ width: "100%", height: "100%" }} />} shortcut={<Kbd size="sm">E</Kbd>} onSelect={() => did("Edit")}>
            Edit
          </Menu.Item>
          <Menu.Item icon={<Copy style={{ width: "100%", height: "100%" }} />} shortcut={<Kbd size="sm">⌘C</Kbd>} onSelect={() => did("Duplicate")}>
            Duplicate
          </Menu.Item>
          <Menu.Item icon={<Settings style={{ width: "100%", height: "100%" }} />} disabled>
            Configure
          </Menu.Item>
          <Menu.Separator />
          <Menu.Item danger icon={<Trash2 style={{ width: "100%", height: "100%" }} />} onSelect={() => did("Deleted")}>
            Delete
          </Menu.Item>
        </Menu.Content>
      </Menu>
    </>
  );
}
```

## Import

```tsx
import { Menu } from "astralis-ui";
```

## Placement

```tsx
"use client";

import { Button, HStack, Menu } from "astralis-ui";

function Placement({ side, align, label }: { side?: "top" | "bottom" | "left" | "right"; align?: "start" | "center" | "end"; label: string }) {
  return (
    <Menu side={side} align={align}>
      <Menu.Trigger>
        <Button size="sm" variant="subtle" colorScheme="gray">{label}</Button>
      </Menu.Trigger>
      <Menu.Content>
        <Menu.Item>First</Menu.Item>
        <Menu.Item>Second</Menu.Item>
        <Menu.Item>Third</Menu.Item>
      </Menu.Content>
    </Menu>
  );
}

export function MenuPlacement() {
  return (
    <HStack gap="3" wrap="wrap">
      <Placement label="bottom / start" />
      <Placement side="bottom" align="end" label="bottom / end" />
      <Placement side="top" align="start" label="top / start" />
      <Placement side="right" align="start" label="right / start" />
    </HStack>
  );
}
```

## Props

### `<Menu>` (root)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open / defaultOpen / onOpenChange` | boolean / boolean / (open: boolean) => void | None | Controlled/uncontrolled open state. |
| `side` | "top" \| "bottom" \| "left" \| "right" | `"bottom"` | Preferred side (flips on collision). |
| `align` | "start" \| "center" \| "end" | `"start"` | Alignment along the trigger. |
| `sideOffset` | number | `6` | Gap to the trigger, px. |
| `closeOnSelect` | boolean | `true` | Close after an item activates. |

### `<Menu.Item>`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSelect` | () => void | None | Runs on click, Enter or Space. |
| `disabled` | boolean | `false` | Skipped by arrow-key focus and can't be activated. |
| `danger` | boolean | `false` | Destructive styling, for delete and remove. |
| `icon` | ReactNode | None | Leading glyph. |
| `shortcut` | ReactNode | None | Trailing hint, such as a Kbd shortcut. |
| `closeOnSelect` | boolean | `the menu's` | Overrides the menu's closeOnSelect for this item. |

### Parts

`Menu.Trigger` (wraps your button; wires `aria-haspopup`/`aria-expanded`),
`Menu.Content`, `Menu.Label`, `Menu.Separator`, `Menu.Group`.

## Keyboard

| Key | Action |
| --- | --- |
| `Enter` / `Space` / `↓` on trigger | Open (focus moves to the first item) |
| `↑` `↓` | Move focus (wraps) |
| `Home` / `End` | First / last item |
| *type characters* | Jump to the item starting with what you typed |
| `Enter` / `Space` | Activate the focused item |
| `Esc` | Close, return focus to the trigger |
| `Tab` | Close |

## Accessibility

- `role="menu"` / `role="menuitem"` with `aria-haspopup="menu"` and
  `aria-expanded` on the trigger; disabled items are `aria-disabled` and
  skipped by focus movement.
- Hover focuses items, so pointer and keyboard share one highlight state.
- Escape/outside-click dismissal runs through the shared overlay stack: a
  Menu inside a Modal peels first.

---

<!-- Navigation / Context Menu: /docs/components/context-menu -->

# Context Menu

A [Menu](/docs/components/menu) opened by right-click and anchored at the
pointer instead of a trigger button. Everything else *is* Menu: the same
items, roving focus, typeahead, Escape/outside dismissal and styling.

```tsx
import { ContextMenu, Center, Text } from "astralis-ui";

export function ContextMenuDemo() {
  return (
    <ContextMenu>
      <ContextMenu.Trigger>
        <Center
          w="full"
          maxW="md"
          h="32"
          rounded="lg"
          border="normal"
          borderStyle="dashed"
          borderColor="base"
          style={{ userSelect: "none" }}
          tabIndex={0}
        >
          <Text size="sm" color="muted">
            Right-click this area, or focus it and press Shift+F10
          </Text>
        </Center>
      </ContextMenu.Trigger>
      <ContextMenu.Content>
        <ContextMenu.Item shortcut="⌘C">Copy</ContextMenu.Item>
        <ContextMenu.Item shortcut="⌘V">Paste</ContextMenu.Item>
        <ContextMenu.Item>Rename</ContextMenu.Item>
        <ContextMenu.Separator />
        <ContextMenu.Item danger>Delete</ContextMenu.Item>
      </ContextMenu.Content>
    </ContextMenu>
  );
}
```

## Import

```tsx
import { ContextMenu } from "astralis-ui";
```

## How it anchors

Right-clicking places an invisible 1px anchor at the pointer and opens the
menu against it. A right-click somewhere else first dismisses (outside
pointer-down), then reopens fresh at the new position, matching platform
context-menu behavior.

## Props

[Menu](/docs/components/menu)'s props, minus `side` and `align`, because the
pointer is the anchor:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open · defaultOpen · onOpenChange` | boolean · boolean · (open: boolean) => void | `None · false · None` | Controlled / initial state, and the change callback. |
| `sideOffset` | number | `2` | Gap between the pointer and the menu, in pixels. |
| `closeOnSelect` | boolean | `true` | Closes the menu after an item is activated. |

### Parts

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ContextMenu.Trigger` | children: ReactElement | None | Wraps the element that opens the menu on right-click. Make it focusable for keyboard users. |
| `ContextMenu.Content / Item / Label / Separator / Group` | as on Menu | None | Identical to Menu's parts, including Item's onSelect, icon, shortcut and danger. |

## Keyboard

The menu opens from the browser's `contextmenu` event, which the keyboard
fires too. For that to work the trigger element has to be focusable, as the
area in the demo above is.

| Key | Action |
| --- | --- |
| `Shift+F10` / `Menu` key | Open the menu from the focused trigger |
| `↑` `↓` | Move focus between items (wraps) |
| `Home` / `End` | First / last item |
| *type characters* | Jump to the item starting with what you typed |
| `Enter` / `Space` | Activate the focused item |
| `Esc` | Close |
| `Tab` | Close |

---

<!-- Navigation / Table of Contents: /docs/components/table-of-contents -->

# Table of Contents

"On this page" navigation with scroll-spy: the entry whose heading is
currently on screen is highlighted, driven by `IntersectionObserver`, no
scroll handler. The entries are **plain anchor links**, so navigation works
before hydration and with JavaScript disabled; only the highlight is the
enhancement.

```tsx
import { TableOfContents, ScrollArea, Box, Heading, Text, HStack } from "astralis-ui";

const SECTIONS = [
  { id: "toc-demo-intro", title: "Introduction" },
  { id: "toc-demo-install", title: "Installation" },
  { id: "toc-demo-theming", title: "Theming", depth: 1 },
  { id: "toc-demo-tokens", title: "Tokens", depth: 1 },
  { id: "toc-demo-faq", title: "FAQ" },
];

export function TableOfContentsDemo() {
  return (
    <HStack gap="8" alignItems="start" w="full" maxW="2xl">
      <ScrollArea style={{ height: "14rem", flex: 1 }}>
        {SECTIONS.map((s) => (
          <Box key={s.id} pb="8">
            <Heading as="h3" id={s.id} size="sm">
              {s.title}
            </Heading>
            <Text size="sm" color="muted" mt="2">
              Scroll this pane: the entry for the section under the header
              highlights on the right. The links are plain anchors, so they
              work before hydration too.
            </Text>
          </Box>
        ))}
      </ScrollArea>
      <TableOfContents items={SECTIONS} offset={0} style={{ width: "10rem", flexShrink: 0 }} />
    </HStack>
  );
}
```

## Import

```tsx
import { TableOfContents } from "astralis-ui";
```

## Usage

Point `items` at heading ids that exist in the page:

```tsx
<TableOfContents
  items={[
    { id: "installation", title: "Installation" },
    { id: "theming", title: "Theming", depth: 1 },
    { id: "api", title: "API" },
  ]}
/>
```

## Props

Extends `nav` props:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | { id: string; title: string; depth?: number }[] | None | The entries. Each id must match a heading's id on the page; depth indents it. Required. |
| `label` | string | `"On this page"` | Accessible name of the nav, also shown as a title above the list. |
| `showLabel` | boolean | `true` | Shows the label above the list. Hidden, it still names the nav. |
| `offset` | number | `80` | Height of a sticky header, in pixels, so the entry highlights when its heading clears it. |

## Keyboard

The entries are plain links: `Tab` moves through them and `Enter` jumps to the
heading. The highlight follows the scroll position, not focus.

---

<!-- Icon / Icon: /docs/components/icon -->

# Icon

A sizing and coloring wrapper for any icon set: Lucide, Heroicons, or your own SVGs.

```tsx
"use client";

import { Icon, HStack } from "astralis-ui";
import { Rocket, Star, Compass, Orbit } from "lucide-react";

export function IconDemo() {
  return (
    <HStack gap="4">
      <Icon as={Rocket} />
      <Icon as={Star} />
      <Icon as={Compass} />
      <Icon as={Orbit} />
    </HStack>
  );
}
```

## Import

```tsx
import { Icon } from "astralis-ui";
import { Rocket } from "lucide-react"; // bring your own icons
```

## Usage

Astralis doesn't bundle an icon set: `Icon` normalizes whatever you use.
Pass an icon component via `as`, or a raw `<svg>` as children; either way
the wrapper controls size and color with tokens.

## Sizes

Token sizes `xs`–`xl`, or any explicit pixel number.

```tsx
"use client";

import { Icon, HStack } from "astralis-ui";
import { Sparkles } from "lucide-react";

export function IconSizes() {
  return (
    <HStack gap="4" alignItems="end">
      <Icon as={Sparkles} size="xs" />
      <Icon as={Sparkles} size="sm" />
      <Icon as={Sparkles} size="md" />
      <Icon as={Sparkles} size="lg" />
      <Icon as={Sparkles} size="xl" />
      {/* Or any explicit pixel value. */}
      <Icon as={Sparkles} size={40} />
    </HStack>
  );
}
```

## Colors

Semantic text-color tokens, or omit `color` and the icon inherits the
surrounding text color via `currentColor`, which is why button icons always
match their label.

```tsx
"use client";

import { Icon, Text, HStack, VStack } from "astralis-ui";
import { Heart, CircleCheck, TriangleAlert, Info } from "lucide-react";

export function IconColors() {
  return (
    <VStack gap="4" alignItems="start">
      <HStack gap="4">
        <Icon as={CircleCheck} color="success" />
        <Icon as={TriangleAlert} color="warning" />
        <Icon as={Heart} color="error" />
        <Icon as={Info} color="info" />
        <Icon as={Heart} color="muted" />
      </HStack>
      {/* Without a color prop, icons inherit the surrounding text color. */}
      <Text color="subtle" size="sm">
        <Icon as={Heart} size="xs" /> inherits via currentColor
      </Text>
    </VStack>
  );
}
```

## Custom SVGs

```tsx
"use client";

import { Icon } from "astralis-ui";

export function IconCustom() {
  return (
    /* A raw <svg> as children: Icon sizes and colors the wrapper. */
    <Icon size="xl" color="info">
      <svg viewBox="0 0 24 24" fill="currentColor">
        <path d="M12 2l2.4 7.2L22 12l-7.6 2.8L12 22l-2.4-7.2L2 12l7.6-2.8L12 2z" />
      </svg>
    </Icon>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | ElementType | None | An icon component to render, such as one from Lucide. |
| `children` | ReactNode | None | Or a raw svg element, which fills the sized wrapper. |
| `size` | "xs" \| "sm" \| "md" \| "lg" \| "xl" \| number | `"md"` | A size token, or an explicit size in pixels. |
| `color` | text color token \| CSS color | None | Omit it and the icon inherits the surrounding text color through currentColor. |
| `strokeWidth` | number | None | Passed to icon components drawn with strokes. Has no effect on raw svg children. |

## Accessibility

Icons are decorative by default (`aria-hidden`). When an icon stands alone
as the only content of a control, label the control. See the icon-only
pattern on the [Button](/docs/components/button) page.

---

<!-- Overlay / Modal: /docs/components/modal -->

# Modal

A focus-trapped dialog for critical actions, with scroll lock and full ARIA wiring.

```tsx
"use client";

import { Modal, Button, Text } from "astralis-ui";

export function ModalDemo() {
  return (
    <Modal>
      <Modal.Trigger>
        <Button>Delete project</Button>
      </Modal.Trigger>
      <Modal.Content>
        <Modal.Header>
          <Modal.Title>Delete this project?</Modal.Title>
          <Modal.CloseButton />
        </Modal.Header>
        <Modal.Body>
          <Modal.Description>
            This permanently removes the project and all of its data.
          </Modal.Description>
          <Text size="sm" color="muted">
            Type the project name to confirm. Just kidding, this is a demo.
          </Text>
        </Modal.Body>
        <Modal.Footer>
          <Modal.Close>
            <Button variant="text" colorScheme="gray">Cancel</Button>
          </Modal.Close>
          <Modal.Close>
            <Button colorScheme="red">Delete</Button>
          </Modal.Close>
        </Modal.Footer>
      </Modal.Content>
    </Modal>
  );
}
```

## Import

```tsx
import { Modal } from "astralis-ui";
// Modal.Trigger, .Content, .Header, .Body, .Footer,
// .Title, .Description, .Close, .CloseButton
```

## Anatomy

`Trigger` and `Close` wrap your own elements (usually Buttons), so the
modal composes with anything focusable:

```tsx
<Modal>
  <Modal.Trigger><Button>Open</Button></Modal.Trigger>
  <Modal.Content>
    <Modal.Header>
      <Modal.Title>Title</Modal.Title>
      <Modal.CloseButton />
    </Modal.Header>
    <Modal.Body>…</Modal.Body>
    <Modal.Footer>
      <Modal.Close><Button variant="text">Cancel</Button></Modal.Close>
    </Modal.Footer>
  </Modal.Content>
</Modal>
```

## Sizes

```tsx
"use client";

import { Modal, Button, HStack } from "astralis-ui";

const sizes = ["sm", "md", "lg", "xl", "full"] as const;

export function ModalSizes() {
  return (
    <HStack gap="3" wrap="wrap" justifyContent="center">
      {sizes.map((size) => (
        <Modal key={size} size={size}>
          <Modal.Trigger>
            <Button variant="outline" colorScheme="gray" size="sm">
              {size}
            </Button>
          </Modal.Trigger>
          <Modal.Content>
            <Modal.Header>
              <Modal.Title>Size {size}</Modal.Title>
              <Modal.CloseButton />
            </Modal.Header>
            <Modal.Body>
              <Modal.Description>
                The panel width tracks the size prop; full covers the viewport.
              </Modal.Description>
            </Modal.Body>
          </Modal.Content>
        </Modal>
      ))}
    </HStack>
  );
}
```

## Controlled

Own the state to keep the modal open during async work. Pair with
`closeOnOverlayClick={false}` so a stray click can't discard a pending save.

```tsx
"use client";

import { useState } from "react";
import { Modal, Button } from "astralis-ui";

export function ModalControlled() {
  const [open, setOpen] = useState(false);
  const [saving, setSaving] = useState(false);

  const save = () => {
    setSaving(true);
    setTimeout(() => {
      setSaving(false);
      setOpen(false); // close only after the work finishes
    }, 1200);
  };

  return (
    <Modal open={open} onOpenChange={setOpen} closeOnOverlayClick={false}>
      <Modal.Trigger>
        <Button variant="subtle">Edit profile</Button>
      </Modal.Trigger>
      <Modal.Content>
        <Modal.Header>
          <Modal.Title>Edit profile</Modal.Title>
          <Modal.CloseButton />
        </Modal.Header>
        <Modal.Body>
          <Modal.Description>
            Controlled mode: the modal stays open until saving completes, and
            overlay clicks are disabled.
          </Modal.Description>
        </Modal.Body>
        <Modal.Footer>
          <Modal.Close>
            <Button variant="text" colorScheme="gray">Cancel</Button>
          </Modal.Close>
          <Button onClick={save} loading={saving} loadingText="Saving…">
            Save changes
          </Button>
        </Modal.Footer>
      </Modal.Content>
    </Modal>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open · defaultOpen · onOpenChange` | boolean · boolean · (open: boolean) => void | `None · false · None` | Controlled / initial state, and the change callback. |
| `size` | "sm" \| "md" \| "lg" \| "xl" \| "full" | `"md"` | Panel width; full covers the viewport. |
| `centered` | boolean | `true` | Vertically center the panel. |
| `closeOnOverlayClick` | boolean | `true` | Dismiss when the backdrop is clicked. |
| `closeOnEsc` | boolean | `true` | Dismiss on Escape. |

### Parts

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Modal.Trigger / Modal.Close` | children: ReactElement | None | Wrap a single element (e.g. a Button) to open / close the modal. |
| `Modal.Content` | children · className | None | The portalled, focus-trapped dialog panel. |
| `Modal.Header / Body / Footer` | children · className | None | Layout regions; Body scrolls when content overflows. |
| `Modal.Title / Modal.Description` | children · className | None | Wired to aria-labelledby / aria-describedby automatically. |
| `Modal.CloseButton` | className | None | The corner ✕ button, placed inside the Header. |

## Keyboard

| Key | Action |
| --- | --- |
| `Esc` | Close (opt out with `closeOnEsc={false}`) |
| `Tab` / `Shift+Tab` | Cycle focus inside the dialog (it can't escape) |

On open, focus moves to the first focusable element inside; on close it
returns to the trigger. With stacked overlays, Escape closes only the
topmost layer at a time.

## Accessibility

- Renders `role="dialog"` with `aria-modal`, portalled to the body; focus is
  trapped inside while open and page scroll is locked.
- `Modal.Title` and `Modal.Description` wire `aria-labelledby` /
  `aria-describedby` automatically.
- Escape and backdrop click dismiss by default; both are opt-out props.

---

<!-- Overlay / Drawer: /docs/components/drawer -->

# Drawer

An edge-anchored dialog that slides in from any side: settings panels, carts, mobile nav.

```tsx
"use client";

import { Drawer, Button, Text, VStack } from "astralis-ui";

export function DrawerDemo() {
  return (
    <Drawer>
      <Drawer.Trigger>
        <Button variant="outline" colorScheme="gray">Open settings</Button>
      </Drawer.Trigger>
      <Drawer.Content>
        <Drawer.Header>
          <Drawer.Title>Workspace settings</Drawer.Title>
          <Drawer.CloseButton />
        </Drawer.Header>
        <Drawer.Body>
          <VStack gap="3" alignItems="stretch">
            <Drawer.Description>
              Slides in from the right by default; the body scrolls
              independently of the header and footer.
            </Drawer.Description>
            <Text size="sm" color="muted">Notifications, members, billing…</Text>
          </VStack>
        </Drawer.Body>
        <Drawer.Footer>
          <Drawer.Close>
            <Button variant="text" colorScheme="gray">Cancel</Button>
          </Drawer.Close>
          <Drawer.Close>
            <Button>Save</Button>
          </Drawer.Close>
        </Drawer.Footer>
      </Drawer.Content>
    </Drawer>
  );
}
```

## Import

```tsx
import { Drawer } from "astralis-ui";
// Same anatomy as Modal: Drawer.Trigger, .Content, .Header,
// .Body, .Footer, .Title, .Description, .Close, .CloseButton
```

## Usage

Drawer shares Modal's anatomy and behavior (focus trap, scroll lock,
Escape/backdrop dismissal) but anchors to an edge and slides instead of
fading in the center. If the content is a critical decision, use
[Modal](/docs/components/modal); if it's a workspace panel, use Drawer.

## Placements

`placement` picks the edge. For `left`/`right` the `size` prop sets width
(18–32rem, or `full`); for `top`/`bottom` it sets height (30–80vh, or `full`).

```tsx
"use client";

import { Drawer, Button, HStack } from "astralis-ui";

const placements = ["left", "right", "top", "bottom"] as const;

export function DrawerPlacements() {
  return (
    <HStack gap="3" wrap="wrap" justifyContent="center">
      {placements.map((placement) => (
        <Drawer key={placement} placement={placement} size="sm">
          <Drawer.Trigger>
            <Button variant="subtle" size="sm">{placement}</Button>
          </Drawer.Trigger>
          <Drawer.Content>
            <Drawer.Header>
              <Drawer.Title>From the {placement}</Drawer.Title>
              <Drawer.CloseButton />
            </Drawer.Header>
            <Drawer.Body>
              <Drawer.Description>
                left/right size the width; top/bottom size the height.
              </Drawer.Description>
            </Drawer.Body>
          </Drawer.Content>
        </Drawer>
      ))}
    </HStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open / defaultOpen / onOpenChange` | boolean / boolean / (open) => void | `None / false / None` | Controlled / initial state and callback. |
| `placement` | "left" \| "right" \| "top" \| "bottom" | `"right"` | Edge to slide from. |
| `size` | "sm" \| "md" \| "lg" \| "xl" \| "full" | `"md"` | Width (left/right) or height (top/bottom). |
| `closeOnOverlayClick` | boolean | `true` | Dismiss on backdrop click. |
| `closeOnEsc` | boolean | `true` | Dismiss on Escape. |

The parts (`Trigger`, `Content`, `Header`, `Body`, `Footer`, `Title`,
`Description`, `Close`, `CloseButton`) behave exactly as documented on
[Modal](/docs/components/modal#parts).

## Keyboard

| Key | Action |
| --- | --- |
| `Esc` | Close (opt out with `closeOnEsc={false}`) |
| `Tab` / `Shift+Tab` | Cycle focus inside the drawer (it can't escape) |

Focus returns to the trigger on close; with stacked overlays, Escape peels
the topmost layer first.

## Accessibility

Identical to Modal: `role="dialog"` + `aria-modal`, portalled, focus-trapped,
scroll-locked, with `Title`/`Description` wired to the dialog automatically.

---

<!-- Overlay / Tooltip: /docs/components/tooltip -->

# Tooltip

Supplementary text on hover or focus: delayed, collision-aware, never interactive.

```tsx
"use client";

import { Tooltip, Button, Icon } from "astralis-ui";
import { Wand2 } from "lucide-react";

export function TooltipDemo() {
  return (
    <Tooltip>
      <Tooltip.Trigger>
        <Button variant="outline" colorScheme="gray" leftIcon={<Icon as={Wand2} size="xs" />} aria-label="Auto-format" />
      </Tooltip.Trigger>
      <Tooltip.Content withArrow>Auto-format the document</Tooltip.Content>
    </Tooltip>
  );
}
```

## Import

```tsx
import { Tooltip } from "astralis-ui";
// Tooltip.Trigger, Tooltip.Content
```

## Usage

Wrap any focusable element in `Tooltip.Trigger`. The tooltip shows after a
delay on hover **and on keyboard focus**, and flips automatically when it
would leave the viewport. Tooltips are for supplementary hints only: the
icon-button above still needs its `aria-label`; if the content must be
clickable, use a [Popover](/docs/components/popover).

## Sides

```tsx
"use client";

import { Tooltip, Button, HStack } from "astralis-ui";

const sides = ["top", "right", "bottom", "left"] as const;

export function TooltipSides() {
  return (
    <HStack gap="3" wrap="wrap" justifyContent="center">
      {sides.map((side) => (
        <Tooltip key={side} side={side} delay={100}>
          <Tooltip.Trigger>
            <Button variant="subtle" size="sm">{side}</Button>
          </Tooltip.Trigger>
          <Tooltip.Content withArrow>Anchored {side}</Tooltip.Content>
        </Tooltip>
      ))}
    </HStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | "top" \| "right" \| "bottom" \| "left" | `"top"` | Preferred placement; flips on collision. |
| `align` | "start" \| "center" \| "end" | `"center"` | Alignment along the side. |
| `sideOffset` | number | `6` | Gap from the trigger, in pixels. |
| `delay` | number | `300` | Hover delay before showing (ms). |
| `avoidCollisions` | boolean | `true` | Flip/shift to stay in the viewport. |
| `open / defaultOpen / onOpenChange` | boolean / boolean / (open: boolean) => void | `None / false / None` | Controlled API. |

`Tooltip.Content` additionally takes `withArrow` (default `false`).

## Keyboard

| Key | Action |
| --- | --- |
| Focus the trigger | Show (no hover delay) |
| Blur / `Esc` | Hide |

## Accessibility

- Renders `role="tooltip"` and wires `aria-describedby` onto the trigger
  while open.
- Shows on focus for keyboard users; Escape dismisses.
- Pointer-events are disabled: it can never trap the cursor.

---

<!-- Overlay / Popover: /docs/components/popover -->

# Popover

An interactive floating panel anchored to its trigger, for content too rich for a tooltip.

```tsx
"use client";

import { Popover, Button, Text, VStack } from "astralis-ui";

export function PopoverDemo() {
  return (
    <Popover>
      <Popover.Trigger>
        <Button variant="outline" colorScheme="gray">Share</Button>
      </Popover.Trigger>
      <Popover.Content withArrow>
        <VStack gap="2" alignItems="stretch" maxW="3xs">
          <Popover.Title>Share this page</Popover.Title>
          <Popover.Description>
            Anyone with the link can view. Popovers hold interactive content,
            unlike tooltips.
          </Popover.Description>
          <Text size="xs" color="subtle">astralis.dev/docs/popover</Text>
          <Popover.Close>
            <Button size="sm">Copy link</Button>
          </Popover.Close>
        </VStack>
      </Popover.Content>
    </Popover>
  );
}
```

## Import

```tsx
import { Popover } from "astralis-ui";
// Popover.Trigger, .Content, .Title, .Description, .Close
```

## Usage

The trigger toggles on click; the panel takes focus while open and returns it
on close. It dismisses on Escape or an outside click (both opt-out). Rule of
thumb: hover + read-only → [Tooltip](/docs/components/tooltip); click +
interactive → Popover; blocking decision → [Modal](/docs/components/modal).

## Placement

`side` and `align` compose into twelve anchor positions, with `sideOffset` /
`alignOffset` for fine-tuning; collisions flip it automatically.

```tsx
"use client";

import { Popover, Button, HStack } from "astralis-ui";

export function PopoverPlacement() {
  return (
    <HStack gap="3" wrap="wrap" justifyContent="center">
      <Popover side="top">
        <Popover.Trigger>
          <Button variant="subtle" size="sm">top</Button>
        </Popover.Trigger>
        <Popover.Content withArrow>
          <Popover.Description>Anchored above.</Popover.Description>
        </Popover.Content>
      </Popover>

      <Popover side="right" align="start">
        <Popover.Trigger>
          <Button variant="subtle" size="sm">right / start</Button>
        </Popover.Trigger>
        <Popover.Content withArrow>
          <Popover.Description>Side and align compose.</Popover.Description>
        </Popover.Content>
      </Popover>

      <Popover side="bottom" align="end" sideOffset={12}>
        <Popover.Trigger>
          <Button variant="subtle" size="sm">bottom / end / offset</Button>
        </Popover.Trigger>
        <Popover.Content withArrow>
          <Popover.Description>With an extra 12px gap.</Popover.Description>
        </Popover.Content>
      </Popover>
    </HStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | "top" \| "right" \| "bottom" \| "left" | `"bottom"` | Preferred placement; flips on collision. |
| `align` | "start" \| "center" \| "end" | `"center"` | Alignment along the side. |
| `sideOffset / alignOffset` | number | `8 / 0` | Pixel gaps on each axis. |
| `avoidCollisions` | boolean | `true` | Flip/shift to stay in the viewport. |
| `closeOnEsc / closeOnOutsidePointer` | boolean | `true` | Dismissal behavior. |
| `open / defaultOpen / onOpenChange` | boolean / boolean / (open: boolean) => void | `None / false / None` | Controlled API. |

`Popover.Content` takes `withArrow`; `Popover.Trigger` and `Popover.Close`
wrap a single element, like Modal's.

## Keyboard

| Key | Action |
| --- | --- |
| `Enter` / `Space` on trigger | Toggle open |
| `Esc` | Close (topmost overlay first) |
| `Tab` | Moves through the panel and out. Focus is not trapped |

## Accessibility

- The panel is `role="dialog"`; the trigger gets `aria-haspopup`,
  `aria-expanded` and `aria-controls` automatically.
- Focus moves into the panel on open and back to the trigger on close.
- `Title`/`Description` wire the dialog's accessible name and description.

---

<!-- Overlay / Popout: /docs/components/popout -->

# Popout

An anchored disclosure panel that ships **zero JavaScript**. The trigger is a
real `<button popovertarget>`; the panel is a native `[popover]` positioned by
CSS anchor positioning against the trigger's implicit anchor. The platform
supplies everything a JS popover engine used to: the top layer, light
dismiss, **Esc**, focus return, and collision flipping. It
renders as a Server Component and works with JavaScript disabled.

```tsx
import { Popout, Text } from "astralis-ui";

// No "use client". A fully interactive anchored panel with no JavaScript:
// a native [popover] invoked by popovertarget, positioned by CSS anchor
// positioning against the trigger's implicit anchor.
export function PopoutDemo() {
  return (
    <Popout>
      <Popout.Trigger>What is this?</Popout.Trigger>
      <Popout.Content side="bottom" align="start">
        <Text size="sm">
          A zero-JS disclosure: top layer, Esc, light dismiss, and collision
          flipping all come from the platform.
        </Text>
      </Popout.Content>
    </Popout>
  );
}
```

## Import

```tsx
import { Popout } from "astralis-ui";
```

## Placement

`side` and `align` compile to `position-area`; when there is no room, the
panel flips via `position-try-fallbacks`, the browser's collision handling,
not a resize listener:

```tsx
import { Popout, HStack } from "astralis-ui";

export function PopoutPlacement() {
  return (
    <HStack gap="3" wrap="wrap" justifyContent="center">
      {(["top", "bottom", "left", "right"] as const).map((side) => (
        <Popout key={side}>
          <Popout.Trigger>{side}</Popout.Trigger>
          <Popout.Content side={side} align="center">
            Anchored {side}; flips when there is no room.
          </Popout.Content>
        </Popout>
      ))}
    </HStack>
  );
}
```

## Popout is a disclosure, not a menu

Deliberately: there is no roving focus and no menu ARIA, because those
require state CSS cannot own. For an actions menu with arrow-key navigation,
reach for [Menu](/docs/components/menu). That's what it's for. Popout is the
right shape for nav dropdowns, info panels, and filters.

## Browser support

Popover is Baseline 2025; anchor positioning is cross-engine since January
2026 (Chrome 125+, Safari 26+, Firefox 147+). In browsers without anchor
positioning the panel still opens, closes and light-dismisses correctly, and
falls back to the browser's centered top-layer placement.

## Props

The root takes only its two parts; the panel is configured on `Popout.Content`:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | "top" \| "bottom" \| "left" \| "right" | `"bottom"` | Which side of the trigger the panel opens on. |
| `align` | "start" \| "center" \| "end" | `"start"` | Alignment along that side. |
| `sideOffset` | number | `8` | Gap between the trigger and the panel, in pixels. |

### Parts

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Popout.Trigger` | button props | None | Renders a button wired to the panel with popovertarget. |
| `Popout.Content` | div props, plus the props above | None | The native popover panel. |

## Keyboard

All of it is the browser's popover behavior:

| Key | Action |
| --- | --- |
| `Enter` / `Space` on the trigger | Open or close the panel |
| `Esc` | Close the panel and return focus to the trigger |
| `Tab` | Move through the panel's content, then on through the page |

---

<!-- Overlay / Alert Dialog: /docs/components/alert-dialog -->

# Alert Dialog

A [Modal](/docs/components/modal) with forced-choice semantics for delete
confirmations, unsaved changes and destructive actions. The panel announces
as an `alertdialog`, clicking the overlay does **not** dismiss it, and there
is deliberately no corner X. The user resolves it through the Footer actions
(Esc still cancels, per the ARIA pattern).

```tsx
import { AlertDialog, Button } from "astralis-ui";

export function AlertDialogDemo() {
  return (
    <AlertDialog>
      <AlertDialog.Trigger>
        <Button colorScheme="error" variant="outline">
          Delete workspace
        </Button>
      </AlertDialog.Trigger>
      <AlertDialog.Content>
        <AlertDialog.Header>
          <AlertDialog.Title>Delete this workspace?</AlertDialog.Title>
          <AlertDialog.Description>
            All projects, members and settings will be permanently removed.
            This action cannot be undone.
          </AlertDialog.Description>
        </AlertDialog.Header>
        <AlertDialog.Footer>
          <AlertDialog.Close>
            <Button variant="outline" colorScheme="gray">
              Cancel
            </Button>
          </AlertDialog.Close>
          <AlertDialog.Close>
            <Button colorScheme="error">Delete workspace</Button>
          </AlertDialog.Close>
        </AlertDialog.Footer>
      </AlertDialog.Content>
    </AlertDialog>
  );
}
```

## Import

```tsx
import { AlertDialog } from "astralis-ui";
```

## Relationship to Modal

The parts *are* Modal's parts: same context, same styling, same composition.
Only the root differs, so everything on the
[Modal page](/docs/components/modal) (sizes, centering, controlled state)
applies here unchanged.

## Props

Modal's props, with overlay dismissal off by default:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open · defaultOpen · onOpenChange` | boolean · boolean · (open: boolean) => void | `None · false · None` | Controlled / initial state, and the change callback. |
| `size` | "sm" \| "md" \| "lg" \| "xl" \| "full" | `"md"` | Panel width. |
| `centered` | boolean | `true` | Centers the panel vertically. |
| `closeOnOverlayClick` | boolean | `false` | Off by default, unlike Modal: the user has to choose an action. |
| `closeOnEsc` | boolean | `true` | Escape cancels, as the ARIA pattern expects. |

### Parts

There is deliberately no `AlertDialog.CloseButton`: the dialog resolves through
the actions in its Footer.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `AlertDialog.Trigger / AlertDialog.Close` | children: ReactElement | None | Wrap a single element, such as a Button, to open or to close the dialog. |
| `AlertDialog.Content` | div props | None | The portalled, focus-trapped panel. |
| `AlertDialog.Header / Body / Footer` | children · className | None | Layout regions. The Footer holds the actions that resolve the dialog. |
| `AlertDialog.Title / AlertDialog.Description` | children · className | None | Wired to aria-labelledby and aria-describedby. |

## Keyboard

| Key | Action |
| --- | --- |
| `Esc` | Cancel and close (opt out with `closeOnEsc={false}`) |
| `Tab` / `Shift+Tab` | Cycle focus between the actions; it can't leave the dialog |
| `Enter` / `Space` | Activate the focused action |

On open, focus moves to the first focusable element inside the panel; on
close it returns to the trigger.

---

<!-- Overlay / Backdrop: /docs/components/backdrop -->

# Backdrop

The scrim [Modal](/docs/components/modal) and
[Drawer](/docs/components/drawer) paint behind their panels, exposed as a
standalone primitive, for blocking "please wait" states, image viewers and
custom overlays. It is purely presentational and ships **zero client
JavaScript**: render it to show it; mounting, transitions and dismissal
belong to the caller.

```tsx
import { Backdrop, Box, Card, Loader, Text } from "astralis-ui";

// The scrim is position:fixed by design; the demo scopes it to a frame by
// overriding to absolute inside a relative container.
export function BackdropDemo() {
  return (
    <Box position="relative" w="full" maxW="md" overflow="hidden" rounded="lg">
      <Card>
        <Card.Body>
          <Text size="sm">Content that is busy loading sits behind the scrim.</Text>
        </Card.Body>
      </Card>
      <Backdrop style={{ position: "absolute" }}>
        <Loader colorScheme="gray" />
      </Backdrop>
    </Box>
  );
}
```

## Import

```tsx
import { Backdrop } from "astralis-ui";
```

## Scoping the scrim

The scrim is `position: fixed` (full screen) by design. To scope it to a
frame, as the demo above does, put it in a `position: relative` container
and pass `style={{ position: "absolute" }}`. Going the other way, a full-screen
scrim rendered deep inside a clipped or transformed container belongs in a
[Portal](/docs/components/portal), so no ancestor can clip it.

## Props

Extends `div` props:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `blur` | boolean | `true` | Frosts the content behind the scrim. |
| `children` | ReactNode | None | Centered on the scrim, such as a Loader or a message. |
| `style` | CSSProperties | None | backgroundColor replaces the scrim color; position scopes it to a frame. |

Backdrop has no keyboard behavior of its own: it doesn't trap focus or close
on Escape. If it blocks the page, move focus to what it's waiting on, or use
[Modal](/docs/components/modal), which handles both.

---

<!-- Overlay / Hover Card: /docs/components/hover-card -->

# Hover Card

A rich preview that opens on hover intent: the "profile card on a mention"
pattern. Unlike [Tooltip](/docs/components/tooltip), the content is
**interactive**: the close delay gives the pointer a grace period to travel
into the card, and entering it cancels the close, so links and buttons
inside are usable.

```tsx
import { HoverCard, Avatar, Button, HStack, VStack, Text, Link } from "astralis-ui";

export function HoverCardDemo() {
  return (
    <Text size="sm">
      Mentioned by{" "}
      <HoverCard>
        <HoverCard.Trigger>
          <Link href="#astralis">@astralis</Link>
        </HoverCard.Trigger>
        <HoverCard.Content>
          <HStack gap="3" alignItems="start">
            <Avatar name="Astralis UI" />
            <VStack gap="1" alignItems="start">
              <Text size="sm" weight="semibold">
                Astralis UI
              </Text>
              <Text size="xs" color="muted">
                React 19 components on semantic design tokens. Server-first,
                precompiled CSS.
              </Text>
              <Button size="xs" variant="outline" colorScheme="gray">
                Follow
              </Button>
            </VStack>
          </HStack>
        </HoverCard.Content>
      </HoverCard>{" "}
      in the release notes.
    </Text>
  );
}
```

## Import

```tsx
import { HoverCard } from "astralis-ui";
```

## Tooltip vs Hover Card

- **Tooltip**: a short text label, `role="tooltip"`, pointer-events off.
- **HoverCard**: a raised card with real content; supplementary by nature,
  so keyboard users get it on focus and the underlying link still works
  without it.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open · defaultOpen · onOpenChange` | boolean · boolean · (open: boolean) => void | `None · false · None` | Controlled / initial state, and the change callback. |
| `side` | "top" \| "right" \| "bottom" \| "left" | `"bottom"` | Preferred side of the trigger. |
| `align` | "start" \| "center" \| "end" | `"center"` | Alignment along that side. |
| `sideOffset` | number | `8` | Gap between the trigger and the card, in pixels. |
| `avoidCollisions` | boolean | `true` | Flips to the opposite side when the card would overflow the viewport. |
| `openDelay` | number | `400` | How long the pointer must rest on the trigger before the card opens, in ms. |
| `closeDelay` | number | `200` | Grace period for the pointer to travel into the card before it closes, in ms. |

### Parts

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `HoverCard.Trigger` | children: ReactElement | None | Wraps a single element, typically a Link. Hover and focus open the card. |
| `HoverCard.Content` | div props | None | The raised card. Its content can be interactive. |

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` onto the trigger | Open the card at once, with no delay |
| `Tab` off the trigger | Close the card |
| `Esc` | Close the card |

Because moving focus off the trigger closes the card, controls inside it
can't be reached from the keyboard. Keep everything in the card available
elsewhere, typically on the page the trigger links to.

---

<!-- Overlay / Portal: /docs/components/portal -->

# Portal

Renders its children into `document.body` (or a container you choose)
instead of where the component sits in the tree. Content in a portal escapes
the `overflow: hidden` and stacking context of its ancestors, which is why
[Modal](/docs/components/modal), [Drawer](/docs/components/drawer),
[Menu](/docs/components/menu), [Popover](/docs/components/popover) and the
[Toaster](/docs/components/toast) all render through it. Reach for it
directly when you build a custom overlay.

```tsx
"use client";

import { useState } from "react";
import { Box, Button, Card, Portal, Text, VStack } from "astralis-ui";

export function PortalDemo() {
  const [open, setOpen] = useState(false);

  return (
    <Box overflow="hidden" p="4" rounded="lg" border="normal" borderColor="base" w="full" maxW="sm">
      <VStack gap="3" alignItems="start">
        <Text size="sm" color="muted">
          This box clips anything that overflows it. The card renders into the document body,
          so the clipping never reaches it.
        </Text>
        <Button size="sm" variant="outline" colorScheme="gray" onClick={() => setOpen((value) => !value)}>
          {open ? "Hide the card" : "Show the card"}
        </Button>
      </VStack>
      {open && (
        <Portal>
          <Card position="fixed" bottom="6" right="6" zIndex="high">
            <Card.Body>
              <Text size="sm">Rendered in document.body, outside the box.</Text>
            </Card.Body>
          </Card>
        </Portal>
      )}
    </Box>
  );
}
```

## Import

```tsx
import { Portal } from "astralis-ui";
```

## Usage

Portalled content keeps its React context: events bubble to React parents and
the theme still applies, because Portal wraps its children in the library's
scoping class. The wrapper uses `display: contents`, so it never affects the
position of what you render.

Portal renders nothing on the server, and its children appear in the first
client render, in the same commit as the component that opened them. That
lets a positioned panel be measured as soon as it mounts.

```tsx
<Portal container={document.getElementById("overlay-root") ?? undefined}>
  <Backdrop />
</Portal>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | ReactNode | None | The content to render elsewhere. |
| `container` | HTMLElement | `document.body` | The element to render into. |

Portal has no playground: it has no appearance of its own to configure.

---

<!-- Data Entry / Input: /docs/components/input -->

# Input

Text inputs with four variants, plus Password, Search and TextArea built in.

```tsx
"use client";

import { Input, Box } from "astralis-ui";

export function InputDemo() {
  return (
    <Box w="full" maxW="xs">
      <Input placeholder="you@example.com" type="email" />
    </Box>
  );
}
```

## Import

```tsx
import { Input, InputGroup } from "astralis-ui";
// Input.Password, Input.Search, Input.TextArea
```

## Variants

```tsx
"use client";

import { Input, Text, VStack } from "astralis-ui";

const variants = ["outline", "filled", "underline", "unstyled"] as const;

export function InputVariants() {
  return (
    <VStack gap="4" alignItems="stretch" w="full" maxW="xs">
      {variants.map((variant) => (
        <VStack key={variant} gap="1" alignItems="stretch">
          <Text as="span" size="xs" color="muted">{variant}</Text>
          <Input variant={variant} placeholder={`The ${variant} variant`} />
        </VStack>
      ))}
    </VStack>
  );
}
```

## Password, Search and TextArea

`Input.Password` manages its own visibility toggle; `Input.Search` fires
`onSearch` on Enter (or its optional button); `Input.TextArea` adds a
character counter via `showCount` + `maxLength`.

```tsx
"use client";

import { useState } from "react";
import { Input, Text, VStack } from "astralis-ui";

export function InputTypes() {
  const [query, setQuery] = useState("");

  return (
    <VStack gap="4" alignItems="stretch" w="full" maxW="xs">
      <Input.Password placeholder="Password with visibility toggle" />
      <VStack gap="1" alignItems="stretch">
        <Input.Search
          placeholder="Search the docs…"
          showSearchButton
          onSearch={setQuery}
        />
        {query && (
          <Text size="xs" color="muted">Searched for “{query}”</Text>
        )}
      </VStack>
      <Input.TextArea placeholder="Short bio…" rows={3} maxLength={120} showCount />
    </VStack>
  );
}
```

## Prefix and suffix

Wrap in `InputGroup` for decorative slots on either side: the input pads
itself automatically.

```tsx
"use client";

import { Input, InputGroup, Icon, Text, VStack } from "astralis-ui";
import { Mail, Link2 } from "lucide-react";

export function InputGroupDemo() {
  return (
    <VStack gap="4" alignItems="stretch" w="full" maxW="xs">
      <InputGroup prefix={<Icon as={Mail} size="xs" />}>
        <Input placeholder="Email address" />
      </InputGroup>
      <InputGroup
        prefix={<Icon as={Link2} size="xs" />}
        suffix={<Text as="span" size="xs" color="subtle">.astralis.dev</Text>}
      >
        <Input placeholder="your-site" />
      </InputGroup>
    </VStack>
  );
}
```

## Props

Inputs accept all native attributes of their element, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | "outline" \| "filled" \| "underline" \| "unstyled" | `"outline"` | Visual style. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Height and padding. |
| `invalid / disabled / readOnly` | boolean | `false` | State flags, inherited automatically inside a [Field](/docs/components/field). |

| Sub-component | Extra props |
| --- | --- |
| `Input.Search` | `onSearch(value)`, `showSearchButton` |
| `Input.TextArea` | `rows`, `maxLength`, `showCount` |
| `InputGroup` | `prefix`, `suffix` (non-interactive slots) |

## Accessibility

State flags map to `aria-invalid` / `aria-readonly`, and a wrapping
[Field](/docs/components/field) wires the label and ids for you.

---

<!-- Data Entry / Field: /docs/components/field -->

# Field

The form-field wrapper: label wiring, help text, error messages, and state that flows into any input.

```tsx
"use client";

import { Field, Input, Box } from "astralis-ui";

export function FieldDemo() {
  return (
    <Box w="full" maxW="xs">
      <Field required>
        <Field.Label>Email address</Field.Label>
        <Input type="email" placeholder="you@example.com" />
        <Field.HelpText>We’ll never share your email.</Field.HelpText>
      </Field>
    </Box>
  );
}
```

## Import

```tsx
import { Field } from "astralis-ui";
// Field.Label, Field.HelpText, Field.ErrorText
// useFieldContext, for your own controls
```

## Usage

Field is context, not chrome: it generates an id, wires
`Field.Label` to the input, appends the required `*`, and pushes `invalid`,
`disabled`, `required` and `readOnly` down to **any** Astralis input inside:
Input, Checkbox, Radio, Switch, Select, Slider… no prop repetition.

## Validation state

Flip one `invalid` flag on the Field and everything reacts: the input
border, and your swap from `HelpText` to `ErrorText`.

```tsx
"use client";

import { useState } from "react";
import { Field, Input, Switch, VStack } from "astralis-ui";

export function FieldError() {
  const [invalid, setInvalid] = useState(true);

  return (
    <VStack gap="5" alignItems="stretch" w="full" maxW="xs">
      <Switch checked={invalid} onChange={(e) => setInvalid(e.target.checked)} size="sm">
        Simulate a validation error
      </Switch>

      {/* One `invalid` flag restyles the input and swaps the message. */}
      <Field invalid={invalid} required>
        <Field.Label>Username</Field.Label>
        <Input placeholder="astro_naut" />
        {invalid ? (
          <Field.ErrorText>That username is already taken.</Field.ErrorText>
        ) : (
          <Field.HelpText>Letters, numbers and underscores only.</Field.HelpText>
        )}
      </Field>
    </VStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `invalid` | boolean | `false` | Error styling + `aria-invalid` on the child input. |
| `disabled` | boolean | `false` | Disables the child input. |
| `required` | boolean | `false` | Appends `*` to the label, sets `aria-required`. |
| `readOnly` | boolean | `false` | Read-only state. |
| `id` | string | `auto` | Explicit id for the label/input pair. |

`Field.Label`, `Field.HelpText` and `Field.ErrorText` accept their native
element attributes.

## Custom controls

`useFieldContext()` gives a control of your own the same wiring the built-in
inputs get. It returns `null` outside a Field, so the control still works on
its own.

```tsx
import { Field, useFieldContext } from "astralis-ui";

function ColorInput(props: React.ComponentProps<"input">) {
  const field = useFieldContext();
  return (
    <input
      type="color"
      id={field?.id}
      aria-describedby={field?.describedBy}
      aria-invalid={field?.invalid || undefined}
      disabled={field?.disabled}
      required={field?.required}
      {...props}
    />
  );
}

<Field required>
  <Field.Label>Brand color</Field.Label>
  <ColorInput />
  <Field.HelpText>Used for buttons and links.</Field.HelpText>
</Field>
```

| Value | Type | Description |
| --- | --- | --- |
| `id` | `string` | The id `Field.Label` points at. Put it on the focusable element. |
| `describedBy` | `string \| undefined` | Ids of the help and error text currently shown, for `aria-describedby`. |
| `labelledBy` | `string \| undefined` | Id of the rendered label, for controls a `<label for>` can't name, such as a radio group. |
| `invalid` · `disabled` · `required` · `readOnly` | `boolean \| undefined` | The Field's state flags. |

## Accessibility

- The label's `htmlFor` and the input's `id` are wired automatically.
- `Field.ErrorText` renders with `role="alert"` and `aria-live="polite"`, so
  screen readers announce validation failures as they happen.

---

<!-- Data Entry / Checkbox: /docs/components/checkbox -->

# Checkbox

Multi-select control with indeterminate state and a managed group.

```tsx
"use client";

import { Checkbox } from "astralis-ui";

export function CheckboxDemo() {
  return <Checkbox defaultChecked>Email me about product updates</Checkbox>;
}
```

## Import

```tsx
import { Checkbox } from "astralis-ui";
// Checkbox.Group
```

## Group

`Checkbox.Group` manages the array for you. Give each checkbox a `value`
and read `onChange(string[])`.

```tsx
"use client";

import { useState } from "react";
import { Checkbox, Text, VStack } from "astralis-ui";

export function CheckboxGroup() {
  const [selected, setSelected] = useState<string[]>(["react"]);

  return (
    <VStack gap="3" alignItems="start">
      <Checkbox.Group value={selected} onChange={setSelected}>
        <Checkbox value="react">React</Checkbox>
        <Checkbox value="vue">Vue</Checkbox>
        <Checkbox value="svelte">Svelte</Checkbox>
      </Checkbox.Group>
      <Text size="xs" color="muted">
        Selected: {selected.length ? selected.join(", ") : "none"}
      </Text>
    </VStack>
  );
}
```

## Sizes, colors and states

`indeterminate` shows the dash, the classic "some children selected"
signal for select-all rows.

```tsx
"use client";

import { Checkbox, HStack, VStack } from "astralis-ui";

export function CheckboxStates() {
  return (
    <VStack gap="4" alignItems="start">
      <HStack gap="5">
        <Checkbox size="sm" defaultChecked>sm</Checkbox>
        <Checkbox size="md" defaultChecked>md</Checkbox>
        <Checkbox size="lg" defaultChecked>lg</Checkbox>
      </HStack>
      <HStack gap="5">
        <Checkbox colorScheme="green" defaultChecked>green</Checkbox>
        <Checkbox colorScheme="purple" defaultChecked>purple</Checkbox>
        <Checkbox indeterminate>indeterminate</Checkbox>
        <Checkbox disabled defaultChecked>disabled</Checkbox>
      </HStack>
    </VStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked / defaultChecked / onChange` | boolean / boolean / (e) => void | `None / false / None` | Controlled / uncontrolled API. |
| `value` | string | None | Identifies the checkbox inside a Group. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Box size. |
| `colorScheme` | all 15 schemes | `"brand"` | Checked hue. |
| `indeterminate` | boolean | `false` | Dash instead of check. |
| `invalid / disabled / readOnly` | boolean | `false` | State flags, inherited from [Field](/docs/components/field). |

### Checkbox.Group

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value / defaultValue / onValueChange` | string[] / string[] / (value: string[]) => void | `None / [] / None` | Controlled / uncontrolled selection. onChange still fires too, but is deprecated. |
| `orientation` | "horizontal" \| "vertical" | `"vertical"` | Lays the checkboxes out in a row or a column. |
| `colorScheme` | all 15 schemes | None | Hue of every checkbox in the group; each can still override it. |
| `disabled` | boolean | `false` | Disables every checkbox in the group. |

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Move between checkboxes. Each is its own tab stop |
| `Space` | Toggle the focused checkbox |

## Accessibility

A real `<input type="checkbox">` lives under the styled box, so keyboard,
form submission and screen-reader behavior all come natively.

---

<!-- Data Entry / Radio: /docs/components/radio -->

# Radio

Single-select options, managed by a group with automatic name wiring.

```tsx
"use client";

import { useState } from "react";
import { Radio, Text, VStack } from "astralis-ui";

export function RadioDemo() {
  const [plan, setPlan] = useState("pro");

  return (
    <VStack gap="3" alignItems="start">
      <Radio.Group value={plan} onChange={setPlan}>
        <Radio value="free">Free: 3 projects</Radio>
        <Radio value="pro">Pro: unlimited projects</Radio>
        <Radio value="team">Team: everything, plus SSO</Radio>
      </Radio.Group>
      <Text size="xs" color="muted">Selected plan: {plan}</Text>
    </VStack>
  );
}
```

## Import

```tsx
import { Radio } from "astralis-ui";
// Radio.Group
```

## Usage

Always wrap radios in `Radio.Group`: it holds the selected `value`, shares
one auto-generated `name` so the browser treats them as a set, and fires
`onChange(value)` with the plain string.

## Orientation, sizes and states

```tsx
"use client";

import { Radio, VStack } from "astralis-ui";

export function RadioHorizontal() {
  return (
    <VStack gap="4" alignItems="start">
      <Radio.Group defaultValue="md" orientation="horizontal" colorScheme="teal">
        <Radio value="sm" size="sm">Small</Radio>
        <Radio value="md">Medium</Radio>
        <Radio value="lg" size="lg">Large</Radio>
      </Radio.Group>
      <Radio.Group defaultValue="a" orientation="horizontal" disabled>
        <Radio value="a">Disabled group</Radio>
        <Radio value="b">Also disabled</Radio>
      </Radio.Group>
    </VStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string \| number | None | Required; identifies the option. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Circle size. |
| `colorScheme` | all 15 schemes | `"brand"` | Selected hue. |
| `invalid / disabled / readOnly` | boolean | `false` | State flags, inherited from [Field](/docs/components/field). |

### Radio.Group

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value / defaultValue / onValueChange` | string / string / (value: string) => void | None | Controlled / uncontrolled selection. onChange still fires too, but is deprecated. |
| `name` | string | `generated` | Name shared by the radios in the set. |
| `orientation` | "horizontal" \| "vertical" | `"vertical"` | Lays the radios out in a row or a column. |
| `colorScheme` | all 15 schemes | None | Hue of every radio in the group; each can still override it. |
| `disabled` | boolean | `false` | Disables every radio in the group. |

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Into the group: one tab stop (the selected option) |
| `←` `↑` / `→` `↓` | Move selection between options |
| `Space` | Select the focused option (when none is selected yet) |

## Accessibility

The group renders `role="radiogroup"` over real `<input type="radio">`
elements: arrow-key movement between options is native browser behavior.

---

<!-- Data Entry / Switch: /docs/components/switch -->

# Switch

A binary toggle with real switch semantics, for settings that apply immediately.

```tsx
"use client";

import { useState } from "react";
import { Switch } from "astralis-ui";

export function SwitchDemo() {
  const [isPublic, setIsPublic] = useState(false);

  return (
    <Switch checked={isPublic} onChange={(e) => setIsPublic(e.target.checked)}>
      {isPublic ? "Profile is public" : "Profile is private"}
    </Switch>
  );
}
```

## Import

```tsx
import { Switch } from "astralis-ui";
```

## Usage

Use a Switch when flipping it takes effect immediately (settings); use a
[Checkbox](/docs/components/checkbox) when the choice is submitted with a
form. The API is the native checkbox event model: `checked` +
`onChange(e)` reading `e.target.checked`.

## Sizes, colors and states

```tsx
"use client";

import { Switch, HStack, VStack } from "astralis-ui";

export function SwitchStates() {
  return (
    <VStack gap="4" alignItems="start">
      <HStack gap="5">
        <Switch size="sm" defaultChecked>sm</Switch>
        <Switch size="md" defaultChecked>md</Switch>
        <Switch size="lg" defaultChecked>lg</Switch>
      </HStack>
      <HStack gap="5">
        <Switch colorScheme="green" defaultChecked>green</Switch>
        <Switch colorScheme="orange" defaultChecked>orange</Switch>
        <Switch disabled>disabled</Switch>
        <Switch disabled defaultChecked>disabled on</Switch>
      </HStack>
    </VStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked / defaultChecked / onChange` | boolean / boolean / (e) => void | `None / false / None` | Controlled / uncontrolled API. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Track and thumb dimensions. |
| `colorScheme` | all 15 schemes | `"brand"` | On-state hue. |
| `children` | ReactNode | None | Label rendered beside the track. |
| `invalid / disabled / readOnly` | boolean | `false` | State flags, inherited from [Field](/docs/components/field). |

## Keyboard

| Key | Action |
| --- | --- |
| `Space` | Toggle |

## Accessibility

Renders `<input type="checkbox" role="switch">` with `aria-checked`, so
assistive tech announces it as an on/off switch, not a checkbox.

---

<!-- Data Entry / Select: /docs/components/select -->

# Select

A custom dropdown with search, groups, clearing, and full keyboard navigation.

```tsx
"use client";

import { useState } from "react";
import { Select, Box } from "astralis-ui";

const options = [
  { value: "figma", label: "Figma" },
  { value: "sketch", label: "Sketch" },
  { value: "penpot", label: "Penpot" },
];

export function SelectDemo() {
  const [tool, setTool] = useState<string | number | null>(null);

  return (
    <Box w="full" maxW="3xs">
      <Select
        options={options}
        value={tool}
        onChange={setTool}
        placeholder="Pick a design tool"
      />
    </Box>
  );
}
```

## Import

```tsx
import { Select } from "astralis-ui";
```

## Usage

Options come in as data (flat `{ value, label }` items or
`{ group, options }` sections), and the dropdown portals out of any
`overflow: hidden` ancestor, so it works inside cards and modals.

## Searchable, clearable, grouped

```tsx
"use client";

import { Select, Box } from "astralis-ui";

const options = [
  {
    group: "Frontend",
    options: [
      { value: "react", label: "React" },
      { value: "vue", label: "Vue" },
      { value: "svelte", label: "Svelte" },
    ],
  },
  {
    group: "Backend",
    options: [
      { value: "node", label: "Node.js" },
      { value: "elixir", label: "Elixir" },
      { value: "go", label: "Go" },
    ],
  },
];

export function SelectSearchable() {
  return (
    <Box w="full" maxW="3xs">
      <Select
        options={options}
        searchable
        clearable
        placeholder="Search frameworks…"
      />
    </Box>
  );
}
```

## States

```tsx
"use client";

import { Select, Text, VStack } from "astralis-ui";

const options = [{ value: "one", label: "Option one" }];

export function SelectStates() {
  return (
    <VStack gap="4" alignItems="stretch" w="full" maxW="3xs">
      <VStack gap="1" alignItems="stretch">
        <Text as="span" size="xs" color="muted">filled variant</Text>
        <Select options={options} variant="filled" placeholder="Filled" />
      </VStack>
      <VStack gap="1" alignItems="stretch">
        <Text as="span" size="xs" color="muted">loading</Text>
        <Select options={[]} loading placeholder="Fetching options…" />
      </VStack>
      <VStack gap="1" alignItems="stretch">
        <Text as="span" size="xs" color="muted">invalid</Text>
        <Select options={options} invalid placeholder="Required field" />
      </VStack>
      <VStack gap="1" alignItems="stretch">
        <Text as="span" size="xs" color="muted">disabled</Text>
        <Select options={options} disabled placeholder="Unavailable" />
      </VStack>
    </VStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | { value, label }[] or { group, options }[] | `[]` | The option data. |
| `value / defaultValue / onChange` | string \| number \| null / same / (value) => void | `None / null / None` | Controlled / uncontrolled API. |
| `placeholder` | string | `"Select an option"` | Trigger text when empty. |
| `searchable` | boolean | `false` | Filter input inside the dropdown. |
| `clearable` | boolean | `false` | × button when a value is selected (also fires `onClear`). |
| `loading` | boolean | `false` | A spinning arc instead of the chevron. |
| `emptyText` | string | `"No options"` | Shown when nothing matches. |
| `name` | string | None | Renders a hidden input so the value submits with native `<form>`s. |
| `variant / size` | "outline" \| "filled" / "sm" \| "md" \| "lg" | `"outline" / "md"` | Styling. |
| `colorScheme` | all 15 schemes | `"brand"` | Highlight and focus-ring hue. |
| `invalid / disabled / readOnly` | boolean | `false` | State flags, inherited from [Field](/docs/components/field). |

## Keyboard

| Key | Action |
| --- | --- |
| `Enter` / `Space` | Open; when open, select the highlighted option |
| `↓` | Open when closed; move the highlight down |
| `↑` | Move the highlight up |
| *type* (with `searchable`) | Filter the options |
| `Esc` | Close and refocus the trigger |
| `Tab` | Close and move on |

## Accessibility

- The trigger is a `combobox` with `aria-haspopup="listbox"` and
  `aria-expanded`; options carry `role="option"`.
- Selecting an option returns focus to the trigger.

---

<!-- Data Entry / MultiSelect: /docs/components/multi-select -->

# MultiSelect

Multi-value selection with removable tags, inline search, and an optional cap.

```tsx
"use client";

import { useState } from "react";
import { MultiSelect, Box } from "astralis-ui";

const skills = [
  { value: "ts", label: "TypeScript" },
  { value: "react", label: "React" },
  { value: "css", label: "CSS" },
  { value: "a11y", label: "Accessibility" },
  { value: "testing", label: "Testing" },
];

export function MultiSelectDemo() {
  const [selected, setSelected] = useState<Array<string | number>>(["ts", "react"]);

  return (
    <Box w="full" maxW="xs">
      <MultiSelect
        options={skills}
        value={selected}
        onChange={setSelected}
        placeholder="Pick your skills…"
      />
    </Box>
  );
}
```

## Import

```tsx
import { MultiSelect } from "astralis-ui";
```

## Usage

Selections render as removable chips in the trigger; typing filters the
options, and Backspace with an empty search removes the last chip: the
interaction set people know from tag pickers.

## Max and disabled options

```tsx
"use client";

import { MultiSelect, Box } from "astralis-ui";

const toppings = [
  { value: "mushroom", label: "Mushroom" },
  { value: "olive", label: "Olive" },
  { value: "basil", label: "Basil" },
  { value: "pepper", label: "Pepper" },
  { value: "onion", label: "Onion" },
  { value: "pineapple", label: "Pineapple", disabled: true },
];

export function MultiSelectMax() {
  return (
    <Box w="full" maxW="xs">
      {/* Capped at 3; the disabled option can't be chosen at all. */}
      <MultiSelect
        options={toppings}
        max={3}
        clearable
        colorScheme="green"
        placeholder="Up to three toppings…"
      />
    </Box>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | { value, label, disabled? }[] or grouped | `[]` | Option data; same group shape as [Select](/docs/components/select). |
| `value / defaultValue / onChange` | Array<string \| number> / same / (values) => void | `None / [] / None` | Controlled / uncontrolled API. |
| `max` | number | None | Cap on selected items. |
| `clearable` | boolean | `false` | Clear-all button. |
| `name` | string | None | Renders one hidden input per selected value (repeated name) for native `<form>` submission. |
| `placeholder / emptyText / loading` | string / string / boolean | None | Same behavior as Select. |
| `variant / size / colorScheme` | "outline" \| "filled" \| "underline" \| "unstyled" / "sm" \| "md" \| "lg" / ColorScheme | `"outline" / "md" / "brand"` | Styling; colorScheme tints the tags. |
| `invalid / disabled / readOnly` | boolean | `false` | State flags, inherited from [Field](/docs/components/field). |

## Keyboard

| Key | Action |
| --- | --- |
| `↓` | Open when closed; move the highlight down |
| `↑` | Move the highlight up |
| `Enter` | Open; when open, toggle the highlighted option |
| *type* | Filter the options (typing also opens the list) |
| `Backspace` (empty input) | Remove the last selected chip |
| `Esc` | Close |
| `Tab` | Close and move on |

## Accessibility

Options carry `role="option"` in a portalled listbox with
`aria-multiselectable`; chip remove buttons stay out of the tab order:
Backspace is the keyboard path.

---

<!-- Data Entry / Pin Input: /docs/components/pin-input -->

# Pin Input

OTP and PIN entry with auto-advance, smart backspace, and paste spreading.

```tsx
"use client";

import { useState } from "react";
import { PinInput, Text, VStack } from "astralis-ui";

export function PinInputDemo() {
  const [done, setDone] = useState(false);

  return (
    <VStack gap="3" alignItems="start">
      <PinInput length={4} onComplete={() => setDone(true)} onChange={() => setDone(false)} />
      <Text size="xs" color={done ? "success" : "muted"}>
        {done ? "Code complete, verifying…" : "Paste works too. Try it."}
      </Text>
    </VStack>
  );
}
```

## Import

```tsx
import { PinInput } from "astralis-ui";
```

## Usage

Typing advances to the next box, Backspace at an empty box steps back and
clears, and pasting a full code spreads it across the boxes. `onChange`
receives the combined string on every keystroke; `onComplete` fires once
every box is filled, the natural hook for auto-submitting a verification
code.

## Masking, types and sizes

```tsx
"use client";

import { PinInput, Text, VStack } from "astralis-ui";

export function PinInputMask() {
  return (
    <VStack gap="5" alignItems="start">
      <VStack gap="1" alignItems="start">
        <Text as="span" size="xs" color="muted">masked, 6 digits, filled</Text>
        <PinInput length={6} mask variant="filled" />
      </VStack>
      <VStack gap="1" alignItems="start">
        <Text as="span" size="xs" color="muted">alphanumeric, size lg</Text>
        <PinInput length={5} type="alphanumeric" size="lg" placeholder="•" />
      </VStack>
    </VStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `length` | number | `4` | Number of boxes. |
| `value / defaultValue / onChange` | string / string / (value: string) => void | `None / "" / None` | The combined code. |
| `onComplete` | (value: string) => void | None | Fires when all boxes are filled. |
| `type` | "numeric" \| "alpha" \| "alphanumeric" | `"numeric"` | Character validation. |
| `mask` | boolean | `false` | Bullet display, password-style. |
| `variant / size` | "outline" \| "filled" / "sm" \| "md" \| "lg" | `"outline" / "md"` | Styling. |
| `placeholder` | string | `"○"` | Shown in empty boxes. |
| `autoFocus` | boolean | `false` | Focus the first box on mount. |
| `invalid / disabled / readOnly` | boolean | `false` | State flags, inherited from [Field](/docs/components/field). |

## Keyboard

| Key | Action |
| --- | --- |
| *type a character* | Fill the box and advance to the next |
| `Backspace` | Clear the box; if already empty, move back and clear that one |
| `Delete` | Clear the current box (no movement) |
| `←` / `→` | Move between boxes without clearing |
| *paste* | Distribute the pasted characters across the boxes |

## Accessibility

Each box is a real input with a per-cell label ("digit 1 of 4"), reachable
with Tab/Shift-Tab; focusing a box selects its content so typing replaces.

---

<!-- Data Entry / Slider: /docs/components/slider -->

# Slider

Single and dual-thumb range controls with marks, tooltips and keyboard support.

```tsx
"use client";

import { useState } from "react";
import { Slider, Text, VStack } from "astralis-ui";

export function SliderDemo() {
  const [volume, setVolume] = useState(40);

  return (
    <VStack gap="3" alignItems="stretch" w="full" maxW="xs">
      <Slider value={volume} onChange={setVolume} />
      <Text size="xs" color="muted">Volume: {volume}%</Text>
    </VStack>
  );
}
```

## Import

```tsx
import { Slider, RangeSlider } from "astralis-ui";
```

## Marks

`marks` accepts `true` for auto-marks at every step, or an array with
optional labels for the ones worth naming.

```tsx
"use client";

import { Slider, Box } from "astralis-ui";

export function SliderMarks() {
  return (
    <Box w="full" maxW="xs" pb="4">
      <Slider
        min={0}
        max={100}
        step={25}
        defaultValue={50}
        colorScheme="purple"
        marks={[
          { value: 0, label: "Off" },
          { value: 25 },
          { value: 50, label: "Balanced" },
          { value: 75 },
          { value: 100, label: "Max" },
        ]}
      />
    </Box>
  );
}
```

## Range

`RangeSlider` is the dual-thumb sibling: same props, tuple value.

```tsx
"use client";

import { useState } from "react";
import { RangeSlider, Text, VStack } from "astralis-ui";

export function SliderRange() {
  const [range, setRange] = useState<[number, number]>([200, 600]);

  return (
    <VStack gap="3" alignItems="stretch" w="full" maxW="xs">
      <RangeSlider min={0} max={1000} step={50} value={range} onChange={setRange} />
      <Text size="xs" color="muted">
        Price: ${range[0]} – ${range[1]}
      </Text>
    </VStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `min / max / step` | number | `0 / 100 / 1` | The scale. |
| `value / defaultValue / onChange` | number (Slider) or [number, number] (RangeSlider) | None | Controlled / uncontrolled API. |
| `marks` | boolean \| { value, label? }[] | None | Tick marks, optionally labeled. |
| `showTooltip` | boolean | `true` | Value tooltip on the thumb. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Track and thumb scale. |
| `colorScheme` | all 15 schemes | `"brand"` | Filled-track and thumb hue. |
| `invalid / disabled / readOnly` | boolean | `false` | State flags, inherited from [Field](/docs/components/field). |

## Keyboard

| Key | Action |
| --- | --- |
| `→` / `↑` | Increase by `step` |
| `←` / `↓` | Decrease by `step` |
| `Home` / `End` | Jump to `min` / `max` |

## Accessibility

Thumbs render `role="slider"` with `aria-valuemin/max/now`; RangeSlider's
two thumbs are each independently focusable and clamp against each other.

---

<!-- Data Entry / Textarea: /docs/components/textarea -->

# Textarea

A multi-line text field with variants, character count, and Field integration.

```tsx
import { Textarea, VStack } from "astralis-ui";

export function TextareaDemo() {
  return (
    <VStack gap="4" alignItems="stretch" w="full" maxW="md">
      <Textarea placeholder="Tell us about your mission…" />
      <Textarea placeholder="With a character count" showCount maxLength={200} defaultValue="Astralis launches in T-minus…" />
      <Textarea placeholder="Filled variant" variant="filled" rows={2} />
    </VStack>
  );
}
```

## Import

```tsx
import { Textarea } from "astralis-ui";
// also available as Input.TextArea
```

## Auto-grow

`autoGrow` lets the field grow with its content instead of scrolling. It uses
the CSS `field-sizing` property, so there is no resize listener; `rows` sets
the starting height. Browsers without `field-sizing` keep a normal scrolling
textarea.

```tsx
import { Box, Textarea } from "astralis-ui";

export function TextareaAutoGrow() {
  return (
    <Box w="full" maxW="md">
      <Textarea autoGrow rows={2} placeholder="Keep typing: the field grows with each new line" />
    </Box>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Text and padding scale. |
| `variant` | "outline" \| "filled" \| "underline" \| "unstyled" | `"outline"` | Visual style. |
| `rows` | number | `4` | Initial visible lines. |
| `autoGrow` | boolean | `false` | Grows with its content instead of scrolling, using CSS field-sizing with no JavaScript. rows becomes the minimum height. |
| `showCount` | boolean | `false` | Character counter (pairs with `maxLength`). |
| `invalid / disabled / readOnly` | boolean | `from [Field](/docs/components/field)` | State plumbing. |

Inside a [Field](/docs/components/field), the label association, `required`,
and help/error `aria-describedby` wiring all come for free.

---

<!-- Data Entry / Number Input: /docs/components/number-input -->

# Number Input

A numeric field with steppers, clamping, and spinbutton keyboard support.

```tsx
import { NumberInput, VStack } from "astralis-ui";

export function NumberInputDemo() {
  return (
    <VStack gap="4" alignItems="stretch" w="full" maxW="56">
      <NumberInput defaultValue={4} min={0} max={10} aria-label="Crew size" />
      <NumberInput defaultValue={2.5} step={0.5} precision={1} aria-label="Thrust (0.5 steps)" />
      <NumberInput defaultValue={7} hideSteppers aria-label="No steppers" />
      <NumberInput defaultValue={3} disabled aria-label="Disabled" />
    </VStack>
  );
}
```

## Import

```tsx
import { NumberInput } from "astralis-ui";
```

Typing is free-form: the value parses, clamps to `min`/`max`, and rounds to
`precision` when you commit (blur, Enter, or the steppers). `onChange`
receives the committed `number`, or `null` when cleared.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value / defaultValue` | number \| null | None | Controlled / uncontrolled value. |
| `onChange` | (value: number \| null) => void | None | Fires on commit. |
| `min / max` | number | None | Clamping bounds (also `aria-valuemin/max`). |
| `step` | number | `1` | Arrow/stepper increment. |
| `precision` | number | None | Decimal places on commit. |
| `hideSteppers` | boolean | `false` | Remove the +/− buttons. |
| `size / variant / invalid` | as Input | `as Input` | Shares the Input styling system. |

## Keyboard

| Key | Action |
| --- | --- |
| `↑` / `↓` | ± `step` (clamped) |
| `Home` / `End` | Jump to `min` / `max` |
| `Enter` | Commit the typed value |

## Accessibility

Renders `role="spinbutton"` with `aria-valuemin/max/now` and inherits label
and description wiring from [Field](/docs/components/field). The stepper
buttons are excluded from the tab order: keyboard users get arrows, which
are faster.

---

<!-- Data Entry / Combobox: /docs/components/combobox -->

# Combobox

A filterable single-value picker on the ARIA combobox pattern.

```tsx
import { Combobox, VStack } from "astralis-ui";

const FRAMEWORKS = [
  { label: "Next.js", value: "next" },
  { label: "Remix", value: "remix" },
  { label: "Astro", value: "astro" },
  { label: "Vite", value: "vite" },
  { label: "Gatsby", value: "gatsby", disabled: true },
];

const GROUPED = [
  { group: "Planets", options: [
    { label: "Mercury", value: "mercury" },
    { label: "Venus", value: "venus" },
    { label: "Mars", value: "mars" },
  ]},
  { group: "Moons", options: [
    { label: "Europa", value: "europa" },
    { label: "Titan", value: "titan" },
  ]},
];

export function ComboboxDemo() {
  return (
    <VStack gap="4" alignItems="stretch" w="full" maxW="sm">
      <Combobox options={FRAMEWORKS} placeholder="Pick a framework…" clearable />
      <Combobox options={GROUPED} placeholder="Grouped options…" defaultValue="europa" clearable />
    </VStack>
  );
}
```

## Import

```tsx
import { Combobox } from "astralis-ui";
```

Type to filter, arrows to move, Enter to commit, Escape to revert to the
last committed selection. Reopening on a committed value shows the **full**
list. Filtering only kicks in once you type.

Compared to [Select](/docs/components/select): Select is a button you pick
from; Combobox is an input you search in. For multiple values, use
[MultiSelect](/docs/components/multi-select). All three share the same
option machinery, so `options` shapes are interchangeable.

## Free-form values

By default the options are a closed set: text that matches nothing reverts on
blur. With `allowCustomValue` they become suggestions, and whatever the user
typed commits as the value on Tab, on blur, or on Enter when no option is
highlighted. Text that exactly matches an option's label commits that option,
and Escape still reverts.

```tsx
import { Combobox } from "astralis-ui";

const LABELS = [
  { label: "bug", value: "bug" },
  { label: "design", value: "design" },
  { label: "docs", value: "docs" },
  { label: "performance", value: "performance" },
];

export function ComboboxCustomValue() {
  return (
    <Combobox
      options={LABELS}
      allowCustomValue
      placeholder="Pick a label or type a new one…"
      clearable
      w="full"
      maxW="sm"
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | Array<{label, value, disabled?} \| {group, options}> | `[]` | Flat or grouped options. |
| `value / defaultValue` | string \| number \| null | None | Controlled / uncontrolled selection; null means nothing is selected. |
| `onChange` | (value) => void | None | Fires on commit (pick or clear). |
| `onInputChange` | (text) => void | None | Fires on every filter keystroke. |
| `placeholder` | string | None | Input text shown while nothing is typed or selected. |
| `allowCustomValue` | boolean | `false` | Typed text that matches no option commits as the value, so the options become suggestions. Tab, blur, or Enter with nothing highlighted commits; Escape reverts. |
| `clearable` | boolean | `false` | ✕ button when a value is selected. |
| `emptyText` | string | `"No matches"` | Shown when nothing matches. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Field height and text size, matching Input. |
| `variant` | "outline" \| "filled" \| "underline" \| "unstyled" | `"outline"` | Field chrome, matching Input. |
| `colorScheme` | all 15 schemes | `"brand"` | Hue for the focus ring and the highlighted option. |
| `loading` | boolean | `false` | Shows a spinner and disables the input while options load. |
| `invalid` | boolean | `false` | Error styling and aria-invalid. Inherited inside a Field. |
| `disabled` | boolean | `false` | Blocks interaction. Inherited inside a Field. |
| `readOnly` | boolean | `false` | Shows the value but can't be changed. |
| `name` | string | None | Hidden input for native form submission. |

## Keyboard

| Key | Action |
| --- | --- |
| *type* | Filter the options |
| `↓` | Open when closed; move the highlight down |
| `↑` | Move the highlight up |
| `Enter` | Commit the highlighted option |
| `Esc` | Close and revert to the last committed value |
| `Tab` | Close, revert, and move on |

## Accessibility

`role="combobox"` with `aria-autocomplete="list"`, `aria-expanded`,
`aria-controls` and `aria-activedescendant` tracking the highlighted option:
the screen reader follows the highlight while focus stays in the input.
Label/description wiring comes from [Field](/docs/components/field).

---

<!-- Data Entry / Segmented Control: /docs/components/segmented-control -->

# Segmented Control

A single-choice control styled as connected segments, the classic "view
switcher". Under the styling it is a group of native radios (visually hidden),
so arrow-key movement, form participation and radio semantics come from the
platform, not from JavaScript re-implementations.

```tsx
import { SegmentedControl } from "astralis-ui";

export function SegmentedControlDemo() {
  return (
    <SegmentedControl defaultValue="list" aria-label="View">
      <SegmentedControl.Item value="list">List</SegmentedControl.Item>
      <SegmentedControl.Item value="grid">Grid</SegmentedControl.Item>
      <SegmentedControl.Item value="table">Table</SegmentedControl.Item>
    </SegmentedControl>
  );
}
```

## Import

```tsx
import { SegmentedControl } from "astralis-ui";
```

## Sizes

```tsx
import { SegmentedControl, VStack } from "astralis-ui";

export function SegmentedControlSizes() {
  return (
    <VStack gap="4" alignItems="start">
      {(["sm", "md", "lg"] as const).map((size) => (
        <SegmentedControl key={size} size={size} defaultValue="week" aria-label={`Range (${size})`}>
          <SegmentedControl.Item value="day">Day</SegmentedControl.Item>
          <SegmentedControl.Item value="week">Week</SegmentedControl.Item>
          <SegmentedControl.Item value="month">Month</SegmentedControl.Item>
        </SegmentedControl>
      ))}
    </VStack>
  );
}
```

## Full width

`fullWidth` stretches the track and shares the width equally between segments:

```tsx
import { SegmentedControl, Box } from "astralis-ui";

export function SegmentedControlFullWidth() {
  return (
    <Box w="full" maxW="md">
      <SegmentedControl fullWidth defaultValue="preview" aria-label="Mode">
        <SegmentedControl.Item value="edit">Edit</SegmentedControl.Item>
        <SegmentedControl.Item value="preview">Preview</SegmentedControl.Item>
      </SegmentedControl>
    </Box>
  );
}
```

## Segmented Control vs Tabs vs CheckableTag

- **SegmentedControl**: one value from a few, radio semantics, no panels.
- **[Tabs](/docs/components/tabs)**: switches visible *content panels*.
- **[CheckableTag](/docs/components/tag)**: chip-shaped multi/single select
  for filtering, wraps freely.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value / defaultValue / onChange` | string / string / (value: string) => void | None | Controlled / uncontrolled selection. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Segment height and text size. |
| `fullWidth` | boolean | `false` | Stretches to the container, sharing the width equally between segments. |
| `disabled` | boolean | `false` | Disables every segment. |
| `name` | string | `generated` | Name of the segment radios, so the choice submits with a native form. |

### SegmentedControl.Item

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | None | The value this segment represents. Required. |
| `children` | ReactNode | None | Segment label. |
| `disabled` | boolean | `false` | Disables just this segment. |

## Keyboard

The segments are native radios, so the keys are the browser's own:

| Key | Action |
| --- | --- |
| `Tab` | Into the control: one tab stop, on the selected segment |
| `←` `↑` / `→` `↓` | Select the previous / next segment |
| `Space` | Select the focused segment, when none is selected yet |

---

<!-- Data Entry / Rating: /docs/components/rating -->

# Rating

Star rating. Interactive mode is a radiogroup of native radios (visually
hidden), so arrow keys, form participation and announcements come from the
platform. Selection is whole stars. Display mode (`readOnly`) renders
fractional values like `4.5` as half-filled stars.

```tsx
import { Rating } from "astralis-ui";

export function RatingDemo() {
  return <Rating defaultValue={3} label="Rate this product" />;
}
```

## Import

```tsx
import { Rating } from "astralis-ui";
```

## Read-only display

`readOnly` swaps the radios for a static `img`-role display. This is where
fractional averages belong:

```tsx
import { Rating, HStack, Text } from "astralis-ui";

export function RatingReadOnly() {
  return (
    <HStack gap="3">
      <Rating value={4.5} readOnly />
      <Text size="sm" color="muted">
        4.5 · 1,238 reviews
      </Text>
    </HStack>
  );
}
```

## Sizes

```tsx
import { Rating, VStack } from "astralis-ui";

export function RatingSizes() {
  return (
    <VStack gap="3" alignItems="start">
      <Rating size="sm" defaultValue={3} label="Small rating" />
      <Rating size="md" defaultValue={3} label="Medium rating" />
      <Rating size="lg" defaultValue={3} label="Large rating" />
    </VStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value / defaultValue / onChange` | number / number / (value: number) => void | `None / 0 / None` | Controlled / uncontrolled value. Fractions such as 4.5 render only in readOnly mode. |
| `max` | number | `5` | Number of stars. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Star size. |
| `colorScheme` | all 15 schemes | `"yellow"` | Hue of the filled stars. |
| `readOnly` | boolean | `false` | Static display with an img role, including half stars. |
| `disabled` | boolean | `false` | Blocks interaction. |
| `label` | string | `"Rating"` | Accessible name of the radio group. Without one, a surrounding Field's label names it. |
| `name` | string | `generated` | Name of the star radios, so the rating submits with a native form. |

## Keyboard

The stars are native radios, so the keys are the browser's own:

| Key | Action |
| --- | --- |
| `Tab` | Into the rating: one tab stop, on the selected star |
| `←` `↑` / `→` `↓` | Select one star fewer / more |
| `Space` | Select the focused star, when none is selected yet |

A `readOnly` rating is an image, not a control, so it takes no focus.

---

<!-- Data Entry / Native Select: /docs/components/native-select -->

# Native Select

A styled native `<select>`. The dropdown, keyboard handling, typeahead and
mobile pickers are the platform's own: no popup re-implementation. Reach for
[Select](/docs/components/select) when options need custom rendering; reach
for this when they don't.

```tsx
import { NativeSelect, Box } from "astralis-ui";

export function NativeSelectDemo() {
  return (
    <Box w="full" maxW="xs">
      <NativeSelect placeholder="Pick a framework" aria-label="Framework">
        <option value="next">Next.js</option>
        <option value="remix">Remix</option>
        <option value="vite">Vite</option>
        <option value="astro">Astro</option>
      </NativeSelect>
    </Box>
  );
}
```

## Import

```tsx
import { NativeSelect } from "astralis-ui";
```

## Variants and states

The chrome mirrors Input's `outline`/`filled` taxonomy:

```tsx
import { NativeSelect, VStack } from "astralis-ui";

export function NativeSelectVariants() {
  return (
    <VStack gap="4" w="full" maxW="xs" alignItems="stretch">
      <NativeSelect variant="outline" defaultValue="outline" aria-label="Outline variant">
        <option value="outline">Outline (default)</option>
      </NativeSelect>
      <NativeSelect variant="filled" defaultValue="filled" aria-label="Filled variant">
        <option value="filled">Filled</option>
      </NativeSelect>
      <NativeSelect invalid defaultValue="invalid" aria-label="Invalid state">
        <option value="invalid">Invalid</option>
      </NativeSelect>
      <NativeSelect disabled defaultValue="disabled" aria-label="Disabled state">
        <option value="disabled">Disabled</option>
      </NativeSelect>
    </VStack>
  );
}
```

## With Field

Inside a [Field](/docs/components/field), `id`, `describedBy`, `invalid` and
`disabled` are inherited automatically, like every other data-entry component.

## Props

Everything a native `<select>` accepts passes through. On top of that:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | ReactNode | None | Native option and optgroup elements. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Field height, matching Input. |
| `variant` | "outline" \| "filled" | `"outline"` | Field chrome, matching Input. |
| `placeholder` | string | None | A disabled empty option shown until a value is chosen. |
| `invalid` | boolean | `false` | Error styling and aria-invalid. Inherited inside a Field. |
| `disabled` | boolean | `false` | Blocks interaction. Inherited inside a Field. |

---

<!-- Data Entry / Checkbox Card: /docs/components/checkbox-card -->

# Checkbox Card

A card-shaped checkbox: the whole surface is the click target, with room for
a title, description and leading addon. It joins
[Checkbox.Group](/docs/components/checkbox) exactly like `Checkbox` does:
give it a `value` inside a group and selection accumulates.

```tsx
import { Checkbox, CheckboxCard, Grid } from "astralis-ui";

export function CheckboxCardDemo() {
  return (
    <Checkbox.Group defaultValue={["analytics"]}>
      <Grid columns={{ base: "1", sm: "3" }} gap="3" w="full" maxW="2xl">
        <CheckboxCard value="analytics" description="Traffic and conversion reports">
          Analytics
        </CheckboxCard>
        <CheckboxCard value="automation" description="Workflows and triggers">
          Automation
        </CheckboxCard>
        <CheckboxCard value="support" description="Shared inbox and live chat">
          Support
        </CheckboxCard>
      </Grid>
    </Checkbox.Group>
  );
}
```

## Import

```tsx
import { CheckboxCard, Checkbox } from "astralis-ui";
```

## Usage

Put the cards inside a [Checkbox.Group](/docs/components/checkbox) and give
each a `value`: the group owns the selection, so `defaultValue`,
`value`/`onValueChange` and `disabled` all work exactly as they do for plain
checkboxes. On its own, a card is a single checkbox with the native
`checked`/`defaultChecked` API.

`addon` puts an icon or avatar beside the copy, and `size="sm"` tightens the
card for dense settings lists. Because each card is a real checkbox, the
group submits with a native form and every card is its own tab stop.

```tsx
import { Checkbox, CheckboxCard, Icon, VStack } from "astralis-ui";
import { Bell, Mail, MessageSquare } from "lucide-react";

export function CheckboxCardAddon() {
  return (
    <Checkbox.Group defaultValue={["email"]}>
      <VStack gap="2" alignItems="stretch" w="full" maxW="sm">
        <CheckboxCard value="email" size="sm" addon={<Icon as={Mail} />} description="A digest every morning">
          Email
        </CheckboxCard>
        <CheckboxCard value="push" size="sm" addon={<Icon as={Bell} />} description="As things happen">
          Push notifications
        </CheckboxCard>
        <CheckboxCard value="sms" size="sm" addon={<Icon as={MessageSquare} />} description="Security alerts only" disabled>
          SMS
        </CheckboxCard>
      </VStack>
    </Checkbox.Group>
  );
}
```

## Props

Extends the native checkbox input's props, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | ReactNode | None | Card title. |
| `description` | ReactNode | None | Secondary line under the title. |
| `addon` | ReactNode | None | Leading slot for an icon or avatar. |
| `checked / defaultChecked / onChange` | boolean / boolean / (event) => void | None | The native checkbox API. Inside a Checkbox.Group, pass value instead. |
| `value` | string | None | Identifies the card inside a Checkbox.Group. |
| `indicator` | boolean | `true` | Shows a tick in the corner while checked. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Padding and text scale. |
| `colorScheme` | all 15 schemes | `"brand"` | Hue of the checked card. |
| `invalid` | boolean | `false` | Error styling and aria-invalid. |
| `disabled` | boolean | `false` | Blocks interaction. Inherited from a Checkbox.Group or Field. |

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` / `Shift+Tab` | Move to the next / previous card |
| `Space` | Toggle the focused card |

For single selection, use [Radio Card](/docs/components/radio-card).

---

<!-- Data Entry / Radio Card: /docs/components/radio-card -->

# Radio Card

A card-shaped radio: the whole surface is the click target, with room for a
title, description and leading addon. It joins
[Radio.Group](/docs/components/radio) exactly like `Radio` does: give it a
`value` inside a group for single selection.

```tsx
import { Radio, RadioCard, Grid } from "astralis-ui";

export function RadioCardDemo() {
  return (
    <Radio.Group defaultValue="pro">
      <Grid columns={{ base: "1", sm: "3" }} gap="3" w="full" maxW="2xl">
        <RadioCard value="free" description="For personal projects">
          Free
        </RadioCard>
        <RadioCard value="pro" description="For growing teams">
          Pro: $12/mo
        </RadioCard>
        <RadioCard value="enterprise" description="SSO, audit log, SLAs">
          Enterprise
        </RadioCard>
      </Grid>
    </Radio.Group>
  );
}
```

## Import

```tsx
import { RadioCard, Radio } from "astralis-ui";
```

## Usage

Put the cards inside a [Radio.Group](/docs/components/radio) and give each a
`value`. The group owns the selection and the shared `name`, so the choice
submits with a native form and the arrow keys move between cards like any
radio set. Reach for Radio Card over plain radios when each option needs a
description, such as a pricing plan or a delivery method.

```tsx
import { Icon, Radio, RadioCard, VStack } from "astralis-ui";
import { Bike, Car, Truck } from "lucide-react";

export function RadioCardAddon() {
  return (
    <Radio.Group defaultValue="standard" name="delivery">
      <VStack gap="2" alignItems="stretch" w="full" maxW="sm">
        <RadioCard value="courier" size="sm" addon={<Icon as={Bike} />} description="Within 2 hours, city centre only">
          Courier
        </RadioCard>
        <RadioCard value="standard" size="sm" addon={<Icon as={Car} />} description="Next working day">
          Standard
        </RadioCard>
        <RadioCard value="freight" size="sm" addon={<Icon as={Truck} />} description="Pallets and bulky items">
          Freight
        </RadioCard>
      </VStack>
    </Radio.Group>
  );
}
```

## Props

Extends the native radio input's props, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | ReactNode | None | Card title. |
| `description` | ReactNode | None | Secondary line under the title. |
| `addon` | ReactNode | None | Leading slot for an icon or avatar. |
| `value` | string | None | The value this card selects inside a Radio.Group. |
| `indicator` | boolean | `true` | Shows a tick in the corner while selected. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Padding and text scale. |
| `colorScheme` | all 15 schemes | `"brand"` | Hue of the selected card. |
| `invalid` | boolean | `false` | Error styling and aria-invalid. |
| `disabled` | boolean | `false` | Blocks selection. Inherited from a Radio.Group or Field. |

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Into the group: one tab stop, on the selected card |
| `←` `↑` / `→` `↓` | Select the previous / next card |
| `Space` | Select the focused card, when none is selected yet |

For multiple selection, use [Checkbox Card](/docs/components/checkbox-card).

---

<!-- Data Entry / Editable: /docs/components/editable -->

# Editable

Click-to-edit text for titles, names and inline fields where a permanent
input would be visual noise. The preview is a real button in the
accessibility tree (Enter/Space start editing); the input auto-focuses with
its text selected, commits on **Enter** or blur, and cancels on **Escape**.

```tsx
import { Editable } from "astralis-ui";

export function EditableDemo() {
  return (
    <Editable defaultValue="Q3 launch plan" size="lg">
      <Editable.Preview />
      <Editable.Input aria-label="Document title" />
    </Editable>
  );
}
```

## Import

```tsx
import { Editable } from "astralis-ui";
```

## Usage

Render both parts; whichever matches the current mode shows itself. The
preview is a button until you activate it, then the input takes focus with
its text selected, so typing replaces the value straight away.

To keep the value in your own state, pass `value` and `onChange`. `onChange`
fires on every keystroke, so pair it with `onSubmit` to know when an edit is
final and `onCancel` to roll back:

```tsx
"use client";

import { useState } from "react";
import { Editable, Text, VStack } from "astralis-ui";

export function EditableControlled() {
  const [name, setName] = useState("Nova Starling");
  const [saved, setSaved] = useState("Nova Starling");

  return (
    <VStack gap="2" alignItems="start">
      <Editable value={name} onChange={setName} onSubmit={setSaved} onCancel={() => setName(saved)}>
        <Editable.Preview />
        <Editable.Input aria-label="Display name" />
      </Editable>
      <Text size="sm" color="muted">
        Saved: {saved}
      </Text>
    </VStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value / defaultValue / onChange` | string / string / (value: string) => void | `None / "" / None` | Controlled / uncontrolled text. onChange fires on every keystroke while editing. |
| `onSubmit` | (value: string) => void | None | Fires when an edit is committed with Enter or blur. |
| `onCancel` | () => void | None | Fires when an edit is cancelled with Escape. |
| `placeholder` | string | `"Click to edit"` | Shown in the preview while the value is empty. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Text scale shared by the preview and the input. |
| `submitOnBlur` | boolean | `true` | Blur commits the edit. Turn it off and blur cancels instead. |
| `startWithEditView` | boolean | `false` | Mounts already editing. |
| `disabled` | boolean | `false` | Locks editing; the preview becomes plain text. |

### Parts

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Editable.Preview` | span props | None | The value at rest. A button in the accessibility tree that starts editing. |
| `Editable.Input` | input props | None | The text field while editing. Focused with its text selected on entry. |

## Keyboard

| Key | Action |
| --- | --- |
| `Enter` / `Space` on the preview | Start editing |
| `Enter` in the input | Commit the edit |
| `Esc` in the input | Cancel and restore the previous value |
| `Tab` out of the input | Commit, or cancel when `submitOnBlur` is off |

---

<!-- Data Entry / File Upload: /docs/components/file-upload -->

# File Upload

File picking and drag-and-drop built around a hidden native
`<input type="file">`: the picker dialog, `accept` filtering and mobile
integrations stay the platform's. `maxSize`/`maxFiles` violations are
**rejected and reported** via `onReject`, never silently truncated.

```tsx
"use client";

import { FileUpload, Box, Text } from "astralis-ui";
import { useState } from "react";

export function FileUploadDemo() {
  const [rejected, setRejected] = useState<string | null>(null);

  return (
    <Box w="full" maxW="md">
      <FileUpload
        multiple
        maxFiles={3}
        maxSize={5 * 1024 * 1024}
        onReject={(rejections) =>
          setRejected(rejections.map((r) => `${r.file.name} (${r.reason})`).join(", "))
        }
      >
        <FileUpload.Dropzone />
        <FileUpload.ItemGroup />
      </FileUpload>
      {rejected && (
        <Text size="xs" color="muted" mt="2">
          Rejected: {rejected}. Max 3 files, 5 MB each.
        </Text>
      )}
    </Box>
  );
}
```

## Import

```tsx
import { FileUpload } from "astralis-ui";
```

## Button trigger

Skip the dropzone entirely: `FileUpload.Trigger` wraps any element and opens
the picker:

```tsx
import { FileUpload, Button, HStack } from "astralis-ui";
import { Paperclip } from "lucide-react";

export function FileUploadTrigger() {
  return (
    <FileUpload multiple>
      <HStack gap="3" alignItems="start">
        <FileUpload.Trigger>
          <Button variant="outline" colorScheme="gray" size="sm" leftIcon={<Paperclip size={14} />}>
            Attach files
          </Button>
        </FileUpload.Trigger>
      </HStack>
      <FileUpload.ItemGroup />
    </FileUpload>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `accept` | string | None | Native accept filter, such as "image/*,.pdf". The picker enforces it. |
| `multiple` | boolean | `false` | Allow more than one file. |
| `maxFiles` | number | None | Cap on the number of kept files when multiple is set. Picks past it are rejected. |
| `maxSize` | number | None | Per-file size cap in bytes. Larger picks are rejected. |
| `onFilesChange` | (files: File[]) => void | None | The full kept list after every add or remove. |
| `onReject` | (rejections: { file, reason: "size" \| "count" }[]) => void | None | The picks that were refused, and why. |
| `disabled` | boolean | `false` | Locks picking and dropping. |

### Parts

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `FileUpload.Dropzone` | div props | None | Drop target that also opens the picker on click, Enter or Space. |
| `FileUpload.Trigger` | children: ReactElement | None | Wraps your own element, such as a Button, to open the picker. |
| `FileUpload.ItemGroup` | ul props | None | The kept files, each with its name, size and a remove button. |

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Move to the dropzone, then to each file's remove button |
| `Enter` / `Space` on the dropzone | Open the file picker |
| `Enter` / `Space` on a remove button | Remove that file |

Dragging files is pointer-only; the picker is the keyboard path to the same
result.

---

<!-- Data Display / Card: /docs/components/card -->

# Card

A content container with header, body and footer sections in four variants.

```tsx
"use client";

import { Card, Badge, Button, Text, Box } from "astralis-ui";

export function CardDemo() {
  return (
    <Box w="full" maxW="xs">
      <Card>
        <Card.Header extra={<Badge colorScheme="green">Operational</Badge>}>
          <Card.Title>Production cluster</Card.Title>
          <Card.Description>us-east-1 · 12 nodes</Card.Description>
        </Card.Header>
        <Card.Body>
          <Text size="sm" color="muted">
            All services healthy. Last incident 42 days ago.
          </Text>
        </Card.Body>
        <Card.Footer>
          <Button variant="link" size="sm">View dashboard →</Button>
        </Card.Footer>
      </Card>
    </Box>
  );
}
```

## Import

```tsx
import { Card } from "astralis-ui";
// Card.Header, .Title, .Description, .Body, .Footer
```

## Anatomy

`Card.Header` takes an `extra` slot for trailing content (badges, menus);
`size` on the root scales every section's padding: the root stamps it as a
`data-card-size` attribute and the sections' CSS reads it, so the whole
compound stays a Server Component.

## Variants

`hoverable` adds a lift on hover. Pair it with clickable cards.

```tsx
"use client";

import { Card, Text, Grid } from "astralis-ui";

const variants = ["elevated", "outline", "filled"] as const;

export function CardVariants() {
  return (
    <Grid columns={{ base: "1", md: "3" }} gap="4" w="full" maxW="md">
      {variants.map((variant) => (
        <Card key={variant} variant={variant} size="sm" hoverable>
          <Card.Body>
            <Text size="sm" weight="medium">{variant}</Text>
            <Text size="xs" color="muted">hoverable: try me</Text>
          </Card.Body>
        </Card>
      ))}
    </Grid>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | "elevated" \| "outline" \| "filled" \| "unstyled" | `"elevated"` | Shadowed, bordered, tinted, or bare. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Padding density for all sections. |
| `hoverable` | boolean | `false` | Hover elevation. |

Card takes no [style props](/docs/style-props): those belong to the layout
primitives. Sizing and placement are the job of whatever lays the card out: a
`Grid` with `alignItems="stretch"` already gives a row of cards equal heights,
and anything past that goes on a wrapping `Box`.

`Card.Header` additionally takes `extra: ReactNode`; `Card.Title` renders an
`h3` and `Card.Description` a `p`. Both accept their native attributes.

---

<!-- Data Display / Tag: /docs/components/tag -->

# Tag

Chips for labels and filters: closable, checkable, and groupable.

```tsx
"use client";

import { useState } from "react";
import { Tag, HStack } from "astralis-ui";

export function TagDemo() {
  const [tags, setTags] = useState(["Design", "Engineering", "Research"]);

  return (
    <HStack gap="2" wrap="wrap" justifyContent="center">
      <Tag colorScheme="purple">Astralis</Tag>
      <Tag variant="outline" colorScheme="blue">v0.1</Tag>
      {tags.map((tag) => (
        <Tag key={tag} closable onClose={() => setTags(tags.filter((t) => t !== tag))}>
          {tag}
        </Tag>
      ))}
    </HStack>
  );
}
```

## Import

```tsx
import { Tag } from "astralis-ui";
// Tag.Checkable, Tag.Group
```

## Tag or Badge?

Tag is a label the thing **carries** (a topic, a category, a filter, a
selected value), which is why it can be removed, selected and grouped. If
you're describing a state the thing is **in** (`Active`, `Beta`, `3 unread`),
that's [Badge](/docs/components/badge). The two chips look nearly identical,
so the component name is what tells a reader which you meant.

## Checkable groups

`Tag.Checkable` is a chip with checkbox semantics; `Tag.Group` manages a
whole set from an `options` array: `multiple` for filters, single-select
for exclusive choices.

```tsx
"use client";

import { useState } from "react";
import { Tag, Text, VStack } from "astralis-ui";

export function TagCheckable() {
  const [topics, setTopics] = useState<Array<string | number>>(["react"]);

  return (
    <VStack gap="3" alignItems="center">
      <Tag.Group
        multiple
        value={topics}
        onChange={setTopics}
        options={[
          { label: "React", value: "react" },
          { label: "Vue", value: "vue" },
          { label: "Svelte", value: "svelte" },
          { label: "Solid", value: "solid" },
        ]}
      />
      <Text size="xs" color="muted">
        Following: {topics.length ? topics.join(", ") : "nothing yet"}
      </Text>
    </VStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | "solid" \| "subtle" \| "surface" \| "outline" | `"subtle"` | Same family as Button/Badge. |
| `size` | "xs" \| "sm" \| "md" \| "lg" | `"md"` | Chip size (same scale as Badge). |
| `colorScheme` | all 15 schemes | `"gray"` | Hue. |
| `startElement / endElement` | ReactNode | None | Leading / trailing slots (endElement yields to the close button). |
| `closable / onClose` | boolean / () => void | None | Adds the ✕ remove button. |

### Tag.Checkable

Takes Tag's props except `variant`, `closable` and `onClose`, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked / onChange` | boolean / (checked: boolean) => void | None | Selected state and its change callback. |
| `colorScheme` | all 15 schemes | `"brand"` | Hue used while checked. |

### Tag.Group

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | { label, value }[] \| (string \| number)[] | None | The chips to render. Required. |
| `value / onChange` | (string \| number)[] / (value) => void | None | The selected values and their change callback. The group is always controlled, so pass both. |
| `multiple` | boolean | `false` | Allow several selected at once. Otherwise selecting one clears the rest. |
| `size` | "xs" \| "sm" \| "md" \| "lg" | `"md"` | Size of every chip. |
| `colorScheme` | all 15 schemes | `"brand"` | Checked hue of every chip. |

## Keyboard

Every checkable tag is its own tab stop.

| Key | Action |
| --- | --- |
| `Tab` / `Shift+Tab` | Move to the next / previous tag |
| `Enter` / `Space` | Toggle the focused tag |

On a closable tag, the remove button is a separate tab stop and activates
with `Enter` or `Space`.

## Accessibility

Checkable tags carry `role="checkbox"` + `aria-checked` and toggle with
Enter/Space; the close button is labeled "Remove".

---

<!-- Data Display / Image: /docs/components/image -->

# Image

Images with aspect ratios, captions, error fallbacks, and a built-in lightbox.

```tsx
"use client";

import { Image, Box } from "astralis-ui";

export function ImageDemo() {
  return (
    <Box w="full" maxW="xs">
      <Image
        src="/placeholder.svg"
        alt="A starfield gradient"
        aspectRatio="video"
        rounded="xl"
        caption="Captions wrap the image in a semantic figure."
      />
    </Box>
  );
}
```

## Import

```tsx
import { Image } from "astralis-ui";
// Image.Group for galleries
```

## Preview lightbox

`preview` makes the image click-to-zoom. The lightbox supports zoom, rotate
and keyboard dismissal, with arrow-key navigation inside an `Image.Group`.

```tsx
"use client";

import { Image, Text, VStack, Box } from "astralis-ui";

export function ImagePreview() {
  return (
    <VStack gap="2" alignItems="start">
      <Box w="56">
        {/* Click to open the built-in lightbox (zoom, rotate, Esc to close). */}
        <Image src="/placeholder.svg" alt="Preview me" aspectRatio="video" rounded="lg" preview />
      </Box>
      <Text size="xs" color="muted">Click the image to preview</Text>
    </VStack>
  );
}
```

## Error fallbacks

```tsx
"use client";

import { Image, HStack, Text } from "astralis-ui";

export function ImageFallback() {
  return (
    <HStack gap="4" wrap="wrap" justifyContent="center">
      {/* A broken src falls back to the default icon… */}
      <Image src="/does-not-exist.png" alt="Broken" width={140} height={90} rounded="lg" />
      {/* …or to whatever you pass as fallback. */}
      <Image
        src="/also-missing.png"
        alt="Broken with custom fallback"
        width={140}
        height={90}
        rounded="lg"
        fallback={<Text size="sm" color="muted">No image</Text>}
      />
    </HStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src / alt` | string | None | Source and alternative text. Both required. |
| `aspectRatio` | "square" \| "video" \| "portrait" \| "wide" \| CSS ratio | None | Locks the frame to 1/1, 16/9, 3/4, 21/9, or any CSS ratio such as "4/3". |
| `objectFit` | "cover" \| "contain" \| "fill" \| "none" \| "scale-down" | `"cover"` | How the image fills its frame. |
| `rounded` | "none" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "full" | `"none"` | Corner radius. |
| `width / height` | number \| string | None | The img element's intrinsic size attributes, which reserve space before it loads. |
| `loading` | "lazy" \| "eager" | `"lazy"` | Native lazy loading. |
| `placeholder` | "blur" \| "empty" \| URL | `"empty"` | A shimmer, nothing, or a low-resolution image shown while loading. |
| `srcset / sizes` | string | None | Responsive image sources, passed to the img element. |
| `fallback` | ReactNode | `icon` | Rendered when the image fails to load. |
| `caption` | ReactNode | None | Wraps the image in a figure with this figcaption. |
| `preview` | boolean | `false` | Opens a lightbox with zoom and rotate on click. |
| `onLoad / onError` | () => void | None | Fire when the image loads or fails. |
| `ariaLabel` | string | None | aria-label for the img element. |

### Image.Group

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | { src, alt, caption? }[] | None | The gallery images. Required. |
| `columns` | 2 \| 3 \| 4 | `3` | Grid columns. |
| `gap` | "sm" \| "md" \| "lg" | `"md"` | Space between images. |
| `rounded` | "none" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "full" | `"md"` | Corner radius of every image. |
| `objectFit` | "cover" \| "contain" \| "fill" \| "none" \| "scale-down" | `"cover"` | How every image fills its cell. |

## Keyboard

With the preview lightbox open:

| Key | Action |
| --- | --- |
| `Esc` | Close the lightbox |
| `←` / `→` | Previous / next image (inside an `Image.Group`) |

---

<!-- Data Display / Calendar: /docs/components/calendar -->

# Calendar

A month grid with single, multiple and range selection, locales and date constraints.

```tsx
"use client";

import { useState } from "react";
import { Calendar, Text, VStack } from "astralis-ui";

export function CalendarDemo() {
  const [date, setDate] = useState<Date | null>(null);

  return (
    <VStack gap="3" alignItems="start">
      <Calendar
        selectionMode="single"
        value={date}
        onValueChange={(next) => setDate(next instanceof Date ? next : null)}
      >
        <Calendar.Header>
          <Calendar.PrevTrigger />
          <Calendar.ViewTrigger />
          <Calendar.NextTrigger />
        </Calendar.Header>
        <Calendar.Weekdays />
        <Calendar.Grid />
      </Calendar>
      <Text size="xs" color="muted">
        {date ? `Selected: ${date.toDateString()}` : "Pick a date"}
      </Text>
    </VStack>
  );
}
```

## Import

```tsx
import { Calendar } from "astralis-ui";
// Calendar.Header, .PrevTrigger, .ViewTrigger, .NextTrigger,
// .Weekdays, .Grid, .Cell
```

## Range selection

`selectionMode="range"` returns `{ start, end }`; `firstDayOfWeek={1}` starts
weeks on Monday, and weekday names follow the `locale`.

```tsx
"use client";

import { Calendar } from "astralis-ui";

export function CalendarRange() {
  return (
    /* Range mode: click a start, then an end; days between highlight. */
    <Calendar selectionMode="range" firstDayOfWeek={1} size="sm">
      <Calendar.Header>
        <Calendar.PrevTrigger />
        <Calendar.ViewTrigger />
        <Calendar.NextTrigger />
      </Calendar.Header>
      <Calendar.Weekdays />
      <Calendar.Grid />
    </Calendar>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `selectionMode` | "single" \| "multiple" \| "range" | `"single"` | What a click selects. |
| `value / defaultValue / onValueChange` | Date \| Date[] \| { start, end } \| null | None | Controlled / uncontrolled API, shaped by the mode. |
| `defaultMonth` | Date | `today` | Initially visible month. |
| `locale` | string | `"en-US"` | Intl locale for month/weekday names. |
| `firstDayOfWeek` | 0 – 6 | `0` | 0 = Sunday, 1 = Monday… |
| `minDate / maxDate / isDateUnavailable` | Date / Date / (date) => boolean | None | Selection constraints. |
| `showOutsideDays` | boolean | `true` | Render the adjacent months' spill-over days. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Cell size. |

## Keyboard

With focus on the day grid:

| Key | Action |
| --- | --- |
| `←` / `→` | Previous / next day |
| `↑` / `↓` | Previous / next week |
| `Home` / `End` | Start / end of the week |
| `PageUp` / `PageDown` | Previous / next month (same day) |
| `Enter` / `Space` | Select the focused day |

Moving past a month boundary flips the visible month and keeps focus on the
day, no extra keystrokes needed.

## Accessibility

Every day cell is a real button with a full-date `aria-label`; the previous
and next triggers are labeled, and unavailable dates use the native
`disabled` attribute.

---

<!-- Data Display / Data List: /docs/components/data-list -->

# Data List

Key–value pairs in a semantic description list, horizontal or stacked.

```tsx
"use client";

import { DataList, Badge, Box } from "astralis-ui";

export function DataListDemo() {
  return (
    <Box w="full" maxW="sm">
      <DataList>
        <DataList.Item>
          <DataList.Label>Name</DataList.Label>
          <DataList.Value>Sophie Durand</DataList.Value>
        </DataList.Item>
        <DataList.Item>
          <DataList.Label>Email</DataList.Label>
          <DataList.Value>sophie@astralis.dev</DataList.Value>
        </DataList.Item>
        <DataList.Item>
          <DataList.Label>Status</DataList.Label>
          <DataList.Value>
            <Badge colorScheme="green">Active</Badge>
          </DataList.Value>
        </DataList.Item>
      </DataList>
    </Box>
  );
}
```

## Import

```tsx
import { DataList } from "astralis-ui";
// DataList.Item, DataList.Label, DataList.Value
```

## Usage

Values take any content (badges, avatars, links) while the underlying
markup stays a real `<dl>`/`<dt>`/`<dd>` description list.

## Vertical

`orientation="vertical"` stacks each label above its value, better for
narrow columns and cards.

```tsx
"use client";

import { DataList, Box } from "astralis-ui";

export function DataListVertical() {
  return (
    <Box w="full" maxW="sm">
      <DataList orientation="vertical" size="sm">
        <DataList.Item>
          <DataList.Label>Deployment region</DataList.Label>
          <DataList.Value>eu-central-1 (Frankfurt)</DataList.Value>
        </DataList.Item>
        <DataList.Item>
          <DataList.Label>Runtime</DataList.Label>
          <DataList.Value>Node 22 on the edge</DataList.Value>
        </DataList.Item>
      </DataList>
    </Box>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | "horizontal" \| "vertical" | `"horizontal"` | Label beside or above the value. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Text and rhythm scale. |

`Item`, `Label` and `Value` take only `className`: they're layout, the
semantics come free.

---

<!-- Data Display / Marquee: /docs/components/marquee -->

# Marquee

An infinitely scrolling strip for logos and highlights: CSS-driven, pausable, gradient-masked.

```tsx
"use client";

import { Marquee, Text, Box } from "astralis-ui";

const stack = ["React", "TypeScript", "Vitest", "Vite", "Next.js", "CVA", "pnpm"];

export function MarqueeDemo() {
  return (
    <Box w="full" maxW="md">
      <Marquee speed={40} gap="0.75rem" pauseOnHover gradient>
        {stack.map((name) => (
          <Marquee.Item key={name}>
            <Box border="normal" borderColor="base" bg="subtle" px="4" py="2" rounded="full">
              <Text as="span" size="sm">{name}</Text>
            </Box>
          </Marquee.Item>
        ))}
      </Marquee>
    </Box>
  );
}
```

## Import

```tsx
import { Marquee } from "astralis-ui";
// Marquee.Item
```

## Usage

Children are duplicated once (the clone is `aria-hidden`) for a seamless
loop; the animation is pure CSS keyframes, so it costs nothing at runtime.
`gradient` masks the edges into the background.

## Opposing rows

```tsx
"use client";

import { Marquee, Text, Box, VStack } from "astralis-ui";

const row1 = ["Semantic tokens", "Runtime theming", "Dark mode", "Responsive props"];
const row2 = ["Compound components", "Accent channel", "Zero build step", "Typed styles"];

export function MarqueeReverse() {
  return (
    /* Two rows in opposite directions: the classic logo-wall move. */
    <VStack gap="3" w="full" maxW="md">
      <Marquee speed={35} gap="0.75rem" gradient>
        {row1.map((label) => (
          <Marquee.Item key={label}>
            <Box bg="brand-subtle" px="4" py="1.5" rounded="full">
              <Text as="span" size="xs">{label}</Text>
            </Box>
          </Marquee.Item>
        ))}
      </Marquee>
      <Marquee speed={35} gap="0.75rem" gradient reverse>
        {row2.map((label) => (
          <Marquee.Item key={label}>
            <Box bg="purple-subtle" px="4" py="1.5" rounded="full">
              <Text as="span" size="xs">{label}</Text>
            </Box>
          </Marquee.Item>
        ))}
      </Marquee>
    </VStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `direction` | "left" \| "right" \| "up" \| "down" | `"left"` | Scroll axis and direction. |
| `speed` | number | `50` | Pixels per second. |
| `gap` | string | `"1rem"` | CSS length between items, and at the loop seam. |
| `reverse` | boolean | `false` | Flips the direction. |
| `pauseOnHover` | boolean | `false` | Pauses while the pointer is over the strip. |
| `pauseOnFocus` | boolean | `false` | Pauses while focus is inside. Turn it on when items are interactive. |
| `gradient` | boolean | `false` | Fades both edges into the background. |
| `gradientColor` | string | `page background` | CSS color the edges fade into. |
| `gradientWidth` | string | `"10%"` | Width of each edge fade. |
| `loopCount` | number | `0` | Loops before the strip stops. 0 loops forever. |

### Parts

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Marquee.Item` | div props | None | One entry in the strip. The items are rendered twice for a seamless loop, and the copy is hidden from assistive technology. |

## Accessibility

The duplicated track is `aria-hidden`, and `pauseOnFocus` lets keyboard
users freeze the motion. Turn it on when items are interactive.

---

<!-- Data Display / QR Code: /docs/components/qr-code -->

# QR Code

Client-side SVG QR codes with logo overlays, lifecycle states and download.

```tsx
"use client";

import { QrCode } from "astralis-ui";

export function QrCodeDemo() {
  return <QrCode value="https://astralis.dev" size="md" />;
}
```

## Import

```tsx
import { QrCode } from "astralis-ui";
```

## Overlays and states

`overlay` centers a logo on the code (raise `errorLevel` to `"H"` so the
covered modules stay scannable). The `status` prop covers the login-QR
lifecycle: `loading`, `expired` (with a refresh action), and `scanned`.

```tsx
"use client";

import { useState } from "react";
import { QrCode, Center, Text, HStack, VStack } from "astralis-ui";

export function QrCodeStates() {
  const [expired, setExpired] = useState(true);

  return (
    <HStack gap="6" wrap="wrap" alignItems="start" justifyContent="center">
      <VStack gap="1" alignItems="start">
        <Text as="span" size="xs" color="muted">overlay + download</Text>
        <QrCode
          value="https://astralis.dev/docs"
          size="sm"
          errorLevel="H"
          downloadable
          overlay={
            <Center bg="inverted" size="full" rounded="sm">
              <Text as="span" size="xs" color="inverted" weight="bold">A</Text>
            </Center>
          }
        />
      </VStack>
      <VStack gap="1" alignItems="start">
        <Text as="span" size="xs" color="muted">expired → refresh</Text>
        <QrCode
          value="https://astralis.dev/session"
          size="sm"
          status={expired ? "expired" : "active"}
          onRefresh={() => setExpired(false)}
        />
      </VStack>
      <VStack gap="1" alignItems="start">
        <Text as="span" size="xs" color="muted">scanned</Text>
        <QrCode value="https://astralis.dev" size="sm" status="scanned" />
      </VStack>
    </HStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | string | None | The text or URL to encode. Required. |
| `size` | "sm" \| "md" \| "lg" \| "xl" | `"md"` | Preset sizes from 96 to 280px. |
| `pixelSize` | number | None | Explicit size in pixels, overriding the preset. |
| `errorLevel` | "L" \| "M" \| "Q" \| "H" | `"M"` | Error correction, from 7% to 30% recoverable. Go higher when an overlay covers modules. |
| `color / bgColor` | string | `"#000000" / "transparent"` | CSS colors of the modules and the background. |
| `overlay / overlaySize` | ReactNode / number | `None / 20` | A centered logo, sized as a percentage of the code. |
| `status` | "active" \| "loading" \| "expired" \| "scanned" | `"active"` | Lifecycle overlay. |
| `onRefresh` | () => void | None | Shows a Refresh button on the expired overlay. |
| `downloadable` | boolean | `false` | Adds a button that downloads the code as an SVG. |
| `downloadFileName` | string | `"qrcode"` | File name for the download, without the extension. |

---

<!-- Data Display / Avatar: /docs/components/avatar -->

# Avatar

User images with graceful fallbacks, status badges, and overlapping groups.

```tsx
"use client";

import { Avatar, HStack } from "astralis-ui";

export function AvatarDemo() {
  return (
    <HStack gap="3">
      {/* Initials with a hue derived deterministically from the name. */}
      <Avatar name="Nova Starling" />
      <Avatar name="Alex Kim" />
      <Avatar name="Maria Lopez" />
      {/* No name, no image → icon fallback. */}
      <Avatar />
      <Avatar name="Sam Patel">
        <Avatar.Badge status="online" />
      </Avatar>
    </HStack>
  );
}
```

## Import

```tsx
import { Avatar } from "astralis-ui";
// Avatar.Group, Avatar.Badge
```

## Usage

The fallback chain is automatic: `src` image → initials from `name` (with a
hue derived deterministically from the name, so the same person always gets
the same color) → silhouette icon. `Avatar.Badge` anchors a status dot.

## Groups

```tsx
"use client";

import { Avatar } from "astralis-ui";

export function AvatarGroup() {
  return (
    /* Overlapping stack; everything past `max` collapses into "+N". */
    <Avatar.Group max={3}>
      <Avatar name="Nova Starling" />
      <Avatar name="Alex Kim" />
      <Avatar name="Maria Lopez" />
      <Avatar name="Sam Patel" />
      <Avatar name="Jo Ellis" />
    </Avatar.Group>
  );
}
```

## Sizes and shapes

```tsx
"use client";

import { Avatar, HStack } from "astralis-ui";

const sizes = ["xs", "sm", "md", "lg", "xl", "2xl"] as const;

export function AvatarSizes() {
  return (
    <HStack gap="4" alignItems="end" wrap="wrap" justifyContent="center">
      {sizes.map((size) => (
        <Avatar key={size} name="Nova Starling" size={size} />
      ))}
      <Avatar name="Nova Starling" shape="rounded" />
      <Avatar name="Nova Starling" shape="square" />
    </HStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src / alt` | string | None | The image, with its alt text. |
| `name` | string | None | Drives initials and the deterministic hue. |
| `icon` | ReactNode | `silhouette` | Custom fallback when no image or name. |
| `size` | "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" | `"md"` | Diameter. |
| `shape` | "circle" \| "rounded" \| "square" | `"circle"` | Outline shape. |
| `colorScheme` | all 15 schemes | `from name` | Explicit hue override. |
| `ring` | boolean | `false` | Border ring (automatic inside a Group). |

### Avatar.Group

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `max` | number | None | How many avatars to show; the rest collapse into a +N chip. |
| `size` | "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" | `"md"` | Applied to every avatar in the group. |
| `spacing` | number | `-8` | Overlap between avatars, in pixels. Negative values overlap. |

### Avatar.Badge

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | "online" \| "away" \| "busy" \| "offline" | `"online"` | Preset dot color. |
| `color` | string | None | Custom dot color, overriding status. |
| `size` | "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" | None | Dot size. Taken from the avatar it sits in. |

---

<!-- Data Display / Badge: /docs/components/badge -->

# Badge

A small status label in the standard variant and color-scheme families.

```tsx
"use client";

import { Badge, HStack } from "astralis-ui";

export function BadgeDemo() {
  return (
    <HStack gap="2" wrap="wrap" justifyContent="center">
      <Badge colorScheme="green" variant="solid">Active</Badge>
      <Badge colorScheme="yellow">Pending</Badge>
      <Badge colorScheme="red" variant="surface">Failed</Badge>
      <Badge colorScheme="blue" variant="outline">Beta</Badge>
      <Badge>Default</Badge>
    </HStack>
  );
}
```

## Import

```tsx
import { Badge } from "astralis-ui";
```

## Variants and sizes

```tsx
"use client";

import { Badge, Text, HStack, VStack } from "astralis-ui";

const variants = ["solid", "subtle", "surface", "outline"] as const;
const sizes = ["xs", "sm", "md", "lg"] as const;

export function BadgeVariants() {
  return (
    <VStack gap="4" alignItems="start">
      <VStack gap="1" alignItems="start">
        <Text as="span" size="xs" color="subtle">variants</Text>
        <HStack gap="2">
          {variants.map((variant) => (
            <Badge key={variant} variant={variant} colorScheme="brand">{variant}</Badge>
          ))}
        </HStack>
      </VStack>
      <VStack gap="1" alignItems="start">
        <Text as="span" size="xs" color="subtle">sizes</Text>
        <HStack gap="2" alignItems="center">
          {sizes.map((size) => (
            <Badge key={size} size={size} colorScheme="teal">{size}</Badge>
          ))}
        </HStack>
      </VStack>
    </VStack>
  );
}
```

## Badge or Tag?

The two render nearly the same chip (Badge is pill-shaped, Tag is rounded),
so the radius won't tell you which to reach for. The meaning does:

- **Badge is a state the thing is *in***: `Active`, `Beta`, `Failed`,
  `3 unread`. Read-only, which is why it has no close button and no group.
- **[Tag](/docs/components/tag) is a label the thing *carries***: a topic, a
  category, a filter. That's why it can be removed, selected and grouped.

Pick by meaning, not by shape: a reader who sees `Badge` should know the chip
describes status without having to check what it says. For counts anchored to
a corner, combine a Badge with [Float](/docs/components/float).

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | "solid" \| "subtle" \| "surface" \| "outline" | `"subtle"` | Visual style. surface is the bordered sibling of subtle. |
| `colorScheme` | all 15 schemes | `"gray"` | Hue the badge paints with, via the accent channel. |
| `size` | "xs" \| "sm" \| "md" \| "lg" | `"sm"` | Text and padding scale. |

---

<!-- Data Display / Stat: /docs/components/stat -->

# Stat

A single metric with label, value, help text and a trend indicator.

```tsx
"use client";

import { Stat, HStack } from "astralis-ui";

export function StatDemo() {
  return (
    <HStack gap="10" wrap="wrap" justifyContent="center">
      <Stat>
        <Stat.Label>Total users</Stat.Label>
        <Stat.Value>24,521</Stat.Value>
        <Stat.HelpText>
          <Stat.Indicator type="increase">12.4%</Stat.Indicator> from last month
        </Stat.HelpText>
      </Stat>
      <Stat>
        <Stat.Label>Bounce rate</Stat.Label>
        <Stat.Value>18.2%</Stat.Value>
        <Stat.HelpText>
          <Stat.Indicator type="decrease">3.1%</Stat.Indicator> from last month
        </Stat.HelpText>
      </Stat>
    </HStack>
  );
}
```

## Import

```tsx
import { Stat } from "astralis-ui";
// Stat.Label, .Value, .HelpText, .Indicator
```

## Usage

Values render with tabular numerals so dashboards line up; the indicator
colors green for `increase` and red for `decrease`. Note that "decrease" is
just the arrow direction, not a judgment (a falling bounce rate is good
news).

## Size

`size` scales the label, value and help text together, so a resized Stat stays
in proportion instead of growing one line and leaving the others behind. It is
responsive, which is what lets one Stat serve a dense dashboard tile and a
marketing band.

```tsx
"use client";

import { Stat, VStack } from "astralis-ui";

const sizes = ["sm", "md", "lg", "xl"] as const;

export function StatSizes() {
  return (
    <VStack gap="6" alignItems="start">
      {sizes.map((size) => (
        <Stat key={size} size={size}>
          <Stat.Label>Monthly revenue · {size}</Stat.Label>
          <Stat.Value>$48,200</Stat.Value>
          <Stat.HelpText>
            <Stat.Indicator type="increase">8.1%</Stat.Indicator> from last month
          </Stat.HelpText>
        </Stat>
      ))}
    </VStack>
  );
}
```

```tsx
{/* big on desktop, back in its box on a two-up mobile grid */}
<Stat size={{ base: "lg", lg: "xl" }} align="center">
  <Stat.Value>99.9%</Stat.Value>
  <Stat.Label>Uptime</Stat.Label>
</Stat>
```

Children render in the order you write them, so a marketing band can lead with
the value while a dashboard tile leads with the label.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | "sm" \| "md" \| "lg" \| "xl" | `"md"` | Scales label, value and help text together. md suits dashboards, xl marketing bands. Responsive. |
| `align` | "start" \| "center" \| "end" | `"start"` | How the lines align within the stat. Responsive. |

### Parts

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Stat.Label / Value / HelpText` | span props | None | The three lines. Each takes its size from the root. |
| `Stat.Indicator` | type?: "increase" \| "decrease" | None | Trend arrow inside the help text, colored for the direction. |

Compose Stats in a [Grid](/docs/components/grid) or
[HStack](/docs/components/stack) for dashboard rows, and inside a
[Card](/docs/components/card) for tiles.

---

<!-- Data Display / Table: /docs/components/table -->

# Table

A semantic table with striping, hover states, sticky headers and two variants.

```tsx
"use client";

import { Table, Badge, Box } from "astralis-ui";

const releases = [
  { version: "0.3.0", date: "Jun 28", status: "Stable", scheme: "green" },
  { version: "0.2.1", date: "Jun 14", status: "Stable", scheme: "green" },
  { version: "0.2.0", date: "Jun 02", status: "Deprecated", scheme: "orange" },
] as const;

export function TableDemo() {
  return (
    <Box w="full" maxW="md">
      <Table variant="outline" striped interactive>
        <Table.Header>
          <Table.Row>
            <Table.Head>Version</Table.Head>
            <Table.Head>Released</Table.Head>
            <Table.Head>Status</Table.Head>
          </Table.Row>
        </Table.Header>
        <Table.Body>
          {releases.map((release) => (
            <Table.Row key={release.version}>
              <Table.Cell>{release.version}</Table.Cell>
              <Table.Cell>{release.date}</Table.Cell>
              <Table.Cell>
                <Badge colorScheme={release.scheme}>{release.status}</Badge>
              </Table.Cell>
            </Table.Row>
          ))}
        </Table.Body>
        <Table.Caption>Astralis UI release history</Table.Caption>
      </Table>
    </Box>
  );
}
```

## Import

```tsx
import { Table } from "astralis-ui";
// Table.Header, .Body, .Footer, .Row, .Head, .Cell, .Caption
```

## Usage

The compound parts map one-to-one onto native table elements: you keep full
control of rows and cells, and the root handles horizontal overflow with its
own scroll container.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | "line" \| "outline" | `"line"` | Subtle row dividers, or a bordered box. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Cell padding and text size. |
| `striped` | boolean | `false` | Alternate row backgrounds. |
| `interactive` | boolean | `false` | Row highlight on hover. |
| `stickyHeader` | boolean | `false` | Header pins while the body scrolls. |

`Table.Head` defaults `scope="col"`; `Table.Caption` takes
`placement: "top" | "bottom"` (default bottom). All parts forward their
native element attributes.

## Accessibility

Real `table`/`thead`/`th[scope]`/`caption` semantics: screen readers get
the table for free; striping and hover are purely visual.

---

<!-- Data Display / Timeline: /docs/components/timeline -->

# Timeline

A vertical sequence of events with indicators, connectors and per-item colors.

```tsx
"use client";

import { Timeline, Icon, Box } from "astralis-ui";
import { Check, Truck, Package } from "lucide-react";

export function TimelineDemo() {
  return (
    <Box w="full" maxW="xs">
      <Timeline>
        <Timeline.Item>
          <Timeline.Indicator colorScheme="green">
            <Icon as={Check} size="xs" />
          </Timeline.Indicator>
          <Timeline.Content>
            <Timeline.Title>Order placed</Timeline.Title>
            <Timeline.Description>Confirmed at 2:30 PM</Timeline.Description>
          </Timeline.Content>
        </Timeline.Item>
        <Timeline.Item>
          <Timeline.Indicator>
            <Icon as={Truck} size="xs" />
          </Timeline.Indicator>
          <Timeline.Content>
            <Timeline.Title>In transit</Timeline.Title>
            <Timeline.Description>Left the warehouse this morning</Timeline.Description>
          </Timeline.Content>
        </Timeline.Item>
        <Timeline.Item>
          <Timeline.Indicator colorScheme="gray">
            <Icon as={Package} size="xs" />
          </Timeline.Indicator>
          <Timeline.Content>
            <Timeline.Title>Delivery</Timeline.Title>
            <Timeline.Description>Expected Thursday</Timeline.Description>
          </Timeline.Content>
        </Timeline.Item>
      </Timeline>
    </Box>
  );
}
```

## Import

```tsx
import { Timeline } from "astralis-ui";
// Timeline.Item, .Indicator, .Content, .Title, .Description
```

## Usage

Indicators take anything, whether numbers, icons, or nothing (a plain dot), and
`colorScheme` on an individual indicator overrides the root's, which is how
the completed step above turns green.

## Variants and sizes

```tsx
"use client";

import { Timeline, Text, HStack, VStack } from "astralis-ui";

const variants = ["solid", "subtle", "outline"] as const;

export function TimelineVariants() {
  return (
    <HStack gap="8" alignItems="start" wrap="wrap" justifyContent="center">
      {variants.map((variant) => (
        <VStack key={variant} gap="2" alignItems="start">
          <Text as="span" size="xs" color="muted">{variant}</Text>
          <Timeline variant={variant} size="sm">
            <Timeline.Item>
              <Timeline.Indicator>1</Timeline.Indicator>
              <Timeline.Content>
                <Timeline.Title>First</Timeline.Title>
              </Timeline.Content>
            </Timeline.Item>
            <Timeline.Item>
              <Timeline.Indicator>2</Timeline.Indicator>
              <Timeline.Content>
                <Timeline.Title>Second</Timeline.Title>
              </Timeline.Content>
            </Timeline.Item>
          </Timeline>
        </VStack>
      ))}
    </HStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | "solid" \| "subtle" \| "outline" | `"solid"` | Indicator fill style. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Indicator diameter and text scale. |
| `colorScheme` | all 15 schemes | `"brand"` | Default indicator hue; overridable per Indicator. |

Connector lines render automatically between items and are hidden after the
last one. Empty indicators are `aria-hidden` decorative dots.

---

<!-- Feedback / Alert: /docs/components/alert -->

# Alert

A status banner for inline feedback: info, success, warning, and error.

```tsx
"use client";

import { Alert, VStack } from "astralis-ui";

export function AlertDemo() {
  return (
    <VStack gap="3" alignItems="stretch" w="full" maxW="xl">
      <Alert status="info">
        <Alert.Title>Scheduled maintenance</Alert.Title>
        <Alert.Description>The dashboard will be read-only on Saturday from 02:00–04:00 UTC.</Alert.Description>
      </Alert>
      <Alert status="success">
        <Alert.Title>Deploy complete</Alert.Title>
        <Alert.Description>v0.2.0 is live on all regions.</Alert.Description>
      </Alert>
      <Alert status="warning">
        <Alert.Title>Approaching quota</Alert.Title>
        <Alert.Description>You have used 90% of this month&apos;s build minutes.</Alert.Description>
      </Alert>
      <Alert status="error">
        <Alert.Title>Payment failed</Alert.Title>
        <Alert.Description>Your card was declined. Update billing to keep deploys running.</Alert.Description>
      </Alert>
    </VStack>
  );
}
```

## Import

```tsx
import { Alert } from "astralis-ui";
```

## Variants and dismissal

```tsx
"use client";

import { useState } from "react";
import { Alert, Button, VStack } from "astralis-ui";

export function AlertVariants() {
  const [dismissed, setDismissed] = useState(false);

  return (
    <VStack gap="3" alignItems="stretch" w="full" maxW="xl">
      <Alert status="success" variant="subtle">
        <Alert.Title>subtle: the default tinted panel</Alert.Title>
      </Alert>
      <Alert status="success" variant="solid">
        <Alert.Title>solid: maximum emphasis</Alert.Title>
      </Alert>
      <Alert status="success" variant="outline">
        <Alert.Title>outline: quiet, keeps the surface</Alert.Title>
      </Alert>
      <Alert status="success" variant="left-accent">
        <Alert.Title>left-accent: editorial side rule</Alert.Title>
      </Alert>
      {dismissed ? (
        <Button size="sm" variant="subtle" onClick={() => setDismissed(false)}>
          Bring back the dismissible alert
        </Button>
      ) : (
        <Alert status="info" onClose={() => setDismissed(true)}>
          <Alert.Title>Dismissible</Alert.Title>
          <Alert.Description>The ✕ calls your onClose handler.</Alert.Description>
        </Alert>
      )}
    </VStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | "info" \| "success" \| "warning" \| "error" | `"info"` | Picks the icon, hue, and ARIA role. |
| `variant` | "subtle" \| "solid" \| "outline" \| "left-accent" | `"subtle"` | Fill treatment. |
| `colorScheme` | all 15 schemes | `from status` | Hue override (info→blue, success→green, warning→orange, error→red). |
| `icon` | ReactNode \| false | `status icon` | Replace or hide the leading icon. |
| `onClose` | () => void | None | Renders the ✕ dismiss button. |

### Parts

| Part | Renders | Notes |
| --- | --- | --- |
| `Alert.Title` | `div` | Semibold heading line. |
| `Alert.Description` | `div` | Supporting copy below the title. |

## Accessibility

- `error` and `warning` render `role="alert"` (announced assertively);
  `info` and `success` render `role="status"` (announced politely).
- The dismiss button ships with an `aria-label`; the status icon is
  decorative (`aria-hidden`) because the role already conveys the meaning.

---

<!-- Feedback / Loader: /docs/components/loader -->

# Loader

An indeterminate loading indicator in five variants, with a screen-reader label
built in.

```tsx
import { Loader } from "astralis-ui";

export function LoaderDemo() {
  return <Loader size="xl" />;
}
```

## Import

```tsx
import { Loader } from "astralis-ui";
```

## Variants

`blocks` is the default: the Astralis mark assembling itself. `spinner` is a
rotating arc, `dots` three dots in sequence, `bars` an equaliser, and `pulse` a
dot sending out rings.

```tsx
import { HStack, Loader, Text, VStack } from "astralis-ui";

const variants = ["blocks", "spinner", "dots", "bars", "pulse"] as const;

export function LoaderVariants() {
  return (
    <HStack gap="10" wrap="wrap" justifyContent="center">
      {variants.map((variant) => (
        <VStack key={variant} gap="3" alignItems="center">
          <Loader variant={variant} size="xl" />
          <Text size="xs" color="muted">
            {variant}
          </Text>
        </VStack>
      ))}
    </HStack>
  );
}
```

## Sizes

```tsx
import { HStack, Loader } from "astralis-ui";

export function LoaderSizes() {
  return (
    <HStack gap="6" alignItems="center">
      <Loader size="xs" />
      <Loader size="sm" />
      <Loader size="md" />
      <Loader size="lg" />
      <Loader size="xl" />
    </HStack>
  );
}
```

## Color schemes

Every variant paints with the accent channel, so any scheme works.

```tsx
import { HStack, Loader } from "astralis-ui";

export function LoaderSchemes() {
  return (
    <HStack gap="6" alignItems="center">
      <Loader size="lg" colorScheme="brand" />
      <Loader size="lg" colorScheme="blue" variant="dots" />
      <Loader size="lg" colorScheme="green" variant="bars" />
      <Loader size="lg" colorScheme="purple" variant="pulse" />
      <Loader size="lg" colorScheme="gray" variant="spinner" />
    </HStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | "blocks" \| "spinner" \| "dots" \| "bars" \| "pulse" | `"blocks"` | Which animation. blocks is the Astralis mark assembling itself. |
| `size` | "xs" \| "sm" \| "md" \| "lg" \| "xl" | `"md"` | Width and height of the indicator. |
| `colorScheme` | all 15 schemes | `"brand"` | Hue of the indicator. |
| `label` | string | `"Loading…"` | Visually-hidden text announced to screen readers. |

## Accessibility

- Renders `role="status"` with a visually-hidden label, so assistive tech
  announces the loading state without any extra wiring.
- The animation keeps running under `prefers-reduced-motion`, because it
  conveys state, not decoration. Pair long operations with
  [Progress](/docs/components/progress) when you can report actual completion.

---

<!-- Feedback / Progress: /docs/components/progress -->

# Progress

Determinate or indeterminate progress, as a linear bar or a circular ring.

```tsx
import { Progress, VStack } from "astralis-ui";

export function ProgressDemo() {
  return (
    <VStack gap="5" alignItems="stretch" w="full" maxW="md">
      <Progress value={30} size="sm" />
      <Progress value={62} showValueLabel />
      <Progress value={88} size="lg" colorScheme="green" />
      <Progress />
    </VStack>
  );
}
```

## Import

```tsx
import { Progress } from "astralis-ui";
```

## Circular

```tsx
import { HStack, Progress } from "astralis-ui";

export function ProgressCircle() {
  return (
    <HStack gap="8" alignItems="center">
      <Progress shape="circle" value={25} size="sm" />
      <Progress shape="circle" value={62} showValueLabel />
      <Progress shape="circle" value={88} size="lg" colorScheme="purple" showValueLabel />
      <Progress shape="circle" />
    </HStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | number | None | Current progress. **Omit entirely for indeterminate.** |
| `max` | number | `100` | The value that counts as 100%. |
| `shape` | "line" \| "circle" | `"line"` | Bar or ring. |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Bar height / ring diameter. |
| `colorScheme` | all 15 schemes | `"brand"` | Hue of the filled portion. |
| `showValueLabel` | boolean | `false` | Percentage text (hidden while indeterminate). |

## Accessibility

- Renders `role="progressbar"` with `aria-valuemin/max/now` and a percentage
  `aria-valuetext`; indeterminate mode omits `aria-valuenow`, which is the
  standard ARIA signal for "busy, duration unknown".
- Give each bar an accessible name (`aria-label="Uploading photos"`) when
  more than one is on screen.

---

<!-- Feedback / Skeleton: /docs/components/skeleton -->

# Skeleton

A pulsing placeholder that holds space while content loads.

```tsx
import { Box, HStack, Skeleton, VStack } from "astralis-ui";

export function SkeletonDemo() {
  return (
    <Box w="sm" maxW="full">
      <HStack gap="4" alignItems="center">
        <Skeleton variant="circle" w="12" h="12" shrink="0" />
        <VStack gap="2" alignItems="stretch" flex="1">
          <Skeleton variant="text" w="3/4" />
          <Skeleton variant="text" />
        </VStack>
      </HStack>
      <Skeleton variant="rect" mt="4" h="24" />
    </Box>
  );
}
```

## Import

```tsx
import { Skeleton } from "astralis-ui";
```

## Swapping in real content

Pass `loaded` with the real content as children: the placeholder and the
content occupy the same slot, so nothing jumps when data arrives.

```tsx
"use client";

import { useState } from "react";
import { Avatar, Box, Button, HStack, Skeleton, Text, VStack } from "astralis-ui";

export function SkeletonLoaded() {
  const [loaded, setLoaded] = useState(false);

  return (
    <VStack gap="4" alignItems="start">
      <Box w="sm" maxW="full">
        <HStack gap="4" alignItems="center">
          <Skeleton variant="circle" loaded={loaded} w="12" h="12" shrink="0">
            <Avatar name="Nova Starling" />
          </Skeleton>
          <VStack gap="1" alignItems="stretch" flex="1">
            <Skeleton variant="text" loaded={loaded} w="1/2">
              <Text weight="semibold">Nova Starling</Text>
            </Skeleton>
            <Skeleton variant="text" loaded={loaded}>
              <Text size="sm" color="muted">Mission specialist · Astralis Station</Text>
            </Skeleton>
          </VStack>
        </HStack>
      </Box>
      <Button size="sm" variant="subtle" onClick={() => setLoaded((v) => !v)}>
        {loaded ? "Show skeleton" : "Finish loading"}
      </Button>
    </VStack>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | "text" \| "circle" \| "rect" | `"text"` | Placeholder shape (size `circle`/`rect` via className or style). |
| `animated` | boolean | `true` | Pulse animation, automatically paused under `prefers-reduced-motion`. |
| `loaded` | boolean | `false` | Render children instead of the placeholder. |

## Accessibility

The placeholder is `aria-hidden`: it's decoration, not information. If the
loading state itself matters to screen-reader users, set `aria-busy` on the
region or show a [Loader](/docs/components/loader).

---

<!-- Feedback / Toast: /docs/components/toast -->

# Toast

Ephemeral notifications fired imperatively from anywhere: no context, no wiring.

```tsx
"use client";

import { Button, HStack, Toaster, toast } from "astralis-ui";

export function ToastDemo() {
  return (
    <>
      {/* Mount ONE Toaster near your app root. It catches toasts from anywhere. */}
      <Toaster placement="bottom-end" />
      <HStack gap="3" wrap="wrap">
        <Button size="sm" colorScheme="blue" variant="subtle" onClick={() => toast.info("Heads up", { description: "A new version is available." })}>
          Info
        </Button>
        <Button size="sm" colorScheme="green" variant="subtle" onClick={() => toast.success("Deploy complete", { description: "v0.2.0 is live." })}>
          Success
        </Button>
        <Button size="sm" colorScheme="orange" variant="subtle" onClick={() => toast.warning("Approaching quota")}>
          Warning
        </Button>
        <Button size="sm" colorScheme="red" variant="subtle" onClick={() => toast.error("Payment failed", { description: "Your card was declined." })}>
          Error
        </Button>
      </HStack>
    </>
  );
}
```

## Import

```tsx
import { Toaster, toast } from "astralis-ui";
```

Mount **one** `<Toaster />` near your app root (inside `AstralisProvider`),
then call `toast(...)` from any event handler, effect, or async flow. The
store is module-level, so it works outside React trees too.

## Options: actions, sticky toasts, dismiss

```tsx
"use client";

import { Button, HStack, toast } from "astralis-ui";

export function ToastOptions() {
  return (
    <HStack gap="3" wrap="wrap">
      <Button
        size="sm"
        variant="outline"
        onClick={() =>
          toast({
            title: "File deleted",
            description: "report-final-v2.pdf was moved to trash.",
            status: "info",
            action: { label: "Undo", onClick: () => toast.success("Restored") },
          })
        }
      >
        With action
      </Button>
      <Button
        size="sm"
        variant="outline"
        onClick={() =>
          toast({
            title: "Copies itself to your clipboard history",
            duration: null,
            status: "warning",
          })
        }
      >
        Sticky (duration: null)
      </Button>
      <Button size="sm" variant="text" colorScheme="gray" onClick={() => toast.dismiss()}>
        Dismiss all
      </Button>
    </HStack>
  );
}
```

## `toast()` API

| Call | Returns | Description |
| --- | --- | --- |
| `toast(options)` | `id` | Full-control form. |
| `toast.info/success/warning/error(title, options?)` | `id` | Status shorthands. |
| `toast.dismiss(id?)` | None | Close one toast, or all when called with no id. |

### Options

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | ReactNode | None | The headline. Required. |
| `description` | ReactNode | None | Supporting copy. |
| `status` | "info" \| "success" \| "warning" \| "error" | `"info"` | Picks the icon and hue, and whether the announcement is polite or assertive. |
| `colorScheme` | all 15 schemes | `from status` | Hue override. |
| `duration` | number \| null | `5000` | Auto-dismiss delay in ms; null keeps the toast until it's dismissed. |
| `closable` | boolean | `true` | Shows the dismiss button and lets Escape dismiss the focused toast. |
| `action` | { label: string; onClick: () => void } | None | A button after the text. |

### `<Toaster />` props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `placement` | "top-start" \| "top-center" \| "top-end" \| "bottom-start" \| "bottom-center" \| "bottom-end" | `"bottom-end"` | The screen corner or edge the stack grows from. |
| `max` | number | `5` | How many toasts show at once, newest first. The rest wait their turn. |

## Keyboard

Toasts never take focus when they appear, so they don't interrupt typing.
They sit in a "Notifications" region you can `Tab` into.

| Key | Action |
| --- | --- |
| `Tab` | Move to a toast's action and dismiss buttons |
| `Enter` / `Space` | Activate the focused button |
| `Esc` | Dismiss the focused toast and return focus to where it was |

`Esc` only dismisses a closable toast, and it doesn't also close a Modal or
Popover open behind it.

## Accessibility

- Toasts are announced through two live regions the Toaster mounts empty:
  polite for `info` and `success`, assertive for `warning` and `error`.
  Regions that exist before their text arrives are announced reliably across
  screen readers, unlike one inserted already filled.
- The toasts themselves sit in a `role="region"` labelled "Notifications".
- Hovering a toast, or moving focus into it, pauses the auto-dismiss timer,
  which resumes with the **remaining** time, so slow readers aren't raced.

---

<!-- Feedback / Empty State: /docs/components/empty-state -->

# Empty State

A placeholder for "no results", "nothing here yet" and recoverable-error
moments. Pure composition: the whole compound renders as a Server Component
and ships **zero client JavaScript**. Size travels to the parts via a data
attribute, not context.

```tsx
import { EmptyState, Button } from "astralis-ui";
import { Inbox } from "lucide-react";

// No "use client": EmptyState is pure composition and ships zero client JS.
export function EmptyStateDemo() {
  return (
    <EmptyState>
      <EmptyState.Indicator>
        <Inbox />
      </EmptyState.Indicator>
      <EmptyState.Title>No messages yet</EmptyState.Title>
      <EmptyState.Description>
        When someone writes to you, the conversation will show up here.
      </EmptyState.Description>
      <EmptyState.Actions>
        <Button size="sm">New message</Button>
        <Button size="sm" variant="outline" colorScheme="gray">
          Invite people
        </Button>
      </EmptyState.Actions>
    </EmptyState>
  );
}
```

## Import

```tsx
import { EmptyState } from "astralis-ui";
```

## Sizes

```tsx
import { EmptyState, Flex } from "astralis-ui";
import { SearchX } from "lucide-react";

export function EmptyStateSizes() {
  return (
    <Flex gap="6" alignItems="start" wrap="wrap">
      {(["sm", "md", "lg"] as const).map((size) => (
        <EmptyState key={size} size={size}>
          <EmptyState.Indicator>
            <SearchX />
          </EmptyState.Indicator>
          <EmptyState.Title>No results</EmptyState.Title>
          <EmptyState.Description>size=&quot;{size}&quot;</EmptyState.Description>
        </EmptyState>
      ))}
    </Flex>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | "sm" \| "md" \| "lg" | `"md"` | Scales the indicator, title and description together. |

### Parts

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `EmptyState.Indicator` | div props | None | Muted circle around an icon. Hidden from assistive technology, since the icon is decorative. |
| `EmptyState.Title` | div props | None | The headline. It isn't a heading element, so wrap it in one when it should appear in the outline. |
| `EmptyState.Description` | div props | None | Supporting copy, capped at a readable line length. |
| `EmptyState.Actions` | div props | None | A wrapping row for one or two Buttons. |