# Getting started

Binary UIKit provides Svelte 5 components and theme tokens for product interfaces. Configure the private package source, install the library with its date peer dependency, and place `Provider` near the root of your app.

<h2 id="purpose">Purpose</h2>

Use the package when an application needs the Binary Dreams token system and its Svelte 5 components. The published library contains no locale state, so your application keeps control of translated labels and route language.

<h2 id="install">Install</h2>

Binary Dreams publishes Binary UIKit to a private OneDev registry. Add the scope mapping to the project `.npmrc`:

```ini
@binarydreams:registry=https://git.binarydreams.io/BinaryDreams/~npm/
```

Keep credentials out of the project. Add a OneDev access token that can read packages to your user-level `~/.npmrc`, replacing the placeholder with the token value:

```ini
//git.binarydreams.io/BinaryDreams/~npm/:_authToken=<ONEDEV_ACCESS_TOKEN>
```

Install the library and its date peer dependency:

```sh
npm install @binarydreams/uikit @internationalized/date
```

<h2 id="provider">Add Provider</h2>

`Provider` installs the default variables and utility styles. Keep document mode for an app shell. Use scoped mode when the kit lives inside a widget or shadow root.

```svelte
<script lang="ts">
	import { Button, Provider } from '@binarydreams/uikit';
</script>

<Provider>
	<Button>Save changes</Button>
</Provider>
```

<h2 id="anatomy">Application structure</h2>

`Provider` establishes the theme boundary. Components sit below it and import from the package root. Overlays use the same boundary, including inside a scoped widget or shadow root.

<h2 id="usage">First component</h2>

Start with one action and keep its label in your application translation layer. Pass component state through props or bindings. Use snippets for visible content and custom cells.

<h2 id="variants">Configuration</h2>

A bare `Provider` installs Graphite Light with the Graphite accent, Compact density, and Ledger radii. The supported 2x2 model pairs Graphite and Blueprint styles with Light and Dark modes. Apply Graphite Dark, Blueprint Light, or Blueprint Dark with `BD_PRESET_GRAPHITE_DARK`, `BD_PRESET_BLUEPRINT`, or `BD_PRESET_BLUEPRINT_DARK`. Marketing Buttons use the pill shape as a contextual exception. Use `scoped={true}` only when the kit must stay inside an embedded boundary.

<h2 id="typescript">TypeScript and SvelteKit</h2>

Import public components and types from `@binarydreams/uikit`. The package supports Svelte 5 and exposes declarations for component props, snippets, callbacks, and bindable values.

<h2 id="accessibility">Accessibility</h2>

Many interactive components use Bits UI, which provides strong keyboard, focus, and ARIA behavior by default. Applications remain responsible for task-specific labels, status messages, and contrast, including after theme overrides.

<h2 id="tokens">Tokens and style hooks</h2>

Use the exported token objects when application code needs token values. Component styles read `--bd-*` variables. Apply visual changes through `Provider` overrides instead of private component classes.

<h2 id="related">Next steps</h2>

Read [Colors](/docs/foundations/colors) before changing theme values. Open the [Button reference](/docs/components/button) for a compact component example.


---

# Colors

Binary UIKit names colors and surfaces by purpose. Components read semantic variables instead of fixed values or theme names.

<h2 id="purpose">Semantic roles</h2>

Canvas, surface, and sunken roles establish the base. Semantic layers assign colors to cards, controls, floating panels, chrome, selections, and prose.

<h2 id="anatomy">Palette structure</h2>

Graphite Light is the base and default. Zinc surfaces, dark neutral text, monochrome technical colors, and a graphite accent define its character.

Accent and status roles communicate selection, progress, warning, and failure. Filled status roles have explicit foreground variables, and controls use a separate thumb foreground.

<h2 id="usage">Provider overrides</h2>

Pass a named preset or a partial `BDThemeOverrides` object to `Provider.overrides`. Graphite Light remains active when `overrides` is absent.

The supported 2x2 model pairs Graphite and Blueprint styles with Light and Dark modes. Graphite Light uses the base tokens and needs no preset. The package exports `BD_PRESET_GRAPHITE_DARK`, `BD_PRESET_BLUEPRINT`, and `BD_PRESET_BLUEPRINT_DARK` for the other three combinations.

Graphite Dark keeps compact ledger geometry on near-black layers. Blueprint Light uses pale drafting paper, blue heading ink, and Cobalt actions. Blueprint Dark keeps the Blueprint geometry on deep blue layers with a brighter Cobalt accent.

The library has no global theme store, picker, or preset-name prop. An application can own a selection and pass the matching object to `Provider`.

<h2 id="details">Roles and states</h2>

Use accent for the primary action and current selection. Use success, warning, danger, and info for states with matching text or icons.

Components use semantic layer, foreground, stroke, focus, and thumb variables. They never inspect `theme.name` or branch by theme ID.

<h2 id="accessibility">Contrast</h2>

Check text, controls, focus rings, status foregrounds, and thumbs on every changed surface. Do not rely on color as the only status cue.

<h2 id="tokens">Tokens</h2>

Use `BD_THEME`, `BD_ACCENT`, and `bdBuildCssVars` when code needs the same values as CSS. Important families include `--bd-layer-*`, `--bd-accent*`, `--bd-{success,warning,danger,info}*`, `--bd-stroke*`, `--bd-focus-ring*`, and `--bd-thumb`.

<h2 id="related">Related</h2>

Start with [Provider](/docs/components/provider) for scope behavior and [Badge](/docs/components/badge) for semantic tones.


---

# Brand

Binary Dreams is a studio that builds mobile apps with care. The identity reads calm and confident: quiet surfaces frame a fixed bright blue brand accent.

<h2 id="purpose">Positioning</h2>

The brand describes a mobile-first product studio, established in 2026. Keep the tone declarative and the surfaces quiet, so the official blue stays clear.

<h2 id="anatomy">Wordmark</h2>

The wordmark sets `Binary Dreams` in the display face across two lines, tightly tracked, with an accent period after the first word. The supporting line stays in the sans face at muted text weight.

<h2 id="usage">Mark</h2>

The mark pairs a rounded rectangle carrying two cut-out windows with a blue capsule and a single counter-form dot. Draw the rectangle in text ink and the windows in canvas. The capsule uses `--bd-brand-accent`, and its dot uses `--bd-brand-accent-fg`. These roles stay fixed across themes and application overrides.

<h2 id="details">On dark</h2>

On ink surfaces the wordmark shortens to `bd.`, set in the display face on a text-ink background with canvas-colored letters. The period keeps the fixed brand accent in both forms.

<h2 id="accessibility">Contrast</h2>

Place the wordmark on canvas, surface, or ink only. Check the blue period and capsule against Graphite and Blueprint surfaces in both modes. Never rely on color alone to carry meaning.

<h2 id="tokens">Tokens</h2>

Official brand accents read `--bd-brand-accent` and `--bd-brand-accent-fg`. These variables do not change with themes or `Provider` overrides. Supporting surfaces read `--bd-text`, `--bd-canvas`, and `--bd-surface`. Typography reads `--bd-font-display` and `--bd-font-sans`. The hero card uses `--bd-hero-wash` for its background image.

<h2 id="related">Related</h2>

See [Colors](/docs/foundations/colors) for application color roles, [Provider](/docs/components/provider) for scoped supporting surfaces, and [LogoStrip](/docs/components/logo-strip) for placing wordmarks in a row.


---

# Typography

Graphite Light uses Apple system fonts with Inter and system fallbacks. Presets can change font roles and type metrics without changing component code.

<h2 id="purpose">Type roles</h2>

Six heading roles carry structure. Two body roles carry interface and general body text. Caption, eyebrow, and mono carry supporting or technical labels.

Heading roles have desktop, tablet, and phone recipes at the 1024 and 640 px boundaries. Fixed roles keep one recipe across viewports.

<h2 id="anatomy">Families</h2>

The system has five font roles. `--bd-font-sans` serves UI labels and small headings. `--bd-font-display` serves display headings. `--bd-font-text` serves body and body-md. `--bd-font-prose` serves authored prose. `--bd-font-mono` serves technical values.

`--bd-font-prose` falls back to `--bd-font-text`. The four public themes keep the same sans and mono font stacks. Blueprint presets change type metrics and geometry without changing those families.

<h2 id="usage">Applying a role</h2>

The utility stylesheet exposes `.bd-h1` through `.bd-h6`, `.bd-body-md`, `.bd-body`, `.bd-caption`, `.bd-eyebrow`, and `.bd-mono`. Apply the class that matches the role. Choose the heading element from the document outline, not from its visual size.

For authored content, `.bd-prose` maps H2 and H3 to responsive H4 and H5 metrics. Paragraphs, list items, and blockquotes use Body metrics with `--bd-font-prose`. Table cells use Caption, table headers use Eyebrow, and code uses Mono. The utility does not set margins or colors.

<h2 id="details">Scale</h2>

Graphite Light and Graphite Dark use 72, 52, 38, 28, 22, and 18 px desktop heading sizes. Blueprint Light and Blueprint Dark use 88, 64, 44, 32, 24, and 20 px through the same semantic roles.

At widths below 1024 and 640 px, each heading changes to its tablet and phone recipe. Each role also owns weight, tracking, and line height.

<h2 id="accessibility">Reading comfort</h2>

Keep the heading level tied to structure, not to size. Reserve uppercase for short eyebrows and badges. Keep authored prose within the `--bd-measure-prose` reading measure.

<h2 id="tokens">Tokens</h2>

`BD_TOKENS.font` holds four default stacks. `bdBuildCssVars()` adds the fifth `prose` role with a fallback to `text`. `BD_TOKENS.type` owns Graphite Light's default metrics.

`BDThemeOverrides.font` can replace any font role. `BDThemeOverrides.type` can replace family assignments and metrics. Components read generated `--bd-font-*` and `--bd-type-*` variables.

<h2 id="related">Related</h2>

See [Eyebrow](/docs/components/eyebrow) for the uppercase label, [Section](/docs/components/section) for heading and description framing, and [CodeBlock](/docs/components/code-block) for monospace output.


---

# Spacing

Every gap, pad, and offset lands on a multiple of 4. The scale reaches from tight form fields to generous hero blocks, and components read it as `--bd-s-*` variables instead of fixed pixel values.

<h2 id="purpose">A 4-base rhythm</h2>

Spacing encodes relationship. Blocks that belong together sit closer, independent blocks sit farther apart. A single 4px base keeps that signal legible: two gaps either match or differ by a step a reader can perceive.

<h2 id="anatomy">Scale structure</h2>

Twelve steps run 4, 8, 12, 16, 20, 24, 32, 40, 56, 72, 96, and 128 px, exposed as `--bd-s-1` through `--bd-s-12`. Small steps handle control internals, mid steps handle grouping, large steps frame sections and hero blocks.

<h2 id="usage">Applying the scale</h2>

Space a group of blocks with the parent container's `gap`, not with the children's own margins. Use semantic HTML and local flex or grid CSS with `--bd-s-*` tokens. One container owns each rhythm.

<h2 id="details">Proximity ramp</h2>

Pick the gap between two blocks by how related they are. Tight (`--bd-s-1`) joins an element to its own satellite, such as a label and its control. Grouped (`--bd-s-3`) separates peers in one group. Related (`--bd-s-4`) separates headingless peer blocks. Distinct (`--bd-s-6`) separates sub-blocks within one surface. Zone (`--bd-s-8`) separates independent top-level sections and is the whitespace ceiling — when a firmer break is needed, add a boundary such as a `Divider` or a `Card` rather than more space.

<h2 id="accessibility">Density and targets</h2>

Keep controls far enough apart that a pointer or a focus ring cannot land ambiguously between them. Grouped is the practical floor between adjacent interactive rows; Tight is reserved for an element and its own satellite. Density changes the scale a component consumes, so verify hit areas after switching density.

<h2 id="tokens">Tokens</h2>

`BD_TOKENS.space` holds the numeric scale, and `bdBuildCssVars` emits it as `--bd-s-1` through `--bd-s-12`. Reference the variables in component styles; read the numbers only when code needs the same values as CSS.

<h2 id="related">Related</h2>

Compose rhythm with semantic HTML and `--bd-s-*` tokens. Use [Section](/docs/components/section), [Divider](/docs/components/divider), or [Card](/docs/components/card) when a stable public frame is needed.


---

# Radius

Softness on demand. Corner rounding comes from one scale and a small set of role radii, so a button, a card, and an input stay recognizable across every screen.

<h2 id="purpose">Corner scale</h2>

The scale runs from `none` through `3xl` to `full`. Small steps keep dense controls crisp, large steps soften panels and cards, and `full` produces a pill.

<h2 id="anatomy">Role radii</h2>

Components do not read the raw scale. Product Buttons read `--bd-r-btn`. Single-line fields read `--bd-r-input`. Marketing Buttons default to `--bd-r-pill`. An explicit `shape` prop can override that default. Chips read `--bd-r-pill`. Badges read `--bd-r-full`. Cards read `--bd-r-card`, and floating panels read `--bd-r-panel`.

Graphite Light and Graphite Dark use the Ledger profile: 5 px buttons and inputs, 8 px cards, 6 px panels, and 4 px items. Blueprint Light and Blueprint Dark use the roomier Rounded profile.

<h2 id="usage">Choosing a value</h2>

Pick the role radius that matches what the element is, not the value that looks right in isolation. Nested surfaces read best when the inner radius is smaller than the outer one. Do not hardcode a pixel value in a component.

<h2 id="tokens">Tokens</h2>

`BD_TOKENS.radius` holds the scale and `BD_RADIUS` holds the role profile. Pass `radius` overrides to `Provider` or to `bdBuildCssVars` when a product needs squarer or rounder corners; components keep reading the resulting `--bd-r-*` variables.

<h2 id="related">Related</h2>

See [Button](/docs/components/button) for product and marketing Button radii, [Card](/docs/components/card) for panel corners, and [Input](/docs/components/input) for field corners.


---

# Elevation

Elevation follows the active style. Graphite uses layers and borders without outer shadows. Blueprint adds cool shadows for raised surfaces.

<h2 id="purpose">Purpose</h2>

Elevation separates a surface from the one behind it. Use it when a panel floats above the page — menus, popovers, modals, toasts, and cards that lift on hover. A surface that sits flat in the layout needs a border, not a shadow.

<h2 id="anatomy">Layer structure</h2>

Blueprint levels use a soft cast and a tighter contact. As elevation rises, the cast grows and the contact attenuates. Graphite Light and Graphite Dark flatten the five outer levels to `none`. Their inset levels retain a quiet inner boundary for wells such as inputs and checkboxes.

<h2 id="usage">Applying a level</h2>

Read the level through its variable — `box-shadow: var(--bd-shadow-md)` — rather than writing a shadow value. `Provider` publishes the whole set, so a theme override changes every elevated surface at once.

<h2 id="details">Levels</h2>

In Blueprint, `xs` and `sm` mark low surfaces, `md` carries floating panels, and `lg` and `xl` carry large overlays. Graphite uses layer color and borders for the same boundaries. `glow` is an accent effect, not a depth level.

<h2 id="accessibility">Boundaries</h2>

Shadows are quiet by design and can disappear under high-contrast or forced-color settings. Keep a border or a background change on any surface whose boundary carries meaning, so the edge survives without the shadow.

<h2 id="tokens">Tokens</h2>

`--bd-shadow-xs`, `--bd-shadow-sm`, `--bd-shadow-md`, `--bd-shadow-lg`, `--bd-shadow-xl`, `--bd-shadow-inset`, `--bd-shadow-inset-sm`, and `--bd-shadow-glow`. The same values are available in code as `BD_THEME.shadows` and through `bdBuildCssVars`.

<h2 id="related">Related</h2>

See [Card](/docs/components/card) for the elevation prop, [Modal](/docs/components/modal) for the highest level, and [Popover](/docs/components/popover) for floating panels.


---

# Gradients

Binary UIKit ships five text gradients for display type. They are applied with utility classes, never with a color value written into a component.

`Provider` injects the utility stylesheet that defines the gradient classes, so no extra CSS file is needed.

<h2 id="purpose">Where gradients belong</h2>

Gradients carry hero titles and single-word emphasis. Keep them out of body copy, buttons, inputs, and any text that has to stay legible at small sizes. Contrast comes first.

