# ljkui — full documentation

> ljkui — a React component library. Themeable, ESM-only, ships its own CSS. Import components from `ljkui`, import `ljkui/styles.css` once, wrap your app in `<Theme>`.

Start with llms.txt if you have not read it — it has the setup and the rules.

---

# Guides

## Adopting tokens

ljkui is a token-first library. Instead of hard-coding hex colors and one-off pixel
values, you reach for the design tokens — Tailwind-style utilities like
`bg-accent-700`, `text-gray-900`, `border-gray-alpha-300`, and the matching CSS
custom properties `var(--accent-700)`, `var(--gray-900)`. Every palette ships as a
12-step scale whose steps are semantic **roles** (10–50 backgrounds,
100–300 fills, 400–600 borders, 700–800 solid, 900–950 text), so a token keeps its
meaning across themes and light/dark — a raw hex never does.

To make that migration painless there's a small checker/codemod, `lint-raw-colors`,
that scans your source for raw hex colors and tells you the nearest token.

## What it does

- Recursively scans `.ts` / `.tsx` / `.js` / `.jsx` / `.css` files.
- Finds raw hex colors (`#rgb`, `#rrggbb`, `#rrggbbaa`) in classNames, `style`
  objects, and CSS values.
- For each one, computes the **nearest token by color distance** — it converts the
  hex to CIELAB and finds the closest step across the shipped palettes, using the
  real seed values extracted from the library's `palettes.css` at build time (so it
  never goes stale against the library).
- Reports `file:line:col  #hex → utility / var(...)  [ΔE distance]`. A chromatic
  match is suggested as the configurable `accent` scale (what you usually want); a
  neutral match is suggested as `gray`.
- With `--fix`, conservatively rewrites the unambiguous className cases in place —
  `className="bg-[#3b82f6]"` becomes `className="bg-accent-800"`. Bare hex in a
  `style` object or CSS value is reported but never auto-edited.
- Exits non-zero when anything is found, so you can gate CI — unless you pass
  `--report-only`.

## Running it

The tool ships **with the `ljkui` package** as a bin, so you can run it in your own
project with no setup:

```sh
# scan your app (default path "."):
bunx ljkui-lint-raw-colors src

# just report, don't fail CI:
bunx ljkui-lint-raw-colors src --report-only

# rewrite the confident className cases:
bunx ljkui-lint-raw-colors src --fix

# also flag arbitrary Tailwind spacing (p-[13px] → p-3):
bunx ljkui-lint-raw-colors src --spacing
```

Working in the ljkui repo itself? Run the same tool from source:

```sh
bun src/bin/lint-raw-colors.ts ../../path/to/your/app/src
```

Example output:

```text
src/Card.tsx:12:20  #3b82f6 → bg-accent-800 / var(--accent-800)  [ΔE 18.5]
src/Card.tsx:14:11  #111827 → bg-gray-950 / var(--gray-950)      [ΔE 4.2]
src/theme.css:3:15  #f11325 → bg-accent-700 / var(--accent-700)  [ΔE 0.0 (exact)]

3 raw color(s) across 1 file(s).
```

## The token-first philosophy

A raw hex encodes one appearance. A token encodes an **intent** — "solid accent",
"subtle border", "body text" — and resolves to the right value for the active theme,
for light and dark, and for whatever `accentColor` the consumer picks. Adopting
tokens is mostly a search-and-replace once you know the mapping, and that mapping is
exactly what this tool prints. Wire it into CI in `--report-only` mode first to see
the scope, then drop `--report-only` once you're clean.

---

> **Maintainer note:** this guide is not yet wired into the Storybook `GUIDES` array in
> `scripts/generate-storybook.ts` — add `adopting-tokens` there to surface it.

---

## Breakpoints

Breakpoints allow you to build responsive layouts based on different screen sizes.

## Available breakpoints

Breakpoints are `min-width` based (mobile-first) and apply when the screen width is equal or greater than given breakpoint.

<table>
  <tr>
    <td>Size</td>
    <td>Screen</td>
    <td>Width</td>
  </tr>
  <tr>
    <td>initial</td>
    <td>Phones (portrait)</td>
    <td>0px</td>
  </tr>
  <tr>
    <td>xs</td>
    <td>Phones (landscape)</td>
    <td>520px</td>
  </tr>
  <tr>
    <td>sm</td>
    <td>Tablets (portrait)</td>
    <td>768px</td>
  </tr>
  <tr>
    <td>md</td>
    <td>Tablets (landscape)</td>
    <td>1024px</td>
  </tr>
  <tr>
    <td>lg</td>
    <td>Laptops</td>
    <td>1280px</td>
  </tr>
  <tr>
    <td>xl</td>
    <td>Desktops</td>
    <td>1640px</td>
  </tr>
</table>

---

## Color system