<h2 id="anatomy">Two classes, one effect</h2>

A gradient needs the base class `.bd-grad-text` plus one ramp class. The base class clips the background to the glyphs; the ramp class supplies the image from a `--bd-grad-text-*` variable.

```html
<h1 class="bd-h1 bd-grad-text bd-grad-text-blueprint">Binary Dreams</h1>
```

<h2 id="usage">Use sparingly</h2>

One gradient per screen is usually enough. Apply it to a single heading or one word inside a heading, and let the rest of the type stay solid. Repeating the effect flattens its meaning.

<h2 id="details">The five ramps</h2>

The class names stay stable across themes. Graphite Light supplies monochrome default ramps. Graphite Dark reverses them for dark surfaces. Blueprint Light and Blueprint Dark replace them with blue technical ramps and warm `ember` and `dawn` counterparts.

<h2 id="accessibility">Legibility</h2>

Clipped text drops the solid `color` value, so a gradient must stay large and heavy enough to read on its own. Check every ramp against the surface behind it, and keep a solid fallback for text that carries meaning at body size.

<h2 id="tokens">Tokens</h2>

The default ramps live in `BD_THEME.gradients` and reach CSS as `--bd-grad-text-blueprint`, `--bd-grad-text-blueprint-deep`, `--bd-grad-text-ember`, `--bd-grad-text-dawn`, and `--bd-grad-text-ink`. A `Provider` override replaces the values without changing the class names.

<h2 id="related">Related</h2>

See [Provider](/docs/components/provider) for the utility stylesheet and overrides, and [Section](/docs/components/section) for the headings a gradient usually lands on.


---

# Grid backgrounds

Graphite and Blueprint provide different pattern recipes. The same grid utilities use the active theme's pattern without checking a theme ID.

<h2 id="purpose">Where patterns apply</h2>

Use a pattern when a surface needs quiet structure: a documentation hero, console frame, settings shell, or reading sheet. Actions still use the active accent.

<h2 id="anatomy">Pattern recipes</h2>

Graphite Light and Graphite Dark use interrupted execution traces on a 28 px rhythm. Blueprint Light and Blueprint Dark build quiet 1 px minor and major rules on a 24 px cell.

<h2 id="usage">Grid surfaces</h2>

`Provider` injects the pattern utility classes with the rest of the kit stylesheet. The base utilities paint `--bd-pattern` over `--bd-canvas`. Add `.bd-bg-grid-fade` to taper the active pattern without fading the content.

<h2 id="details">Utility classes</h2>

`.bd-bg-grid` and `.bd-bg-grid-blueprint` render the active theme pattern. `.bd-bg-grid-dots` and `.bd-bg-grid-crosshair` use generated geometry from the current theme colors. `.bd-bg-hero-blueprint` combines the active pattern with the theme's hero wash.

<h2 id="accessibility">Legibility</h2>

Patterns stay quiet on purpose. `.bd-bg-grid-fade` places the selected pattern on a masked pseudo-layer, while foreground content stays opaque. Use a semantic layer when the content needs stronger separation.

<h2 id="tokens">Tokens</h2>

`BDThemeOverrides.grid` controls pattern geometry, image, size, and position. The theme's technical color family supplies generated line, dot, and crosshair colors. `bdBuildCssVars()` emits the `--bd-pattern*`, `--bd-grid*`, and `--bd-hero-pattern*` families.

<h2 id="related">Related</h2>

See [Provider](/docs/components/provider) for how the utility stylesheet is injected, [Section](/docs/components/section) for the frame a grid usually sits behind, and [Card](/docs/components/card) for the opaque surface that carries text above one.


---

# Motion

Binary UIKit animates with curves rather than linear timing. Transitions are fast enough to feel responsive and curved enough to feel alive.

<h2 id="purpose">Duration and easing</h2>

Motion is expressed as one value that carries duration and easing. Components use stable semantic steps, while each preset can tune the resulting pace.

<h2 id="anatomy">The four steps</h2>

`fast` covers hover, focus, and small states. `base` is the common control step. `slow` covers large surfaces and overlays. `spring` is the emphasis recipe.

Graphite Light and Graphite Dark use 90, 140, 220, and 260 ms without spring overshoot. Blueprint Light and Blueprint Dark use 120, 200, 320, and 520 ms.

<h2 id="usage">Choosing a step</h2>

Default to `base`. Use `fast` for small changes that repeat often. Use `slow` when a large surface enters or leaves. Reserve `spring` for emphasis.

<h2 id="accessibility">Reduced motion</h2>

Honor `prefers-reduced-motion` in product code: shorten or remove movement and keep the state change itself visible. Never make an animation the only signal that something happened.

<h2 id="tokens">Tokens</h2>

`--bd-motion-fast`, `--bd-motion-base`, `--bd-motion-slow`, and `--bd-motion-spring` come from the merged motion axis through `Provider`. `BD_TOKENS.motion` supplies Graphite Light defaults, and `BDThemeOverrides.motion` can replace individual steps.

<h2 id="related">Related</h2>

See [Modal](/docs/components/modal) and [Sheet](/docs/components/sheet) for overlay timing, and [Accordion](/docs/components/accordion) for a state change on the base step.


---

# Provider

Installs theme variables, utility CSS, scope boundaries, and overlay portal context.

Place Provider around an application or an isolated subtree that needs Binary UIKit theme variables and overlay boundaries. Scoped utilities do not style matching classes outside `.bd-scope`; a host/global Provider can still style them separately.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `children` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `overrides` | `BDThemeOverrides` | prop | No | `undefined` | No additional description. |
| `scoped` | `boolean` | prop | No | `false` | If true, scopes CSS vars and utilities to this element / shadow root, leaving matching utility classes outside `.bd-scope` untouched. Default false (document mode). |

## Related

- [Accordion](/docs/components/accordion): Single or multiple disclosure panels.
- [Collapsible](/docs/components/collapsible): Single disclosure region with panel and plain presentations and measured-height animation.
- [Section](/docs/components/section): Top-level showcase or document section frame.

---

# Eyebrow

Tracked label used above headings.

Use Eyebrow as a short category label above a heading, not as a replacement for the heading.

## API

The package declarations define these public members.

### Inherited prop contracts

- `Omit<HTMLAttributes<HTMLDivElement>, 'children'>` — Props from this native base are accepted except the listed members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `children` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `color` | `string` | prop | No | `undefined` | Raw CSS color value (e.g. a var(--bd-*) token or color-mix() expression). Defaults to the accent. |

## Related

- [Avatar](/docs/components/avatar): Identity image or fallback with an optional status marker.
- [CodeBlock](/docs/components/code-block): Read-only code surface with copy support.
- [Stat](/docs/components/stat): Metric value and caption for KPI compositions.

---

# Link

Styled native link for body and navigation text.

Choose Link for inline or navigational text that leads to another destination.

## API

The package declarations define these public members.

### Inherited prop contracts

- `Omit<HTMLAnchorAttributes, 'children'>` — Props from this native base are accepted except the listed members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `children` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `variant` | `'accent' \| 'muted'` | prop | No | `'accent'` | No additional description. |

## Related

- [Segmented](/docs/components/segmented): Single-select segmented control.
- [Tabs](/docs/components/tabs): Panelled tabs with underline and pill presentations.
- [Breadcrumb](/docs/components/breadcrumb): Breadcrumb trail with optional overflow menu.

---

# Label

Visible form label with required-state treatment.

Pair Label with a form control when the field needs a persistent visible name.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `children` | `Snippet` | snippet | Yes | - | No additional description. |
| `for` | `string` | prop | No | `undefined` | Id of the control this labels. |
| `required` | `boolean` | prop | No | `false` | Renders the required marker. |
| `size` | `ControlSize` | prop | No | `'md'` | No additional description. |

## Related

- [Input](/docs/components/input): Single-line field with internal or external labeling, hint, error, icons, and password reveal.
- [Switch](/docs/components/switch): Bindable binary switch with visible or aria-only labeling.
- [Checkbox](/docs/components/checkbox): Bindable tri-state checkbox with a visible or ARIA-only accessible name.

---

# Badge

Compact semantic or categorical label.

Use Badge for compact status or category metadata that does not trigger an action. Each tone pairs a soft tint with its semantic foreground.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `children` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `tone` | `BadgeTone` | prop | No | `'neutral'` | No additional description. |

## Related

- [StatusDot](/docs/components/status-dot): Semantic status dot with an optional label and pulse.
- [EmptyState](/docs/components/empty-state): Empty-state message with optional art and action.
- [Spinner](/docs/components/spinner): Indeterminate loading indicator.

---

# Avatar

Identity image or fallback with an optional status marker.

Use Avatar to identify a person or account where a compact image or initials aid recognition.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `alt` | `string` | prop | No | `undefined` | Accessible alt text for the image. |
| `icon` | `IconGlyph` | prop | No | `undefined` | Fallback glyph when there is no image and no initials. |
| `initials` | `string` | prop | No | `undefined` | Initials shown when no `src` resolves. Optional once `icon` is a fallback. |
| `size` | `number \| ControlSize` | prop | No | `40` | Outer diameter — a number (px) or a token: sm 32 / md 40 / lg 56. |
| `src` | `string` | prop | No | `undefined` | Image URL. Renders an <img>, falling back to initials / icon on error. |
| `status` | `AvatarStatus` | prop | No | `undefined` | No additional description. |
| `statusLabel` | `string` | prop | No | `undefined` | Accessible presence text. Auto-derived as 'Online' / 'Offline' for `status` 'online' / 'offline'; required (and used verbatim) for the other five `status` values — the aria text is omitted when neither applies. |
| `variant` | `AvatarVariant` | prop | No | `'accent'` | No additional description. |

## Related

- [Eyebrow](/docs/components/eyebrow): Tracked label used above headings.
- [CodeBlock](/docs/components/code-block): Read-only code surface with copy support.
- [Stat](/docs/components/stat): Metric value and caption for KPI compositions.

---

# CodeBlock

Read-only code surface with copy support.

Choose CodeBlock for read-only code that readers may need to copy.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `code` | `string` | prop | Yes | - | Raw source. Exactly what the copy button puts on the clipboard. |
| `copyLabel` | `string` | prop | No | `'Copy code'` | Accessible label for the copy control. |
| `copyable` | `boolean` | prop | No | `true` | Render the copy control in the header. |
| `filename` | `string` | prop | No | `undefined` | Header label. |
| `highlight` | `(code: string, language: string) => string` | callback | No | `undefined` | Opt-in highlighter. The kit bundles none. Whatever this returns is injected with `{@html}` — **the caller owns sanitisation**. |
| `label` | `string` | prop | No | `undefined` | Accessible label for the code region. |
| `language` | `CodeLang \| (string & {})` | prop | No | `'text'` | Header label, and the hint passed to `highlight`. |
| `maxHeight` | `number` | prop | No | `undefined` | Maximum body height in px; taller content scrolls. |
| `showLineNumbers` | `boolean` | prop | No | `false` | Render a line-number gutter. |
| `wrap` | `boolean` | prop | No | `false` | Soft-wrap long lines instead of scrolling horizontally. |

## Related

- [Eyebrow](/docs/components/eyebrow): Tracked label used above headings.
- [Avatar](/docs/components/avatar): Identity image or fallback with an optional status marker.
- [Stat](/docs/components/stat): Metric value and caption for KPI compositions.

---

# Stat

Metric value and caption for KPI compositions.

Use Stat to foreground one metric and its caption inside a dashboard or summary.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | `string` | prop | No | `undefined` | Caption below the value. |
| `leading` | `Snippet` | snippet | No | `undefined` | Optional content slot rendered above the value (e.g. badge, icon). |
| `size` | `StatSize` | prop | No | `'md'` | Display size — `sm` 32 / `md` 40 / `lg` 56 px. Default `md`. |
| `value` | `string \| number` | prop | Yes | - | The numeric or short value displayed prominently. |

## Related

- [Eyebrow](/docs/components/eyebrow): Tracked label used above headings.
- [Avatar](/docs/components/avatar): Identity image or fallback with an optional status marker.
- [CodeBlock](/docs/components/code-block): Read-only code surface with copy support.

---

# StatusDot

Semantic status dot with an optional label and pulse.

Add StatusDot when a compact semantic indicator needs an optional text label.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `children` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `pulse` | `boolean` | prop | No | `false` | Pulse the dot for "live" / in-progress states. |
| `tone` | `StatusDotTone` | prop | No | `'neutral'` | Drives the dot color. |

## Related

- [Badge](/docs/components/badge): Compact semantic or categorical label.
- [EmptyState](/docs/components/empty-state): Empty-state message with optional art and action.
- [Spinner](/docs/components/spinner): Indeterminate loading indicator.

---

# LogoStrip

Row of text-based brand marks.

Use LogoStrip for a compact row of partner or customer wordmarks.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | `string` | prop | No | `undefined` | Accessible label for the surrounding `<ul>`. |
| `labels` | `readonly string[]` | prop | Yes | - | Brand wordmarks rendered in display font. |
| `variant` | `LogoStripVariant` | prop | No | `'light'` | `light` over a light surface (text-subtle); `dark` over a dark/accent surface. |

## Related

- [Eyebrow](/docs/components/eyebrow): Tracked label used above headings.
- [Avatar](/docs/components/avatar): Identity image or fallback with an optional status marker.
- [CodeBlock](/docs/components/code-block): Read-only code surface with copy support.

---

# EmptyState

Empty-state message with optional art and action.

Show EmptyState when a view has no content and the reader needs an explanation or next action.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `action` | `Snippet` | snippet | No | `undefined` | Slot for action buttons rendered below the description. |
| `art` | `Snippet` | snippet | No | `undefined` | Slot for custom artwork (replaces `icon` when provided). |
| `description` | `string` | prop | No | `undefined` | Optional supporting copy. |
| `icon` | `IconGlyph` | prop | No | `TrayIcon` | Iconic glyph rendered above the title. Defaults to `Tray`. |
| `size` | `EmptyStateSize` | prop | No | `'md'` | Vertical density. `sm` 32 / `md` 48 / `lg` 80 px outer padding. |
| `title` | `string` | prop | Yes | - | Headline. |

## Related

- [Badge](/docs/components/badge): Compact semantic or categorical label.
- [StatusDot](/docs/components/status-dot): Semantic status dot with an optional label and pulse.
- [Spinner](/docs/components/spinner): Indeterminate loading indicator.

---

# Placeholder

Decorative blueprint preview frame.

Use Placeholder as a decorative stand-in for media or unfinished preview content.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `height` | `number` | prop | No | `874` | No additional description. |
| `label` | `string` | prop | No | `'Preview slot'` | No additional description. |
| `width` | `number` | prop | No | `402` | No additional description. |

## Related

- [Eyebrow](/docs/components/eyebrow): Tracked label used above headings.
- [Avatar](/docs/components/avatar): Identity image or fallback with an optional status marker.
- [CodeBlock](/docs/components/code-block): Read-only code surface with copy support.

---

# Icon

Renders a phosphor-svelte glyph component passed as `glyph`.

Use Icon to render a Phosphor glyph when text alone does not communicate the action or subject quickly enough.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `color` | `string` | prop | No | `undefined` | Defaults to `currentColor` (phosphor default). |
| `glyph` | `IconGlyph` | prop | Yes | - | The glyph component itself — e.g. `HouseIcon` from `phosphor-svelte`. |
| `mirrored` | `boolean` | prop | No | `false` | Horizontally mirror the glyph (RTL). |
| `size` | `number \| string` | prop | No | `18` | px number or any CSS length. Default 18. |
| `weight` | `IconWeight` | prop | No | `'regular'` | phosphor weight. Default `regular`. |

## Related

- [Eyebrow](/docs/components/eyebrow): Tracked label used above headings.
- [Avatar](/docs/components/avatar): Identity image or fallback with an optional status marker.
- [CodeBlock](/docs/components/code-block): Read-only code surface with copy support.

---

# Spinner

Indeterminate loading indicator.

Show Spinner for work with an unknown completion time when the surrounding interface remains visible.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `color` | `string` | prop | No | `'currentColor'` | Stroke colour. Defaults to the inherited text colour. |
| `label` | `string` | prop | No | `'Loading'` | Accessible label announced to assistive tech. |
| `size` | `number \| ControlSize` | prop | No | `18` | Outer diameter — a number (px) or a token: sm 16 / md 20 / lg 24. |

## Related

- [Badge](/docs/components/badge): Compact semantic or categorical label.
- [StatusDot](/docs/components/status-dot): Semantic status dot with an optional label and pulse.
- [EmptyState](/docs/components/empty-state): Empty-state message with optional art and action.

---

# Alert

Inline semantic message, optionally dismissible.

Use Alert for an inline message that needs semantic emphasis within the current page.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `children` | `Snippet` | snippet | No | `undefined` | Message body. |
| `dismissLabel` | `string` | prop | No | `'Dismiss'` | Accessible label for the dismiss control. |
| `dismissible` | `boolean` | prop | No | `false` | No additional description. |
| `icon` | `IconGlyph \| boolean` | prop | No | `undefined` | Leading icon, rendered tinted to the tone colour. Pass an {@link IconGlyph} for a specific glyph, or `true` to use the tone's canonical glyph. |
| `iconContent` | `Snippet` | snippet | No | `undefined` | Arbitrary leading content in place of a glyph. Takes precedence over `icon`. A glyph and a snippet are both functions at runtime, so they cannot share one prop. |
| `onDismiss` | `() => void` | callback | No | `undefined` | No additional description. |
| `title` | `string` | prop | No | `undefined` | No additional description. |
| `tone` | `AlertTone` | prop | No | `'info'` | No additional description. |

## Related

- [Badge](/docs/components/badge): Compact semantic or categorical label.
- [StatusDot](/docs/components/status-dot): Semantic status dot with an optional label and pulse.
- [EmptyState](/docs/components/empty-state): Empty-state message with optional art and action.

---

# Skeleton

Decorative loading placeholder recipes.

Reserve Skeleton for loading layouts whose final structure is already known.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `circle` | `boolean` | prop | No | `false` | Round avatar — forces equal w/h and a full radius. |
| `height` | `string \| number` | prop | No | `undefined` | Box height. Number → px, string → used verbatim. Default 1em. |
| `lines` | `number` | prop | No | `undefined` | Render N stacked text bars; the last one is shortened. |
| `radius` | `string \| number` | prop | No | `undefined` | Corner radius. Number → px, string → used verbatim. |
| `variant` | `SkeletonVariant` | prop | No | `undefined` | Preset shape that seeds default width / height / radius. |
| `width` | `string \| number` | prop | No | `undefined` | Box width. Number → px, string → used verbatim. |

## Related

- [Badge](/docs/components/badge): Compact semantic or categorical label.
- [StatusDot](/docs/components/status-dot): Semantic status dot with an optional label and pulse.
- [EmptyState](/docs/components/empty-state): Empty-state message with optional art and action.

---

# Progress

Task progress or a bounded measurement, selected with a required kind.

Choose kind="task" for determinate or indeterminate work. Choose kind="measurement" for a named bounded value and add text when color alone would carry meaning.

## API

The package declarations define these public members.

### Inherited prop contracts

- `AccessibleName` — Requires exactly one accessible name: `label`, `aria-label`, or `aria-labelledby`.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `aria-label` | `string` | prop | No | `undefined` | No additional description. |
| `aria-labelledby` | `string` | prop | No | `undefined` | No additional description. |
| `aria-valuetext` | `string` | prop | No | `undefined` | No additional description. |
| `indeterminate` | `boolean` | prop | No | `false` | No additional description. |
| `kind` | `'measurement' \| 'task'` | prop | Yes | - | No additional description. |
| `label` | `string` | prop | No | `undefined` | No additional description. |
| `max` | `number` | prop | No | `100` | No additional description. |
| `min` | `number` | prop | No | `0` | No additional description. |
| `showValue` | `boolean` | prop | No | `false` | No additional description. |
| `tone` | `ProgressTone` | prop | No | `'accent'` | No additional description. |
| `value` | `number` | prop | No | `0` | No additional description. |
| `valueLabel` | `string` | prop | No | `undefined` | No additional description. |

## Related

- [Badge](/docs/components/badge): Compact semantic or categorical label.
- [StatusDot](/docs/components/status-dot): Semantic status dot with an optional label and pulse.
- [EmptyState](/docs/components/empty-state): Empty-state message with optional art and action.

---

# LiveRegion

Visually hidden ARIA live region for consumer-controlled announcements.

Use LiveRegion for one consumer-controlled status announcement. Announce state transitions or completed chunks, not each streamed token or a duplicate nested status.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `atomic` | `boolean` | prop | No | `true` | Announces the complete region when the message changes. |
| `message` | `string` | prop | No | `''` | Text that assistive technology announces. |
| `politeness` | `LiveRegionPoliteness` | prop | No | `'polite'` | Controls when assistive technology interrupts its current output. |

## Related

- [Badge](/docs/components/badge): Compact semantic or categorical label.
- [StatusDot](/docs/components/status-dot): Semantic status dot with an optional label and pulse.
- [EmptyState](/docs/components/empty-state): Empty-state message with optional art and action.

---

# Button

Button starts an action or opens a link while keeping size, tone, loading, and disabled behavior consistent.

Use Button for an action or link treatment. Select product and marketing contexts deliberately: product for interface actions, marketing for conversion CTAs. Use `fullWidth` when a button or full-width link must fill a bounded container. Open destructive confirmation with a quiet danger action.

<h2 id="purpose">Purpose</h2>

Use Button for a clear action. Choose one primary action in a local group. Use concise, verb-led labels such as “Save changes” or “Create project”. Use its link behavior when the same visual treatment must navigate to another location.

<h2 id="anatomy">Anatomy</h2>

The component owns the interactive element, label, optional icon snippets, and loading indicator. The `children` snippet supplies the visible label. Native buttons keep their built-in keyboard behavior, while `href` renders a link for navigation. Icon-only Buttons require an accessible label. If completion matters, announce the result separately because `loading` only marks the action as busy.

<h2 id="context">Context</h2>

<h3 id="product-context">Product context</h3>

Product is the default context. It uses the semantic Button radius and the small primary shadow. Use it in forms, dialogs, settings, toolbars, tables, empty states, and onboarding flows.

<h3 id="marketing-context">Marketing context</h3>

Marketing is an explicit context. It defaults to the pill shape. An enabled primary marketing Button uses the accent glow. Use it for landing-page heroes, pricing sections, compact marketing headers, and promotional banners. Do not use it for routine product actions.

```svelte
<Button context="marketing">Get started</Button>
```

<h2 id="shape">Shape</h2>

Shape remains independent from context. `rounded` uses the default Button radius. `pill` uses the full pill radius. `circle` is for icon-only Buttons. An explicit shape overrides the context default.

<h2 id="form-alignment">Form alignment</h2>

Product Button and Input use paired semantic radii. Their heights come from separate control and field recipes, so a preset can tune each role. Use the product default when Button sits beside or below an Input in a form.

Use `sm` only when the surrounding layout provides a clear and usable target. Icon-only Buttons require an accessible label.

<h2 id="standalone-hero-cta">Standalone hero CTA</h2>

One standalone hero CTA can use `lg` when one action dominates the page. Center the CTA in the hero. Do not place a second `lg` Button beside it.

```svelte
<Button context="marketing" size="lg">Start a project</Button>
```

<h2 id="two-button-hero-cta">Two-button hero CTA</h2>

A two-button hero group uses `md` for both buttons. Variant and glow create the hierarchy. Size does not create hierarchy inside the group.

```svelte
<Button context="marketing">Get started</Button>
<Button context="marketing" variant="outline">View examples</Button>
```

<h2 id="tokens">Tokens and style hooks</h2>

Button reads semantic accent, text, focus, radius, spacing, and motion variables. Override those values through `Provider` rather than targeting internal classes.

## API

The package declarations define these public members.

### Inherited prop contracts

- `Omit<HTMLButtonAttributes, 'children' | 'onclick'>` — Props from this native base are accepted except the listed members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `children` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `context` | `ButtonContext` | prop | No | `'product'` | No additional description. |
| `fullWidth` | `boolean` | prop | No | `false` | No additional description. |
| `href` | `string` | prop | No | `undefined` | Render an `<a>` instead of a `<button>`. |
| `icon` | `IconGlyph` | prop | No | `undefined` | Leading glyph component. |
| `iconContent` | `Snippet` | snippet | No | `undefined` | Arbitrary leading content. Takes precedence over `icon`. A glyph and a snippet are both functions at runtime, so they cannot share one prop. |
| `iconOnly` | `boolean` | prop | No | `false` | No additional description. |
| `loading` | `boolean` | prop | No | `false` | No additional description. |
| `onclick` | `(event: MouseEvent) => void` | callback | No | `undefined` | No additional description. |
| `shape` | `ButtonShape` | prop | No | `undefined` | No additional description. |
| `size` | `ButtonSize` | prop | No | `'md'` | No additional description. |
| `tone` | `ButtonTone` | prop | No | `'neutral'` | No additional description. |
| `trailing` | `IconGlyph` | prop | No | `undefined` | Trailing glyph component. |
| `trailingContent` | `Snippet` | snippet | No | `undefined` | Arbitrary trailing content. Takes precedence over `trailing`. |
| `variant` | `ButtonVariant` | prop | No | `'primary'` | No additional description. |

## Related

- [Chip](/docs/components/chip): Bindable toggle pill for compact filters on the shared control ladder.
- [CopyButton](/docs/components/copy-button): Clipboard action with temporary copied feedback.
- [Toolbar](/docs/components/toolbar): Data-driven toolbar with roving focus, action presentations and tones, and toggle groups.


---

# Input

Single-line field with internal or external labeling, hint, error, icons, and password reveal.

Use Input for one line of text. Compose an external Label with matching `for` and `id`, or provide at most one internal name through `label`, `aria-label`, or `aria-labelledby`.

## API

The package declarations define these public members.

### Inherited prop contracts

- `Omit<HTMLInputAttributes, 'value' | 'size' | 'aria-label' | 'aria-labelledby'>` — Props from this native base are accepted except the listed members.
- `Partial<AccessibleName>` — Optional internal naming accepts at most one of `label`, `aria-label`, or `aria-labelledby`; omit all three when an external `Label` targets the input `id`.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `aria-label` | `string` | prop | No | `undefined` | No additional description. |
| `aria-labelledby` | `string` | prop | No | `undefined` | No additional description. |
| `error` | `string` | prop | No | `undefined` | No additional description. |
| `hideLabel` | `string` | prop | No | `'Hide password'` | Accessible label for the reveal toggle while the password is shown. |
| `hint` | `string` | prop | No | `undefined` | No additional description. |
| `label` | `string` | prop | No | `undefined` | No additional description. |
| `leading` | `IconGlyph` | prop | No | `undefined` | Leading glyph component. |
| `leadingContent` | `Snippet` | snippet | No | `undefined` | Arbitrary leading content — a keycap, a prefix, a unit. Takes precedence over `leading`. A glyph and a snippet are both functions at runtime, so they cannot share one prop. |
| `revealToggle` | `boolean` | prop | No | `true` | Show a built-in show/hide toggle when `type="password"` and no custom `trailing`. |
| `showLabel` | `string` | prop | No | `'Show password'` | Accessible label for the reveal toggle while the password is hidden. |
| `trailing` | `IconGlyph` | prop | No | `undefined` | Trailing glyph component. Suppresses the built-in password reveal toggle. |
| `trailingContent` | `Snippet` | snippet | No | `undefined` | Arbitrary trailing content — a keycap, a character counter, a clear button. Takes precedence over `trailing` and suppresses the built-in password reveal toggle. |
| `value` | `string` | binding | No | `''` | No additional description. |

## Related

- [Label](/docs/components/label): Visible form label with required-state treatment.
- [Switch](/docs/components/switch): Bindable binary switch with visible or aria-only labeling.
- [Checkbox](/docs/components/checkbox): Bindable tri-state checkbox with a visible or ARIA-only accessible name.

---

# Switch

Bindable binary switch with visible or aria-only labeling.

Use Switch for a setting that takes effect as soon as it changes. The thumb keeps the same inset in both states.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `ariaLabel` | `string` | prop | No | `undefined` | aria-only label for icon-only placements — no visible caption is rendered. |
| `checked` | `boolean` | binding | No | `false` | No additional description. |
| `disabled` | `boolean` | prop | No | `false` | No additional description. |
| `label` | `string` | prop | No | `undefined` | Visible caption next to the track; clicking it toggles the switch. |
| `onCheckedChange` | `(checked: boolean) => void` | callback | No | `undefined` | No additional description. |
| `size` | `ControlSize` | prop | No | `'md'` | No additional description. |

## Related

- [Label](/docs/components/label): Visible form label with required-state treatment.
- [Input](/docs/components/input): Single-line field with internal or external labeling, hint, error, icons, and password reveal.
- [Checkbox](/docs/components/checkbox): Bindable tri-state checkbox with a visible or ARIA-only accessible name.

---

# Segmented

Single-select segmented control.

Choose Segmented for one selection among a short set of closely related text options.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `ariaLabel` | `string` | prop | No | `undefined` | Accessible label for the group. |
| `onValueChange` | `(value: T) => void` | callback | No | `undefined` | No additional description. |
| `optionLabel` | `(value: T) => string` | callback | No | `undefined` | Display label for an option value. Defaults to the value itself. Use this to render translated/formatted labels while keeping stable option values (e.g. `optionLabel={(v) => lang.t(v)}`). |
| `options` | `readonly T[]` | prop | Yes | - | No additional description. |
| `size` | `ControlSize` | prop | No | `'md'` | Control size. Defaults to `md` (the original dimensions). |
| `value` | `T` | binding | No | `undefined as T | undefined` | No additional description. |

## Related

- [Link](/docs/components/link): Styled native link for body and navigation text.
- [Tabs](/docs/components/tabs): Panelled tabs with underline and pill presentations.
- [Breadcrumb](/docs/components/breadcrumb): Breadcrumb trail with optional overflow menu.

---

# Tabs

Panelled tabs with underline and pill presentations.

Use Tabs to switch between peer sections that share the same page context. The underline variant uses only an active underline. Use the pill variant for a contained group.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `ariaLabel` | `string` | prop | No | `undefined` | aria-only label — Tabs renders no visible caption of its own. |
| `onValueChange` | `(value: T) => void` | callback | No | `undefined` | No additional description. |
| `orientation` | `"horizontal" \| "vertical"` | prop | No | `'horizontal'` | No additional description. |
| `panel` | `Snippet<[{ value: T; }]>` | snippet | No | `undefined` | Renders the active panel. Omit to render panels yourself. |
| `selectWhenFocused` | `boolean` | prop | No | `false` | Activate a tab as soon as it receives focus, rather than on Enter/Space. |
| `size` | `ControlSize` | prop | No | `'md'` | No additional description. |
| `tabs` | `readonly TabItem<T>[]` | prop | Yes | - | No additional description. |
| `value` | `T` | binding | No | `undefined as T | undefined` | Active tab. Two-way bindable; defaults to the first tab. |
| `variant` | `TabsVariant` | prop | No | `'underline'` | No additional description. |

## Related

- [Link](/docs/components/link): Styled native link for body and navigation text.
- [Segmented](/docs/components/segmented): Single-select segmented control.
- [Breadcrumb](/docs/components/breadcrumb): Breadcrumb trail with optional overflow menu.

---

# Chip

Bindable toggle pill for compact filters on the shared control ladder.

Use the default Chip for compact filters and selectable attributes. Chip uses the same control ladder as adjacent interactive elements.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `active` | `boolean` | binding | No | `false` | No additional description. |
| `children` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `disabled` | `boolean` | prop | No | `false` | No additional description. |
| `icon` | `IconGlyph` | prop | No | `undefined` | Leading glyph component. |
| `onActiveChange` | `(active: boolean) => void` | callback | No | `undefined` | No additional description. |
| `size` | `ControlSize` | prop | No | `'md'` | No additional description. |

## Related

- [Button](/docs/components/button): Primary action control or link with variants and loading state.
- [CopyButton](/docs/components/copy-button): Clipboard action with temporary copied feedback.
- [Toolbar](/docs/components/toolbar): Data-driven toolbar with roving focus, action presentations and tones, and toggle groups.

---

# Accordion

Single or multiple disclosure panels.