The color palettes in ljkui are the [Tailwind CSS v4 palettes](https://tailwindcss.com/docs/colors),
each extended with an extra light shade to form a 12-step scale with light, dark and alpha variants.

Colors are grouped into 3 categories: `accents`, `grays`, and `semantic` (info, success, warning, danger).
All of these can be specified on your `<Theme />`, or per component where appropriate.

## Understanding the scale

Steps are named after the Tailwind stops, with an extra `10` step for the additional light shade —
so a scale reads `10, 50, 100, 200, … 900, 950`, and `accent-950` is the darkest step.

Each scale has 12 steps with dedicated roles — `10`-`50` backgrounds, `100`-`300` component
backgrounds, `400`-`600` borders, `700`-`800` solid colors, `900`-`950` text.

<Callout type="warn">
  **A step's name is not the Tailwind stop it is built from**, in either light or dark mode.
  `accent-500` is a *border*, so it is derived from around Tailwind's `300`, not its `500`.
</Callout>

The scales are Tailwind palettes fitted onto these roles, not Tailwind's ramp renamed. Six of the
twelve steps are backgrounds and borders, so they all live in the light half of the palette; the
solid step is the vivid form of the hue and is the *same color* in light and dark; and the `900`
text step is solved for a contrast ratio against `10` rather than pinned to a stop. If you want
Tailwind's stop values themselves, use Tailwind's own `blue-500` utility — `accent-500` is a role.

## Solid and alpha

Every scale ships twice. `--accent-200` is opaque; `--accent-alpha-200` is the same step as a
translucent color, so it **tints** whatever is behind it instead of covering it — over the page
background it lands on exactly the solid step, and over a panel it keeps its hue.

This is why the alpha scale exists rather than an opacity modifier: `bg-accent-alpha-200` is a
saturated color at low alpha, whereas `bg-accent-200/50` fades the already-pale solid step toward
whatever is behind it, which goes grey on dark backgrounds. Use the alpha steps for anything layered
over a surface — soft variants, hover states, borders.

```tsx
<div className="bg-accent-200" />        // opaque
<div className="bg-accent-alpha-200" />  // tints the surface underneath
```

---

## Forms & Field Binding

Every ljkui input is a thin, styled wrapper over a native control. The library owns
the look — you own the state. That means an input binds to whatever holds your form
state (React `useState`, a native `<Form>`, or a form library) through one small,
predictable prop contract, and never depends on the form library itself.

The `ljkui` package ships **no** form dependency. `@tanstack/react-form` is a dev
dependency used only by the examples — you bring your own.

## The binding contract

Each input exposes a controlled/uncontrolled surface plus the native form attributes:

| Concern | Text-like inputs | Boolean inputs (Checkbox, Switch) | Choice inputs (Select, RadioGroup) |
| --- | --- | --- | --- |
| Controlled value | `value` | `checked` | `value` |
| Uncontrolled default | `defaultValue` | `defaultChecked` | `defaultValue` |
| Change callback | `onValueChange` / native `onChange` | `onCheckedChange` | `onValueChange` |
| Submission key | `name` | `name` | `name` |
| Disabled | `disabled` | `disabled` | `disabled` |
| Required | `required` | `required` | `required` |

`Input.Control` forwards native DOM props, so `value` + `onChange` (the native event)
work exactly as they do on a plain `<input>`; the higher-level controls (Checkbox,
Switch, Select) expose the semantic `onCheckedChange` / `onValueChange` callbacks.

### Error / invalid state

Validation state lives on the **wrapper**, not the input. `<Field.Root>` and
`<Fieldset.Root>` own the invalid state and the error message:

- `<Field.Root invalid>` — mark the field invalid from an external source (a form
  library, a server response). This is the escape hatch when you are not using native
  constraint validation.
- `<Field.Error match="valueMissing">…</Field.Error>` — render an error keyed to a
  native validity state (`valueMissing`, `typeMismatch`, `tooShort`, `patternMismatch`, …).
- `<Field.Error match={true}>…</Field.Error>` — always render when the field is invalid,
  which is how you surface a message string that came from a form library.
- `<Field.Description>` — non-error helper text.

```tsx
<Field.Root name="email">
  <Field.Label>Email</Field.Label>
  <Input.Root>
    <Input.Control type="email" required placeholder="you@example.com" />
  </Input.Root>
  <Field.Error match="valueMissing">Email is required</Field.Error>
  <Field.Error match="typeMismatch">Please enter a valid email</Field.Error>
</Field.Root>
```

## Controlled vs uncontrolled

**Uncontrolled** is the default and the least code. Wrap fields in `<Form>` (a native
`<form>` with consolidated error handling) and read values on submit — either from the
native event or from the `onFormSubmit` callback, which hands you a plain object:

```tsx
<Form onFormSubmit={(values) => console.log(values)}>
  <Field.Root name="name">
    <Field.Label>Name</Field.Label>
    <Input.Root>
      <Input.Control placeholder="Jane Smith" defaultValue="" />
    </Input.Root>
  </Field.Root>
  <Button type="submit">Submit</Button>
</Form>
```

Native constraint validation (`required`, `minLength`, `pattern`, …) plus
`<Field.Error match="…">` covers most forms with no JavaScript state at all.

**Controlled** is what you reach for when the value drives other UI (conditional
fields, live previews, debounced auto-save) or when a form library owns the state:

```tsx
const [country, setCountry] = React.useState('us');

<Select.Root value={country} onValueChange={(v) => v && setCountry(v)} items={items}>
  <Select.Trigger placeholder="Select a country" />
  <Select.Content>…</Select.Content>
</Select.Root>;
```

## Binding a form library (TanStack Form)

Because the contract is just `value` + a change callback + an `invalid` flag, any form
library binds cleanly. With `@tanstack/react-form`, `form.Field` is a render prop that
supplies the field state; map it onto the input and forward errors into
`<Field.Root invalid>`:

```tsx
import { useForm } from '@tanstack/react-form';
import { Button, Field, Input } from 'ljkui';

function ProfileForm() {
  const form = useForm({
    defaultValues: { username: '' },
    onSubmit: async ({ value }) => save(value),
  });

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        e.stopPropagation();
        form.handleSubmit();
      }}
    >
      <form.Field
        name="username"
        validators={{
          onChange: ({ value }) =>
            value.length < 3 ? 'Username must be at least 3 characters' : undefined,
        }}
      >
        {(field) => (
          <Field.Root name={field.name} invalid={field.state.meta.errors.length > 0}>
            <Field.Label>Username</Field.Label>
            <Input.Root>
              <Input.Control
                value={field.state.value}
                onChange={(e) => field.handleChange(e.target.value)}
                onBlur={field.handleBlur}
              />
            </Input.Root>
            {field.state.meta.errors.length > 0 && (
              <Field.Error match={true}>{field.state.meta.errors[0]}</Field.Error>
            )}
          </Field.Root>
        )}
      </form.Field>

      <form.Subscribe selector={(state) => state.isSubmitting}>
        {(isSubmitting) => (
          <Button type="submit" loading={isSubmitting}>
            Save
          </Button>
        )}
      </form.Subscribe>
    </form>
  );
}
```

The three moving parts are always the same, whatever the library:

1. **Value in** — feed the library's value into `value` (or `checked`).
2. **Change out** — call the library's change handler from `onChange` /
   `onValueChange` / `onCheckedChange`.
3. **Errors** — set `invalid` on `<Field.Root>` and render `<Field.Error match={true}>`
   with the library's message.

Boolean and choice controls follow the same shape — bind `checked`/`onCheckedChange`
for `<Checkbox>` and `<Switch>`, and `value`/`onValueChange` for `<Select>`.

---

## Getting started

## Install

```sh
bun add ljkui
```

## Wrap your app in a Theme

`ljkui/styles.css` carries the tokens and a global reset; `<Theme>` scopes the
accent, gray, radius and appearance to a subtree.

```tsx
import { Theme } from 'ljkui';
import 'ljkui/styles.css';

<Theme accentColor="blue" radius="medium" appearance="inherit">
  {children}
</Theme>;
```

## With Tailwind

Import the theme bridge after Tailwind to get utilities for every design token —
`bg-accent-700`, `text-gray-900`, `border-gray-alpha-300`. The layer order matters;
see the **Tailwind plugin** guide.

```css
@layer theme, base, ljkui, components, utilities;

@import 'tailwindcss';
@import 'ljkui/styles.css' layer(ljkui);
@import 'ljkui/theme.css';
```

---

## Installation & Layers

## Install

```sh
bun add ljkui
```

`ljkui` ships ESM only and lists `react` / `react-dom` as peers.

The library ships no icon set and has no opinion about which one you use. Import icons
from your own library and pass them as children:

```tsx
import { Search } from 'lucide-react';

<Button>
  <Search /> Search
</Button>;
```

Inside a `Button` or `IconButton` the icon is sized to match the button's `size`, so an
icon that carries no intrinsic `width` / `height` still comes out right. To override,
give the icon its own size — a `className` such as Tailwind's `size-5` wins.

## The three stylesheets

ljkui ships three CSS entry points. Which you import depends on whether you use Tailwind.

| File | What it is |
| --- | --- |
| `ljkui/styles.css` | The full stylesheet: design tokens **plus** a global reset and every component's CSS. |
| `ljkui/styles.lite.css` | The same, minus the global reset — for apps that already own their reset. |
| `ljkui/theme.css` | The Tailwind bridge: exposes every design token as a Tailwind utility (`bg-accent-700`, `text-gray-900`, `border-gray-alpha-300`). Import it **only** alongside Tailwind. |

## Without Tailwind

Import the stylesheet once, at the root of your app, and wrap the tree in `<Theme>`:

```tsx
import { Theme, Button } from 'ljkui';
import 'ljkui/styles.css';

export default function App() {
  return (
    <Theme accentColor="blue" radius="medium" appearance="inherit">
      <Button>Click me</Button>
    </Theme>
  );
}
```

## With Tailwind — the layer order matters

This is the one thing that has to be exactly right. `ljkui/styles.css` carries a **global
reset**, including `h1..h6 { font-size: inherit; font-weight: inherit }`. If that reset is
imported **unlayered**, it outranks every Tailwind utility — because unlayered CSS beats all
`@layer`s — and your headings silently flatten site-wide: `text-4xl` does nothing.

The fix is to declare the layer order up front and import ljkui's reset **into** the `ljkui`
layer, so Tailwind's `utilities` layer can still win:

```css
/* app.css — the @layer statement must come first (an empty @layer is one of the
   few things allowed before @import). */
@layer theme, base, ljkui, components, utilities;

@import 'tailwindcss';
@import 'ljkui/styles.css' layer(ljkui);
@import 'ljkui/theme.css';
```

Two details that trip people up:

> **`theme.css` stays unlayered — on purpose.** It only defines custom properties. Demote it
> below Tailwind's `theme` layer and Tailwind's own `--color-*` defaults would win instead of
> ljkui's tokens.

> **Never add a remote `@import url(...)` to your ljkui imports.** A remote `@import` is only
> legal at the very top of the final stylesheet; dropped in among these it lands thousands of
> lines deep in the concatenated output, where every CSS parser rejects it. A webfont belongs in
> your document `<head>`, not here.

## Fonts

The library ships **no** `font-family` and **no** `letter-spacing` — only the size / line-height /
weight scale. Text inherits its typeface from your page, and `<Code>` / `<Kbd>` / `<DateField>`
fall back to the generic `monospace` keyword. Set your own font on `html`/`body` (or via
Tailwind's `--default-font-family`) and every component follows.

## Verify the setup

If headings look flat, or Tailwind utilities appear to do nothing on ljkui components, the layer
order is almost always the cause — re-check that `@layer theme, base, ljkui, components, utilities;`
is declared **before** the `@import`s and that `styles.css` is imported with `layer(ljkui)`.

---

## Layout

ljkui includes SwiftUI-style layout primitives. They take layout-specific props
(`spacing`, `alignment`, …) and, like every ljkui component, also accept `className` and
`style` for anything else.

<Demo name="layout" />

## HStack

Lays children out horizontally. `spacing` is the gap in pixels; `alignment` controls the
cross-axis: `top`, `center` (default), `bottom`, `firstTextBaseline`, `lastTextBaseline`.

```tsx
import { Badge, Button, HStack } from 'ljkui';

<HStack spacing={12} alignment="center">
  <Button>Save</Button>
  <Badge color="green">Synced</Badge>
</HStack>;
```

<PropsTable component="HStack" />

## VStack

Lays children out vertically. `alignment` controls the cross-axis: `leading`, `center`
(default), `trailing`.

```tsx
import { Heading, Text, VStack } from 'ljkui';

<VStack spacing={8} alignment="leading">
  <Heading size="4">Billing</Heading>
  <Text size="2" color="gray">
    Manage your subscription and invoices.
  </Text>
</VStack>;
```

<PropsTable component="VStack" />

## ZStack

Stacks children on top of each other. `alignment` positions them using SwiftUI-style values:
`center` (default), `leading`, `trailing`, `top`, `bottom`, `topLeading`, `topTrailing`,
`bottomLeading`, `bottomTrailing`, plus text-baseline variants.

```tsx
import { Avatar, Badge, ZStack } from 'ljkui';

<ZStack alignment="bottomTrailing">
  <Avatar size="5" fallback="LK" />
  <Badge color="green" size="1">
    on
  </Badge>
</ZStack>;
```

<PropsTable component="ZStack" />

## Grid and Grid.Row

A SwiftUI-style grid: the column count is the largest number of cells in any row, and cells
align across rows.

```tsx
import { Grid, Text } from 'ljkui';

<Grid horizontalSpacing={16} verticalSpacing={8}>
  <Grid.Row>
    <Text>1 × 1</Text>
    <Text>1 × 2</Text>
  </Grid.Row>
  <Grid.Row>
    <Text>2 × 1</Text>
    <Text>2 × 2</Text>
  </Grid.Row>
</Grid>;
```

<PropsTable component="Grid" />

`Grid.Row` takes no extra props beyond the standard `div` attributes.

## Spacer

Expands to fill the available space along the parent stack's axis — the SwiftUI way to push
siblings apart. `minLength` sets the minimum size in pixels.

```tsx
import { Button, Heading, HStack, Spacer } from 'ljkui';

<HStack spacing={8}>
  <Heading size="4">Members</Heading>
  <Spacer />
  <Button size="1">Invite</Button>
</HStack>;
```

<PropsTable component="Spacer" />

## Overlay

Layers `Overlay.Content` children in front of the remaining children, matching SwiftUI's
`.overlay(alignment:)` semantics:

```tsx
import { Card, Overlay, Spinner } from 'ljkui';

<Overlay alignment="center">
  <Card size="3">Loading…</Card>
  <Overlay.Content>
    <Spinner />
  </Overlay.Content>
</Overlay>;
```

<PropsTable component="Overlay" />

`Overlay.Content` takes no extra props beyond the standard `div` attributes.

## Escape hatches

Every layout component forwards standard `div` props, so `className` (e.g. Tailwind utilities)
and `style` compose naturally with the SwiftUI-style props:

```tsx
<HStack spacing={12} className="rounded-lg border p-4">
  …
</HStack>
```

---

## Oscar

A single page that puts a spread of ljkui components side by side — profile cards, badges, lists,
tables, progress, switches, alerts, tabs, typography, tooltips, and empty states — with one thing in
common: every one of them mentions Oscar.

It doubles as a quick tour of how the components look next to each other, rather than one at a time
on their own page.

<Examples name="oscar" />

---

## Render Prop (Composition)

Several ljkui components support a `render` prop that allows you to customize the underlying element while preserving the component's functionality and styling. This is useful for integrating with routing libraries, using semantic HTML elements, or composing with other components.

## What is the render prop?

The `render` prop lets you replace the default HTML element that a component renders while keeping all of its behavior, styling, and props intact.

For example, `<Text>` renders a `<span>` by default, but you might want it to render as a `<label>` for form accessibility, or as a Next.js `<Link>` for navigation.

## Basic Usage

### Using a React Element

The simplest way to use the `render` prop is to pass a React element:

```tsx
import { Text } from 'ljkui';

// Text renders as a <label> instead of <span>
<Text render={<label htmlFor="email" />}>Email address</Text>;
```

The component will clone your element and merge its props onto it. Your element's attributes (like `htmlFor`) are preserved.

### Using a Callback Function

For more control, you can pass a function that receives the merged props:

```tsx
import { Text } from 'ljkui';

<Text render={(props) => <label {...props} htmlFor="email" />}>Email address</Text>;
```

This gives you explicit control over how props are spread and merged.

## Components That Support render

The following components support the `render` prop:

| Component          | Default Element | Common Use Cases               |
| ------------------ | --------------- | ------------------------------ |
| `Text`             | `<span>`        | Labels, links, custom elements |
| `Heading`          | `<h1>`          | Custom heading levels, links   |
| `Card`             | `<div>`         | Links, buttons, articles       |
| `Theme`            | `<div>`         | Custom wrapper elements        |
| `Breadcrumbs.Root` | `<nav>`         | Custom navigation wrappers     |
| `WidgetStack.Next` | `<button>`      | Custom button components       |
| `WidgetStack.Prev` | `<button>`      | Custom button components       |

## Integration with Routing Libraries

One of the most common use cases is integrating with routing libraries like Next.js, React Router, or TanStack Router.

### Next.js App Router

```tsx
import Link from 'next/link';
import { Text, Card, Heading } from 'ljkui';

// Text as a Next.js Link
<Text render={<Link href="/about" />}>
  About us
</Text>

// Card as a clickable link
<Card render={<Link href="/product/123" />}>
  <Heading size="3">Product Name</Heading>
  <Text>Click to view details</Text>
</Card>
```

### React Router

```tsx
import { Link } from 'react-router-dom';
import { Text } from 'ljkui';

<Text render={<Link to="/dashboard" />}>Go to Dashboard</Text>;
```

### TanStack Router

```tsx
import { Link } from '@tanstack/react-router';
import { Card } from 'ljkui';

<Card render={<Link to="/users/$userId" params={{ userId: '123' }} />}>User Profile Card</Card>;
```

## How Props Are Merged

Understanding how props are merged is crucial for avoiding unexpected behavior.

### Priority Order (Lowest to Highest)

When using the element form of `render`, props are merged in this order:

```
1. Props on the component          → LOWEST priority (can be overridden)
2. Props on the render element     → HIGHEST priority (wins for conflicts)
```

The render element's props win because you're explicitly saying "render THIS element with THESE props".

**Example:**

```tsx
<Link data-testid="link-id" href="/page-one" render={<a data-testid="anchor-id" href="/page-two" />}>
  Click me
</Link>

// Result HTML:
// <a data-testid="anchor-id" href="/page-two" class="fui-Text fui-Link ...">Click me</a>

// The render element's props won:
// - data-testid="anchor-id" (not "link-id")
// - href="/page-two" (not "/page-one")
// - className was CONCATENATED (both component and internal classes)
```

### Why Does This Happen?

Internally, `useRender` merges props using Base UI's `mergeProps` utility, with the render element's props taking precedence. This design choice means: **the element you explicitly provide keeps its props**.

This is useful when you want the render element to "own" certain props:

```tsx
// NextLink controls the href, Link just adds styling
<Link render={<NextLink href="/dashboard" prefetch={false} />}>Go to Dashboard</Link>
```

### Callback Form: You Control Everything

With the callback form, YOU decide exactly how props are merged by where you place the spread:

```tsx
// Component props win (spread them LAST)
<Link href="/one" render={(props) => <a href="/two" {...props} />}>
  Click me
</Link>
// Result: href="/one" (because {...props} overwrites href="/two")

// Render element props win (put them LAST)
<Link href="/one" render={(props) => <a {...props} href="/two" />}>
  Click me
</Link>
// Result: href="/two" (because href="/two" overwrites the spread)
```

Use the callback form when you need the component's props to take precedence.

### Special Merge Behaviors

Not all props follow the "render element wins" rule. Some are merged specially:

| Prop Type                        | Behavior                                       | Example Result                                  |
| -------------------------------- | ---------------------------------------------- | ----------------------------------------------- |
| `className`                      | **Concatenated** - all classes kept            | `"fui-Text your-class element-class"`           |
| `style`                          | **Shallow merged** - render element's keys win | Combined styles, conflicts go to render element |
| Event handlers (`onClick`, etc.) | **Both run**                                   | Both handlers execute                           |
| Everything else                  | **Render element wins**                        | `data-x="from-render-element"`                  |
| `ref`                            | Only one ref is kept (component's ref)         |

## Using the as Prop (Alternative)

Some components also support an `as` prop for simple element changes without needing `render`:

```tsx
import { Text, Heading } from 'ljkui';

// Simple element change with `as`
<Text as="label">Email</Text>
<Text as="p">A paragraph of text</Text>
<Text as="div">A div element</Text>

<Heading as="h2">Section Title</Heading>
<Heading as="h3">Subsection</Heading>
```

**When to use `as` vs `render`:**

| Use `as` when...                 | Use `render` when...                 |
| -------------------------------- | ------------------------------------ |
| Changing to a basic HTML element | Integrating with external components |
| No additional props needed       | Need to pass props to the element    |
| Simple semantic changes          | Complex composition scenarios        |

```tsx
// ✅ Use `as` for simple cases
<Text as="label">Simple label</Text>

// ✅ Use `render` when you need props on the element
<Text render={<label htmlFor="email" />}>Email with htmlFor</Text>
```

## Common Patterns

### Form Labels with Text

```tsx
import { Text, TextField } from 'ljkui';

<div>
  <Text as="label" htmlFor="username" size="2" weight="medium">
    Username
  </Text>
  <TextField.Root id="username" placeholder="Enter username" />
</div>;
```

### Clickable Cards

```tsx
import Link from 'next/link';
import { Card, Heading, Text } from 'ljkui';

function ProductCard({ product }) {
  return (
    <Card render={<Link href={`/products/${product.id}`} />}>
      <Heading size="3">{product.name}</Heading>
      <Text color="gray">{product.description}</Text>
    </Card>
  );
}
```

### Custom Navigation Buttons

```tsx
import { WidgetStack, IconButton } from 'ljkui';
import { ChevronLeft, ChevronRight } from 'lucide-react';

<WidgetStack.Root>
  <WidgetStack.Prev render={<IconButton variant="soft" />}>
    <ChevronLeft size={16} />
  </WidgetStack.Prev>

  <WidgetStack.Content>{/* slides */}</WidgetStack.Content>

  <WidgetStack.Next render={<IconButton variant="soft" />}>
    <ChevronRight size={16} />
  </WidgetStack.Next>
</WidgetStack.Root>;
```

### Nested Theme with Custom Element

```tsx
import { Theme } from 'ljkui';

// Theme as a section element
<Theme render={<section aria-label="Dark mode preview" />} appearance="dark">
  <MyContent />
</Theme>;
```

## Pitfalls and How to Avoid Them

### 1. Nested Buttons (Invalid HTML)

**Problem:** Some components render a `<button>` by default. If you put another button-like component inside, you get invalid nested buttons.

```tsx
// ❌ BAD: Creates <button><button>...</button></button>
<WidgetStack.Next>
  <IconButton>
    <ChevronRightIcon />
  </IconButton>
</WidgetStack.Next>
```

**Solution:** Use the `render` prop to make the IconButton the rendered element:

```tsx
// ✅ GOOD: IconButton IS the rendered element
<WidgetStack.Next render={<IconButton variant="soft" />}>
  <ChevronRightIcon />
</WidgetStack.Next>
```

### 2. Forgetting to Spread Props in Callback

**Problem:** When using the callback form, forgetting to spread props loses the component's functionality.

```tsx
// ❌ BAD: Lost all Text styling and props
<Text render={(props) => <label>Email</label>}>Email</Text>
```

**Solution:** Always spread the props:

```tsx
// ✅ GOOD: Props are spread onto the element
<Text render={(props) => <label {...props}>Email</label>}>Email</Text>
```

### 3. Conflicting Props Confusion

**Problem:** Not understanding which props win when there are conflicts.

```tsx
// ⚠️ Example 1: className - which is applied?
<Text className="my-class" render={<span className="other-class" />}>
  Hello
</Text>
// Answer: BOTH! classNames are concatenated
// Result: className="fui-Text my-class other-class"

// ⚠️ Example 2: data attributes - which wins?
<Text data-testid="text-id" render={<span data-testid="span-id" />}>
  Hello
</Text>
// Answer: Render element wins!
// Result: data-testid="span-id"
```

**Solution:** Remember the priority order:

1. Props on component → can be overridden
2. Props on render element → win for conflicts
3. `className` is special → always concatenated
4. Use callback form with `{...props}` spread LAST if you need component props to win

### 4. Refs Don't Merge

**Problem:** If you need a ref on the rendered element, only one ref will work.

```tsx
// ⚠️ Only one ref will be attached
const myRef = useRef(null);
<Text render={<span ref={myRef} />}>Hello</Text>;
```

**Solution:** Use the callback form and handle refs manually if needed:

```tsx
const myRef = useRef(null);
<Text
  render={(props) => {
    // Combine refs if needed using a callback ref or mergeRefs utility
    return <span {...props} ref={myRef} />;
  }}
>
  Hello
</Text>;
```

### 5. TypeScript: Missing Props

**Problem:** TypeScript might not know about props from the render element.

```tsx
// TypeScript doesn't know about htmlFor
<Text render={<label />} htmlFor="email">
  Email
</Text>
```

**Solution:** Use the callback form for proper typing:

```tsx
<Text render={(props) => <label {...props} htmlFor="email" />}>Email</Text>
```

## Migration from asChild

If you're migrating from an older version of ljkui that used `asChild`, here's how to update:

```tsx
// ❌ OLD: asChild pattern
<Text asChild>
  <label htmlFor="email">Email</label>
</Text>

// ✅ NEW: render prop pattern
<Text render={<label htmlFor="email" />}>
  Email
</Text>
```

The key differences:

- `asChild` made the child THE element and merged parent props down
- `render` specifies what element to render and merges YOUR props onto it
- Children are now passed as normal children, not as the render target

### Quick Migration Guide

| Old (asChild)                               | New (render)                               |
| ------------------------------------------- | ------------------------------------------ |
| `<Text asChild><label>Email</label></Text>` | `<Text render={<label />}>Email</Text>`    |
| `<Card asChild><a href="/">...</a></Card>`  | `<Card render={<a href="/" />}>...</Card>` |
| `<Heading asChild><h2>Title</h2></Heading>` | `<Heading as="h2">Title</Heading>`         |

## Summary

- Use `render` to customize the underlying element while keeping component behavior
- Element form (`render={<element />}`): Simple, but **render element's props win** for conflicts
- Callback form (`render={(props) => ...}`): Full control - spread `{...props}` last if you want component props to win
- Use `as` for simple HTML element changes when you don't need extra props
- Always spread props in the callback form to preserve component styling
- Watch out for nested buttons and ref merging
- `className` is always concatenated, other conflicting props go to the render element

---

## Tailwind plugin

If you want to use ljkui with Tailwind CSS, you can use the ljkui Tailwind plugin.
The plugin maps all of the FUI color tokens, font related tokens and screen breakpoints to Tailwind CSS classes.

## Usage

Add the `ljkuiThemePlugin` to `plugins` in your `tailwind.config.js` file.

```js
import { ljkuiThemePlugin } from 'ljkui/tailwind';

export default {
  darkMode: ['class'],
  content: [],
  theme: {
    extend: {},
  },
  plugins: [ljkuiThemePlugin()],
};
```

Then instead of importing `ljkui/styles.css` stylesheet in your JSX,
do it in your Tailwind `globals.css` file like this. Remember to use the `@config` directive to point to your `tailwind.config.js` file.

```css
@config "../tailwind.config.js";
@layer theme, base, ljkui, components, utilities;

@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/preflight.css' layer(base);
@import 'tailwindcss/utilities.css' layer(utilities);
@import 'ljkui/styles.css' layer(ljkui);
```

Then you can use the ljkui tokens via Tailwind classes.

```tsx
<div className="text-1 leading-1 bg-gray-alpha-50 text-success-700">ljkui</div>
```

---

## Theming

All theming happens through the `Theme` component and CSS variables.

```tsx
import { Theme } from 'ljkui';

<Theme accentColor="blue" appearance="inherit">
  <App />
</Theme>;
```

Configuration is managed and applied via `<Theme />`, including the semantic colors:

```tsx
<Theme
  // Sets Light or Dark mode
  appearance="dark"
  // Accent color (mainly used as a default color for interactive elements)
  accentColor="blue"
  // Semantic colors
  infoColor="sky"
  successColor="green"
  warningColor="yellow"
  dangerColor="red"
>
  {children}
</Theme>
```

## Theme props

<PropsTable component="Theme" />

## Accent colors

`accentColor` selects the color scale used by interactive components (buttons, switches,
checkboxes, badges, …). The scales are the Tailwind CSS v4 palettes — each one extended with an
extra light shade (step `10`) to form the 12-step scale components consume:

`red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`,
`indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`, and the neutrals `slate`, `gray`,
`zinc`, `neutral`, `stone`.

```tsx
<Theme accentColor="emerald">…</Theme>
```

Most components also accept a per-instance `color` prop that overrides the theme accent:

```tsx
<Button color="rose">Delete</Button>
<Badge color="emerald">New</Badge>
```

## Custom palettes

For brand colors not covered by the Tailwind palettes, generate a custom 12-step
scale (light + dark + alpha variants) with the palette helpers:

```tsx
import { createPaletteCss, createPaletteFromColor } from 'ljkui';

// 1. Expand a single brand color into a full Tailwind-style 50–950 palette…
const palette = createPaletteFromColor('#5b3df5');

// 2. …then generate self-contained CSS for it. Inject it once (a CSS file or <style> tag).
const css = createPaletteCss('my-brand', palette);
```

If you already have a full Tailwind-style palette (stops 50–950), pass it to `createPaletteCss`
directly. Once the CSS is injected, the name works everywhere a scale name does:

```tsx
<Theme accentColor="my-brand">…</Theme>
// or scope it to a subtree:
<div data-accent-color="my-brand">…</div>
// or use the raw tokens:
// var(--my-brand-9), var(--my-brand-a3), …
```

## Gray scale

The gray scale is fixed. `--gray-10` through `--gray-950` are always Tailwind's `neutral`
palette, in both light and dark mode. There is no prop for it.

## Light and dark

- `appearance="inherit"` (recommended): follows a `light` or `dark` class on an ancestor
  element, so it integrates with any theme switcher.
- `appearance="light" | "dark"`: forces a mode and keeps the document class in sync.

## Fonts

There is nothing to configure: ljkui sets no `font-family` and no `letter-spacing`, so components
inherit your page's type. Set it wherever you normally would:

```css
body {
  font-family: 'Inter', sans-serif;
}
```

`<Code>`, `<Kbd>` and `<DateField>` use the generic `monospace` keyword; override `.fui-Code` and friends
if you want a specific mono. See **Guides → Typography** for the size scale and self-hosting recipes.

## Scrollbars

Thin, themed scrollbars are opt-in. Add the `fui-scrollbar-thin` class to any scroll container
to get a slim scrollbar that follows the theme:

```html
<div class="fui-scrollbar-thin" style="overflow: auto">…</div>
```

---

## Typography

Components like `<Heading />` and `<Text />` and used to render titles and body copy respectively.
Both of them share the same size and weight props to enforce consistent typography in your app.

## Typography scale

The typography scale is a 10 step scale where each step has its corresponding font-size and line-height value.
There is no letter-spacing step — ljkui sets no tracking at all, so text keeps whatever your own stylesheet
specifies.

<table>
  <tr>
    <td>Step</td>
    <td>Size</td>
    <td>Line height</td>
  </tr>
  <tr>
    <td>0</td>
    <td>10px</td>
    <td>12px</td>
  </tr>
  <tr>
    <td>1</td>
    <td>12px</td>
    <td>16px</td>
  </tr>
  <tr>
    <td>2</td>
    <td>14px</td>
    <td>20px</td>
  </tr>
  <tr>
    <td>3</td>
    <td>16px</td>
    <td>24px</td>
  </tr>
  <tr>
    <td>4</td>
    <td>18px</td>
    <td>26px</td>
  </tr>
  <tr>
    <td>5</td>
    <td>20px</td>
    <td>28px</td>
  </tr>
  <tr>
    <td>6</td>
    <td>24px</td>
    <td>30px</td>
  </tr>
  <tr>
    <td>7</td>
    <td>28px</td>
    <td>34px</td>
  </tr>
  <tr>
    <td>8</td>
    <td>32px</td>
    <td>38px</td>
  </tr>
  <tr>
    <td>9</td>
    <td>40px</td>
    <td>48px</td>
  </tr>
</table>

## Weight scale

The weight scale is a 4 step scale where each step has it's corresponding font-weight value.

<table>
  <tr>
    <td>Weight</td>
    <td>Default value</td>
  </tr>
  <tr>
    <td>Light</td>
    <td>300</td>
  </tr>
  <tr>
    <td>Regular</td>
    <td>400</td>
  </tr>
  <tr>
    <td>Medium</td>
    <td>500</td>
  </tr>
  <tr>
    <td>Bold</td>
    <td>700</td>
  </tr>
</table>

## Font families

**ljkui ships no fonts and sets no `font-family`.** There is nothing to override and nothing to undo:
`<Text>`, `<Heading>`, `<Strong>`, `<Em>` and `<Quote>` all inherit from whatever ancestor your app styles,
so the components match the rest of your page out of the box. The one exception is `<Code>`, `<Kbd>` and
`<DateField>`, which use the generic `monospace` keyword — your OS's default mono, not a font ljkui picked.

Set your type where you set it for everything else:

```css
body {
  font-family: 'Inter', sans-serif;
}
```

Want a different face for one part of the library? Style the component's class, or wrap it:

```css
.fui-Heading {
  font-family: 'Adobe Text Pro', serif;
}
.fui-Code {
  font-family: 'Fira Code', monospace;
}
```

### Self hosted fonts

You can use self-hosted fonts by downloading font files and adding them to your project.
Then define the named font styles and weights by using `@font-face`.

```css
@font-face {
  font-family: 'Inter';
  src: url('./inter-light.woff2') format('woff2');
  font-weight: 300;
  font-style: normal;
}

@font-face {
  font-family: 'Inter';
  src: url('./inter-regular.woff2') format('woff2');
  font-weight: 400;
  font-style: normal;
}

@font-face {
  font-family: 'Inter';
  src: url('./inter-medium.woff2') format('woff2');
  font-weight: 500;
  font-style: normal;
}

@font-face {
  font-family: 'Inter';
  src: url('./inter-bold.woff2') format('woff2');
  font-weight: 700;
  font-style: normal;
}
```

Then apply it to your page, and ljkui follows:

```css
body {
  font-family: 'Inter', sans-serif;
}
```

### Custom fonts with `next/font`

To load fonts using [next/font](https://nextjs.org/docs/pages/building-your-application/optimizing/fonts),
you can specify a CSS variable name and assign it to the 'inter' font.
Then, you can use `inter.variable` to add the CSS variable to your HTML document.

```tsx
import { Inter } from 'next/font/google';

const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-inter',
});

export default function RootLayout({ children }) {
  return (
    <html lang="en" className={inter.variable}>
      <body>{children}</body>
    </html>
  );
}
```

Then, just use the CSS variable on your page:

```css
body {
  font-family: var(--font-inter), sans-serif;
}
```

---

# Components

## Accordion

Parts: Accordion.Content, Accordion.Item, Accordion.Root, Accordion.Trigger

```tsx
<Accordion.Root type="single" defaultValue={['item-1']} className="w-full max-w-125">
  <div className="flex flex-col gap-4">
    <Accordion.Item value="item-1">
      <Accordion.Trigger>Is it accessible?</Accordion.Trigger>
      <Accordion.Content>Yes. It adheres to the WAI-ARIA design pattern.</Accordion.Content>
    </Accordion.Item>

    <Accordion.Item value="item-2">
      <Accordion.Trigger>Can it open multiple items?</Accordion.Trigger>
      <Accordion.Content>Yes. Set type to multiple to allow several open panels at once.</Accordion.Content>
    </Accordion.Item>

    <Accordion.Item value="item-3">
      <Accordion.Trigger>Can it be animated?</Accordion.Trigger>
      <Accordion.Content>Yes! Panels animate open and closed by default.</Accordion.Content>
    </Accordion.Item>
  </div>
</Accordion.Root>
```

Props:
  - multiple: boolean (default: false) — Whether multiple items can be open at the same time. When omitted, falls back to the deprecated `type` prop (`type="multiple"`).
  - type: "single" | "multiple" — Deprecated Base UI-style API for `multiple`. Kept for backwards compatibility — use `multiple` instead.
  - disabled: boolean (default: false) — Whether the accordion should ignore user interaction.
  - keepMounted: boolean (default: false) — Whether to keep the panel in the DOM while it is closed.
  - orientation: "horizontal" | "vertical" (default: vertical) — The component orientation.

## Alert

Parts: Alert.Action, Alert.Actions, Alert.Description, Alert.Icon, Alert.Root, Alert.Title

```tsx
<Alert.Root color="warning" className="max-w-105">
  <Alert.Icon>
    <Info />
  </Alert.Icon>
  <Alert.Title>Your trial ends in 3 days</Alert.Title>
  <Alert.Description>Upgrade to keep access to analytics and priority support.</Alert.Description>
  <Alert.Actions>
    <Alert.Action>Upgrade</Alert.Action>
    <Alert.Action variant="secondary">Remind me later</Alert.Action>
  </Alert.Actions>
</Alert.Root>
```

Props:
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — The color of the alert, applied to its icon, title and description. Inherits the theme accent color when not set.

## AlertDialog

Parts: AlertDialog.Action, AlertDialog.Cancel, AlertDialog.Close, AlertDialog.Content, AlertDialog.Description, AlertDialog.Root, AlertDialog.Title, AlertDialog.Trigger

```tsx
<AlertDialog.Root>
  <AlertDialog.Trigger>
    <Button variant="classic" color="red">
      Revoke access
    </Button>
  </AlertDialog.Trigger>

  <AlertDialog.Content className="max-w-[450px]">
    <AlertDialog.Title>Revoke access</AlertDialog.Title>
    <AlertDialog.Description>
      Are you sure? This application will no longer be accessible and any existing sessions will be expired.
    </AlertDialog.Description>

    <div className="mt-4 flex justify-end gap-3">
      <AlertDialog.Cancel>
        <Button variant="soft" color="gray">
          Cancel
        </Button>
      </AlertDialog.Cancel>
      <AlertDialog.Action>
        <Button variant="classic" color="red">
          Revoke access
        </Button>
      </AlertDialog.Action>
    </div>
  </AlertDialog.Content>
</AlertDialog.Root>
```

Props:
  - size: "1" | "2" | "3" | "4" (default: 3)

## AspectRatio

```tsx
<Card style={{ width: 300 }}>
  <AspectRatio ratio={16 / 9}>
    <div
      style={{
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
        background: 'var(--gray-alpha-200)',
      }}
    >
      <Typography.Text size="2" color="gray">
        16 / 9
      </Typography.Text>
    </div>
  </AspectRatio>
</Card>
```

## Autocomplete

Parts: Autocomplete.Clear, Autocomplete.Content, Autocomplete.Empty, Autocomplete.Group, Autocomplete.GroupLabel, Autocomplete.Icon, Autocomplete.Input, Autocomplete.Item, Autocomplete.List, Autocomplete.Root, Autocomplete.Row, Autocomplete.Separator, Autocomplete.Status, Autocomplete.Trigger

```tsx
<div className="w-75">
  <Autocomplete.Root items={tags}>
    <Input.Root>
      <Autocomplete.Input render={<Input.Control placeholder="Search tags..." />} />
    </Input.Root>
    <Autocomplete.Content>
      <ScrollArea type="auto">
        <Autocomplete.Empty>No tags found.</Autocomplete.Empty>
        <Autocomplete.List>
          {(tag) => (
            <Autocomplete.Item key={tag as string} value={tag}>
              {tag as string}
            </Autocomplete.Item>
          )}
        </Autocomplete.List>
      </ScrollArea>
    </Autocomplete.Content>
  </Autocomplete.Root>
</div>
```

Props:
  - size: "1" | "2" | "3" (default: 2) — The size of the popup and its items.
  - variant: "solid" | "translucent" (default: translucent) — The visual style of the popup background.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — The accent color used for highlighted items. Inherits the theme accent color when not set.

## Avatar

```tsx
<div className="flex flex-wrap items-center gap-3">
  <Avatar
    size="4"
    src="https://images.unsplash.com/photo-1502823403499-6ccfcf4fb453?&w=256&h=256&q=70&crop=focalpoint&fp-x=0.5&fp-y=0.3&fp-z=1&fit=crop"
    fallback="A"
  />
  <Avatar size="4" fallback="LK" color="indigo" />
  <Avatar size="4" shape="square" fallback="SQ" color="teal" />
  <Avatar size="2" fallback="S" color="orange" />
  <Avatar size="6" fallback="L" color="rose" highContrast />
</div>
```

Props:
  - size: "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" (default: 3) — The size of the avatar.
  - shape: "circle" | "square" (default: circle) — The shape of the avatar.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — The color of the fallback background. Inherits the theme accent color when not set.
  - highContrast: boolean — Increases color contrast of the fallback for better legibility.
  - fallback: ReactNode — Content shown while the image is loading or when it fails to load. A string is converted to initials (e.g. "Jane Doe" becomes "JD").

## AvatarGroup

Parts: AvatarGroup.Avatar, AvatarGroup.Root

```tsx
<AvatarGroup.Root size="3">
  <AvatarGroup.Avatar
    src="https://images.unsplash.com/photo-1502823403499-6ccfcf4fb453?&w=256&h=256&q=70&crop=focalpoint&fp-x=0.5&fp-y=0.3&fp-z=1&fit=crop"
    fallback="Ada Lovelace"
  />
  <AvatarGroup.Avatar fallback="GH" color="indigo" />
  <AvatarGroup.Avatar fallback="AT" color="teal" />
  <AvatarGroup.Avatar fallback="+3" color="gray" />
</AvatarGroup.Root>
```

Props:
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" (default: gray) — The color applied to the group's avatars.
  - size: "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" (default: 3) — The size of the group's avatars.
  - shape: "circle" | "square" (default: circle) — The shape of the group's avatars.

## AvatarStack

Parts: AvatarStack.Avatar, AvatarStack.Root

```tsx
<AvatarStack.Root size="3">
  <AvatarStack.Avatar
    src="https://images.unsplash.com/photo-1502823403499-6ccfcf4fb453?&w=256&h=256&q=70&crop=focalpoint&fp-x=0.5&fp-y=0.3&fp-z=1&fit=crop"
    fallback="Ada Lovelace"
  />
  <AvatarStack.Avatar fallback="GH" color="indigo" />
  <AvatarStack.Avatar fallback="AT" color="teal" />
  <AvatarStack.Avatar fallback="ML" color="orange" />
</AvatarStack.Root>
```

Props:
  - size: "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" (default: 3) — The size of the stack's avatars.

## Badge

```tsx
<div className="flex flex-wrap items-center gap-2">
  <Badge variant="solid" color="blue">
    Solid
  </Badge>
  <Badge variant="soft" color="green">
    Soft
  </Badge>
  <Badge variant="surface" color="orange">
    Surface
  </Badge>
  <Badge variant="outline" color="rose">
    Outline
  </Badge>
  <Badge size="2" color="purple">
    Size 2
  </Badge>
</div>
```

Props:
  - size: "1" | "2" (default: 1) — The size of the badge.
  - variant: "solid" | "soft" | "surface" | "outline" (default: soft) — The visual style of the badge.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — The color of the badge. Inherits the theme accent color when not set.
  - highContrast: boolean — Increases color contrast with the background for better legibility.

## Bleed

```tsx
<Card size="2" style={{ maxWidth: 280 }}>
  <Bleed side="x" size="3">
    <div style={{ height: 96, background: 'var(--accent-alpha-200)' }} />
  </Bleed>
  <Typography.Text size="2">
    The tinted area bleeds out to the card&apos;s edges; this text keeps the normal padding.
  </Typography.Text>
</Card>
```

Props:
  - side: "all" | "x" | "y" | "top" | "bottom" | "left" | "right" (default: all) — Which side(s) the content bleeds out of the parent's padding.
  - size: Responsive<"1" | "2" | "3" | "4"> (default: 3) — The amount of negative margin: 1=--space-2, 2=--space-3, 3=--space-4, 4=--space-5.

## Breadcrumb

Parts: Breadcrumb.Dropdown, Breadcrumb.DropdownItem, Breadcrumb.Item, Breadcrumb.Root

```tsx
<Breadcrumb.Root>
  <Breadcrumb.Item render={<a href="#" />} nativeButton={false}>
    Home
  </Breadcrumb.Item>
  <Breadcrumb.Dropdown>
    <Breadcrumb.DropdownItem render={<a href="#">Products</a>} />
    <Breadcrumb.DropdownItem render={<a href="#">Categories</a>} />
  </Breadcrumb.Dropdown>
  <Breadcrumb.Item render={<a href="#" />} nativeButton={false}>
    Bots
  </Breadcrumb.Item>
  <Breadcrumb.Item>Sneaker Bot</Breadcrumb.Item>
</Breadcrumb.Root>
```

Props:
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" (default: gray) — The color of the breadcrumb items and separators. Passed down to each item unless it sets its own.

## Button

```tsx
<div className="flex flex-wrap items-center gap-3">
  <Button variant="classic">Classic</Button>
  <Button variant="solid">Solid</Button>
  <Button variant="soft">Soft</Button>
  <Button variant="surface">Surface</Button>
  <Button variant="ghost">Ghost</Button>
  <Button variant="solid" color="red">
    Red
  </Button>
  <Button variant="solid" size="4">
    Large
  </Button>
  <Button disabled>Disabled</Button>
</div>
```

Props:
  - size: "1" | "2" | "3" | "4" (default: 2) — The size of the button.
  - variant: "classic" | "solid" | "soft" | "surface" | "ghost" (default: surface) — The visual style of the button.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — The color of the button. Inherits the theme accent color when not set (gray for the `surface` variant).
  - highContrast: boolean — Increases color contrast with the background for better legibility.

## ButtonGroup

Parts: ButtonGroup.Root, ButtonGroup.Separator, ButtonGroup.Text

```tsx
<ButtonGroup.Root>
  <ButtonGroup.Text>https://</ButtonGroup.Text>
  <Button variant="surface">example.com</Button>
  <Button variant="solid">Copy</Button>
</ButtonGroup.Root>
```

Props:
  - orientation: "horizontal" | "vertical" (default: horizontal) — The direction the buttons are stacked in.

## Calendar

Parts: Calendar.Range, Calendar.Root

```tsx
return <Calendar.Root aria-label="Appointment date" defaultValue={parseDate('2020-02-03')} />;
```

Props:
  - isDisabled: boolean (default: false) — Whether the calendar is disabled.
  - isReadOnly: boolean (default: false) — Whether the calendar value is immutable.
  - autoFocus: boolean (default: false) — Whether to automatically focus the calendar when it mounts.
  - isInvalid: boolean — Whether the current selection is invalid according to application logic.
  - pageBehavior: "visible" | "single" (default: visible) — Controls the behavior of paging. Pagination either advances the visible page by `visibleDuration` (`'visible'`) or by one unit of it (`'single'`).
  - firstDayOfWeek: "sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat" — The day that starts the week.

## Card

```tsx
<Card size="2" variant="surface" className="max-w-80">
  <div className="flex items-center gap-3">
    <Avatar size="3" fallback="AF" color="blue" />
    <div>
      <Typography.Text render={<div />} size="2" weight="bold">
        ljkui
      </Typography.Text>
      <Typography.Text render={<div />} size="2" color="gray">
        A design system for building products
      </Typography.Text>
    </div>
  </div>
</Card>
```

Props:
  - size: "1" | "2" | "3" | "4" | "5" (default: 1) — The size of the card: controls its padding and border radius.
  - variant: "surface" | "outline" | "ghost" | "soft" (default: surface) — The visual style of the card.

## Carousel

Parts: Carousel.Item, Carousel.Next, Carousel.Previous, Carousel.Root, Carousel.ScrollMarker, Carousel.ScrollMarkerGroup, Carousel.Viewport

```tsx
<Carousel.Root defaultValue={0}>
  <Carousel.Viewport
    aria-label="Gallery"
    className="flex gap-3 overflow-x-auto [overscroll-behavior-x:contain] [scroll-snap-type:x_mandatory] [scrollbar-width:none]"
  >
    {items.map((label) => (
      <Carousel.Item key={label} className="shrink-0 [scroll-snap-align:start]">
        <Card size="2" className="grid h-25 w-45 place-items-center">
          <Typography.Text size="3" weight="bold">
            {label}
          </Typography.Text>
        </Card>
      </Carousel.Item>
    ))}
  </Carousel.Viewport>

  <div className="mt-3 flex items-center justify-between">
    <div className="flex gap-2">
      <Carousel.Previous aria-label="Previous" render={<IconButton variant="soft" size="1" color="gray" />}>
        <ChevronLeft />
      </Carousel.Previous>
      <Carousel.Next aria-label="Next" render={<IconButton variant="soft" size="1" color="gray" />}>
        <ChevronRight />
      </Carousel.Next>
    </div>

    <Carousel.ScrollMarkerGroup aria-label="Go to item" className="flex gap-1">
      {items.map((label, i) => (
        <Carousel.ScrollMarker
          key={label}
          index={i}
          render={(props, state) => (
            <button
              {...props}
              className={`size-2 cursor-pointer rounded-full border-[1.5px] border-gray-600 p-0 ${
                state.active ? 'bg-gray-950' : 'bg-transparent'
              }`}
            />
          )}
        />
      ))}
    </Carousel.ScrollMarkerGroup>
  </div>
</Carousel.Root>
```

Props:
  - defaultValue: string | number (default: 0) — The initial active item index (uncontrolled mode).
  - value: string | number — The active item index (controlled mode). When provided, the component is fully controlled — external changes scroll the viewport to the corresponding item.
  - loop: boolean (default: false) — When true, navigation wraps around at boundaries: previous/next buttons jump to the other end instead of disabling, and marker arrow keys wrap instead of clamping.
  - orientation: "horizontal" | "vertical" (default: horizontal) — The scroll orientation of the gallery.
  - scrollBehavior: "smooth" | "instant" (default: smooth) — Controls whether programmatic scrolls animate smoothly or jump instantly. Reduced motion always forces `'instant'` regardless of this value.

## Chart

```tsx
<div className="w-80">
  <Chart
    data={[
      { label: 'Completed', value: 60, color: 'green' },
      { label: 'In progress', value: 25, color: 'blue' },
      { label: 'Failed', value: 15, color: 'red' },
    ]}
  />
</div>
```

Props:
  - data: ChartData[] — Segments to render, in order. Each segment's width is its `value` as a percentage of the sum of all segment values. Every segment has a `label`, a numeric `value`, and a theme accent `color`.

## Checkbox

```tsx
<div className="flex flex-col gap-2">
  <Typography.Text render={<label />} size="2" className="flex items-center gap-2">
    <Checkbox defaultChecked />
    Agree to terms and conditions
  </Typography.Text>
  <Typography.Text render={<label />} size="2" className="flex items-center gap-2">
    <Checkbox color="green" defaultChecked />
    Subscribe to the newsletter
  </Typography.Text>
  <Typography.Text render={<label />} size="2" color="gray" className="flex items-center gap-2">
    <Checkbox disabled />
    Disabled option
  </Typography.Text>
</div>
```

Props:
  - size: "1" | "2" | "3" (default: 2) — The size of the checkbox.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — The color of the checkbox when checked. Inherits the theme accent color when not set.
  - highContrast: boolean — Increases color contrast with the background for better legibility.

## CircularProgress

```tsx
<div className="flex items-center gap-4">
  <CircularProgress value={25} size="3" aria-label="25% complete" />
  <CircularProgress value={60} size="5" aria-label="60% complete" />
  <CircularProgress value={85} size="7" color="green" aria-label="85% complete" />
  <CircularProgress value={100} size="7" color="green" aria-label="Complete" />
</div>
```

Props:
  - size: "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" (default: 3) — The diameter of the progress ring.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — The color of the progress indicator. Inherits the theme accent color when not set.
  - highContrast: boolean — Increases color contrast with the background for better legibility.

## Collapsible

Parts: Collapsible.Content, Collapsible.Root, Collapsible.Trigger

```tsx
<Collapsible.Root>
  <Collapsible.Trigger render={<Button variant="ghost" />}>Advanced options</Collapsible.Trigger>
  <Collapsible.Content>
    <Typography.Text size="2" color="gray">
      Requests are retried three times before the job is marked as failed.
    </Typography.Text>
  </Collapsible.Content>
</Collapsible.Root>
```

Props:
  - open: boolean — Whether the panel is open (controlled). To render an uncontrolled collapsible, use `defaultOpen`.
  - defaultOpen: boolean (default: false) — Whether the panel is initially open (uncontrolled). To render a controlled collapsible, use `open`.
  - disabled: boolean (default: false) — Whether the collapsible should ignore user interaction.

## Combobox

Parts: Combobox.Chip, Combobox.Chips, Combobox.ChipsInput, Combobox.Clear, Combobox.Collection, Combobox.Content, Combobox.Empty, Combobox.Group, Combobox.GroupLabel, Combobox.Icon, Combobox.Input, Combobox.InputRoot, Combobox.InputSlot, Combobox.Item, Combobox.ItemIndicator, Combobox.List, Combobox.Root, Combobox.Separator, Combobox.Status, Combobox.Trigger, Combobox.Value

```tsx
<div className="w-75">
  <Combobox.Root items={fruits} defaultValue="Apple">
    <Combobox.InputRoot showClear>
      <Combobox.Input placeholder="Choose a fruit..." />
    </Combobox.InputRoot>
    <Combobox.Content>
      <ScrollArea type="auto" className="max-h-75">
        <Combobox.Empty>No fruits found.</Combobox.Empty>
        <Combobox.List>
          {(item) => (
            <Combobox.Item key={item} value={item}>
              {item}
            </Combobox.Item>
          )}
        </Combobox.List>
      </ScrollArea>
    </Combobox.Content>
  </Combobox.Root>
</div>
```

Props:
  - variant: "solid" | "soft" (default: soft) — The visual style of the popup background.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — The accent color used for highlighted items. Inherits the theme accent color when not set.
  - highContrast: boolean — Increases color contrast with the background for better legibility.
  - size: "1" | "2" | "3" | "4" (default: 2) — The size shared with the combobox parts (`Input`, `Chips`, `Content`) via context.

## Command

Parts: Command.Dialog, Command.Empty, Command.Group, Command.Input, Command.Item, Command.List, Command.Root, Command.Separator, Command.Shortcut

```tsx
<Command.Root style={{ width: 380, boxShadow: '0 0 0 1px var(--gray-alpha-300) inset' }}>
  <Command.Input placeholder="Type a command or search…" />
  <Command.List>
    <Command.Empty>No results found.</Command.Empty>
    <Command.Group heading="Actions">
      <Command.Item onSelect={() => console.log('invoice')}>
        Create invoice
        <Command.Shortcut>⌘N</Command.Shortcut>
      </Command.Item>
      <Command.Item onSelect={() => console.log('customer')}>
        Add customer
        <Command.Shortcut>⌘⇧C</Command.Shortcut>
      </Command.Item>
    </Command.Group>
    <Command.Separator />
    <Command.Group heading="Navigation">
      <Command.Item onSelect={() => console.log('settings')}>Go to settings</Command.Item>
    </Command.Group>
  </Command.List>
</Command.Root>
```

Props:
  - heading: ReactNode — The label shown above the group.
  - value: string — The search text, when controlling the filter yourself. Pair with `onValueChange`.
  - disabled: boolean (default: false) — Whether the item can be selected.

## Container

```tsx
<div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--space-4)' }}>
  {(['left', 'center', 'right'] as const).map((align) => (
    <Container key={align} size="1" align={align}>
      <Card variant="soft">
        <Typography.Text size="2">Aligned {align}</Typography.Text>
      </Card>
    </Container>
  ))}
</div>
```

Props:
  - size: Responsive<"1" | "2" | "3" | "4"> (default: 4) — The maximum width of the container: 1=448px, 2=688px, 3=880px, 4=1136px.
  - align: "left" | "center" | "right" (default: center) — How the container is aligned within its parent when narrower than the available space.

## ContextMenu

Parts: ContextMenu.CheckboxItem, ContextMenu.Content, ContextMenu.Group, ContextMenu.GroupLabel, ContextMenu.Item, ContextMenu.RadioGroup, ContextMenu.RadioItem, ContextMenu.Root, ContextMenu.Separator, ContextMenu.Sub, ContextMenu.SubContent, ContextMenu.SubTrigger, ContextMenu.Trigger

```tsx
<ContextMenu.Root>
  <ContextMenu.Trigger>
    <div className="flex h-[150px] w-50 items-center justify-center rounded-md bg-gray-alpha-50">
      Right-click here
    </div>
  </ContextMenu.Trigger>
  <ContextMenu.Content>
    <ContextMenu.Item shortcut="⌘ E">Edit</ContextMenu.Item>
    <ContextMenu.Item shortcut="⌘ D">Duplicate</ContextMenu.Item>
    <ContextMenu.Separator />
    <ContextMenu.Item shortcut="⌘ N">Archive</ContextMenu.Item>
    <ContextMenu.Separator />
    <ContextMenu.Item shortcut="⌘ ⌫" color="danger">
      Delete
    </ContextMenu.Item>
  </ContextMenu.Content>
</ContextMenu.Root>
```

Props:
  - shortcut: string
  - size: "1" | "2" | "3" (default: 2)
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone"
  - variant: "solid" | "translucent" (default: translucent)

## CreditCard

Parts: CreditCard.Back, CreditCard.BackContent, CreditCard.Brand, CreditCard.BrandLogo, CreditCard.CVVField, CreditCard.Content, CreditCard.Errors, CreditCard.ExpiryField, CreditCard.Field, CreditCard.FieldError, CreditCard.FieldGroup, CreditCard.FieldLabel, CreditCard.Fieldset, CreditCard.Front, CreditCard.FrontFooter, CreditCard.FrontHeader, CreditCard.Input, CreditCard.LastFour, CreditCard.Logo, CreditCard.MagStripe, CreditCard.NumberField, CreditCard.Root, CreditCard.Title, CreditCard.Trigger

```tsx
<CreditCard.Root defaultFace="front">
  <CreditCard.Content>
    <CreditCard.Front>
      <CreditCard.FrontHeader>
        <CreditCard.Logo>
          <span className="text-[20px] leading-none font-bold">ljkui</span>
        </CreditCard.Logo>
        <CreditCard.Brand>
          <CreditCard.BrandLogo brand="visa" />
        </CreditCard.Brand>
      </CreditCard.FrontHeader>
      <CreditCard.FrontFooter>
        <CreditCard.Title>Claude credits</CreditCard.Title>
        <CreditCard.LastFour>•••• 0991</CreditCard.LastFour>
      </CreditCard.FrontFooter>
    </CreditCard.Front>

    <CreditCard.Back>
      <CreditCard.MagStripe />
      <CreditCard.BackContent>
        <CreditCard.Fieldset aria-label="Card details">
          <CreditCard.Field>
            <CreditCard.FieldLabel>Card number</CreditCard.FieldLabel>
            <CreditCard.NumberField readOnly defaultValue="4242 4242 4242 0991" />
          </CreditCard.Field>
          <CreditCard.FieldGroup>
            <CreditCard.Field>
              <CreditCard.FieldLabel>Exp</CreditCard.FieldLabel>
              <CreditCard.ExpiryField readOnly defaultValue="11/27" />
            </CreditCard.Field>
            <CreditCard.Field>
              <CreditCard.FieldLabel>CVV</CreditCard.FieldLabel>
              <CreditCard.CVVField readOnly defaultValue="817" />
            </CreditCard.Field>
          </CreditCard.FieldGroup>
        </CreditCard.Fieldset>
      </CreditCard.BackContent>
    </CreditCard.Back>
  </CreditCard.Content>

  <div className="mt-4 flex justify-center">
    <CreditCard.Trigger render={<Button variant="surface" size="2" />}>Flip card</CreditCard.Trigger>
  </div>
</CreditCard.Root>
```

Props:
  - face: "front" | "back" — The active face in controlled mode. Pair with `onFaceChange` to keep state in sync.
  - defaultFace: "front" | "back" (default: front) — The initial face in uncontrolled mode.

## DataTable

Parts: DataTable.Item, DataTable.Label, DataTable.Root, DataTable.Value

```tsx
<DataTable.Root>
  <DataTable.Item align="center">
    <DataTable.Label>Status</DataTable.Label>
    <DataTable.Value>
      <Badge color="success">Active</Badge>
    </DataTable.Value>
  </DataTable.Item>
  <DataTable.Item>
    <DataTable.Label>ID</DataTable.Label>
    <DataTable.Value>
      <Typography.Code variant="ghost">usr_4f9a2c</Typography.Code>
    </DataTable.Value>
  </DataTable.Item>
  <DataTable.Item>
    <DataTable.Label>Name</DataTable.Label>
    <DataTable.Value>Ada Lovelace</DataTable.Value>
  </DataTable.Item>
  <DataTable.Item>
    <DataTable.Label>Email</DataTable.Label>
    <DataTable.Value>
      <Link href="mailto:ada@example.com">ada@example.com</Link>
    </DataTable.Value>
  </DataTable.Item>
</DataTable.Root>
```

Props:
  - align: "start" | "center" | "end" | "baseline" | "stretch" — How the label and value are vertically aligned within the row.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — The color of the label text. Inherits the low-contrast gray label styling when not set.
  - highContrast: boolean — Increases color contrast with the background for better legibility.
  - orientation: "horizontal" | "vertical" (default: horizontal) — Whether labels and values are laid out side by side or stacked.
  - size: "1" | "2" | "3" (default: 2) — The size of the list text and spacing.
  - trim: "normal" | "start" | "end" | "both" — Trims the leading (whitespace above/below the text box) from the start, end, or both sides.

## DateField

```tsx
<div className="w-75">
  <DateField aria-label="Birth date" defaultValue={parseDate('2020-02-03')} />
</div>
```

Props:
  - size: "1" | "2" | "3" | "4" (default: 2) — The size of the field.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — The accent color of the field, used for focus and selection styling.

## DatePicker

```tsx
<DatePicker
  aria-label="Appointment date"
  defaultValue={parseDate('2020-02-03')}
  minValue={parseDate('2020-01-01')}
  maxValue={parseDate('2020-12-31')}
/>
```

Props:
  - size: "1" | "2" | "3" | "4" (default: 2) — The size of the field.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — The accent color of the field, used for focus and selection styling.

## DateRangePicker

```tsx
<DateRangePicker
  aria-label="Trip dates"
  defaultValue={{
    start: parseDate('2020-02-03'),
    end: parseDate('2020-02-08'),
  }}
/>
```

Props:
  - size: "1" | "2" | "3" | "4" (default: 2) — The size of the field.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — The accent color of the field, used for focus and selection styling.

## Dialog

Parts: Dialog.Close, Dialog.Content, Dialog.Description, Dialog.Root, Dialog.Title, Dialog.Trigger

```tsx
<Dialog.Root>
  <Dialog.Trigger nativeButton>
    <Button>Edit profile</Button>
  </Dialog.Trigger>

  <Dialog.Content className="max-w-[450px]">
    <Dialog.Title>Edit profile</Dialog.Title>
    <Dialog.Description>Make changes to your profile.</Dialog.Description>

    <label>
      <Typography.Text render={<div />} size="2" weight="bold" className="mb-1">
        Name
      </Typography.Text>
      <Input.Root>
        <Input.Control defaultValue="Freja Johnsen" placeholder="Enter your full name" />
      </Input.Root>
    </label>

    <div className="mt-4 flex justify-end gap-3">
      <Dialog.Close>
        <Button variant="soft" color="gray">
          Cancel
        </Button>
      </Dialog.Close>
      <Dialog.Close>
        <Button>Save</Button>
      </Dialog.Close>
    </div>
  </Dialog.Content>
</Dialog.Root>
```

Props:
  - size: "1" | "2" | "3" | "4" (default: 3) — The size of the dialog: controls its max width, padding and radius, and scales the default `Title` and `Description` sizes.

## Drawer

Parts: Drawer.Body, Drawer.Close, Drawer.Content, Drawer.Header, Drawer.Root, Drawer.StickyFooter, Drawer.Title, Drawer.Trigger

```tsx
<Drawer.Root>
  <Drawer.Trigger>
    <Button>Edit profile</Button>
  </Drawer.Trigger>

  <Drawer.Content>
    <Drawer.Header>
      <Drawer.Title>Edit profile</Drawer.Title>
    </Drawer.Header>
    <Drawer.Body>
      <Typography.Text render={<p />} size="2" className="mb-4">
        Make changes to your profile, then save.
      </Typography.Text>

      <label>
        <Typography.Text render={<div />} size="2" weight="bold" className="mb-1">
          Name
        </Typography.Text>
        <Input.Control defaultValue="Freja Johnsen" placeholder="Enter your full name" />
      </label>

      <div className="mt-4 flex justify-end gap-3">
        <Drawer.Close>
          <Button variant="soft" color="gray">
            Cancel
          </Button>
        </Drawer.Close>
        <Drawer.Close>
          <Button>Save</Button>
        </Drawer.Close>
      </div>
    </Drawer.Body>
  </Drawer.Content>
</Drawer.Root>
```

Props:
  - open: boolean — Whether the drawer is open (controlled). Pair with `onOpenChange`.
  - defaultOpen: boolean (default: false) — Whether the drawer is initially open (uncontrolled). To render a controlled drawer, use `open` instead.
  - disablePointerDismissal: boolean (default: false) — Whether to prevent the drawer from closing on outside presses.

## DropdownMenu

Parts: DropdownMenu.CheckboxItem, DropdownMenu.Content, DropdownMenu.Group, DropdownMenu.GroupLabel, DropdownMenu.Item, DropdownMenu.RadioGroup, DropdownMenu.RadioItem, DropdownMenu.Root, DropdownMenu.Separator, DropdownMenu.Sub, DropdownMenu.SubContent, DropdownMenu.SubTrigger, DropdownMenu.Trigger

```tsx
const [showHiddenFiles, setShowHiddenFiles] = React.useState(true);

return (
  <DropdownMenu.Root>
    <DropdownMenu.Trigger>
      <Button variant="soft">Options</Button>
    </DropdownMenu.Trigger>
    <DropdownMenu.Content>
      <DropdownMenu.Item shortcut="⌘ E">Edit</DropdownMenu.Item>
      <DropdownMenu.Item shortcut="⌘ D">Duplicate</DropdownMenu.Item>
      <DropdownMenu.Separator />
      <DropdownMenu.Sub>
        <DropdownMenu.SubTrigger>More</DropdownMenu.SubTrigger>
        <DropdownMenu.SubContent>
          <DropdownMenu.Item>Move to project…</DropdownMenu.Item>
          <DropdownMenu.Item>Move to folder…</DropdownMenu.Item>
        </DropdownMenu.SubContent>
      </DropdownMenu.Sub>
      <DropdownMenu.Separator />
      <DropdownMenu.CheckboxItem checked={showHiddenFiles} onCheckedChange={setShowHiddenFiles}>
        Show hidden files
      </DropdownMenu.CheckboxItem>
      <DropdownMenu.Separator />
      <DropdownMenu.Item shortcut="⌘ ⌫" color="danger">
        Delete
      </DropdownMenu.Item>
    </DropdownMenu.Content>
  </DropdownMenu.Root>
);
```

Props:
  - shortcut: string
  - size: "1" | "2" | "3" (default: 2)
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone"
  - variant: "solid" | "translucent" (default: translucent)

## Empty

Parts: Empty.Actions, Empty.Description, Empty.Header, Empty.Media, Empty.Root, Empty.Title

```tsx
<Empty.Root>
  <Empty.Header>
    <Empty.Media>
      <Inbox />
    </Empty.Media>
    <Empty.Title>No messages yet</Empty.Title>
    <Empty.Description>When someone sends you a message, it will show up here.</Empty.Description>
  </Empty.Header>
  <Empty.Actions>
    <Button variant="classic">Compose message</Button>
  </Empty.Actions>
</Empty.Root>
```

## Field

Parts: Field.Control, Field.Description, Field.Error, Field.Item, Field.Label, Field.Root, Field.Validity

```tsx
<div className="w-75">
  <Field.Root name="username">
    <Field.Label>Username</Field.Label>
    <Field.Description>Must be at least 3 characters</Field.Description>
    <Input.Root>
      <Input.Control placeholder="johndoe" required minLength={3} />
    </Input.Root>
    <Field.Error match="valueMissing">Username is required</Field.Error>
    <Field.Error match="tooShort">Username must be at least 3 characters</Field.Error>
  </Field.Root>
</div>
```

Props:
  - name: string — Identifies the field when a form is submitted. Takes precedence over the `name` prop on `Field.Control`.
  - disabled: boolean (default: false) — Whether the field should ignore user interaction. Takes precedence over the `disabled` prop on `Field.Control`.
  - invalid: boolean — Whether the field is invalid. Useful when the field state is controlled by an external library.

## Fieldset

Parts: Fieldset.Legend, Fieldset.Root

```tsx
<Fieldset.Root className="w-80">
  <Fieldset.Legend>Billing Details</Fieldset.Legend>

  <Field.Root name="company">
    <Field.Label>Company</Field.Label>
    <Input.Root>
      <Input.Control placeholder="Acme Inc." />
    </Input.Root>
  </Field.Root>

  <Field.Root name="taxId">
    <Field.Label>Tax ID</Field.Label>
    <Input.Root>
      <Input.Control placeholder="XX-XXXXXXX" />
    </Input.Root>
    <Field.Description>Your company's tax identification number</Field.Description>
  </Field.Root>
</Fieldset.Root>
```

Props:
  - variant: "legend" | "label" (default: legend) — The visual variant of the legend. `'legend'` is a larger section heading (size 3, bold); `'label'` matches a field label (size 2, medium).

## FilterChip

```tsx
<div className="flex flex-wrap gap-2">
  <FilterChip defaultChecked>In stock</FilterChip>
  <FilterChip>On sale</FilterChip>
  <FilterChip defaultChecked color="orange">
    Free shipping
  </FilterChip>
  <FilterChip disabled>Disabled</FilterChip>
</div>
```

Props:
  - size: "1" | "2" | "3" (default: 2) — The size of the chip.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — The color of the chip when checked. Inherits the theme accent color when not set.

## Form

```tsx
const [submitted, setSubmitted] = React.useState(false);

return (
  <Form
    className="w-75"
    onSubmit={(event) => {
      event.preventDefault();
      setSubmitted(true);
    }}
  >
    <Field.Root name="email">
      <Field.Label>Email</Field.Label>
      <Input.Root>
        <Input.Control type="email" placeholder="you@example.com" required />
      </Input.Root>
      <Field.Error match="valueMissing">Email is required</Field.Error>
      <Field.Error match="typeMismatch">Please enter a valid email</Field.Error>
    </Field.Root>

    <Button type="submit" variant="solid" className="w-full">
      {submitted ? 'Subscribed!' : 'Subscribe'}
    </Button>
  </Form>
);
```

Props:
  - validationMode: "onSubmit" | "onBlur" | "onChange" (default: onSubmit) — Determines when the form should be validated: - `'onSubmit'`: validate on submit, afterwards fields re-validate on change. - `'onBlur'`: validate a field when it loses focus. - `'onChange'`: validate the field on every change to its value. The `validationMode` prop on `<Field.Root>` takes precedence over this.

## Grid

Parts: Grid.Item, Grid.Root, Grid.Row

```tsx
<Grid.Root horizontalSpacing={8} verticalSpacing={8}>
  <Grid.Root.Row>
    <div style={cell}>1</div>
    <div style={cell}>2</div>
    <div style={cell}>3</div>
  </Grid.Root.Row>
  <Grid.Root.Row>
    <div style={cell}>4</div>
    <div style={cell}>5</div>
  </Grid.Root.Row>
  <Typography.Text size="2" color="gray">
    Spans every column
  </Typography.Text>
</Grid.Root>
```

Props:
  - alignment: "center" | "leading" | "trailing" | "top" | "bottom" | "topLeading" | "topTrailing" | "bottomLeading" | "bottomTrailing" | "centerFirstTextBaseline" | "centerLastTextBaseline" | "leadingFirstTextBaseline" | "leadingLastTextBaseline" | "trailingFirstTextBaseline" | "trailingLastTextBaseline" (default: center) — How cells are aligned within their grid area, following SwiftUI-style alignment names.

## HStack

```tsx
<HStack spacing={12} alignment="center">
  <div style={box(40)}>1</div>
  <div style={box(80)}>2</div>
  <div style={box(56)}>3</div>
</HStack>
```

Props:
  - alignment: "top" | "center" | "bottom" | "firstTextBaseline" | "lastTextBaseline" (default: center) — How children are aligned vertically within the row.

## HoverCard

Parts: HoverCard.Content, HoverCard.Root, HoverCard.Trigger

```tsx
<Typography.Text>
  Follow{' '}
  <HoverCard.Root>
    <HoverCard.Trigger>
      <Link href="https://github.com/aussieljk/ljkui" target="_blank">
        ljkui
      </Link>
    </HoverCard.Trigger>
    <HoverCard.Content>
      <div className="flex gap-4">
        <Avatar size="3" fallback="AF" />
        <div>
          <Typography.Heading size="3">ljkui</Typography.Heading>
          <Typography.Text render={<div />} size="2" color="gray">
            aussieljk
          </Typography.Text>
          <Typography.Text render={<div />} size="2" className="mt-3 max-w-75">
            React components library built on top of Base UI primitives.
          </Typography.Text>
        </div>
      </div>
    </HoverCard.Content>
  </HoverCard.Root>{' '}
  for updates.
</Typography.Text>
```

Props:
  - size: "1" | "2" | "3" (default: 2) — The size of the card: controls its padding and border radius.
  - variant: "solid" | "translucent" (default: translucent) — The visual style of the card background.

## IconButton

```tsx
<div className="flex flex-wrap items-center gap-3">
  <IconButton variant="classic" aria-label="Search">
    <Search />
  </IconButton>
  <IconButton variant="solid" aria-label="Add">
    <Plus />
  </IconButton>
  <IconButton variant="soft" aria-label="Favorite">
    <Heart />
  </IconButton>
  <IconButton variant="surface" aria-label="Settings">
    <Settings />
  </IconButton>
  <IconButton variant="ghost" aria-label="Notifications">
    <Bell />
  </IconButton>
  <IconButton variant="solid" color="red" aria-label="Delete">
    <Trash />
  </IconButton>
  <IconButton variant="soft" loading aria-label="Loading">
    <Star />
  </IconButton>
</div>
```

Props:
  - size: "1" | "2" | "3" | "4" (default: 2) — The size of the button.
  - variant: "classic" | "solid" | "soft" | "surface" | "ghost" (default: surface) — The visual style of the button.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — The color of the button. Inherits the theme accent color when not set (gray for the `surface` variant).
  - highContrast: boolean — Increases color contrast with the background for better legibility.

## Input

Parts: Input.Control, Input.Root, Input.Slot

```tsx
<div className="flex w-70 flex-col gap-3">
  <Input.Root>
    <Input.Slot>
      <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
        <circle cx="11" cy="11" r="7" />
        <path d="m20 20-3.5-3.5" />
      </svg>
    </Input.Slot>
    <Input.Control placeholder="Search the docs…" />
  </Input.Root>

  <Input.Root variant="soft" size="3">
    <Input.Control placeholder="Soft variant, size 3" />
  </Input.Root>
</div>
```

Props:
  - size: "1" | "2" | "3" | "4" (default: 2) — Controls the height, text size and padding of the field.
  - variant: "surface" | "soft" (default: surface) — Controls the visual style of the field.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" (default: gray) — Overrides the accent color used for the field's background tint and focus ring.

## InputGroup

Parts: InputGroup.Addon, InputGroup.Button, InputGroup.Input, InputGroup.Root, InputGroup.Text, InputGroup.Textarea

```tsx
<InputGroup.Root style={{ maxWidth: 260 }}>
  <InputGroup.Addon>
    <InputGroup.Text>$</InputGroup.Text>
  </InputGroup.Addon>
  <InputGroup.Input placeholder="0.00" inputMode="decimal" />
  <InputGroup.Addon>
    <InputGroup.Text>USD</InputGroup.Text>
  </InputGroup.Addon>
</InputGroup.Root>
```

Props:
  - size: "1" | "2" | "3" | "4" (default: 1) — Controls the height, text size and padding of the field.
  - variant: "classic" | "solid" | "soft" | "surface" | "ghost" (default: ghost) — Controls the visual style of the field.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" (default: gray) — Overrides the accent color used for the field's background tint and focus ring.

## InputOTP

Parts: InputOTP.Group, InputOTP.Root, InputOTP.Separator, InputOTP.Slot

```tsx
<InputOTP.Root
  maxLength={6}
  render={({ slots }) => (
    <>
      <InputOTP.Group>
        {slots.slice(0, 3).map((slot, index) => (
          <InputOTP.Slot key={index} {...slot} />
        ))}
      </InputOTP.Group>
      <InputOTP.Separator />
      <InputOTP.Group>
        {slots.slice(3).map((slot, index) => (
          <InputOTP.Slot key={index} {...slot} />
        ))}
      </InputOTP.Group>
    </>
  )}
/>
```

Props:
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" (default: gray) — Overrides the theme accent color for the OTP slots.

## Inset

```tsx
<Card size="2" className="max-w-70">
  <Inset side="top" pb="current">
    <div className="h-24 bg-accent-alpha-200" />
  </Inset>
  <Typography.Text size="2">
    The tinted area bleeds to the card&apos;s edges; this text keeps the normal padding.
  </Typography.Text>
</Card>
```

Props:
  - side: "all" | "x" | "y" | "top" | "bottom" | "left" | "right" (default: all) — Which side(s) the inset bleeds into the parent's padding.
  - clip: "border-box" | "padding-box" (default: border-box) — Whether content is clipped to the parent's border box or padding box.
  - p: "current" | "0" — Padding on all sides: 'current' keeps the parent's padding, '0' removes it.
  - px: "current" | "0" — Horizontal padding: 'current' keeps the parent's padding, '0' removes it.
  - py: "current" | "0" — Vertical padding: 'current' keeps the parent's padding, '0' removes it.
  - pt: "current" | "0" — Top padding: 'current' keeps the parent's padding, '0' removes it.
  - pr: "current" | "0" — Right padding: 'current' keeps the parent's padding, '0' removes it.
  - pb: "current" | "0" — Bottom padding: 'current' keeps the parent's padding, '0' removes it.
  - pl: "current" | "0" — Left padding: 'current' keeps the parent's padding, '0' removes it.

## Item

Parts: Item.Actions, Item.Content, Item.Description, Item.Group, Item.Media, Item.Root, Item.Separator, Item.Title

```tsx
<Item.Root variant="outline" style={{ maxWidth: 380 }}>
  <Item.Media>
    <Avatar fallback="AL" />
  </Item.Media>
  <Item.Content>
    <Item.Title>Ada Lovelace</Item.Title>
    <Item.Description>ada@example.com</Item.Description>
  </Item.Content>
  <Item.Actions>
    <Button size="1" variant="surface">
      Invite
    </Button>
  </Item.Actions>
</Item.Root>
```

Props:
  - size: "1" | "2" | "3" (default: 2) — The size of the item.
  - variant: "plain" | "outline" | "muted" (default: plain) — The visual style of the item.

## Kbd

```tsx
<div className="flex flex-col gap-3">
  <Typography.Text size="3">
    Press <Kbd>⇧⌘K</Kbd> to open the command palette.
  </Typography.Text>
  <div className="flex items-center gap-3">
    <Kbd size="1">Shift + Tab</Kbd>
    <Kbd size="3">Shift + Tab</Kbd>
    <Kbd size="5">Shift + Tab</Kbd>
  </div>
</div>
```

Props:
  - size: "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" — Sets the key cap size on the theme's typographic scale. When unset, the Kbd scales relative to the surrounding text.

## Lightbox

Parts: Lightbox.Caption, Lightbox.Close, Lightbox.Content, Lightbox.Counter, Lightbox.Item, Lightbox.ItemGroup, Lightbox.Next, Lightbox.Previous, Lightbox.Root, Lightbox.Thumbnail, Lightbox.ThumbnailGroup, Lightbox.Trigger, Lightbox.Zoom, Lightbox.ZoomIn, Lightbox.ZoomOut

```tsx
<Lightbox.Root viewTransition>
  <div className="grid max-w-105 grid-cols-3 gap-3">
    {overviewImages.map((img, i) => (
      <Lightbox.Trigger
        key={img.seed}
        index={i}
        crossfade
        className="cursor-pointer border-none bg-transparent p-0"
      >
        <img
          src={`https://picsum.photos/seed/${img.seed}/200/200`}
          alt={img.alt}
          className="block h-25 w-full rounded-xl object-cover"
        />
      </Lightbox.Trigger>
    ))}
  </div>

  <Lightbox.Content aria-label="Photo gallery">
    <div className="absolute top-4 right-4 z-1">
      <Lightbox.Close aria-label="Close" render={navButton}>
        <X />
      </Lightbox.Close>
    </div>

    <Lightbox.ItemGroup>
      {overviewImages.map((img, i) => (
        <Lightbox.Item key={img.seed} index={i}>
          <img
            src={`https://picsum.photos/seed/${img.seed}/1200/800`}
            alt={img.alt}
            className="max-h-[75vh] max-w-[90vw] rounded-lg object-contain"
          />
        </Lightbox.Item>
      ))}
    </Lightbox.ItemGroup>

    <div className="flex items-center gap-3 p-3">
      <Lightbox.Previous aria-label="Previous" render={navButton}>
        <ChevronLeft />
      </Lightbox.Previous>
      <Lightbox.Counter>
        {({ current, total }) => (
          <Typography.Text size="2" className="min-w-12 text-center text-white/70">
            {current} / {total}
          </Typography.Text>
        )}
      </Lightbox.Counter>
      <Lightbox.Next aria-label="Next" render={navButton}>
        <ChevronRight />
      </Lightbox.Next>
    </div>
  </Lightbox.Content>
</Lightbox.Root>
```

Props:
  - open: boolean — Controlled open state. Pair with `onOpenChange`.
  - defaultOpen: boolean (default: false) — Uncontrolled initial open state.
  - value: string | number — Controlled active item index. Pair with `onValueChange`.
  - defaultValue: string | number (default: 0) — Uncontrolled initial active item index.
  - loop: boolean (default: false) — Wrap navigation at the first and last items.
  - viewTransition: boolean (default: false) — Enable the View Transitions morph animation between trigger and lightbox item. Falls back to a fade when unsupported or when `prefers-reduced-motion` is set.
  - morphTo: "active" | "origin" | "closest" (default: active) — Which trigger receives the morph on close: `'active'` (the current item), `'origin'` (the trigger that opened the lightbox), or `'closest'` (the nearest registered trigger).
  - awaitImageDecode: boolean (default: true) — Whether the open morph waits for the destination image to decode before starting. Only relevant when `viewTransition` is enabled.

## Link

```tsx
<div className="flex flex-col gap-2">
  <Typography.Text size="3">
    Read the <Link href="#">documentation</Link> to get started.
  </Typography.Text>
  <div className="flex items-center gap-4">
    <Link href="#" underline="auto">
      Auto underline
    </Link>
    <Link href="#" underline="hover">
      Hover underline
    </Link>
    <Link href="#" underline="always">
      Always underlined
    </Link>
    <Link href="#" color="orange">
      Orange link
    </Link>
  </div>
</div>
```

Props:
  - size: "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" — Sets the text size on the theme's typographic scale. When unset, the link inherits the size of the surrounding text.
  - weight: "light" | "regular" | "medium" | "semi-bold" | "bold" — Sets the font weight of the link text.
  - trim: "normal" | "start" | "end" | "both" — Trims the leading (whitespace above and below the text) from the start, end, or both sides.
  - underline: "auto" | "hover" | "always" (default: auto) — Controls when the link's underline is shown.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — Overrides the theme accent color for this link. Inherits the theme accent color when unset.
  - highContrast: boolean — Renders a higher-contrast color variant for improved accessibility.

## Menubar

Parts: Menubar.CheckboxItem, Menubar.Content, Menubar.Group, Menubar.GroupLabel, Menubar.Item, Menubar.Menu, Menubar.RadioGroup, Menubar.RadioItem, Menubar.Root, Menubar.Separator, Menubar.Sub, Menubar.SubContent, Menubar.SubTrigger, Menubar.Trigger

```tsx
<Menubar.Root>
  <Menubar.Menu>
    <Menubar.Trigger>File</Menubar.Trigger>
    <Menubar.Content>
      <Menubar.Item>New window</Menubar.Item>
      <Menubar.Item>Open…</Menubar.Item>
      <Menubar.Separator />
      <Menubar.Item>Print…</Menubar.Item>
    </Menubar.Content>
  </Menubar.Menu>
  <Menubar.Menu>
    <Menubar.Trigger>Edit</Menubar.Trigger>
    <Menubar.Content>
      <Menubar.Item>Undo</Menubar.Item>
      <Menubar.Item>Redo</Menubar.Item>
    </Menubar.Content>
  </Menubar.Menu>
</Menubar.Root>
```

Props:
  - orientation: "horizontal" | "vertical" (default: horizontal) — The orientation of the menubar.
  - modal: boolean (default: true) — Whether the open menu traps focus and blocks interaction with the rest of the page.
  - loopFocus: boolean (default: true) — Whether arrow-key focus loops back to the first item when it reaches the end.

## Meter

```tsx
return <Meter />;
```

Props:
  - size: "1" | "2" | "3" | "4" | "5" | "6" (default: 4) — Controls the height of the meter.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — Overrides the theme accent color for the indicator (default undefined = inherit the theme accent).
  - highContrast: boolean — Renders a higher-contrast indicator color.

## NavigationMenu

Parts: NavigationMenu.Content, NavigationMenu.Item, NavigationMenu.Link, NavigationMenu.List, NavigationMenu.Root, NavigationMenu.Trigger, NavigationMenu.Viewport

```tsx
<NavigationMenu.Root>
  <NavigationMenu.List>
    <NavigationMenu.Item>
      <NavigationMenu.Trigger>Product</NavigationMenu.Trigger>
      <NavigationMenu.Content>
        <NavigationMenu.Link href="#overview">Overview</NavigationMenu.Link>
        <NavigationMenu.Link href="#pricing">Pricing</NavigationMenu.Link>
      </NavigationMenu.Content>
    </NavigationMenu.Item>
    <NavigationMenu.Item>
      <NavigationMenu.Link href="#support">Support</NavigationMenu.Link>
    </NavigationMenu.Item>
  </NavigationMenu.List>
  <NavigationMenu.Viewport />
</NavigationMenu.Root>
```

Props:
  - delay: string | number (default: 50) — How long to wait before opening the navigation popup, in milliseconds.
  - closeDelay: string | number (default: 50) — How long to wait before closing the navigation popup, in milliseconds.
  - orientation: "horizontal" | "vertical" (default: horizontal) — The orientation of the navigation menu.

## NumberField

Parts: NumberField.Decrement, NumberField.Increment, NumberField.Input, NumberField.Root, NumberField.Slot

```tsx
<div className="flex w-45 flex-col gap-3">
  <NumberField.Root defaultValue={50} min={0} max={100}>
    <NumberField.Input />
  </NumberField.Root>

  <NumberField.Root defaultValue={5} buttonLayout="split">
    <NumberField.Slot>Qty</NumberField.Slot>
    <NumberField.Input />
  </NumberField.Root>

  <NumberField.Root defaultValue={99} buttonLayout="none">
    <NumberField.Slot>$</NumberField.Slot>
    <NumberField.Input />
  </NumberField.Root>
</div>
```

Props:
  - size: "1" | "2" | "3" | "4" (default: 2) — Controls the overall size (height, padding and typography) of the field.
  - variant: "surface" | "soft" (default: surface) — Controls the visual style of the field.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" (default: gray) — Overrides the theme accent color for the field and its stepper buttons.
  - buttonLayout: "split" | "trailing" | "none" (default: trailing) — Controls where the increment/decrement buttons are placed: on either side of the input, grouped after it, or hidden entirely.

## Overlay

Parts: Overlay.Content, Overlay.Root

```tsx
<Overlay.Root alignment="topTrailing">
  <div className="size-40 rounded-2xl bg-accent-alpha-200" />
  <Overlay.Root.Content>
    <Badge color="red" variant="solid" className="m-2">
      99+
    </Badge>
  </Overlay.Root.Content>
</Overlay.Root>
```

Props:
  - alignment: "center" | "leading" | "trailing" | "top" | "bottom" | "topLeading" | "topTrailing" | "bottomLeading" | "bottomTrailing" | "centerFirstTextBaseline" | "centerLastTextBaseline" | "leadingFirstTextBaseline" | "leadingLastTextBaseline" | "trailingFirstTextBaseline" | "trailingLastTextBaseline" (default: center) — Where `Overlay.Content` is positioned over the base content, using SwiftUI-style alignment (leading/trailing resolve against the writing direction).

## Pagination

Parts: Pagination.Content, Pagination.Ellipsis, Pagination.Item, Pagination.Link, Pagination.Next, Pagination.Previous, Pagination.Root

```tsx
<Pagination.Root>
  <Pagination.Content>
    <Pagination.Item>
      <Pagination.Previous href="#" />
    </Pagination.Item>
    <Pagination.Item>
      <Pagination.Link href="#">1</Pagination.Link>
    </Pagination.Item>
    <Pagination.Item>
      <Pagination.Link href="#" isActive>
        2
      </Pagination.Link>
    </Pagination.Item>
    <Pagination.Item>
      <Pagination.Ellipsis />
    </Pagination.Item>
    <Pagination.Item>
      <Pagination.Link href="#">24</Pagination.Link>
    </Pagination.Item>
    <Pagination.Item>
      <Pagination.Next href="#" />
    </Pagination.Item>
  </Pagination.Content>
</Pagination.Root>
```

Props:
  - size: "1" | "2" | "3" (default: 2) — The size of the pagination controls.

## Popover

Parts: Popover.Close, Popover.Content, Popover.Root, Popover.Trigger

```tsx
<Popover.Root>
  <Popover.Trigger>
    <Button variant="soft">Comment</Button>
  </Popover.Trigger>
  <Popover.Content className="w-90">
    <div className="flex gap-3">
      <Avatar size="2" fallback="A" />
      <div className="grow">
        <Textarea placeholder="Write a comment…" className="h-20" />
        <div className="mt-3 flex items-center justify-between gap-3">
          <Checkbox size="2">Send to group</Checkbox>
          <Popover.Close>
            <Button size="1">Comment</Button>
          </Popover.Close>
        </div>
      </div>
    </div>
  </Popover.Content>
</Popover.Root>
```

Props:
  - size: "1" | "2" | "3" | "4" (default: 2) — Controls the padding and border radius scale of the popover panel.
  - variant: "solid" | "translucent" (default: translucent) — Controls the panel's background treatment (opaque vs. blurred translucent).

## Portal

```tsx
const [show, setShow] = React.useState(false);
return (
  <div>
    <Button variant="soft" onClick={() => setShow(!show)}>
      {show ? 'Hide' : 'Show'} portaled content
    </Button>
    {show && (
      <Portal className="fixed right-5 bottom-5 z-[1000] rounded-md bg-panel-solid p-4 shadow-[var(--shadow-5)]">
        <Typography.Text size="2" weight="medium">
          Rendered at the end of document.body
        </Typography.Text>
      </Portal>
    )}
  </div>
);
```

## Progress

```tsx
<div className="flex w-70 flex-col gap-4">
  <Progress value={25} size="1" aria-label="25% complete" />
  <Progress value={60} size="2" aria-label="60% complete" />
  <Progress value={85} size="3" color="green" aria-label="85% complete" />
</div>
```

Props:
  - size: "1" | "2" | "3" | "4" | "5" | "6" (default: 6) — Controls the height of the progress bar.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — Overrides the theme accent color for the indicator (default undefined = inherit the theme accent).
  - highContrast: boolean — Renders a higher-contrast indicator color.

## RadioButtonGroup

Parts: RadioButtonGroup.Icon, RadioButtonGroup.Item, RadioButtonGroup.Root

```tsx
<RadioButtonGroup.Root defaultValue="Pro">
  <div className="flex gap-2">
    {plans.map((plan) => (
      <RadioButtonGroup.Item key={plan} value={plan}>
        <div className="flex items-center gap-2 rounded-lg border border-gray-alpha-500 px-4 py-2">
          <RadioButtonGroup.Icon />
          <Typography.Text size="2">{plan}</Typography.Text>
        </div>
      </RadioButtonGroup.Item>
    ))}
  </div>
</RadioButtonGroup.Root>
```

Props:
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — Overrides the theme accent color for the selected item's outline and check icon (default undefined = inherit the theme accent).
  - highContrast: boolean — Renders a higher-contrast selected state.

## RadioGroup

Parts: RadioGroup.Item, RadioGroup.Root

```tsx
<div className="flex gap-8">
  <RadioGroup.Root defaultValue="1">
    <RadioGroup.Item value="1">Default</RadioGroup.Item>
    <RadioGroup.Item value="2">Comfortable</RadioGroup.Item>
    <RadioGroup.Item value="3">Compact</RadioGroup.Item>
  </RadioGroup.Root>

  <RadioGroup.Root defaultValue="1" color="green" size="3">
    <RadioGroup.Item value="1">Green</RadioGroup.Item>
    <RadioGroup.Item value="2">Size 3</RadioGroup.Item>
  </RadioGroup.Root>
</div>
```

Props:
  - size: "1" | "2" | "3" (default: 2) — Controls the size of the radio buttons and their labels.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — Overrides the theme accent color for the selected radio buttons (default undefined = inherit the theme accent).
  - highContrast: boolean — Renders a higher-contrast selected state.

## Resizable

Parts: Resizable.Handle, Resizable.Panel, Resizable.Root

```tsx
<div
  style={{
    height: 200,
    width: 480,
    borderRadius: 'var(--radius-3)',
    boxShadow: '0 0 0 1px var(--gray-alpha-300) inset',
  }}
>
  <Resizable.Root direction="horizontal">
    <Resizable.Panel defaultSize={30} minSize={15}>
      <div style={{ padding: 'var(--space-4)' }}>
        <Typography.Text size="2">Sidebar</Typography.Text>
      </div>
    </Resizable.Panel>
    <Resizable.Handle withHandle />
    <Resizable.Panel defaultSize={70}>
      <div style={{ padding: 'var(--space-4)' }}>
        <Typography.Text size="2">Editor</Typography.Text>
      </div>
    </Resizable.Panel>
  </Resizable.Root>
</div>
```

Props:
  - withHandle: boolean — Shows a grip so the handle is discoverable without hovering.
  - defaultSize: string | number (default: 50) — The panel's starting size, relative to its siblings. Normalised so the group totals 100.
  - minSize: string | number (default: 10) — The smallest size, as a percentage of the group, the panel can be dragged to.
  - direction: "horizontal" | "vertical" (default: horizontal) — The axis the panels are laid out along.

## Result

Parts: Result.Actions, Result.Description, Result.Header, Result.Icon, Result.Root, Result.Title

```tsx
<Result.Root status="success">
  <Result.Icon />
  <Result.Title>Payment complete</Result.Title>
  <Result.Description>We emailed a receipt to you. Your subscription is now active.</Result.Description>
  <Result.Actions style={{ flexDirection: 'row' }}>
    <Button variant="surface">View invoice</Button>
    <Button>Back to dashboard</Button>
  </Result.Actions>
</Result.Root>
```

Props:
  - status: "success" | "error" | "warning" | "info" (default: info) — The outcome a `Result` communicates. Each status maps to a semantic accent color (`success`→green, `error`→red/danger, `warning`→amber, `info`→blue) and a default icon. / const resultStatuses = ['success', 'error', 'warning', 'info'] as const; type ResultStatus = (typeof resultStatuses)[number]; const resultRootPropDefs = { /** The outcome being communicated, which sets the media color and default icon.

## ScrollArea

```tsx
<ScrollArea type="hover" scrollbars="vertical" className="h-40 max-w-120">
  <div className="flex flex-col gap-3 pr-4">
    <Typography.Heading size="4" trim="start">
      Principles of the typographic craft
    </Typography.Heading>
    <Typography.Text render={<p />}>
      Three fundamental aspects of typography are legibility, readability, and aesthetics. Although in a
      non-technical sense "legible" and "readable" are often used synonymously, typographically they are separate
      but related concepts.
    </Typography.Text>
    <Typography.Text render={<p />}>
      Legibility describes how easily individual characters can be distinguished from one another. It is described
      by Walter Tracy as "the quality of being decipherable and recognisable".
    </Typography.Text>
    <Typography.Text render={<p />}>
      Typographers are concerned with legibility insofar as it is their job to select the correct font to use.
      Using only uppercase letters (all-caps) reduces legibility.
    </Typography.Text>
  </div>
</ScrollArea>
```

Props:
  - size: "1" | "2" | "3" (default: 1) — The thickness of the scrollbars.
  - scrollbars: "vertical" | "horizontal" | "both" (default: both) — Which scrollbars are rendered, constraining the directions the viewport can scroll in.
  - type: "auto" | "always" | "scroll" | "hover" (default: hover) — Describes the nature of scrollbar visibility, similar to how the scrollbar preferences in macOS control visibility of native scrollbars. - `"auto"` - scrollbars are visible when content is overflowing - `"always"` - scrollbars are always visible regardless of overflow - `"scroll"` - scrollbars are visible when the user is scrolling - `"hover"` - scrollbars are visible when scrolling or hovering over the scroll area
  - fadeEdges: "false" | "true" | "vertical" | "horizontal" (default: false) — Fades the scrollable edges with a gradient mask that only appears when there is more content to scroll in that direction. - `false` - no fade masks (default) - `true` - fade the top/bottom edges (equivalent to `"vertical"`) - `"vertical"` - fade the top/bottom edges - `"horizontal"` - fade the left/right edges

## Section

```tsx
<Section size="2" render={<section />}>
  <Typography.Text>
    Use the <Typography.Code>render</Typography.Code> prop to render the section as a{' '}
    <Typography.Code>&lt;section&gt;</Typography.Code> with vertical padding rhythm.
  </Typography.Text>
</Section>
```

Props:
  - size: Responsive<"1" | "2" | "3" | "4"> (default: 3) — The vertical padding of the section: 1=24px, 2=40px, 3=64px, 4=96px.

## Select

Parts: Select.Content, Select.Group, Select.GroupLabel, Select.Item, Select.Root, Select.Separator, Select.Trigger

```tsx
<Select.Root defaultValue="apple" size="2">
  <Select.Trigger />
  <Select.Content>
    <Select.Group>
      <Select.GroupLabel>Fruits</Select.GroupLabel>
      <Select.Item value="apple">Apple</Select.Item>
      <Select.Item value="orange">Orange</Select.Item>
      <Select.Item value="grape" disabled>
        Grape
      </Select.Item>
    </Select.Group>
    <Select.Separator />
    <Select.Group>
      <Select.GroupLabel>Vegetables</Select.GroupLabel>
      <Select.Item value="carrot">Carrot</Select.Item>
      <Select.Item value="potato">Potato</Select.Item>
    </Select.Group>
  </Select.Content>
</Select.Root>
```

Props:
  - highContrast: boolean — Renders the dropdown items in a higher-contrast color variant.
  - size: "1" | "2" | "3" | "4" (default: 2) — Controls the overall size of the trigger and dropdown content.
  - variant: "classic" | "surface" | "soft" | "ghost" (default: surface) — Controls the visual style of the trigger button.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — Overrides the theme accent color for the trigger. When omitted, the theme accent color is inherited (the 'surface' variant falls back to gray).

## Separator

```tsx
<Typography.Text size="2">
  Tools for building high-quality, accessible UI.
  <Separator size="4" className="my-3" />
  <div className="flex items-center gap-3">
    Themes
    <Separator orientation="vertical" />
    Primitives
    <Separator orientation="vertical" />
    Icons
    <Separator orientation="vertical" />
    Colors
  </div>
</Typography.Text>
```

Props:
  - size: "1" | "2" | "3" | "4" (default: 1) — Controls the length of the separator line.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" (default: gray) — Overrides the color of the separator line.

## Sheet

Parts: Sheet.Body, Sheet.Close, Sheet.Content, Sheet.Description, Sheet.Header, Sheet.NestedRoot, Sheet.Root, Sheet.Title, Sheet.Trigger

```tsx
<Sheet.Root>
  <Sheet.Trigger>
    <Button>Edit profile</Button>
  </Sheet.Trigger>

  <Sheet.Content>
    <Sheet.Header>
      <Sheet.Title>Edit profile</Sheet.Title>
      <Sheet.Description>Make changes to your profile.</Sheet.Description>
    </Sheet.Header>
    <Sheet.Body>
      <label>
        <Typography.Text render={<div />} size="2" weight="bold" className="mb-1">
          Name
        </Typography.Text>
        <Input.Control defaultValue="Freja Johnsen" placeholder="Enter your full name" />
      </label>

      <div className="mt-4 flex justify-end gap-3">
        <Sheet.Close>
          <Button variant="soft" color="gray">
            Cancel
          </Button>
        </Sheet.Close>
        <Sheet.Close>
          <Button>Save</Button>
        </Sheet.Close>
      </div>
    </Sheet.Body>
  </Sheet.Content>
</Sheet.Root>
```

Props:
  - open: boolean — Whether the sheet is open (controlled). Pair with `onOpenChange`.
  - defaultOpen: boolean (default: false) — Whether the sheet is initially open (uncontrolled). To render a controlled sheet, use `open`.
  - dismissible: boolean (default: true) — When `false`, swiping, clicking outside and pressing Escape will not close the sheet.

## Shine

```tsx
<div className="flex flex-col items-center gap-4">
  <Shine puffyness="2">
    <Typography.Text size="9" weight="bold">
      Shine ✨
    </Typography.Text>
  </Shine>
  <Shine puffyness="1">
    <Badge size="2" color="yellow">
      Premium
    </Badge>
  </Shine>
</div>
```

## Sidebar

Parts: Sidebar.Content, Sidebar.Footer, Sidebar.Group, Sidebar.GroupAction, Sidebar.GroupContent, Sidebar.GroupLabel, Sidebar.Header, Sidebar.Input, Sidebar.Inset, Sidebar.Menu, Sidebar.MenuAction, Sidebar.MenuBadge, Sidebar.MenuButton, Sidebar.MenuItem, Sidebar.MenuSkeleton, Sidebar.MenuSub, Sidebar.MenuSubButton, Sidebar.MenuSubItem, Sidebar.Provider, Sidebar.Rail, Sidebar.Root, Sidebar.Separator, Sidebar.Trigger

```tsx
<div
  style={{
    height: 320,
    borderRadius: 'var(--radius-3)',
    overflow: 'hidden',
    boxShadow: '0 0 0 1px var(--gray-alpha-300) inset',
  }}
>
  <Sidebar.Provider>
    <Sidebar.Root collapsible="icon">
      <Sidebar.Header>
        <Typography.Text size="2" weight="medium">
          Acme Inc.
        </Typography.Text>
      </Sidebar.Header>
      <Sidebar.Content>
        <Sidebar.Group>
          <Sidebar.GroupLabel>Workspace</Sidebar.GroupLabel>
          <Sidebar.Menu>
            <Sidebar.MenuItem>
              <Sidebar.MenuButton isActive>Dashboard</Sidebar.MenuButton>
            </Sidebar.MenuItem>
            <Sidebar.MenuItem>
              <Sidebar.MenuButton>Projects</Sidebar.MenuButton>
            </Sidebar.MenuItem>
          </Sidebar.Menu>
        </Sidebar.Group>
      </Sidebar.Content>
      <Sidebar.Rail />
    </Sidebar.Root>

    <Sidebar.Inset>
      <HStack spacing={8} style={{ padding: 'var(--space-3)' }}>
        <Sidebar.Trigger />
        <Typography.Text size="2" weight="medium">
          Dashboard
        </Typography.Text>
      </HStack>
    </Sidebar.Inset>
  </Sidebar.Provider>
</div>
```

Props:
  - side: "start" | "end" (default: start) — Which edge the sidebar is docked to.
  - variant: "sidebar" | "floating" | "inset" (default: sidebar) — The visual treatment of the sidebar.
  - collapsible: "offcanvas" | "icon" | "none" (default: offcanvas) — What collapsing does: slide off screen, shrink to an icon rail, or nothing.

## Skeleton

Parts: Skeleton.Avatar, Skeleton.Box, Skeleton.Rect, Skeleton.Text

```tsx
<Card size="2" className="max-w-80">
  <div className="flex items-center gap-3">
    <Skeleton.Avatar size="3" />
    <div className="flex flex-1 flex-col gap-2">
      <Skeleton.Text size="2" className="w-[60%]" />
      <Skeleton.Text size="2" className="w-[90%]" />
    </div>
  </div>
  <Skeleton.Rect className="mt-3 h-24" />
</Card>
```

Props:
  - size: "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" (default: 3) — The size of the avatar placeholder, matching Avatar's size scale.
  - shape: "circle" | "square" (default: circle) — The shape of the avatar placeholder, matching Avatar's shapes.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" (default: gray) — Overrides the theme accent color used for the skeleton's pulse.
  - highContrast: boolean — Renders a higher-contrast skeleton.

## Slider

```tsx
<div className="flex w-75 flex-col gap-4">
  <Slider defaultValue={[50]} />
  <Slider defaultValue={[30]} size="1" color="orange" />
  <Slider defaultValue={[25, 75]} color="cyan" />
  <Slider defaultValue={[60]} disabled />
</div>
```

Props:
  - size: "1" | "2" | "3" (default: 2) — The size of the slider's track and thumbs.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — Overrides the theme accent color for this slider. Inherits the theme accent when omitted.
  - highContrast: boolean — Renders a higher-contrast slider.

## Spacer

```tsx
<HStack spacing={0} className="w-80 rounded-xl border border-dashed border-gray-alpha-400 p-2">
  <Button size="1" variant="soft">
    Leading
  </Button>
  <Spacer minLength={24} />
  <Button size="1" variant="soft">
    Trailing
  </Button>
</HStack>
```

## Spinner

```tsx
<div className="flex items-center gap-6">
  <Spinner size="1" />
  <Spinner size="3" />
  <Spinner size="5" />
  {/* `loading` swaps children for a spinner while preserving their dimensions */}
  <Spinner loading>
    <Switch defaultChecked />
  </Spinner>
</div>
```

Props:
  - size: "1" | "2" | "3" | "4" | "5" | "6" (default: 2) — The size of the spinner.
  - loading: boolean (default: true) — Whether the spinner is shown. When `false`, the component renders its children (if any) instead of the spinner.

## Stepper

```tsx
<div style={{ width: 520 }}>
  <Stepper steps={steps} activeStep={2} />
</div>
```

Props:
  - size: "1" | "2" | "3" (default: 2) — The size of the step markers and labels.
  - orientation: "horizontal" | "vertical" (default: horizontal) — Whether the steps are laid out in a row or a column.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — Overrides the theme accent color for completed / current markers.
  - highContrast: boolean — Renders higher-contrast completed / current markers.

## Switch

```tsx
<div className="flex flex-wrap items-center gap-4">
  <Switch size="1" defaultChecked />
  <Switch size="2" defaultChecked />
  <Switch size="3" defaultChecked />
  <Typography.Text render={<label />} size="2" className="flex items-center gap-2">
    <Switch color="orange" defaultChecked />
    Notifications
  </Typography.Text>
</div>
```

Props:
  - size: "1" | "2" | "3" (default: 2) — Controls the size of the switch control.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — Overrides the theme accent color for the checked state (default undefined = inherit the theme accent).
  - highContrast: boolean — Renders a higher-contrast checked state.

## Table

Parts: Table.Body, Table.BottomBar, Table.Cell, Table.ColumnHeaderCell, Table.ColumnHeaderCellButton, Table.Footer, Table.Header, Table.Root, Table.Row, Table.RowHeaderCell, Table.Table

```tsx
<Table.Root variant="surface" className="min-w-105">
  <Table.Table>
    <Table.Header>
      <Table.Row>
        <Table.ColumnHeaderCell>Name</Table.ColumnHeaderCell>
        <Table.ColumnHeaderCell>Email</Table.ColumnHeaderCell>
        <Table.ColumnHeaderCell>Role</Table.ColumnHeaderCell>
      </Table.Row>
    </Table.Header>
    <Table.Body>
      <Table.Row>
        <Table.RowHeaderCell>Ada Lovelace</Table.RowHeaderCell>
        <Table.Cell>ada@example.com</Table.Cell>
        <Table.Cell>Admin</Table.Cell>
      </Table.Row>
      <Table.Row>
        <Table.RowHeaderCell>Grace Hopper</Table.RowHeaderCell>
        <Table.Cell>grace@example.com</Table.Cell>
        <Table.Cell>Developer</Table.Cell>
      </Table.Row>
      <Table.Row>
        <Table.RowHeaderCell>Alan Turing</Table.RowHeaderCell>
        <Table.Cell>alan@example.com</Table.Cell>
        <Table.Cell>Developer</Table.Cell>
      </Table.Row>
    </Table.Body>
  </Table.Table>
</Table.Root>
```

Props:
  - justify: "start" | "center" | "end" — Horizontal alignment of the cell's content.
  - width: string | number — Fixed width of the cell's column (any CSS width value; numbers are treated as pixels).
  - size: "1" | "2" (default: 2) — Controls cell padding and text size throughout the table.
  - variant: "surface" | "ghost" (default: surface) — Controls the table's visual style ('surface' adds a card-like background and border).
  - align: "start" | "center" | "end" | "baseline" — Vertical alignment of the cells in the row.

## Tabs

Parts: Tabs.Content, Tabs.List, Tabs.Root, Tabs.Trigger

```tsx
<Tabs.Root defaultValue="account" className="w-full max-w-100">
  <Tabs.List>
    <Tabs.Trigger value="account">Account</Tabs.Trigger>
    <Tabs.Trigger value="documents">Documents</Tabs.Trigger>
    <Tabs.Trigger value="settings">Settings</Tabs.Trigger>
  </Tabs.List>

  <Tabs.Content value="account" className="px-1 py-3">
    <Typography.Text size="2">Make changes to your account.</Typography.Text>
  </Tabs.Content>
  <Tabs.Content value="documents" className="px-1 py-3">
    <Typography.Text size="2">Access and update your documents.</Typography.Text>
  </Tabs.Content>
  <Tabs.Content value="settings" className="px-1 py-3">
    <Typography.Text size="2">Edit your profile and preferences.</Typography.Text>
  </Tabs.Content>
</Tabs.Root>
```

Props:
  - size: "1" | "2" (default: 2) — The size of the tab triggers.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — The color of the active tab indicator and label. Inherits the theme accent color when not set.
  - highContrast: boolean — Increases color contrast with the background for better legibility.

## TabsNav

Parts: TabsNav.Link, TabsNav.Root

```tsx
<TabsNav.Root className="w-full max-w-100">
  <TabsNav.Link active href="#">
    Account
  </TabsNav.Link>
  <TabsNav.Link href="#">Documents</TabsNav.Link>
  <TabsNav.Link href="#">Settings</TabsNav.Link>
</TabsNav.Root>
```

Props:
  - size: "1" | "2" (default: 2) — The size of the tab triggers.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — The color of the active tab indicator and label. Inherits the theme accent color when not set.
  - highContrast: boolean — Increases color contrast with the background for better legibility.

## Textarea

```tsx
<div className="flex w-75 flex-col gap-3">
  <Textarea placeholder="Reply to comment…" />
  <Textarea variant="soft" placeholder="Soft variant" />
  <Textarea variant="soft" color="blue" size="3" placeholder="Blue, size 3" />
  <Textarea disabled placeholder="Disabled" />
</div>
```

Props:
  - size: "1" | "2" | "3" | "4" (default: 2) — Controls the text size and padding of the text area.
  - variant: "surface" | "soft" (default: surface) — Controls the visual style of the text area.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" (default: gray) — Overrides the accent color used for the text area's background tint and focus ring.

## Theme

```tsx
<div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, minmax(0, 1fr))', gap: 'var(--space-4)' }}>
  <Theme appearance="light" style={{ padding: 'var(--space-5)', borderRadius: 'var(--radius-4)' }}>
    <Label>appearance=&quot;light&quot;</Label>
    <Sampler />
  </Theme>
  <Theme appearance="dark" style={{ padding: 'var(--space-5)', borderRadius: 'var(--radius-4)' }}>
    <Label>appearance=&quot;dark&quot;</Label>
    <Sampler />
  </Theme>
</div>
```

Props:
  - hasBackground: boolean (default: true)
  - appearance: "inherit" | "light" | "dark" (default: inherit)
  - accentColor: "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" (default: blue)
  - dangerColor: "red" | "rose" (default: red)
  - warningColor: "amber" | "yellow" | "orange" (default: amber)
  - successColor: "green" | "emerald" | "teal" (default: green)
  - infoColor: "sky" | "blue" | "cyan" (default: sky)

## Timeline

Parts: Timeline.Item, Timeline.Root

```tsx
<div style={{ width: 340 }}>
  <Timeline.Root>
    <Timeline.Item time="09:00" title="Order placed" />
    <Timeline.Item time="10:15" title="Payment confirmed" color="green" />
    <Timeline.Item time="12:30" title="Shipped" color="blue">
      Package left the Sydney warehouse.
    </Timeline.Item>
    <Timeline.Item time="—" title="Out for delivery" color="gray" />
  </Timeline.Root>
</div>
```

Props:
  - size: "1" | "2" | "3" (default: 2) — The size of the markers and text.

## Toaster

## Toggle

```tsx
<HStack spacing={8}>
  <Toggle defaultPressed>Bold</Toggle>
  <Toggle>Italic</Toggle>
  <Toggle>Underline</Toggle>