Use Accordion to reveal optional supporting content while keeping the page outline visible.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `answer` | `Snippet<[AccordionItem]>` | snippet | No | `undefined` | No additional description. |
| `items` | `AccordionItem[]` | prop | Yes | - | No additional description. |
| `multiple` | `Multiple` | prop | No | `undefined` | Allow more than one panel open at a time. With `multiple`, `value` and `onValueChange` resolve to `string[]`; otherwise `string \| undefined`. |
| `onValueChange` | `(value: AccordionValue<Multiple>) => void` | callback | No | `undefined` | No additional description. |
| `question` | `Snippet<[AccordionItem]>` | snippet | No | `undefined` | No additional description. |
| `value` | `AccordionValue<Multiple>` | binding | No | `undefined` | Open panel(s): `string \| undefined` for single select, `string[]` for multiple — discriminated by `multiple`. See {@link AccordionValue}. |

## Related

- [Provider](/docs/components/provider): Installs theme variables, utility CSS, scope boundaries, and overlay portal context.
- [Collapsible](/docs/components/collapsible): Single disclosure region with panel and plain presentations and measured-height animation.
- [Section](/docs/components/section): Top-level showcase or document section frame.

---

# Checkbox

Bindable tri-state checkbox with a visible or ARIA-only accessible name.

Choose Checkbox for an independent option or multi-selection. New code supplies exactly one accessible name through `label`, `aria-label`, or `aria-labelledby`. The optional-label branch exists only for source compatibility with 0.19. Do not create an unnamed control.

## API

The package declarations define these public members.

### Inherited prop contracts

- `AccessibleName` — Requires exactly one accessible name: `label`, `aria-label`, or `aria-labelledby`.
- `LegacyOptionalLabelCheckbox` — This shared prop contract also applies.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `aria-label` | `string` | prop | No | `undefined` | No additional description. |
| `aria-labelledby` | `string` | prop | No | `undefined` | No additional description. |
| `checked` | `boolean` | binding | No | `false` | No additional description. |
| `disabled` | `boolean` | prop | No | `false` | No additional description. |
| `indeterminate` | `boolean` | binding | No | `false` | Shows a mixed state for partial group selection. |
| `label` | `string` | prop | No | `undefined` | No additional description. |
| `onCheckedChange` | `(checked: boolean) => void` | callback | No | `undefined` | No additional description. |
| `size` | `ControlSize` | prop | No | `'md'` | No additional description. |

## Related

- [Label](/docs/components/label): Visible form label with required-state treatment.
- [Input](/docs/components/input): Single-line field with internal or external labeling, hint, error, icons, and password reveal.
- [Switch](/docs/components/switch): Bindable binary switch with visible or aria-only labeling.

---

# RadioGroup

Exclusive selection from labelled options.

Use RadioGroup when readers must choose exactly one visible option from a small set.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `disabled` | `boolean` | prop | No | `false` | No additional description. |
| `label` | `string` | prop | No | `undefined` | No additional description. |
| `name` | `string` | prop | No | `undefined` | Form field name forwarded to the hidden input. |
| `onValueChange` | `(value: T) => void` | callback | No | `undefined` | No additional description. |
| `options` | `readonly T[] \| readonly RadioOption<T>[]` | prop | Yes | - | Either bare values or `{ value, label, hint }` rows. |
| `orientation` | `"vertical" \| "horizontal"` | prop | No | `'vertical'` | No additional description. |
| `value` | `T` | binding | No | `undefined as T | undefined` | The selected value. Two-way bindable. |

## Related

- [Label](/docs/components/label): Visible form label with required-state treatment.
- [Input](/docs/components/input): Single-line field with internal or external labeling, hint, error, icons, and password reveal.
- [Switch](/docs/components/switch): Bindable binary switch with visible or aria-only labeling.

---

# PinInput

Multi-cell PIN or one-time-code entry.

Use PinInput for a named fixed-length PIN or one-time code that must participate in native form submission.

## API

The package declarations define these public members.

### Inherited prop contracts

- `AccessibleName` — Requires exactly one accessible name: `label`, `aria-label`, or `aria-labelledby`.
- `Omit<HTMLInputAttributes, 'type' | 'value' | 'maxlength' | 'minlength' | 'pattern' | 'aria-label' | 'aria-labelledby' | 'class' | 'style'>` — Props from this native base are accepted except the listed members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `allowPaste` | `boolean` | prop | No | `true` | Allow a whole code to be pasted into the control. |
| `aria-label` | `string` | prop | No | `undefined` | No additional description. |
| `aria-labelledby` | `string` | prop | No | `undefined` | No additional description. |
| `characters` | `'numeric' \| 'alphanumeric' \| 'any'` | prop | No | `'numeric'` | Character set accepted during typing and paste. |
| `error` | `string` | prop | No | `undefined` | Error text associated with the real input. |
| `label` | `string` | prop | No | `undefined` | No additional description. |
| `length` | `number` | prop | No | `6` | Number of cells and required code length. |
| `mask` | `boolean` | prop | No | `false` | Hide entered characters in the visual cells. |
| `onComplete` | `(value: string) => void` | callback | No | `undefined` | Fired once the value reaches `length`. |
| `onError` | `(error: PinInputError) => void` | callback | No | `undefined` | Fired when typed or pasted content does not match `characters`. |
| `value` | `string` | binding | No | `''` | The entered code. Two-way bindable. |

## Related

- [Label](/docs/components/label): Visible form label with required-state treatment.
- [Input](/docs/components/input): Single-line field with internal or external labeling, hint, error, icons, and password reveal.
- [Switch](/docs/components/switch): Bindable binary switch with visible or aria-only labeling.

---

# Textarea

Auto-growing multiline field with stable label, hint, error, count, and native-element associations.

Choose Textarea for free-form multiline text. Use its label or a native accessible name. Component errors replace hints, preserve consumer `aria-describedby`, and set `aria-invalid`.

## API

The package declarations define these public members.

### Inherited prop contracts

- `Omit<HTMLTextareaAttributes, 'value'>` — Props from this native base are accepted except the listed members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `error` | `string` | prop | No | `undefined` | No additional description. |
| `hint` | `string` | prop | No | `undefined` | No additional description. |
| `label` | `string` | prop | No | `undefined` | No additional description. |
| `maxRows` | `number` | prop | No | `undefined` | No additional description. |
| `ref` | `HTMLTextAreaElement` | binding | No | `undefined` | Bind this property to access the native textarea element. |
| `rows` | `number` | prop | No | `3` | No additional description. |
| `showCount` | `boolean` | prop | No | `false` | No additional description. |
| `value` | `string` | binding | No | `''` | No additional description. |

## Related

- [Label](/docs/components/label): Visible form label with required-state treatment.
- [Input](/docs/components/input): Single-line field with internal or external labeling, hint, error, icons, and password reveal.
- [Switch](/docs/components/switch): Bindable binary switch with visible or aria-only labeling.

---

# Select

Single select with native label, description, and error associations that optionally switches to a searchable combobox.

Use Select for one value from a list when showing every option at once would take too much space. Give it a visible label or an aria-label.

## API

The package declarations define these public members.

### Inherited prop contracts

- `Pick<HTMLButtonAttributes, "id" | "aria-describedby" | "aria-invalid" | "aria-label" | "aria-labelledby">` — Only the listed props from this native base are accepted.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `disabled` | `boolean` | prop | No | `false` | No additional description. |
| `emptyText` | `string` | prop | No | `'No results'` | Shown in place of the list when there is nothing to pick. |
| `error` | `string` | prop | No | `undefined` | Error message; also marks the active control invalid. |
| `hint` | `string` | prop | No | `undefined` | Helper text associated with the active control. |
| `label` | `string` | prop | No | `undefined` | Visible label associated with the active control. |
| `onValueChange` | `(value: T) => void` | callback | No | `undefined` | Fired whenever the selected value changes (alongside the bindable `value`). |
| `optionLabel` | `(value: T) => string` | callback | No | `undefined` | Resolve a display label from an option value, including reactive or localized labels. |
| `options` | `readonly T[] \| readonly SelectOption<T>[]` | prop | Yes | - | Either bare values or `{ value, label }` pairs. |
| `placeholder` | `string` | prop | No | `undefined` | Placeholder shown when nothing is selected. |
| `searchable` | `boolean` | prop | No | `false` | Render a filterable combobox instead of a plain select. |
| `value` | `T` | binding | No | `undefined as T | undefined` | The selected value. Two-way bindable. |

## Related

- [Label](/docs/components/label): Visible form label with required-state treatment.
- [Input](/docs/components/input): Single-line field with internal or external labeling, hint, error, icons, and password reveal.
- [Switch](/docs/components/switch): Bindable binary switch with visible or aria-only labeling.

---

# Slider

Single-value range control with optional readout.

Choose Slider for an approximate value within a bounded range where direct manipulation aids comparison. The accent fill covers the full visible track height.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `disabled` | `boolean` | prop | No | `false` | No additional description. |
| `formatValue` | `(value: number) => string` | callback | No | `undefined` | Format the displayed value, e.g. append a unit. |
| `label` | `string` | prop | No | `undefined` | No additional description. |
| `max` | `number` | prop | No | `100` | No additional description. |
| `min` | `number` | prop | No | `0` | No additional description. |
| `onValueChange` | `(value: number) => void` | callback | No | `undefined` | No additional description. |
| `showValue` | `boolean` | prop | No | `false` | Show the current value in mono at the right edge of the label row. |
| `step` | `number` | prop | No | `1` | No additional description. |
| `value` | `number` | binding | No | `0` | Current value. Two-way bindable. |

## Related

- [Label](/docs/components/label): Visible form label with required-state treatment.
- [Input](/docs/components/input): Single-line field with internal or external labeling, hint, error, icons, and password reveal.
- [Switch](/docs/components/switch): Bindable binary switch with visible or aria-only labeling.

---

# ScrubInput

Native numeric input with optional label dragging, bounds, steps, suffixes, and display formatting.

Use ScrubInput for precise numeric values in an inspector. Keep the native number input as the primary control. Treat label dragging as an optional pointer shortcut.

## API

The package declarations define these public members.

### Inherited prop contracts

- `AccessibleName` — Requires exactly one accessible name: `label`, `aria-label`, or `aria-labelledby`.
- `Omit<HTMLInputAttributes, 'type' | 'value' | 'min' | 'max' | 'step' | 'aria-label' | 'aria-labelledby'>` — Props from this native base are accepted except the listed members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `aria-label` | `string` | prop | No | `undefined` | No additional description. |
| `aria-labelledby` | `string` | prop | No | `undefined` | No additional description. |
| `formatValue` | `(value: number) => string` | callback | No | `undefined` | Formats the unfocused value and its accessible value text. |
| `label` | `string` | prop | No | `undefined` | No additional description. |
| `max` | `number` | prop | No | `undefined` | No additional description. |
| `min` | `number` | prop | No | `undefined` | No additional description. |
| `onValueChange` | `(value: number \| undefined) => void` | callback | No | `undefined` | No additional description. |
| `scrub` | `boolean` | prop | No | `false` | Enables pointer dragging on the visible label. |
| `step` | `number \| 'any'` | prop | No | `1` | No additional description. |
| `suffix` | `string` | prop | No | `undefined` | Visible unit shown after the native input value. |
| `value` | `number` | binding | No | `undefined` | Current numeric value. An undefined value leaves the input empty. |

## Related

- [Label](/docs/components/label): Visible form label with required-state treatment.
- [Input](/docs/components/input): Single-line field with internal or external labeling, hint, error, icons, and password reveal.
- [Switch](/docs/components/switch): Bindable binary switch with visible or aria-only labeling.

---

# FileUpload

Drag-and-drop file input with validation and removable files.

Use FileUpload when readers need to choose or drop one or more files and review validation results.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `accept` | `string` | prop | No | `undefined` | MIME type, MIME group, or comma-separated extensions — as the native `accept`. |
| `disabled` | `boolean` | prop | No | `false` | No additional description. |
| `files` | `File[]` | binding | No | `[]` | Current selection. Two-way bindable. |
| `hint` | `string` | prop | No | `undefined` | Secondary line under the headline, e.g. accepted formats. |
| `label` | `string` | prop | No | `undefined` | No additional description. |
| `maxSize` | `number` | prop | No | `undefined` | Maximum file size in bytes. |
| `multiple` | `boolean` | prop | No | `false` | Accept several files; the list below the dropzone grows instead of replacing. |
| `onError` | `(error: FileUploadError) => void` | callback | No | `undefined` | Fired when a file fails `accept` / `maxSize` validation. |
| `onFilesChange` | `(files: File[]) => void` | callback | No | `undefined` | Fired with the full selection whenever it changes. |
| `title` | `string` | prop | No | `'Drop files here or click to browse'` | Dropzone headline. |

## Related

- [Label](/docs/components/label): Visible form label with required-state treatment.
- [Input](/docs/components/input): Single-line field with internal or external labeling, hint, error, icons, and password reveal.
- [Switch](/docs/components/switch): Bindable binary switch with visible or aria-only labeling.

---

# CopyButton

Clipboard action with temporary copied feedback.

Use CopyButton for clipboard actions that need short, local confirmation.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `copiedIcon` | `IconGlyph` | prop | No | `CheckIcon` | Glyph shown after a successful copy. |
| `copiedLabel` | `string` | prop | No | `'Copied'` | a11y label announced after a successful copy. English fallback for locale-agnostic use — consumers should pass a localized string. |
| `label` | `string` | prop | No | `'Copy'` | a11y label in the idle state. English fallback for locale-agnostic use — consumers should pass a localized string. |
| `size` | `ButtonSize` | prop | No | `'md'` | No additional description. |
| `tone` | `'neutral' \| 'success'` | prop | No | `'neutral'` | Tint the copied-state icon with `--bd-success` for a confirmation cue. |
| `value` | `string` | prop | Yes | - | No additional description. |
| `variant` | `ButtonVariant` | prop | No | `'ghost'` | No additional description. |

## Related

- [Button](/docs/components/button): Primary action control or link with variants and loading state.
- [Chip](/docs/components/chip): Bindable toggle pill for compact filters on the shared control ladder.
- [Toolbar](/docs/components/toolbar): Data-driven toolbar with roving focus, action presentations and tones, and toggle groups.

---

# Calendar

Single-date calendar grid.

Use Calendar when date selection benefits from a persistent month grid.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `disabled` | `boolean` | prop | No | `false` | No additional description. |
| `isDateDisabled` | `(date: DateValue) => boolean` | callback | No | `undefined` | No additional description. |
| `isDateUnavailable` | `(date: DateValue) => boolean` | callback | No | `undefined` | No additional description. |
| `label` | `string` | prop | No | `undefined` | No additional description. |
| `locale` | `string` | prop | No | `undefined` | No additional description. |
| `maxValue` | `DateValue` | prop | No | `undefined` | No additional description. |
| `minValue` | `DateValue` | prop | No | `undefined` | No additional description. |
| `nextMonthLabel` | `string` | prop | No | `'Next month'` | No additional description. |
| `numberOfMonths` | `1 \| 2` | prop | No | `1` | No additional description. |
| `onValueChange` | `(value: DateValue \| undefined) => void` | callback | No | `undefined` | No additional description. |
| `previousMonthLabel` | `string` | prop | No | `'Previous month'` | No additional description. |
| `value` | `DateValue` | binding | No | `undefined` | Selected date. Two-way bindable. |
| `viewDate` | `DateValue` | binding | No | `undefined` | Bindable month in view. Maps to bits-ui's `placeholder`. |
| `weekStartsOn` | `0 \| 1` | prop | No | `1` | 1 = Monday, matching the range modes of `DateTimeField`. |

## Related

- [DateTimeField](/docs/components/date-time-field): Segmented date, date-range, time, or time-range field selected with a required mode.

---

# Collapsible

Single disclosure region with panel and plain presentations and measured-height animation.

Choose Collapsible for one optional region. Use the default panel variant for a standalone surface. Use `plain` inside an existing surface.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `children` | `Snippet` | snippet | Yes | - | No additional description. |
| `disabled` | `boolean` | prop | No | `false` | No additional description. |
| `label` | `string` | prop | No | `undefined` | No additional description. |
| `onOpenChange` | `(open: boolean) => void` | callback | No | `undefined` | No additional description. |
| `open` | `boolean` | binding | No | `false` | Two-way open state. |
| `trigger` | `Snippet` | snippet | No | `undefined` | Replaces the default label and caret row. |
| `variant` | `CollapsibleVariant` | prop | No | `'panel'` | No additional description. |

## Related

- [Provider](/docs/components/provider): Installs theme variables, utility CSS, scope boundaries, and overlay portal context.
- [Accordion](/docs/components/accordion): Single or multiple disclosure panels.
- [Section](/docs/components/section): Top-level showcase or document section frame.

---

# RatingGroup

Keyboard-operable whole or half-step rating control.

Use RatingGroup to collect or display a rating on a short ordered scale. Its flat gold fill shows the current value without decorative depth.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `allowHalf` | `boolean` | prop | No | `false` | Half-star precision. |
| `disabled` | `boolean` | prop | No | `false` | No additional description. |
| `icon` | `IconGlyph` | prop | No | `StarIcon` | Glyph. Defaults to a star. |
| `label` | `string` | prop | No | `undefined` | No additional description. |
| `max` | `number` | prop | No | `5` | No additional description. |
| `onValueChange` | `(value: number) => void` | callback | No | `undefined` | No additional description. |
| `readonly` | `boolean` | prop | No | `false` | No additional description. |
| `size` | `ControlSize` | prop | No | `'md'` | No additional description. |
| `value` | `number` | binding | No | `0` | Current rating. Two-way bindable. |

## Related

- [Label](/docs/components/label): Visible form label with required-state treatment.
- [Input](/docs/components/input): Single-line field with internal or external labeling, hint, error, icons, and password reveal.
- [Switch](/docs/components/switch): Bindable binary switch with visible or aria-only labeling.

---

# DateTimeField

DateTimeField provides segmented date and time entry. Its required `mode` selects the value shape and available controls.

Choose the required mode for date, date picker, date range, date range picker, time, or time range. Keep storage and time-zone conversion in application code.

<h2 id="purpose">Purpose</h2>

Use DateTimeField when a form needs a structured date, time, or range value. Keep persistent storage and time-zone conversion in application code.

<h2 id="anatomy">Anatomy</h2>

Each mode renders editable keyboard segments. Picker modes add a trigger and keyboard-operable calendar panel. Range modes render separate start and end groups. Provide a visible label or an accessible name for every field.

<h2 id="modes">Modes</h2>

| Mode                | Use                                                       |
| ------------------- | --------------------------------------------------------- |
| `date`              | Enter one date in editable segments.                      |
| `date-picker`       | Enter one date and open a calendar.                       |
| `date-range`        | Enter start and end dates in segments.                    |
| `date-range-picker` | Select a date range with a calendar and optional presets. |
| `time`              | Enter one time in editable segments.                      |
| `time-range`        | Enter start and end times in segments.                    |

Bind `value` to the type that the selected mode accepts. Picker modes also accept calendar labels and state.

```svelte
<DateTimeField
	mode="date-range-picker"
	bind:value={reportingPeriod}
	label="Reporting period"
	previousMonthLabel="Previous month"
	nextMonthLabel="Next month"
/>
```

<h2 id="tokens">Tokens and style hooks</h2>

DateTimeField uses input, surface, border, focus, accent, radius, spacing, and floating-layer tokens. Picker panels follow the active Provider boundary.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `align` | `'start' \| 'end'` | prop | No | `'start'` | No additional description. |
| `disabled` | `boolean` | prop | No | `false` | No additional description. |
| `error` | `string` | prop | No | `undefined` | No additional description. |
| `formatRange` | `(range: DateRange) => string` | callback | No | `formatRangeDefault` | No additional description. |
| `granularity` | `'day' \| 'hour' \| 'minute' \| 'second'` | prop | No | `undefined` | No additional description. |
| `hourCycle` | `12 \| 24` | prop | No | `undefined` | No additional description. |
| `isDateDisabled` | `(date: DateValue) => boolean` | callback | No | `undefined` | No additional description. |
| `isDateUnavailable` | `(date: DateValue) => boolean` | callback | No | `undefined` | No additional description. |
| `label` | `string` | prop | No | `undefined` | No additional description. |
| `locale` | `string` | prop | No | `undefined` | No additional description. |
| `maxValue` | `DateValue \| TimeValue` | prop | No | `undefined` | No additional description. |
| `minValue` | `DateValue \| TimeValue` | prop | No | `undefined` | No additional description. |
| `mode` | `'date' \| 'date-picker' \| 'date-range' \| 'date-range-picker' \| 'time' \| 'time-range'` | prop | Yes | - | No additional description. |
| `nextMonthLabel` | `string` | prop | No | `'Next month'` | No additional description. |
| `numberOfMonths` | `1 \| 2` | prop | No | `date-picker = 1, date-range-picker = 2` | No additional description. |
| `onValueChange` | `((value: DateRange) => void) \| ((value: DateValue \| undefined) => void) \| ((value: TimeRange<T>) => void) \| ((value: TimeValue \| undefined) => void)` | callback | No | `undefined` | No additional description. |
| `open` | `boolean \| never` | binding | No | `false` | The calendar popover state. Two-way bindable. |
| `openCalendarLabel` | `string` | prop | No | `'Open calendar'` | No additional description. |
| `presets` | `RangePreset[] \| never` | prop | No | `DEFAULT_PRESETS` | No additional description. |
| `previousMonthLabel` | `string` | prop | No | `'Previous month'` | No additional description. |
| `readonly` | `boolean` | prop | No | `false` | No additional description. |
| `size` | `ControlSize` | prop | No | `'md'` | No additional description. |
| `value` | `DateRange \| DateValue \| TimeRange<T> \| TimeValue` | binding | No | `date/date-picker/time = undefined, range modes = { start: undefined, end: undefined }` | No additional description. |
| `weekStartsOn` | `0 \| 1` | prop | No | `1` | No additional description. |

## Related

- [Calendar](/docs/components/calendar): Single-date calendar grid.


---

# Section

Top-level showcase or document section frame.

Use Section as the top-level frame for a documented or showcase section.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `children` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `description` | `string` | prop | No | `undefined` | No additional description. |
| `eyebrow` | `string` | prop | No | `undefined` | No additional description. |
| `fullbleed` | `boolean` | prop | No | `false` | No additional description. |
| `id` | `string` | prop | No | `undefined` | No additional description. |
| `title` | `string` | prop | No | `undefined` | No additional description. |
| `titleSize` | `'h2' \| 'h3' \| 'h4'` | prop | No | `'h3'` | Typographic scale of the title. Defaults to `h3`. |

## Related

- [Provider](/docs/components/provider): Installs theme variables, utility CSS, scope boundaries, and overlay portal context.
- [Accordion](/docs/components/accordion): Single or multiple disclosure panels.
- [Collapsible](/docs/components/collapsible): Single disclosure region with panel and plain presentations and measured-height animation.

---

# Card

Generic content surface with padding, variant, and elevation.

Use Card to group related content on a non-interactive surface, choosing fixed tokenized padding that stays inside its container.

## API

The package declarations define these public members.

### Inherited prop contracts

- `Omit<HTMLAttributes<HTMLDivElement>, 'children'>` — Props from this native base are accepted except the listed members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `border` | `boolean` | prop | No | `undefined` | Show the 1 px border. Defaults true for `surface`/`canvas`, false for filled variants. |
| `children` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `elevation` | `CardElevation` | prop | No | `'none'` | Elevation step from the shadow scale. |
| `overflow` | `'visible' \| 'hidden'` | prop | No | `'visible'` | Clip overflowing children at the rounded corner (use for media zones). |
| `padding` | `CardPadding` | prop | No | `'md'` | Fixed inner padding scale from `none` to `lg`. |
| `variant` | `CardVariant` | prop | No | `'surface'` | Background + foreground recipe. |

## Related

- [Provider](/docs/components/provider): Installs theme variables, utility CSS, scope boundaries, and overlay portal context.
- [Accordion](/docs/components/accordion): Single or multiple disclosure panels.
- [Collapsible](/docs/components/collapsible): Single disclosure region with panel and plain presentations and measured-height animation.

---

# AppShell

Responsive application shell with navigation, search, and mobile tabs.

Use AppShell for a localized application frame with primary navigation, search, content, and mobile navigation.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `account` | `Snippet` | snippet | No | `undefined` | Block at the bottom of the sidebar (account). |
| `brand` | `Snippet` | snippet | No | `undefined` | Block at the top of the sidebar (workspace or logo). |
| `children` | `Snippet` | snippet | No | `undefined` | Main content, which scrolls inside the floating surface. |
| `contentId` | `string` | prop | No | `undefined` | ID of the primary content target. Defaults to an SSR-stable generated ID. |
| `drawerOpen` | `boolean` | binding | No | `false` | Mobile drawer open state. Two-way bindable. |
| `fab` | `AppShellFab` | prop | No | `undefined` | Global floating action button (for example, Capture). |
| `header` | `Snippet` | snippet | No | `undefined` | Sticky bar over the content (breadcrumbs or page actions). |
| `height` | `number \| string` | prop | No | `'100dvh'` | Host height. Defaults to the full viewport; pass a number or CSS length to embed. |
| `labels` | `AppShellLabels` | prop | Yes | - | Locale-owned navigation and bypass-link labels. |
| `mainLandmark` | `boolean` | prop | No | `true` | Whether AppShell owns the page's main landmark and bypass link. |
| `nav` | `AppNavItem[]` | prop | No | `[]` | Primary navigation — sidebar on desktop, modal drawer on mobile. |
| `onSearchSelect` | `(item: CommandPaletteItem) => void` | callback | No | `undefined` | Fired when a palette row is chosen. |
| `onSearchSubmit` | `(query: string) => void` | callback | No | `undefined` | Fired when Enter is pressed with no row highlighted. |
| `search` | `boolean` | prop | No | `true` | Show the search trigger and command palette. |
| `searchEmpty` | `Snippet` | snippet | No | `undefined` | Empty-state content for the palette. |
| `searchFilter` | `boolean \| ((item: CommandPaletteItem, query: string) => boolean)` | callback | No | `undefined` | Client-side filtering of `searchItems` by the query. |
| `searchHotkey` | `string \| false` | prop | No | `'k'` | Letter for the global mod+letter shortcut. Falsy disables it. |
| `searchHotkeyHint` | `string` | prop | No | `undefined` | Visible shortcut hint. Auto-derived from `searchHotkey` when omitted. |
| `searchItems` | `CommandPaletteItem[] \| CommandPaletteGroup[]` | prop | No | `[]` | Result model rendered and navigated by the palette. |
| `searchLabel` | `string` | prop | No | `'Search'` | Accessible label for the search trigger and palette. |
| `searchOpen` | `boolean` | binding | No | `false` | Command-palette open state. Two-way bindable. |
| `searchPlaceholder` | `string` | prop | No | `'Search…'` | Placeholder for the search trigger and palette field. |
| `searchQuery` | `string` | binding | No | `''` | Search query. Two-way bindable. |
| `searchRow` | `Snippet<[CommandPaletteItem, boolean]>` | snippet | No | `undefined` | Optional per-row renderer for the palette. |
| `searchTrigger` | `'topbar' \| 'sidebar-top' \| 'sidebar-bottom'` | prop | No | `'topbar'` | Where the trigger sits: top bar (default) or the sidebar. |
| `tabs` | `AppNavItem[]` | prop | No | `undefined` | Mobile bottom navigation (a compact subset, usually 3–5 items). |

## Related

- [Provider](/docs/components/provider): Installs theme variables, utility CSS, scope boundaries, and overlay portal context.
- [Accordion](/docs/components/accordion): Single or multiple disclosure panels.
- [Collapsible](/docs/components/collapsible): Single disclosure region with panel and plain presentations and measured-height animation.

---

# Divider

Horizontal or vertical semantic separator.

Use Divider when spacing alone does not make the boundary between content groups clear.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | `never \| string` | prop | No | `undefined` | Optional centred label, e.g. "or". (Horizontal only.) |
| `orientation` | `'horizontal' \| 'vertical'` | prop | No | `'horizontal'` | No additional description. |

## Related

- [Provider](/docs/components/provider): Installs theme variables, utility CSS, scope boundaries, and overlay portal context.
- [Accordion](/docs/components/accordion): Single or multiple disclosure panels.
- [Collapsible](/docs/components/collapsible): Single disclosure region with panel and plain presentations and measured-height animation.

---

# Breadcrumb

Breadcrumb trail with optional overflow menu.

Use Breadcrumb to show the current page position within a navigable hierarchy.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `itemLabel` | `Snippet<[{ item: BreadcrumbItem; }]>` | snippet | No | `undefined` | Custom render for one crumb's label. |
| `items` | `BreadcrumbItem[]` | prop | Yes | - | Ordered trail. The last item, or any with `current: true`, is current. |
| `maxItems` | `number` | prop | No | `undefined` | Above this count, the middle collapses into an overflow Menu. |
| `navLabel` | `string` | prop | No | `'Breadcrumb'` | Accessible label for the `nav` landmark. |
| `overflowLabel` | `string` | prop | No | `'Show hidden crumbs'` | Accessible label for the overflow Menu trigger. |
| `separator` | `BreadcrumbSeparator \| Snippet` | snippet | No | `'chevron'` | Enum separator, or a snippet that replaces it entirely. |
| `size` | `ControlSize` | prop | No | `'md'` | No additional description. |

## Related

- [Link](/docs/components/link): Styled native link for body and navigation text.
- [Segmented](/docs/components/segmented): Single-select segmented control.
- [Tabs](/docs/components/tabs): Panelled tabs with underline and pill presentations.

---

# Toolbar

Data-driven toolbar with roving focus, action presentations and tones, and toggle groups.

Use Toolbar for related actions that need coordinated keyboard focus. Choose icon, label, or both for each item. Give every icon-only action a specific label. For toggle groups, `value` and `defaultValue` initialize uncontrolled state. Set `controlled: true` when each update must read the current `value`.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `items` | `ToolbarItem[]` | prop | Yes | - | Declarative item list: buttons, links, separators, and toggle groups. |
| `label` | `string` | prop | No | `undefined` | Accessible name for the `role="toolbar"` region. |
| `size` | `ControlSize` | prop | No | `'md'` | No additional description. |

## Related

- [Button](/docs/components/button): Primary action control or link with variants and loading state.
- [Chip](/docs/components/chip): Bindable toggle pill for compact filters on the shared control ladder.
- [CopyButton](/docs/components/copy-button): Clipboard action with temporary copied feedback.

---

# CommandPalette

Searchable command dialog with grouped results.

Use CommandPalette for searchable application commands when the available actions span several groups. Give duplicate titles distinct `id` values; titles remain searchable.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `empty` | `Snippet` | snippet | No | `undefined` | Shown when `items` is empty/absent (hint / empty state). |
| `filter` | `boolean \| ((item: CommandPaletteItem, query: string) => boolean)` | callback | No | `true` | Client-side filtering of `items` by `query`. `true` (default) keeps rows whose title / description / meta contain the query (case-insensitive). Pass a predicate for custom matching, or `false` to disable it (when the consumer filters externally, e.g. server-side, and feeds already-filtered `items`). |
| `hotkey` | `string \| false` | prop | No | `'k'` | Letter for the global mod+<letter> shortcut (⌘ on macOS, Ctrl elsewhere). Falsy disables. |
| `items` | `CommandPaletteItem[] \| CommandPaletteGroup[]` | prop | No | `[]` | Result model — flat list or grouped. Each item needs a distinct id; titles remain searchable. |
| `label` | `string` | prop | No | `'Search'` | Accessible label for the dialog and the result listbox. |
| `onSelect` | `(item: CommandPaletteItem) => void` | callback | No | `undefined` | Fired when a row is chosen (Enter on the highlighted row, or click), after the item's own `onSelect`. |
| `onSubmit` | `(query: string) => void` | callback | No | `undefined` | Fired when Enter is pressed with no row highlighted (free-text submit). |
| `open` | `boolean` | binding | No | `false` | Whether the palette is open. Two-way bindable. |
| `placeholder` | `string` | prop | No | `'Search…'` | Placeholder + accessible label for the search field. |
| `query` | `string` | binding | No | `''` | The search query. Two-way bindable. |
| `row` | `Snippet<[CommandPaletteItem, boolean]>` | snippet | No | `undefined` | Optional per-row renderer; receives (item, isActive). Overrides the default row body. |