</HStack>
```

Props:
  - size: "1" | "2" | "3" | "4" (default: 2) — The size of the toggle.
  - variant: "solid" | "soft" | "surface" | "ghost" (default: soft) — The visual style of the toggle when pressed. Unpressed toggles always render as `ghost`.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — The color of the toggle when pressed. Inherits the theme accent color when not set.
  - highContrast: boolean — Increases color contrast with the background for better legibility.

## ToggleGroup

Parts: ToggleGroup.Content, ToggleGroup.List, ToggleGroup.Root, ToggleGroup.Trigger

```tsx
<ToggleGroup.Root defaultValue="account">
  <ToggleGroup.List>
    <ToggleGroup.Trigger value="account">Account</ToggleGroup.Trigger>
    <ToggleGroup.Trigger value="documents">Documents</ToggleGroup.Trigger>
    <ToggleGroup.Trigger value="settings">Settings</ToggleGroup.Trigger>
  </ToggleGroup.List>

  <ToggleGroup.Content value="account" className="px-1 py-3">
    <Typography.Text size="2">Make changes to your account.</Typography.Text>
  </ToggleGroup.Content>
  <ToggleGroup.Content value="documents" className="px-1 py-3">
    <Typography.Text size="2">Access and update your documents.</Typography.Text>
  </ToggleGroup.Content>
  <ToggleGroup.Content value="settings" className="px-1 py-3">
    <Typography.Text size="2">Edit your profile and preferences.</Typography.Text>
  </ToggleGroup.Content>