## Related

- [Modal](/docs/components/modal): Dialog or confirmation modal selected with a required kind and delegated trigger.
- [Sheet](/docs/components/sheet): Edge-anchored dialog panel with optional body padding.
- [Menu](/docs/components/menu): Dropdown action menu with declarative items and eyebrow-styled group headers.

---

# Modal

Modal places a focused task above the current page and returns focus when the task closes.

Choose kind="dialog" for a short task or form that needs page context. Choose kind="confirmation" for a consequential choice with explicit Cancel and Confirm actions. On narrow screens, the dialog uses the available viewport width and keeps its fields contained.

<h2 id="purpose">Purpose</h2>

Use Modal for short decisions and forms that need page context. Set `kind` on every Modal. Use `dialog` for forms and short tasks. Use `confirmation` only when the user must explicitly accept or cancel a consequential decision. Move long or navigable work to a page or Sheet.

<h2 id="anatomy">Anatomy</h2>

Modal combines a consumer-owned trigger, dialog surface, title, description, content, and optional footer actions. The `trigger` snippet receives delegated props; spread them onto its one real interactive element. `kind="dialog"` uses Dialog behavior for forms and tasks. `kind="confirmation"` uses alert-dialog semantics and explicit Cancel and Confirm actions for consequential decisions. Bind the open state when application code must close the dialog after a save. Give every Modal a task-specific title and add a description when the consequence needs context. The dialog keeps focus inside its surface, closes with Escape when dismissible, and restores focus after closing.

<h2 id="tokens">Tokens and style hooks</h2>

Modal uses surface, border, shadow, radius, overlay, motion, and floating-layer tokens. A scoped `Provider` keeps its portal inside the active boundary.

## API

The package declarations define these public members.

### Inherited prop contracts

- `Omit<ModalBaseProps, 'title'>` — Props from this native base are accepted except the listed members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `cancelLabel` | `string` | prop | No | `'Cancel'` | No additional description. |
| `children` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `closeLabel` | `string` | prop | No | `'Close'` | No additional description. |
| `confirmLabel` | `string` | prop | No | `'Continue'` | No additional description. |
| `confirmVariant` | `ModalConfirmVariant` | prop | No | `'primary'` | No additional description. |
| `description` | `string` | prop | No | `undefined` | No additional description. |
| `dismissible` | `boolean` | prop | No | `true` | No additional description. |
| `footer` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `kind` | `'confirmation' \| 'dialog'` | prop | Yes | - | No additional description. |
| `onCancel` | `() => void` | callback | No | `undefined` | No additional description. |
| `onConfirm` | `() => void` | callback | No | `undefined` | No additional description. |
| `open` | `boolean` | binding | No | `false` | No additional description. |
| `size` | `ModalSize` | prop | No | `'md'` | No additional description. |
| `title` | `string` | prop | No | `undefined` | No additional description. |
| `trigger` | `Snippet<[Record<string, unknown>]>` | snippet | No | `undefined` | No additional description. |

## Related

- [CommandPalette](/docs/components/command-palette): Searchable command dialog with grouped results.
- [Sheet](/docs/components/sheet): Edge-anchored dialog panel with optional body padding.
- [Menu](/docs/components/menu): Dropdown action menu with declarative items and eyebrow-styled group headers.


---

# Sheet

Edge-anchored dialog panel with optional body padding.

Choose Sheet for supporting work that benefits from an edge-mounted panel and more room than a popover. Use an unpadded navigation sheet when the navigation owns its edge spacing. Set `padding="none"` for this case.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `children` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `closeLabel` | `string` | prop | No | `'Close'` | Close-button aria-label. |
| `description` | `string` | prop | No | `undefined` | Supporting line rendered under the title. |
| `dismissible` | `boolean` | prop | No | `true` | No additional description. |
| `footer` | `Snippet` | snippet | No | `undefined` | Action row pinned to the bottom of the sheet. |
| `open` | `boolean` | binding | No | `false` | No additional description. |
| `padding` | `SheetPadding` | prop | No | `'md'` | Body inset. Use `none` when the child owns its edge spacing. |
| `side` | `'left' \| 'right' \| 'bottom'` | prop | No | `'right'` | No additional description. |
| `size` | `SheetSize` | prop | No | `'md'` | Side-panel width (left/right only). Defaults to the original width. |
| `title` | `string` | prop | No | `undefined` | No additional description. |

## Related

- [CommandPalette](/docs/components/command-palette): Searchable command dialog with grouped results.
- [Modal](/docs/components/modal): Dialog or confirmation modal selected with a required kind and delegated trigger.
- [Menu](/docs/components/menu): Dropdown action menu with declarative items and eyebrow-styled group headers.

---

# Toaster

Toast region backed by the imperative toast queue.

Use Toaster for brief application feedback that does not need to interrupt the current task.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `closeLabel` | `string` | prop | No | `'Dismiss'` | Accessible label for the close control on each toast. |
| `label` | `string` | prop | No | `'Notifications'` | Accessible label for the toast region itself. |

## Related

- [Badge](/docs/components/badge): Compact semantic or categorical label.
- [StatusDot](/docs/components/status-dot): Semantic status dot with an optional label and pulse.
- [EmptyState](/docs/components/empty-state): Empty-state message with optional art and action.

---

# Menu

Dropdown action menu with declarative items and eyebrow-styled group headers.

Use Menu to place secondary actions behind one compact trigger. Use header items to group related actions. Group headers use the shared eyebrow typography recipe.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `children` | `Snippet` | snippet | No | `undefined` | Custom panel content as an alternative to `items`. |
| `items` | `MenuItem[]` | prop | No | `[]` | Declarative item list. Use this OR `children`. |
| `onOpenChange` | `(open: boolean) => void` | callback | No | `undefined` | Fired whenever the panel opens or closes. |
| `onSelect` | `(item: MenuAction) => void` | callback | No | `undefined` | Fired when any action row is chosen, after its own `onSelect`. |
| `open` | `boolean` | binding | No | `false` | Two-way panel open state. |
| `sameWidth` | `boolean` | prop | No | `false` | Match the panel width to the trigger width. |
| `trigger` | `Snippet \| Snippet<[Record<string, unknown>]> \| undefined` | snippet | No | `undefined` | Custom anchor snippet. Pair it with `triggerMode` to select the migration strategy. |
| `triggerIcon` | `IconGlyph` | prop | No | `DotsThreeIcon` | Glyph for the built-in trigger button, used only when no `trigger` snippet is given. |
| `triggerLabel` | `string` | prop | No | `undefined` | Accessible label for the built-in trigger button. |
| `triggerMode` | `'delegated' \| 'legacy' \| never` | prop | No | `undefined` | Required with `trigger`. `delegated` passes props to the control; `legacy` preserves the deprecated wrapper. |

## Related

- [CommandPalette](/docs/components/command-palette): Searchable command dialog with grouped results.
- [Modal](/docs/components/modal): Dialog or confirmation modal selected with a required kind and delegated trigger.
- [Sheet](/docs/components/sheet): Edge-anchored dialog panel with optional body padding.

---

# Tooltip

Hover and focus tooltip.

Use Tooltip for a short explanation of a control whose visible label cannot carry enough context.

## API

The package declarations define these public members.

### Inherited prop contracts

- `Common` — This shared prop contract also applies.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `content` | `string \| Snippet` | snippet | Yes | - | Tooltip copy — a plain string renders as text, a Snippet renders inline markup. |
| `disabled` | `boolean` | prop | No | `false` | Suppresses the panel entirely while keeping the trigger interactive. |
| `openDelay` | `number` | prop | No | `300` | Milliseconds the pointer must rest before the panel opens. |
| `side` | `Side` | prop | No | `'top'` | Preferred placement; flips automatically when it would overflow. |
| `trigger` | `Snippet \| Snippet<[Record<string, unknown>]> \| never` | snippet | No | `undefined` | The described element. Pair it with `triggerMode` to select the migration strategy. |
| `triggerIcon` | `IconGlyph \| never` | prop | No | `undefined` | Convenience trigger: renders a ghost icon-only Button with this glyph. |
| `triggerMode` | `'delegated' \| 'legacy' \| never` | prop | No | `undefined` | Required with `trigger`. `delegated` passes props to the control; `legacy` preserves the deprecated wrapper. |

## Related

- [CommandPalette](/docs/components/command-palette): Searchable command dialog with grouped results.
- [Modal](/docs/components/modal): Dialog or confirmation modal selected with a required kind and delegated trigger.
- [Sheet](/docs/components/sheet): Edge-anchored dialog panel with optional body padding.

---

# Popover

Free-form anchored floating panel.

Choose Popover for compact contextual content or controls anchored to a trigger.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `anchor` | `HTMLElement \| Measurable \| null` | prop | No | `null` | Position the panel against this instead of the trigger. Accepts a real element or anything that can report a rect (e.g. a virtual caret). |
| `children` | `Snippet` | snippet | Yes | - | Panel content. |
| `flush` | `boolean` | prop | No | `false` | Remove the built-in panel padding for edge-to-edge content. |
| `focusOnOpen` | `boolean` | prop | No | `true` | Move focus into the panel when it opens. Pass `false` to leave the caret where it is — for a mention menu over a textarea, say. With `false` the panel is never focused, so **the caller owns the ARIA wiring** on the input side: `role="combobox"`, `aria-expanded`, `aria-controls`, `aria-activedescendant`. |
| `onOpenChange` | `(open: boolean) => void` | callback | No | `undefined` | No additional description. |
| `open` | `boolean` | binding | No | `false` | Two-way panel open state. |
| `placement` | `PopoverPlacement` | prop | No | `'bottom'` | No additional description. |
| `sameWidth` | `boolean` | prop | No | `false` | Match the panel width to the trigger width. |
| `trigger` | `Snippet \| Snippet<[Record<string, unknown>]> \| undefined` | snippet | No | `undefined` | Custom anchor snippet. Pair it with `triggerMode` to select the migration strategy. |
| `triggerMode` | `'delegated' \| 'legacy' \| never` | prop | No | `undefined` | Required with `trigger`. `delegated` passes props to the control; `legacy` preserves the deprecated wrapper. |

## Related

- [CommandPalette](/docs/components/command-palette): Searchable command dialog with grouped results.
- [Modal](/docs/components/modal): Dialog or confirmation modal selected with a required kind and delegated trigger.
- [Sheet](/docs/components/sheet): Edge-anchored dialog panel with optional body padding.

---

# ContextMenu

Right-click action menu with consumer-owned trigger styling and eyebrow-styled group headers.

Use ContextMenu for actions tied to a specific region when a conventional menu trigger would add clutter. Apply delegated trigger props to one real target element. Use a native focusable element, or add the correct role and `tabindex="0"` to a custom target so keyboard users can reach it. ContextMenu does not style target typography. Apply a semantic utility such as `bd-body`. Header items use the shared eyebrow typography recipe.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `items` | `MenuItem[]` | prop | Yes | - | Same declarative model as Menu. |
| `onSelect` | `(item: MenuAction) => void` | callback | No | `undefined` | Fired when any action row is chosen, after its own `onSelect`. |
| `trigger` | `Snippet<[Record<string, unknown>]>` | snippet | Yes | - | Consumer-owned region that receives context-menu trigger props. |

## Related

- [CommandPalette](/docs/components/command-palette): Searchable command dialog with grouped results.
- [Modal](/docs/components/modal): Dialog or confirmation modal selected with a required kind and delegated trigger.
- [Sheet](/docs/components/sheet): Edge-anchored dialog panel with optional body padding.

---

# LinkPreview

Hover and focus preview for a link target.

Use LinkPreview when readers need a brief destination summary before following a link.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `children` | `Snippet` | snippet | Yes | - | Preview card contents. |
| `closeDelay` | `number` | prop | No | `undefined` | Milliseconds after the pointer leaves before the preview closes. bits-ui default: 300. |
| `href` | `string` | prop | Yes | - | Destination the trigger navigates to; also the element the preview anchors to. |
| `label` | `string` | prop | No | `undefined` | Fallback link text, used only when no `trigger` snippet is given. |
| `openDelay` | `number` | prop | No | `undefined` | Milliseconds the pointer must rest over the trigger before the preview opens. bits-ui default: 700. |
| `trigger` | `Snippet` | snippet | No | `undefined` | The link itself. Falls back to a styled anchor rendering `label`. |

## Related

- [CommandPalette](/docs/components/command-palette): Searchable command dialog with grouped results.
- [Modal](/docs/components/modal): Dialog or confirmation modal selected with a required kind and delegated trigger.
- [Sheet](/docs/components/sheet): Edge-anchored dialog panel with optional body padding.

---

# Menubar

Desktop application menubar with item-radius chrome, panel-radius dropdowns, and eyebrow-styled group headers.

Use Menubar for desktop-style command groups that must remain visible across a workspace. The outer bar uses the item radius, while dropdowns retain the panel radius. Header items use the shared eyebrow typography recipe.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | `string` | prop | No | `undefined` | Accessible name for the menubar as a whole, e.g. "Main menu". |
| `menus` | `MenubarMenu[]` | prop | Yes | - | One entry per top-level menu, each with its own trigger label and item list. |
| `onSelect` | `(item: MenuAction) => void` | callback | No | `undefined` | Fired when any action row is chosen, after its own `onSelect`. |

## Related

- [Link](/docs/components/link): Styled native link for body and navigation text.
- [Segmented](/docs/components/segmented): Single-select segmented control.
- [Tabs](/docs/components/tabs): Panelled tabs with underline and pill presentations.

---

# NavigationMenu

Top navigation with links and disclosure panels.

Use NavigationMenu for wide desktop navigation that mixes direct links with grouped destination panels. Use openMode="click" when pointer hover must not open a panel.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `items` | `NavigationMenuEntry[]` | prop | Yes | - | Top-level entries, left to right. |
| `label` | `string` | prop | No | `undefined` | Accessible name for the menu landmark. |
| `openMode` | `NavigationMenuOpenMode` | prop | No | `'hover'` | Opens panel entries on pointer hover or only when activated. |

## Related

- [Link](/docs/components/link): Styled native link for body and navigation text.
- [Segmented](/docs/components/segmented): Single-select segmented control.
- [Tabs](/docs/components/tabs): Panelled tabs with underline and pill presentations.

---

# Table

Table renders typed records with captions, sorting, controlled selection, responsive layouts, loading, empty, and row-action states.

Use Table for records compared across consistent fields. Add a caption. Choose cards for reordered narrow layouts or scroll to preserve columns. Controlled selection requires `rowKey` and localized selection labels.

<h2 id="purpose">Purpose</h2>

Use Table for records that users compare across consistent fields. Use a list when records do not share a comparison structure.

<h2 id="anatomy">Anatomy</h2>

Columns define headers, alignment, sorting, and cell behavior. Rows supply typed data. Optional snippets render cells and row actions.

Add a caption that identifies the record set. Set `captionVisuallyHidden` when the surrounding page already shows the same title.

Use descriptive column labels and preserve the sort direction on sortable headers. Keep sorting state in the parent when a server owns the result order. When rows are reconstructed after sorting or fetching, pass `rowKey={(row) => row.id}` so cells retain their identity.

The default `responsive="cards"` layout stacks labelled values on narrow screens. Use `responsive="scroll"` when preserving the column comparison is more important than removing horizontal scrolling.

Controlled selection requires `rowKey`, a `selectedKeys` set, and `onSelectedKeysChange`. Supply localized `selectAllLabel` and `selectRowLabel` text. The select-all control reports a mixed state when only some available rows are selected. Disabled rows do not change through row or select-all controls.

Give each row action a label that includes the record name when nearby text does not provide it. Table does not paginate or virtualize records.

<h2 id="tokens">Tokens and style hooks</h2>

Table uses card, chrome, control, and selected layers with table geometry, text, border, radius, focus, and motion tokens. Cell snippets should use the same semantic variables.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `caption` | `string` | prop | No | `undefined` | Table caption. |
| `captionVisuallyHidden` | `boolean` | prop | No | `false` | Visually hides the caption while keeping it available to assistive technology. |
| `cell` | `Snippet<[TableCellArgs<Row>]>` | snippet | No | `undefined` | Custom cell render. Falls back to `String(row[column.key])` when omitted. |
| `columns` | `TableColumn[]` | prop | Yes | - | Column definitions, left to right. A trailing action cell is appended when `rowAction` is set. |
| `empty` | `Snippet` | snippet | No | `undefined` | Fallback when `rows` is empty and not loading. Defaults to a simple `EmptyState`. |
| `loading` | `boolean` | prop | No | `false` | Replace the body with shimmering skeleton rows. |
| `loadingRows` | `number` | prop | No | `5` | Skeleton row count while `loading`. |
| `onSortByChange` | `(sort: TableSort) => void` | callback | No | `undefined` | Fired when a sortable header is clicked. Receives the newly-resolved sort state, so consumers can sort without binding `sortBy`. |
| `responsive` | `"cards" \| "scroll"` | prop | No | `'cards'` | Narrow-screen layout. Defaults to `cards`. |
| `rowAction` | `Snippet<[TableRowArgs<Row>]>` | snippet | No | `undefined` | Trailing per-row action cell, e.g. a `Menu` trigger. |
| `rowKey` | `TableRowKey<Row>` | prop | No | `undefined` | Stable primitive identity for reconstructed rows. Defaults to the row object's identity. |
| `rows` | `Row[]` | prop | Yes | - | Row records. Each cell reads `row[column.key]` unless `cell` overrides it. |
| `selection` | `TableSelection<Row> \| undefined` | prop | No | `undefined` | Controlled row-selection state. |
| `sortBy` | `TableSort` | binding | No | `undefined` | Active sort — bindable. Drives the header chevron. |

## Related

- [Eyebrow](/docs/components/eyebrow): Tracked label used above headings.
- [Avatar](/docs/components/avatar): Identity image or fallback with an optional status marker.
- [CodeBlock](/docs/components/code-block): Read-only code surface with copy support.


---

# Pagination

Controlled pagination with item range and edge controls.

Use Pagination when a long result set is split into stable pages and readers need direct navigation.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `disabled` | `boolean` | prop | No | `false` | No additional description. |
| `firstPageLabel` | `string` | prop | No | `'First page'` | Accessible name for the first-page control. |
| `formatSummary` | `(from: number, to: number, total: number) => string` | callback | No | `(from, to, count) => `${from.toLocaleString()}–${to.toLocaleString()} of ${count.toLocaleString()}`` | Localise the summary; the kit ships an English default. |
| `label` | `string` | prop | No | `'Pagination'` | No additional description. |
| `lastPageLabel` | `string` | prop | No | `'Last page'` | Accessible name for the last-page control. |
| `nextPageLabel` | `string` | prop | No | `'Next page'` | Accessible name for the next-page control. |
| `onPageChange` | `(page: number) => void` | callback | No | `undefined` | No additional description. |
| `page` | `number` | binding | No | `1` | Current page, 1-based. Two-way bindable. |
| `pageSize` | `number` | prop | No | `50` | Items per page. |
| `previousPageLabel` | `string` | prop | No | `'Previous page'` | Accessible name for the previous-page control. |
| `showFirstLast` | `boolean` | prop | No | `true` | Render first/last jump controls. |
| `siblingCount` | `number` | prop | No | `1` | Page buttons kept on each side of the current one. |
| `size` | `ControlSize` | prop | No | `'md'` | No additional description. |
| `summary` | `boolean` | prop | No | `true` | Render the `1–50 of 1,234` line. |
| `total` | `number` | prop | Yes | - | Total item count. Drives the page count and the summary. |

## Related

- [Link](/docs/components/link): Styled native link for body and navigation text.
- [Segmented](/docs/components/segmented): Single-select segmented control.
- [Tabs](/docs/components/tabs): Panelled tabs with underline and pill presentations.

---

# Chart

Accessible SVG line or area chart with tooltip and data table.

Use Chart for a labelled trend with one or more stable series when readers need axes, values, and accessible source data.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `curve` | `ChartCurve` | prop | No | `'monotone'` | `monotone` is smooth without overshooting the data. |
| `directLabels` | `boolean` | prop | No | `false` | End-of-line labels — the relief channel for the sub-3:1 palette slots. |
| `empty` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `height` | `number` | prop | No | `280` | Width is responsive; height is fixed. |
| `label` | `string` | prop | No | `undefined` | Accessible name. Also captions the offscreen data table. |
| `loading` | `boolean` | prop | No | `false` | No additional description. |
| `onPointHover` | `(hover: ChartHover \| null) => void` | callback | No | `undefined` | Fires on crosshair move and on leave, for cross-component sync. |
| `series` | `ChartSeries[]` | prop | Yes | - | At least one series, in a stable key order — the order pins the palette. |
| `showGrid` | `boolean` | prop | No | `true` | No additional description. |
| `showLegend` | `boolean` | prop | No | `undefined` | Defaults on for ≥2 series; a single series is named by its own title. |
| `showTooltip` | `boolean` | prop | No | `true` | No additional description. |
| `showXAxis` | `boolean` | prop | No | `true` | No additional description. |
| `showYAxis` | `boolean` | prop | No | `true` | No additional description. |
| `size` | `ControlSize` | prop | No | `'md'` | No additional description. |
| `tickFormatX` | `(x: number) => string` | callback | No | `undefined` | Epoch ms → label. The caller localizes. |
| `tickFormatY` | `(y: number) => string` | callback | No | `compactNumber` | No additional description. |
| `tooltipContent` | `Snippet<[ChartHover]>` | snippet | No | `undefined` | No additional description. |
| `variant` | `ChartVariant` | prop | No | `'area'` | `area` is `line` plus a gradient fill down to the baseline. |
| `xScale` | `ChartXScale` | prop | No | `'time'` | No additional description. |
| `xTicks` | `number` | prop | No | `6` | No additional description. |
| `yMax` | `number` | prop | No | `undefined` | No additional description. |
| `yMin` | `number` | prop | No | `undefined` | No additional description. |
| `yTicks` | `number` | prop | No | `5` | No additional description. |

## Related

- [Sparkline](/docs/components/sparkline): Compact inline line or area trend.

---

# Sparkline

Compact inline line or area trend.

Choose Sparkline for a compact trend beside a metric when full axes and detailed comparison are unnecessary.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `color` | `string` | prop | No | `'var(--bd-series-1)'` | Any token or hex. |
| `curve` | `SparklineCurve` | prop | No | `'monotone'` | No additional description. |
| `height` | `number` | prop | No | `24` | No additional description. |
| `label` | `string` | prop | No | `undefined` | Omit when the sparkline sits beside a labelled value; then it is decorative. |
| `points` | `SparklinePoint[]` | prop | Yes | - | Bare numbers are indexed by position. |
| `showLast` | `boolean` | prop | No | `false` | Mark the final point with a dot. |
| `strokeWidth` | `number` | prop | No | `1.5` | No additional description. |
| `variant` | `SparklineVariant` | prop | No | `'line'` | No additional description. |
| `width` | `number` | prop | No | `96` | Requested intrinsic width in pixels is an upper bound; the SVG shrinks to its container while preserving its viewBox aspect ratio. |
| `yMax` | `number` | prop | No | `undefined` | No additional description. |
| `yMin` | `number` | prop | No | `undefined` | No additional description. |

## Related

- [Chart](/docs/components/chart): Accessible SVG line or area chart with tooltip and data table.

---

# ActivityStatus

Compact agent activity status with elapsed time, task progress, and one live announcement.

Use ActivityStatus for one observable operation. Supply visible status text. Let only one owner announce each transition.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `activityId` | `string` | prop | Yes | - | No additional description. |
| `announcement` | `string` | prop | No | `undefined` | Message for the owned live region. An empty value keeps the region mounted without announcing. |
| `elapsed` | `string` | prop | No | `undefined` | No additional description. |
| `label` | `string` | prop | Yes | - | No additional description. |
| `politeness` | `'polite' \| 'assertive'` | prop | No | `'polite'` | No additional description. |
| `progress` | `ActivityProgress` | prop | No | `undefined` | No additional description. |
| `status` | `AgentStatus` | prop | Yes | - | No additional description. |
| `statusLabel` | `string` | prop | Yes | - | No additional description. |

## Related

- [AgentTrace](/docs/components/agent-trace): Controlled disclosure of observable stages, searches, tools, files, and checks.
- [AgentResponse](/docs/components/agent-response): Assistant result with consumer-rendered content, streaming state, sources, actions, and follow-up prompts.
- [ApprovalRequest](/docs/components/approval-request): Explicit approve-or-reject workflow with consequences, optional editing, and separate decision submission.

---

# AgentTrace

AgentTrace is a controlled disclosure for observable agent operations and their current result.

Use AgentTrace for observable searches, tools, files, and checks. Never expose private reasoning. Keep the plain collapsed summary useful.

<h2 id="purpose">Purpose</h2>

Use AgentTrace for searches, tool calls, files, checks, and other observable work. Do not expose hidden reasoning, private chain-of-thought, or unsupported explanations of model behavior.

<h2 id="anatomy">Summary and items</h2>

Keep `summary` useful while the trace is closed. It should report the current result, count, duration, or next blocked step. Do not require expansion to understand whether work succeeded.

Give the trace and every item a stable ID. Supply visible `statusLabel` text for each state. Descriptions can report an operation and its evidence, but must not imitate internal reasoning.

Control disclosure through `open` and `onOpenChange`. Preserve failed and blocked items until the user retries or starts a new run.

<h2 id="announcements">Announcements</h2>

Pass a non-empty `announcement` for one completed status transition. AgentTrace keeps an empty live region mounted when no message is present. An empty message announces nothing. Do not announce each streamed token or repeat the same status from a parent live region.

<h2 id="tokens">Tokens and style hooks</h2>

AgentTrace uses status, text, mono type, border, spacing, and motion tokens. Its detail disclosure uses the plain core Collapsible presentation. The trace rail appears only inside expanded details.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `announcement` | `string` | prop | No | `undefined` | Message for the owned live region. An empty value keeps the region mounted without announcing. |
| `emptyMessage` | `string` | prop | No | `undefined` | No additional description. |
| `items` | `readonly AgentTraceItem[]` | prop | Yes | - | No additional description. |
| `onOpenChange` | `(open: boolean) => void` | callback | No | `undefined` | No additional description. |
| `open` | `boolean` | binding | No | `false` | No additional description. |
| `status` | `AgentStatus` | prop | Yes | - | No additional description. |
| `statusLabel` | `string` | prop | Yes | - | No additional description. |
| `summary` | `string` | prop | Yes | - | No additional description. |
| `title` | `string` | prop | Yes | - | No additional description. |
| `traceId` | `string` | prop | Yes | - | No additional description. |

## Related

- [ActivityStatus](/docs/components/activity-status): Compact agent activity status with elapsed time, task progress, and one live announcement.
- [AgentResponse](/docs/components/agent-response): Assistant result with consumer-rendered content, streaming state, sources, actions, and follow-up prompts.
- [ApprovalRequest](/docs/components/approval-request): Explicit approve-or-reject workflow with consequences, optional editing, and separate decision submission.


---

# AgentResponse

Assistant result with consumer-rendered content, streaming state, sources, actions, and follow-up prompts.

Render and sanitize response content in application code. Place sources beside the claims they support. Label every supplied source, action, and follow-up collection. Announce completed semantic chunks, not each streamed token.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `actions` | `readonly AgentResponseAction[] \| undefined` | prop | No | `[]` | No additional description. |
| `actionsLabel` | `string` | prop | No | `undefined` | No additional description. |
| `announcement` | `string` | prop | No | `undefined` | A completed semantic chunk for the owned live region. Do not pass token-by-token content. |
| `content` | `Snippet` | snippet | Yes | - | Rich response content. The consumer controls all parsing and rendering. |
| `followups` | `readonly AgentResponseFollowup[] \| undefined` | prop | No | `[]` | No additional description. |
| `followupsLabel` | `string` | prop | No | `undefined` | No additional description. |
| `label` | `string` | prop | Yes | - | Accessible name for the response article. |
| `onSourcesOpenChange` | `(open: boolean) => void` | callback | No | `undefined` | No additional description. |
| `responseId` | `string` | prop | Yes | - | No additional description. |
| `sources` | `readonly AgentSource[] \| undefined` | prop | No | `[]` | No additional description. |
| `sourcesLabel` | `string` | prop | No | `undefined` | Visible disclosure text for `sources`. |
| `sourcesOpen` | `boolean` | binding | No | `false` | No additional description. |
| `streaming` | `boolean` | prop | No | `false` | No additional description. |
| `streamingLabel` | `string` | prop | No | `undefined` | Visible text for the streaming state. |

## Related

- [ActivityStatus](/docs/components/activity-status): Compact agent activity status with elapsed time, task progress, and one live announcement.
- [AgentTrace](/docs/components/agent-trace): Controlled disclosure of observable stages, searches, tools, files, and checks.
- [ApprovalRequest](/docs/components/approval-request): Explicit approve-or-reject workflow with consequences, optional editing, and separate decision submission.

---

# ApprovalRequest

ApprovalRequest presents a consequential decision with details, consequences, explicit choices, and a separate submission action.

State the consequence before the choice. Selecting approve or reject only updates the decision. Use a full warning border for a blocked request. Require explicit submission and keep the terminal result visible.

<h2 id="purpose">Purpose</h2>

Use ApprovalRequest when an agent needs human authorization before consequential work. Do not use it as a passive status card or an automatic confirmation.

<h2 id="anatomy">Decision flow</h2>

State the consequence before the decision controls. A radio choice updates `decision` but does not call `onSubmit`. The user must activate the submit action to approve or reject the request.

ApprovalRequest does not render a form. Its submit action uses `type="button"` and calls `onSubmit` only after a valid choice. The component can sit inside a consumer-owned form without causing a nested form or an implicit form submission.

Use `onEdit` when the user can change the proposed operation before deciding. Do not treat editing as approval. Keep request details specific enough to identify the target, scope, and expected side effects.

Only queued or blocked requests accept a decision. Application state owns the transition after submission and must keep the terminal result visible. A failed result must state whether any changes were applied.

<h2 id="focus-and-announcements">Focus and announcements</h2>

Set `focusHeading` when a newly active request needs focus. Do not move focus on routine data refreshes. Supply one completed status announcement and avoid a duplicate live region around the component.

<h2 id="tokens">Tokens and style hooks</h2>

ApprovalRequest uses a complete warning border for blocked requests and a complete danger border for failed requests. The consequence remains on a quiet inset layer. The component also uses display type, mono detail, radius, spacing, and focus tokens.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `announcement` | `string` | prop | No | `undefined` | Message for the owned live region. |
| `approveLabel` | `string` | prop | Yes | - | No additional description. |
| `busy` | `boolean` | prop | No | `false` | No additional description. |
| `decision` | `ApprovalDecision \| null` | binding | No | `null` | No additional description. |
| `decisionLabel` | `string` | prop | Yes | - | No additional description. |
| `disabled` | `boolean` | prop | No | `false` | No additional description. |
| `editLabel` | `string` | prop | No | `undefined` | No additional description. |
| `focusHeading` | `boolean` | prop | No | `false` | Moves focus to the decision heading when the request becomes active. |
| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | prop | No | `2` | Heading level for the request title. Nested headings use the next level, capped at 6. |
| `onDecisionChange` | `(decision: ApprovalDecision) => void` | callback | No | `undefined` | No additional description. |
| `onEdit` | `(requestId: string) => void` | callback | No | `undefined` | No additional description. |
| `onSubmit` | `(requestId: string, decision: ApprovalDecision) => void` | callback | Yes | - | No additional description. |
| `rejectLabel` | `string` | prop | Yes | - | No additional description. |
| `request` | `ApprovalRequestData` | prop | Yes | - | No additional description. |
| `submitLabel` | `string` | prop | Yes | - | No additional description. |

## Related

- [ActivityStatus](/docs/components/activity-status): Compact agent activity status with elapsed time, task progress, and one live announcement.
- [AgentTrace](/docs/components/agent-trace): Controlled disclosure of observable stages, searches, tools, files, and checks.
- [AgentResponse](/docs/components/agent-response): Assistant result with consumer-rendered content, streaming state, sources, actions, and follow-up prompts.


---

# ToolCallList

Controlled tool-call disclosures with status, duration, inputs, output, and changed artifacts.