</ToggleGroup.Root>
```

Props:
  - value: string — The value of the selected segment (controlled). Pair with `onValueChange`.
  - defaultValue: string — The value of the initially selected segment (uncontrolled).

## ToggleGroupNav

Parts: ToggleGroupNav.Link, ToggleGroupNav.Root

```tsx
<ToggleGroupNav.Root>
  <ToggleGroupNav.Link active href="#">
    Account
  </ToggleGroupNav.Link>
  <ToggleGroupNav.Link href="#">Documents</ToggleGroupNav.Link>
  <ToggleGroupNav.Link href="#">Settings</ToggleGroupNav.Link>
</ToggleGroupNav.Root>
```

## ToggleGroupRadioGroup

Parts: ToggleGroupRadioGroup.Item, ToggleGroupRadioGroup.Root

```tsx
const [view, setView] = React.useState('day');

return (
  <div className="flex flex-col items-center gap-3">
    <ToggleGroupRadioGroup.Root value={view} onValueChange={setView}>
      <ToggleGroupRadioGroup.Item value="day">Day</ToggleGroupRadioGroup.Item>
      <ToggleGroupRadioGroup.Item value="week">Week</ToggleGroupRadioGroup.Item>
      <ToggleGroupRadioGroup.Item value="month">Month</ToggleGroupRadioGroup.Item>
    </ToggleGroupRadioGroup.Root>
    <Typography.Text size="2" color="gray">
      Selected view: {view}
    </Typography.Text>
  </div>
);
```

Props:
  - value: string — The value of the selected item (controlled). Pair with `onValueChange`.
  - disabled: boolean (default: false) — Whether the group should ignore user interaction.
  - defaultValue: string — The value of the initially selected item (uncontrolled).

## Tooltip

```tsx
<Tooltip content="This appears on hover">
  <Button variant="surface">Hover me</Button>