Use ToolCallList for observable tool activity. Keep each closed row on one scan line when content fits. Wrap long technical values in narrow containers. Show inputs, output, and changed artifacts after expansion. On failure, state whether side effects occurred.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `announcement` | `string` | prop | No | `undefined` | No additional description. |
| `calls` | `readonly ToolCall[]` | prop | Yes | - | No additional description. |
| `emptyMessage` | `string` | prop | No | `undefined` | No additional description. |
| `expandedIds` | `string[]` | binding | No | `[]` | No additional description. |
| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | prop | No | `2` | Heading level for the list label. Nested headings use the next level, capped at 6. |
| `label` | `string` | prop | Yes | - | No additional description. |
| `onExpandedIdsChange` | `(ids: string[]) => void` | callback | No | `undefined` | No additional description. |

## Related

- [ActivityStatus](/docs/components/activity-status): Compact agent activity status with elapsed time, task progress, and one live announcement.
- [AgentTrace](/docs/components/agent-trace): Controlled disclosure of observable stages, searches, tools, files, and checks.
- [AgentResponse](/docs/components/agent-response): Assistant result with consumer-rendered content, streaming state, sources, actions, and follow-up prompts.

---

# AgentTaskList

Ordered agent task plan with status, summaries, and controlled detail disclosures.

Use AgentTaskList for a consumer-owned execution plan. Keep each closed task on one scan line when content fits, with visible status text. Wrap long content in narrow containers. Preserve blocked and failed tasks until the plan changes.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `announcement` | `string` | prop | No | `undefined` | No additional description. |
| `emptyMessage` | `string` | prop | No | `undefined` | No additional description. |
| `expandedIds` | `string[]` | binding | No | `[]` | No additional description. |
| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | prop | No | `2` | Heading level for the list label. Nested headings use the next level, capped at 6. |
| `label` | `string` | prop | Yes | - | No additional description. |
| `onExpandedIdsChange` | `(ids: string[]) => void` | callback | No | `undefined` | No additional description. |
| `tasks` | `readonly AgentTask[]` | prop | Yes | - | No additional description. |

## Related

- [ActivityStatus](/docs/components/activity-status): Compact agent activity status with elapsed time, task progress, and one live announcement.
- [AgentTrace](/docs/components/agent-trace): Controlled disclosure of observable stages, searches, tools, files, and checks.
- [AgentResponse](/docs/components/agent-response): Assistant result with consumer-rendered content, streaming state, sources, actions, and follow-up prompts.

---

# Conversation

Accessible conversation log with optional stick-to-bottom behavior and a jump-to-latest action.

Use Conversation as the named scrollable log around Message entries. Keep transcript announcements off. Announce completed updates through the component that owns each status.

## API

The package declarations define these public members.

### Inherited prop contracts

- `Omit<HTMLAttributes<HTMLDivElement>, 'children'>` — Props from this native base are accepted except the listed members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `children` | `Snippet` | snippet | Yes | - | No additional description. |
| `jumpToLatestLabel` | `string` | prop | No | `undefined` | Text for the jump action. Omit this text to hide the action. |
| `label` | `string` | prop | Yes | - | Accessible name for the conversation log. |
| `onStickToBottomChange` | `(stickToBottom: boolean) => void` | callback | No | `undefined` | No additional description. |
| `stickToBottom` | `boolean` | binding | No | `false` | Follow new content until the user scrolls away from the latest item. |

## Related

- [ActivityStatus](/docs/components/activity-status): Compact agent activity status with elapsed time, task progress, and one live announcement.
- [AgentTrace](/docs/components/agent-trace): Controlled disclosure of observable stages, searches, tools, files, and checks.
- [AgentResponse](/docs/components/agent-response): Assistant result with consumer-rendered content, streaming state, sources, actions, and follow-up prompts.

---

# Message

Presentation for user, assistant, tool, and system messages with consumer-rendered content and actions.

Use Message to identify the author or event role with a required label. Render rich content and actions through consumer-owned snippets. Keep tool and system output distinct from assistant prose.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `actions` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `avatar` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `content` | `Snippet` | snippet | Yes | - | No additional description. |
| `label` | `string` | prop | Yes | - | Visible and accessible author or event label. |
| `messageId` | `string` | prop | Yes | - | No additional description. |
| `metadata` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `role` | `MessageRole` | prop | Yes | - | No additional description. |

## Related

- [ActivityStatus](/docs/components/activity-status): Compact agent activity status with elapsed time, task progress, and one live announcement.
- [AgentTrace](/docs/components/agent-trace): Controlled disclosure of observable stages, searches, tools, files, and checks.
- [AgentResponse](/docs/components/agent-response): Assistant result with consumer-rendered content, streaming state, sources, actions, and follow-up prompts.

---

# PromptBar

PromptBar is a controlled prompt composer that switches between compact and expanded layouts.

Use PromptBar as a controlled composer. Application code owns uploads, attachment opening, dictation, transcription, and execution. Use stable IDs for context and commands. The bar switches between compact and expanded layouts by itself. Do not force a layout from the outside. Set `submitOnEnter` deliberately. Keep stop available while work is busy. Do not execute work when context, command, attachment, or policy selection changes.

<h2 id="purpose">Purpose</h2>

Use PromptBar when prompt controls must share one keyboard, layout, and motion contract. Use Textarea for ordinary multiline input.

<h2 id="anatomy">Control boundary</h2>

PromptBar uses compact mode for one line without tokens. It switches to expanded mode when text needs multiple lines or a token exists. PromptBar always measures wrapping at the compact input width, even after it expands. It measures again when the container width changes.

The `shape` prop accepts `rounded` or `pill`. A pill changes to the panel radius in expanded mode.

Add context and submit or stop always render. Attach, policy, measurement, and dictation controls render only when the consumer supplies their data or callbacks.

The policy control uses a menu-style select trigger. It shows each policy label, optional description, disabled state, and selected state. Typeahead works while the trigger is closed. Keyboard navigation keeps the highlighted policy visible in long lists.

Application code owns uploads, audio capture, transcription, persistence, and execution. PromptBar reports callbacks and renders the supplied state.

Use `onOpenAttachment` only with a localized `openAttachment` label. The controlled `transcribing` state also requires its visible status label.

Keep context as stable IDs in `selectedContextIds`. Keep attachments as separate records. A command inserts its consumer-owned `insertText`.

Changing context, a command, or an execution policy must not start work. Keep stop available during `busy` when the operation can stop safely.

<h2 id="keyboard">Keyboard and input</h2>

The textarea keeps focus while the anchored suggestion panel is open. Arrow keys move through enabled suggestions without changing their stable IDs. Enter or Tab selects the active enabled suggestion. Tab closes the panel without selection when no enabled suggestion is active. Escape closes the panel.

`submitOnEnter` defaults to `true`. Enter submits, while Shift+Enter inserts a line break. Set `submitOnEnter={false}` when Enter must always insert a line break. IME composition does not select a suggestion or submit a prompt.

Supply the complete localized `labels` object. Give each context item, command, attachment, and execution policy a stable ID.

Changing the controlled `value` outside PromptBar closes the suggestion panel. The next input or selection recomputes the inline trigger. Setting `busy` or `disabled` closes the suggestion and policy panels. These states also block suggestion and policy changes.

<h2 id="tokens">Tokens and style hooks</h2>

PromptBar uses card, control, floating, and selected layers. Height, cluster, and radius changes use `--bd-motion-base`.

The rounded shape uses `--bd-r-card`. The compact pill uses token-derived control geometry and changes to `--bd-r-panel` when expanded. The policy trigger uses `--bd-r-btn`. Reduced motion disables layout and panel animation.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `attachments` | `readonly PromptBarAttachment[]` | prop | No | `[]` | No additional description. |
| `busy` | `boolean` | prop | No | `false` | No additional description. |
| `commands` | `readonly PromptBarCommand[]` | prop | No | `[]` | No additional description. |
| `contextItems` | `readonly PromptBarContextItem[]` | prop | No | `[]` | No additional description. |
| `disabled` | `boolean` | prop | No | `false` | No additional description. |
| `executionPolicies` | `readonly PromptBarExecutionPolicy[]` | prop | No | `[]` | No additional description. |
| `labels` | `PromptBarLabels \| (PromptBarLabels & { openAttachment: (attachment: PromptBarAttachment) => string; }) \| PromptBarLabels & { transcribing: string; }` | prop | Yes | - | No additional description. |
| `listening` | `boolean` | binding | No | `false` | No additional description. |
| `maxRows` | `number` | prop | No | `6` | No additional description. |
| `measurement` | `PromptBarMeasurement` | prop | No | `undefined` | No additional description. |
| `onAddAttachment` | `() => void` | callback | No | `undefined` | No additional description. |
| `onListeningChange` | `(listening: boolean) => void` | callback | No | `undefined` | No additional description. |
| `onOpenAttachment` | `((attachment: PromptBarAttachment) => void) \| undefined` | callback | No | `undefined` | No additional description. |
| `onPolicyChange` | `(policy: PromptBarExecutionPolicy) => void` | callback | No | `undefined` | No additional description. |
| `onRemoveAttachment` | `(attachment: PromptBarAttachment) => void` | callback | No | `undefined` | No additional description. |
| `onRemoveContext` | `(item: PromptBarContextItem) => void` | callback | No | `undefined` | No additional description. |
| `onSelectCommand` | `(command: PromptBarCommand) => void` | callback | No | `undefined` | No additional description. |
| `onSelectContext` | `(item: PromptBarContextItem) => void` | callback | No | `undefined` | No additional description. |
| `onStop` | `() => void` | callback | No | `undefined` | No additional description. |
| `onSubmit` | `(detail: PromptBarSubmitDetail) => void` | callback | No | `undefined` | No additional description. |
| `selectedContextIds` | `string[]` | binding | No | `[]` | No additional description. |
| `selectedPolicyId` | `string` | binding | No | `''` | No additional description. |
| `shape` | `'rounded' \| 'pill'` | prop | No | `'rounded'` | No additional description. |
| `submitOnEnter` | `boolean` | prop | No | `true` | Set to false when Enter must insert a newline instead of submitting. |
| `transcribing` | `boolean \| false \| undefined` | prop | No | `false` | Controlled state for speech that is being converted to text. |
| `value` | `string` | binding | No | `''` | No additional description. |

## Related

- [ActivityStatus](/docs/components/activity-status): Compact agent activity status with elapsed time, task progress, and one live announcement.
- [AgentTrace](/docs/components/agent-trace): Controlled disclosure of observable stages, searches, tools, files, and checks.
- [AgentResponse](/docs/components/agent-response): Assistant result with consumer-rendered content, streaming state, sources, actions, and follow-up prompts.


---

# Recommendation

Agent proposal with rationale, explained confidence, evidence, alternatives, and explicit accept or reject actions.

Use Recommendation for a proposal that needs a decision. Explain the evidence or criterion behind confidence. Keep evidence and alternatives as divided rows. Place confidence beside the actions. Set `actionable` only when accept and reject are valid. Use `pendingAction` to identify the pending decision. The deprecated `busy` prop represents only a pending accept action.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `acceptLabel` | `string` | prop | Yes | - | No additional description. |
| `announcement` | `string` | prop | No | `undefined` | Message for the owned live region. |
| `busy` | `boolean` | prop | No | `false` | Deprecated compatibility prop for a pending accept action. Use `pendingAction`. |
| `disabled` | `boolean` | prop | No | `false` | No additional description. |
| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | prop | No | `2` | Heading level for the title. Nested headings use the next level, capped at 6. |
| `onAccept` | `(recommendationId: string) => void` | callback | Yes | - | No additional description. |
| `onReject` | `(recommendationId: string) => void` | callback | Yes | - | No additional description. |
| `pendingAction` | `RecommendationPendingAction` | prop | No | `undefined` | Identifies the action that is waiting for a consumer-owned result. |
| `recommendation` | `RecommendationData` | prop | Yes | - | No additional description. |
| `rejectLabel` | `string` | prop | Yes | - | No additional description. |

## Related

- [ActivityStatus](/docs/components/activity-status): Compact agent activity status with elapsed time, task progress, and one live announcement.
- [AgentTrace](/docs/components/agent-trace): Controlled disclosure of observable stages, searches, tools, files, and checks.
- [AgentResponse](/docs/components/agent-response): Assistant result with consumer-rendered content, streaming state, sources, actions, and follow-up prompts.

---

# ContextList

Retrieved context records with source metadata, state, and optional open or remove actions.

Use ContextList for a named set of evidence or prompt context. Show source type, location, size, and state when available. Keep open and remove actions explicit. Announce each semantic state change once.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `announcement` | `string` | prop | No | `undefined` | Consumer-owned text for one semantic state change. |
| `empty` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `items` | `readonly ContextItem[]` | prop | Yes | - | No additional description. |
| `label` | `string` | prop | Yes | - | Accessible name for the context list. |
| `onOpen` | `(item: ContextItem) => void` | callback | No | `undefined` | No additional description. |
| `onRemove` | `(item: ContextItem) => void` | callback | No | `undefined` | No additional description. |

## Related

- [ActivityStatus](/docs/components/activity-status): Compact agent activity status with elapsed time, task progress, and one live announcement.
- [AgentTrace](/docs/components/agent-trace): Controlled disclosure of observable stages, searches, tools, files, and checks.
- [AgentResponse](/docs/components/agent-response): Assistant result with consumer-rendered content, streaming state, sources, actions, and follow-up prompts.

---

# ChangeReview

Responsive before-and-after table for added, removed, modified, or unchanged values with per-item decisions.

Use ChangeReview before consequential data changes. Supply a text label for every change kind. Keep before and after values visible, and require an explicit item decision.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `items` | `readonly ChangeReviewItem[]` | prop | Yes | - | No additional description. |
| `labels` | `ChangeReviewLabels` | prop | Yes | - | No additional description. |
| `onAccept` | `(item: ChangeReviewItem) => void` | callback | Yes | - | No additional description. |
| `onEdit` | `(item: ChangeReviewItem) => void` | callback | Yes | - | No additional description. |
| `onReject` | `(item: ChangeReviewItem) => void` | callback | Yes | - | No additional description. |

## Related

- [ActivityStatus](/docs/components/activity-status): Compact agent activity status with elapsed time, task progress, and one live announcement.
- [AgentTrace](/docs/components/agent-trace): Controlled disclosure of observable stages, searches, tools, files, and checks.
- [AgentResponse](/docs/components/agent-response): Assistant result with consumer-rendered content, streaming state, sources, actions, and follow-up prompts.

---

# SelectionActions

Controlled workflow for applying an instruction to selected text, then accepting, rejecting, or retrying its result.

Use SelectionActions for a controlled edit to selected text. Keep the selection visible. Show a preview before acceptance. Preserve errors until retry or rejection. Supply one announcement for each semantic transition.

## API

The package declarations define these public members.

### Inherited prop contracts

- `Omit<HTMLAttributes<HTMLDivElement>, 'children'>` — Props from this native base are accepted except the listed members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `anchorId` | `string` | prop | No | `undefined` | ID of an optional consumer-owned anchor. This component does not position it. |
| `announcement` | `string` | prop | No | `undefined` | Consumer-owned text for one semantic workflow transition. |
| `error` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `instructions` | `readonly SelectionInstruction[]` | prop | Yes | - | No additional description. |
| `labels` | `SelectionActionsLabels` | prop | Yes | - | No additional description. |
| `onAccept` | `() => void` | callback | Yes | - | No additional description. |
| `onInstruction` | `(instruction: SelectionInstruction) => void` | callback | Yes | - | No additional description. |
| `onReject` | `() => void` | callback | Yes | - | No additional description. |
| `onRetry` | `() => void` | callback | Yes | - | No additional description. |
| `preview` | `Snippet` | snippet | No | `undefined` | No additional description. |
| `selectedText` | `string` | prop | Yes | - | Consumer-owned text. Empty text keeps the workflow out of the DOM. |
| `state` | `SelectionActionsState` | binding | No | `'idle'` | No additional description. |

## Related

- [ActivityStatus](/docs/components/activity-status): Compact agent activity status with elapsed time, task progress, and one live announcement.
- [AgentTrace](/docs/components/agent-trace): Controlled disclosure of observable stages, searches, tools, files, and checks.
- [AgentResponse](/docs/components/agent-response): Assistant result with consumer-rendered content, streaming state, sources, actions, and follow-up prompts.