</Tooltip>
```

Props:
  - content: ReactNode — The content displayed inside the tooltip popup.

## TreeView

```tsx
<div style={{ width: 260 }}>
  <TreeView data={files} defaultExpandedIds={['src', 'components']} defaultSelectedId="button" />
</div>
```

Props:
  - size: "1" | "2" | "3" (default: 2) — The size of the rows and text.
  - color: "danger" | "warning" | "success" | "info" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone" — Overrides the theme accent color for the selected row.
  - highContrast: boolean — Renders a higher-contrast selected row.

## Typography

Parts: Typography.Blockquote, Typography.Code, Typography.Em, Typography.Heading, Typography.Quote, Typography.Strong, Typography.Text

```tsx
<div className="flex flex-col gap-2">
  <Typography.Text size="1">The quick brown fox jumps over the lazy dog.</Typography.Text>
  <Typography.Text size="2">The quick brown fox jumps over the lazy dog.</Typography.Text>
  <Typography.Text size="3">The quick brown fox jumps over the lazy dog.</Typography.Text>
  <Typography.Text size="4">The quick brown fox jumps over the lazy dog.</Typography.Text>
  <Typography.Text size="3" weight="medium">
    Medium weight
  </Typography.Text>
  <Typography.Text size="3" weight="bold">
    Bold weight
  </Typography.Text>
  <Typography.Text size="3" color="indigo">
    Indigo text
  </Typography.Text>
</div>
```

## VStack

```tsx
<VStack spacing={12} alignment="leading">
  <div style={box(64)}>1</div>
  <div style={box(128)}>2</div>
  <div style={box(96)}>3</div>
</VStack>
```

Props:
  - alignment: "leading" | "center" | "trailing" (default: center) — Horizontal alignment of children within the stack, using SwiftUI-style values (leading/trailing resolve against the writing direction).

## VisuallyHidden

```tsx
<div className="flex items-center gap-3">
  <IconButton variant="soft">
    <VisuallyHidden>Settings</VisuallyHidden>
    <Settings />
  </IconButton>
  <Typography.Text size="2" color="gray">
    Screen readers announce this button as &quot;Settings&quot;.
  </Typography.Text>
</div>
```

## WidgetStack

Parts: WidgetStack.Item, WidgetStack.Next, WidgetStack.Prev, WidgetStack.Root, WidgetStack.Stack

```tsx
<WidgetStack.Root orientation="horizontal">
  <div className="flex items-center gap-4">
    <WidgetStack.Prev render={<IconButton variant="soft" color="gray" className="rounded-full" />}>
      {'<'}
    </WidgetStack.Prev>

    <WidgetStack.Stack className="h-40 w-80">
      <WidgetStack.Item>
        <div className={`${itemClass} bg-linear-to-b from-blue-700 to-blue-400 text-blue-700-contrast`}>
          <Typography.Text weight="bold" size="5">
            Sunny, 24°
          </Typography.Text>
        </div>
      </WidgetStack.Item>
      <WidgetStack.Item>
        <div className={`${itemClass} bg-green-700 text-[64px]`}>🏝️</div>
      </WidgetStack.Item>
      <WidgetStack.Item>
        <div className={`${itemClass} bg-gray-50`}>
          <Typography.Text weight="medium" size="3">
            Swipe or use the arrows
          </Typography.Text>
        </div>
      </WidgetStack.Item>
    </WidgetStack.Stack>

    <WidgetStack.Next render={<IconButton variant="soft" color="gray" className="rounded-full" />}>
      {'>'}
    </WidgetStack.Next>
  </div>
</WidgetStack.Root>
```

Props:
  - orientation: "horizontal" | "vertical" (default: vertical) — Controls the scroll axis along which the stacked widgets are laid out and paged.

## ZStack

```tsx
<ZStack alignment="bottomTrailing">
  <div className="size-40 rounded-2xl bg-accent-alpha-200" />
  <div className="size-24 rounded-2xl bg-accent-alpha-400" />
  <div className="size-10 rounded-2xl bg-accent-alpha-700" />
</ZStack>
```

Props:
  - alignment: "center" | "leading" | "trailing" | "top" | "bottom" | "topLeading" | "topTrailing" | "bottomLeading" | "bottomTrailing" | "centerFirstTextBaseline" | "centerLastTextBaseline" | "leadingFirstTextBaseline" | "leadingLastTextBaseline" | "trailingFirstTextBaseline" | "trailingLastTextBaseline" (default: center) — Two-dimensional alignment of children within the stack, using SwiftUI-style values (leading/trailing resolve against the writing direction).