# Inkbox design system: instructions for agents

Use this system to build Inkbox pages and interfaces from the user's brief. These instructions work with any agent that can read text and edit project files. The CLI is a local Node.js tool; no model account or agent-specific integration is needed for setup, discovery, installation or token checks.

## Start here

1. Read the project instructions and package.json. Identify the framework, package manager, stylesheet and import aliases. Use the user's requirements to decide whether to build new UI or restyle existing UI.
2. Read this guide, then the relevant component references. The library is at https://inkbox-ds.vercel.app/components. Plain text is at https://inkbox-ds.vercel.app/llms.txt; a complete copy is at https://inkbox-ds.vercel.app/llms-full.txt.
3. Reuse the library's components and variants. Do not recreate them from screenshots or guess their props. Each reference contains the actual exports, dependencies, working examples and source code.

## Install and prepare a project

Requires Node.js 20 or later. Run commands from the consuming project root, not the design-system repository.

```sh
npm install --save-dev github:anwarlemu/inkbox-brand-cli#release
npx inkbox-ds init
```

`npm install` installs the CLI only. `init` installs styles, fonts and agent instructions without converting existing components or creating conversion review tasks. It preserves other instructions already in the project. Inspect its warnings about a missing stylesheet or alias.

React components require React 19 or later, Tailwind CSS 4 and a working build. The installer follows components.json and TypeScript or JavaScript aliases; without aliases, it uses relative imports. Set up that framework first. Other frameworks can use the CSS tokens and styling guidance, but cannot render the React components.

For an existing interface that the user wants restyled, preview the explicit apply command:

```sh
npx -y github:anwarlemu/inkbox-brand-cli#release apply --dry-run
npx -y github:anwarlemu/inkbox-brand-cli#release apply
```

The apply command can adapt matching components, convert style values, and install agent rules and hooks. Color conversion is scoped to recognized components; unrelated palettes and artwork remain unchanged. The legacy bare command also converts styles; use explicit commands for setup and discovery. Subsequent runs resume review tasks. `--redo` repeats conversion. Review the diff and test existing behavior after conversion; a successful exit is not proof that the visual review is complete.

## Find, inspect and add components

```sh
npx inkbox-ds list --json
npx inkbox-ds show select
npx inkbox-ds show select --json
npx inkbox-ds add field select button --dry-run --json
npx inkbox-ds add field select button --json
```

The add command above is an example, not the list required for every page. Choose items from `list`. `show` is read-only and works offline using the registry bundled with the CLI. `show --json` returns source, examples, usage rules, exports, dependencies and links. Hooks and helper libraries are included in the JSON index.

`add` copies source files and their transitive dependencies, installs missing npm packages, and wires the theme. Existing files are kept. Use `--overwrite` only when intentionally replacing local component changes. Read the returned file list and warnings. Generated imports and target files follow components.json and the project alias configuration. Existing utility files are preserved; brand helpers use their own names.

For HTTP-only agents, fetch `https://inkbox-ds.vercel.app/r/index.json`, then `https://inkbox-ds.vercel.app/r/<name>.json` or `https://inkbox-ds.vercel.app/r/<name>.md`. Follow `requires` recursively. Each `files[].path` is relative to the source root; `files[].content` is the exact source. Each example lists its own `requires` and `packages`; install these too when using that example. Do not copy the example file as the component implementation. The CLI handles dependency ordering and theme installation for you.

The component reference states its source. `https://inkbox-ds.vercel.app/r/audit.json` records the reference basis for all components. Many components come straight from the console's design (Figma 427:2715); the rest extend its patterns because the design has no standalone equivalent (menus, calendars, charts). Each reference says which. Do not describe extensions as exact copies of the design.

## Compose the interface

- Follow the user's brief. For new pages, add the required content and behavior. When only restyling an existing page, preserve its content, links, order and behavior unless the user requests changes.
- Use component props and variants shown in the source. Read the named example functions before composing compound components. Keep client state inside a client component when using Next.js; imports of client components can still be rendered by server pages.
- Apply color tokens by component and state (primary action, field, panel, selected, invalid), using the component reference. The restyle installs the color definitions and Tailwind aliases, then maps identified uses. Preserve shared palette definitions, chart data, artwork, gradients and unrelated colors; do not replace every occurrence of a color or repurpose a shared variable. Leave ambiguous dynamic styling for review.
- `init`, `add` and restyle install the complete token set: colors, typography, spacing, layout, radii, shadows, blur and motion. Tailwind utilities read those variables, including fractional spacing, font weights and transition durations. Keep shared values in these tokens so edits remain consistent across components.
- Use design tokens for custom styles. `npx inkbox-ds tokens <term> --json` finds values; `npx inkbox-ds look <element-or-file> --json` explains styling by role. Use `var(--ds-*)` in CSS or the matching Tailwind utilities.
- Every word is Inter: 14px regular for body and controls, 20px regular for page and dialog titles, medium for tabs and card titles. Keys, hosts and IDs are IBM Plex Mono. Use the purple pill for the one main action, lilac wells and rails, 40px fields with the lilac-gray edge, Shadow/S on raised white panels and filled Phosphor glyphs. Do not introduce unrelated colors, shadows or type scales.
- Every icon is Phosphor: `@phosphor-icons/react` on the web (import from `@phosphor-icons/react/ssr` in server components), `phosphor-react-native` in native apps. Use the fill weight for navigation and object glyphs, regular for chevrons, close, plus and other line marks. Do not add another icon library or draw icons as inline SVG; `check` flags other icon packages.
- The installed stylesheet imports `./_inkbox-ds/brand.css` and `./_inkbox-ds/theme.css` beside the main stylesheet. `brand.css` includes tokens and base styles. Keep both imports after `@import "tailwindcss"`. Let the installer configure fonts; do not add a second font loader.
- Put one control in each Field. Field connects labels, help, errors and required state. Validation and submission belong to your form. For Select use `value` and `onValueChange`, SelectTrigger with SelectValue, and SelectContent with SelectItem; values must be non-empty strings. Give the root a `name` for FormData. Use `defaultValue` only for uncontrolled input.
- Connect every action to its intended behavior. Handle empty, loading, disabled, invalid, success and error states. Preserve keyboard controls, focus return, accessible names and native form semantics. Never present a preview's local demo action as a completed backend operation.
- Use the provided portal behavior. Surface is for an isolated preview or a scoped theme; ordinary pages do not need an extra Surface wrapper. Mount one Toaster per application when using toast notifications.

## Interaction and motion rules

- Rare triggers (onboarding, occasional feedback, celebrations) may use expressive animation. Keep it interruptible and respect reduced motion; never make an action wait for it. Repeated feedback is a frequent interaction, even if it is called a celebration.
- Tens of uses per day (hover effects, list navigation) get only subtle color, background, border-color, shadow or opacity changes, normally 150ms. Reuse one component variant and interaction treatment for each role.
- Hundreds of uses per day, keyboard shortcuts and command palette toggles have no animation, transition or smooth-scroll wait. Use `data-ds-motion="instant"` on custom high-frequency surfaces, including portaled content. The command components already do this.
- Show press feedback on pointer-down with `:active` (or `onPointerDown` for custom drawing), never after click/touch-up. Keep the actual action on accessible click/keyboard activation. Use `touch-action: manipulation` on ordinary controls to avoid the tap delay while preserving zoom.
- Keep dimensions, padding, gaps and font metrics identical across hover, focus and pressed states. Never scale a button or change font weight from 400 to 500/600 on interaction. Change visual styling instead.
- Buttons and compact controls use `rounded-pill`; cards use `rounded-dialog` (24px), including small cards and cards with footers. Multi-select fields also use 24px corners; their individual chips remain pills.
- All dropdown menus and popup panels use the shared 16px `rounded-panel` radius, including submenus, command palettes, date pickers, hover cards, tooltips, dialogs and toasts. Sheets and drawers use it on their exposed corners.
- Use shared components, size variants and spacing tokens. Equivalent sections share a gutter; equivalent controls share padding. Do not invent separate hover treatments or per-instance spacing for the same component role.
- Audit every debounce, timeout, transition wait and artificial latency. Update controlled inputs and local filtering immediately. Debounce only necessary network/background work, with immediate local feedback and stale-result cancellation. Never wait for an exit animation before accepting input or opening the next view.
- `check` reports UI timers for review. Remove artificial waits. For an essential nonblocking timer, put `// ds-latency: <specific reason>` immediately above the call, explaining what it delays and why typing/actions remain immediate. This documents an audit, not a general exemption for delayed input.
- Verify in a browser with motion enabled and reduced motion: hold a pointer down before release, type rapidly, toggle the command palette and shortcuts repeatedly, compare bounds and font weight before/after hover and press, and check consistent section/component padding. Static checks cannot establish actual usage frequency or timing by themselves.

## Verify before finishing

1. Run the consuming project's type checks, tests and production build.
2. Run `npx inkbox-ds check --json`. Exit 0 means no detected token or interaction violations; exit 1 means unresolved violations or a command error. Read the JSON result, fix the findings and rerun. Static checks do not replace accessibility and interaction testing.
3. Test every interaction with mouse and keyboard. Submit invalid and valid forms, choose options, open and close overlays, and test loading/error paths. Check desktop and phone widths, focus visibility, overflow and reduced-motion behavior.
4. Compare screenshots against the relevant library previews and reference. `npx inkbox-ds review http://localhost:3000 --any` can capture and review a running page. It requires playwright-core and Chromium. Automated scoring uses an available supported reviewer; if none is available, read the saved screenshots and report a manual review. Never claim an independent score that was not produced.
5. Report what changed, which checks passed, and any remaining limitations. If conversion left follow-up tasks, complete or report them explicitly.

## Instructions and hooks

`init` and conversion install AGENTS.md and a local `.ds/agent-guide.md`, plus supported agent instruction files and hook configuration. Agents that do not load those files automatically should read them explicitly. Hooks support Claude Code, Codex and Cursor when enabled by that tool; other agents run the CLI checks directly. Codex hook activation may require the user's `/hooks` trust step. No hook integration is required to use the components correctly.

Read-only commands: `guide`, `list`, `show`, `look`, `tokens`, `check` without `--fix`.
Commands that write project files: `init`, `add`, `apply`, the legacy bare conversion command, `check --fix`, and review/snapshot state updates. Use `--dry-run` with `init`, `add` or conversion to inspect planned writes. JSON goes to stdout and progress goes to stderr. Installation/build failures return a nonzero exit code.

## Project configuration and agent handoff

Start with `npx inkbox-ds info --json`, then `search <term> --json` and `view <names...> --json`. These commands are read-only. `show` and `inspect` remain aliases of `view`.

`add` respects components.json, inherited TypeScript or JavaScript aliases, the target stylesheet and the package manager. It emits JSX/JS when `tsx` is false, installs the theme and agent guidance, and preserves differing local files. Use `add <names...> --diff` to review changes before `--overwrite`. Use `--cwd <app>` from a repository root. For shared workspace packages, use the upstream installer described below.

`create --template vite --name <directory>` scaffolds a new app and installs brand components. `init` configures an existing app; `init button card` also adds components. `apply --dry-run --json` previews a requested conversion of existing styles. Do not run conversion to discover or install the library.

Portable skills are installed in `.agents/skills/inkbox-ds/SKILL.md` and `.claude/skills/inkbox-ds/SKILL.md`; the full guide is `.ds/agent-guide.md`. Read `add --view` or the installed source for imports resolved to this project's paths. The installed brand utility is separate from the application's existing `lib/utils` exports.

The standard shadcn registry is configured under `@inkbox-ds` in components.json. For workspace routing, install with `npx inkbox-ds shadcn add @inkbox-ds/theme @inkbox-ds/button`. Include the theme explicitly with upstream shadcn so existing font and color aliases are updated. Native `add` applies it automatically.

Advanced operations use pinned shadcn 4.22.1: `shadcn <args...>`, `mcp`, `registry`, `preset`, `migrate`, `eject`, and `build`. These need network access on first use and preserve upstream output formats. Native brand commands accept `--json`. Preset/base changes are upstream operations that may change the brand; use them only when requested. MCP configuration alone does not prove the agent host has loaded its server.

The explicit `apply` command scopes color conversion to recognized components and preserves unrelated artwork and shared palette data. The legacy bare-command conversion remains for compatibility; use `apply` for new restyling tasks.

# Inkbox theme
The Inkbox tokens and the Tailwind names that read them.

Install: npx inkbox-ds add theme
Requires: none
Packages: none
Exports: See source
Client boundary: not required by this entry file

## Usage



## Source

styles/tokens.css

```css
/* Written by inkbox-ds from its brand files. Do not edit; run the CLI again to update. */
:root {
	/* Core: deep purple ink, the action purple, the lilac wash, the pink accent, and white. */
	--ds-color-brand: #74629D;
	--ds-color-black: #000000;
	--ds-color-white: #FFFFFF;
	--ds-color-ink: #3E2A53;
	--ds-color-lilac: #F4F2F6;
	--ds-color-pink: #F9B1B5;
	/* The pink's dark partner: the glyph on a pink channel tile, and an agent handle in a table. */
	--ds-color-rose: #8C5659;
	/* An avatar's initial tile. */
	--ds-color-avatar: #5063B1;

	/* Surfaces: white panels on a white page; the lilac for the second rail, a selected row, a table's head and foot,
	   a field's well and a channel card. */
	--ds-color-bg-default: #FFFFFF;
	--ds-color-bg-page: #FFFFFF;
	--ds-color-bg-subtle: #F4F2F6;
	/* The lilac under the pointer or pressed: the wash a step deeper (not in the design; derived for hover). */
	--ds-color-bg-subtle-hover: #ECE9F0;
	--ds-color-bg-frame: #F4F2F6;
	--ds-color-bg-canvas: #F4F2F6;
	--ds-color-bg-tint: #F4F2F6;
	--ds-color-bg-brand: #74629D;
	--ds-color-bg-inverse: #3E2A53;
	--ds-color-bg-dark: #3E2A53;
	/* Code: the light editor theme of the event catalog (a gray head over an off-white body). */
	--ds-color-bg-code: #FFFFFE;
	--ds-color-bg-code-head: #F0F0F0;
	/* The page behind a dialog: the ink at 12 percent, over a light blur. */
	--ds-color-bg-scrim: rgb(62 42 83 / 0.12);
	/* A switch that is off, and a disabled control's fill. */
	--ds-color-bg-off: #B1ADBB;

	/* Text: the ink, and four lighter purples (secondary for body copy under a title, muted for table heads, dates and
	   descriptions, subtle for placeholders, faint for a close glyph); the action purple for links and labels. */
	--ds-color-text-default: #3E2A53;
	--ds-color-text-secondary: #70637E;
	--ds-color-text-muted: #998EA5;
	--ds-color-text-subtle: #9E94A9;
	--ds-color-text-nav: #3E2A53;
	--ds-color-text-faint: #BCB3C5;
	--ds-color-text-inverse: #FFFFFF;
	--ds-color-text-brand: #74629D;
	--ds-color-text-on-brand: #FFFFFF;
	--ds-color-text-label: #74629D;
	/* Icons: the ink for nav glyphs, a softer purple for row actions and empty-state orbits. */
	--ds-color-icon-default: #3E2A53;
	--ds-color-icon-secondary: #5B4C6A;
	/* Code: the editor theme's keys, strings, line numbers, braces and plain text. */
	--ds-color-code-key: #A31515;
	--ds-color-code-string: #0451A5;
	--ds-color-code-line: #237893;
	--ds-color-code-brace: #F8CC5E;
	--ds-color-code-text: #1A202C;
	--ds-color-code-punct: #0431FA;
	--ds-color-code-line-active: #0B216F;
	--ds-color-code-head-fg: #4A4A4A;
	/* The rest of the same editor theme (Light+), for code other than JSON: keywords, comments, numbers, functions,
	   types, markup tags and attributes. */
	--ds-color-code-keyword: #0000FF;
	--ds-color-code-comment: #008000;
	--ds-color-code-number: #098658;
	--ds-color-code-function: #795E26;
	--ds-color-code-type: #267F99;
	--ds-color-code-tag: #800000;
	--ds-color-code-attr: #E50000;

	/* Lines: a field's edge, the rail and header rules, and the two shared styles (Line/S Bottom under a table row,
	   Shadow/S's ring around a raised white panel). */
	--ds-color-border-default: #D2C9DB;
	--ds-color-border-subtle: #F3F1F5;
	--ds-color-border-strong: #B1ADBB;
	--ds-color-border-field: #D2C9DB;
	--ds-color-border-row: rgb(102 102 99 / 0.12);
	--ds-color-border-ring: rgb(23 47 41 / 0.12);
	/* Shadow/S's drop, for a raised panel drawn without box-shadow (a table body built from cells). */
	--ds-color-shadow-drop: rgb(23 47 41 / 0.08);
	--ds-color-border-brand: #74629D;
	--ds-color-border-pink: #F9B1B5;
	/* A code block's edge, its head's rule and its indent guides (the editor theme's gray). */
	--ds-color-border-code: #E0E0E0;
	--ds-color-wash-hover: rgb(62 42 83 / 0.04);
	--ds-color-ring-tint: rgb(116 98 157 / 0.24);

	/* Actions and states. The main action is the purple pill. */
	--ds-color-action-primary: #74629D;
	--ds-color-action-primary-hover: #67568E;
	--ds-color-action-primary-fg: #FFFFFF;
	--ds-color-focus-ring: #74629D;
	/* Success: the Included pill and its checks, and the Active status well. */
	--ds-color-status-success: #1CA721;
	--ds-color-status-success-bg: #C6F6D5;
	/* Warning: the copy-this-key banner (its fill, title ink, glyph and note). */
	--ds-color-status-warning: #8A581D;
	--ds-color-status-warning-bg: #F6E8C9;
	--ds-color-status-warning-fg: #4A2F0B;
	--ds-color-status-warning-muted: #8E7045;
	/* Danger: a field that failed (its edge and message) and the error glyph inside it. */
	--ds-color-status-danger: #BD5557;
	--ds-color-status-danger-strong: #A71C1F;
	/* Info: the zero-knowledge note (fill, ink, glyph), and the blue tag and status well. */
	--ds-color-status-info: #1C7390;
	--ds-color-status-info-bg: #C9EBF6;
	--ds-color-status-info-fg: #0D4152;
	--ds-color-tag-blue: #BEE3F8;
	--ds-color-tag-blue-fg: #2A4365;
	--ds-color-tag-purple: #E9D8FD;
	--ds-color-tag-purple-fg: #6D5C9B;
	--ds-color-tag-gray: #EDF2F7;
	--ds-color-chart-series-1: #74629D;
	--ds-color-chart-series-2: #F9B1B5;
	--ds-color-chart-series-3: #5063B1;
	--ds-color-chart-series-4: #1C7390;
	--ds-color-chart-series-5: #1CA721;

	/* Type: Inter for everything, IBM Plex Mono for keys, hosts and IDs, the system monospace in code blocks. Body copy is 14px regular; medium for
	   tabs and card titles; bold only for an empty state's title. No tracking. */
	--ds-font-sans: var(--font-inter, "Inter"), ui-sans-serif, system-ui, sans-serif;
	--ds-font-display: var(--font-inter, "Inter"), ui-sans-serif, system-ui, sans-serif;
	--ds-font-mono: var(--font-plex-mono, "IBM Plex Mono"), ui-monospace, SFMono-Regular, Menlo, monospace;
	/* Code blocks (the event catalog's JSON) use the system monospace, as the editor theme does. */
	--ds-font-code: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
	--ds-font-weight-regular: 400;
	--ds-font-weight-medium: 500;
	--ds-font-weight-semibold: 600;
	--ds-font-weight-bold: 700;
	--ds-font-weight-heading: 400;
	/* Page and dialog titles are 20px regular; an empty state's title 22px bold; the rest 11 to 16px. */
	--ds-text-display: 2rem;
	--ds-text-h1: 1.5rem;
	--ds-text-h2: 1.375rem;
	--ds-text-h3: 1.25rem;
	--ds-text-h4: 1rem;
	--ds-text-body-lg: 1rem;
	--ds-text-body: 0.875rem;
	--ds-text-body-sm: 0.8125rem;
	--ds-text-caption: 0.75rem;
	--ds-text-micro: 0.6875rem;
	--ds-leading-tight: 1.2;
	--ds-leading-heading: 1.4;
	--ds-leading-display: 1.25;
	--ds-leading-snug: 1.25;
	--ds-leading-body: 1.5;
	--ds-leading-relaxed: 1.6;
	--ds-leading-code: 1.5;
	--ds-tracking-normal: 0;
	/* Nothing is tracked; the engine's heading tracking resolves to none. */
	--ds-tracking-tight: 0;
	--ds-tracking-caps: 0.02em;

	/* Space (rem, so it follows the root); the design's spacing variables are 4, 8, 12, 16 and 24. */
	--ds-space-0: 0;
	--ds-space-px: 1px;
	--ds-space-0-5: 0.125rem;
	--ds-space-1: 0.25rem;
	--ds-space-1-5: 0.375rem;
	--ds-space-2: 0.5rem;
	--ds-space-2-5: 0.625rem;
	--ds-space-3: 0.75rem;
	--ds-space-3-5: 0.875rem;
	--ds-space-4: 1rem;
	--ds-space-5: 1.25rem;
	--ds-space-6: 1.5rem;
	--ds-space-7: 1.75rem;
	--ds-space-8: 2rem;
	--ds-space-9: 2.25rem;
	--ds-space-9-5: 2.375rem;
	--ds-space-10: 2.5rem;
	--ds-space-10-5: 2.625rem;
	--ds-space-12: 3rem;
	--ds-space-14: 3.5rem;
	--ds-space-16: 4rem;
	--ds-space-20: 5rem;
	--ds-space-24: 6rem;

	/* Layout: a 288px rail, a 288px second rail, a 64px page head with 24px gutters. */
	--ds-layout-column: 75rem;
	--ds-layout-gutter: 1.5rem;
	--ds-layout-text: 42.5rem;
	--ds-layout-heading: 42rem;
	--ds-layout-header: 4rem;
	--ds-layout-rail: 18rem;
	--ds-frame-column: min(100% - 2 * var(--ds-layout-gutter), var(--ds-layout-column));

	/* Shape: pill buttons and compact controls, 6px details, 8px tiles, 12px content panels,
	   16px popup panels, table heads and banners, and 24px cards and multi-select fields. */
	--ds-radius-xs: 0.375rem;
	--ds-radius-sm: 0.5rem;
	--ds-radius-control: 0.75rem;
	--ds-radius-panel: 1rem;
	--ds-radius-dialog: 1.5rem;
	--ds-radius-pill: 9999px;
	/* Shadow/S: a raised white panel (a selected tab, a table's body, a select, a menu): a 1px ring and a short drop. */
	--ds-shadow-s: 0 2px 4px rgb(23 47 41 / 0.08), 0 0 0 1px rgb(23 47 41 / 0.12);
	/* A card: the same raised panel. */
	--ds-shadow-card: 0 2px 4px rgb(23 47 41 / 0.08), 0 0 0 1px rgb(23 47 41 / 0.12);
	/* Line/S Bottom: the rule under a table row. */
	--ds-shadow-line: 0 1px 0 rgb(102 102 99 / 0.12);
	/* A floating panel (a menu, a popover, a toast): Shadow/S with a softer, longer drop. */
	--ds-shadow-floating: 0 0 0 1px rgb(23 47 41 / 0.12), 0 2px 4px rgb(23 47 41 / 0.08), 0 12px 24px -8px rgb(62 42 83 / 0.16);
	/* A dialog sits on the scrim with no drop of its own; a sheet gets one where it meets the page. */
	--ds-shadow-dialog: 0 24px 48px -16px rgb(62 42 83 / 0.16);
	--ds-shadow-knob: 0 1px 2px rgb(62 42 83 / 0.24), 0 0 0 0.5px rgb(62 42 83 / 0.12);
	--ds-shadow-focus: 0 0 0 3px rgb(116 98 157 / 0.24);
	--ds-blur-scrim: 4px;

	/* Motion: a strong ease-out for every hover, press and entrance; in-out only for what travels on screen (a tab
	   thumb, a switch knob). Never ease-in. */
	--ds-duration-fast: 150ms;
	--ds-duration-base: 200ms;
	--ds-duration-moderate: 250ms;
	--ds-duration-slow: 300ms;
	--ds-easing-out: cubic-bezier(0.23, 1, 0.32, 1);
	--ds-easing-in-out: cubic-bezier(0.77, 0, 0.175, 1);
	--ds-easing-drawer: cubic-bezier(0.32, 0.72, 0, 1);
}

```

styles/theme.css

```css
/* Written by inkbox-ds from its brand files. Do not edit; run the CLI again to update. */
@theme inline {
	--color-brand: var(--ds-color-brand);
	--color-black: var(--ds-color-black);
	--color-white: var(--ds-color-white);
	--color-primary: var(--ds-color-action-primary);
	--color-primary-hover: var(--ds-color-action-primary-hover);
	--color-on-primary: var(--ds-color-action-primary-fg);
	--color-focus-ring: var(--ds-color-focus-ring);
	--color-surface: var(--ds-color-bg-default);
	--color-surface-brand: var(--ds-color-bg-brand);
	--color-subtle: var(--ds-color-bg-subtle);
	--color-frame: var(--ds-color-bg-frame);
	--color-canvas: var(--ds-color-bg-canvas);
	--color-tint: var(--ds-color-bg-tint);
	--color-inverse: var(--ds-color-bg-inverse);
	--color-dark: var(--ds-color-bg-dark);
	--color-code: var(--ds-color-bg-code);
	--color-scrim: var(--ds-color-bg-scrim);
	--color-fg: var(--ds-color-text-default);
	--color-fg-secondary: var(--ds-color-text-secondary);
	--color-fg-muted: var(--ds-color-text-muted);
	--color-fg-subtle: var(--ds-color-text-subtle);
	--color-fg-faint: var(--ds-color-text-faint);
	--color-fg-nav: var(--ds-color-text-nav);
	--color-fg-inverse: var(--ds-color-text-inverse);
	--color-fg-brand: var(--ds-color-text-brand);
	--color-on-brand: var(--ds-color-text-on-brand);
	--color-line: var(--ds-color-border-default);
	--color-line-subtle: var(--ds-color-border-subtle);
	--color-line-strong: var(--ds-color-border-strong);
	--color-success: var(--ds-color-status-success);
	--color-warning: var(--ds-color-status-warning);
	--color-danger: var(--ds-color-status-danger);
	--color-ink: var(--ds-color-ink);
	--color-lilac: var(--ds-color-lilac);
	--color-pink: var(--ds-color-pink);
	--color-rose: var(--ds-color-rose);
	--color-avatar: var(--ds-color-avatar);
	--color-page: var(--ds-color-bg-page);
	--color-subtle-hover: var(--ds-color-bg-subtle-hover);
	--color-code-head: var(--ds-color-bg-code-head);
	--color-off: var(--ds-color-bg-off);
	--color-fg-label: var(--ds-color-text-label);
	--color-icon-default: var(--ds-color-icon-default);
	--color-icon-secondary: var(--ds-color-icon-secondary);
	--color-code-key: var(--ds-color-code-key);
	--color-code-string: var(--ds-color-code-string);
	--color-code-line: var(--ds-color-code-line);
	--color-code-brace: var(--ds-color-code-brace);
	--color-code-text: var(--ds-color-code-text);
	--color-code-punct: var(--ds-color-code-punct);
	--color-code-line-active: var(--ds-color-code-line-active);
	--color-code-head-fg: var(--ds-color-code-head-fg);
	--color-code-keyword: var(--ds-color-code-keyword);
	--color-code-comment: var(--ds-color-code-comment);
	--color-code-number: var(--ds-color-code-number);
	--color-code-function: var(--ds-color-code-function);
	--color-code-type: var(--ds-color-code-type);
	--color-code-tag: var(--ds-color-code-tag);
	--color-code-attr: var(--ds-color-code-attr);
	--color-line-field: var(--ds-color-border-field);
	--color-line-row: var(--ds-color-border-row);
	--color-line-ring: var(--ds-color-border-ring);
	--color-shadow-drop: var(--ds-color-shadow-drop);
	--color-line-brand: var(--ds-color-border-brand);
	--color-line-pink: var(--ds-color-border-pink);
	--color-line-code: var(--ds-color-border-code);
	--color-wash-hover: var(--ds-color-wash-hover);
	--color-ring-tint: var(--ds-color-ring-tint);
	--color-success-bg: var(--ds-color-status-success-bg);
	--color-warning-bg: var(--ds-color-status-warning-bg);
	--color-warning-fg: var(--ds-color-status-warning-fg);
	--color-warning-muted: var(--ds-color-status-warning-muted);
	--color-danger-strong: var(--ds-color-status-danger-strong);
	--color-info: var(--ds-color-status-info);
	--color-info-bg: var(--ds-color-status-info-bg);
	--color-info-fg: var(--ds-color-status-info-fg);
	--color-tag-blue: var(--ds-color-tag-blue);
	--color-tag-blue-fg: var(--ds-color-tag-blue-fg);
	--color-tag-purple: var(--ds-color-tag-purple);
	--color-tag-purple-fg: var(--ds-color-tag-purple-fg);
	--color-tag-gray: var(--ds-color-tag-gray);
	--color-series-1: var(--ds-color-chart-series-1);
	--color-series-2: var(--ds-color-chart-series-2);
	--color-series-3: var(--ds-color-chart-series-3);
	--color-series-4: var(--ds-color-chart-series-4);
	--color-series-5: var(--ds-color-chart-series-5);
	--font-sans: var(--ds-font-sans);
	--font-display: var(--ds-font-display);
	--font-mono: var(--ds-font-mono);
	--font-code: var(--ds-font-code);
	--font-weight-normal: var(--ds-font-weight-regular);
	--font-weight-medium: var(--ds-font-weight-medium);
	--font-weight-semibold: var(--ds-font-weight-semibold);
	--font-weight-bold: var(--ds-font-weight-bold);
	--font-weight-heading: var(--ds-font-weight-heading);
	--spacing: var(--ds-space-1);
	--spacing-0: var(--ds-space-0);
	--spacing-px: var(--ds-space-px);
	--spacing-0\.5: var(--ds-space-0-5);
	--spacing-1: var(--ds-space-1);
	--spacing-1\.5: var(--ds-space-1-5);
	--spacing-2: var(--ds-space-2);
	--spacing-2\.5: var(--ds-space-2-5);
	--spacing-3: var(--ds-space-3);
	--spacing-3\.5: var(--ds-space-3-5);
	--spacing-4: var(--ds-space-4);
	--spacing-5: var(--ds-space-5);
	--spacing-6: var(--ds-space-6);
	--spacing-7: var(--ds-space-7);
	--spacing-8: var(--ds-space-8);
	--spacing-9: var(--ds-space-9);
	--spacing-9\.5: var(--ds-space-9-5);
	--spacing-10: var(--ds-space-10);
	--spacing-10\.5: var(--ds-space-10-5);
	--spacing-12: var(--ds-space-12);
	--spacing-14: var(--ds-space-14);
	--spacing-16: var(--ds-space-16);
	--spacing-20: var(--ds-space-20);
	--spacing-24: var(--ds-space-24);
	--spacing-layout-column: var(--ds-layout-column);
	--spacing-layout-gutter: var(--ds-layout-gutter);
	--spacing-layout-text: var(--ds-layout-text);
	--spacing-layout-heading: var(--ds-layout-heading);
	--spacing-layout-header: var(--ds-layout-header);
	--spacing-layout-rail: var(--ds-layout-rail);
	--container-frame-column: var(--ds-frame-column);
	--blur-scrim: var(--ds-blur-scrim);
	--transition-duration-fast: var(--ds-duration-fast);
	--transition-duration-150: var(--ds-duration-fast);
	--transition-duration-base: var(--ds-duration-base);
	--transition-duration-200: var(--ds-duration-base);
	--transition-duration-moderate: var(--ds-duration-moderate);
	--transition-duration-250: var(--ds-duration-moderate);
	--transition-duration-slow: var(--ds-duration-slow);
	--transition-duration-300: var(--ds-duration-slow);
	--default-transition-duration: var(--ds-duration-fast);
	--default-transition-timing-function: var(--ds-easing-out);
	--text-display: var(--ds-text-display);
	--text-h1: var(--ds-text-h1);
	--text-h2: var(--ds-text-h2);
	--text-h3: var(--ds-text-h3);
	--text-h4: var(--ds-text-h4);
	--text-body-lg: var(--ds-text-body-lg);
	--text-body: var(--ds-text-body);
	--text-body-sm: var(--ds-text-body-sm);
	--text-caption: var(--ds-text-caption);
	--text-micro: var(--ds-text-micro);
	--leading-tight: var(--ds-leading-tight);
	--leading-heading: var(--ds-leading-heading);
	--leading-display: var(--ds-leading-display);
	--leading-snug: var(--ds-leading-snug);
	--leading-body: var(--ds-leading-body);
	--leading-relaxed: var(--ds-leading-relaxed);
	--leading-code: var(--ds-leading-code);
	--tracking-normal: var(--ds-tracking-normal);
	--tracking-tight: var(--ds-tracking-tight);
	--tracking-caps: var(--ds-tracking-caps);
	--radius-xs: var(--ds-radius-xs);
	--radius-sm: var(--ds-radius-sm);
	--radius-control: var(--ds-radius-control);
	--radius-panel: var(--ds-radius-panel);
	--radius-dialog: var(--ds-radius-dialog);
	--radius-pill: var(--ds-radius-pill);
	--shadow-s: var(--ds-shadow-s);
	--shadow-card: var(--ds-shadow-card);
	--shadow-line: var(--ds-shadow-line);
	--shadow-floating: var(--ds-shadow-floating);
	--shadow-dialog: var(--ds-shadow-dialog);
	--shadow-knob: var(--ds-shadow-knob);
	--shadow-focus: var(--ds-shadow-focus);
	--ease-out: var(--ds-easing-out);
	--ease-in-out: var(--ds-easing-in-out);
	--ease-drawer: var(--ds-easing-drawer);
}

@theme {
	--animate-pop-in: ds-pop-in var(--ds-duration-base) var(--ds-easing-out);
	--animate-pop-out: ds-pop-out var(--ds-duration-fast) var(--ds-easing-out) forwards;
	--animate-fade-in: ds-fade-in var(--ds-duration-fast) var(--ds-easing-out);
	--animate-fade-out: ds-fade-out var(--ds-duration-fast) var(--ds-easing-out) forwards;
	--animate-dialog-in: ds-dialog-in var(--ds-duration-moderate) var(--ds-easing-out);
	--animate-dialog-out: ds-dialog-out var(--ds-duration-fast) var(--ds-easing-out) forwards;
	--animate-sheet-in-right: ds-sheet-in-right var(--ds-duration-slow) var(--ds-easing-drawer);
	--animate-sheet-out-right: ds-sheet-out-right var(--ds-duration-base) var(--ds-easing-drawer) forwards;
	--animate-sheet-in-left: ds-sheet-in-left var(--ds-duration-slow) var(--ds-easing-drawer);
	--animate-sheet-out-left: ds-sheet-out-left var(--ds-duration-base) var(--ds-easing-drawer) forwards;
	--animate-sheet-in-top: ds-sheet-in-top var(--ds-duration-slow) var(--ds-easing-drawer);
	--animate-sheet-out-top: ds-sheet-out-top var(--ds-duration-base) var(--ds-easing-drawer) forwards;
	--animate-sheet-in-bottom: ds-sheet-in-bottom var(--ds-duration-slow) var(--ds-easing-drawer);
	--animate-sheet-out-bottom: ds-sheet-out-bottom var(--ds-duration-base) var(--ds-easing-drawer) forwards;
	--animate-content-in: ds-content-in var(--ds-duration-base) var(--ds-easing-out);
	--animate-accordion-down: ds-accordion-down var(--ds-duration-base) var(--ds-easing-out);
	--animate-accordion-up: ds-accordion-up var(--ds-duration-fast) var(--ds-easing-out);
	--animate-collapsible-down: ds-collapsible-down var(--ds-duration-base) var(--ds-easing-out);
	--animate-collapsible-up: ds-collapsible-up var(--ds-duration-fast) var(--ds-easing-out);
	--animate-pulse-soft: ds-pulse-soft 1.6s var(--ds-easing-in-out) infinite;
	--animate-spin-steady: spin 0.8s linear infinite;
	--animate-caret-blink: ds-caret-blink 1.1s steps(1) infinite;
	--animate-chart-line: ds-chart-line 700ms var(--ds-easing-out) backwards;
	--animate-chart-bar: ds-chart-bar 400ms var(--ds-easing-out) backwards;

	@keyframes ds-pop-in {
		from {
			opacity: 0;
			transform: scale(0.96);
		}
	}

	@keyframes ds-pop-out {
		to {
			opacity: 0;
			transform: scale(0.96);
		}
	}

	@keyframes ds-fade-in {
		from {
			opacity: 0;
		}
	}

	@keyframes ds-fade-out {
		to {
			opacity: 0;
		}
	}

	@keyframes ds-dialog-in {
		from {
			opacity: 0;
			transform: scale(0.96);
		}
	}

	@keyframes ds-dialog-out {
		to {
			opacity: 0;
			transform: scale(0.97);
		}
	}

	@keyframes ds-sheet-in-right {
		from {
			transform: translateX(100%);
		}
	}

	@keyframes ds-sheet-out-right {
		to {
			transform: translateX(100%);
		}
	}

	@keyframes ds-sheet-in-left {
		from {
			transform: translateX(-100%);
		}
	}

	@keyframes ds-sheet-out-left {
		to {
			transform: translateX(-100%);
		}
	}

	@keyframes ds-sheet-in-top {
		from {
			transform: translateY(-100%);
		}
	}

	@keyframes ds-sheet-out-top {
		to {
			transform: translateY(-100%);
		}
	}

	@keyframes ds-sheet-in-bottom {
		from {
			transform: translateY(100%);
		}
	}

	@keyframes ds-sheet-out-bottom {
		to {
			transform: translateY(100%);
		}
	}

	@keyframes ds-content-in {
		from {
			opacity: 0;
			transform: translateY(4px);
		}
	}

	@keyframes ds-accordion-down {
		from {
			height: 0;
			opacity: 0;
		}
		to {
			height: var(--radix-accordion-content-height);
		}
	}

	@keyframes ds-accordion-up {
		from {
			height: var(--radix-accordion-content-height);
		}
		to {
			height: 0;
			opacity: 0;
		}
	}

	@keyframes ds-collapsible-down {
		from {
			height: 0;
			opacity: 0;
		}
		to {
			height: var(--radix-collapsible-content-height);
		}
	}

	@keyframes ds-collapsible-up {
		from {
			height: var(--radix-collapsible-content-height);
		}
		to {
			height: 0;
			opacity: 0;
		}
	}

	@keyframes ds-pulse-soft {
		50% {
			opacity: 0.55;
		}
	}

	@keyframes ds-caret-blink {
		50% {
			opacity: 0;
		}
	}

	@keyframes ds-chart-line {
		from {
			stroke-dashoffset: 1;
		}
	}

	@keyframes ds-chart-bar {
		from {
			transform: scaleY(0.04);
		}
	}
}

@media (prefers-reduced-motion: reduce) {
	@keyframes ds-pop-in {
		from {
			opacity: 0;
		}
	}

	@keyframes ds-pop-out {
		to {
			opacity: 0;
		}
	}

	@keyframes ds-dialog-in {
		from {
			opacity: 0;
		}
	}

	@keyframes ds-dialog-out {
		to {
			opacity: 0;
		}
	}

	@keyframes ds-content-in {
		from {
			opacity: 0;
		}
	}

	@keyframes ds-sheet-in-right {
		from {
			opacity: 0;
		}
	}

	@keyframes ds-sheet-out-right {
		to {
			opacity: 0;
		}
	}

	@keyframes ds-sheet-in-left {
		from {
			opacity: 0;
		}
	}

	@keyframes ds-sheet-out-left {
		to {
			opacity: 0;
		}
	}

	@keyframes ds-sheet-in-top {
		from {
			opacity: 0;
		}
	}

	@keyframes ds-sheet-out-top {
		to {
			opacity: 0;
		}
	}

	@keyframes ds-sheet-in-bottom {
		from {
			opacity: 0;
		}
	}

	@keyframes ds-sheet-out-bottom {
		to {
			opacity: 0;
		}
	}

	@keyframes ds-chart-line {
		from {
			opacity: 0;
		}
	}

	@keyframes ds-chart-bar {
		from {
			opacity: 0;
		}
	}
}

/* Shared interaction rules for installed CSS and the component theme. */
@layer base {
 :where(button, [role="button"], a[href], input, select, textarea, summary) {
  touch-action: manipulation;
 }
}

/* Press feedback is immediate; the action still activates through the native click/keyboard path. */
:where(button, [role="button"], a[href], summary):active {
 transition-duration: 0s !important;
 transition-delay: 0s !important;
}

/* Keyboard feedback and explicitly high-frequency surfaces never wait for motion. */
:where(button, [role="button"], a[href], input, select, textarea, summary):focus-visible,
:where(button, [role="button"], a[href], input, select, textarea, summary):focus-visible *,
:where([data-ds-motion="instant"], [data-instant="true"], [data-slot^="command"]),
:where([data-ds-motion="instant"], [data-instant="true"], [data-slot^="command"]) *,
:where([data-ds-motion="instant"], [data-instant="true"], [data-slot^="command"]) *::before,
:where([data-ds-motion="instant"], [data-instant="true"], [data-slot^="command"]) *::after,
:where([data-ds-motion="instant"], [data-instant="true"], [data-slot^="command"])::before,
:where([data-ds-motion="instant"], [data-instant="true"], [data-slot^="command"])::after {
 animation: none !important;
 transition: none !important;
 scroll-behavior: auto !important;
}

@media (prefers-reduced-motion: reduce) {
 *, ::before, ::after {
  animation: none !important;
  transition: none !important;
  scroll-behavior: auto !important;
 }
}

```

# Accordion
Sections that open in place: 14px ink labels with a caret at the right, ruled by the faint lilac line.

Install: npx inkbox-ds add accordion
Requires: theme, utils
Packages: @chakra-ui/react, @phosphor-icons/react
Exports: Accordion, AccordionContent, AccordionItem, AccordionTrigger
Client boundary: yes
Reference: Figma 427:2715: Create Agent Identity (Advanced settings - tunnel mode, phone state, line sharing)


## Usage
Use for settings or answers people open one at a time (advanced options, FAQs). Pass type="single" collapsible for one open at a time, type="multiple" for several. Keep the label a short phrase; the content is 14px secondary text or a group of fields.
- Avoid: Bold or purple trigger labels
- Avoid: A chevron at the left
- Avoid: Boxing each item in a card
- Avoid: Opening animation longer than 200ms


## Examples
Example components: npx inkbox-ds add accordion
[Preview](https://inkbox-ds.vercel.app/preview/accordion/Preview) | [Multiple](https://inkbox-ds.vercel.app/preview/accordion/Multiple)

examples/accordion.tsx

```tsx
import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from "@/components/ui/accordion";

export function Preview() {
  return (
    <Accordion type="single" collapsible defaultValue="tunnel" className="w-full max-w-120">
      <AccordionItem value="tunnel">
        <AccordionTrigger>What does the tunnel do?</AccordionTrigger>
        <AccordionContent>It gives each agent a stable hostname (acme.inkboxwire.com) and routes inbound traffic to wherever the agent runs, with TLS at the edge or passed through.</AccordionContent>
      </AccordionItem>
      <AccordionItem value="phone">
        <AccordionTrigger>Can one agent have a phone number and iMessage?</AccordionTrigger>
        <AccordionContent>Yes. Turn on Phone Number for calls and SMS, and iMessage for a shared or dedicated line. Each channel keeps its own contact rules.</AccordionContent>
      </AccordionItem>
      <AccordionItem value="vault">
        <AccordionTrigger>Who can read the vault?</AccordionTrigger>
        <AccordionContent>Only people with the vault key. Encryption and decryption happen in the browser, so the server never sees your secrets.</AccordionContent>
      </AccordionItem>
    </Accordion>
  );
}

export function Multiple() {
  return (
    <Accordion type="multiple" defaultValue={["email", "calls"]} className="w-full max-w-120">
      <AccordionItem value="email">
        <AccordionTrigger>Email</AccordionTrigger>
        <AccordionContent>acme-support@inboxmail.com receives and sends mail for this agent.</AccordionContent>
      </AccordionItem>
      <AccordionItem value="calls">
        <AccordionTrigger>Calls and texts</AccordionTrigger>
        <AccordionContent>Any state. Calls and SMS are on; RCS needs a dedicated line.</AccordionContent>
      </AccordionItem>
      <AccordionItem value="a2a" disabled>
        <AccordionTrigger>Agent2Agent (not enabled)</AccordionTrigger>
        <AccordionContent>Turn on Agent2Agent to publish this identity&apos;s Agent Card.</AccordionContent>
      </AccordionItem>
    </Accordion>
  );
}

```

## Source

components/ui/accordion.tsx

```tsx
"use client";

import * as React from "react";
import { Accordion as ChakraAccordion } from "@chakra-ui/react";
import { CaretDownIcon } from "@phosphor-icons/react/ssr";

import { cn } from "@/lib/utils";

// Sections that open in place, drawn as the dialog's Advanced settings row (Figma 427:2715, Create Agent Identity): a
// 14px regular ink label with a 20px caret at the right, items ruled by the faint lilac line. The panel opens with its
// height (200ms, the strong ease-out; closing is quicker) and the caret turns to point up.
type AccordionProps = Omit<React.ComponentProps<typeof ChakraAccordion.Root>, "multiple" | "collapsible" | "value" | "defaultValue"> & { type?: "single" | "multiple"; collapsible?: boolean; value?: string | string[]; defaultValue?: string | string[] };
function Accordion({ type = "single", collapsible, value, defaultValue, ...props }: AccordionProps) {
  return <ChakraAccordion.Root unstyled data-slot="accordion" multiple={type === "multiple"} collapsible={collapsible} value={value === undefined ? undefined : Array.isArray(value) ? value : [value]} defaultValue={defaultValue === undefined ? undefined : Array.isArray(defaultValue) ? defaultValue : [defaultValue]} {...props} />;
}

function AccordionItem({ className, ...props }: React.ComponentProps<typeof ChakraAccordion.Item>) {
  return <ChakraAccordion.Item unstyled data-slot="accordion-item" className={cn("border-b border-line-subtle last:border-b-0", className)} {...props} />;
}

function AccordionTrigger({ className, children, ...props }: React.ComponentProps<typeof ChakraAccordion.ItemTrigger>) {
  return (
    <ChakraAccordion.ItemTrigger
        data-slot="accordion-trigger"
        className={cn(
          "group/accordion-trigger flex flex-1 items-center justify-between gap-4 rounded-pill py-3.5 text-left font-sans text-body leading-body text-fg outline-none transition-colors duration-150 ease-out hover:text-fg-brand focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring disabled:pointer-events-none disabled:text-fg-muted motion-reduce:transition-none",
          className,
        )}
        {...props}
      >
        {children}
        <ChakraAccordion.ItemIndicator>
          <CaretDownIcon aria-hidden data-slot="accordion-trigger-icon" weight="bold" className="size-4 shrink-0 text-icon-default transition-transform duration-200 ease-out group-data-[state=open]/accordion-trigger:rotate-180 motion-reduce:transition-none" />
        </ChakraAccordion.ItemIndicator>
      </ChakraAccordion.ItemTrigger>
  );
}

function AccordionContent({ className, children, ...props }: React.ComponentProps<typeof ChakraAccordion.ItemContent>) {
  return (
    <ChakraAccordion.ItemContent data-slot="accordion-content" className="overflow-hidden text-body leading-body text-fg-secondary data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down" {...props}>
      <ChakraAccordion.ItemBody className={cn("pb-4", className)}>{children}</ChakraAccordion.ItemBody>
    </ChakraAccordion.ItemContent>
  );
}

export { Accordion, AccordionContent, AccordionItem, AccordionTrigger };

```

# Alert Dialog
The console's dialog for a question that must be answered: title, a secondary line and two pills.

Install: npx inkbox-ds add alert-dialog
Requires: theme, button, surface, utils
Packages: radix-ui
Exports: AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogMedia, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger
Client boundary: yes
Reference: Figma 427:2715: Modal - Create Agent (panel, scrim, title) with the console's pill buttons


## Usage
Use before an action that cannot be undone (delete an agent, rotate an API key) or when the person must acknowledge something. Name the action on its button (Delete agent), use variant="destructive" for it, and keep Cancel beside it.
- Avoid: OK and Cancel as labels
- Avoid: A close glyph on an alert dialog
- Avoid: Closing on a click outside
- Avoid: More than two actions


## Examples
Example components: npx inkbox-ds add alert-dialog button
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/alert-dialog/Preview) | [Small](https://inkbox-ds.vercel.app/preview/alert-dialog/Small) | [Open](https://inkbox-ds.vercel.app/preview/alert-dialog/Open)

examples/alert-dialog.tsx

```tsx
"use client";

import { KeyIcon, TrashIcon } from "@phosphor-icons/react/ssr";

import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogMedia, AlertDialogTitle, AlertDialogTrigger } from "@/components/ui/alert-dialog";
import { Button } from "@/components/ui/button";

function DeleteAgent() {
  return (
    <AlertDialogContent>
      <AlertDialogHeader>
        <AlertDialogTitle>Delete @acme?</AlertDialogTitle>
        <AlertDialogDescription>Its mailbox, phone line and tunnel are deleted with it. Messages it sent stay with their recipients. This cannot be undone.</AlertDialogDescription>
      </AlertDialogHeader>
      <AlertDialogFooter>
        <AlertDialogCancel>Cancel</AlertDialogCancel>
        <AlertDialogAction variant="destructive">Delete agent</AlertDialogAction>
      </AlertDialogFooter>
    </AlertDialogContent>
  );
}

export function Preview() {
  return (
    <div className="flex justify-center">
      <AlertDialog>
        <AlertDialogTrigger asChild>
          <Button variant="destructive">
            <TrashIcon weight="fill" />
            Delete agent
          </Button>
        </AlertDialogTrigger>
        <DeleteAgent />
      </AlertDialog>
    </div>
  );
}

export function Small() {
  return (
    <div className="flex justify-center">
      <AlertDialog>
        <AlertDialogTrigger asChild>
          <Button variant="outline">
            <KeyIcon weight="fill" />
            Rotate API key
          </Button>
        </AlertDialogTrigger>
        <AlertDialogContent size="sm">
          <AlertDialogHeader>
            <AlertDialogMedia>
              <KeyIcon weight="fill" />
            </AlertDialogMedia>
            <AlertDialogTitle>Rotate the API key?</AlertDialogTitle>
            <AlertDialogDescription>Agents using the old key stop working until you give them the new one.</AlertDialogDescription>
          </AlertDialogHeader>
          <AlertDialogFooter>
            <AlertDialogCancel>Cancel</AlertDialogCancel>
            <AlertDialogAction>Rotate</AlertDialogAction>
          </AlertDialogFooter>
        </AlertDialogContent>
      </AlertDialog>
    </div>
  );
}

export function Open() {
  return (
    <div className="min-h-100">
      <AlertDialog defaultOpen>
        <DeleteAgent />
      </AlertDialog>
    </div>
  );
}

```

## Source

components/ui/alert-dialog.tsx

```tsx
"use client";

import * as React from "react";
import { AlertDialog as AlertDialogPrimitive } from "radix-ui";

import { buttonVariants } from "@/components/ui/button";
import { usePortalContainer } from "@/lib/surface";
import { cn } from "@/lib/utils";

// A confirmation, drawn as the console's dialog (Figma 427:2715: Create Agent Identity, @test-agent is ready!): a white
// panel with 16px corners over the blurred, ink-tinted page, a 20px regular title and a 14px secondary line, 24px of
// padding, then the actions: the cancel as the lilac pill and the action as the purple pill (red for a destructive
// one), side by side at the end, stacked full width on phones. `size="sm"` is a 320px card with the title centered
// under an optional media tile (AlertDialogMedia). It has no close glyph: the person answers it. Opens from 96 percent
// with a fade, centered; closes faster.
function AlertDialog(props: React.ComponentProps<typeof AlertDialogPrimitive.Root>) {
  return <AlertDialogPrimitive.Root data-slot="alert-dialog" {...props} />;
}

function AlertDialogTrigger(props: React.ComponentProps<typeof AlertDialogPrimitive.Trigger>) {
  return <AlertDialogPrimitive.Trigger data-slot="alert-dialog-trigger" {...props} />;
}

function AlertDialogPortal(props: React.ComponentProps<typeof AlertDialogPrimitive.Portal>) {
  const container = usePortalContainer();
  return <AlertDialogPrimitive.Portal data-slot="alert-dialog-portal" container={container} {...props} />;
}

function AlertDialogOverlay({ className, ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Overlay>) {
  return (
    <AlertDialogPrimitive.Overlay
      data-slot="alert-dialog-overlay"
      className={cn("fixed inset-0 z-50 bg-scrim backdrop-blur-[var(--ds-blur-scrim)] data-[state=closed]:animate-fade-out data-[state=open]:animate-fade-in", className)}
      {...props}
    />
  );
}

function AlertDialogContent({ className, size = "default", ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Content> & { size?: "default" | "sm" }) {
  return (
    <AlertDialogPortal>
      <AlertDialogOverlay />
      <AlertDialogPrimitive.Content
        data-slot="alert-dialog-content"
        data-size={size}
        className={cn(
          "group/alert-dialog fixed top-1/2 left-1/2 z-50 grid max-h-[calc(100dvh-2rem)] w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 gap-6 overflow-y-auto rounded-panel bg-surface p-6 text-fg outline-none data-[size=default]:max-w-112 data-[size=sm]:max-w-80 data-[state=closed]:animate-dialog-out data-[state=open]:animate-dialog-in",
          className,
        )}
        {...props}
      />
    </AlertDialogPortal>
  );
}

function AlertDialogHeader({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="alert-dialog-header" className={cn("grid gap-1.5 group-data-[size=sm]/alert-dialog:justify-items-center group-data-[size=sm]/alert-dialog:text-center", className)} {...props} />;
}

function AlertDialogFooter({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="alert-dialog-footer"
      className={cn("flex flex-col-reverse gap-3 sm:flex-row sm:justify-end group-data-[size=sm]/alert-dialog:grid group-data-[size=sm]/alert-dialog:grid-cols-2 group-data-[size=sm]/alert-dialog:[&>*]:w-full", className)}
      {...props}
    />
  );
}

/** A 48px tile above the title (the console's pink channel tile): put a filled glyph inside. */
function AlertDialogMedia({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="alert-dialog-media" className={cn("mb-1.5 inline-flex size-12 items-center justify-center rounded-pill bg-pink text-rose [&_svg:not([class*='size-'])]:size-7", className)} {...props} />;
}

function AlertDialogTitle({ className, ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Title>) {
  return <AlertDialogPrimitive.Title data-slot="alert-dialog-title" className={cn("font-sans text-h3 leading-heading font-normal text-fg", className)} {...props} />;
}

function AlertDialogDescription({ className, ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Description>) {
  return <AlertDialogPrimitive.Description data-slot="alert-dialog-description" className={cn("text-body leading-body text-fg-secondary", className)} {...props} />;
}

function AlertDialogAction({ className, variant = "default", ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Action> & { variant?: "default" | "destructive" }) {
  return <AlertDialogPrimitive.Action data-slot="alert-dialog-action" className={cn(buttonVariants({ variant }), className)} {...props} />;
}

function AlertDialogCancel({ className, ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Cancel>) {
  return <AlertDialogPrimitive.Cancel data-slot="alert-dialog-cancel" className={cn(buttonVariants({ variant: "secondary" }), className)} {...props} />;
}

export {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogMedia,
  AlertDialogOverlay,
  AlertDialogPortal,
  AlertDialogTitle,
  AlertDialogTrigger,
};

```

# Alert
The vault box on the lilac, the pale cyan info note, the sand warning banner with a note at the right, and a red error.

Install: npx inkbox-ds add alert
Requires: theme, utils
Packages: class-variance-authority
Exports: Alert, AlertAction, AlertDescription, AlertTitle, alertVariants
Client boundary: not required by this entry file
Reference: Figma 427:2715: Vault (Initialize vault, zero-knowledge note), Modal - Created (Copy this API key now)


## Usage
Use default for a panel that introduces a setup step (Initialize vault: glyph, 16px title, muted description). Use info for a fact the person should know (The vault is zero-knowledge), warning for something to act on now (Copy this API key now, with the reason in AlertAction), destructive for a failure. Lead with a filled Phosphor glyph.
- Avoid: A dark or saturated alert background
- Avoid: More than one alert stacked for one message
- Avoid: Dismissable warnings for security notes
- Avoid: A bold title


## Examples
Example components: npx inkbox-ds add alert button
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/alert/Preview) | [Info](https://inkbox-ds.vercel.app/preview/alert/Info) | [Warning](https://inkbox-ds.vercel.app/preview/alert/Warning) | [Destructive](https://inkbox-ds.vercel.app/preview/alert/Destructive)

examples/alert.tsx

```tsx
import { InfoIcon, LockIcon, WarningIcon, XCircleIcon } from "@phosphor-icons/react/ssr";

import { Alert, AlertAction, AlertDescription, AlertTitle } from "@/components/ui/alert";
import { Button } from "@/components/ui/button";

export function Preview() {
  return (
    <Alert className="max-w-200">
      <LockIcon weight="fill" />
      <AlertTitle>Initialize vault</AlertTitle>
      <AlertDescription className="grid gap-2">
        <p>Create an encrypted vault for your organization. The vault can store login credentials including MFA one-time passwords (OTP), SSH keys, API keys and other secrets for your agents.</p>
        <Alert variant="info">
          <InfoIcon weight="fill" />
          <AlertTitle>The vault is zero-knowledge: all encryption and decryption happens in your browser. The server never sees your secrets.</AlertTitle>
        </Alert>
      </AlertDescription>
    </Alert>
  );
}

export function Info() {
  return (
    <Alert variant="info" className="max-w-200">
      <InfoIcon weight="fill" />
      <AlertTitle>The vault is zero-knowledge: all encryption and decryption happens in your browser. The server never sees your secrets.</AlertTitle>
    </Alert>
  );
}

export function Warning() {
  return (
    <Alert variant="warning" className="max-w-180">
      <WarningIcon weight="fill" />
      <AlertTitle>Copy this API key now</AlertTitle>
      <AlertAction>For security, the full key cannot be shown again.</AlertAction>
    </Alert>
  );
}

export function Destructive() {
  return (
    <Alert variant="destructive" className="max-w-180">
      <XCircleIcon weight="fill" />
      <AlertTitle>Webhook delivery failed</AlertTitle>
      <AlertDescription>https://hooks.example.com/inkbox returned 502 three times. Deliveries are paused until it responds.</AlertDescription>
      <AlertAction>
        <Button variant="outline" size="sm">Retry</Button>
      </AlertAction>
    </Alert>
  );
}

```

## Source

components/ui/alert.tsx

```tsx
import * as React from "react";
import { cva, type VariantProps } from "class-variance-authority";

import { cn } from "@/lib/utils";

// The console's notes (Figma 427:2715). `default` is the vault box: a lilac panel with 8px corners, a 22px filled ink
// glyph beside a 16px regular title, then a 14px muted description across the full width (it can hold an info note). `info` is the zero-knowledge note: pale cyan, 8px corners,
// a filled info glyph and 14px deep teal text. `warning` is the copy-this-key banner: pale sand, 10px corners, a filled
// warning glyph, a 14px medium title and a 13px note at the right (AlertAction). `destructive` borrows the failed
// field's red. Put a Phosphor glyph first; the title and description line up beside it.
const alertVariants = cva(
  "@container/alert group/alert relative grid w-full grid-cols-[minmax(0,1fr)_auto] items-start gap-x-2.5 gap-y-0.5 font-sans text-body leading-body has-[>svg]:grid-cols-[auto_minmax(0,1fr)_auto] [&>svg]:shrink-0",
  {
    variants: {
      variant: {
        default: "items-center rounded-control bg-subtle px-3.5 py-3 text-fg [&>svg]:size-6 [&>svg]:text-icon-default [&>[data-slot=alert-description]]:col-span-full [&>[data-slot=alert-description]]:col-start-1 [&>[data-slot=alert-description]]:text-fg-muted [&>[data-slot=alert-title]]:text-body-lg [&>[data-slot=alert-title]]:leading-snug",
        info: "rounded-control bg-info-bg px-4 py-2 text-info-fg [&>svg]:size-5 [&>svg]:text-info",
        warning: "rounded-panel bg-warning-bg px-4 py-2 text-warning-fg [&>svg]:size-5.5 [&>svg]:text-warning [&>[data-slot=alert-action]]:text-warning-muted [&>[data-slot=alert-description]]:text-warning-muted [&>[data-slot=alert-title]]:font-medium",
        destructive: "rounded-control border border-danger bg-surface px-3.5 py-3 text-danger [&>svg]:size-5.5 [&>svg]:text-danger-strong [&>[data-slot=alert-description]]:text-fg-secondary [&>[data-slot=alert-title]]:font-medium",
      },
    },
    defaultVariants: { variant: "default" },
  },
);

function Alert({ className, variant, ...props }: React.ComponentProps<"div"> & VariantProps<typeof alertVariants>) {
  return <div data-slot="alert" data-variant={variant ?? "default"} role="alert" className={cn(alertVariants({ variant }), className)} {...props} />;
}

function AlertTitle({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="alert-title"
      className={cn(
        "col-start-1 min-w-0 leading-body group-has-[>svg]/alert:col-start-2",
        className,
      )}
      {...props}
    />
  );
}

function AlertDescription({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="alert-description"
      className={cn(
        "col-start-1 min-w-0 text-body leading-body group-has-[>svg]/alert:col-start-2 [&_p]:leading-body",
        className,
      )}
      {...props}
    />
  );
}

/** What sits at the right of an alert: a note (For security, the full key cannot be shown again) or a button. */
function AlertAction({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="alert-action"
      className={cn("col-start-2 row-span-2 row-start-1 self-center text-right text-body-sm group-has-[>svg]/alert:col-start-3 @max-sm/alert:col-start-1 @max-sm/alert:col-end-[-1] @max-sm/alert:row-start-3 @max-sm/alert:row-span-1 @max-sm/alert:text-left @max-sm/alert:group-has-[>svg]/alert:col-start-2", className)}
      {...props}
    />
  );
}

export { Alert, AlertAction, AlertDescription, AlertTitle, alertVariants };

```

# Aspect Ratio
A frame that holds media at a fixed shape.

Install: npx inkbox-ds add aspect-ratio
Requires: theme
Packages: radix-ui
Exports: AspectRatio
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the 8px corners of its cards and wells


## Usage
Wrap a screenshot, an attachment preview or a video in AspectRatio with ratio={16 / 9} (or 4 / 3, 1) so it keeps its shape at every width. Round and clip it with rounded-control and overflow-hidden.
- Avoid: Stretching an image to fill without object-cover
- Avoid: Corners other than the card's 8px on media inside cards


## Examples
Example components: npx inkbox-ds add aspect-ratio
[Preview](https://inkbox-ds.vercel.app/preview/aspect-ratio/Preview) | [Square](https://inkbox-ds.vercel.app/preview/aspect-ratio/Square)

examples/aspect-ratio.tsx

```tsx
import { AspectRatio } from "@/components/ui/aspect-ratio";

export function Preview() {
  return (
    <div className="w-full max-w-120">
      <AspectRatio ratio={16 / 9} className="overflow-hidden rounded-control bg-subtle">
        {/* eslint-disable-next-line @next/next/no-img-element */}
        <img src="/octopus.png" alt="The Inkbox octopus" className="size-full object-contain p-6" />
      </AspectRatio>
    </div>
  );
}

export function Square() {
  return (
    <div className="w-40">
      <AspectRatio ratio={1} className="flex items-center justify-center rounded-control border border-line-field bg-surface text-body text-fg-muted">1:1</AspectRatio>
    </div>
  );
}

```

## Source

components/ui/aspect-ratio.tsx

```tsx
"use client";

import * as React from "react";
import { AspectRatio as AspectRatioPrimitive } from "radix-ui";

// Holds media at a fixed shape (a screenshot, an attachment preview). The frame takes no style of its own; round and
// clip the media inside it with the card's 8px corners.
function AspectRatio(props: React.ComponentProps<typeof AspectRatioPrimitive.Root>) {
  return <AspectRatioPrimitive.Root data-slot="aspect-ratio" {...props} />;
}

export { AspectRatio };

```

# Attachment
A white file attachment with the field edge: horizontal rows and their pink file icons are fully rounded; vertical cards retain rounded corners. Names use 14px medium ink and sizes use IBM Plex Mono.

Install: npx inkbox-ds add attachment
Requires: theme, button, utils
Packages: @chakra-ui/react, class-variance-authority
Exports: Attachment, AttachmentAction, AttachmentActions, AttachmentContent, AttachmentDescription, AttachmentGroup, AttachmentMedia, AttachmentTitle, AttachmentTrigger
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the webhook cards (white, field edge, 8px corners) and the pink channel tiles of Create Agent Identity


## Usage
Show a file attached to an email, a message or a draft. Set state to idle while it waits, uploading or processing while it moves, error when it failed (say why in AttachmentDescription), and done when it is ready. Add AttachmentTrigger to open the file and AttachmentAction for remove or retry. Lay several out in an AttachmentGroup, which scrolls sideways.
- Avoid: A colored card behind the file
- Avoid: Sizes in Inter
- Avoid: A spinner over the whole card
- Avoid: An icon that moves on hover


## Examples
Example components: npx inkbox-ds add attachment
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/attachment/Preview) | [States](https://inkbox-ds.vercel.app/preview/attachment/States) | [Vertical](https://inkbox-ds.vercel.app/preview/attachment/Vertical) | [Sizes](https://inkbox-ds.vercel.app/preview/attachment/Sizes)

examples/attachment.tsx

```tsx
"use client";

import * as React from "react";
import { ArrowClockwiseIcon, DownloadSimpleIcon, FileCsvIcon, FilePdfIcon, FileTextIcon, ImageIcon, XIcon } from "@phosphor-icons/react/ssr";

import { Attachment, AttachmentAction, AttachmentActions, AttachmentContent, AttachmentDescription, AttachmentGroup, AttachmentMedia, AttachmentTitle, AttachmentTrigger } from "@/components/ui/attachment";

export function Preview() {
  const [files, setFiles] = React.useState([
    { name: "invoice-2026-08.pdf", size: "248 KB", icon: FilePdfIcon },
    { name: "contacts-export.csv", size: "1.2 MB", icon: FileCsvIcon },
    { name: "agent-card.json", size: "3 KB", icon: FileTextIcon },
  ]);
  return (
    <AttachmentGroup className="max-w-full">
      {files.map(({ name, size, icon: Icon }) => (
        <Attachment key={name}>
          <AttachmentTrigger aria-label={`Open ${name}`} />
          <AttachmentMedia>
            <Icon weight="fill" />
          </AttachmentMedia>
          <AttachmentContent>
            <AttachmentTitle>{name}</AttachmentTitle>
            <AttachmentDescription>{size}</AttachmentDescription>
          </AttachmentContent>
          <AttachmentActions>
            <AttachmentAction aria-label={`Remove ${name}`} onClick={() => setFiles((all) => all.filter((f) => f.name !== name))}>
              <XIcon />
            </AttachmentAction>
          </AttachmentActions>
        </Attachment>
      ))}
    </AttachmentGroup>
  );
}

export function States() {
  return (
    <div className="flex flex-wrap items-start gap-3">
      <Attachment state="idle">
        <AttachmentMedia>
          <FileTextIcon weight="fill" />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>quickstart.md</AttachmentTitle>
          <AttachmentDescription>Waiting</AttachmentDescription>
        </AttachmentContent>
      </Attachment>
      <Attachment state="uploading">
        <AttachmentMedia>
          <FilePdfIcon weight="fill" />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>contract-signed.pdf</AttachmentTitle>
          <AttachmentDescription>62% of 4.8 MB</AttachmentDescription>
        </AttachmentContent>
      </Attachment>
      <Attachment state="error">
        <AttachmentMedia>
          <FileCsvIcon weight="fill" />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>leads.csv</AttachmentTitle>
          <AttachmentDescription>Larger than 25 MB</AttachmentDescription>
        </AttachmentContent>
        <AttachmentActions>
          <AttachmentAction aria-label="Retry leads.csv">
            <ArrowClockwiseIcon />
          </AttachmentAction>
        </AttachmentActions>
      </Attachment>
    </div>
  );
}

export function Vertical() {
  return (
    <div className="flex flex-wrap items-start gap-3">
      <Attachment orientation="vertical">
        <AttachmentMedia variant="image">
          {/* eslint-disable-next-line @next/next/no-img-element */}
          <img src="/octopus.png" alt="" />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>octopus.png</AttachmentTitle>
          <AttachmentDescription>94 KB</AttachmentDescription>
        </AttachmentContent>
        <AttachmentActions>
          <AttachmentAction aria-label="Download octopus.png">
            <DownloadSimpleIcon />
          </AttachmentAction>
        </AttachmentActions>
      </Attachment>
      <Attachment orientation="vertical" state="processing">
        <AttachmentMedia>
          <ImageIcon weight="fill" />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>screenshot.png</AttachmentTitle>
          <AttachmentDescription>Scanning</AttachmentDescription>
        </AttachmentContent>
      </Attachment>
    </div>
  );
}

export function Sizes() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      {(["default", "sm", "xs"] as const).map((size) => (
        <Attachment key={size} size={size}>
          <AttachmentMedia>
            <FilePdfIcon weight="fill" />
          </AttachmentMedia>
          <AttachmentContent>
            <AttachmentTitle>invoice.pdf</AttachmentTitle>
            <AttachmentDescription>248 KB</AttachmentDescription>
          </AttachmentContent>
        </Attachment>
      ))}
    </div>
  );
}

```

## Source

components/ui/attachment.tsx

```tsx
"use client";

import * as React from "react";
import { chakra } from "@chakra-ui/react";
import { cva, type VariantProps } from "class-variance-authority";

import { Button } from "@/components/ui/button";
import { cn } from "@/lib/utils";

// A file attached to a message or an email, drawn as the console's cards (Figma 427:2715): white with the field edge
// and pill corners on horizontal rows. Vertical cards keep their rounded corners. The file sits in a pink tile
// with a rose glyph; its name is 14px medium ink and its size or status 12px muted in IBM Plex Mono. A waiting file has a
// dashed edge, one uploading pulses its name softly, one that failed takes the red edge and a red line.
const attachmentVariants = cva(
  "group/attachment relative flex w-fit max-w-full min-w-0 shrink-0 flex-wrap rounded-control border border-line-field bg-surface text-fg transition-[background-color,border-color] duration-150 ease-out has-[>[data-slot=attachment-trigger]]:hover:bg-subtle has-[>[data-slot=attachment-trigger]:focus-visible]:outline-2 has-[>[data-slot=attachment-trigger]:focus-visible]:outline-offset-2 has-[>[data-slot=attachment-trigger]:focus-visible]:outline-focus-ring data-[state=error]:border-danger data-[state=idle]:border-dashed motion-reduce:transition-none",
  {
    variants: {
      size: {
        default: "gap-3 text-body has-data-[slot=attachment-content]:px-3 has-data-[slot=attachment-content]:py-2.5 has-data-[slot=attachment-media]:p-2.5",
        sm: "gap-2.5 text-body has-data-[slot=attachment-content]:px-2.5 has-data-[slot=attachment-content]:py-2 has-data-[slot=attachment-media]:p-2",
        xs: "gap-2 rounded-sm text-body-sm has-data-[slot=attachment-content]:px-2 has-data-[slot=attachment-content]:py-1.5 has-data-[slot=attachment-media]:p-1.5",
      },
      orientation: {
        horizontal: "min-w-48 items-center rounded-pill",
        vertical: "w-28 flex-col has-data-[slot=attachment-content]:w-36",
      },
    },
    defaultVariants: { size: "default", orientation: "horizontal" },
  },
);

type AttachmentState = "idle" | "uploading" | "processing" | "error" | "done";

function Attachment({ className, state = "done", size = "default", orientation = "horizontal", ...props }: React.ComponentProps<"div"> & VariantProps<typeof attachmentVariants> & { state?: AttachmentState }) {
  return <div data-slot="attachment" data-state={state} data-size={size} data-orientation={orientation} aria-busy={state === "uploading" || state === "processing" || undefined} className={cn(attachmentVariants({ size, orientation }), className)} {...props} />;
}

const attachmentMediaVariants = cva(
  "relative flex aspect-square w-10 shrink-0 items-center justify-center overflow-hidden rounded-pill bg-pink text-rose group-data-[orientation=vertical]/attachment:w-full group-data-[size=sm]/attachment:w-8 group-data-[size=xs]/attachment:w-7 group-data-[orientation=vertical]/attachment:rounded-sm group-data-[orientation=vertical]/attachment:group-data-[size=xs]/attachment:rounded-xs group-data-[state=error]/attachment:bg-subtle group-data-[state=error]/attachment:text-danger [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-5.5 group-data-[orientation=vertical]/attachment:[&_svg:not([class*='size-'])]:size-7 group-data-[size=xs]/attachment:[&_svg:not([class*='size-'])]:size-4",
  {
    variants: {
      variant: {
        icon: "",
        // A photo shows itself; it stays faint until it has uploaded.
        image: "bg-subtle opacity-60 group-data-[state=done]/attachment:opacity-100 group-data-[state=idle]/attachment:opacity-100 *:[img]:aspect-square *:[img]:w-full *:[img]:object-cover",
      },
    },
    defaultVariants: { variant: "icon" },
  },
);

function AttachmentMedia({ className, variant = "icon", ...props }: React.ComponentProps<"div"> & VariantProps<typeof attachmentMediaVariants>) {
  return <div data-slot="attachment-media" data-variant={variant} className={cn(attachmentMediaVariants({ variant }), className)} {...props} />;
}

function AttachmentContent({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="attachment-content" className={cn("max-w-full min-w-0 flex-1 leading-tight group-data-[orientation=vertical]/attachment:px-1 group-data-[orientation=vertical]/attachment:pb-1", className)} {...props} />;
}

function AttachmentTitle({ className, ...props }: React.ComponentProps<"span">) {
  return (
    <span
      data-slot="attachment-title"
      className={cn("block max-w-full min-w-0 truncate font-sans font-medium text-fg group-data-[state=processing]/attachment:animate-pulse-soft group-data-[state=uploading]/attachment:animate-pulse-soft", className)}
      {...props}
    />
  );
}

function AttachmentDescription({ className, ...props }: React.ComponentProps<"span">) {
  return <span data-slot="attachment-description" className={cn("mt-1 block max-w-full min-w-0 truncate font-mono text-caption leading-tight text-fg-muted group-data-[state=error]/attachment:font-sans group-data-[state=error]/attachment:text-danger", className)} {...props} />;
}

function AttachmentActions({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="attachment-actions" className={cn("relative z-20 flex shrink-0 items-center gap-0.5 group-data-[orientation=vertical]/attachment:absolute group-data-[orientation=vertical]/attachment:top-3.5 group-data-[orientation=vertical]/attachment:right-3.5", className)} {...props} />;
}

/** A row action on the attachment (remove, retry, download): a ghost glyph button. */
function AttachmentAction({ className, variant, size = "icon-sm", ...props }: React.ComponentProps<typeof Button>) {
  return <Button data-slot="attachment-action" variant={variant ?? "ghost"} size={size} className={cn("group-data-[orientation=vertical]/attachment:bg-surface group-data-[orientation=vertical]/attachment:shadow-s", className)} {...props} />;
}

/** Makes the whole card open the file: a button (or a link with asChild) stretched over it. */
function AttachmentTrigger({ className, asChild = false, type, ...props }: React.ComponentProps<"button"> & { asChild?: boolean }) {
  const Comp = asChild ? chakra.button : "button";
  // Chakra's factory renders its child in its place only when told to.
  const slotProps = asChild ? { asChild: true } : {};
  return <Comp {...slotProps} data-slot="attachment-trigger" type={asChild ? undefined : (type ?? "button")} className={cn("absolute inset-0 z-10 cursor-pointer rounded-control group-data-[orientation=horizontal]/attachment:rounded-pill outline-none", className)} {...props} />;
}

function AttachmentGroup({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="attachment-group"
      className={cn("flex min-w-0 snap-x snap-mandatory scroll-px-1 gap-3 overflow-x-auto overscroll-x-contain p-1 [scrollbar-width:none] *:data-[slot=attachment]:flex-none *:data-[slot=attachment]:snap-start", className)}
      {...props}
    />
  );
}

export { Attachment, AttachmentAction, AttachmentActions, AttachmentContent, AttachmentDescription, AttachmentGroup, AttachmentMedia, AttachmentTitle, AttachmentTrigger };

```

# Avatar
Circular initial tiles and agent portraits, with a fallback, status dot and group.

Install: npx inkbox-ds add avatar
Requires: theme, utils
Packages: @chakra-ui/react
Exports: Avatar, AvatarBadge, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarImage
Client boundary: yes
Reference: Figma 427:2715: the rail (Robert Ligthart), the agent picker (@acme), Modal - Created (@test-agent)


## Usage
Use the default circle shape for people, identities and agent portraits, including in rails and lists: size sm in a 38px row. Use shape="square" only when an explicit square variation is requested. Always give an AvatarFallback with the first initial. AvatarBadge marks a live agent; AvatarGroup shows who shares a mailbox.
- Avoid: Gradient or random-colored fallbacks
- Avoid: Two-letter initials in the 22px tile


## Examples
Example components: npx inkbox-ds add avatar
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/avatar/Preview) | [Sizes](https://inkbox-ds.vercel.app/preview/avatar/Sizes) | [WithBadge](https://inkbox-ds.vercel.app/preview/avatar/WithBadge) | [Group](https://inkbox-ds.vercel.app/preview/avatar/Group) | [Fallback](https://inkbox-ds.vercel.app/preview/avatar/Fallback)

examples/avatar.tsx

```tsx
import { CheckIcon } from "@phosphor-icons/react/ssr";

import { Avatar, AvatarBadge, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarImage } from "@/components/ui/avatar";

export function Preview() {
  return (
    <div className="grid gap-3">
      <div className="flex h-9.5 items-center gap-2.5 px-3">
        <Avatar size="sm">
          <AvatarFallback>R</AvatarFallback>
        </Avatar>
        <span className="text-body text-fg">Robert Ligthart</span>
      </div>
      <div className="flex h-9.5 items-center gap-2.5 px-3">
        <Avatar size="sm">
          <AvatarFallback>A</AvatarFallback>
        </Avatar>
        <span className="text-body text-fg">@acme</span>
      </div>
    </div>
  );
}

export function Sizes() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      <Avatar size="sm">
        <AvatarFallback>R</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarFallback>R</AvatarFallback>
      </Avatar>
      <Avatar size="lg">
        <AvatarFallback>R</AvatarFallback>
      </Avatar>
      <Avatar shape="circle" size="sm">
        <AvatarImage src="/logo-mark.png" alt="@test-agent" />
        <AvatarFallback>T</AvatarFallback>
      </Avatar>
      <Avatar shape="circle">
        <AvatarImage src="/logo-mark.png" alt="@test-agent" />
        <AvatarFallback>T</AvatarFallback>
      </Avatar>
      <Avatar shape="circle" size="lg">
        <AvatarImage src="/logo-mark.png" alt="@test-agent" />
        <AvatarFallback>T</AvatarFallback>
      </Avatar>
    </div>
  );
}

export function WithBadge() {
  return (
    <div className="flex items-center gap-4">
      <Avatar>
        <AvatarFallback>A</AvatarFallback>
        <AvatarBadge />
      </Avatar>
      <Avatar size="lg" shape="circle">
        <AvatarImage src="/logo-mark.png" alt="@test-agent" />
        <AvatarFallback>T</AvatarFallback>
        <AvatarBadge>
          <CheckIcon weight="bold" />
        </AvatarBadge>
      </Avatar>
    </div>
  );
}

export function Group() {
  return (
    <AvatarGroup>
      <Avatar>
        <AvatarFallback>R</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarFallback>A</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarFallback>M</AvatarFallback>
      </Avatar>
      <AvatarGroupCount>+3</AvatarGroupCount>
    </AvatarGroup>
  );
}

export function Fallback() {
  return (
    <div className="flex items-center gap-4">
      <Avatar size="lg" shape="circle">
        <AvatarFallback>R</AvatarFallback>
      </Avatar>
      <Avatar size="lg">
        <AvatarFallback>R</AvatarFallback>
      </Avatar>
    </div>
  );
}

```

## Source

components/ui/avatar.tsx

```tsx
"use client";

import * as React from "react";
import { Avatar as ChakraAvatar } from "@chakra-ui/react";

import { cn } from "@/lib/utils";

// Circular avatars with an avatar-blue fallback and a white initial; `square` remains an explicit shape option.
// Sizes: sm 22px (the rail), default 32px, lg 40px. The fallback shows until the image has loaded.
function Avatar({ className, size = "default", shape = "circle", ...props }: React.ComponentProps<typeof ChakraAvatar.Root> & { size?: "sm" | "default" | "lg"; shape?: "square" | "circle" }) {
  return (
    <ChakraAvatar.Root
      unstyled
      data-slot="avatar"
      data-size={size}
      data-shape={shape}
      className={cn(
        "group/avatar relative flex size-8 shrink-0 select-none data-[size=lg]:size-10 data-[size=sm]:size-5.5",
        shape === "circle" ? "rounded-pill" : "rounded-sm data-[size=lg]:rounded-control data-[size=sm]:rounded-xs",
        className,
      )}
      {...props}
    />
  );
}

function AvatarImage({ className, ...props }: React.ComponentProps<typeof ChakraAvatar.Image>) {
  return <ChakraAvatar.Image data-slot="avatar-image" className={cn("aspect-square size-full rounded-[inherit] object-cover", className)} {...props} />;
}

function AvatarFallback({ className, ...props }: React.ComponentProps<typeof ChakraAvatar.Fallback>) {
  return (
    <ChakraAvatar.Fallback
      data-slot="avatar-fallback"
      className={cn("flex size-full items-center justify-center rounded-[inherit] bg-avatar font-sans text-body leading-none text-white group-data-[size=lg]/avatar:text-body-lg group-data-[size=sm]/avatar:text-body", className)}
      {...props}
    />
  );
}

/** A status dot at the avatar's lower right (an agent online), ringed in white. */
function AvatarBadge({ className, ...props }: React.ComponentProps<"span">) {
  return (
    <span
      data-slot="avatar-badge"
      className={cn(
        "absolute -right-0.5 -bottom-0.5 z-10 inline-flex size-2.5 items-center justify-center rounded-pill bg-success text-white ring-2 ring-surface select-none group-data-[size=lg]/avatar:size-3 group-data-[size=sm]/avatar:size-2 [&>svg]:hidden group-data-[size=lg]/avatar:[&>svg]:block group-data-[size=lg]/avatar:[&>svg]:size-2",
        className,
      )}
      {...props}
    />
  );
}

/** Avatars overlapped by 8px, each ringed in white. */
function AvatarGroup({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="avatar-group" className={cn("group/avatar-group flex -space-x-2 *:data-[slot=avatar]:ring-2 *:data-[slot=avatar]:ring-surface", className)} {...props} />;
}

/** The count of avatars not shown (+3), on the lilac. */
function AvatarGroupCount({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="avatar-group-count"
      className={cn(
        "relative flex size-8 shrink-0 items-center justify-center rounded-pill bg-subtle font-sans text-caption leading-none text-fg-secondary ring-2 ring-surface group-has-data-[size=lg]/avatar-group:size-10 group-has-data-[size=sm]/avatar-group:size-5.5 [&>svg]:size-4",
        className,
      )}
      {...props}
    />
  );
}

export { Avatar, AvatarBadge, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarImage };

```

# Badge
The pink BETA and ADMIN marks, the green Included pill, the pale webhook tags, and the tunnel's status wells.

Install: npx inkbox-ds add badge
Requires: theme, utils
Packages: @chakra-ui/react, class-variance-authority
Exports: Badge, badgeVariants
Client boundary: yes
Reference: Figma 427:2715: the rail (BETA, ADMIN), Create Agent Identity (Included), Webhooks (Email, Signed, Fire-and-forget), iMessage (Blacklist), Tunnel (Active, Idle, Edge), Inbox (Unread)


## Usage
Use pink for a feature or role marker beside a label (BETA, ADMIN), success size lg with a filled check-circle for something granted (Included), blue, purple and gray at size sm for event tags (Email, Signed, Fire-and-forget), green size sm for a rule mode (Blacklist), and size well for a status reading (Active on green, Idle on gray, Edge on blue). Default (purple) and destructive are for counts and errors.
- Avoid: Caps typed with CSS
- Avoid: A badge as a button
- Avoid: More than three badges in a row
- Avoid: Saturated fills behind text


## Examples
Example components: npx inkbox-ds add badge
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/badge/Preview) | [Tags](https://inkbox-ds.vercel.app/preview/badge/Tags) | [Status](https://inkbox-ds.vercel.app/preview/badge/Status) | [Variants](https://inkbox-ds.vercel.app/preview/badge/Variants)

examples/badge.tsx

```tsx
import { CheckCircleIcon } from "@phosphor-icons/react/ssr";

import { Badge } from "@/components/ui/badge";

export function Preview() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <span className="flex items-center gap-2.5 text-body text-fg">
        Agent2Agent
        <Badge variant="pink">BETA</Badge>
      </span>
      <span className="flex items-center gap-2.5 text-body text-fg">
        My Organisation
        <Badge variant="pink">ADMIN</Badge>
      </span>
      <Badge variant="success" size="lg">
        <CheckCircleIcon weight="fill" />
        Included
      </Badge>
    </div>
  );
}

export function Tags() {
  return (
    <div className="flex flex-wrap items-center gap-1.5">
      <Badge variant="blue" size="sm">Email</Badge>
      <Badge variant="purple" size="sm">Signed</Badge>
      <Badge variant="gray" size="sm">Fire-and-forget</Badge>
      <Badge variant="green" size="sm">Blacklist</Badge>
      <Badge variant="blue" size="sm">Unread</Badge>
    </div>
  );
}

export function Status() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      <Badge variant="green" size="well">Active</Badge>
      <Badge variant="gray" size="well">Idle</Badge>
      <Badge variant="blue" size="well">Edge</Badge>
    </div>
  );
}

export function Variants() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Badge>3 new</Badge>
      <Badge variant="secondary">Draft</Badge>
      <Badge variant="outline">Webhook</Badge>
      <Badge variant="destructive">Failed</Badge>
      <Badge variant="ghost">Archived</Badge>
      <Badge variant="link" asChild>
        <a href="https://inkbox.ai/docs" target="_blank" rel="noreferrer">Docs</a>
      </Badge>
    </div>
  );
}

```

## Source

components/ui/badge.tsx

```tsx
"use client";

import * as React from "react";
import { chakra } from "@chakra-ui/react";
import { cva, type VariantProps } from "class-variance-authority";

import { cn } from "@/lib/utils";

// Every badge in the console (Figma 427:2715). `pink` is BETA and ADMIN: a 1px pink edge, fully rounded corners, 12px pink text,
// 22px tall with 6px sides and a 1px top inset to optically center the uppercase label. `success` is the Included pill:
// white with a 1px green edge, a filled check-circle (22px, the design's 20px glyph at Phosphor's proportions) 4px in and a 14px green label, 28px tall. `blue`, `purple` and `gray` are the webhook tags (Email, Signed,
// Fire-and-forget) at size sm: 11px medium on the pale fill, fully rounded corners, 17px tall; `green` is the Blacklist tag.
// At size `well` they become the tunnel's 38px status wells (Active, Idle, Edge): 14px ink, fully rounded corners.
const badgeVariants = cva(
  "inline-flex w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-pill border border-transparent font-sans whitespace-nowrap transition-[background-color,color] duration-150 ease-out focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring motion-reduce:transition-none [&>svg]:pointer-events-none [&>svg]:shrink-0",
  {
    variants: {
      variant: {
        default: "bg-primary text-on-primary [a&]:hover:bg-primary-hover",
        secondary: "bg-subtle text-fg [a&]:hover:bg-subtle-hover",
        destructive: "bg-danger text-white",
        outline: "border-line-field bg-surface text-fg [a&]:hover:bg-subtle",
        ghost: "text-fg-secondary [a&]:hover:bg-subtle",
        link: "text-fg-brand underline-offset-4 [a&]:hover:underline",
        pink: "rounded-pill border-pink bg-surface pt-px text-pink",
        success: "rounded-pill border-success bg-surface text-success",
        green: "bg-success-bg text-fg",
        blue: "bg-tag-blue text-tag-blue-fg",
        purple: "bg-tag-purple text-tag-purple-fg",
        gray: "bg-tag-gray text-fg",
      },
      size: {
        sm: "h-4.5 px-1 text-micro leading-tight font-medium [&>svg]:size-3.5",
        default: "h-5.5 px-1.5 text-caption leading-none [&>svg]:size-4",
        lg: "h-7 gap-1.5 pr-2.5 pl-1 text-body leading-tight [&>svg]:size-5.5",
        well: "h-9.5 rounded-pill px-3.5 text-body leading-tight text-fg [&>svg]:size-5.5",
      },
    },
    defaultVariants: { variant: "default", size: "default" },
  },
);

function Badge({ className, variant, size, asChild = false, ...props }: React.ComponentProps<"span"> & VariantProps<typeof badgeVariants> & { asChild?: boolean }) {
  const Comp = asChild ? chakra.span : "span";
  // Chakra's factory renders its child in its place only when told to.
  const slotProps = asChild ? { asChild: true } : {};
  return <Comp {...slotProps} data-slot="badge" data-variant={variant ?? "default"} className={cn(badgeVariants({ variant, size }), className)} {...props} />;
}

export { Badge, badgeVariants };

```

# Breadcrumb
A trail of 14px muted links ending in the current page in ink, with faint carets between.

Install: npx inkbox-ds add breadcrumb
Requires: theme, utils
Packages: @chakra-ui/react, @phosphor-icons/react
Exports: Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): page heads, muted text and links


## Usage
Use above a page head when a page sits deep in a hierarchy (Webhooks, then an endpoint, then a delivery). Fold middle levels into BreadcrumbEllipsis when the trail is long; use asChild to render your router's link.
- Avoid: Purple links
- Avoid: Slashes as separators
- Avoid: A breadcrumb on a top-level page


## Examples
Example components: npx inkbox-ds add breadcrumb
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/breadcrumb/Preview) | [Collapsed](https://inkbox-ds.vercel.app/preview/breadcrumb/Collapsed) | [CustomSeparator](https://inkbox-ds.vercel.app/preview/breadcrumb/CustomSeparator)

examples/breadcrumb.tsx

```tsx
import { LineVerticalIcon } from "@phosphor-icons/react/ssr";

import { Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator } from "@/components/ui/breadcrumb";

export function Preview() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="#">Webhooks</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink href="#">Delivery log</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>message.sent</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  );
}

export function Collapsed() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="#">Agent Workspace</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbEllipsis />
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink href="#">Tunnel</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>Telemetry</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  );
}

export function CustomSeparator() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="#">Vault</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator>
          <LineVerticalIcon className="rotate-12" />
        </BreadcrumbSeparator>
        <BreadcrumbItem>
          <BreadcrumbPage>Login credentials</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  );
}

```

## Source

components/ui/breadcrumb.tsx

```tsx
"use client";

import * as React from "react";
import { chakra } from "@chakra-ui/react";
import { CaretRightIcon, DotsThreeIcon } from "@phosphor-icons/react/ssr";

import { cn } from "@/lib/utils";

// A trail of pages (extrapolated from the Inkbox console, Figma 427:2715: its page heads and muted links). 14px muted
// links that darken to ink on hover, the current page in ink, 16px faint carets between them, and three dots for the
// pages folded away.
function Breadcrumb(props: React.ComponentProps<"nav">) {
  return <nav aria-label="breadcrumb" data-slot="breadcrumb" {...props} />;
}

function BreadcrumbList({ className, ...props }: React.ComponentProps<"ol">) {
  return <ol data-slot="breadcrumb-list" className={cn("flex flex-wrap items-center gap-1.5 font-sans text-body leading-tight break-words text-fg-muted", className)} {...props} />;
}

function BreadcrumbItem({ className, ...props }: React.ComponentProps<"li">) {
  return <li data-slot="breadcrumb-item" className={cn("inline-flex items-center gap-1.5", className)} {...props} />;
}

function BreadcrumbLink({ asChild, className, ...props }: React.ComponentProps<"a"> & { asChild?: boolean }) {
  const Comp = asChild ? chakra.a : "a";
  // Chakra's factory renders its child in its place only when told to.
  const slotProps = asChild ? { asChild: true } : {};
  return (
    <Comp {...slotProps}
      data-slot="breadcrumb-link"
      className={cn("rounded-xs text-fg-muted outline-none transition-colors duration-150 ease-out hover:text-fg focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring motion-reduce:transition-none", className)}
      {...props}
    />
  );
}

function BreadcrumbPage({ className, ...props }: React.ComponentProps<"span">) {
  return <span data-slot="breadcrumb-page" role="link" aria-disabled="true" aria-current="page" className={cn("font-normal text-fg", className)} {...props} />;
}

function BreadcrumbSeparator({ children, className, ...props }: React.ComponentProps<"li">) {
  return (
    <li data-slot="breadcrumb-separator" role="presentation" aria-hidden="true" className={cn("text-fg-faint [&>svg]:size-4", className)} {...props}>
      {children ?? <CaretRightIcon />}
    </li>
  );
}

function BreadcrumbEllipsis({ className, ...props }: React.ComponentProps<"span">) {
  return (
    <span data-slot="breadcrumb-ellipsis" role="presentation" aria-hidden="true" className={cn("flex size-7 items-center justify-center", className)} {...props}>
      <DotsThreeIcon weight="bold" className="size-4" />
      <span className="sr-only">More</span>
    </span>
  );
}

export { Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator };

```

# Bubble
A message bubble: incoming on the lilac, outgoing in the action purple, 16px corners with a 4px tail corner.

Install: npx inkbox-ds add bubble
Requires: theme, utils
Packages: @chakra-ui/react, class-variance-authority
Exports: Bubble, BubbleContent, BubbleGroup, BubbleReactions, bubbleVariants
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): iMessage and the inbox, in the action purple and the lilac


## Usage
Use inside Message for each piece of a conversation with an agent or a contact. Use the default (purple) variant with align end for what the person or their agent sent, secondary (lilac) for what arrived, tinted for another agent over Agent2Agent, muted for a system note, outline for a quoted message and destructive for one that failed to send. Stack consecutive bubbles in a BubbleGroup so only the last keeps the tail. BubbleReactions pins reactions to an edge.
- Avoid: Bubbles in colors outside the palette
- Avoid: An entrance animation on each bubble
- Avoid: Text smaller than 14px
- Avoid: Square corners


## Examples
Example components: npx inkbox-ds add bubble
[Preview](https://inkbox-ds.vercel.app/preview/bubble/Preview) | [Variants](https://inkbox-ds.vercel.app/preview/bubble/Variants)

examples/bubble.tsx

```tsx
import { Bubble, BubbleContent, BubbleGroup, BubbleReactions } from "@/components/ui/bubble";

export function Preview() {
  return (
    <div className="mx-auto flex w-full max-w-120 flex-col gap-3">
      <BubbleGroup>
        <Bubble variant="secondary">
          <BubbleContent>Hi, can you send me the invoice for August?</BubbleContent>
        </Bubble>
        <Bubble variant="secondary">
          <BubbleContent>The one from acme@inkboxmail.com.</BubbleContent>
        </Bubble>
      </BubbleGroup>
      <Bubble align="end">
        <BubbleContent>Sent it to you just now. It is also in your inbox as invoice-2026-08.pdf.</BubbleContent>
        <BubbleReactions align="start">👍</BubbleReactions>
      </Bubble>
    </div>
  );
}

export function Variants() {
  return (
    <div className="mx-auto flex w-full max-w-120 flex-col gap-3">
      <Bubble variant="tinted">
        <BubbleContent>@ops-agent: I can take the delegated task. Starting now.</BubbleContent>
      </Bubble>
      <Bubble variant="muted">
        <BubbleContent>Shared iMessage line connected.</BubbleContent>
      </Bubble>
      <Bubble variant="outline">
        <BubbleContent>Quoted: Your agent will be reachable at acme-support.inkboxwire.com</BubbleContent>
      </Bubble>
      <Bubble variant="destructive" align="end">
        <BubbleContent>Not delivered. The recipient blocks unknown senders.</BubbleContent>
      </Bubble>
      <Bubble variant="ghost">
        <BubbleContent>A ghost bubble sets text without a box, for long agent output.</BubbleContent>
      </Bubble>
      <Bubble align="end">
        <BubbleContent asChild>
          <button type="button">Retry sending</button>
        </BubbleContent>
      </Bubble>
    </div>
  );
}

```

## Source

components/ui/bubble.tsx

```tsx
"use client";

import * as React from "react";
import { chakra } from "@chakra-ui/react";
import { cva, type VariantProps } from "class-variance-authority";

import { cn } from "@/lib/utils";

// A message bubble in an agent conversation, in the console's colors (Figma 427:2715, iMessage and the inbox): an
// incoming message on the lilac with ink text, an outgoing one in the action purple with white text. 14px text on a 21px
// line, 14px by 10px of padding, 16px corners with the tail corner (bottom left for incoming, bottom right for outgoing)
// cut to 4px. In a BubbleGroup only the last bubble keeps the tail. Bubbles never animate in: a conversation is read
// all day.
function BubbleGroup({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="bubble-group" className={cn("flex min-w-0 flex-col gap-1 [&>[data-slot=bubble]:not(:last-child)>[data-slot=bubble-content]]:rounded-dialog", className)} {...props} />;
}

const bubbleVariants = cva(
  "group/bubble relative flex w-fit max-w-[80%] min-w-0 flex-col gap-1 group-data-[align=end]/message:self-end data-[align=end]:self-end data-[align=start]:*:data-[slot=bubble-content]:rounded-bl-xs data-[align=end]:*:data-[slot=bubble-content]:rounded-br-xs data-[variant=ghost]:max-w-full",
  {
    variants: {
      variant: {
        // Outgoing: the purple, as the main action.
        default: "*:data-[slot=bubble-content]:bg-primary *:data-[slot=bubble-content]:text-on-primary [&>[data-slot=bubble-content]:is(button,a):hover]:bg-primary-hover",
        // Incoming: the lilac.
        secondary: "*:data-[slot=bubble-content]:bg-subtle *:data-[slot=bubble-content]:text-fg [&>[data-slot=bubble-content]:is(button,a):hover]:bg-subtle-hover",
        // A system or quoted message: the cool gray of a neutral tag.
        muted: "*:data-[slot=bubble-content]:bg-tag-gray *:data-[slot=bubble-content]:text-fg-secondary [&>[data-slot=bubble-content]:is(button,a):hover]:bg-subtle-hover",
        // Another agent (Agent2Agent): the pale purple of a Signed tag.
        tinted: "*:data-[slot=bubble-content]:bg-tag-purple *:data-[slot=bubble-content]:text-fg [&>[data-slot=bubble-content]:is(button,a):hover]:bg-subtle-hover",
        outline: "*:data-[slot=bubble-content]:border-line-field *:data-[slot=bubble-content]:bg-surface *:data-[slot=bubble-content]:text-fg [&>[data-slot=bubble-content]:is(button,a):hover]:bg-subtle",
        ghost: "*:data-[slot=bubble-content]:rounded-none *:data-[slot=bubble-content]:bg-transparent *:data-[slot=bubble-content]:p-0 *:data-[slot=bubble-content]:text-fg",
        // A message that failed to send.
        destructive: "*:data-[slot=bubble-content]:border-danger *:data-[slot=bubble-content]:bg-surface *:data-[slot=bubble-content]:text-danger [&>[data-slot=bubble-content]:is(button,a):hover]:bg-subtle",
      },
    },
    defaultVariants: { variant: "default" },
  },
);

function Bubble({ variant = "default", align = "start", className, ...props }: React.ComponentProps<"div"> & VariantProps<typeof bubbleVariants> & { align?: "start" | "end" }) {
  return <div data-slot="bubble" data-variant={variant} data-align={align} className={cn(bubbleVariants({ variant }), className)} {...props} />;
}

function BubbleContent({ asChild = false, className, ...props }: React.ComponentProps<"div"> & { asChild?: boolean }) {
  const Comp = asChild ? chakra.div : "div";
  // Chakra's factory renders its child in its place only when told to.
  const slotProps = asChild ? { asChild: true } : {};
  return (
    <Comp {...slotProps}
      data-slot="bubble-content"
      className={cn(
        "w-fit max-w-full min-w-0 overflow-hidden rounded-dialog border border-transparent px-3.5 py-2.5 font-sans text-body leading-body break-words group-data-[align=end]/bubble:self-end [button]:cursor-pointer [button]:text-left [button,a]:outline-none [button,a]:transition-colors [button,a]:duration-150 [button,a]:ease-out [button,a]:focus-visible:outline-2 [button,a]:focus-visible:outline-offset-2 [button,a]:focus-visible:outline-focus-ring motion-reduce:transition-none",
        className,
      )}
      {...props}
    />
  );
}

const bubbleReactionsVariants = cva(
  "absolute z-10 flex w-fit shrink-0 items-center justify-center gap-1 rounded-pill bg-surface px-1.5 py-0.5 text-body-sm leading-tight text-fg shadow-s has-[button]:p-0",
  {
    variants: {
      side: { top: "top-0 -translate-y-3/4", bottom: "bottom-0 translate-y-3/4" },
      align: { start: "left-3", end: "right-3" },
    },
    defaultVariants: { side: "bottom", align: "end" },
  },
);

/** Reactions pinned to a bubble's edge: a white pill with Shadow/S. */
function BubbleReactions({ side = "bottom", align = "end", className, ...props }: React.ComponentProps<"div"> & { align?: "start" | "end"; side?: "top" | "bottom" }) {
  return <div data-slot="bubble-reactions" data-align={align} data-side={side} className={cn(bubbleReactionsVariants({ side, align }), className)} {...props} />;
}

export { Bubble, BubbleContent, BubbleGroup, BubbleReactions, bubbleVariants };

```

# Button Group
Buttons, fields and text segments joined into one bar with shared edges and outer corners only.

Install: npx inkbox-ds add button-group
Requires: theme, utils
Packages: @chakra-ui/react, class-variance-authority
Exports: ButtonGroup, ButtonGroupSeparator, ButtonGroupText, buttonGroupVariants
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the outline keys of the created dialog and the Email channel card's split field


## Usage
Use to join related actions into one control (View as formatted beside Copy as markdown), a field with an action, or a field with a fixed part (the @inboxmail.com suffix as ButtonGroupText). Nest groups to keep space between sets.
- Avoid: Joining a purple pill with an outline key
- Avoid: More than five buttons in a group
- Avoid: Joining unrelated actions


## Examples
Example components: npx inkbox-ds add button-group button input
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/button-group/Preview) | [WithField](https://inkbox-ds.vercel.app/preview/button-group/WithField) | [Split](https://inkbox-ds.vercel.app/preview/button-group/Split) | [Vertical](https://inkbox-ds.vercel.app/preview/button-group/Vertical)

examples/button-group.tsx

```tsx
import { CaretDownIcon, CopyIcon, FileTextIcon, MinusIcon, PlusIcon } from "@phosphor-icons/react/ssr";

import { Button } from "@/components/ui/button";
import { ButtonGroup, ButtonGroupSeparator, ButtonGroupText } from "@/components/ui/button-group";
import { Input } from "@/components/ui/input";

export function Preview() {
  return (
    <ButtonGroup aria-label="Prompt actions">
      <Button variant="outline">
        <FileTextIcon weight="fill" />
        View as formatted
      </Button>
      <Button variant="outline">
        <CopyIcon weight="duotone" />
        Copy as markdown
      </Button>
    </ButtonGroup>
  );
}

export function WithField() {
  return (
    <div className="grid w-full max-w-115 gap-4">
      <ButtonGroup className="w-full">
        <Input aria-label="Mailbox name" defaultValue="acme-support" />
        <ButtonGroupText>@inboxmail.com</ButtonGroupText>
      </ButtonGroup>
      <ButtonGroup className="w-full">
        <Input aria-label="Search contacts" placeholder="Search contacts" />
        <Button variant="outline">Search</Button>
      </ButtonGroup>
    </div>
  );
}

export function Split() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      <ButtonGroup>
        <Button>Create Agent</Button>
        <ButtonGroupSeparator />
        <Button size="icon-lg" aria-label="More create options">
          <CaretDownIcon />
        </Button>
      </ButtonGroup>
      <ButtonGroup aria-label="Phone lines">
        <Button variant="outline" size="icon" className="size-9" aria-label="Remove a line">
          <MinusIcon />
        </Button>
        <ButtonGroupText className="min-w-12 justify-center text-fg">2</ButtonGroupText>
        <Button variant="outline" size="icon" className="size-9" aria-label="Add a line">
          <PlusIcon />
        </Button>
      </ButtonGroup>
    </div>
  );
}

export function Vertical() {
  return (
    <ButtonGroup orientation="vertical" aria-label="Zoom">
      <Button variant="outline" size="icon" className="size-9" aria-label="Zoom in">
        <PlusIcon />
      </Button>
      <Button variant="outline" size="icon" className="size-9" aria-label="Zoom out">
        <MinusIcon />
      </Button>
    </ButtonGroup>
  );
}

```

## Source

components/ui/button-group.tsx

```tsx
"use client";

import * as React from "react";
import { chakra } from "@chakra-ui/react";
import { cva, type VariantProps } from "class-variance-authority";

import { cn } from "@/lib/utils";

// Buttons joined into one control (extrapolated from the Inkbox console, Figma 427:2715: the outline keys of the
// created dialog and the split field of the Email channel card). Inner corners square off and the shared edges merge,
// so outline keys read as one 36px bar with fully rounded outer corners; a field, select or text segment can sit in the bar.
// ButtonGroupText is the lilac segment with muted 14px text (@inboxmail.com); ButtonGroupSeparator is a 1px rule
// between filled buttons.
const buttonGroupVariants = cva(
  "group/button-group flex w-fit items-stretch *:focus-visible:relative *:focus-visible:z-10 has-[>[data-slot=button-group]]:gap-2 has-[>input]:[&>[data-slot=button]]:h-10 has-[>input]:[&>[data-slot=button-group-text]]:h-10 [&>input]:flex-1",
  {
    variants: {
      orientation: {
        horizontal: "[&>*:not(:first-child)]:rounded-l-none [&>*:not(:first-child)]:border-l-0 [&>*:not(:last-child)]:rounded-r-none",
        vertical: "flex-col [&>*:not(:first-child)]:rounded-t-none [&>*:not(:first-child)]:border-t-0 [&>*:not(:last-child)]:rounded-b-none",
      },
    },
    defaultVariants: { orientation: "horizontal" },
  },
);

function ButtonGroup({ className, orientation, ...props }: React.ComponentProps<"div"> & VariantProps<typeof buttonGroupVariants>) {
  return <div role="group" data-slot="button-group" data-orientation={orientation ?? "horizontal"} className={cn(buttonGroupVariants({ orientation }), className)} {...props} />;
}

function ButtonGroupText({ className, asChild = false, ...props }: React.ComponentProps<"div"> & { asChild?: boolean }) {
  const Comp = asChild ? chakra.div : "div";
  // Chakra's factory renders its child in its place only when told to.
  const slotProps = asChild ? { asChild: true } : {};
  return (
    <Comp {...slotProps}
      data-slot="button-group-text"
      className={cn("flex items-center gap-2 rounded-pill border border-line-field bg-subtle px-3.5 font-sans text-body leading-tight whitespace-nowrap text-fg-muted [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-5.5", className)}
      {...props}
    />
  );
}

function ButtonGroupSeparator({ className, orientation = "vertical", ...props }: React.ComponentProps<"div"> & { orientation?: "horizontal" | "vertical" }) {
  return (
    <div
      role="separator"
      aria-orientation={orientation}
      data-slot="button-group-separator"
      data-orientation={orientation}
      className={cn("relative shrink-0 self-stretch bg-surface/40", orientation === "vertical" ? "w-px" : "h-px", className)}
      {...props}
    />
  );
}

export { ButtonGroup, ButtonGroupSeparator, ButtonGroupText, buttonGroupVariants };

```

# Button
The purple pill for the main action, the lilac pill, the white outline key, the soft lilac key, ghost glyphs and text links.

Install: npx inkbox-ds add button
Requires: theme, utils
Packages: @chakra-ui/react, class-variance-authority
Exports: Button, buttonVariants
Client boundary: yes
Reference: Figma 427:2715: Create Agent, Enable iMessage, Log in, Continue with GitHub, View as formatted, Tunnel quickstart


## Usage
Use one default (purple pill) button per view for the main action, secondary for the alternatives beside it (Continue with GitHub), outline for actions inside content (View as formatted), soft for an action in a page head (Tunnel quickstart), ghost with size icon for row actions, and link for an inline action in text. Use type="submit" in forms, or asChild with a link for navigation. Put a Phosphor glyph first for an action that adds or creates.
- Avoid: Two purple pills side by side
- Avoid: A square or 8px-cornered main action
- Avoid: Bold or caps labels
- Avoid: An icon that moves on hover


## Examples
Example components: npx inkbox-ds add button
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/button/Preview) | [Variants](https://inkbox-ds.vercel.app/preview/button/Variants) | [States](https://inkbox-ds.vercel.app/preview/button/States)

examples/button.tsx

```tsx
import { CopyIcon, FileTextIcon, GithubLogoIcon, LightningIcon, PencilSimpleIcon, PlusIcon, TrashIcon } from "@phosphor-icons/react/ssr";

import { Button } from "@/components/ui/button";

export function Preview() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Button>
        <PlusIcon />
        Create Agent
      </Button>
      <Button variant="secondary">
        <GithubLogoIcon weight="fill" />
        Continue with GitHub
      </Button>
      <Button variant="outline">
        <FileTextIcon weight="fill" />
        View as formatted
      </Button>
      <Button variant="soft">
        <LightningIcon weight="fill" />
        Tunnel quickstart
      </Button>
    </div>
  );
}

export function Variants() {
  return (
    <div className="grid gap-4">
      <div className="flex flex-wrap items-center gap-3">
        <Button>Log in</Button>
        <Button variant="secondary">Cancel</Button>
        <Button variant="destructive">
          <TrashIcon weight="fill" />
          Delete agent
        </Button>
      </div>
      <div className="flex flex-wrap items-center gap-3">
        <Button variant="outline">
          <CopyIcon weight="duotone" />
          Copy as markdown
        </Button>
        <Button variant="ghost" size="icon" aria-label="Edit mailbox">
          <PencilSimpleIcon weight="fill" />
        </Button>
        <Button variant="link">Generate a random key instead</Button>
      </div>
    </div>
  );
}

export function States() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Button disabled>Create Agent Identity</Button>
      <Button variant="outline" disabled>
        View as formatted
      </Button>
      <Button size="sm">Small</Button>
      <Button size="lg">Large</Button>
    </div>
  );
}

```

## Source

components/ui/button.tsx

```tsx
"use client";

import * as React from "react";
import { Button as ChakraButton } from "@chakra-ui/react";
import { cva, type VariantProps } from "class-variance-authority";

import { cn } from "@/lib/utils";

// The console's buttons (Figma 427:2715). The main action is a 40px purple pill with a 14px regular white label and a
// 20px glyph 8px from it (Create Agent, Enable iMessage, Log in). `secondary` is the same pill in lilac with ink text
// (Continue with GitHub). `outline` is the 36px white key with fully rounded corners, the field edge and a medium purple label
// (View as formatted, Copy as markdown). `soft` is the 38px lilac key in a page head (Tunnel quickstart). `ghost` is a
// bare glyph or label that washes on hover (a row's edit pencil). Press feedback changes the fill immediately without resizing.
const buttonVariants = cva(
  "inline-flex shrink-0 items-center justify-center gap-2 whitespace-nowrap font-sans text-body leading-tight outline-none select-none transition-[background-color,color] duration-150 ease-out focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring active:brightness-95 active:transition-none disabled:pointer-events-none disabled:opacity-50 motion-reduce:transition-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-5.5",
  {
    variants: {
      variant: {
        default: "rounded-pill bg-primary px-5 text-on-primary hover:bg-primary-hover active:bg-primary-hover",
        secondary: "rounded-pill bg-subtle px-5 text-fg hover:bg-subtle-hover active:bg-subtle-hover",
        destructive: "rounded-pill bg-danger px-5 text-white hover:bg-danger-strong active:bg-danger-strong",
        outline: "rounded-pill border border-line-field bg-surface px-2.5 font-medium text-fg-brand hover:bg-subtle active:bg-subtle",
        soft: "rounded-pill bg-subtle px-3 text-fg hover:bg-subtle-hover active:bg-subtle-hover [&_svg:not([class*='size-'])]:size-6",
        ghost: "rounded-pill text-icon-secondary hover:bg-subtle active:bg-subtle hover:text-fg data-[state=open]:bg-subtle",
        link: "h-auto rounded-pill px-0 text-fg-brand underline-offset-4 hover:underline",
      },
      size: {
        default: "h-10",
        sm: "h-9 [&_svg:not([class*='size-'])]:size-5.5",
        lg: "h-11 px-6",
        icon: "size-8 rounded-pill px-0",
        "icon-sm": "size-7 rounded-pill px-0 [&_svg:not([class*='size-'])]:size-4.5",
        "icon-lg": "size-10 px-0",
      },
    },
    compoundVariants: [
      { variant: "outline", size: "default", className: "h-9" },
      { variant: "soft", size: "default", className: "h-9.5 gap-2.5" },
      { variant: "ghost", size: "default", className: "h-8 px-2" },
      { variant: "link", size: "default", className: "h-auto" },
    ],
    defaultVariants: { variant: "default", size: "default" },
  },
);

type ButtonProps = Omit<React.ComponentProps<typeof ChakraButton>, "variant" | "size"> & VariantProps<typeof buttonVariants> & { asChild?: boolean };

function Button({ className, variant, size, asChild = false, type, ...props }: ButtonProps) {
  return <ChakraButton unstyled asChild={asChild} data-slot="button" data-variant={variant ?? "default"} type={asChild ? type : (type ?? "button")} className={cn(buttonVariants({ variant, size, className }))} {...props} />;
}

export { Button, buttonVariants };

```

# Calendar
A month grid of 36px keys: today in purple, selected days as purple keys, a range on a lilac band.

Install: npx inkbox-ds add calendar
Requires: theme, utils
Packages: @phosphor-icons/react
Exports: Calendar, CalendarDayButton, CalendarProps, DateRange
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): 8px keys, the lilac wash and the purple action


## Usage
Use to pick a day, several days or a range (a delivery log window, a report period) when the month view helps. Set mode to single, multiple or range, pass selected and onSelect, and disable days that cannot be picked. For a field that opens a calendar, use Date Picker.
- Avoid: Round day keys
- Avoid: A dark selected day
- Avoid: Animating between months


## Examples
Example components: npx inkbox-ds add calendar
[Preview](https://inkbox-ds.vercel.app/preview/calendar/Preview) | [Range](https://inkbox-ds.vercel.app/preview/calendar/Range) | [Multiple](https://inkbox-ds.vercel.app/preview/calendar/Multiple) | [Disabled](https://inkbox-ds.vercel.app/preview/calendar/Disabled) | [Dropdown](https://inkbox-ds.vercel.app/preview/calendar/Dropdown)

examples/calendar.tsx

```tsx
"use client";

import * as React from "react";

import { Calendar, type DateRange } from "@/components/ui/calendar";

const TODAY = new Date(2026, 7, 8);
const FRAME = "w-fit rounded-control border border-line-field bg-surface";

export function Preview() {
  const [date, setDate] = React.useState<Date | undefined>(TODAY);
  return <Calendar mode="single" selected={date} onSelect={setDate} today={TODAY} className={FRAME} />;
}

export function Range() {
  const [range, setRange] = React.useState<DateRange | undefined>({ from: new Date(2026, 7, 4), to: new Date(2026, 7, 12) });
  return <Calendar mode="range" selected={range} onSelect={setRange} today={TODAY} numberOfMonths={2} className={FRAME} />;
}

export function Multiple() {
  const [days, setDays] = React.useState<Date[]>([new Date(2026, 7, 3), new Date(2026, 7, 10), new Date(2026, 7, 17)]);
  return <Calendar mode="multiple" selected={days} onSelect={setDays} today={TODAY} weekStartsOn={1} className={FRAME} />;
}

export function Disabled() {
  const [date, setDate] = React.useState<Date | undefined>();
  return <Calendar mode="single" selected={date} onSelect={setDate} today={TODAY} disabled={[{ before: TODAY }, { dayOfWeek: [0, 6] }]} showOutsideDays={false} className={FRAME} />;
}

export function Dropdown() {
  const [date, setDate] = React.useState<Date | undefined>(new Date(1994, 4, 21));
  return <Calendar mode="single" selected={date} onSelect={setDate} today={TODAY} captionLayout="dropdown" fromYear={1940} toYear={2026} className={FRAME} />;
}

```

## Source

components/ui/calendar.tsx

```tsx
"use client";

import * as React from "react";
import { CaretDownIcon, CaretLeftIcon, CaretRightIcon } from "@phosphor-icons/react/ssr";

import { cn } from "@/lib/utils";

// A month grid (extrapolated from the Inkbox console, Figma 427:2715: its 8px keys, the lilac wash and the purple
// action). The caption is 14px medium ink between two ghost caret keys; weekdays are 12px muted; days are 36px keys with
// 8px corners and 14px ink. Today is purple and medium; a selected day is the purple key with white text; the days
// inside a range sit on a lilac band between its two purple ends; days of the next and last month are faint. Arrow keys
// move a day or a week, Home and End go to the week's ends, Page Up and Page Down change the month (with Shift, the
// year), Enter or Space selects. Changing month is instant: it happens many times in a row.

type DateRange = { from: Date | undefined; to?: Date | undefined };
type Matcher = Date | Date[] | ((date: Date) => boolean) | { before?: Date; after?: Date } | { from: Date; to: Date } | { dayOfWeek: number[] };

type CommonProps = {
  /** The month shown first (controlled). */
  month?: Date;
  defaultMonth?: Date;
  onMonthChange?: (month: Date) => void;
  numberOfMonths?: number;
  /** Show the days of the months before and after in the grid (default true). */
  showOutsideDays?: boolean;
  /** 0 is Sunday (default), 1 is Monday. */
  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
  disabled?: Matcher | Matcher[];
  /** "label" (the default) or "dropdown": month and year selects in the caption. */
  captionLayout?: "label" | "dropdown";
  fromYear?: number;
  toYear?: number;
  /** Today, for the marker (defaults to the current date). */
  today?: Date;
  locale?: string;
  className?: string;
  autoFocus?: boolean;
};

type SingleProps = { mode?: "single"; selected?: Date; onSelect?: (date: Date | undefined) => void; required?: boolean };
type MultipleProps = { mode: "multiple"; selected?: Date[]; onSelect?: (dates: Date[]) => void; max?: number };
type RangeProps = { mode: "range"; selected?: DateRange; onSelect?: (range: DateRange | undefined) => void; min?: number; max?: number };

type CalendarProps = CommonProps & (SingleProps | MultipleProps | RangeProps);

const day0 = (d: Date) => new Date(d.getFullYear(), d.getMonth(), d.getDate());
const sameDay = (a?: Date, b?: Date) => !!a && !!b && a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
const addDays = (d: Date, n: number) => new Date(d.getFullYear(), d.getMonth(), d.getDate() + n);
const addMonths = (d: Date, n: number) => {
  const target = new Date(d.getFullYear(), d.getMonth() + n, 1);
  const last = new Date(target.getFullYear(), target.getMonth() + 1, 0).getDate();
  return new Date(target.getFullYear(), target.getMonth(), Math.min(d.getDate(), last));
};
const startOfMonth = (d: Date) => new Date(d.getFullYear(), d.getMonth(), 1);
const diffDays = (a: Date, b: Date) => Math.round((day0(a).getTime() - day0(b).getTime()) / 86_400_000);

function matches(date: Date, matcher: Matcher): boolean {
  if (matcher instanceof Date) return sameDay(date, matcher);
  if (Array.isArray(matcher)) return matcher.some((d) => sameDay(date, d));
  if (typeof matcher === "function") return matcher(date);
  if ("dayOfWeek" in matcher) return matcher.dayOfWeek.includes(date.getDay());
  if ("from" in matcher && "to" in matcher) return diffDays(date, matcher.from) >= 0 && diffDays(matcher.to, date) >= 0;
  const m = matcher as { before?: Date; after?: Date };
  return (!!m.before && diffDays(date, m.before) < 0) || (!!m.after && diffDays(date, m.after) > 0);
}

/** The weeks shown for a month: whole weeks from the one holding the 1st. */
function weeksOf(month: Date, weekStartsOn: number) {
  const first = startOfMonth(month);
  const start = addDays(first, -((first.getDay() - weekStartsOn + 7) % 7));
  const weeks: Date[][] = [];
  for (let w = 0; w < 6; w++) {
    const week = Array.from({ length: 7 }, (_, i) => addDays(start, w * 7 + i));
    if (w > 3 && week[0].getMonth() !== month.getMonth()) break;
    weeks.push(week);
  }
  return weeks;
}

function Calendar(props: CalendarProps) {
  const { month: monthProp, defaultMonth, onMonthChange, numberOfMonths = 1, showOutsideDays = true, weekStartsOn = 0, disabled, captionLayout = "label", fromYear, toYear, locale, className, autoFocus } = props;
  const today = React.useMemo(() => day0(props.today ?? new Date()), [props.today]);
  const initial = (() => {
    if (props.mode === "range") return props.selected?.from;
    if (props.mode === "multiple") return props.selected?.[0];
    return props.selected;
  })();
  const [monthState, setMonthState] = React.useState(() => startOfMonth(defaultMonth ?? initial ?? today));
  const month = monthProp ? startOfMonth(monthProp) : monthState;
  const setMonth = (m: Date) => {
    const next = startOfMonth(m);
    if (!monthProp) setMonthState(next);
    onMonthChange?.(next);
  };
  const [focused, setFocused] = React.useState<Date | undefined>(undefined);
  const grid = React.useRef<HTMLDivElement>(null);
  const focusPending = React.useRef(!!autoFocus);

  const isDisabled = (d: Date) => (disabled ? (Array.isArray(disabled) && !(disabled[0] instanceof Date) ? (disabled as Matcher[]).some((m) => matches(d, m)) : matches(d, disabled as Matcher)) : false);

  const state = (d: Date) => {
    if (props.mode === "range") {
      const { from, to } = props.selected ?? { from: undefined };
      const start = sameDay(d, from);
      const end = sameDay(d, to ?? from);
      const middle = !!from && !!to && diffDays(d, from) > 0 && diffDays(to, d) > 0;
      return { selected: start || end || middle, start: start && !!to && !sameDay(from, to), end: end && !!to && !sameDay(from, to), middle };
    }
    if (props.mode === "multiple") return { selected: !!props.selected?.some((s) => sameDay(s, d)), start: false, end: false, middle: false };
    return { selected: sameDay(props.selected, d), start: false, end: false, middle: false };
  };

  const select = (d: Date) => {
    if (isDisabled(d)) return;
    if (props.mode === "range") {
      const cur = props.selected;
      if (!cur?.from || cur.to) {
        props.onSelect?.({ from: d, to: undefined });
        return;
      }
      const [from, to] = diffDays(d, cur.from) < 0 ? [d, cur.from] : [cur.from, d];
      const length = diffDays(to, from);
      if ((props.max && length > props.max) || (props.min && length < props.min)) {
        props.onSelect?.({ from: d, to: undefined });
        return;
      }
      props.onSelect?.({ from, to });
    } else if (props.mode === "multiple") {
      const cur = props.selected ?? [];
      const has = cur.some((s) => sameDay(s, d));
      if (has) props.onSelect?.(cur.filter((s) => !sameDay(s, d)));
      else if (!props.max || cur.length < props.max) props.onSelect?.([...cur, d]);
    } else {
      const p = props as SingleProps;
      p.onSelect?.(sameDay(p.selected, d) && !p.required ? undefined : d);
    }
    if (d.getMonth() !== month.getMonth() && numberOfMonths === 1) setMonth(d);
  };

  // The day that takes Tab focus in the grid: the focused day, else the selection, else today, else the 1st.
  const months = Array.from({ length: numberOfMonths }, (_, i) => addMonths(month, i));
  const inView = (d: Date) => months.some((m) => m.getMonth() === d.getMonth() && m.getFullYear() === d.getFullYear());
  const tabDay = [focused, initial, today, month].find((d) => d && inView(d))!;

  // Focus the moved-to day, or with autoFocus the day that takes Tab focus (the selection, else today) on mount.
  const target = focused ?? tabDay;
  React.useEffect(() => {
    if (!focusPending.current || !target) return;
    focusPending.current = false;
    grid.current?.querySelector<HTMLButtonElement>(`[data-day="${target.toDateString()}"]`)?.focus();
  }, [target, month]);

  const move = (d: Date) => {
    if (!inView(d)) setMonth(diffDays(d, month) < 0 ? d : addMonths(d, -(numberOfMonths - 1)));
    focusPending.current = true;
    setFocused(d);
  };

  const onKeyDown = (event: React.KeyboardEvent, d: Date) => {
    const weekStart = addDays(d, -((d.getDay() - weekStartsOn + 7) % 7));
    const keys: Record<string, () => Date> = {
      ArrowLeft: () => addDays(d, -1),
      ArrowRight: () => addDays(d, 1),
      ArrowUp: () => addDays(d, -7),
      ArrowDown: () => addDays(d, 7),
      Home: () => weekStart,
      End: () => addDays(weekStart, 6),
      PageUp: () => addMonths(d, event.shiftKey ? -12 : -1),
      PageDown: () => addMonths(d, event.shiftKey ? 12 : 1),
    };
    const next = keys[event.key];
    if (!next) return;
    event.preventDefault();
    move(next());
  };

  const fmt = (opts: Intl.DateTimeFormatOptions) => new Intl.DateTimeFormat(locale, opts);
  const weekdayNames = Array.from({ length: 7 }, (_, i) => addDays(new Date(2023, 0, 1 + weekStartsOn), i));
  const years = (() => {
    const from = fromYear ?? today.getFullYear() - 100;
    const to = toYear ?? today.getFullYear() + 10;
    return Array.from({ length: to - from + 1 }, (_, i) => from + i);
  })();

  return (
    <div data-slot="calendar" className={cn("w-fit p-3 font-sans text-fg", className)}>
      <div ref={grid} className="flex flex-col gap-4 sm:flex-row">
        {months.map((m, index) => (
          <div key={m.toISOString()} data-slot="calendar-month" className="flex flex-col gap-3">
            <div data-slot="calendar-caption" className="relative flex h-8 items-center justify-center">
              {index === 0 && (
                <button type="button" aria-label="Go to the previous month" onClick={() => setMonth(addMonths(month, -1))} className={NAV_BUTTON + " absolute left-0"}>
                  <CaretLeftIcon />
                </button>
              )}
              {captionLayout === "dropdown" && index === 0 ? (
                <div className="flex items-center gap-1.5">
                  <CaptionSelect label="Month" value={m.getMonth()} onChange={(v) => setMonth(new Date(m.getFullYear(), v, 1))} options={Array.from({ length: 12 }, (_, i) => ({ value: i, label: fmt({ month: "short" }).format(new Date(2023, i, 1)) }))} />
                  <CaptionSelect label="Year" value={m.getFullYear()} onChange={(v) => setMonth(new Date(v, m.getMonth(), 1))} options={years.map((y) => ({ value: y, label: String(y) }))} />
                </div>
              ) : (
                <p aria-live="polite" className="text-body leading-tight font-medium text-fg">
                  {fmt({ month: "long", year: "numeric" }).format(m)}
                </p>
              )}
              {index === months.length - 1 && (
                <button type="button" aria-label="Go to the next month" onClick={() => setMonth(addMonths(month, 1))} className={NAV_BUTTON + " absolute right-0"}>
                  <CaretRightIcon />
                </button>
              )}
            </div>
            <table role="grid" aria-label={fmt({ month: "long", year: "numeric" }).format(m)} className="border-collapse">
              <thead>
                <tr>
                  {weekdayNames.map((w) => (
                    <th key={w.getDay()} scope="col" aria-label={fmt({ weekday: "long" }).format(w)} className="size-9 p-0 text-caption leading-tight font-normal text-fg-muted">
                      {fmt({ weekday: "short" }).format(w).slice(0, 2)}
                    </th>
                  ))}
                </tr>
              </thead>
              <tbody>
                {weeksOf(m, weekStartsOn).map((week) => (
                  <tr key={week[0].toISOString()} className="mt-0.5">
                    {week.map((d) => {
                      const outside = d.getMonth() !== m.getMonth();
                      if (outside && !showOutsideDays) return <td key={d.toISOString()} className="size-9 p-0" />;
                      const s = state(d);
                      const off = isDisabled(d);
                      return (
                        <td
                          key={d.toISOString()}
                          role="gridcell"
                          aria-selected={s.selected || undefined}
                          data-range-start={s.start || undefined}
                          data-range-end={s.end || undefined}
                          data-range-middle={s.middle || undefined}
                          className="relative size-9 p-0 py-0.5 text-center data-range-end:bg-[linear-gradient(to_left,transparent_50%,var(--ds-color-bg-subtle)_50%)] data-range-middle:bg-subtle data-range-start:bg-[linear-gradient(to_right,transparent_50%,var(--ds-color-bg-subtle)_50%)] data-range-start:[background-clip:content-box] data-range-end:[background-clip:content-box] data-range-middle:[background-clip:content-box]"
                        >
                          <CalendarDayButton
                            date={d}
                            label={fmt({ weekday: "long", month: "long", day: "numeric", year: "numeric" }).format(d)}
                            today={sameDay(d, today)}
                            outside={outside}
                            disabled={off}
                            selected={s.selected && !s.middle}
                            middle={s.middle}
                            tabIndex={sameDay(d, tabDay) && !outside ? 0 : -1}
                            onClick={() => select(d)}
                            onFocus={() => setFocused(d)}
                            onKeyDown={(e) => onKeyDown(e, d)}
                          />
                        </td>
                      );
                    })}
                  </tr>
                ))}
              </tbody>
            </table>
          </div>
        ))}
      </div>
    </div>
  );
}

const NAV_BUTTON =
  "inline-flex size-8 items-center justify-center rounded-pill text-icon-secondary outline-none transition-[background-color,color] duration-150 ease-out hover:bg-subtle active:bg-subtle hover:text-fg active:brightness-95 active:transition-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring motion-reduce:transition-none [&_svg]:size-4";

function CaptionSelect({ label, value, options, onChange }: { label: string; value: number; options: { value: number; label: string }[]; onChange: (value: number) => void }) {
  return (
    <span className="relative inline-flex">
      <select
        aria-label={label}
        value={value}
        onChange={(e) => onChange(Number(e.target.value))}
        className="h-8 appearance-none rounded-pill bg-surface pr-7 pl-2.5 font-sans text-body leading-tight font-medium text-fg shadow-s outline-none focus-visible:shadow-focus"
      >
        {options.map((o) => (
          <option key={o.value} value={o.value}>
            {o.label}
          </option>
        ))}
      </select>
      <CaretDownIcon aria-hidden className="pointer-events-none absolute top-1/2 right-2 size-3.5 -translate-y-1/2 text-fg" />
    </span>
  );
}

type DayButtonProps = Omit<React.ComponentProps<"button">, "children"> & { date: Date; label: string; today?: boolean; outside?: boolean; selected?: boolean; middle?: boolean };

/** One day: a 36px key with 8px corners. Exported so an app can render a day its own way inside the same grid. */
function CalendarDayButton({ date, label, today, outside, selected, middle, disabled, className, ...props }: DayButtonProps) {
  return (
    <button
      type="button"
      data-slot="calendar-day"
      data-day={date.toDateString()}
      data-today={today || undefined}
      data-outside={outside || undefined}
      data-selected={selected || undefined}
      data-range-middle={middle || undefined}
      aria-label={label}
      aria-pressed={selected || middle || undefined}
      aria-current={today ? "date" : undefined}
      disabled={disabled}
      className={cn(
        "relative mx-auto flex size-9 items-center justify-center rounded-pill font-sans text-body leading-tight text-fg tabular-nums outline-none transition-[background-color,color] duration-150 ease-out hover:bg-subtle active:bg-subtle active:brightness-95 active:transition-none focus-visible:z-10 focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-focus-ring disabled:pointer-events-none disabled:text-fg-faint disabled:line-through motion-reduce:transition-none",
        today && "font-medium text-fg-brand",
        outside && "text-fg-faint",
        middle && "rounded-none bg-transparent text-fg hover:bg-subtle-hover",
        selected && "bg-primary text-on-primary hover:bg-primary-hover",
        className,
      )}
      {...props}
    >
      {date.getDate()}
    </button>
  );
}

export { Calendar, CalendarDayButton };
export type { CalendarProps, DateRange };

```

# Card
White cards with the field edge, raised white panels, and lilac channel cards, all with 24px corners.

Install: npx inkbox-ds add card
Requires: theme, utils
Packages: class-variance-authority
Exports: Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, cardVariants
Client boundary: not required by this entry file
Reference: Figma 427:2715: Webhooks - Event catalog (Trigger, Delivery, Response contract), Create Agent Identity (Email, Phone Number channel cards)


## Usage
Use default for a small fact block in a grid (Trigger, Delivery, Response contract): a glyph-led 14px title and a muted description. Use raised for a white panel that sits on lilac or holds rows. Use muted for a grouped setting inside a dialog (a channel with its toggle in CardAction). Put a button or toggle in CardAction at the top right.
- Avoid: Drop shadows on default cards
- Avoid: Corners other than rounded-dialog
- Avoid: A colored header bar
- Avoid: Nesting cards more than one level


## Examples
Example components: npx inkbox-ds add card badge button
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/card/Preview) | [Channel](https://inkbox-ds.vercel.app/preview/card/Channel) | [WithFooter](https://inkbox-ds.vercel.app/preview/card/WithFooter) | [Small](https://inkbox-ds.vercel.app/preview/card/Small)

examples/card.tsx

```tsx
import { BellRingingIcon, CheckCircleIcon, EnvelopeIcon, LightningIcon, PhoneIcon, PlugsIcon } from "@phosphor-icons/react/ssr";

import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import { Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "@/components/ui/card";

export function Preview() {
  return (
    <div className="grid w-full gap-6 sm:grid-cols-3">
      <Card>
        <CardHeader>
          <CardTitle>
            <LightningIcon weight="fill" />
            Trigger
          </CardTitle>
          <CardDescription>Triggered after an inbound email is accepted and persisted to the mailbox.</CardDescription>
        </CardHeader>
      </Card>
      <Card>
        <CardHeader>
          <CardTitle>
            <BellRingingIcon weight="fill" />
            Delivery
          </CardTitle>
          <CardDescription>Fire-and-forget POST. Delivery failures are logged and do not block mail processing.</CardDescription>
        </CardHeader>
      </Card>
      <Card>
        <CardHeader>
          <CardTitle>
            <PlugsIcon weight="fill" />
            Response contract
          </CardTitle>
          <CardDescription>Any response body is ignored.</CardDescription>
        </CardHeader>
      </Card>
    </div>
  );
}

function Tile({ children }: { children: React.ReactNode }) {
  return <span className="flex size-7 shrink-0 items-center justify-center rounded-pill bg-pink text-rose">{children}</span>;
}

export function Channel() {
  return (
    <div className="grid w-full max-w-122 gap-2">
      <Card variant="muted">
        <CardHeader className="items-center">
          <CardTitle className="gap-2.5">
            <Tile>
              <EnvelopeIcon weight="fill" className="size-5.5" />
            </Tile>
            Email
          </CardTitle>
          <CardAction className="self-center">
            <Badge variant="success" size="lg">
              <CheckCircleIcon weight="fill" />
              Included
            </Badge>
          </CardAction>
        </CardHeader>
        <CardContent>
          <p className="flex h-10 items-center rounded-pill border border-line-field bg-subtle px-3.5 text-body text-fg-muted">acme-support@inboxmail.com</p>
        </CardContent>
      </Card>
      <Card variant="muted">
        <CardHeader className="items-center">
          <CardTitle className="gap-2.5">
            <Tile>
              <PhoneIcon weight="fill" className="size-5.5" />
            </Tile>
            Phone Number
          </CardTitle>
        </CardHeader>
      </Card>
    </div>
  );
}

export function WithFooter() {
  return (
    <Card variant="raised" className="w-full max-w-100">
      <CardHeader>
        <CardTitle className="text-body-lg">Custom domain</CardTitle>
        <CardDescription>Send and receive as you@yourcompany.com. Add the DNS records, then verify.</CardDescription>
        <CardAction>
          <Button variant="ghost" size="sm">Docs</Button>
        </CardAction>
      </CardHeader>
      <CardContent>
        <p className="font-mono text-body text-fg">mail.yourcompany.com</p>
      </CardContent>
      <CardFooter className="justify-end">
        <Button variant="outline">Verify domain</Button>
      </CardFooter>
    </Card>
  );
}

export function Small() {
  return (
    <Card size="sm" className="w-full max-w-72">
      <CardHeader>
        <CardTitle>Last connected</CardTitle>
        <CardDescription>Aug 8, 2026, 07:16 PM</CardDescription>
      </CardHeader>
    </Card>
  );
}

```

## Source

components/ui/card.tsx

```tsx
import * as React from "react";
import { cva, type VariantProps } from "class-variance-authority";

import { cn } from "@/lib/utils";

// The console's cards (Figma 427:2715). `default` is the webhook Trigger and Delivery card: white, a 1px #D2C9DB edge,
// 24px corners, 14px in; a 14px ink title led by a 16px filled glyph and a 14px muted description. `raised` is the white
// panel lifted by Shadow/S (a table's body). `muted` is the dialog's channel card: lilac, 24px corners, no edge, 12px above and
// below, a 16px medium title (52px tall with a 28px glyph tile). Size sm tightens the insides to 12px.
const cardVariants = cva("group/card flex flex-col gap-3 rounded-dialog py-3.5 font-sans text-body leading-body text-fg data-[size=sm]:gap-2 data-[size=sm]:py-3", {
  variants: {
    variant: {
      default: "border border-line-field bg-surface",
      raised: "bg-surface shadow-s",
      muted: "bg-subtle py-3",
    },
  },
  defaultVariants: { variant: "default" },
});

function Card({ className, variant, size = "default", ...props }: React.ComponentProps<"div"> & VariantProps<typeof cardVariants> & { size?: "default" | "sm" }) {
  return <div data-slot="card" data-variant={variant ?? "default"} data-size={size} className={cn(cardVariants({ variant }), className)} {...props} />;
}

function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="card-header"
      className={cn("grid auto-rows-min grid-rows-[auto] has-data-[slot=card-description]:grid-rows-[auto_auto] items-start gap-x-3 gap-y-2.5 px-3.5 group-data-[size=sm]/card:px-3 has-data-[slot=card-action]:grid-cols-[minmax(0,1fr)_auto]", className)}
      {...props}
    />
  );
}

function CardTitle({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="card-title"
      className={cn("flex min-w-0 items-center gap-1.5 text-body leading-body text-fg group-data-[variant=muted]/card:text-body-lg group-data-[variant=muted]/card:font-medium [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4.5", className)}
      {...props}
    />
  );
}

function CardDescription({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="card-description" className={cn("text-body leading-body text-fg-muted", className)} {...props} />;
}

function CardAction({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="card-action" className={cn("col-start-2 row-span-full flex self-start justify-self-end", className)} {...props} />;
}

function CardContent({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="card-content" className={cn("px-3.5 group-data-[size=sm]/card:px-3", className)} {...props} />;
}

function CardFooter({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="card-footer" className={cn("flex items-center gap-2 px-3.5 group-data-[size=sm]/card:px-3", className)} {...props} />;
}

export { Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, cardVariants };

```

# Carousel
A row of slides that snap into place, with white round previous and next keys outside it.

Install: npx inkbox-ds add carousel
Requires: theme, utils
Packages: @phosphor-icons/react
Exports: Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious, useCarousel, CarouselApi
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): white keys with Shadow/S


## Usage
Use to page through a set of similar cards when space is short (agent templates, integrations). Give each CarouselItem a basis for how many show at once. Leave room either side for the arrow keys, or place them yourself.
- Avoid: Autoplay
- Avoid: Dots as the only way to move
- Avoid: Slides of different heights in one row


## Examples
Example components: npx inkbox-ds add carousel
[Preview](https://inkbox-ds.vercel.app/preview/carousel/Preview) | [Sizes](https://inkbox-ds.vercel.app/preview/carousel/Sizes) | [Vertical](https://inkbox-ds.vercel.app/preview/carousel/Vertical)

examples/carousel.tsx

```tsx
import { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious } from "@/components/ui/carousel";

const TEMPLATES = [
  { name: "Support desk", text: "Answers inbound email and hands hard cases to a person." },
  { name: "Scheduler", text: "Books calls over iMessage and confirms by email." },
  { name: "Researcher", text: "Reads replies and files notes to the shared vault." },
  { name: "Recruiter", text: "Screens candidates by phone and logs each call." },
  { name: "Concierge", text: "Greets new contacts and routes them to the right agent." },
];

function Slide({ name, text }: { name: string; text: string }) {
  return (
    <div className="grid h-36 content-start gap-1 rounded-control border border-line-field bg-surface p-4">
      <p className="text-body leading-tight font-medium text-fg">{name}</p>
      <p className="text-body leading-body text-fg-muted">{text}</p>
    </div>
  );
}

export function Preview() {
  return (
    <div className="mx-auto w-full max-w-sm px-12">
      <Carousel>
        <CarouselContent>
          {TEMPLATES.map((t) => (
            <CarouselItem key={t.name}>
              <Slide {...t} />
            </CarouselItem>
          ))}
        </CarouselContent>
        <CarouselPrevious />
        <CarouselNext />
      </Carousel>
    </div>
  );
}

export function Sizes() {
  return (
    <div className="mx-auto w-full max-w-2xl px-12">
      <Carousel opts={{ align: "start" }}>
        <CarouselContent>
          {TEMPLATES.map((t) => (
            <CarouselItem key={t.name} className="sm:basis-1/2 lg:basis-1/3">
              <Slide {...t} />
            </CarouselItem>
          ))}
        </CarouselContent>
        <CarouselPrevious />
        <CarouselNext />
      </Carousel>
    </div>
  );
}

export function Vertical() {
  return (
    <div className="mx-auto w-full max-w-xs py-12">
      <Carousel orientation="vertical">
        <CarouselContent className="h-40">
          {TEMPLATES.map((t) => (
            <CarouselItem key={t.name}>
              <Slide {...t} />
            </CarouselItem>
          ))}
        </CarouselContent>
        <CarouselPrevious />
        <CarouselNext />
      </Carousel>
    </div>
  );
}

```

## Source

components/ui/carousel.tsx

```tsx
"use client";

import * as React from "react";
import { ArrowLeftIcon, ArrowRightIcon } from "@phosphor-icons/react/ssr";

import { cn } from "@/lib/utils";

// A row of slides that snap into place (extrapolated from the Inkbox console, Figma 427:2715: its white keys with
// Shadow/S and 8px corners). Slides scroll natively (touch, trackpad and wheel) and snap; the previous and next keys
// are 32px white circles with Shadow/S and an ink arrow, outside the row. Arrow keys move a slide when the carousel has
// focus. The scroll is smooth (the browser's own easing) unless reduced motion is set.

type CarouselEvent = "select" | "reInit";
type CarouselApi = {
  scrollPrev: () => void;
  scrollNext: () => void;
  scrollTo: (index: number) => void;
  canScrollPrev: () => boolean;
  canScrollNext: () => boolean;
  selectedScrollSnap: () => number;
  scrollSnapList: () => number[];
  on: (event: CarouselEvent, callback: (api: CarouselApi) => void) => void;
  off: (event: CarouselEvent, callback: (api: CarouselApi) => void) => void;
};
type CarouselOptions = { loop?: boolean; align?: "start" | "center" | "end" };

type CarouselProps = {
  opts?: CarouselOptions;
  orientation?: "horizontal" | "vertical";
  setApi?: (api: CarouselApi) => void;
};

type CarouselContextProps = {
  viewport: React.RefObject<HTMLDivElement | null>;
  orientation: "horizontal" | "vertical";
  align: "start" | "center" | "end";
  scrollPrev: () => void;
  scrollNext: () => void;
  canScrollPrev: boolean;
  canScrollNext: boolean;
  update: () => void;
};

const CarouselContext = React.createContext<CarouselContextProps | null>(null);

function useCarousel() {
  const context = React.useContext(CarouselContext);
  if (!context) throw new Error("useCarousel must be used within a <Carousel />");
  return context;
}

function Carousel({ orientation = "horizontal", opts, setApi, className, children, ...props }: React.ComponentProps<"div"> & CarouselProps) {
  const viewport = React.useRef<HTMLDivElement | null>(null);
  const [edges, setEdges] = React.useState({ prev: false, next: false, index: 0 });
  const listeners = React.useRef<Record<CarouselEvent, Set<(api: CarouselApi) => void>>>({ select: new Set(), reInit: new Set() });
  const vertical = orientation === "vertical";
  const loop = !!opts?.loop;

  const slides = React.useCallback(() => Array.from(viewport.current?.querySelectorAll<HTMLElement>(":scope > [data-slot=carousel-content] > [data-slot=carousel-item]") ?? []), []);
  const offsetOf = React.useCallback((el: HTMLElement) => (vertical ? el.offsetTop : el.offsetLeft), [vertical]);
  const current = React.useCallback(() => {
    const el = viewport.current;
    if (!el) return 0;
    const pos = vertical ? el.scrollTop : el.scrollLeft;
    const list = slides();
    let best = 0;
    list.forEach((s, i) => {
      if (Math.abs(offsetOf(s) - pos) < Math.abs(offsetOf(list[best]) - pos)) best = i;
    });
    return best;
  }, [offsetOf, slides, vertical]);

  const scrollTo = React.useCallback((index: number) => {
    const el = viewport.current;
    const list = slides();
    if (!el || !list.length) return;
    const i = loop ? (index + list.length) % list.length : Math.max(0, Math.min(list.length - 1, index));
    const reduce = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
    el.scrollTo({ [vertical ? "top" : "left"]: offsetOf(list[i]), behavior: reduce ? "auto" : "smooth" });
  }, [loop, offsetOf, slides, vertical]);

  const api = React.useMemo<CarouselApi>(() => {
    const self: CarouselApi = {
      scrollPrev: () => scrollTo(current() - 1),
      scrollNext: () => scrollTo(current() + 1),
      scrollTo,
      canScrollPrev: () => {
        const el = viewport.current;
        return !!el && (loop || (vertical ? el.scrollTop : el.scrollLeft) > 1);
      },
      canScrollNext: () => {
        const el = viewport.current;
        if (!el) return false;
        return loop || (vertical ? el.scrollTop + el.clientHeight < el.scrollHeight - 1 : el.scrollLeft + el.clientWidth < el.scrollWidth - 1);
      },
      selectedScrollSnap: current,
      scrollSnapList: () => slides().map((_, i) => i),
      on: (event, cb) => void listeners.current[event].add(cb),
      off: (event, cb) => void listeners.current[event].delete(cb),
    };
    return self;
  }, [current, loop, scrollTo, slides, vertical]);

  const update = React.useCallback(() => {
    const next = { prev: api.canScrollPrev(), next: api.canScrollNext(), index: api.selectedScrollSnap() };
    setEdges((e) => {
      if (e.index !== next.index) listeners.current.select.forEach((cb) => cb(api));
      return e.prev === next.prev && e.next === next.next && e.index === next.index ? e : next;
    });
  }, [api]);

  React.useEffect(() => {
    setApi?.(api);
    const el = viewport.current;
    if (!el) return;
    update();
    const observer = new ResizeObserver(() => {
      update();
      listeners.current.reInit.forEach((cb) => cb(api));
    });
    observer.observe(el);
    el.addEventListener("scroll", update, { passive: true });
    return () => {
      observer.disconnect();
      el.removeEventListener("scroll", update);
    };
  }, [api, setApi, update]);

  const onKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
    const back = vertical ? "ArrowUp" : "ArrowLeft";
    const forward = vertical ? "ArrowDown" : "ArrowRight";
    if (event.key === back) {
      event.preventDefault();
      api.scrollPrev();
    } else if (event.key === forward) {
      event.preventDefault();
      api.scrollNext();
    }
  };

  return (
    <CarouselContext.Provider value={{ viewport, orientation, align: opts?.align ?? "start", scrollPrev: api.scrollPrev, scrollNext: api.scrollNext, canScrollPrev: edges.prev, canScrollNext: edges.next, update }}>
      <div onKeyDownCapture={onKeyDown} className={cn("relative", className)} role="region" aria-roledescription="carousel" data-slot="carousel" data-orientation={orientation} {...props}>
        {children}
      </div>
    </CarouselContext.Provider>
  );
}

function CarouselContent({ className, ...props }: React.ComponentProps<"div">) {
  const { viewport, orientation } = useCarousel();
  const vertical = orientation === "vertical";
  return (
    <div
      ref={viewport}
      data-slot="carousel-viewport"
      className={cn("overflow-auto overscroll-contain [scrollbar-width:none] [&::-webkit-scrollbar]:hidden", vertical ? "h-full snap-y snap-mandatory" : "snap-x snap-mandatory")}
    >
      <div data-slot="carousel-content" className={cn("flex", vertical ? "-mt-4 flex-col" : "-ml-4", className)} {...props} />
    </div>
  );
}

function CarouselItem({ className, ...props }: React.ComponentProps<"div">) {
  const { orientation, align } = useCarousel();
  return (
    <div
      role="group"
      aria-roledescription="slide"
      data-slot="carousel-item"
      className={cn("min-w-0 shrink-0 grow-0 basis-full", orientation === "horizontal" ? "pl-4" : "pt-4", align === "center" ? "snap-center" : align === "end" ? "snap-end" : "snap-start", className)}
      {...props}
    />
  );
}

const ARROW =
  "absolute inline-flex size-8 items-center justify-center rounded-pill bg-surface text-fg shadow-s outline-none transition-[background-color,opacity] duration-150 ease-out hover:bg-subtle active:bg-subtle active:brightness-95 active:transition-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring disabled:pointer-events-none disabled:opacity-40 motion-reduce:transition-none [&_svg]:size-4";

function CarouselPrevious({ className, ...props }: React.ComponentProps<"button">) {
  const { orientation, scrollPrev, canScrollPrev } = useCarousel();
  return (
    <button
      type="button"
      data-slot="carousel-previous"
      disabled={!canScrollPrev}
      onClick={scrollPrev}
      className={cn(ARROW, orientation === "horizontal" ? "top-1/2 -left-12 -translate-y-1/2" : "-top-12 left-1/2 -translate-x-1/2 rotate-90", className)}
      {...props}
    >
      <ArrowLeftIcon />
      <span className="sr-only">Previous slide</span>
    </button>
  );
}

function CarouselNext({ className, ...props }: React.ComponentProps<"button">) {
  const { orientation, scrollNext, canScrollNext } = useCarousel();
  return (
    <button
      type="button"
      data-slot="carousel-next"
      disabled={!canScrollNext}
      onClick={scrollNext}
      className={cn(ARROW, orientation === "horizontal" ? "top-1/2 -right-12 -translate-y-1/2" : "-bottom-12 left-1/2 -translate-x-1/2 rotate-90", className)}
      {...props}
    >
      <ArrowRightIcon />
      <span className="sr-only">Next slide</span>
    </button>
  );
}

export { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious, useCarousel };
export type { CarouselApi };

```

# Chart
Line, area, bar and pie charts in SVG with lilac rules, 12px muted labels and a white floating tooltip.

Install: npx inkbox-ds add chart
Requires: theme, utils
Packages: none
Exports: ChartConfig, AreaChart, BarChart, ChartContainer, ChartLegend, ChartLegendContent, ChartStyle, ChartTooltip, ChartTooltipContent, LineChart, PieChart, useChart
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): muted labels, lilac rules, floating panels and the status colors


## Usage
Use to show volume over time (messages sent, calls, webhook deliveries) or a share (deliveries by status). Name and color each series in a ChartConfig, wrap the chart in ChartContainer, and add ChartTooltip and ChartLegend. Keep to five series; the colors follow the series order.
- Avoid: Gradients other than the area fade
- Avoid: 3D or shadowed marks
- Avoid: More than five series
- Avoid: Colors outside the series tokens


## Examples
Example components: npx inkbox-ds add chart
[Preview](https://inkbox-ds.vercel.app/preview/chart/Preview) | [Line](https://inkbox-ds.vercel.app/preview/chart/Line) | [Area](https://inkbox-ds.vercel.app/preview/chart/Area) | [Pie](https://inkbox-ds.vercel.app/preview/chart/Pie)

examples/chart.tsx

```tsx
"use client";

import { AreaChart, BarChart, type ChartConfig, ChartContainer, ChartLegend, ChartLegendContent, ChartTooltip, ChartTooltipContent, LineChart, PieChart } from "@/components/ui/chart";

const MESSAGES = [
  { month: "January", email: 186, imessage: 80 },
  { month: "February", email: 305, imessage: 200 },
  { month: "March", email: 237, imessage: 120 },
  { month: "April", email: 173, imessage: 190 },
  { month: "May", email: 209, imessage: 130 },
  { month: "June", email: 264, imessage: 140 },
];

const config = {
  email: { label: "Email" },
  imessage: { label: "iMessage" },
} satisfies ChartConfig;

const short = (v: string) => v.slice(0, 3);

export function Preview() {
  return (
    <ChartContainer config={config} className="aspect-auto h-80">
      <BarChart data={MESSAGES} index="month" tickFormatter={short} aria-label="Messages sent per month by channel" />
      <ChartTooltip content={<ChartTooltipContent />} />
      <ChartLegend content={<ChartLegendContent />} />
    </ChartContainer>
  );
}

export function Line() {
  return (
    <ChartContainer config={config} className="aspect-auto h-80">
      <LineChart data={MESSAGES} index="month" tickFormatter={short} showYAxis dots aria-label="Messages sent per month" />
      <ChartTooltip content={<ChartTooltipContent indicator="line" />} />
      <ChartLegend content={<ChartLegendContent />} />
    </ChartContainer>
  );
}

export function Area() {
  return (
    <ChartContainer config={config} className="aspect-auto h-80">
      <AreaChart data={MESSAGES} index="month" tickFormatter={short} stacked aria-label="Messages per month, stacked by channel" />
      <ChartTooltip content={<ChartTooltipContent indicator="dashed" />} />
    </ChartContainer>
  );
}

const DELIVERIES = [
  { status: "delivered", count: 1240 },
  { status: "retrying", count: 86 },
  { status: "failed", count: 32 },
];

const deliveryConfig = {
  delivered: { label: "Delivered", color: "var(--ds-color-chart-series-1)" },
  retrying: { label: "Retrying", color: "var(--ds-color-chart-series-2)" },
  failed: { label: "Failed", color: "var(--ds-color-chart-series-3)" },
} satisfies ChartConfig;

export function Pie() {
  return (
    <ChartContainer config={deliveryConfig} className="mx-auto aspect-square max-h-72">
      <PieChart data={DELIVERIES} index="status" value="count" aria-label="Webhook deliveries by status" />
      <ChartTooltip content={<ChartTooltipContent hideLabel />} />
      <ChartLegend content={<ChartLegendContent />} />
    </ChartContainer>
  );
}

```

## Source

components/ui/chart.tsx

```tsx
"use client";

import * as React from "react";

import { cn } from "@/lib/utils";

// Charts drawn in SVG (extrapolated from the Inkbox console, Figma 427:2715: its 12px muted labels, lilac rules, white
// floating panels and the purple, pink, blue, teal and green of its states). ChartContainer takes a config that names
// and colors each series (series-1 purple, then pink, avatar blue, info teal, success green) and holds the chart, its
// tooltip and its legend. Lines draw in from the left and bars rise from the axis once, on mount (700ms and 400ms, the
// strong ease-out); with reduced motion they fade in. Hovering or moving with the arrow keys shows the tooltip.

export type ChartConfig = Record<string, { label?: React.ReactNode; icon?: React.ComponentType<{ className?: string }>; color?: string }>;

type Datum = Record<string, string | number>;
type Active = { index: number; x: number; y: number } | null;
type ChartContextProps = {
  config: ChartConfig;
  data: Datum[];
  setData: (data: Datum[], index: string, keys: string[]) => void;
  index: string;
  keys: string[];
  active: Active;
  setActive: (active: Active) => void;
  hidden: Set<string>;
  toggle: (key: string) => void;
};

const ChartContext = React.createContext<ChartContextProps | null>(null);

function useChart() {
  const context = React.useContext(ChartContext);
  if (!context) throw new Error("useChart must be used within a <ChartContainer />");
  return context;
}

const SERIES = ["var(--ds-color-chart-series-1)", "var(--ds-color-chart-series-2)", "var(--ds-color-chart-series-3)", "var(--ds-color-chart-series-4)", "var(--ds-color-chart-series-5)"];
const colorOf = (config: ChartConfig, key: string, i: number) => `var(--color-${key}, ${config[key]?.color ?? SERIES[i % SERIES.length]})`;

/** Kept for API parity: ChartContainer already sets each series' color as --color-<key> on itself. */
function ChartStyle(_props: { id?: string; config: ChartConfig }) {
  return null;
}

function ChartContainer({ id, className, children, config, ...props }: React.ComponentProps<"div"> & { config: ChartConfig }) {
  const [data, setDataState] = React.useState<Datum[]>([]);
  const [index, setIndex] = React.useState("");
  const [keys, setKeys] = React.useState<string[]>([]);
  const [active, setActive] = React.useState<Active>(null);
  const [hidden, setHidden] = React.useState<Set<string>>(new Set());
  const setData = React.useCallback((d: Datum[], i: string, k: string[]) => {
    setDataState(d);
    setIndex(i);
    setKeys(k);
  }, []);
  const toggle = React.useCallback((key: string) => setHidden((h) => {
    const next = new Set(h);
    if (next.has(key)) next.delete(key);
    else next.add(key);
    return next;
  }), []);
  const style = Object.fromEntries(Object.entries(config).map(([key, v], i) => [`--color-${key}`, v.color ?? SERIES[i % SERIES.length]])) as React.CSSProperties;
  return (
    <ChartContext.Provider value={{ config, data, setData, index, keys, active, setActive, hidden, toggle }}>
      <div data-slot="chart" data-chart={id} style={style} className={cn("relative flex aspect-video w-full flex-col justify-center font-sans text-caption text-fg-muted", className)} {...props}>
        {children}
      </div>
    </ChartContext.Provider>
  );
}

function useSize<T extends HTMLElement>() {
  const ref = React.useRef<T>(null);
  const [size, setSize] = React.useState({ width: 0, height: 0 });
  React.useLayoutEffect(() => {
    const el = ref.current;
    if (!el) return;
    const observer = new ResizeObserver(([entry]) => setSize({ width: entry.contentRect.width, height: entry.contentRect.height }));
    observer.observe(el);
    return () => observer.disconnect();
  }, []);
  return [ref, size] as const;
}

const PAD = { top: 12, right: 12, bottom: 28, left: 12 };

function niceMax(max: number) {
  if (max <= 0) return 1;
  const step = 10 ** Math.floor(Math.log10(max));
  return Math.ceil(max / step) * step;
}

/** A smooth path through the points (monotone in x), or straight segments. */
function pathOf(points: [number, number][], curve: "monotone" | "linear") {
  if (!points.length) return "";
  if (curve === "linear" || points.length < 3) return points.map(([x, y], i) => `${i ? "L" : "M"}${x},${y}`).join("");
  let d = `M${points[0][0]},${points[0][1]}`;
  for (let i = 0; i < points.length - 1; i++) {
    const [x0, y0] = points[i - 1] ?? points[i];
    const [x1, y1] = points[i];
    const [x2, y2] = points[i + 1];
    const [x3, y3] = points[i + 2] ?? points[i + 1];
    const c1 = [x1 + (x2 - x0) / 6, y1 + (y2 - y0) / 6];
    const c2 = [x2 - (x3 - x1) / 6, y2 - (y3 - y1) / 6];
    d += `C${c1[0]},${c1[1]} ${c2[0]},${c2[1]} ${x2},${y2}`;
  }
  return d;
}

type CartesianProps = {
  data: Datum[];
  /** The key of each datum's label on the x axis (month, day). */
  index: string;
  /** The series to draw, in order; defaults to every key in the config. */
  keys?: string[];
  showGrid?: boolean;
  showXAxis?: boolean;
  showYAxis?: boolean;
  /** Format the x labels (e.g. the first three letters of a month). */
  tickFormatter?: (value: string) => string;
  valueFormatter?: (value: number) => string;
  className?: string;
  "aria-label"?: string;
};

function useCartesian(kind: "line" | "area" | "bar", { data, index, keys: keysProp, showYAxis }: CartesianProps, stacked: boolean) {
  const chart = useChart();
  const keys = React.useMemo(() => keysProp ?? Object.keys(chart.config), [keysProp, chart.config]);
  const { setData } = chart;
  React.useEffect(() => setData(data, index, keys), [data, index, keys, setData]);
  const [ref, size] = useSize<HTMLDivElement>();
  const visible = keys.filter((k) => !chart.hidden.has(k));
  const values = data.map((d) => (stacked ? visible.reduce((s, k) => s + Number(d[k] ?? 0), 0) : Math.max(0, ...visible.map((k) => Number(d[k] ?? 0)))));
  const max = niceMax(Math.max(0, ...values));
  const left = PAD.left + (showYAxis ? 32 : 0);
  const innerW = Math.max(0, size.width - left - PAD.right);
  // Lines and areas keep their first and last points (and labels) clear of the edges.
  const inset = kind === "bar" ? 0 : 16;
  const innerH = Math.max(0, size.height - PAD.top - PAD.bottom);
  const band = data.length ? innerW / data.length : 0;
  const xAt = (i: number) => (kind === "bar" ? left + band * i + band / 2 : left + inset + (data.length > 1 ? ((innerW - inset * 2) * i) / (data.length - 1) : innerW / 2 - inset));
  const yAt = (v: number) => PAD.top + innerH - (innerH * v) / max;
  return { chart, keys, visible, ref, size, max, left, innerW, innerH, band, xAt, yAt };
}

function Frame({ kind, props, geometry, children }: { kind: "line" | "area" | "bar"; props: CartesianProps; geometry: ReturnType<typeof useCartesian>; children: React.ReactNode }) {
  const { chart, ref, size, max, left, innerW, innerH, band, xAt, yAt } = geometry;
  const { data, index, showGrid = true, showXAxis = true, showYAxis = false, tickFormatter = (v: string) => v, valueFormatter = (v: number) => v.toLocaleString() } = props;
  const ticks = [0, 0.25, 0.5, 0.75, 1].map((t) => max * t);
  const pick = (clientX: number, rect: DOMRect) => {
    const x = clientX - rect.left;
    let best = 0;
    for (let i = 0; i < data.length; i++) if (Math.abs(xAt(i) - x) < Math.abs(xAt(best) - x)) best = i;
    return best;
  };
  const activate = (i: number) => chart.setActive({ index: i, x: xAt(i), y: PAD.top });
  const labelStep = Math.max(1, Math.ceil(data.length / Math.max(1, Math.floor(innerW / 56))));
  return (
    <div ref={ref} className={cn("relative h-full min-h-0 w-full flex-1", props.className)}>
      {size.width > 0 && (
        <svg
          width={size.width}
          height={size.height}
          role="img"
          tabIndex={0}
          aria-label={props["aria-label"] ?? "Chart"}
          className="block overflow-visible rounded-control outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring"
          onPointerMove={(e) => activate(pick(e.clientX, e.currentTarget.getBoundingClientRect()))}
          onPointerLeave={() => chart.setActive(null)}
          onBlur={() => chart.setActive(null)}
          onFocus={() => activate(chart.active?.index ?? 0)}
          onKeyDown={(e) => {
            if (e.key !== "ArrowLeft" && e.key !== "ArrowRight") return;
            e.preventDefault();
            const current = chart.active?.index ?? 0;
            activate(Math.min(data.length - 1, Math.max(0, current + (e.key === "ArrowRight" ? 1 : -1))));
          }}
        >
          {showGrid && ticks.map((t) => <line key={t} x1={left} x2={left + innerW} y1={yAt(t)} y2={yAt(t)} className="stroke-line-subtle" strokeWidth={1} strokeDasharray={t === 0 ? undefined : "3 3"} />)}
          {showYAxis && ticks.map((t) => (
            <text key={t} x={left - 8} y={yAt(t)} dy="0.32em" textAnchor="end" className="fill-fg-muted text-caption">
              {valueFormatter(t)}
            </text>
          ))}
          {chart.active && kind !== "bar" && <line x1={xAt(chart.active.index)} x2={xAt(chart.active.index)} y1={PAD.top} y2={PAD.top + innerH} className="stroke-line-field" strokeWidth={1} />}
          {chart.active && kind === "bar" && <rect x={xAt(chart.active.index) - band / 2} y={PAD.top} width={band} height={innerH} rx={6} className="fill-subtle" />}
          {children}
          {showXAxis && data.map((d, i) => (i % labelStep === 0 ? (
            <text key={i} x={xAt(i)} y={PAD.top + innerH + 18} textAnchor="middle" className="fill-fg-muted text-caption">
              {tickFormatter(String(d[index]))}
            </text>
          ) : null))}
        </svg>
      )}
    </div>
  );
}

function LineChart(props: CartesianProps & { curve?: "monotone" | "linear"; dots?: boolean }) {
  const g = useCartesian("line", props, false);
  const { curve = "monotone", dots = false } = props;
  return (
    <Frame kind="line" props={props} geometry={g}>
      {g.visible.map((key) => {
        const i = g.keys.indexOf(key);
        const points = props.data.map((d, n) => [g.xAt(n), g.yAt(Number(d[key] ?? 0))] as [number, number]);
        return (
          <g key={key} data-series={key}>
            <path d={pathOf(points, curve)} fill="none" stroke={colorOf(g.chart.config, key, i)} strokeWidth={2} strokeLinecap="round" strokeLinejoin="round" pathLength={1} strokeDasharray="1 1" className="animate-chart-line" />
            {(dots || g.chart.active) && points.map(([x, y], n) => (dots || g.chart.active?.index === n ? <circle key={n} cx={x} cy={y} r={g.chart.active?.index === n ? 4 : 3} fill="var(--ds-color-bg-default)" stroke={colorOf(g.chart.config, key, i)} strokeWidth={2} /> : null))}
          </g>
        );
      })}
    </Frame>
  );
}

function AreaChart(props: CartesianProps & { curve?: "monotone" | "linear"; stacked?: boolean }) {
  const { curve = "monotone", stacked = false } = props;
  const g = useCartesian("area", props, stacked);
  const base = props.data.map(() => 0);
  const id = React.useId().replace(/:/g, "");
  return (
    <Frame kind="area" props={props} geometry={g}>
      <defs>
        {g.visible.map((key) => (
          <linearGradient key={key} id={`${id}-${key}`} x1="0" x2="0" y1="0" y2="1">
            <stop offset="0%" stopColor={colorOf(g.chart.config, key, g.keys.indexOf(key))} stopOpacity={0.32} />
            <stop offset="100%" stopColor={colorOf(g.chart.config, key, g.keys.indexOf(key))} stopOpacity={0.02} />
          </linearGradient>
        ))}
      </defs>
      {g.visible.map((key) => {
        const i = g.keys.indexOf(key);
        const lows = stacked ? [...base] : props.data.map(() => 0);
        const highs = props.data.map((d, n) => lows[n] + Number(d[key] ?? 0));
        if (stacked) highs.forEach((h, n) => (base[n] = h));
        const top = highs.map((v, n) => [g.xAt(n), g.yAt(v)] as [number, number]);
        const bottom = lows.map((v, n) => [g.xAt(n), g.yAt(v)] as [number, number]).reverse();
        const line = pathOf(top, curve);
        const area = `${line}L${bottom.map(([x, y]) => `${x},${y}`).join("L")}Z`;
        return (
          <g key={key} data-series={key}>
            <path d={area} fill={`url(#${id}-${key})`} className="animate-fade-in" />
            <path d={line} fill="none" stroke={colorOf(g.chart.config, key, i)} strokeWidth={2} strokeLinecap="round" pathLength={1} strokeDasharray="1 1" className="animate-chart-line" />
          </g>
        );
      })}
    </Frame>
  );
}

function BarChart(props: CartesianProps & { stacked?: boolean; radius?: number }) {
  const { stacked = false, radius = 4 } = props;
  const g = useCartesian("bar", props, stacked);
  const gap = 4;
  const groupW = Math.max(0, g.band * 0.72);
  const barW = stacked ? groupW : Math.max(2, (groupW - gap * (g.visible.length - 1)) / Math.max(1, g.visible.length));
  return (
    <Frame kind="bar" props={props} geometry={g}>
      {props.data.map((d, n) => {
        let acc = 0;
        return (
          <g key={n}>
            {g.visible.map((key, k) => {
              const value = Number(d[key] ?? 0);
              const x = stacked ? g.xAt(n) - groupW / 2 : g.xAt(n) - groupW / 2 + k * (barW + gap);
              const y0 = g.yAt(acc);
              const y1 = g.yAt(acc + value);
              if (stacked) acc += value;
              const top = !stacked || k === g.visible.length - 1;
              return (
                <rect
                  key={key}
                  x={x}
                  y={y1}
                  width={barW}
                  height={Math.max(0, y0 - y1)}
                  rx={top ? Math.min(radius, barW / 2) : 0}
                  fill={colorOf(g.chart.config, key, g.keys.indexOf(key))}
                  style={{ transformOrigin: `0 ${g.yAt(0)}px`, animationDelay: `${n * 30}ms` }}
                  className="animate-chart-bar"
                />
              );
            })}
          </g>
        );
      })}
    </Frame>
  );
}

function PieChart({ data, index, value, innerRadius = 0.6, className, ...props }: { data: Datum[]; index: string; value: string; innerRadius?: number; className?: string; "aria-label"?: string }) {
  const chart = useChart();
  const { setData } = chart;
  React.useEffect(() => setData(data, index, [value]), [data, index, value, setData]);
  const [ref, size] = useSize<HTMLDivElement>();
  const shown = data.filter((d) => !chart.hidden.has(String(d[index])));
  const total = shown.reduce((s, d) => s + Number(d[value] ?? 0), 0) || 1;
  const r = Math.max(0, Math.min(size.width, size.height) / 2 - 8);
  const cx = size.width / 2;
  const cy = size.height / 2;
  let angle = -Math.PI / 2;
  return (
    <div ref={ref} className={cn("relative h-full min-h-0 w-full flex-1", className)}>
      {r > 0 && (
        <svg width={size.width} height={size.height} role="img" aria-label={props["aria-label"] ?? "Chart"} className="block animate-pop-in origin-center" onPointerLeave={() => chart.setActive(null)}>
          {shown.map((d) => {
            const key = String(d[index]);
            const n = data.indexOf(d);
            const sweep = (Number(d[value] ?? 0) / total) * Math.PI * 2;
            const a0 = angle;
            const a1 = angle + sweep;
            angle = a1;
            const ri = r * innerRadius;
            const large = sweep > Math.PI ? 1 : 0;
            const p = (a: number, rr: number) => `${cx + rr * Math.cos(a)},${cy + rr * Math.sin(a)}`;
            const dPath = sweep >= Math.PI * 2 - 1e-6
              ? `M${cx - r},${cy}a${r},${r} 0 1,0 ${r * 2},0a${r},${r} 0 1,0 ${-r * 2},0${ri ? `M${cx - ri},${cy}a${ri},${ri} 0 1,1 ${ri * 2},0a${ri},${ri} 0 1,1 ${-ri * 2},0` : ""}`
              : `M${p(a0, r)}A${r},${r} 0 ${large} 1 ${p(a1, r)}${ri ? `L${p(a1, ri)}A${ri},${ri} 0 ${large} 0 ${p(a0, ri)}` : `L${cx},${cy}`}Z`;
            return (
              <path
                key={key}
                d={dPath}
                fillRule="evenodd"
                fill={colorOf(chart.config, key, n)}
                stroke="var(--ds-color-bg-default)"
                strokeWidth={2}
                className={cn("transition-opacity duration-150 ease-out", chart.active && chart.active.index !== n && "opacity-60")}
                onPointerMove={(e) => {
                  const rect = e.currentTarget.ownerSVGElement!.getBoundingClientRect();
                  chart.setActive({ index: n, x: e.clientX - rect.left, y: e.clientY - rect.top });
                }}
              />
            );
          })}
        </svg>
      )}
    </div>
  );
}

type TooltipItem = { key: string; name: React.ReactNode; value: number; color: string };

/** Where the tooltip shows: pass `content` (usually <ChartTooltipContent />). It follows the hovered point. */
function ChartTooltip({ content, cursor: _cursor }: { content?: React.ReactElement<ChartTooltipContentProps>; cursor?: boolean }) {
  const chart = useChart();
  if (!chart.active || !chart.data.length) return null;
  const datum = chart.data[chart.active.index];
  if (!datum) return null;
  const pie = chart.keys.length === 1 && !(chart.keys[0] in chart.config) && String(datum[chart.index]) in chart.config;
  const payload: TooltipItem[] = pie
    ? [{ key: String(datum[chart.index]), name: chart.config[String(datum[chart.index])]?.label ?? String(datum[chart.index]), value: Number(datum[chart.keys[0]] ?? 0), color: colorOf(chart.config, String(datum[chart.index]), chart.active.index) }]
    : chart.keys.filter((k) => !chart.hidden.has(k)).map((k, i) => ({ key: k, name: chart.config[k]?.label ?? k, value: Number(datum[k] ?? 0), color: colorOf(chart.config, k, chart.keys.indexOf(k) ?? i) }));
  const element = content ?? <ChartTooltipContent />;
  return (
    <div
      data-slot="chart-tooltip"
      role="status"
      className="pointer-events-none absolute z-10 animate-fade-in"
      style={{ left: chart.active.x, top: chart.active.y, transform: `translate(${chart.active.x > 160 ? "calc(-100% - 12px)" : "12px"}, 0)` }}
    >
      {React.cloneElement(element, { payload, label: pie ? undefined : String(datum[chart.index]) })}
    </div>
  );
}

type ChartTooltipContentProps = React.ComponentProps<"div"> & {
  payload?: TooltipItem[];
  label?: string;
  indicator?: "dot" | "line" | "dashed";
  hideLabel?: boolean;
  hideIndicator?: boolean;
  labelFormatter?: (label: string) => React.ReactNode;
  formatter?: (value: number, name: React.ReactNode, key: string) => React.ReactNode;
};

/** The tooltip's panel: white, 16px corners, the floating shadow, the label in 13px medium ink, a row per series. */
function ChartTooltipContent({ payload = [], label, indicator = "dot", hideLabel = false, hideIndicator = false, labelFormatter, formatter, className, ...props }: ChartTooltipContentProps) {
  return (
    <div data-slot="chart-tooltip-content" className={cn("grid min-w-32 gap-1.5 rounded-panel bg-surface px-3 py-2 text-caption leading-tight text-fg shadow-floating", className)} {...props}>
      {!hideLabel && label !== undefined && <p className="text-body-sm font-medium text-fg">{labelFormatter ? labelFormatter(label) : label}</p>}
      <div className="grid gap-1">
        {payload.map((item) => (
          <div key={item.key} className="flex items-center gap-2">
            {!hideIndicator && (
              <span
                aria-hidden
                className={cn("shrink-0", indicator === "dot" ? "size-2.5 rounded-xs" : "h-3 w-1 rounded-xs", indicator === "dashed" && "border border-dashed bg-transparent")}
                style={indicator === "dashed" ? { borderColor: item.color } : { background: item.color }}
              />
            )}
            {formatter ? formatter(item.value, item.name, item.key) : (
              <>
                <span className="text-fg-muted">{item.name}</span>
                <span className="ml-auto pl-3 font-medium text-fg tabular-nums">{item.value.toLocaleString()}</span>
              </>
            )}
          </div>
        ))}
      </div>
    </div>
  );
}

/** Where the legend shows: pass `content` (usually <ChartLegendContent />). */
function ChartLegend({ content, verticalAlign = "bottom" }: { content?: React.ReactElement<React.ComponentProps<typeof ChartLegendContent>>; verticalAlign?: "top" | "bottom" }) {
  const element = content ?? <ChartLegendContent />;
  return <div className={cn(verticalAlign === "top" ? "order-first pb-3" : "pt-3")}>{element}</div>;
}

/** A row of 12px muted labels with their color keys; each toggles its series when `interactive`. */
function ChartLegendContent({ className, hideIcon = false, interactive = true, ...props }: React.ComponentProps<"div"> & { hideIcon?: boolean; interactive?: boolean }) {
  const chart = useChart();
  const keys = chart.keys.length === 1 && !(chart.keys[0] in chart.config) ? chart.data.map((d) => String(d[chart.index])) : chart.keys;
  return (
    <div data-slot="chart-legend-content" className={cn("flex flex-wrap items-center justify-center gap-x-4 gap-y-1.5", className)} {...props}>
      {keys.map((key, i) => {
        const item = chart.config[key];
        const Icon = item?.icon;
        const off = chart.hidden.has(key);
        const body = (
          <>
            {Icon && !hideIcon ? <Icon className="size-3.5" /> : <span aria-hidden className="size-2.5 rounded-xs" style={{ background: colorOf(chart.config, key, i) }} />}
            {item?.label ?? key}
          </>
        );
        return interactive ? (
          <button key={key} type="button" aria-pressed={!off} onClick={() => chart.toggle(key)} className={cn("inline-flex items-center gap-1.5 rounded-pill text-caption leading-tight text-fg-secondary outline-none transition-opacity duration-150 ease-out focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring motion-reduce:transition-none", off && "opacity-40")}>
            {body}
          </button>
        ) : (
          <span key={key} className="inline-flex items-center gap-1.5 text-caption leading-tight text-fg-secondary">
            {body}
          </span>
        );
      })}
    </div>
  );
}

export { AreaChart, BarChart, ChartContainer, ChartLegend, ChartLegendContent, ChartStyle, ChartTooltip, ChartTooltipContent, LineChart, PieChart, useChart };

```

# Checkbox
An 18px box with 4px corners and a gray edge that fills purple with a white check.

Install: npx inkbox-ds add checkbox
Requires: theme, utils
Packages: @chakra-ui/react, @phosphor-icons/react
Exports: Checkbox
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the radios' 18px size and gray edge, the action purple and the white checks


## Usage
Use for independent on or off choices that apply when a form is submitted (event subscriptions, consent). Pair each checkbox with a Label 8px to its right. Use the indeterminate state for a parent that covers some of its children. For a setting that applies at once use Switch.
- Avoid: A pink checked box
- Avoid: A round checkbox
- Avoid: A checkbox that acts immediately like a switch


## Examples
Example components: npx inkbox-ds add checkbox label
[Preview](https://inkbox-ds.vercel.app/preview/checkbox/Preview) | [States](https://inkbox-ds.vercel.app/preview/checkbox/States)

examples/checkbox.tsx

```tsx
"use client";

import * as React from "react";

import { Checkbox } from "@/components/ui/checkbox";
import { Label } from "@/components/ui/label";

const EVENTS = ["message.received", "message.sent", "message.delivered"];

export function Preview() {
  const [chosen, setChosen] = React.useState<string[]>(["message.received"]);
  const all = chosen.length === EVENTS.length ? true : chosen.length ? "indeterminate" : false;
  return (
    <div className="grid gap-2.5">
      <div className="flex items-center gap-2">
        <Checkbox id="all-events" checked={all} onCheckedChange={(v) => setChosen(v === true ? EVENTS : [])} />
        <Label htmlFor="all-events" className="font-medium">All email events</Label>
      </div>
      <div className="grid gap-2.5 pl-6.5">
        {EVENTS.map((e) => (
          <div key={e} className="flex items-center gap-2">
            <Checkbox id={e} checked={chosen.includes(e)} onCheckedChange={(v) => setChosen((c) => (v === true ? [...c, e] : c.filter((x) => x !== e)))} />
            <Label htmlFor={e} className="font-mono">{e}</Label>
          </div>
        ))}
      </div>
    </div>
  );
}

export function States() {
  return (
    <div className="grid gap-2.5">
      <div className="flex items-center gap-2">
        <Checkbox id="c1" />
        <Label htmlFor="c1">Unchecked</Label>
      </div>
      <div className="flex items-center gap-2">
        <Checkbox id="c2" defaultChecked />
        <Label htmlFor="c2">Checked</Label>
      </div>
      <div className="flex items-center gap-2">
        <Checkbox id="c3" checked="indeterminate" />
        <Label htmlFor="c3">Some of them</Label>
      </div>
      <div className="flex items-center gap-2">
        <Checkbox id="c4" disabled />
        <Label htmlFor="c4">Disabled</Label>
      </div>
      <div className="flex items-center gap-2">
        <Checkbox id="c5" aria-invalid />
        <Label htmlFor="c5">I accept the Terms of Service (required)</Label>
      </div>
    </div>
  );
}

```

## Source

components/ui/checkbox.tsx

```tsx
"use client";

import * as React from "react";
import { Checkbox as ChakraCheckbox } from "@chakra-ui/react";
import { CheckIcon, MinusIcon } from "@phosphor-icons/react/ssr";

import { cn } from "@/lib/utils";

// Extrapolated from the console's radios and checks (Figma 427:2715): an 18px box with 4px corners and the radio's
// 1.5px gray edge on white; checked or mixed it fills with the action purple and shows a bold white check (or dash).
// Its label sits 8px away in 14px ink.
type CheckboxProps = Omit<React.ComponentProps<typeof ChakraCheckbox.Root>, "onCheckedChange"> & { onCheckedChange?: (checked: boolean | "indeterminate") => void };

function Checkbox({ className, onCheckedChange, ...props }: CheckboxProps) {
  return (
    <ChakraCheckbox.Root
      data-slot="checkbox"
      className={cn(
        "peer inline-flex size-4.5 shrink-0 cursor-pointer items-center justify-center rounded-pill border-[1.5px] border-line-strong bg-surface text-on-primary outline-none active:brightness-95 active:transition-none transition-[background-color,border-color] duration-150 ease-out hover:border-fg-muted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-danger data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=indeterminate]:border-primary data-[state=indeterminate]:bg-primary motion-reduce:transition-none",
        className,
      )}
      onCheckedChange={(details) => onCheckedChange?.(details.checked)}
      {...props}
    >
      <ChakraCheckbox.HiddenInput />
      <ChakraCheckbox.Control data-slot="checkbox-control" className="contents">
        <ChakraCheckbox.Indicator data-slot="checkbox-indicator" className="group/indicator flex items-center justify-center text-current">
          <CheckIcon weight="bold" className="size-3.5 group-data-[state=indeterminate]/indicator:hidden" />
          <MinusIcon weight="bold" className="hidden size-3.5 group-data-[state=indeterminate]/indicator:block" />
        </ChakraCheckbox.Indicator>
      </ChakraCheckbox.Control>
    </ChakraCheckbox.Root>
  );
}

export { Checkbox };

```

# Code Block
The event catalog's code viewer: a gray head with the language and a copy glyph over an off-white body with line numbers.

Install: npx inkbox-ds add code-block
Requires: theme, utils
Packages: @phosphor-icons/react
Exports: CodeBlock, CodeBlockActions, CodeBlockContent, CodeBlockCopyButton, CodeBlockHeader, CodeBlockTitle, tokenize
Client boundary: yes
Reference: Figma 427:2715: Webhooks - Event catalog (Signature headers, Payload example)


## Usage
Use to show a payload, headers or a snippet someone will read or copy (Signature headers, Payload example). Give it a CodeBlockHeader with the language and a CodeBlockCopyButton, then CodeBlockContent with the code. Pass wrap for long single values such as signatures.
- Avoid: A dark code block
- Avoid: Code in Inter
- Avoid: Highlight colors outside the editor theme


## Examples
Example components: npx inkbox-ds add code-block
Example packages: @inkbox/sdk
[Preview](https://inkbox-ds.vercel.app/preview/code-block/Preview) | [Script](https://inkbox-ds.vercel.app/preview/code-block/Script)

examples/code-block.tsx

```tsx
import { CodeBlock, CodeBlockActions, CodeBlockContent, CodeBlockCopyButton, CodeBlockHeader, CodeBlockTitle } from "@/components/ui/code-block";

const HEADERS = `{
  "X-Inkbox-Request-ID": "b4f64d39-7cf0-4c89-b2fa-3522091e979d",
  "X-Inkbox-Timestamp": "1764875501",
  "X-Inkbox-Signature": "sha256=2f8d6b7f37b7d6461f7b8a91f4f495eb54f60af8f4a1f9d3edfdc7d2adf237f2"
}`;

const SNIPPET = `import { Inkbox } from "@inkbox/sdk";

// Send the agent's first email.
const inkbox = new Inkbox({ apiKey: process.env.INKBOX_API_KEY });
await inkbox.mail.send({ to: "you@example.com", subject: "Hello" });`;

export function Preview() {
  return (
    <CodeBlock>
      <CodeBlockHeader>
        <CodeBlockTitle language="json">JSON</CodeBlockTitle>
        <CodeBlockActions>
          <CodeBlockCopyButton value={HEADERS} />
        </CodeBlockActions>
      </CodeBlockHeader>
      <CodeBlockContent code={HEADERS} language="json" wrap />
    </CodeBlock>
  );
}

export function Script() {
  return (
    <CodeBlock>
      <CodeBlockHeader>
        <CodeBlockTitle>send.ts</CodeBlockTitle>
        <CodeBlockActions>
          <CodeBlockCopyButton value={SNIPPET} />
        </CodeBlockActions>
      </CodeBlockHeader>
      <CodeBlockContent code={SNIPPET} language="ts" />
    </CodeBlock>
  );
}

```

## Source

components/ui/code-block.tsx

```tsx
"use client";

import * as React from "react";
import { BracketsCurlyIcon, CheckIcon, CopyIcon } from "@phosphor-icons/react/ssr";

import { cn } from "@/lib/utils";

// The event catalog's code block (Figma 427:2715, Webhooks: Signature headers, Payload example): 8px corners and the
// editor's gray edge, a 40px gray head with the language (yellow braces for JSON) and a purple copy glyph, then the
// off-white body in the system monospace at 14px on 20px lines, line numbers in the editor's teal (the first line's
// darker), and the Light+ colors: red keys, blue values and braces. Long lines scroll, or wrap with `wrap`.
function CodeBlock({ className, ...props }: React.ComponentProps<"figure">) {
  return <figure data-slot="code-block" className={cn("group/code-block m-0 flex w-full min-w-0 flex-col overflow-hidden rounded-control border border-line-code bg-code text-code-text", className)} {...props} />;
}

function CodeBlockHeader({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="code-block-header" className={cn("flex h-10 min-w-0 shrink-0 items-center gap-2 border-b border-line-code bg-code-head pr-1.5 pl-3", className)} {...props} />;
}

function CodeBlockTitle({ className, children, language, ...props }: React.ComponentProps<"figcaption"> & { language?: string }) {
  return (
    <figcaption data-slot="code-block-title" className={cn("flex min-w-0 items-center gap-2 font-sans text-body leading-tight text-code-head-fg [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4", className)} {...props}>
      {language === "json" && <BracketsCurlyIcon aria-hidden className="text-code-brace" />}
      <span className="truncate">{children}</span>
    </figcaption>
  );
}

function CodeBlockActions({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="code-block-actions" className={cn("ml-auto flex shrink-0 items-center gap-1", className)} {...props} />;
}

function CodeBlockCopyButton({ value, className, ...props }: Omit<React.ComponentProps<"button">, "value" | "children"> & { value: string }) {
  const [state, setState] = React.useState<"idle" | "copied" | "failed">("idle");
  React.useEffect(() => {
    if (state === "idle") return;
    // ds-latency: resets completed clipboard feedback without delaying the copy action.
    const timeout = setTimeout(() => setState("idle"), 2000);
    return () => clearTimeout(timeout);
  }, [state]);
  return (
    <>
      <button
        type="button"
        data-slot="code-block-copy-button"
        data-copied={state === "copied" || undefined}
        aria-label={state === "copied" ? "Copied" : "Copy code"}
        onClick={() => navigator.clipboard.writeText(value).then(() => setState("copied"), () => setState("failed"))}
        className={cn("inline-flex size-8 items-center justify-center rounded-pill text-fg-brand outline-none transition-[background-color] duration-150 ease-out hover:bg-surface active:bg-surface active:brightness-95 active:transition-none focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus-ring motion-reduce:transition-none", className)}
        {...props}
      >
        {state === "copied" ? <CheckIcon className="size-4.5" weight="bold" /> : <CopyIcon className="size-4.5" weight="duotone" />}
      </button>
      <span aria-live="polite" className="sr-only">
        {state === "copied" ? "Copied" : state === "failed" ? "Copy failed. Select the code and copy it." : ""}
      </span>
    </>
  );
}

type Kind = "key" | "string" | "punct" | "keyword" | "comment" | "number" | "function" | "type" | "tag" | "attr" | "plain";
const COLOR: Record<Kind, string | undefined> = {
  key: "text-code-key",
  string: "text-code-string",
  punct: "text-code-punct",
  keyword: "text-code-keyword",
  comment: "text-code-comment",
  number: "text-code-number",
  function: "text-code-function",
  type: "text-code-type",
  tag: "text-code-tag",
  attr: "text-code-attr",
  plain: undefined,
};

const KEYWORDS = /^(?:import|from|export|default|function|return|const|let|var|if|else|for|of|in|new|type|interface|extends|as|async|await|true|false|null|undefined|class|this|throw|try|catch)$/;

/** Splits code into colored runs for the Light+ theme. JSON keys are red and values blue; in scripts strings are red. */
function tokenize(code: string, language: string): { kind: Kind; text: string }[] {
  const out: { kind: Kind; text: string }[] = [];
  const push = (kind: Kind, text: string) => (text ? out.push({ kind, text }) : undefined);
  if (language === "json") {
    for (const m of code.matchAll(/("(?:\\.|[^"\\])*")(\s*:)?|(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)|(true|false|null)|([{}[\]])|([^"{}[\]\d\-tfn]+|[\s\S])/g)) {
      if (m[1]) {
        push(m[2] ? "key" : "string", m[1]);
        push("plain", m[2] ?? "");
      } else if (m[3]) push("number", m[3]);
      else if (m[4]) push("keyword", m[4]);
      else if (m[5]) push("punct", m[5]);
      else push("plain", m[0]);
    }
    return out;
  }
  if (language === "bash" || language === "sh" || language === "shell") {
    for (const line of code.split(/(\n)/)) {
      if (line === "\n") push("plain", line);
      else if (/^\s*#/.test(line)) push("comment", line);
      else
        for (const [i, m] of [...line.matchAll(/("[^"]*"|'[^']*')|(\s--?[\w-]+)|(\S+|\s+)/g)].entries()) {
          if (m[1]) push("string", m[1]);
          else if (m[2]) push("keyword", m[2]);
          else push(i === 0 || (i === 1 && /^\s/.test(line)) ? "function" : "plain", m[0]);
        }
    }
    return out;
  }
  const pattern = /(\/\/[^\n]*|\/\*[\s\S]*?\*\/)|("(?:\\.|[^"\\\n])*"|'(?:\\.|[^'\\\n])*'|`(?:\\.|[^`\\])*`)|(<\/?)([A-Za-z][\w.]*)|([A-Za-z_$][\w-]*)(=)|\b(\d+(?:\.\d+)?)\b|([A-Za-z_$][\w$]*)(?=\s*\()|([A-Z][\w$]*)|([A-Za-z_$][\w$]*)|([\s\S])/g;
  for (const m of code.matchAll(pattern)) {
    if (m[1]) push("comment", m[1]);
    else if (m[2]) push("string", m[2]);
    else if (m[3]) {
      push("punct", m[3]);
      push("tag", m[4]);
    } else if (m[5]) {
      push("attr", m[5]);
      push("plain", m[6]);
    } else if (m[7]) push("number", m[7]);
    else if (m[8]) push(KEYWORDS.test(m[8]) ? "keyword" : "function", m[8]);
    else if (m[9]) push("type", m[9]);
    else if (m[10]) push(KEYWORDS.test(m[10]) ? "keyword" : "plain", m[10]);
    else push("plain", m[11]);
  }
  return out.map((t) => (t.kind === "string" ? { ...t, kind: "key" as Kind } : t));
}

/** Draws the editor's indent guides: each two spaces of leading indentation becomes a cell with a hairline in it. */
function withGuides(line: { kind: Kind; text: string }[]): { kind: Kind | "guide"; text: string }[] {
  const first = line[0];
  const indent = first?.kind === "plain" ? (first.text.match(/^ +/)?.[0].length ?? 0) : 0;
  const levels = Math.floor(indent / 2);
  if (!levels) return line;
  const rest = first.text.slice(levels * 2);
  return [...Array.from({ length: levels }, () => ({ kind: "guide" as const, text: "  " })), ...(rest ? [{ kind: "plain" as Kind, text: rest }] : []), ...line.slice(1)];
}

/**
 * The code itself. Pass the text as `code` and its `language` (json, tsx, ts, css, bash); line numbers show by default.
 * `wrap` breaks long lines instead of scrolling; `maxHeight` scrolls a long file inside the block.
 */
function CodeBlockContent({ code, language = "tsx", lineNumbers = true, wrap = false, className, ...props }: Omit<React.ComponentProps<"pre">, "children"> & { code: string; language?: string; lineNumbers?: boolean; wrap?: boolean }) {
  const lines = React.useMemo(() => {
    const rows: { kind: Kind; text: string }[][] = [[]];
    for (const token of tokenize(code.replace(/\n$/, ""), language)) {
      const parts = token.text.split("\n");
      parts.forEach((part, i) => {
        if (i > 0) rows.push([]);
        if (part) rows[rows.length - 1].push({ kind: token.kind, text: part });
      });
    }
    return rows;
  }, [code, language]);
  return (
    <pre
      data-slot="code-block-content"
      tabIndex={0}
      className={cn("m-0 overflow-auto bg-code py-3 font-code text-body leading-5 outline-none [scrollbar-width:thin] [tab-size:2] focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus-ring", className)}
      {...props}
    >
      <code className={cn("grid", wrap ? "grid-cols-[minmax(0,1fr)]" : "min-w-max")}>
        {lines.map((line, i) => (
          <span key={i} className={cn("grid", lineNumbers ? "grid-cols-[3rem_minmax(0,1fr)]" : "grid-cols-[minmax(0,1fr)] pl-4", wrap && "min-w-0")}>
            {lineNumbers && (
              <span aria-hidden className={cn("pr-4 text-right select-none", i === 0 ? "text-code-line-active" : "text-code-line")}>
                {i + 1}
              </span>
            )}
            <span className={cn("pr-4", wrap ? "whitespace-pre-wrap [overflow-wrap:anywhere]" : "whitespace-pre")}>
              {line.length ? withGuides(line).map((t, j) =>
                t.kind === "guide" ? (
                  <span key={j} className="relative inline-block w-[2ch]">
                    <span aria-hidden className="absolute inset-y-0 left-[1ch] w-px bg-line-code" />
                    {"  "}
                  </span>
                ) : (
                  <span key={j} className={COLOR[t.kind]}>
                    {t.text}
                  </span>
                ),
              ) : "\u200b"}
            </span>
          </span>
        ))}
      </code>
    </pre>
  );
}

export { CodeBlock, CodeBlockActions, CodeBlockContent, CodeBlockCopyButton, CodeBlockHeader, CodeBlockTitle, tokenize };

```

# Collapsible
A part that shows and hides in place, opening with its height.

Install: npx inkbox-ds add collapsible
Requires: theme, utils
Packages: @chakra-ui/react
Exports: Collapsible, CollapsibleContent, CollapsibleTrigger
Client boundary: yes
Reference: Figma 427:2715: Create Agent Identity (Advanced settings - tunnel mode, phone state, line sharing)


## Usage
Use for one optional group (Advanced settings under the channels). Make the trigger the whole row: a 14px ink label with a caret at the right that turns when open. For several sections, use Accordion.
- Avoid: Hiding required fields in it
- Avoid: A trigger without a caret
- Avoid: Animating anything but the content height and the caret


## Examples
Example components: npx inkbox-ds add collapsible label
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/collapsible/Preview)

examples/collapsible.tsx

```tsx
"use client";

import * as React from "react";
import { CaretDownIcon } from "@phosphor-icons/react/ssr";

import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible";
import { Label } from "@/components/ui/label";

export function Preview() {
  const [open, setOpen] = React.useState(false);
  return (
    <Collapsible open={open} onOpenChange={setOpen} className="w-full max-w-122">
      <CollapsibleTrigger className="group flex w-full items-center justify-between gap-4 rounded-pill py-2 text-left text-body text-fg outline-none transition-colors duration-150 ease-out hover:text-fg-brand focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring motion-reduce:transition-none">
        Advanced settings - tunnel mode, phone state, line sharing
        <CaretDownIcon aria-hidden weight="bold" className="size-4 shrink-0 text-icon-default transition-transform duration-200 ease-out group-data-[state=open]:rotate-180 motion-reduce:transition-none" />
      </CollapsibleTrigger>
      <CollapsibleContent>
        <div className="grid gap-2 pt-3" role="radiogroup" aria-label="Tunnel TLS mode">
          <p className="text-body text-fg">Tunnel TLS mode</p>
          <Label className="gap-2">
            <input type="radio" name="tls" defaultChecked className="size-4 accent-[var(--ds-color-action-primary)]" />
            Edge (default)
          </Label>
          <Label className="gap-2">
            <input type="radio" name="tls" className="size-4 accent-[var(--ds-color-action-primary)]" />
            Passthrough
          </Label>
        </div>
      </CollapsibleContent>
    </Collapsible>
  );
}

```

## Source

components/ui/collapsible.tsx

```tsx
"use client";

import * as React from "react";
import { Collapsible as ChakraCollapsible } from "@chakra-ui/react";

import { cn } from "@/lib/utils";

// A part that shows and hides in place (Figma 427:2715: "Advanced settings - tunnel mode, phone state, line sharing"
// under the channels). The parts carry no look of their own beyond the motion: the content opens with its height
// (200ms, the strong ease-out; closing is quicker). Style the trigger as the row it is (see the example).
type CollapsibleProps = Omit<React.ComponentProps<typeof ChakraCollapsible.Root>, "onOpenChange"> & { onOpenChange?: (open: boolean) => void };
function Collapsible({ onOpenChange, ...props }: CollapsibleProps) {
  return <ChakraCollapsible.Root unstyled data-slot="collapsible" onOpenChange={(details) => onOpenChange?.(details.open)} {...props} />;
}

function CollapsibleTrigger(props: React.ComponentProps<typeof ChakraCollapsible.Trigger>) {
  return <ChakraCollapsible.Trigger unstyled data-slot="collapsible-trigger" {...props} />;
}

function CollapsibleContent({ className, ...props }: React.ComponentProps<typeof ChakraCollapsible.Content>) {
  return <ChakraCollapsible.Content unstyled data-slot="collapsible-content" className={cn("overflow-hidden data-[state=closed]:animate-collapsible-up data-[state=open]:animate-collapsible-down", className)} {...props} />;
}

export { Collapsible, CollapsibleContent, CollapsibleTrigger };

```

# Combobox
A pill trigger for one value, or a field with 24px corners for multiple lilac pill chips, opening a searchable menu with 16px corners.

Install: npx inkbox-ds add combobox
Requires: theme, surface, utils
Packages: radix-ui, cmdk, @phosphor-icons/react
Exports: Combobox, ComboboxChip, ComboboxChips, ComboboxChipsInput, ComboboxClear, ComboboxCollection, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxInput, ComboboxItem, ComboboxLabel, ComboboxList, ComboboxSeparator, ComboboxTrigger, ComboboxValue, useCombobox, useComboboxAnchor
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the select trigger (Any State), the command menu and the lilac handle chip


## Usage
Use instead of Select when there are more than about ten choices or people know what they are looking for (an agent, a contact, webhook events). Wrap ComboboxTrigger (or ComboboxChips with ComboboxChip and ComboboxChipsInput for several values) and ComboboxContent with ComboboxInput, ComboboxList, ComboboxItem rows and ComboboxEmpty in a Combobox with value and onValueChange (multiple for several). Pass items so the closed field can show labels. To let people add a new value, render an extra item for the search text from useCombobox().
- Avoid: A combobox for five or fewer choices (use Select or a radio group)
- Avoid: Animating the highlight between rows
- Avoid: A list without an empty state
- Avoid: Chips in the purple


## Examples
Example components: npx inkbox-ds add combobox label
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/combobox/Preview) | [Multiple](https://inkbox-ds.vercel.app/preview/combobox/Multiple) | [Creatable](https://inkbox-ds.vercel.app/preview/combobox/Creatable) | [Groups](https://inkbox-ds.vercel.app/preview/combobox/Groups) | [States](https://inkbox-ds.vercel.app/preview/combobox/States)

examples/combobox.tsx

```tsx
"use client";

import * as React from "react";
import { PlusIcon, RobotIcon } from "@phosphor-icons/react/ssr";

import {
  Combobox,
  ComboboxChip,
  ComboboxChips,
  ComboboxChipsInput,
  ComboboxClear,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxGroup,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxSeparator,
  ComboboxTrigger,
  ComboboxValue,
  useCombobox,
} from "@/components/ui/combobox";
import { Label } from "@/components/ui/label";

const AGENTS = [
  { value: "acme", label: "@acme" },
  { value: "acme-support", label: "@acme-support" },
  { value: "support-desk", label: "@support-desk" },
  { value: "ops-runner", label: "@ops-runner" },
  { value: "test-agent-233", label: "@test-agent-233" },
  { value: "billing-bot", label: "@billing-bot", disabled: true },
];

const EVENTS = ["message.received", "message.sent", "message.delivered", "message.bounced", "call.started", "call.ended", "imessage.received", "tunnel.connected", "tunnel.disconnected"];

export function Preview() {
  const [agent, setAgent] = React.useState<string | null>("acme");
  return (
    <div className="grid w-full max-w-80 gap-1">
      <Label id="agent-label">Agent</Label>
      <Combobox items={AGENTS} value={agent} onValueChange={setAgent}>
        <ComboboxTrigger aria-labelledby="agent-label">
          <ComboboxValue placeholder="Choose an agent" />
        </ComboboxTrigger>
        <ComboboxContent>
          <ComboboxInput placeholder="Search agents" />
          <ComboboxList>
            <ComboboxEmpty>No agent with that handle.</ComboboxEmpty>
            {AGENTS.map((a) => (
              <ComboboxItem key={a.value} value={a.value} label={a.label} disabled={a.disabled}>
                <RobotIcon weight="fill" />
                {a.label}
              </ComboboxItem>
            ))}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  );
}

export function Multiple() {
  const [events, setEvents] = React.useState<string[]>(["message.received", "message.delivered"]);
  return (
    <div className="grid w-full max-w-100 gap-1">
      <Label htmlFor="events">Events</Label>
      <Combobox multiple items={EVENTS} value={events} onValueChange={setEvents} name="events">
        <ComboboxChips>
          {events.map((e) => (
            <ComboboxChip key={e} value={e} className="font-mono text-body-sm" />
          ))}
          <ComboboxChipsInput id="events" placeholder={events.length ? "" : "Add events"} />
          <ComboboxClear />
        </ComboboxChips>
        <ComboboxContent>
          <ComboboxList>
            {(item) => (
              <ComboboxItem value={item.value} className="font-mono text-body-sm">
                {item.label}
              </ComboboxItem>
            )}
          </ComboboxList>
          <ComboboxEmpty>No such event.</ComboboxEmpty>
        </ComboboxContent>
      </Combobox>
    </div>
  );
}

// The "Create" row reads the search from the combobox and offers it as a new value; choosing it calls onValueChange.
function CreateRow({ known }: { known: string[] }) {
  const { search } = useCombobox();
  const value = search.trim().toLowerCase();
  if (!value || known.includes(value)) return null;
  return (
    <>
      <ComboboxSeparator />
      <ComboboxItem value={value} label={value}>
        <PlusIcon />
        Create &ldquo;{value}&rdquo;
      </ComboboxItem>
    </>
  );
}

export function Creatable() {
  const [tags, setTags] = React.useState(["vip", "customer", "vendor"]);
  const [tag, setTag] = React.useState<string | null>(null);
  return (
    <div className="grid w-full max-w-80 gap-1">
      <Label id="tag-label">Contact tag</Label>
      <Combobox items={tags} value={tag} onValueChange={(v) => {
        if (v && !tags.includes(v)) setTags((t) => [...t, v]);
        setTag(v);
      }}>
        <ComboboxTrigger aria-labelledby="tag-label">
          <ComboboxValue placeholder="Add a tag" />
        </ComboboxTrigger>
        <ComboboxContent>
          <ComboboxInput placeholder="Search or create a tag" />
          <ComboboxList>
            {tags.map((t) => (
              <ComboboxItem key={t} value={t}>
                {t}
              </ComboboxItem>
            ))}
            <CreateRow known={tags} />
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  );
}

export function Groups() {
  const [line, setLine] = React.useState<string | null>(null);
  return (
    <div className="grid w-full max-w-80 gap-1">
      <Label id="line-label">Route to</Label>
      <Combobox
        value={line}
        onValueChange={setLine}
        items={[
          { value: "+16504749720", label: "+1 650 474 9720" },
          { value: "+14155550134", label: "+1 415 555 0134" },
          { value: "shared", label: "Shared iMessage line" },
        ]}
      >
        <ComboboxTrigger aria-labelledby="line-label">
          <ComboboxValue placeholder="Choose a line" />
        </ComboboxTrigger>
        <ComboboxContent>
          <ComboboxInput placeholder="Search lines" />
          <ComboboxList>
            <ComboboxEmpty />
            <ComboboxGroup heading="Phone">
              <ComboboxItem value="+16504749720">+1 650 474 9720</ComboboxItem>
              <ComboboxItem value="+14155550134">+1 415 555 0134</ComboboxItem>
            </ComboboxGroup>
            <ComboboxSeparator />
            <ComboboxGroup heading="iMessage">
              <ComboboxItem value="shared">Shared iMessage line</ComboboxItem>
            </ComboboxGroup>
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  );
}

export function States() {
  return (
    <div className="grid w-full max-w-80 gap-3">
      <Combobox items={AGENTS} defaultValue="acme" disabled>
        <ComboboxTrigger aria-label="Disabled agent" />
      </Combobox>
      <div className="grid gap-1">
        <Combobox items={AGENTS}>
          <ComboboxTrigger aria-label="Required agent" aria-invalid>
            <ComboboxValue placeholder="Choose an agent" />
          </ComboboxTrigger>
          <ComboboxContent>
            <ComboboxInput placeholder="Search agents" />
            <ComboboxList>
              {(a) => <ComboboxItem value={a.value}>{a.label}</ComboboxItem>}
            </ComboboxList>
          </ComboboxContent>
        </Combobox>
        <p className="text-caption leading-body text-danger">Choose the agent that owns this mailbox.</p>
      </div>
    </div>
  );
}

```

## Source

components/ui/combobox.tsx

```tsx
"use client";

import * as React from "react";
import { Popover as PopoverPrimitive } from "radix-ui";
import { Command as CommandPrimitive } from "cmdk";
import { CaretDownIcon, CheckIcon, MagnifyingGlassIcon, XIcon } from "@phosphor-icons/react/ssr";

import { usePortalContainer } from "@/lib/surface";
import { cn } from "@/lib/utils";

// A searchable choice (extrapolated from the Inkbox console, Figma 427:2715: the select trigger "Any State" and the
// command menu). The trigger is a white 40px pill with the Shadow/S ring, the value in 14px ink
// (the placeholder in the light purple) and the bold caret at the right. It opens the menu panel (white, 16px corners,
// the floating shadow) from the trigger: a 44px search row with a magnifying glass, then 36px rows of 14px ink with the
// highlighted row on the lilac and a purple check beside the chosen ones; groups are headed in 13px purple. For several
// values, ComboboxChips is a field with 24px corners: lilac pill chips with an x, and an input that filters as you
// type (Backspace on an empty input removes the last chip). Moving through the rows is instant: it is done by keyboard.

type Item = { value: string; label: string; disabled?: boolean };

type ComboboxContextValue = {
  multiple: boolean;
  values: string[];
  toggle: (value: string) => void;
  remove: (value: string) => void;
  clear: () => void;
  open: boolean;
  setOpen: (open: boolean) => void;
  search: string;
  setSearch: (search: string) => void;
  labelOf: (value: string) => string;
  register: (value: string, label: string) => void;
  items?: Item[];
  disabled?: boolean;
  listRef: React.RefObject<HTMLDivElement | null>;
  chipsRef: React.RefObject<HTMLDivElement | null>;
  chips: boolean;
  setChips: (chips: boolean) => void;
  contentId: string;
};

const ComboboxContext = React.createContext<ComboboxContextValue | null>(null);

function useCombobox() {
  const context = React.useContext(ComboboxContext);
  if (!context) throw new Error("Combobox parts must be used within <Combobox>");
  return context;
}

type ComboboxBaseProps = {
  /** The choices, for labels while the list is closed and for ComboboxList's render function. */
  items?: (Item | string)[];
  open?: boolean;
  defaultOpen?: boolean;
  onOpenChange?: (open: boolean) => void;
  disabled?: boolean;
  /** The submitted name: one hidden input per chosen value. */
  name?: string;
  children?: React.ReactNode;
};

type ComboboxSingleProps = ComboboxBaseProps & { multiple?: false; value?: string | null; defaultValue?: string | null; onValueChange?: (value: string | null) => void };
type ComboboxMultipleProps = ComboboxBaseProps & { multiple: true; value?: string[]; defaultValue?: string[]; onValueChange?: (value: string[]) => void };

const normalize = (items?: (Item | string)[]) => items?.map((i) => (typeof i === "string" ? { value: i, label: i } : i));

function Combobox(props: ComboboxSingleProps | ComboboxMultipleProps) {
  const { open: openProp, defaultOpen = false, onOpenChange, disabled, name, children } = props;
  const multiple = props.multiple === true;
  const items = React.useMemo(() => normalize(props.items), [props.items]);
  const initial = props.defaultValue == null ? [] : Array.isArray(props.defaultValue) ? props.defaultValue : [props.defaultValue];
  const [inner, setInner] = React.useState<string[]>(initial);
  const controlled = props.value !== undefined;
  const values = controlled ? (props.value == null ? [] : Array.isArray(props.value) ? props.value : [props.value]) : inner;
  const [openInner, setOpenInner] = React.useState(defaultOpen);
  const open = openProp ?? openInner;
  const [search, setSearch] = React.useState("");
  const [chips, setChips] = React.useState(false);
  const labels = React.useRef(new Map<string, string>());
  const listRef = React.useRef<HTMLDivElement>(null);
  const chipsRef = React.useRef<HTMLDivElement>(null);
  const contentId = React.useId();

  const setOpen = React.useCallback(
    (next: boolean) => {
      if (openProp === undefined) setOpenInner(next);
      onOpenChange?.(next);
      if (!next) setSearch("");
    },
    [openProp, onOpenChange],
  );
  const commit = (next: string[]) => {
    if (!controlled) setInner(next);
    if (multiple) (props as ComboboxMultipleProps).onValueChange?.(next);
    else (props as ComboboxSingleProps).onValueChange?.(next[0] ?? null);
  };
  const toggle = (value: string) => {
    if (multiple) {
      commit(values.includes(value) ? values.filter((v) => v !== value) : [...values, value]);
      setSearch("");
    } else {
      // Picking the chosen value again keeps it; ComboboxClear empties the field.
      commit([value]);
      setOpen(false);
    }
  };
  const remove = (value: string) => commit(values.filter((v) => v !== value));
  const labelOf = (value: string) => labels.current.get(value) ?? items?.find((i) => i.value === value)?.label ?? value;
  const register = React.useCallback((value: string, label: string) => labels.current.set(value, label), []);

  return (
    <ComboboxContext.Provider value={{ multiple, values, toggle, remove, clear: () => commit([]), open, setOpen, search, setSearch, labelOf, register, items, disabled, listRef, chipsRef, chips, setChips, contentId }}>
      <PopoverPrimitive.Root data-slot="combobox" open={open} onOpenChange={setOpen}>
        {children}
      </PopoverPrimitive.Root>
      {name && values.map((v) => <input key={v} type="hidden" name={name} value={v} />)}
    </ComboboxContext.Provider>
  );
}

const FIELD =
  "flex min-h-10 w-full min-w-0 items-center gap-2 rounded-pill bg-surface pr-3 pl-3.5 font-sans text-body leading-tight text-fg shadow-s outline-none transition-[box-shadow] duration-150 ease-out aria-invalid:shadow-[0_0_0_1px_var(--ds-color-status-danger)] motion-reduce:transition-none";

/** The closed field: the chosen value (ComboboxValue) and the caret. Opens the list. */
function ComboboxTrigger({ className, children, ...props }: React.ComponentProps<"button">) {
  const { open, disabled, values, contentId } = useCombobox();
  return (
    <PopoverPrimitive.Trigger asChild>
      <button
        type="button"
        role="combobox"
        aria-expanded={open}
        aria-controls={contentId}
        data-slot="combobox-trigger"
        data-empty={!values.length}
        disabled={disabled}
        className={cn(FIELD, "h-10 cursor-pointer text-left focus-visible:shadow-[var(--ds-shadow-s),var(--ds-shadow-focus)] disabled:cursor-not-allowed disabled:bg-subtle disabled:text-fg-muted data-[empty=true]:text-fg-subtle", className)}
        {...props}
      >
        <span className="flex min-w-0 flex-1 items-center gap-2 truncate">{children ?? <ComboboxValue />}</span>
        <CaretDownIcon aria-hidden weight="bold" className="size-4 shrink-0 text-fg" />
      </button>
    </PopoverPrimitive.Trigger>
  );
}

/** The chosen value's label, the chosen labels joined, or the placeholder. */
function ComboboxValue({ placeholder = "Select", children }: { placeholder?: string; children?: (values: string[]) => React.ReactNode }) {
  const { values, labelOf } = useCombobox();
  if (children) return <>{children(values)}</>;
  return <span data-slot="combobox-value">{values.length ? values.map(labelOf).join(", ") : placeholder}</span>;
}

/** Clears every chosen value. Put it inside ComboboxChips or beside a trigger. */
function ComboboxClear({ className, ...props }: React.ComponentProps<"button">) {
  const { values, clear, disabled } = useCombobox();
  if (!values.length) return null;
  return (
    <button
      type="button"
      data-slot="combobox-clear"
      aria-label="Clear"
      disabled={disabled}
      onClick={(e) => {
        e.stopPropagation();
        clear();
      }}
      className={cn("inline-flex size-6 shrink-0 items-center justify-center rounded-pill text-fg-faint outline-none active:brightness-95 active:transition-none transition-colors duration-150 ease-out hover:text-fg-muted focus-visible:outline-2 focus-visible:outline-focus-ring motion-reduce:transition-none", className)}
      {...props}
    >
      <XIcon weight="bold" className="size-4" />
    </button>
  );
}

function ComboboxContent({ className, children, align = "start", sideOffset = 6, anchor, onInteractOutside, ...props }: React.ComponentProps<typeof PopoverPrimitive.Content> & { anchor?: React.RefObject<HTMLElement | null> }) {
  const container = usePortalContainer();
  const { search, chips, listRef, chipsRef, contentId, open } = useCombobox();
  // With chips cmdk does not filter, so it would keep a hidden row highlighted: highlight the first match instead.
  const [active, setActive] = React.useState("");
  React.useEffect(() => {
    if (!chips || !open) return;
    const frame = requestAnimationFrame(() => setActive(listRef.current?.querySelector("[cmdk-item]:not([data-disabled=true])")?.getAttribute("data-value") ?? ""));
    return () => cancelAnimationFrame(frame);
  }, [chips, open, search, listRef]);
  return (
    <>
    {anchor && <PopoverPrimitive.Anchor virtualRef={anchor as React.RefObject<HTMLElement>} />}
    <PopoverPrimitive.Portal container={container}>
      <PopoverPrimitive.Content
        id={contentId}
        data-slot="combobox-content"
        align={align}
        sideOffset={sideOffset}
        // With chips the typing stays in the field; the list follows it.
        onOpenAutoFocus={chips ? (e) => e.preventDefault() : undefined}
        onInteractOutside={(e) => {
          onInteractOutside?.(e);
          // A press in the chips field keeps the list open: the field is where the typing happens.
          if (chips && chipsRef.current?.contains(e.target as Node)) e.preventDefault();
        }}
        className={cn(
          "z-50 w-(--radix-popover-trigger-width) min-w-56 max-w-[calc(100vw-2rem)] origin-(--radix-popover-content-transform-origin) overflow-hidden rounded-panel bg-surface text-fg shadow-floating outline-none data-[state=closed]:animate-fade-out data-[state=open]:animate-fade-in",
          className,
        )}
        {...props}
      >
        <CommandPrimitive ref={listRef} shouldFilter={!chips} {...(chips ? { value: active, onValueChange: setActive } : {})} className="flex flex-col">
          {children}
        </CommandPrimitive>
      </PopoverPrimitive.Content>
    </PopoverPrimitive.Portal>
    </>
  );
}

/** The search row at the top of the list. */
function ComboboxInput({ className, placeholder = "Search", ...props }: Omit<React.ComponentProps<typeof CommandPrimitive.Input>, "value" | "onValueChange">) {
  const { search, setSearch } = useCombobox();
  return (
    <div data-slot="combobox-input-wrapper" className="flex h-11 shrink-0 items-center gap-2.5 border-b border-line-subtle px-3.5">
      <MagnifyingGlassIcon aria-hidden className="size-5.5 shrink-0 text-fg-muted" />
      <CommandPrimitive.Input
        data-slot="combobox-input"
        value={search}
        onValueChange={setSearch}
        placeholder={placeholder}
        className={cn("h-full w-full min-w-0 bg-transparent font-sans text-body leading-tight text-fg outline-none placeholder:text-fg-subtle", className)}
        {...props}
      />
    </div>
  );
}

/** The rows. Pass items as children, or a function that renders each of the Combobox's items. */
function ComboboxList({ className, children, ...props }: Omit<React.ComponentProps<typeof CommandPrimitive.List>, "children"> & { children?: React.ReactNode | ((item: Item) => React.ReactNode) }) {
  const { items } = useCombobox();
  return (
    <CommandPrimitive.List data-slot="combobox-list" className={cn("max-h-72 scroll-py-1 overflow-x-hidden overflow-y-auto overscroll-contain p-1", className)} {...props}>
      {typeof children === "function" ? items?.map((item) => <React.Fragment key={item.value}>{children(item)}</React.Fragment>) : children}
    </CommandPrimitive.List>
  );
}

/** Renders a group's own items with a function, inside a ComboboxGroup. */
function ComboboxCollection({ items, children }: { items: (Item | string)[]; children: (item: Item) => React.ReactNode }) {
  return <>{normalize(items)?.map((item) => <React.Fragment key={item.value}>{children(item)}</React.Fragment>)}</>;
}

function ComboboxItem({ value, label, className, children, disabled, ...props }: Omit<React.ComponentProps<typeof CommandPrimitive.Item>, "value" | "onSelect"> & { value: string; label?: string }) {
  const { values, toggle, register, chips, search } = useCombobox();
  const text = label ?? (typeof children === "string" ? children : value);
  React.useEffect(() => {
    register(value, text);
  }, [register, value, text]);
  // With chips, cmdk does not filter (the typing is outside it): hide rows that do not match here.
  if (chips && search && !text.toLowerCase().includes(search.toLowerCase())) return null;
  const selected = values.includes(value);
  return (
    <CommandPrimitive.Item
      data-slot="combobox-item"
      value={`${text} ${value}`}
      disabled={disabled}
      data-checked={selected || undefined}
      onSelect={() => toggle(value)}
      className={cn(
        "relative flex h-9 cursor-default items-center gap-2.5 rounded-pill pr-8 pl-2.5 font-sans text-body leading-tight text-fg outline-none select-none data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 data-[selected=true]:bg-subtle [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-5.5 [&_svg:not([class*='text-'])]:text-icon-secondary",
        className,
      )}
      {...props}
    >
      {children ?? text}
      {selected && <CheckIcon aria-hidden weight="bold" className="absolute right-2.5 size-4 text-fg-brand" />}
    </CommandPrimitive.Item>
  );
}

function ComboboxEmpty({ className, children = "No results.", ...props }: React.ComponentProps<typeof CommandPrimitive.Empty>) {
  const { chips, search, items, labelOf, values } = useCombobox();
  // cmdk's own empty state only knows its filter; with chips, decide here.
  if (chips) {
    const any = (items ?? values.map((v) => ({ value: v, label: labelOf(v) }))).some((i) => !search || i.label.toLowerCase().includes(search.toLowerCase()));
    if (any) return null;
    return (
      <div data-slot="combobox-empty" className={cn("py-6 text-center text-body text-fg-muted", className)}>
        {children}
      </div>
    );
  }
  return (
    <CommandPrimitive.Empty data-slot="combobox-empty" className={cn("py-6 text-center text-body text-fg-muted", className)} {...props}>
      {children}
    </CommandPrimitive.Empty>
  );
}

function ComboboxGroup({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.Group>) {
  return (
    <CommandPrimitive.Group
      data-slot="combobox-group"
      className={cn("overflow-hidden text-fg [&_[cmdk-group-heading]]:px-2.5 [&_[cmdk-group-heading]]:pt-2 [&_[cmdk-group-heading]]:pb-1 [&_[cmdk-group-heading]]:text-body-sm [&_[cmdk-group-heading]]:leading-tight [&_[cmdk-group-heading]]:text-fg-label", className)}
      {...props}
    />
  );
}

/** A heading inside the list that is not a group's (a note above the rows). */
function ComboboxLabel({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="combobox-label" className={cn("px-2.5 pt-2 pb-1 text-body-sm leading-tight text-fg-label", className)} {...props} />;
}

function ComboboxSeparator({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.Separator>) {
  return <CommandPrimitive.Separator data-slot="combobox-separator" className={cn("-mx-1 my-1 h-px bg-line-subtle", className)} {...props} />;
}

/** The field for several values: chips and a text input, anchoring the list. */
function ComboboxChips({ className, children, ...props }: React.ComponentProps<"div">) {
  const { setChips, setOpen, disabled, chipsRef } = useCombobox();
  React.useEffect(() => {
    setChips(true);
    return () => setChips(false);
  }, [setChips]);
  return (
    <PopoverPrimitive.Anchor asChild>
      <div
        ref={chipsRef}
        data-slot="combobox-chips"
        data-disabled={disabled || undefined}
        onMouseDown={(e) => {
          if (disabled || e.target !== e.currentTarget) return;
          e.preventDefault();
          e.currentTarget.querySelector("input")?.focus();
          setOpen(true);
        }}
        className={cn(FIELD, "flex-wrap gap-1.5 rounded-dialog py-1.5 pl-1.5 has-[input:focus-visible]:shadow-[var(--ds-shadow-s),var(--ds-shadow-focus)] data-disabled:bg-subtle data-disabled:text-fg-muted", className)}
        {...props}
      >
        {children}
      </div>
    </PopoverPrimitive.Anchor>
  );
}

function ComboboxChip({ value, className, children, ...props }: React.ComponentProps<"span"> & { value: string }) {
  const { remove, labelOf, disabled } = useCombobox();
  return (
    <span data-slot="combobox-chip" className={cn("inline-flex h-7 max-w-full items-center gap-1 rounded-pill bg-subtle pr-1 pl-2 text-body leading-tight text-fg", className)} {...props}>
      <span className="truncate">{children ?? labelOf(value)}</span>
      <button
        type="button"
        aria-label={`Remove ${labelOf(value)}`}
        disabled={disabled}
        onClick={() => remove(value)}
        className="inline-flex size-5 items-center justify-center rounded-pill text-fg-muted outline-none active:brightness-95 active:transition-none transition-colors duration-150 ease-out hover:bg-subtle-hover active:bg-subtle-hover hover:text-fg focus-visible:outline-2 focus-visible:outline-focus-ring motion-reduce:transition-none"
      >
        <XIcon weight="bold" className="size-3.5" />
      </button>
    </span>
  );
}

/** The typing part of ComboboxChips: filters the list; arrows and Enter work the list; Backspace removes the last chip. */
function ComboboxChipsInput({ className, onKeyDown, ...props }: React.ComponentProps<"input">) {
  const { search, setSearch, setOpen, open, values, remove, listRef, disabled, contentId } = useCombobox();
  return (
    <input
      data-slot="combobox-chips-input"
      role="combobox"
      aria-expanded={open}
      aria-controls={contentId}
      aria-autocomplete="list"
      disabled={disabled}
      value={search}
      onChange={(e) => {
        setSearch(e.target.value);
        if (!open) setOpen(true);
      }}
      onFocus={() => setOpen(true)}
      onKeyDown={(e) => {
        onKeyDown?.(e);
        if (e.defaultPrevented) return;
        if (e.key === "Backspace" && !search && values.length) remove(values[values.length - 1]);
        else if (["ArrowDown", "ArrowUp", "Enter", "Home", "End"].includes(e.key) && open && listRef.current) {
          e.preventDefault();
          // Hand the key to the list, which moves the highlight or picks the highlighted row.
          listRef.current.dispatchEvent(new KeyboardEvent("keydown", { key: e.key, bubbles: true, cancelable: true }));
        } else if (e.key === "ArrowDown" && !open) setOpen(true);
      }}
      className={cn("h-7 min-w-24 flex-1 bg-transparent font-sans text-body leading-tight text-fg outline-none placeholder:text-fg-subtle disabled:cursor-not-allowed", className)}
      {...props}
    />
  );
}

/** A ref for an element the list should open from, when it is not the trigger (pass it to ComboboxContent's anchor). */
function useComboboxAnchor<T extends HTMLElement = HTMLDivElement>() {
  return React.useRef<T>(null);
}

export {
  Combobox,
  ComboboxChip,
  ComboboxChips,
  ComboboxChipsInput,
  ComboboxClear,
  ComboboxCollection,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxGroup,
  ComboboxInput,
  ComboboxItem,
  ComboboxLabel,
  ComboboxList,
  ComboboxSeparator,
  ComboboxTrigger,
  ComboboxValue,
  useCombobox,
  useComboboxAnchor,
};

```

# Command
A search row over grouped 36px results with purple group headings, in a panel or a dialog with the shared 16px popup corners.

Install: npx inkbox-ds add command
Requires: theme, surface, utils
Packages: cmdk, radix-ui, @phosphor-icons/react
Exports: Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the nav rows, section labels (Channels, Shared) and the dialog


## Usage
Use as a command palette (CommandDialog, opened with Command K) to jump to agents, mailboxes and pages, or inline as a searchable list. Give every item a filled glyph and the group a heading.
- Avoid: Animating the palette open or closed
- Avoid: A palette without an empty state
- Avoid: Results without groups once there are more than ten


## Examples
Example components: npx inkbox-ds add command button
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/command/Preview) | [Dialog](https://inkbox-ds.vercel.app/preview/command/Dialog) | [Open](https://inkbox-ds.vercel.app/preview/command/Open)

examples/command.tsx

```tsx
"use client";

import * as React from "react";
import { BookOpenTextIcon, EnvelopeSimpleIcon, GearSixIcon, KeyIcon, LockKeyIcon, PhoneIcon, PlusIcon, RobotIcon, WebhooksLogoIcon } from "@phosphor-icons/react/ssr";

import { Button } from "@/components/ui/button";
import { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut } from "@/components/ui/command";

function Items({ onRun }: { onRun?: () => void }) {
  return (
    <>
      <CommandInput placeholder="Search agents, mailboxes and pages" />
      <CommandList>
        <CommandEmpty>No results.</CommandEmpty>
        <CommandGroup heading="Agents">
          <CommandItem onSelect={onRun}>
            <RobotIcon weight="fill" />
            @acme
          </CommandItem>
          <CommandItem onSelect={onRun}>
            <RobotIcon weight="fill" />
            @acme-support
          </CommandItem>
          <CommandItem onSelect={onRun}>
            <PlusIcon />
            Create Agent
            <CommandShortcut>⌘N</CommandShortcut>
          </CommandItem>
        </CommandGroup>
        <CommandSeparator />
        <CommandGroup heading="Channels">
          <CommandItem onSelect={onRun}>
            <EnvelopeSimpleIcon weight="fill" />
            Email
          </CommandItem>
          <CommandItem onSelect={onRun}>
            <PhoneIcon weight="fill" />
            Phone
          </CommandItem>
          <CommandItem disabled>
            <WebhooksLogoIcon weight="fill" />
            Agent2Agent (beta)
          </CommandItem>
        </CommandGroup>
        <CommandSeparator />
        <CommandGroup heading="Shared">
          <CommandItem onSelect={onRun}>
            <LockKeyIcon weight="fill" />
            Vault
          </CommandItem>
          <CommandItem onSelect={onRun}>
            <KeyIcon weight="fill" />
            API Keys
            <CommandShortcut>⌘K</CommandShortcut>
          </CommandItem>
          <CommandItem onSelect={onRun}>
            <GearSixIcon weight="fill" />
            Settings
            <CommandShortcut>⌘,</CommandShortcut>
          </CommandItem>
          <CommandItem onSelect={onRun}>
            <BookOpenTextIcon weight="fill" />
            Read the docs
          </CommandItem>
        </CommandGroup>
      </CommandList>
    </>
  );
}

export function Preview() {
  return (
    <Command className="mx-auto max-w-112 shadow-s">
      <Items />
    </Command>
  );
}

export function Dialog() {
  const [open, setOpen] = React.useState(false);
  React.useEffect(() => {
    const onKey = (event: KeyboardEvent) => {
      if (event.key === "k" && (event.metaKey || event.ctrlKey)) {
        event.preventDefault();
        setOpen((o) => !o);
      }
    };
    document.addEventListener("keydown", onKey);
    return () => document.removeEventListener("keydown", onKey);
  }, []);
  return (
    <div className="grid justify-items-center gap-3">
      <Button variant="outline" onClick={() => setOpen(true)}>
        Open the command menu
      </Button>
      <p className="text-body text-fg-muted">
        Or press <kbd className="rounded-xs bg-subtle px-1.5 font-sans text-caption text-fg">⌘K</kbd>
      </p>
      <CommandDialog open={open} onOpenChange={setOpen}>
        <Items onRun={() => setOpen(false)} />
      </CommandDialog>
    </div>
  );
}

export function Open() {
  return (
    <div className="min-h-120">
      <CommandDialog defaultOpen>
        <Items />
      </CommandDialog>
    </div>
  );
}

```

## Source

components/ui/command.tsx

```tsx
"use client";

import * as React from "react";
import { Command as CommandPrimitive } from "cmdk";
import { Dialog as DialogPrimitive } from "radix-ui";
import { MagnifyingGlassIcon } from "@phosphor-icons/react/ssr";

import { usePortalContainer } from "@/lib/surface";
import { cn } from "@/lib/utils";

// A command menu, extrapolated from the console (Figma 427:2715): a white panel with 16px corners; the search row is
// 48px with a 20px magnifying glass in muted purple and 14px ink text over the rail's hairline; groups open with 13px
// headings in the label purple ("Channels"), items are 36px pill rows, a 20px glyph in the action-glyph
// purple and the lilac under the selected row; shortcuts are 12px muted. CommandDialog puts it in the console's dialog
// (16px corners, the blurred ink-tinted page) and opens without motion: it is summoned by keyboard many times a day.
function Command({ className, ...props }: React.ComponentProps<typeof CommandPrimitive>) {
  return <CommandPrimitive data-slot="command" data-ds-motion="instant" className={cn("flex size-full flex-col overflow-hidden rounded-panel bg-surface text-fg", className)} {...props} />;
}

function CommandDialog({
  title = "Command menu",
  description = "Search for a command to run",
  children,
  className,
  showCloseButton = false,
  ...props
}: React.ComponentProps<typeof DialogPrimitive.Root> & { title?: string; description?: string; className?: string; showCloseButton?: boolean }) {
  const container = usePortalContainer();
  return (
    <DialogPrimitive.Root data-slot="command-dialog" {...props}>
      <DialogPrimitive.Portal container={container}>
        <DialogPrimitive.Overlay data-ds-motion="instant" className="fixed inset-0 z-50 bg-scrim backdrop-blur-[var(--ds-blur-scrim)]" />
        <DialogPrimitive.Content
          data-ds-motion="instant"
          className={cn("fixed top-[18dvh] left-1/2 z-50 w-[calc(100%-2rem)] max-w-140 -translate-x-1/2 overflow-hidden rounded-panel bg-surface p-1.5 text-fg outline-none", className)}
          aria-describedby={undefined}
        >
          <DialogPrimitive.Title className="sr-only">{title}</DialogPrimitive.Title>
          <DialogPrimitive.Description className="sr-only">{description}</DialogPrimitive.Description>
          <Command className="rounded-panel [&_[data-slot=command-list]]:max-h-96">{children}</Command>
          {showCloseButton && <DialogPrimitive.Close className="sr-only">Close</DialogPrimitive.Close>}
        </DialogPrimitive.Content>
      </DialogPrimitive.Portal>
    </DialogPrimitive.Root>
  );
}

function CommandInput({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.Input>) {
  return (
    <div data-slot="command-input-wrapper" className="flex h-12 shrink-0 items-center gap-2.5 border-b border-line-subtle px-3.5">
      <MagnifyingGlassIcon aria-hidden className="size-5.5 shrink-0 text-fg-muted" />
      <CommandPrimitive.Input
        data-slot="command-input"
        className={cn("h-full w-full min-w-0 bg-transparent font-sans text-body leading-tight text-fg outline-none placeholder:text-fg-subtle disabled:cursor-not-allowed disabled:opacity-50", className)}
        {...props}
      />
    </div>
  );
}

function CommandList({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.List>) {
  return <CommandPrimitive.List data-slot="command-list" className={cn("max-h-80 scroll-py-1 overflow-x-hidden overflow-y-auto overscroll-contain p-1", className)} {...props} />;
}

function CommandEmpty({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.Empty>) {
  return <CommandPrimitive.Empty data-slot="command-empty" className={cn("py-8 text-center text-body text-fg-muted", className)} {...props} />;
}

function CommandGroup({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.Group>) {
  return (
    <CommandPrimitive.Group
      data-slot="command-group"
      className={cn("overflow-hidden text-fg [&_[cmdk-group-heading]]:px-2.5 [&_[cmdk-group-heading]]:pt-2 [&_[cmdk-group-heading]]:pb-1 [&_[cmdk-group-heading]]:text-body-sm [&_[cmdk-group-heading]]:leading-tight [&_[cmdk-group-heading]]:text-fg-label", className)}
      {...props}
    />
  );
}

function CommandSeparator({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.Separator>) {
  return <CommandPrimitive.Separator data-slot="command-separator" className={cn("-mx-1 my-1 h-px bg-line-subtle", className)} {...props} />;
}

function CommandItem({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.Item>) {
  return (
    <CommandPrimitive.Item
      data-slot="command-item"
      className={cn(
        "relative flex h-9 cursor-default items-center gap-2.5 rounded-pill px-2.5 font-sans text-body leading-tight text-fg outline-none select-none data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 data-[selected=true]:bg-subtle [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-5.5 [&_svg:not([class*='text-'])]:text-icon-secondary",
        className,
      )}
      {...props}
    />
  );
}

function CommandShortcut({ className, ...props }: React.ComponentProps<"span">) {
  return <span data-slot="command-shortcut" className={cn("ml-auto pl-4 font-sans text-caption text-fg-muted", className)} {...props} />;
}

export { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut };

```

# Context Menu
The dropdown menu's panel and rows, opened with a right click or a long press on an area.

Install: npx inkbox-ds add context-menu
Requires: theme, surface, utils
Packages: radix-ui, @phosphor-icons/react
Exports: ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the email list items, nav rows and the raised panel


## Usage
Use for shortcuts to actions on an item in a list (an email in the inbox, a contact). Every action must also be reachable another way, such as a row's menu button.
- Avoid: Actions that exist only in the context menu
- Avoid: A context menu on text people need to select
- Avoid: Nested submenus beyond one level


## Examples
Example components: npx inkbox-ds add context-menu
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/context-menu/Preview)

examples/context-menu.tsx

```tsx
"use client";

import * as React from "react";
import { ArchiveIcon, ArrowBendUpLeftIcon, ArrowBendUpRightIcon, EnvelopeOpenIcon, ProhibitIcon, TrashIcon, WarningIcon } from "@phosphor-icons/react/ssr";

import {
  ContextMenu,
  ContextMenuCheckboxItem,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuLabel,
  ContextMenuRadioGroup,
  ContextMenuRadioItem,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuSub,
  ContextMenuSubContent,
  ContextMenuSubTrigger,
  ContextMenuTrigger,
} from "@/components/ui/context-menu";

export function Preview() {
  const [starred, setStarred] = React.useState(false);
  const [folder, setFolder] = React.useState("inbox");
  return (
    <ContextMenu>
      <ContextMenuTrigger className="mx-auto grid w-full max-w-96 gap-1 rounded-control bg-subtle p-3">
        <span className="flex justify-between text-body text-fg">
          Ray Liao <span className="text-fg-muted">Yesterday</span>
        </span>
        <span className="text-body text-fg">Inkbox A2A: publish your Agent Card</span>
        <span className="truncate text-body text-fg-brand">Hello @acme, This is Ray, cofounder of Inkbox.</span>
        <span className="mt-2 text-caption text-fg-muted">Right-click or long-press the email</span>
      </ContextMenuTrigger>
      <ContextMenuContent className="w-60">
        <ContextMenuItem>
          <ArrowBendUpLeftIcon />
          Reply
          <ContextMenuShortcut>R</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuItem>
          <ArrowBendUpRightIcon />
          Forward
          <ContextMenuShortcut>F</ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuItem>
          <EnvelopeOpenIcon weight="fill" />
          Mark as unread
        </ContextMenuItem>
        <ContextMenuCheckboxItem checked={starred} onCheckedChange={(v) => setStarred(v === true)}>
          Starred
        </ContextMenuCheckboxItem>
        <ContextMenuSub>
          <ContextMenuSubTrigger>
            <ArchiveIcon weight="fill" />
            Move to
          </ContextMenuSubTrigger>
          <ContextMenuSubContent className="w-44">
            <ContextMenuLabel>Folders</ContextMenuLabel>
            <ContextMenuRadioGroup value={folder} onValueChange={setFolder}>
              <ContextMenuRadioItem value="inbox">Inbox</ContextMenuRadioItem>
              <ContextMenuRadioItem value="sent">Sent</ContextMenuRadioItem>
              <ContextMenuRadioItem value="spam">Spam</ContextMenuRadioItem>
            </ContextMenuRadioGroup>
          </ContextMenuSubContent>
        </ContextMenuSub>
        <ContextMenuSeparator />
        <ContextMenuItem>
          <WarningIcon weight="fill" />
          Report spam
        </ContextMenuItem>
        <ContextMenuItem>
          <ProhibitIcon />
          Block sender
        </ContextMenuItem>
        <ContextMenuItem variant="destructive">
          <TrashIcon weight="fill" />
          Delete
          <ContextMenuShortcut>⌫</ContextMenuShortcut>
        </ContextMenuItem>
      </ContextMenuContent>
    </ContextMenu>
  );
}

```

## Source

components/ui/context-menu.tsx

```tsx
"use client";

import * as React from "react";
import { ContextMenu as ContextMenuPrimitive } from "radix-ui";
import { CaretRightIcon, CheckIcon } from "@phosphor-icons/react/ssr";

import { usePortalContainer } from "@/lib/surface";
import { cn } from "@/lib/utils";

// A right-click menu, extrapolated from the console (Figma 427:2715), drawn as the dropdown menu: the panel is a raised white panel (16px corners, the floating
// shadow) with 4px of padding; items are 36px rows with fully rounded corners like the rail's nav rows, a 20px glyph in the
// action-glyph purple 10px from a 14px ink label, and the lilac under the highlighted row. Section labels are 13px in
// the label purple ("Channels"), separators the rail's hairline, shortcuts 12px muted, destructive items red. The
// panel grows out of its trigger from 96 percent with a fade; highlighting a row is instant (menus are used by keyboard
// and many times a day).
const CONTENT =
  "z-50 max-h-(--radix-context-menu-content-available-height) min-w-48 overflow-x-hidden overflow-y-auto rounded-panel bg-surface p-1 text-fg shadow-floating outline-none data-[state=closed]:animate-fade-out data-[state=open]:animate-fade-in";
const ITEM =
  "relative flex h-9 cursor-default items-center gap-2.5 rounded-pill px-2.5 font-sans text-body leading-tight text-fg outline-none select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[highlighted]:bg-subtle data-[inset]:pl-10.5 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-5.5 [&_svg:not([class*='text-'])]:text-icon-secondary";

function ContextMenu(props: React.ComponentProps<typeof ContextMenuPrimitive.Root>) {
  return <ContextMenuPrimitive.Root data-slot="context-menu" {...props} />;
}

function ContextMenuPortal(props: React.ComponentProps<typeof ContextMenuPrimitive.Portal>) {
  const container = usePortalContainer();
  return <ContextMenuPrimitive.Portal data-slot="context-menu-portal" container={container} {...props} />;
}

function ContextMenuTrigger({ className, ...props }: React.ComponentProps<typeof ContextMenuPrimitive.Trigger>) {
  return <ContextMenuPrimitive.Trigger data-slot="context-menu-trigger" className={cn("select-none", className)} {...props} />;
}

function ContextMenuContent({ className, ...props }: React.ComponentProps<typeof ContextMenuPrimitive.Content>) {
  return (
    <ContextMenuPortal>
      <ContextMenuPrimitive.Content data-slot="context-menu-content" className={cn(CONTENT, "origin-(--radix-context-menu-content-transform-origin)", className)} {...props} />
    </ContextMenuPortal>
  );
}

function ContextMenuGroup(props: React.ComponentProps<typeof ContextMenuPrimitive.Group>) {
  return <ContextMenuPrimitive.Group data-slot="context-menu-group" {...props} />;
}

function ContextMenuItem({ className, inset, variant = "default", ...props }: React.ComponentProps<typeof ContextMenuPrimitive.Item> & { inset?: boolean; variant?: "default" | "destructive" }) {
  return (
    <ContextMenuPrimitive.Item
      data-slot="context-menu-item"
      data-inset={inset || undefined}
      data-variant={variant}
      className={cn(ITEM, "data-[variant=destructive]:text-danger data-[variant=destructive]:[&_svg]:text-danger", className)}
      {...props}
    />
  );
}

function ContextMenuCheckboxItem({ className, children, checked, ...props }: React.ComponentProps<typeof ContextMenuPrimitive.CheckboxItem>) {
  return (
    <ContextMenuPrimitive.CheckboxItem data-slot="context-menu-checkbox-item" checked={checked} className={cn(ITEM, "pl-10.5", className)} {...props}>
      <span className="pointer-events-none absolute left-2.5 flex size-5.5 items-center justify-center">
        <ContextMenuPrimitive.ItemIndicator>
          <CheckIcon weight="bold" className="size-4.5 text-fg-brand" />
        </ContextMenuPrimitive.ItemIndicator>
      </span>
      {children}
    </ContextMenuPrimitive.CheckboxItem>
  );
}

function ContextMenuRadioGroup(props: React.ComponentProps<typeof ContextMenuPrimitive.RadioGroup>) {
  return <ContextMenuPrimitive.RadioGroup data-slot="context-menu-radio-group" {...props} />;
}

// The selected choice wears the console's radio mark: a pink ring around white.
function ContextMenuRadioItem({ className, children, ...props }: React.ComponentProps<typeof ContextMenuPrimitive.RadioItem>) {
  return (
    <ContextMenuPrimitive.RadioItem data-slot="context-menu-radio-item" className={cn(ITEM, "pl-10.5", className)} {...props}>
      <span className="pointer-events-none absolute left-2.5 flex size-5.5 items-center justify-center">
        <ContextMenuPrimitive.ItemIndicator>
          <span className="block size-3.5 rounded-pill border-[3.5px] border-pink bg-surface" />
        </ContextMenuPrimitive.ItemIndicator>
      </span>
      {children}
    </ContextMenuPrimitive.RadioItem>
  );
}

function ContextMenuLabel({ className, inset, ...props }: React.ComponentProps<typeof ContextMenuPrimitive.Label> & { inset?: boolean }) {
  return <ContextMenuPrimitive.Label data-slot="context-menu-label" data-inset={inset || undefined} className={cn("px-2.5 pt-2 pb-1 font-sans text-body-sm leading-tight text-fg-label data-[inset]:pl-10.5", className)} {...props} />;
}

function ContextMenuSeparator({ className, ...props }: React.ComponentProps<typeof ContextMenuPrimitive.Separator>) {
  return <ContextMenuPrimitive.Separator data-slot="context-menu-separator" className={cn("-mx-1 my-1 h-px bg-line-subtle", className)} {...props} />;
}

function ContextMenuShortcut({ className, ...props }: React.ComponentProps<"span">) {
  return <span data-slot="context-menu-shortcut" className={cn("ml-auto pl-4 font-sans text-caption text-fg-muted", className)} {...props} />;
}

function ContextMenuSub(props: React.ComponentProps<typeof ContextMenuPrimitive.Sub>) {
  return <ContextMenuPrimitive.Sub data-slot="context-menu-sub" {...props} />;
}

function ContextMenuSubTrigger({ className, inset, children, ...props }: React.ComponentProps<typeof ContextMenuPrimitive.SubTrigger> & { inset?: boolean }) {
  return (
    <ContextMenuPrimitive.SubTrigger data-slot="context-menu-sub-trigger" data-inset={inset || undefined} className={cn(ITEM, "data-[state=open]:bg-subtle", className)} {...props}>
      {children}
      <CaretRightIcon className="ml-auto size-4.5 text-fg-muted" />
    </ContextMenuPrimitive.SubTrigger>
  );
}

function ContextMenuSubContent({ className, ...props }: React.ComponentProps<typeof ContextMenuPrimitive.SubContent>) {
  return (
    <ContextMenuPortal>
      <ContextMenuPrimitive.SubContent data-slot="context-menu-sub-content" className={cn(CONTENT, "max-h-(--radix-context-menu-content-available-height) origin-(--radix-context-menu-content-transform-origin)", className)} {...props} />
    </ContextMenuPortal>
  );
}

export {
  ContextMenu,
  ContextMenuCheckboxItem,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuItem,
  ContextMenuLabel,
  ContextMenuPortal,
  ContextMenuRadioGroup,
  ContextMenuRadioItem,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuSub,
  ContextMenuSubContent,
  ContextMenuSubTrigger,
  ContextMenuTrigger,
};

```

# Data Table
The console's table with a filter field, sortable heads, row checkboxes, a Columns menu and the lilac pagination bar.

Install: npx inkbox-ds add data-table
Requires: theme, button, checkbox, dropdown-menu, input-group, pagination, select, table, utils
Packages: @phosphor-icons/react
Exports: DataTable, DataTableColumnHeader, DataTablePagination, DataTableViewOptions, DataTableColumn, DataTableProps, SortState
Client boundary: yes
Reference: Figma 427:2715: Email (Mailboxes table and its pagination bar), iMessage (Agents and lines)


## Usage
Use for a list of records people manage (mailboxes, agents and lines, webhook subscriptions): pass columns (id, header, an accessor for sorting and filtering, a cell renderer), data and getRowId. Turn on selectable for bulk actions and put those actions in toolbar; set pageSize and pageSizes for long lists. For a short fixed list with no sorting or paging, use Table on its own. Keep row actions as ghost icon buttons in the last column.
- Avoid: Zebra stripes
- Avoid: A border around the whole table instead of the three panels
- Avoid: Animating rows when sorting or paging
- Avoid: More than one purple pill in the toolbar


## Examples
Example components: npx inkbox-ds add data-table badge button
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/data-table/Preview) | [Selection](https://inkbox-ds.vercel.app/preview/data-table/Selection) | [Empty](https://inkbox-ds.vercel.app/preview/data-table/Empty)

examples/data-table.tsx

```tsx
"use client";

import * as React from "react";
import { ArrowsClockwiseIcon, PencilSimpleIcon, TrashIcon } from "@phosphor-icons/react/ssr";

import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import { DataTable, type DataTableColumn } from "@/components/ui/data-table";

type Mailbox = { address: string; agent: string; webhooks: number; storage: number; created: Date; status: "active" | "paused" };

const AGENTS = ["acme", "support-desk", "ops-runner", "acme-support", "test-agent-233", "billing-bot"];
const MAILBOXES: Mailbox[] = Array.from({ length: 23 }, (_, i) => {
  const agent = AGENTS[i % AGENTS.length];
  return { address: `${agent}${i > 5 ? `-${i}` : ""}@inkboxmail.com`, agent, webhooks: (i * 7) % 4, storage: (i * 13) % 61, created: new Date(2026, 6, 27 + (i % 20)), status: i % 5 === 3 ? "paused" : "active" };
});

const date = new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric", year: "numeric" });

const COLUMNS: DataTableColumn<Mailbox>[] = [
  { id: "address", header: "Email address", accessor: (m) => m.address, sortable: true, hideable: false },
  { id: "agent", header: "Agent", accessor: (m) => m.agent, sortable: true, cell: (m) => <span className="text-rose">@{m.agent}</span> },
  { id: "webhooks", header: "Webhooks", accessor: (m) => m.webhooks, sortable: true, cell: (m) => (m.webhooks ? m.webhooks : "None") },
  { id: "storage", header: "Storage", accessor: (m) => m.storage, sortable: true, cell: (m) => `${m.storage}%` },
  { id: "status", header: "Status", accessor: (m) => m.status, hidden: true, cell: (m) => <Badge variant={m.status === "active" ? "green" : "gray"} size="sm">{m.status === "active" ? "Active" : "Paused"}</Badge> },
  { id: "created", header: "Created", accessor: (m) => m.created, sortable: true, cell: (m) => date.format(m.created) },
  {
    id: "actions",
    header: <span className="sr-only">Actions</span>,
    hideable: false,
    align: "end",
    className: "w-14",
    cell: (m) => (
      <Button variant="ghost" size="icon" aria-label={`Edit ${m.address}`}>
        <PencilSimpleIcon weight="fill" />
      </Button>
    ),
  },
];

export function Preview() {
  return <DataTable columns={COLUMNS} data={MAILBOXES} getRowId={(m) => m.address} rowName="mailbox" pageSize={5} filter={{ placeholder: "Filter mailboxes" }} defaultSort={{ id: "created", desc: false }} empty="No mailbox matches." />;
}

export function Selection() {
  const [rows, setRows] = React.useState(MAILBOXES.slice(0, 8));
  const [selected, setSelected] = React.useState<string[]>([]);
  return (
    <DataTable
      columns={COLUMNS}
      data={rows}
      getRowId={(m) => m.address}
      rowName="mailbox"
      selectable
      selection={selected}
      onSelectionChange={setSelected}
      pageSize={5}
      pageSizes={[5, 10, 20]}
      filter={{ placeholder: "Filter mailboxes", columns: ["address", "agent"] }}
      toolbar={
        <>
          <Button
            variant="ghost"
            size="icon-lg"
            aria-label="Refresh"
            onClick={() => {
              setRows(MAILBOXES.slice(0, 8));
              setSelected([]);
            }}
          >
            <ArrowsClockwiseIcon />
          </Button>
          {selected.length > 0 && (
            <Button
              variant="destructive"
              onClick={() => {
                setRows((r) => r.filter((m) => !selected.includes(m.address)));
                setSelected([]);
              }}
            >
              <TrashIcon weight="fill" />
              Delete {selected.length}
            </Button>
          )}
        </>
      }
    />
  );
}

export function Empty() {
  return <DataTable columns={COLUMNS} data={[]} getRowId={(m) => m.address} filter={false} hideViewOptions empty="No mailboxes yet. Mailboxes are created with their agent identity." />;
}

```

## Source

components/ui/data-table.tsx

```tsx
"use client";

import * as React from "react";
import { ArrowDownIcon, ArrowUpIcon, CaretUpDownIcon, ColumnsIcon, MagnifyingGlassIcon } from "@phosphor-icons/react/ssr";

import { Button } from "@/components/ui/button";
import { Checkbox } from "@/components/ui/checkbox";
import { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger } from "@/components/ui/dropdown-menu";
import { InputGroup, InputGroupAddon, InputGroupInput } from "@/components/ui/input-group";
import { Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious } from "@/components/ui/pagination";
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";
import { cn } from "@/lib/utils";

// A table of records people sort, filter, select and page through (the console's Mailboxes table, Figma 427:2715,
// Email). It keeps the table's three panels: the 48px lilac head with 14px muted labels (a sortable label is a ghost key
// with an arrow for its direction), the white Shadow/S body with 64px rows (a selected row on the lilac) and, 8px below,
// the 42px lilac pagination bar with the selection count at its left and the pages at its right. Above it, a toolbar:
// a 40px filter field with a magnifying glass and the outline Columns key that opens a menu of checkboxes. Sorting,
// filtering and paging are instant (no motion): they are repeated many times in a row.

type Value = string | number | Date | boolean | null | undefined;

type DataTableColumn<T> = {
  id: string;
  /** The column's label, in its head and in the Columns menu. */
  header: React.ReactNode;
  /** What the cell shows; defaults to the accessor's value. */
  cell?: (row: T) => React.ReactNode;
  /** The value used to sort and filter. */
  accessor?: (row: T) => Value;
  sortable?: boolean;
  /** Whether the Columns menu can hide it (default true). */
  hideable?: boolean;
  /** Hidden until turned on in the Columns menu. */
  hidden?: boolean;
  align?: "start" | "end";
  className?: string;
};

type SortState = { id: string; desc: boolean } | null;

const text = (v: Value) => (v instanceof Date ? v.toISOString() : v == null ? "" : String(v));
function compare(a: Value, b: Value) {
  if (a == null && b == null) return 0;
  if (a == null) return 1;
  if (b == null) return -1;
  if (a instanceof Date && b instanceof Date) return a.getTime() - b.getTime();
  if (typeof a === "number" && typeof b === "number") return a - b;
  return text(a).localeCompare(text(b), undefined, { numeric: true, sensitivity: "base" });
}

/** A sortable head label: a ghost key whose arrow shows the direction (both carets while unsorted). */
function DataTableColumnHeader({ title, sorted, onSort, className }: { title: React.ReactNode; sorted: false | "asc" | "desc"; onSort?: () => void; className?: string }) {
  if (!onSort) return <span className={className}>{title}</span>;
  const Icon = sorted === "asc" ? ArrowUpIcon : sorted === "desc" ? ArrowDownIcon : CaretUpDownIcon;
  return (
    <button
      type="button"
      data-slot="data-table-column-header"
      onClick={onSort}
      className={cn("-mx-2 inline-flex h-8 items-center gap-1.5 rounded-pill px-2 font-sans text-body leading-tight font-normal text-fg-muted outline-none active:brightness-95 active:transition-none transition-colors duration-150 ease-out hover:bg-subtle-hover active:bg-subtle-hover hover:text-fg focus-visible:outline-2 focus-visible:outline-focus-ring data-[sorted=true]:text-fg motion-reduce:transition-none", className)}
      data-sorted={!!sorted}
    >
      {title}
      <Icon aria-hidden weight={sorted ? "bold" : "regular"} className="size-4" />
    </button>
  );
}

/** The Columns key and its menu of checkboxes, one per column that can be hidden. */
function DataTableViewOptions({ columns, visible, onVisibleChange }: { columns: { id: string; header: React.ReactNode }[]; visible: Record<string, boolean>; onVisibleChange: (id: string, on: boolean) => void }) {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="outline" className="h-10 shrink-0">
          <ColumnsIcon weight="fill" />
          Columns
        </Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent align="end" className="w-52">
        <DropdownMenuLabel>Show columns</DropdownMenuLabel>
        <DropdownMenuSeparator />
        {columns.map((c) => (
          <DropdownMenuCheckboxItem key={c.id} checked={visible[c.id] !== false} onCheckedChange={(on) => onVisibleChange(c.id, on === true)} onSelect={(e) => e.preventDefault()}>
            {c.header}
          </DropdownMenuCheckboxItem>
        ))}
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

/** The page numbers around the current one: the ends, its neighbors and ellipses between. */
function pageList(page: number, count: number): (number | "gap")[] {
  if (count <= 7) return Array.from({ length: count }, (_, i) => i);
  const set = new Set([0, count - 1, page - 1, page, page + 1].filter((p) => p >= 0 && p < count));
  const sorted = [...set].sort((a, b) => a - b);
  return sorted.flatMap((p, i) => (i && p - sorted[i - 1] > 1 ? (["gap", p] as const) : [p]));
}

/** The lilac bar under the table: the selection count, rows per page and the pages. */
function DataTablePagination({ page, pageCount, onPageChange, pageSize, pageSizes, onPageSizeChange, selected, total, className }: { page: number; pageCount: number; onPageChange: (page: number) => void; pageSize?: number; pageSizes?: number[]; onPageSizeChange?: (size: number) => void; selected?: number; total?: number; className?: string }) {
  const go = (p: number) => (e: React.MouseEvent) => {
    e.preventDefault();
    if (p >= 0 && p < pageCount) onPageChange(p);
  };
  return (
    <Pagination bar className={cn("flex-wrap justify-between gap-x-4 gap-y-1", className)}>
      <div className="flex min-h-7.5 flex-wrap items-center gap-x-4 gap-y-1 pl-2 text-body leading-tight text-fg-muted">
        {selected !== undefined && total !== undefined && (
          <span aria-live="polite">
            {selected} of {total} selected
          </span>
        )}
        {pageSizes && pageSize && onPageSizeChange && (
          <span className="flex items-center gap-2">
            <span id="data-table-page-size">Rows per page</span>
            <Select value={String(pageSize)} onValueChange={(v) => onPageSizeChange(Number(v))}>
              <SelectTrigger size="sm" aria-labelledby="data-table-page-size" className="h-7.5 w-18 pr-2 pl-2.5">
                <SelectValue />
              </SelectTrigger>
              <SelectContent>
                {pageSizes.map((s) => (
                  <SelectItem key={s} value={String(s)}>
                    {s}
                  </SelectItem>
                ))}
              </SelectContent>
            </Select>
          </span>
        )}
      </div>
      <PaginationContent className="ml-auto">
        <PaginationItem>
          <PaginationPrevious href="#" onClick={go(page - 1)} aria-disabled={page === 0 || undefined} tabIndex={page === 0 ? -1 : undefined} />
        </PaginationItem>
        {pageList(page, pageCount).map((p, i) =>
          p === "gap" ? (
            <PaginationItem key={`gap-${i}`}>
              <PaginationEllipsis />
            </PaginationItem>
          ) : (
            <PaginationItem key={p}>
              <PaginationLink href="#" isActive={p === page} onClick={go(p)} aria-label={`Page ${p + 1}`}>
                {p + 1}
              </PaginationLink>
            </PaginationItem>
          ),
        )}
        <PaginationItem>
          <PaginationNext href="#" onClick={go(page + 1)} aria-disabled={page >= pageCount - 1 || undefined} tabIndex={page >= pageCount - 1 ? -1 : undefined} />
        </PaginationItem>
      </PaginationContent>
    </Pagination>
  );
}

type DataTableProps<T> = {
  columns: DataTableColumn<T>[];
  data: T[];
  getRowId: (row: T) => string;
  /** A filter field over these columns' values (all filterable columns when omitted). */
  filter?: { placeholder?: string; columns?: string[] } | false;
  /** A checkbox column for choosing rows. */
  selectable?: boolean;
  selection?: string[];
  onSelectionChange?: (ids: string[]) => void;
  /** Hide the Columns key. */
  hideViewOptions?: boolean;
  pageSize?: number;
  /** Offer these page sizes in the bar. */
  pageSizes?: number[];
  defaultSort?: SortState;
  /** Shown in the body when nothing matches. */
  empty?: React.ReactNode;
  /** Actions at the toolbar's right, before the Columns key. */
  toolbar?: React.ReactNode;
  /** What a row is called in labels ("mailbox"). */
  rowName?: string;
  className?: string;
};

function DataTable<T>({ columns, data, getRowId, filter = {}, selectable = false, selection: selectionProp, onSelectionChange, hideViewOptions = false, pageSize: pageSizeProp = 10, pageSizes, defaultSort = null, empty = "No results.", toolbar, rowName = "row", className }: DataTableProps<T>) {
  const [query, setQuery] = React.useState("");
  const [sort, setSort] = React.useState<SortState>(defaultSort);
  const [page, setPage] = React.useState(0);
  const [pageSize, setPageSize] = React.useState(pageSizeProp);
  const [visible, setVisible] = React.useState<Record<string, boolean>>(() => Object.fromEntries(columns.map((c) => [c.id, !c.hidden])));
  const [selectionInner, setSelectionInner] = React.useState<string[]>([]);
  const selection = selectionProp ?? selectionInner;
  const setSelection = (ids: string[]) => {
    if (!selectionProp) setSelectionInner(ids);
    onSelectionChange?.(ids);
  };

  const shown = columns.filter((c) => visible[c.id] !== false);
  const filterColumns = filter ? columns.filter((c) => c.accessor && (!filter.columns || filter.columns.includes(c.id))) : [];

  const q = query.trim().toLowerCase();
  let rows = q ? data.filter((row) => filterColumns.some((c) => text(c.accessor!(row)).toLowerCase().includes(q))) : data;
  const sortColumn = sort && columns.find((c) => c.id === sort.id);
  if (sort && sortColumn?.accessor) {
    const get = sortColumn.accessor;
    rows = [...rows].sort((a, b) => compare(get(a), get(b)) * (sort.desc ? -1 : 1));
  }

  const pageCount = Math.max(1, Math.ceil(rows.length / pageSize));
  const current = Math.min(page, pageCount - 1);
  const pageRows = rows.slice(current * pageSize, current * pageSize + pageSize);
  const pageIds = pageRows.map(getRowId);
  const allOnPage = pageIds.length > 0 && pageIds.every((id) => selection.includes(id));
  const someOnPage = pageIds.some((id) => selection.includes(id));

  const toggleSort = (id: string) => setSort((s) => (s?.id !== id ? { id, desc: false } : s.desc ? null : { id, desc: true }));

  return (
    <div data-slot="data-table" className={cn("grid min-w-0 grid-cols-[minmax(0,1fr)] gap-3", className)}>
      {(filter || !hideViewOptions || toolbar) && (
        <div data-slot="data-table-toolbar" className="flex flex-wrap items-center gap-2">
          {filter && (
            <InputGroup className="max-w-80 min-w-48 flex-1">
              <InputGroupAddon>
                <MagnifyingGlassIcon />
              </InputGroupAddon>
              <InputGroupInput
                type="search"
                value={query}
                onChange={(e) => {
                  setQuery(e.target.value);
                  setPage(0);
                }}
                placeholder={filter.placeholder ?? "Filter"}
                aria-label={filter.placeholder ?? "Filter"}
              />
            </InputGroup>
          )}
          <div className="ml-auto flex items-center gap-2">
            {toolbar}
            {!hideViewOptions && (
              <DataTableViewOptions
                columns={columns.filter((c) => c.hideable !== false)}
                visible={visible}
                onVisibleChange={(id, on) => setVisible((v) => ({ ...v, [id]: on }))}
              />
            )}
          </div>
        </div>
      )}
      <div>
        <Table>
          <TableHeader>
            <TableRow className="hover:[&>td]:bg-transparent">
              {selectable && (
                <TableHead>
                  <Checkbox
                    aria-label={`Select every ${rowName} on this page`}
                    checked={allOnPage ? true : someOnPage ? "indeterminate" : false}
                    onCheckedChange={(on) => setSelection(on === true ? [...new Set([...selection, ...pageIds])] : selection.filter((id) => !pageIds.includes(id)))}
                  />
                </TableHead>
              )}
              {shown.map((c) => (
                <TableHead key={c.id} aria-sort={sort?.id === c.id ? (sort.desc ? "descending" : "ascending") : c.sortable ? "none" : undefined} className={cn(c.align === "end" && "text-right", c.className)}>
                  <DataTableColumnHeader title={c.header} sorted={sort?.id === c.id ? (sort.desc ? "desc" : "asc") : false} onSort={c.sortable && c.accessor ? () => toggleSort(c.id) : undefined} />
                </TableHead>
              ))}
            </TableRow>
          </TableHeader>
          <TableBody>
            {pageRows.length ? (
              pageRows.map((row) => {
                const id = getRowId(row);
                const selected = selection.includes(id);
                return (
                  <TableRow key={id} data-state={selected ? "selected" : undefined}>
                    {selectable && (
                      <TableCell>
                        <Checkbox aria-label={`Select ${rowName} ${id}`} checked={selected} onCheckedChange={(on) => setSelection(on === true ? [...selection, id] : selection.filter((s) => s !== id))} />
                      </TableCell>
                    )}
                    {shown.map((c) => (
                      <TableCell key={c.id} className={cn(c.align === "end" && "text-right", c.className)}>
                        {c.cell ? c.cell(row) : text(c.accessor?.(row))}
                      </TableCell>
                    ))}
                  </TableRow>
                );
              })
            ) : (
              <TableRow className="hover:[&>td]:bg-surface">
                <TableCell colSpan={shown.length + (selectable ? 1 : 0)} className="h-24 text-center whitespace-normal text-fg-muted">
                  {empty}
                </TableCell>
              </TableRow>
            )}
          </TableBody>
        </Table>
        <DataTablePagination
          className="mt-1"
          page={current}
          pageCount={pageCount}
          onPageChange={setPage}
          pageSize={pageSize}
          pageSizes={pageSizes}
          onPageSizeChange={(s) => {
            setPageSize(s);
            setPage(0);
          }}
          selected={selectable ? selection.length : undefined}
          total={selectable ? data.length : undefined}
        />
      </div>
    </div>
  );
}

export { DataTable, DataTableColumnHeader, DataTablePagination, DataTableViewOptions };
export type { DataTableColumn, DataTableProps, SortState };

```

# Date Picker
The select trigger with a calendar glyph that opens the calendar in a white panel, for one date or a range, with optional presets.

Install: npx inkbox-ds add date-picker
Requires: theme, calendar, popover, utils
Packages: @phosphor-icons/react
Exports: DatePicker, DateRangePicker, formatDate, formatRange, DatePickerProps, DateRangePickerProps
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the select trigger (Any State) and the menu panel, with the calendar


## Usage
Use DatePicker for one date (a key's expiry, when to send) and DateRangePicker for a period (the delivery log's range). Pass value and onValueChange, a placeholder, and presets for common choices (Today, Last 7 days). Pass calendar props such as disabled days through calendar. Give it a name to submit the date as YYYY-MM-DD with a form.
- Avoid: A text field people must type a date into
- Avoid: A range picker for a single date
- Avoid: More than six presets
- Avoid: Closing a range before both ends are picked


## Examples
Example components: npx inkbox-ds add date-picker calendar label
[Preview](https://inkbox-ds.vercel.app/preview/date-picker/Preview) | [Range](https://inkbox-ds.vercel.app/preview/date-picker/Range) | [Presets](https://inkbox-ds.vercel.app/preview/date-picker/Presets) | [States](https://inkbox-ds.vercel.app/preview/date-picker/States)

examples/date-picker.tsx

```tsx
"use client";

import * as React from "react";

import type { DateRange } from "@/components/ui/calendar";
import { DatePicker, DateRangePicker } from "@/components/ui/date-picker";
import { Label } from "@/components/ui/label";

// A fixed today, so the examples read the same on every visit.
const TODAY = new Date(2026, 7, 8);
const days = (n: number) => new Date(TODAY.getFullYear(), TODAY.getMonth(), TODAY.getDate() + n);

export function Preview() {
  const [date, setDate] = React.useState<Date | undefined>();
  return (
    <div className="grid w-full max-w-72 gap-1">
      <Label htmlFor="expires">Key expires</Label>
      <DatePicker id="expires" value={date} onValueChange={setDate} placeholder="Never" calendar={{ today: TODAY, disabled: { before: TODAY } }} />
    </div>
  );
}

export function Range() {
  const [range, setRange] = React.useState<DateRange | undefined>({ from: days(-6), to: TODAY });
  return (
    <div className="grid w-full max-w-80 gap-1">
      <Label htmlFor="log-range">Delivery log</Label>
      <DateRangePicker id="log-range" value={range} onValueChange={setRange} calendar={{ today: TODAY, disabled: { after: TODAY } }} />
    </div>
  );
}

export function Presets() {
  const [send, setSend] = React.useState<Date | undefined>(days(1));
  const [range, setRange] = React.useState<DateRange | undefined>();
  return (
    <div className="grid w-full max-w-80 gap-4">
      <div className="grid gap-1">
        <Label htmlFor="send-at">Send the summary on</Label>
        <DatePicker
          id="send-at"
          value={send}
          onValueChange={setSend}
          calendar={{ today: TODAY, disabled: { before: TODAY } }}
          presets={[
            { label: "Today", value: TODAY },
            { label: "Tomorrow", value: days(1) },
            { label: "In a week", value: days(7) },
            { label: "In a month", value: days(30) },
          ]}
        />
      </div>
      <div className="grid gap-1">
        <Label htmlFor="usage-range">Usage</Label>
        <DateRangePicker
          id="usage-range"
          value={range}
          onValueChange={setRange}
          placeholder="All time"
          calendar={{ today: TODAY, disabled: { after: TODAY } }}
          presets={[
            { label: "Last 7 days", value: { from: days(-6), to: TODAY } },
            { label: "Last 30 days", value: { from: days(-29), to: TODAY } },
            { label: "Last 90 days", value: { from: days(-89), to: TODAY } },
          ]}
        />
      </div>
    </div>
  );
}

export function States() {
  return (
    <div className="grid w-full max-w-72 gap-3">
      <DatePicker aria-label="Disabled date" defaultValue={TODAY} disabled />
      <div className="grid gap-1">
        <DatePicker aria-label="Start date" aria-invalid calendar={{ today: TODAY }} />
        <p className="text-caption leading-body text-danger">Choose a start date.</p>
      </div>
    </div>
  );
}

```

## Source

components/ui/date-picker.tsx

```tsx
"use client";

import * as React from "react";
import { CalendarBlankIcon, CaretDownIcon } from "@phosphor-icons/react/ssr";

import { Calendar, type CalendarProps, type DateRange } from "@/components/ui/calendar";
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
import { cn } from "@/lib/utils";

// A date field (extrapolated from the Inkbox console, Figma 427:2715: the select trigger "Any State" and its menu
// panel). The trigger is the select's white 40px key with 8px corners and the Shadow/S ring: a 24px calendar glyph in
// the softer purple, the date in 14px ink (the placeholder in the light purple) and the bold caret at the right. The
// calendar opens under it in the popover's white panel, growing from the trigger. Presets sit in a column of 36px rows
// at the panel's left, the chosen one on the lilac. A single date closes the panel when picked; a range closes once both
// ends are set. Opening puts focus on the chosen day (or today), so the arrow keys work at once.
const TRIGGER =
  "flex h-10 w-full min-w-0 cursor-pointer items-center gap-2.5 rounded-pill bg-surface pr-3 pl-3 font-sans text-body leading-tight whitespace-nowrap text-fg shadow-s outline-none transition-[box-shadow] duration-150 ease-out focus-visible:shadow-[var(--ds-shadow-s),var(--ds-shadow-focus)] disabled:cursor-not-allowed disabled:bg-subtle disabled:text-fg-muted aria-invalid:shadow-[0_0_0_1px_var(--ds-color-status-danger)] data-[empty=true]:text-fg-subtle motion-reduce:transition-none";

type Preset<T> = { label: string; value: T };

function formatDate(date: Date, locale?: string, options: Intl.DateTimeFormatOptions = { month: "short", day: "numeric", year: "numeric" }) {
  return new Intl.DateTimeFormat(locale, options).format(date);
}

function formatRange(range: DateRange | undefined, locale?: string) {
  if (!range?.from) return undefined;
  if (!range.to) return `${formatDate(range.from, locale)} -`;
  const sameYear = range.from.getFullYear() === range.to.getFullYear();
  return `${formatDate(range.from, locale, sameYear ? { month: "short", day: "numeric" } : undefined)} - ${formatDate(range.to, locale)}`;
}

function DatePickerTrigger({ empty, label, className, children, ...props }: React.ComponentProps<"button"> & { empty: boolean; label?: string }) {
  return (
    <PopoverTrigger asChild>
      <button type="button" data-slot="date-picker-trigger" data-empty={empty} aria-label={label} className={cn(TRIGGER, className)} {...props}>
        <CalendarBlankIcon aria-hidden weight="fill" className="size-6 shrink-0 text-icon-secondary" />
        <span className="min-w-0 flex-1 truncate text-left">{children}</span>
        <CaretDownIcon aria-hidden weight="bold" className="size-4 shrink-0 text-fg" />
      </button>
    </PopoverTrigger>
  );
}

function Presets<T>({ presets, isActive, onPick }: { presets: Preset<T>[]; isActive: (p: Preset<T>) => boolean; onPick: (value: T) => void }) {
  return (
    <div data-slot="date-picker-presets" role="group" aria-label="Presets" className="flex gap-1 overflow-x-auto border-line-subtle p-1 max-sm:border-b sm:w-40 sm:flex-col sm:border-r">
      {presets.map((p) => (
        <button
          key={p.label}
          type="button"
          aria-pressed={isActive(p)}
          onClick={() => onPick(p.value)}
          className="flex h-9 shrink-0 items-center rounded-pill px-2.5 text-left font-sans text-body leading-tight whitespace-nowrap text-fg outline-none transition-colors duration-150 ease-out hover:bg-subtle focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus-ring aria-pressed:bg-subtle motion-reduce:transition-none"
        >
          {p.label}
        </button>
      ))}
    </div>
  );
}

const sameDay = (a?: Date, b?: Date) => !!a && !!b && a.toDateString() === b.toDateString();

type CalendarPassThrough = Omit<CalendarProps, "mode" | "selected" | "onSelect" | "required" | "min" | "max">;

type DatePickerProps = {
  value?: Date;
  defaultValue?: Date;
  onValueChange?: (date: Date | undefined) => void;
  placeholder?: string;
  disabled?: boolean;
  /** Shortcuts beside the calendar (Today, In a week). */
  presets?: Preset<Date>[];
  /** Props for the calendar inside (disabled days, the first day of the week, today). */
  calendar?: CalendarPassThrough;
  locale?: string;
  id?: string;
  name?: string;
  className?: string;
  "aria-invalid"?: boolean;
  "aria-label"?: string;
};

function DatePicker({ value: valueProp, defaultValue, onValueChange, placeholder = "Pick a date", disabled, presets, calendar, locale, id, name, className, ...aria }: DatePickerProps) {
  const [open, setOpen] = React.useState(false);
  const [inner, setInner] = React.useState(defaultValue);
  const value = valueProp !== undefined ? valueProp : inner;
  const set = (d: Date | undefined) => {
    if (valueProp === undefined) setInner(d);
    onValueChange?.(d);
  };
  return (
    <Popover open={open} onOpenChange={setOpen}>
      <DatePickerTrigger id={id} empty={!value} disabled={disabled} className={className} aria-invalid={aria["aria-invalid"]} label={aria["aria-label"]}>
        {value ? formatDate(value, locale) : placeholder}
      </DatePickerTrigger>
      {name && <input type="hidden" name={name} value={value ? value.toISOString().slice(0, 10) : ""} />}
      <PopoverContent data-slot="date-picker-content" align="start" onOpenAutoFocus={(e) => e.preventDefault()} className="w-auto gap-0 overflow-hidden p-0">
        <div className="flex flex-col sm:flex-row">
          {presets && (
            <Presets
              presets={presets}
              isActive={(p) => sameDay(p.value, value)}
              onPick={(d) => {
                set(d);
                setOpen(false);
              }}
            />
          )}
          <Calendar
            {...calendar}
            mode="single"
            selected={value}
            defaultMonth={value ?? calendar?.defaultMonth}
            locale={locale}
            autoFocus
            onSelect={(d) => {
              set(d);
              if (d) setOpen(false);
            }}
          />
        </div>
      </PopoverContent>
    </Popover>
  );
}

type DateRangePickerProps = Omit<DatePickerProps, "value" | "defaultValue" | "onValueChange" | "presets"> & {
  value?: DateRange;
  defaultValue?: DateRange;
  onValueChange?: (range: DateRange | undefined) => void;
  presets?: Preset<DateRange>[];
  /** How many months show side by side (two by default; one on a phone). */
  numberOfMonths?: number;
};

function DateRangePicker({ value: valueProp, defaultValue, onValueChange, placeholder = "Pick a date range", disabled, presets, calendar, locale, numberOfMonths = 2, id, name, className, ...aria }: DateRangePickerProps) {
  const [open, setOpen] = React.useState(false);
  const [inner, setInner] = React.useState(defaultValue);
  const value = valueProp !== undefined ? valueProp : inner;
  const set = (r: DateRange | undefined) => {
    if (valueProp === undefined) setInner(r);
    onValueChange?.(r);
  };
  const [narrow, setNarrow] = React.useState(false);
  React.useEffect(() => {
    const query = window.matchMedia("(max-width: 39.99rem)");
    const update = () => setNarrow(query.matches);
    update();
    query.addEventListener("change", update);
    return () => query.removeEventListener("change", update);
  }, []);
  const label = formatRange(value, locale);
  return (
    <Popover open={open} onOpenChange={setOpen}>
      <DatePickerTrigger id={id} empty={!label} disabled={disabled} className={className} aria-invalid={aria["aria-invalid"]} label={aria["aria-label"]}>
        {label ?? placeholder}
      </DatePickerTrigger>
      {name && (
        <>
          <input type="hidden" name={`${name}From`} value={value?.from ? value.from.toISOString().slice(0, 10) : ""} />
          <input type="hidden" name={`${name}To`} value={value?.to ? value.to.toISOString().slice(0, 10) : ""} />
        </>
      )}
      <PopoverContent data-slot="date-range-picker-content" align="start" onOpenAutoFocus={(e) => e.preventDefault()} className="w-auto max-w-[calc(100vw-2rem)] gap-0 overflow-hidden p-0">
        <div className="flex flex-col sm:flex-row">
          {presets && (
            <Presets
              presets={presets}
              isActive={(p) => sameDay(p.value.from, value?.from) && sameDay(p.value.to, value?.to)}
              onPick={(r) => {
                set(r);
                setOpen(false);
              }}
            />
          )}
          <Calendar
            {...calendar}
            mode="range"
            selected={value}
            defaultMonth={value?.from ?? calendar?.defaultMonth}
            numberOfMonths={narrow ? 1 : numberOfMonths}
            locale={locale}
            autoFocus
            onSelect={(r) => {
              set(r);
              if (r?.from && r.to) setOpen(false);
            }}
          />
        </div>
      </PopoverContent>
    </Popover>
  );
}

export { DatePicker, DateRangePicker, formatDate, formatRange };
export type { DatePickerProps, DateRangePickerProps };

```

# Dialog
A centered white panel with 16px corners over the blurred, ink-tinted page.

Install: npx inkbox-ds add dialog
Requires: theme, surface, utils
Packages: @chakra-ui/react, @phosphor-icons/react
Exports: Dialog, DialogBody, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger
Client boundary: yes
Reference: Figma 427:2715: Modal - Create Agent, Modal - Created, modal-bg


## Usage
Use for a short task that needs the person's full attention (Create Agent Identity) or a result they must read before moving on (the new API key). Put the title in DialogHeader, the content in DialogBody and a full-width default Button at the end of the body for the one action.
- Avoid: A dark scrim
- Avoid: A dialog that opens another dialog
- Avoid: A drop shadow under the panel
- Avoid: Scaling from zero


## Examples
Example components: npx inkbox-ds add dialog button input label
[Preview](https://inkbox-ds.vercel.app/preview/dialog/Preview)

examples/dialog.tsx

```tsx
"use client";

import { Button } from "@/components/ui/button";
import { Dialog, DialogBody, DialogContent, DialogDescription, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui/dialog";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";

export function Preview() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button>Create Agent</Button>
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Create Agent Identity</DialogTitle>
          <DialogDescription className="sr-only">Choose a handle and a display name for the new agent.</DialogDescription>
        </DialogHeader>
        <DialogBody className="grid gap-3">
          <div className="grid gap-1">
            <Label htmlFor="handle">Agent handle</Label>
            <Input id="handle" placeholder="acme-support" />
          </div>
          <div className="grid gap-1">
            <Label htmlFor="display">Agent display name</Label>
            <Input id="display" placeholder="Robert" />
          </div>
          <Button className="mt-3 w-full">Create Agent Identity</Button>
        </DialogBody>
      </DialogContent>
    </Dialog>
  );
}

```

## Source

components/ui/dialog.tsx

```tsx
"use client";

import * as React from "react";
import { Dialog as ChakraDialog, Portal } from "@chakra-ui/react";
import { XIcon } from "@phosphor-icons/react/ssr";

import { usePortalContainer } from "@/lib/surface";
import { cn } from "@/lib/utils";

// The console's dialog (Create Agent Identity, @test-agent is ready!): a white panel with 16px corners on the page
// behind it, which takes the ink at 12 percent over a light blur. A 68px head holds the 20px regular title 24px in from
// the left and a faint 20px close glyph 24px from the right; the body keeps the same 24px sides. It stays centered and
// opens from 96 percent with a fade (250ms, the strong ease-out); it closes faster than it opens.
type DialogProps = Omit<React.ComponentProps<typeof ChakraDialog.Root>, "onOpenChange"> & { onOpenChange?: (open: boolean) => void };
function Dialog({ onOpenChange, ...props }: DialogProps) {
  return <ChakraDialog.Root unstyled data-slot="dialog" onOpenChange={(details) => onOpenChange?.(details.open)} {...props} />;
}

function DialogTrigger(props: React.ComponentProps<typeof ChakraDialog.Trigger>) {
  return <ChakraDialog.Trigger data-slot="dialog-trigger" {...props} />;
}

function DialogPortal(props: React.ComponentProps<typeof Portal>) {
  const container = usePortalContainer();
  const portalRef = React.useMemo(() => container ? { current: container } : undefined, [container]);
  return <Portal data-slot="dialog-portal" container={portalRef} {...props} />;
}

function DialogClose(props: React.ComponentProps<typeof ChakraDialog.CloseTrigger>) {
  return <ChakraDialog.CloseTrigger unstyled data-slot="dialog-close" {...props} />;
}

function DialogOverlay({ className, ...props }: React.ComponentProps<typeof ChakraDialog.Backdrop>) {
  return (
    <ChakraDialog.Backdrop unstyled
      data-slot="dialog-overlay"
      className={cn("fixed inset-0 z-50 bg-scrim backdrop-blur-[var(--ds-blur-scrim)] data-[state=closed]:animate-fade-out data-[state=open]:animate-fade-in", className)}
      {...props}
    />
  );
}

function DialogContent({ className, children, showClose = true, ...props }: React.ComponentProps<typeof ChakraDialog.Content> & { showClose?: boolean }) {
  return (
    <DialogPortal>
      <DialogOverlay />
      <ChakraDialog.Positioner>
      <ChakraDialog.Content
        unstyled
        data-slot="dialog-content"
        className={cn(
          "z-50 flex max-h-[calc(100dvh-2rem)] w-[calc(100%-2rem)] max-w-133.5 flex-col overflow-hidden rounded-panel bg-surface text-fg outline-none data-[state=closed]:animate-dialog-out data-[state=open]:animate-dialog-in",
          className,
        )}
        {...props}
      >
        {children}
        {showClose && (
          <ChakraDialog.CloseTrigger unstyled
            data-slot="dialog-close"
            className="absolute top-5 right-5 inline-flex size-7 items-center justify-center rounded-pill text-fg-faint outline-none active:brightness-95 active:transition-none transition-colors duration-150 ease-out hover:text-fg-muted focus-visible:outline-2 focus-visible:outline-focus-ring motion-reduce:transition-none"
          >
            <XIcon className="size-5.5" weight="bold" />
            <span className="sr-only">Close</span>
          </ChakraDialog.CloseTrigger>
        )}
      </ChakraDialog.Content>
      </ChakraDialog.Positioner>
    </DialogPortal>
  );
}

function DialogHeader({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="dialog-header" className={cn("flex min-h-17 shrink-0 flex-col justify-center gap-1 py-5 pr-14 pl-6", className)} {...props} />;
}

/** The scrolling middle of a dialog, with the head's 24px sides. */
function DialogBody({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="dialog-body" className={cn("min-h-0 flex-1 overflow-y-auto px-6 pb-6", className)} {...props} />;
}

function DialogFooter({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="dialog-footer" className={cn("flex shrink-0 flex-col-reverse gap-3 px-6 pb-6 sm:flex-row sm:justify-end", className)} {...props} />;
}

function DialogTitle({ className, ...props }: React.ComponentProps<typeof ChakraDialog.Title>) {
  return <ChakraDialog.Title unstyled data-slot="dialog-title" className={cn("font-sans text-h3 leading-heading font-normal text-fg", className)} {...props} />;
}

function DialogDescription({ className, ...props }: React.ComponentProps<typeof ChakraDialog.Description>) {
  return <ChakraDialog.Description unstyled data-slot="dialog-description" className={cn("text-body leading-body text-fg-secondary", className)} {...props} />;
}

export { Dialog, DialogBody, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger };

```

# Direction
Sets left-to-right or right-to-left for every component inside it.

Install: npx inkbox-ds add direction
Requires: theme
Packages: radix-ui
Exports: DirectionProvider, useDirection
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): no visual of its own


## Usage
Wrap an app or a section in DirectionProvider dir="rtl" when its language reads right to left, and set dir on the element too. Menus, sliders, tabs and carousels then flip their keyboard and layout direction.
- Avoid: Mixing directions inside one menu or form
- Avoid: Mirroring logos or code


## Examples
Example components: npx inkbox-ds add direction tabs
[Preview](https://inkbox-ds.vercel.app/preview/direction/Preview)

examples/direction.tsx

```tsx
import { DirectionProvider } from "@/components/ui/direction";
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";

export function Preview() {
  return (
    <DirectionProvider dir="rtl">
      <div dir="rtl" className="grid gap-3">
        <p className="text-body text-fg">صندوق البريد</p>
        <Tabs defaultValue="mailboxes">
          <TabsList>
            <TabsTrigger value="mailboxes">صناديق البريد</TabsTrigger>
            <TabsTrigger value="rules">قواعد الاتصال</TabsTrigger>
            <TabsTrigger value="domains">النطاقات</TabsTrigger>
          </TabsList>
        </Tabs>
      </div>
    </DirectionProvider>
  );
}

```

## Source

components/ui/direction.tsx

```tsx
"use client";

import * as React from "react";
import { Direction } from "radix-ui";

// Sets the reading direction (ltr or rtl) for every Radix-based component inside it, so menus, sliders and tabs flip
// for right-to-left text. It renders nothing of its own; set dir on the element you wrap too.
function DirectionProvider({ dir, direction, children }: React.ComponentProps<typeof Direction.DirectionProvider> & { direction?: React.ComponentProps<typeof Direction.DirectionProvider>["dir"] }) {
  return <Direction.DirectionProvider dir={direction ?? dir}>{children}</Direction.DirectionProvider>;
}

const useDirection = Direction.useDirection;

export { DirectionProvider, useDirection };

```

# Drawer
A panel pulled up from the bottom edge with a handle, dragged away with a flick or a pull.

Install: npx inkbox-ds add drawer
Requires: theme, surface, utils
Packages: radix-ui
Exports: Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerOverlay, DrawerPortal, DrawerTitle, DrawerTrigger
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): Modal - Create Agent (panel, title, scrim) and the field-edge lilac


## Usage
Use on phones for a task or a choice from the bottom of the screen (choose a phone line, confirm a key). Pair it with Dialog on larger screens when the same task is needed. Set direction for other edges.
- Avoid: A drawer without its handle
- Avoid: Dragging that fights scrolling content (mark scroll areas data-drawer-no-drag)
- Avoid: A drawer on desktop for long forms


## Examples
Example components: npx inkbox-ds add drawer button
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/drawer/Preview) | [Directions](https://inkbox-ds.vercel.app/preview/drawer/Directions) | [Open](https://inkbox-ds.vercel.app/preview/drawer/Open)

examples/drawer.tsx

```tsx
"use client";

import * as React from "react";
import { CheckCircleIcon } from "@phosphor-icons/react/ssr";

import { Button } from "@/components/ui/button";
import { Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerTitle, DrawerTrigger } from "@/components/ui/drawer";

const LINES = [
  { id: "shared", title: "Shared", body: "Assigned when someone connects to this agent." },
  { id: "dedicated", title: "Dedicated", body: "A number only this agent uses." },
];

function ChooseLine({ onChoose }: { onChoose?: () => void }) {
  const [line, setLine] = React.useState("shared");
  return (
    <>
      <DrawerHeader>
        <DrawerTitle>iMessage line</DrawerTitle>
        <DrawerDescription>Choose how recipients connect to @acme.</DrawerDescription>
      </DrawerHeader>
      <div role="radiogroup" aria-label="iMessage line" className="grid gap-2 px-6">
        {LINES.map((l) => (
          <button
            key={l.id}
            type="button"
            role="radio"
            aria-checked={line === l.id}
            onClick={() => setLine(l.id)}
            className="flex items-start gap-3 rounded-control bg-subtle p-3.5 text-left outline-none transition-colors duration-150 ease-out hover:bg-subtle-hover focus-visible:outline-2 focus-visible:outline-focus-ring aria-checked:bg-surface aria-checked:shadow-s motion-reduce:transition-none"
          >
            <span className="grid flex-1 gap-0.5">
              <span className="text-body font-medium text-fg">{l.title}</span>
              <span className="text-body text-fg-muted">{l.body}</span>
            </span>
            {line === l.id && <CheckCircleIcon weight="fill" className="size-5.5 text-success" />}
          </button>
        ))}
      </div>
      <DrawerFooter>
        <Button onClick={onChoose}>Use {line} line</Button>
        <DrawerClose asChild>
          <Button variant="secondary">Cancel</Button>
        </DrawerClose>
      </DrawerFooter>
    </>
  );
}

export function Preview() {
  const [open, setOpen] = React.useState(false);
  return (
    <div className="flex justify-center">
      <Drawer open={open} onOpenChange={setOpen}>
        <DrawerTrigger asChild>
          <Button variant="outline">Choose a line</Button>
        </DrawerTrigger>
        <DrawerContent>
          <div className="mx-auto w-full max-w-md">
            <ChooseLine onChoose={() => setOpen(false)} />
          </div>
        </DrawerContent>
      </Drawer>
    </div>
  );
}

export function Directions() {
  const directions = ["bottom", "top", "right", "left"] as const;
  return (
    <div className="flex flex-wrap justify-center gap-3">
      {directions.map((direction) => (
        <Drawer key={direction} direction={direction}>
          <DrawerTrigger asChild>
            <Button variant="outline" className="capitalize">
              {direction}
            </Button>
          </DrawerTrigger>
          <DrawerContent>
            <DrawerHeader>
              <DrawerTitle>Drawer from the {direction}</DrawerTitle>
              <DrawerDescription>Drag it back toward its edge, or flick it, to close.</DrawerDescription>
            </DrawerHeader>
            <DrawerFooter>
              <DrawerClose asChild>
                <Button variant="secondary">Close</Button>
              </DrawerClose>
            </DrawerFooter>
          </DrawerContent>
        </Drawer>
      ))}
    </div>
  );
}

export function Open() {
  return (
    <div className="min-h-120">
      <Drawer defaultOpen>
        <DrawerContent>
          <div className="mx-auto w-full max-w-md">
            <ChooseLine />
          </div>
        </DrawerContent>
      </Drawer>
    </div>
  );
}

```

## Source

components/ui/drawer.tsx

```tsx
"use client";

import * as React from "react";
import { Dialog as DrawerPrimitive } from "radix-ui";

import { usePortalContainer } from "@/lib/surface";
import { cn } from "@/lib/utils";

// A drawer, drawn as the console's dialog (Figma 427:2715: Create Agent Identity) and pulled from an edge: white over
// the blurred, ink-tinted page, 16px corners on its inner edge, a 40 by 4px handle in the field-edge lilac, a 20px
// regular title and 24px sides. It slides in on the drawer curve and can be dragged away: a flick (faster than 0.11px
// per ms) or a pull past a third of its size closes it, a shorter pull springs back on the same curve, and pulling the
// other way meets growing resistance instead of a wall. The drag follows the pointer even off the panel (pointer
// capture) and ignores a second finger.
type Direction = "bottom" | "top" | "left" | "right";

const DrawerContext = React.createContext<{ direction: Direction; setOpen: (open: boolean) => void }>({ direction: "bottom", setOpen: () => {} });

function Drawer({ open: openProp, defaultOpen = false, onOpenChange, direction = "bottom", ...props }: React.ComponentProps<typeof DrawerPrimitive.Root> & { direction?: Direction }) {
  const [uncontrolled, setUncontrolled] = React.useState(defaultOpen);
  const open = openProp ?? uncontrolled;
  const setOpen = React.useCallback(
    (next: boolean) => {
      if (openProp === undefined) setUncontrolled(next);
      onOpenChange?.(next);
    },
    [openProp, onOpenChange],
  );
  return (
    <DrawerContext.Provider value={{ direction, setOpen }}>
      <DrawerPrimitive.Root data-slot="drawer" open={open} onOpenChange={setOpen} {...props} />
    </DrawerContext.Provider>
  );
}

function DrawerTrigger(props: React.ComponentProps<typeof DrawerPrimitive.Trigger>) {
  return <DrawerPrimitive.Trigger data-slot="drawer-trigger" {...props} />;
}

function DrawerPortal(props: React.ComponentProps<typeof DrawerPrimitive.Portal>) {
  const container = usePortalContainer();
  return <DrawerPrimitive.Portal data-slot="drawer-portal" container={container} {...props} />;
}

function DrawerClose(props: React.ComponentProps<typeof DrawerPrimitive.Close>) {
  return <DrawerPrimitive.Close data-slot="drawer-close" {...props} />;
}

function DrawerOverlay({ className, ...props }: React.ComponentProps<typeof DrawerPrimitive.Overlay>) {
  return (
    <DrawerPrimitive.Overlay
      data-slot="drawer-overlay"
      className={cn("fixed inset-0 z-50 bg-scrim backdrop-blur-[var(--ds-blur-scrim)] data-[state=closed]:animate-fade-out data-[state=open]:animate-fade-in", className)}
      {...props}
    />
  );
}

const PLACE: Record<Direction, string> = {
  bottom: "inset-x-0 bottom-0 max-h-[85dvh] rounded-t-panel data-[state=closed]:animate-sheet-out-bottom data-[state=open]:animate-sheet-in-bottom",
  top: "inset-x-0 top-0 max-h-[85dvh] flex-col-reverse rounded-b-panel data-[state=closed]:animate-sheet-out-top data-[state=open]:animate-sheet-in-top",
  right: "inset-y-0 right-0 w-3/4 flex-row-reverse rounded-l-panel sm:max-w-96 data-[state=closed]:animate-sheet-out-right data-[state=open]:animate-sheet-in-right",
  left: "inset-y-0 left-0 w-3/4 flex-row rounded-r-panel sm:max-w-96 data-[state=closed]:animate-sheet-out-left data-[state=open]:animate-sheet-in-left",
};

// Where a pull closes the drawer: toward its own edge (positive for bottom and right).
const AXIS: Record<Direction, { axis: "x" | "y"; sign: 1 | -1 }> = { bottom: { axis: "y", sign: 1 }, top: { axis: "y", sign: -1 }, right: { axis: "x", sign: 1 }, left: { axis: "x", sign: -1 } };
const VELOCITY = 0.11;
const SKIP = "button, a, input, textarea, select, [role=slider], [contenteditable=true], [data-drawer-no-drag]";

function useDrag(direction: Direction, close: () => void) {
  const panel = React.useRef<HTMLDivElement>(null);
  const drag = React.useRef<{ id: number; start: number; at: number; time: number } | null>(null);
  const { axis, sign } = AXIS[direction];
  const translate = (px: number) => (axis === "y" ? `translateY(${px}px)` : `translateX(${px}px)`);

  const onPointerDown = (event: React.PointerEvent<HTMLDivElement>) => {
    if (drag.current || event.button !== 0) return; // one pointer only
    if ((event.target as Element).closest(SKIP)) return;
    if (window.getSelection()?.toString()) return;
    const start = axis === "y" ? event.clientY : event.clientX;
    drag.current = { id: event.pointerId, start, at: 0, time: performance.now() };
    event.currentTarget.setPointerCapture(event.pointerId);
    if (panel.current) panel.current.style.transition = "none";
  };

  const onPointerMove = (event: React.PointerEvent<HTMLDivElement>) => {
    const d = drag.current;
    if (!d || d.id !== event.pointerId || !panel.current) return;
    const raw = (axis === "y" ? event.clientY : event.clientX) - d.start;
    const toward = raw * sign;
    // Toward the edge it follows the pointer; away from it, resistance grows with distance.
    const moved = toward >= 0 ? toward : -Math.sqrt(-toward) * 2;
    d.at = moved;
    panel.current.style.transform = translate(moved * sign);
  };

  const end = (event: React.PointerEvent<HTMLDivElement>) => {
    const d = drag.current;
    if (!d || d.id !== event.pointerId || !panel.current) return;
    drag.current = null;
    const el = panel.current;
    const size = axis === "y" ? el.offsetHeight : el.offsetWidth;
    const velocity = Math.abs(d.at) / Math.max(1, performance.now() - d.time);
    if (d.at > 0 && (d.at > size / 3 || velocity > VELOCITY)) {
      el.style.transition = "";
      close();
      return;
    }
    el.style.transition = "transform 500ms var(--ds-easing-drawer)";
    el.style.transform = "";
    const reset = () => {
      el.style.transition = "";
      el.removeEventListener("transitionend", reset);
    };
    el.addEventListener("transitionend", reset);
  };

  return { panel, handlers: { onPointerDown, onPointerMove, onPointerUp: end, onPointerCancel: end } };
}

function DrawerContent({ className, children, ...props }: React.ComponentProps<typeof DrawerPrimitive.Content>) {
  const { direction, setOpen } = React.useContext(DrawerContext);
  const { panel, handlers } = useDrag(direction, () => setOpen(false));
  const vertical = direction === "bottom" || direction === "top";
  return (
    <DrawerPortal>
      <DrawerOverlay />
      <DrawerPrimitive.Content
        ref={panel}
        data-slot="drawer-content"
        data-direction={direction}
        className={cn("group/drawer fixed z-50 flex touch-none bg-surface text-fg shadow-dialog outline-none", vertical ? "flex-col" : "", PLACE[direction], className)}
        {...handlers}
        {...props}
      >
        <div aria-hidden data-slot="drawer-handle" className={cn("shrink-0 rounded-pill bg-line-field", vertical ? "mx-auto my-3 h-1 w-10" : "my-auto mx-3 h-10 w-1")} />
        <div className="flex min-h-0 min-w-0 flex-1 touch-auto flex-col overflow-auto">{children}</div>
      </DrawerPrimitive.Content>
    </DrawerPortal>
  );
}

function DrawerHeader({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="drawer-header" className={cn("flex flex-col gap-1 px-6 pt-2 pb-4 group-data-[direction=bottom]/drawer:text-center group-data-[direction=top]/drawer:text-center md:text-left md:group-data-[direction=bottom]/drawer:text-left", className)} {...props} />;
}

function DrawerFooter({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="drawer-footer" className={cn("mt-auto flex flex-col gap-3 p-6", className)} {...props} />;
}

function DrawerTitle({ className, ...props }: React.ComponentProps<typeof DrawerPrimitive.Title>) {
  return <DrawerPrimitive.Title data-slot="drawer-title" className={cn("font-sans text-h3 leading-heading font-normal text-fg", className)} {...props} />;
}

function DrawerDescription({ className, ...props }: React.ComponentProps<typeof DrawerPrimitive.Description>) {
  return <DrawerPrimitive.Description data-slot="drawer-description" className={cn("text-body leading-body text-fg-secondary", className)} {...props} />;
}

export { Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerOverlay, DrawerPortal, DrawerTitle, DrawerTrigger };

```

# Dropdown Menu
A raised white menu of 36px rows with filled glyphs, lilac highlight, purple section labels and checks.

Install: npx inkbox-ds add dropdown-menu
Requires: theme, surface, utils
Packages: @chakra-ui/react, @phosphor-icons/react
Exports: DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): nav rows (38px, 8px corners, filled glyphs, lilac current row), section labels (Channels), the raised panel


## Usage
Use for actions on one thing behind a single control (an agent's row actions, the account menu), and for small option sets with DropdownMenuCheckboxItem or DropdownMenuRadioItem. Mark a destructive action with variant="destructive" and keep it last, after a separator.
- Avoid: Navigation between pages in a dropdown
- Avoid: More than one level of submenu
- Avoid: Animating the highlighted row
- Avoid: Icons that move on hover


## Examples
Example components: npx inkbox-ds add dropdown-menu button
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/dropdown-menu/Preview) | [Open](https://inkbox-ds.vercel.app/preview/dropdown-menu/Open) | [RowActions](https://inkbox-ds.vercel.app/preview/dropdown-menu/RowActions) | [Options](https://inkbox-ds.vercel.app/preview/dropdown-menu/Options)

examples/dropdown-menu.tsx

```tsx
"use client";

import * as React from "react";
import { BuildingsIcon, DotsThreeIcon, GearSixIcon, KeyIcon, PencilSimpleIcon, QuestionIcon, SignOutIcon, TrashIcon, UsersThreeIcon } from "@phosphor-icons/react/ssr";

import { Button } from "@/components/ui/button";
import {
  DropdownMenu,
  DropdownMenuCheckboxItem,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";

function AccountItems() {
  return (
    <>
      <DropdownMenuLabel>Robert Ligthart</DropdownMenuLabel>
      <DropdownMenuGroup>
        <DropdownMenuItem>
          <BuildingsIcon weight="fill" />
          My Organisation
          <DropdownMenuShortcut>⇧⌘O</DropdownMenuShortcut>
        </DropdownMenuItem>
        <DropdownMenuItem>
          <KeyIcon weight="fill" />
          API Keys
          <DropdownMenuShortcut>⌘K</DropdownMenuShortcut>
        </DropdownMenuItem>
        <DropdownMenuSub>
          <DropdownMenuSubTrigger>
            <UsersThreeIcon weight="fill" />
            Invite people
          </DropdownMenuSubTrigger>
          <DropdownMenuSubContent>
            <DropdownMenuItem>By email</DropdownMenuItem>
            <DropdownMenuItem>Copy invite link</DropdownMenuItem>
          </DropdownMenuSubContent>
        </DropdownMenuSub>
        <DropdownMenuItem>
          <GearSixIcon weight="fill" />
          Settings
        </DropdownMenuItem>
      </DropdownMenuGroup>
      <DropdownMenuSeparator />
      <DropdownMenuItem>
        <QuestionIcon weight="fill" />
        Help
      </DropdownMenuItem>
      <DropdownMenuItem disabled>Billing (admins only)</DropdownMenuItem>
      <DropdownMenuSeparator />
      <DropdownMenuItem variant="destructive">
        <SignOutIcon weight="fill" />
        Log out
      </DropdownMenuItem>
    </>
  );
}

export function Preview() {
  return (
    <div className="flex justify-center">
      <DropdownMenu>
        <DropdownMenuTrigger asChild>
          <Button variant="outline">Account</Button>
        </DropdownMenuTrigger>
        <DropdownMenuContent align="start" className="w-60">
          <AccountItems />
        </DropdownMenuContent>
      </DropdownMenu>
    </div>
  );
}

export function Open() {
  return (
    <div className="flex min-h-110 items-start justify-center">
      <DropdownMenu defaultOpen>
        <DropdownMenuTrigger asChild>
          <Button variant="outline">Account</Button>
        </DropdownMenuTrigger>
        <DropdownMenuContent className="w-60">
          <AccountItems />
        </DropdownMenuContent>
      </DropdownMenu>
    </div>
  );
}

export function RowActions() {
  return (
    <div className="flex justify-center">
      <DropdownMenu>
        <DropdownMenuTrigger asChild>
          <Button variant="ghost" size="icon" aria-label="Actions for @acme">
            <DotsThreeIcon weight="bold" />
          </Button>
        </DropdownMenuTrigger>
        <DropdownMenuContent align="end" className="w-48">
          <DropdownMenuItem>
            <PencilSimpleIcon weight="fill" />
            Edit agent
          </DropdownMenuItem>
          <DropdownMenuItem>
            <KeyIcon weight="fill" />
            Rotate API key
          </DropdownMenuItem>
          <DropdownMenuSeparator />
          <DropdownMenuItem variant="destructive">
            <TrashIcon weight="fill" />
            Delete agent
          </DropdownMenuItem>
        </DropdownMenuContent>
      </DropdownMenu>
    </div>
  );
}

export function Options() {
  const [channels, setChannels] = React.useState({ email: true, phone: true, imessage: false });
  const [mode, setMode] = React.useState("edge");
  return (
    <div className="flex justify-center">
      <DropdownMenu>
        <DropdownMenuTrigger asChild>
          <Button variant="outline">Filter</Button>
        </DropdownMenuTrigger>
        <DropdownMenuContent className="w-56">
          <DropdownMenuLabel>Channels</DropdownMenuLabel>
          <DropdownMenuCheckboxItem checked={channels.email} onCheckedChange={(v) => setChannels((c) => ({ ...c, email: v === true }))}>
            Email
          </DropdownMenuCheckboxItem>
          <DropdownMenuCheckboxItem checked={channels.phone} onCheckedChange={(v) => setChannels((c) => ({ ...c, phone: v === true }))}>
            Phone
          </DropdownMenuCheckboxItem>
          <DropdownMenuCheckboxItem checked={channels.imessage} onCheckedChange={(v) => setChannels((c) => ({ ...c, imessage: v === true }))}>
            iMessage
          </DropdownMenuCheckboxItem>
          <DropdownMenuSeparator />
          <DropdownMenuLabel>Tunnel TLS mode</DropdownMenuLabel>
          <DropdownMenuRadioGroup value={mode} onValueChange={setMode}>
            <DropdownMenuRadioItem value="edge">Edge (default)</DropdownMenuRadioItem>
            <DropdownMenuRadioItem value="passthrough">Passthrough</DropdownMenuRadioItem>
          </DropdownMenuRadioGroup>
        </DropdownMenuContent>
      </DropdownMenu>
    </div>
  );
}

```

## Source

components/ui/dropdown-menu.tsx

```tsx
"use client";

import * as React from "react";
import { Menu as ChakraMenu, Portal } from "@chakra-ui/react";
import { CaretRightIcon, CheckIcon } from "@phosphor-icons/react/ssr";

import { usePortalContainer } from "@/lib/surface";
import { cn } from "@/lib/utils";

// A menu, extrapolated from the console (Figma 427:2715): the panel is a raised white panel (16px corners, the floating
// shadow) with 4px of padding; items are 36px rows with fully rounded corners like the rail's nav rows, a 20px glyph in the
// action-glyph purple 10px from a 14px ink label, and the lilac under the highlighted row. Section labels are 13px in
// the label purple ("Channels"), separators the rail's hairline, shortcuts 12px muted, destructive items red. The
// panel grows out of its trigger from 96 percent with a fade; highlighting a row is instant (menus are used by keyboard
// and many times a day).
const CONTENT =
  "z-50 max-h-(--available-height) min-w-48 overflow-x-hidden overflow-y-auto rounded-panel bg-surface p-1 text-fg shadow-floating outline-none data-[state=closed]:animate-fade-out data-[state=open]:animate-fade-in";
const ITEM =
  "relative flex h-9 cursor-default items-center gap-2.5 rounded-pill px-2.5 font-sans text-body leading-tight text-fg outline-none select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[highlighted]:bg-subtle data-[inset]:pl-10.5 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-5.5 [&_svg:not([class*='text-'])]:text-icon-secondary";

// The trigger, so focus can go back to it when the menu closes.
const TriggerRef = React.createContext<React.RefObject<HTMLElement | null> | null>(null);

type MenuProps = Omit<React.ComponentProps<typeof ChakraMenu.Root>, "onOpenChange"> & { onOpenChange?: (open: boolean) => void };
function DropdownMenu({ onOpenChange, onExitComplete, ...props }: MenuProps) {
  const trigger = React.useRef<HTMLElement | null>(null);
  const restore = React.useCallback(() => {
    if (document.activeElement === document.body || document.activeElement === null) trigger.current?.focus();
  }, []);
  return (
    <TriggerRef.Provider value={trigger}>
      <ChakraMenu.Root
        unstyled
        data-slot="dropdown-menu"
        onOpenChange={(details) => {
          onOpenChange?.(details.open);
          // Closing right after a keyboard open can leave focus on the page body (the menu's own first-item focus lands
          // in the panel as it leaves). Hand it back to the trigger then; focus moved on purpose (a dialog an item opened)
          // is left alone.
          if (!details.open) requestAnimationFrame(() => requestAnimationFrame(restore));
        }}
        // And again once the panel has left: its unmount can drop focus after the close.
        onExitComplete={() => {
          onExitComplete?.();
          restore();
        }}
        {...props}
      />
    </TriggerRef.Provider>
  );
}

function DropdownMenuPortal(props: React.ComponentProps<typeof Portal>) {
  const container = usePortalContainer();
  const portalRef = React.useMemo(() => container ? { current: container } : undefined, [container]);
  return <Portal data-slot="dropdown-menu-portal" container={portalRef} {...props} />;
}

function DropdownMenuTrigger({ ref, ...props }: React.ComponentProps<typeof ChakraMenu.Trigger>) {
  const trigger = React.useContext(TriggerRef);
  const setRef = React.useCallback(
    (node: HTMLButtonElement | null) => {
      if (trigger) trigger.current = node;
      if (typeof ref === "function") ref(node);
      else if (ref) ref.current = node;
    },
    [trigger, ref],
  );
  return <ChakraMenu.Trigger ref={setRef} data-slot="dropdown-menu-trigger" {...props} />;
}

function DropdownMenuContent({ className, sideOffset = 6, align, onFocus, ...props }: Omit<React.ComponentProps<typeof ChakraMenu.Content>, "align"> & { sideOffset?: number; align?: "start" | "center" | "end" }) {
  const trigger = React.useContext(TriggerRef);
  return (
    <DropdownMenuPortal>
      <ChakraMenu.Positioner data-align={align}>
        <ChakraMenu.Content
          unstyled
          data-slot="dropdown-menu-content"
          style={{ marginBlockStart: sideOffset }}
          className={cn(CONTENT, "origin-(--transform-origin)", className)}
          onFocus={(event) => {
            onFocus?.(event);
            // A keyboard open focuses the panel a moment later; if the menu closed first (a quick Escape), that focus
            // would land in a panel that is leaving. Send it back to the trigger.
            if (event.currentTarget.getAttribute("data-state") === "closed") trigger?.current?.focus();
          }}
          {...props}
        />
      </ChakraMenu.Positioner>
    </DropdownMenuPortal>
  );
}

function DropdownMenuGroup(props: React.ComponentProps<typeof ChakraMenu.ItemGroup>) {
  return <ChakraMenu.ItemGroup data-slot="dropdown-menu-group" {...props} />;
}

function DropdownMenuItem({ className, inset, variant = "default", value, children, ...props }: Omit<React.ComponentProps<typeof ChakraMenu.Item>, "value"> & { value?: string; inset?: boolean; variant?: "default" | "destructive" }) {
  return (
    <ChakraMenu.Item unstyled
      data-slot="dropdown-menu-item"
      data-inset={inset || undefined}
      data-variant={variant}
      value={value ?? (typeof children === "string" ? children : "menu-item")}
      className={cn(ITEM, "data-[variant=destructive]:text-danger data-[variant=destructive]:[&_svg]:text-danger", className)}
      {...props}
    >{children}</ChakraMenu.Item>
  );
}

function DropdownMenuCheckboxItem({ className, children, checked, onCheckedChange, value, ...props }: Omit<React.ComponentProps<typeof ChakraMenu.CheckboxItem>, "onCheckedChange" | "value"> & { value?: string; onCheckedChange?: (checked: boolean) => void }) {
  return (
    <ChakraMenu.CheckboxItem unstyled data-slot="dropdown-menu-checkbox-item" value={value ?? (typeof children === "string" ? children : "menu-checkbox-item")} checked={checked} onCheckedChange={onCheckedChange} className={cn(ITEM, "pl-10.5", className)} {...props}>
      <span className="pointer-events-none absolute left-2.5 flex size-5.5 items-center justify-center">
        <ChakraMenu.ItemIndicator>
          <CheckIcon weight="bold" className="size-4.5 text-fg-brand" />
        </ChakraMenu.ItemIndicator>
      </span>
      {children}
    </ChakraMenu.CheckboxItem>
  );
}

type RadioMenuProps = Omit<React.ComponentProps<typeof ChakraMenu.RadioItemGroup>, "onValueChange"> & { onValueChange?: (value: string) => void };
function DropdownMenuRadioGroup({ onValueChange, ...props }: RadioMenuProps) {
  return <ChakraMenu.RadioItemGroup data-slot="dropdown-menu-radio-group" onValueChange={(details) => onValueChange?.(details.value)} {...props} />;
}

// The selected choice wears the console's radio mark: a pink ring around white.
function DropdownMenuRadioItem({ className, children, value, ...props }: Omit<React.ComponentProps<typeof ChakraMenu.RadioItem>, "value"> & { value?: string }) {
  return (
    <ChakraMenu.RadioItem unstyled data-slot="dropdown-menu-radio-item" value={value ?? (typeof children === "string" ? children : "menu-radio-item")} className={cn(ITEM, "pl-10.5", className)} {...props}>
      <span className="pointer-events-none absolute left-2.5 flex size-5.5 items-center justify-center">
        <ChakraMenu.ItemIndicator>
          <span className="block size-3.5 rounded-pill border-[3.5px] border-pink bg-surface" />
        </ChakraMenu.ItemIndicator>
      </span>
      {children}
    </ChakraMenu.RadioItem>
  );
}

// A heading above items: shadcn's label stands alone, so it is a plain element rather than Chakra's group label (which
// must sit inside a group).
function DropdownMenuLabel({ className, inset, ...props }: React.ComponentProps<"div"> & { inset?: boolean }) {
  return <div data-slot="dropdown-menu-label" data-inset={inset || undefined} className={cn("px-2.5 pt-2 pb-1 font-sans text-body-sm leading-tight text-fg-label data-[inset]:pl-10.5", className)} {...props} />;
}

function DropdownMenuSeparator({ className, ...props }: React.ComponentProps<typeof ChakraMenu.Separator>) {
  return <ChakraMenu.Separator data-slot="dropdown-menu-separator" className={cn("-mx-1 my-1 h-px bg-line-subtle", className)} {...props} />;
}

function DropdownMenuShortcut({ className, ...props }: React.ComponentProps<"span">) {
  return <span data-slot="dropdown-menu-shortcut" className={cn("ml-auto pl-4 font-sans text-caption text-fg-muted", className)} {...props} />;
}

function DropdownMenuSub({ onOpenChange, ...props }: MenuProps) {
  return <ChakraMenu.Root unstyled data-slot="dropdown-menu-sub" onOpenChange={(details) => onOpenChange?.(details.open)} {...props} />;
}

function DropdownMenuSubTrigger({ className, inset, children, ...props }: React.ComponentProps<typeof ChakraMenu.TriggerItem> & { inset?: boolean }) {
  return (
    <ChakraMenu.TriggerItem unstyled data-slot="dropdown-menu-sub-trigger" data-inset={inset || undefined} className={cn(ITEM, "data-[state=open]:bg-subtle", className)} {...props}>
      {children}
      <CaretRightIcon className="ml-auto size-4.5 text-fg-muted" />
    </ChakraMenu.TriggerItem>
  );
}

function DropdownMenuSubContent({ className, ...props }: React.ComponentProps<typeof ChakraMenu.Content>) {
  return (
    <DropdownMenuPortal>
      <ChakraMenu.Positioner>
        <ChakraMenu.Content unstyled data-slot="dropdown-menu-sub-content" className={cn(CONTENT, "origin-(--transform-origin)", className)} {...props} />
      </ChakraMenu.Positioner>
    </DropdownMenuPortal>
  );
}

export {
  DropdownMenu,
  DropdownMenuCheckboxItem,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuPortal,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger,
};

```

# Empty
The centered empty state: the 3D octopus under an arc of glyph circles, a 22px bold title, a short description and a purple pill.

Install: npx inkbox-ds add empty
Requires: theme, utils
Packages: class-variance-authority
Exports: Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMascot, EmptyMedia, EmptyOrbit, EmptyTitle
Client boundary: not required by this entry file
Reference: Figma 427:2715: Dashboard - empty state (Create Your First Agent), Agent Workspace - Inbox - Not selected (No email selected)


## Usage
Use where a list or pane has nothing yet (Create Your First Agent, No email selected). Put EmptyOrbit (up to five filled glyphs of what the area holds) and EmptyMascot in an EmptyMedia variant="mascot", then the title, a one-sentence description and one default Button with a plus. For a smaller pane, use EmptyMedia variant="icon" with one glyph.
- Avoid: More than one action
- Avoid: Animating the orbit
- Avoid: A title longer than five words
- Avoid: Gray stock illustrations


## Examples
Example components: npx inkbox-ds add empty button
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/empty/Preview) | [NoSelection](https://inkbox-ds.vercel.app/preview/empty/NoSelection) | [Icon](https://inkbox-ds.vercel.app/preview/empty/Icon)

examples/empty.tsx

```tsx
import { ArrowsHorizontalIcon, ChatCircleIcon, EnvelopeIcon, EnvelopeOpenIcon, EnvelopeSimpleIcon, PaperPlaneTiltIcon, PhoneIcon, PlusIcon, TextAlignLeftIcon, TrayIcon, VaultIcon } from "@phosphor-icons/react/ssr";

import { Button } from "@/components/ui/button";
import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMascot, EmptyMedia, EmptyOrbit, EmptyTitle } from "@/components/ui/empty";

export function Preview() {
  return (
    <Empty className="min-h-100">
      <EmptyMedia variant="mascot">
        <EmptyOrbit>
          <EnvelopeIcon weight="fill" />
          <PhoneIcon weight="fill" />
          <ChatCircleIcon weight="bold" className="size-7 text-success" />
          <ArrowsHorizontalIcon weight="bold" />
          <VaultIcon weight="fill" />
        </EmptyOrbit>
        <EmptyMascot src="/octopus.png" />
      </EmptyMedia>
      <EmptyHeader>
        <EmptyTitle>Create Your First Agent</EmptyTitle>
        <EmptyDescription>Set up an identity to unlock mailbox, phone, and vault features</EmptyDescription>
      </EmptyHeader>
      <EmptyContent>
        <Button>
          <PlusIcon />
          Create Agent
        </Button>
      </EmptyContent>
    </Empty>
  );
}

export function NoSelection() {
  return (
    <Empty className="min-h-100">
      <EmptyMedia variant="mascot">
        <EmptyOrbit>
          <TextAlignLeftIcon weight="bold" />
          <EnvelopeOpenIcon weight="fill" />
          <EnvelopeSimpleIcon weight="fill" />
          <PaperPlaneTiltIcon weight="fill" />
          <TrayIcon weight="fill" />
        </EmptyOrbit>
        <EmptyMascot src="/octopus.png" />
      </EmptyMedia>
      <EmptyHeader>
        <EmptyTitle>No email selected</EmptyTitle>
        <EmptyDescription>Select an email from the list to read it</EmptyDescription>
      </EmptyHeader>
      <EmptyContent>
        <Button>
          <PlusIcon />
          Compose Email
        </Button>
      </EmptyContent>
    </Empty>
  );
}

export function Icon() {
  return (
    <Empty className="min-h-72">
      <EmptyMedia variant="icon">
        <TrayIcon weight="fill" />
      </EmptyMedia>
      <EmptyHeader>
        <EmptyTitle>No emails to display</EmptyTitle>
        <EmptyDescription>New mail for @acme lands here.</EmptyDescription>
      </EmptyHeader>
    </Empty>
  );
}

```

## Source

components/ui/empty.tsx

```tsx
import * as React from "react";
import { cva, type VariantProps } from "class-variance-authority";

import { cn } from "@/lib/utils";

// The console's empty states (Figma 427:2715: Create Your First Agent, No email selected). Centered: the media, a 22px
// bold ink title, a 14px description on 24px lines in the secondary purple, at most 248px wide, then the action (a purple pill). The
// `mascot` media is the 3D octopus with a soft shadow under it; EmptyOrbit arcs up to five 40px white circles holding
// the channel glyphs above it. Nothing moves: the empty state is seen every time the page loads.
function Empty({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="empty" className={cn("flex min-w-0 flex-1 flex-col items-center justify-center gap-5 p-6 text-center text-balance", className)} {...props} />;
}

function EmptyHeader({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="empty-header" className={cn("flex max-w-sm flex-col items-center gap-2", className)} {...props} />;
}

const emptyMediaVariants = cva("flex shrink-0 items-center justify-center [&_svg]:pointer-events-none [&_svg]:shrink-0", {
  variants: {
    variant: {
      default: "bg-transparent",
      icon: "size-10 rounded-pill border border-line-subtle bg-surface text-icon-secondary shadow-line [&_svg:not([class*='size-'])]:size-5.5",
      mascot: "relative mb-1 w-56 flex-col",
    },
  },
  defaultVariants: { variant: "default" },
});

function EmptyMedia({ className, variant = "default", ...props }: React.ComponentProps<"div"> & VariantProps<typeof emptyMediaVariants>) {
  return <div data-slot="empty-media" data-variant={variant} className={cn(emptyMediaVariants({ variant }), className)} {...props} />;
}

// Where each circle sits on the arc over the mascot, outermost first: left offset and top, in px of a 224px box.
const ORBIT = [
  [0, 32],
  [44, 12],
  [92, 0],
  [140, 12],
  [184, 32],
] as const;

/** Up to five glyphs in white circles, arced over the mascot (email, phone, iMessage, agent to agent, vault). */
function EmptyOrbit({ className, children, ...props }: React.ComponentProps<"div">) {
  const glyphs = React.Children.toArray(children).slice(0, 5);
  const start = Math.floor((5 - glyphs.length) / 2);
  return (
    <div data-slot="empty-orbit" aria-hidden className={cn("relative h-13 w-56", className)} {...props}>
      {glyphs.map((glyph, i) => {
        const [left, top] = ORBIT[start + i];
        return (
          <span key={i} className="absolute flex size-10 items-center justify-center rounded-pill border border-line-subtle bg-surface text-icon-secondary shadow-line [&_svg:not([class*='size-'])]:size-5.5 [&_svg]:shrink-0" style={{ left, top }}>
            {glyph}
          </span>
        );
      })}
    </div>
  );
}

/** The 3D octopus, standing on a soft shadow. Pass its image as src (the brand's octopus.png). */
function EmptyMascot({ className, alt = "", ...props }: React.ComponentProps<"img">) {
  return (
    <span data-slot="empty-mascot" className="relative -mt-1 flex justify-center after:absolute after:-bottom-1 after:left-1/2 after:h-3 after:w-20 after:-translate-x-1/2 after:rounded-pill after:bg-ink after:opacity-10 after:blur-md">
      {/* eslint-disable-next-line @next/next/no-img-element */}
      <img alt={alt} width={90} height={80} className={cn("relative z-10 h-20 w-auto select-none", className)} draggable={false} {...props} />
    </span>
  );
}

function EmptyTitle({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="empty-title" className={cn("font-sans text-h2 leading-tight font-bold text-fg", className)} {...props} />;
}

function EmptyDescription({ className, ...props }: React.ComponentProps<"p">) {
  return <p data-slot="empty-description" className={cn("max-w-62 text-body leading-6 text-pretty text-fg-secondary [&>a]:text-fg-brand [&>a]:underline [&>a]:underline-offset-4", className)} {...props} />;
}

function EmptyContent({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="empty-content" className={cn("flex w-full max-w-sm min-w-0 flex-col items-center gap-3 text-body text-balance", className)} {...props} />;
}

export { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMascot, EmptyMedia, EmptyOrbit, EmptyTitle };

```

# Field
A field's label, control, description and error stacked 4px apart, fields 12px apart, with the 'or' hairline between two ways in.

Install: npx inkbox-ds add field
Requires: theme, label, utils
Packages: class-variance-authority
Exports: Field, FieldContent, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend, FieldSeparator, FieldSet, FieldTitle
Client boundary: yes
Reference: Figma 427:2715: Login (Email address, Password, Forgot password?, or), Vault (Vault key and its description), Create Agent Identity (is not available, Will be displayed as)


## Usage
Wrap every form control in Field with a FieldLabel above it; add FieldDescription for a hint (Enter a vault key or generate a random one) and FieldError, with data-invalid on the Field and aria-invalid on the control, when the value is rejected. Group fields in FieldGroup, related choices in FieldSet with a FieldLegend. Put an action beside the label (Forgot password?) in a row with justify-between. Use orientation horizontal for a label beside its control, and FieldSeparator with "or" between a form and other ways in.
- Avoid: A red label on an invalid field
- Avoid: A placeholder as the only label
- Avoid: Errors larger than 12px
- Avoid: Fields closer than 12px


## Examples
Example components: npx inkbox-ds add field button input
[Preview](https://inkbox-ds.vercel.app/preview/field/Preview) | [Description](https://inkbox-ds.vercel.app/preview/field/Description) | [Invalid](https://inkbox-ds.vercel.app/preview/field/Invalid) | [Horizontal](https://inkbox-ds.vercel.app/preview/field/Horizontal) | [Fieldset](https://inkbox-ds.vercel.app/preview/field/Fieldset)

examples/field.tsx

```tsx
import { Button } from "@/components/ui/button";
import { Field, FieldContent, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend, FieldSeparator, FieldSet, FieldTitle } from "@/components/ui/field";
import { Input } from "@/components/ui/input";

export function Preview() {
  return (
    <form className="mx-auto w-full max-w-86">
      <FieldGroup>
        <Field>
          <FieldLabel htmlFor="login-email">Email address</FieldLabel>
          <Input id="login-email" type="email" placeholder="your@email.com" autoComplete="email" />
        </Field>
        <Field>
          <div className="flex items-center justify-between gap-3">
            <FieldLabel htmlFor="login-password">Password</FieldLabel>
            <a href="#forgot" className="text-body leading-body text-fg-brand underline-offset-4 hover:underline">
              Forgot password?
            </a>
          </div>
          <Input id="login-password" type="password" autoComplete="current-password" />
        </Field>
        <Button type="submit" className="w-full">Log in</Button>
        <FieldSeparator>or</FieldSeparator>
        <Button variant="secondary" className="w-full">Continue with Google</Button>
      </FieldGroup>
    </form>
  );
}

export function Description() {
  return (
    <Field className="max-w-162.5">
      <FieldLabel htmlFor="vault-key">Vault key</FieldLabel>
      <FieldDescription>Enter a vault key or generate a random one. You&apos;ll need this to unlock the vault.</FieldDescription>
      <Input id="vault-key" type="password" defaultValue="correct-horse-battery" />
    </Field>
  );
}

export function Invalid() {
  return (
    <Field data-invalid="true" className="max-w-100">
      <FieldLabel htmlFor="handle">Agent handle</FieldLabel>
      <Input id="handle" defaultValue="acme-support" aria-invalid aria-describedby="handle-error" />
      <div className="flex flex-wrap items-center gap-x-2 gap-y-1 text-caption leading-body text-fg">
        Will be displayed as
        <span className="rounded-pill bg-subtle px-1.5 py-0.5">@acme-support</span>
        <FieldError id="handle-error">(is not available)</FieldError>
      </div>
    </Field>
  );
}

export function Horizontal() {
  return (
    <FieldGroup className="max-w-120">
      <Field orientation="horizontal">
        <FieldContent>
          <FieldTitle>Retention</FieldTitle>
          <FieldDescription>Days to keep delivered messages before they are deleted.</FieldDescription>
        </FieldContent>
        <Input aria-label="Retention in days" type="number" defaultValue={30} className="w-24" />
      </Field>
      <Field orientation="responsive">
        <FieldLabel htmlFor="display-name">Display name</FieldLabel>
        <Input id="display-name" placeholder="Agent display name" className="@md/field-group:w-64" />
      </Field>
    </FieldGroup>
  );
}

export function Fieldset() {
  return (
    <FieldSet className="max-w-120">
      <FieldLegend>Webhook destination</FieldLegend>
      <FieldDescription>Inkbox signs every delivery with the key for this agent identity.</FieldDescription>
      <FieldGroup>
        <Field>
          <FieldLabel htmlFor="webhook-url">Endpoint URL</FieldLabel>
          <Input id="webhook-url" type="url" placeholder="https://example.com/inkbox" />
        </Field>
        <Field data-invalid="true">
          <FieldLabel htmlFor="webhook-secret">Signing secret</FieldLabel>
          <Input id="webhook-secret" aria-invalid defaultValue="short" />
          <FieldError errors={[{ message: "Use at least 32 characters." }, { message: "Include letters and numbers." }]} />
        </Field>
      </FieldGroup>
    </FieldSet>
  );
}

```

## Source

components/ui/field.tsx

```tsx
"use client";

import * as React from "react";
import { cva, type VariantProps } from "class-variance-authority";

import { Label } from "@/components/ui/label";
import { cn } from "@/lib/utils";

// A form's fields as the console lays them out (Figma 427:2715, Login, Vault, Create Agent Identity). A field is its
// 14px label on a 24px line, 4px above the control; fields sit 12px apart. A description under it is 14px muted
// (Vault key: "Enter a vault key or generate a random one"); an error is 12px red (is not available). "or" between two
// ways in is 14px muted on a hairline. A field marked data-invalid keeps its label ink: only the control and the
// message turn red.
function FieldSet({ className, ...props }: React.ComponentProps<"fieldset">) {
  return <fieldset data-slot="field-set" className={cn("m-0 flex min-w-0 flex-col gap-4 border-0 p-0 has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3", className)} {...props} />;
}

function FieldLegend({ className, variant = "legend", ...props }: React.ComponentProps<"legend"> & { variant?: "legend" | "label" }) {
  return (
    <legend
      data-slot="field-legend"
      data-variant={variant}
      className={cn("mb-1 p-0 font-sans text-fg data-[variant=label]:text-body data-[variant=label]:leading-body data-[variant=label]:font-normal data-[variant=legend]:text-body-lg data-[variant=legend]:leading-body data-[variant=legend]:font-medium", className)}
      {...props}
    />
  );
}

function FieldGroup({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="field-group" className={cn("group/field-group @container/field-group flex w-full flex-col gap-3 [&>[data-slot=field-group]]:gap-4", className)} {...props} />;
}

const fieldVariants = cva("group/field flex w-full gap-1 data-[disabled=true]:opacity-50", {
  variants: {
    orientation: {
      // Label over control (Email address over its field).
      vertical: "flex-col [&>*]:w-full [&>.sr-only]:w-auto",
      // Label beside its control (a channel row and its switch, a checkbox and its label).
      horizontal: "flex-row items-center gap-3 [&>[data-slot=field-label]]:flex-auto has-[>[data-slot=field-content]]:items-start has-[>[data-slot=field-content]]:[&>[role=checkbox],&>[role=radio]]:mt-0.5",
      // Over on a narrow form, beside from 28rem of container.
      responsive: "flex-col [&>*]:w-full [&>.sr-only]:w-auto @md/field-group:flex-row @md/field-group:items-center @md/field-group:gap-3 @md/field-group:[&>*]:w-auto @md/field-group:[&>[data-slot=field-label]]:flex-auto",
    },
  },
  defaultVariants: { orientation: "vertical" },
});

function Field({ className, orientation = "vertical", ...props }: React.ComponentProps<"div"> & VariantProps<typeof fieldVariants>) {
  return <div role="group" data-slot="field" data-orientation={orientation} className={cn(fieldVariants({ orientation }), className)} {...props} />;
}

function FieldContent({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="field-content" className={cn("group/field-content flex min-w-0 flex-1 flex-col gap-0.5 leading-body", className)} {...props} />;
}

// A label that wraps a whole field becomes a choice card: the field edge and 8px corners, 14px in; the checked one takes
// the purple edge on the lilac.
function FieldLabel({ className, ...props }: React.ComponentProps<typeof Label>) {
  return (
    <Label
      data-slot="field-label"
      className={cn(
        "group/field-label peer/field-label flex w-fit gap-2 leading-body group-data-[disabled=true]/field:opacity-50",
        "has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col has-[>[data-slot=field]]:rounded-control has-[>[data-slot=field]]:border has-[>[data-slot=field]]:border-line-field has-[>[data-slot=field]]:transition-[background-color,border-color] has-[>[data-slot=field]]:duration-150 has-[>[data-slot=field]]:ease-out *:data-[slot=field]:p-3.5 has-[>[data-slot=field]]:hover:bg-subtle has-data-[state=checked]:border-line-brand has-data-[state=checked]:bg-subtle motion-reduce:transition-none",
        className,
      )}
      {...props}
    />
  );
}

function FieldTitle({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="field-title" className={cn("flex w-fit items-center gap-2 font-sans text-body leading-body font-medium text-fg group-data-[disabled=true]/field:opacity-50", className)} {...props} />;
}

function FieldDescription({ className, ...props }: React.ComponentProps<"p">) {
  return (
    <p
      data-slot="field-description"
      className={cn(
        "m-0 font-sans text-body leading-body font-normal text-fg-muted group-has-[[data-orientation=horizontal]]/field:text-balance [[data-variant=legend]+&]:-mt-1 [&>a]:text-fg-brand [&>a]:underline-offset-4 [&>a:hover]:underline",
        className,
      )}
      {...props}
    />
  );
}

/** The "or" between two ways in: a hairline across the form with a 14px muted word on the page color. */
function FieldSeparator({ children, className, ...props }: React.ComponentProps<"div"> & { children?: React.ReactNode }) {
  return (
    <div data-slot="field-separator" data-content={!!children} className={cn("relative flex h-6 items-center text-body leading-body", className)} {...props}>
      <div aria-hidden className="absolute inset-x-0 top-1/2 h-px bg-line-subtle" />
      {children && (
        <span data-slot="field-separator-content" className="relative mx-auto block w-fit bg-surface px-3 text-fg-muted">
          {children}
        </span>
      )}
    </div>
  );
}

function FieldError({ className, children, errors, ...props }: React.ComponentProps<"div"> & { errors?: Array<{ message?: string } | undefined> }) {
  const content = React.useMemo(() => {
    if (children) return children;
    if (!errors?.length) return null;
    const unique = [...new Map(errors.map((error) => [error?.message, error])).values()];
    if (unique.length === 1) return unique[0]?.message;
    return <ul className="m-0 flex list-disc flex-col gap-0.5 pl-4">{unique.map((error, index) => error?.message && <li key={index}>{error.message}</li>)}</ul>;
  }, [children, errors]);
  if (!content) return null;
  return (
    <div role="alert" data-slot="field-error" className={cn("font-sans text-caption leading-body font-normal text-danger", className)} {...props}>
      {content}
    </div>
  );
}

export { Field, FieldContent, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend, FieldSeparator, FieldSet, FieldTitle };

```

# Form
react-hook-form fields laid out as the console's forms: a 14px label, the control, a muted description and a 12px red message.

Install: npx inkbox-ds add form
Requires: theme, label, utils
Packages: @chakra-ui/react, react-hook-form
Exports: Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, useFormField
Client boundary: yes
Reference: Figma 427:2715: Create Agent Identity (handle check states, Creating Agent Identity...), Login


## Usage
Build a validated form with react-hook-form: wrap it in Form with the useForm result, give each field a FormField with a render function returning FormItem, FormLabel, FormControl around the one control, then FormDescription and FormMessage. FormControl passes the id, the described-by ids and aria-invalid to the control, so the red edge and the message appear together. Finish with one full-width default Button of type submit, showing a Spinner while it works.
- Avoid: A red label on an invalid field
- Avoid: Validating on every keystroke before the first submit
- Avoid: A submit button that stays enabled while the request runs
- Avoid: More than one purple pill in the form


## Examples
Example components: npx inkbox-ds add form badge button input input-group label radio-group spinner switch textarea
Example packages: react-hook-form, @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/form/Preview) | [Login](https://inkbox-ds.vercel.app/preview/form/Login)

examples/form.tsx

```tsx
"use client";

import * as React from "react";
import { useForm } from "react-hook-form";
import { AppleLogoIcon, ArrowsLeftRightIcon, CheckCircleIcon, EnvelopeSimpleIcon, GlobeIcon, InfoIcon, PhoneIcon, PlusIcon, XCircleIcon } from "@phosphor-icons/react/ssr";

import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import { Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage } from "@/components/ui/form";
import { Input } from "@/components/ui/input";
import { InputGroup, InputGroupAddon, InputGroupInput } from "@/components/ui/input-group";
import { Label } from "@/components/ui/label";
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
import { Spinner } from "@/components/ui/spinner";
import { Switch } from "@/components/ui/switch";
import { Textarea } from "@/components/ui/textarea";

type Values = { handle: string; displayName: string; description: string; phone: boolean; imessage: boolean; a2a: boolean; tls: "edge" | "passthrough" };

const TAKEN = ["acme", "support", "acme-support"];

// The local example checks immediately. Real availability checks should use the API without delaying typing.
async function isAvailable(handle: string) {
  return !TAKEN.includes(handle);
}

const CHANNELS = [
  { name: "phone", label: "Phone Number", icon: PhoneIcon },
  { name: "imessage", label: "iMessage", icon: AppleLogoIcon },
] as const;

export function Preview() {
  const form = useForm<Values>({ mode: "onSubmit", reValidateMode: "onChange", defaultValues: { handle: "", displayName: "", description: "", phone: false, imessage: false, a2a: false, tls: "edge" } });
  const [check, setCheck] = React.useState<"idle" | "checking" | "free" | "taken">("idle");
  const [created, setCreated] = React.useState<string | null>(null);
  const handle = form.watch("handle");

  // Start validation immediately; discard stale results if the handle changes.
  React.useEffect(() => {
    if (!/^[a-z0-9-]{3,}$/.test(handle)) return setCheck("idle");
    let live = true;
    setCheck("checking");
    void isAvailable(handle).then((ok) => live && setCheck(ok ? "free" : "taken"));
    return () => {
      live = false;
    };
  }, [handle]);

  async function onSubmit(values: Values) {
    if (!(await isAvailable(values.handle))) {
      form.setError("handle", { message: "(is not available)" });
      return;
    }
    setCreated(values.handle);
  }

  const submitting = form.formState.isSubmitting;
  if (created)
    return (
      <div className="mx-auto grid w-full max-w-121.5 justify-items-center gap-3 py-6 text-center">
        <CheckCircleIcon weight="fill" className="size-10 text-success" />
        <p className="text-h3 leading-heading text-fg">@{created} is ready!</p>
        <Button variant="secondary" onClick={() => { form.reset(); setCreated(null); }}>
          Create another
        </Button>
      </div>
    );

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} noValidate className="mx-auto grid w-full max-w-121.5 gap-6">
        <fieldset disabled={submitting} className="m-0 grid gap-6 border-0 p-0 disabled:opacity-60">
          <div className="flex gap-5">
            <button type="button" aria-label="Add a picture" className="flex size-16 shrink-0 items-center justify-center rounded-pill bg-subtle text-fg outline-none transition-[background-color] duration-150 ease-out hover:bg-subtle-hover active:brightness-95 active:transition-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring motion-reduce:transition-none">
              <PlusIcon className="size-7" />
            </button>
            <div className="grid min-w-0 flex-1 gap-3">
              <FormField
                control={form.control}
                name="handle"
                rules={{
                  required: "Choose a handle for the agent.",
                  pattern: { value: /^[a-z0-9-]{3,}$/, message: "Use at least 3 lowercase letters, numbers or hyphens." },
                  validate: () => check !== "taken" || "(is not available)",
                }}
                render={({ field, fieldState }) => (
                  <FormItem>
                    <FormLabel className="sr-only">Agent handle</FormLabel>
                    <InputGroup>
                      <FormControl>
                        <InputGroupInput placeholder="Agent handle" autoComplete="off" spellCheck={false} {...field} aria-invalid={!!fieldState.error || check === "taken"} />
                      </FormControl>
                      <InputGroupAddon align="inline-end">
                        {check === "checking" && <Spinner aria-label="Checking the handle" className="text-fg-faint" />}
                        {check === "free" && <CheckCircleIcon weight="fill" className="text-success" aria-label="Available" />}
                        {check === "taken" && <XCircleIcon weight="fill" className="text-danger-strong" aria-label="Not available" />}
                      </InputGroupAddon>
                    </InputGroup>
                    {handle && check !== "idle" && check !== "checking" ? (
                      <p className="flex flex-wrap items-center gap-2 text-caption leading-body text-fg-secondary">
                        Will be displayed as <span className="rounded-pill bg-subtle px-2 py-0.5 text-fg">@{handle}</span>
                        {check === "taken" && <span className="text-danger">(is not available)</span>}
                      </p>
                    ) : null}
                    {check !== "taken" && <FormMessage />}
                  </FormItem>
                )}
              />
              <FormField
                control={form.control}
                name="displayName"
                rules={{ maxLength: { value: 40, message: "Keep the display name under 40 characters." } }}
                render={({ field }) => (
                  <FormItem>
                    <FormLabel className="sr-only">Agent display name</FormLabel>
                    <FormControl>
                      <Input placeholder="Agent display name" {...field} />
                    </FormControl>
                    <FormMessage />
                  </FormItem>
                )}
              />
              <FormField
                control={form.control}
                name="description"
                render={({ field }) => (
                  <FormItem>
                    <FormLabel className="sr-only">Agent description</FormLabel>
                    <FormControl>
                      <Textarea placeholder="Agent Description" {...field} />
                    </FormControl>
                  </FormItem>
                )}
              />
            </div>
          </div>

          <div className="grid gap-2.5">
            <p className="text-body leading-body text-fg">Channels</p>
            <div className="grid gap-3 rounded-control bg-subtle p-3.5">
              <div className="flex items-center gap-2.5">
                <span className="flex size-7 items-center justify-center rounded-pill bg-pink text-rose">
                  <EnvelopeSimpleIcon weight="fill" className="size-5.5" />
                </span>
                <span className="flex-1 text-body-lg font-medium text-fg">Email</span>
                <Badge variant="success" size="lg">
                  <CheckCircleIcon weight="fill" />
                  Included
                </Badge>
              </div>
              <InputGroup>
                <InputGroupInput aria-label="Mailbox" value={handle || "acme-support"} readOnly />
                <InputGroupAddon align="inline-end" variant="segment">
                  @inboxmail.com
                </InputGroupAddon>
              </InputGroup>
            </div>
            {CHANNELS.map(({ name, label, icon: Icon }) => (
              <FormField
                key={name}
                control={form.control}
                name={name}
                render={({ field }) => (
                  <FormItem className="flex h-13 items-center gap-2.5 rounded-pill bg-subtle px-3.5">
                    <span className="flex size-7 items-center justify-center rounded-pill bg-pink text-rose">
                      <Icon weight="fill" className="size-5.5" />
                    </span>
                    <FormLabel className="flex-1 text-body-lg font-medium">{label}</FormLabel>
                    <FormControl>
                      <Switch checked={field.value} onCheckedChange={field.onChange} onBlur={field.onBlur} />
                    </FormControl>
                  </FormItem>
                )}
              />
            ))}
            <FormField
              control={form.control}
              name="a2a"
              render={({ field }) => (
                <FormItem className="flex h-13 items-center gap-2.5 rounded-pill bg-subtle px-3.5">
                  <ArrowsLeftRightIcon className="size-6 text-icon-secondary" aria-hidden />
                  <FormLabel className="flex-1 text-body-lg font-medium">
                    Agent2Agent <Badge variant="pink">BETA</Badge>
                  </FormLabel>
                  <FormControl>
                    <Switch checked={field.value} onCheckedChange={field.onChange} onBlur={field.onBlur} />
                  </FormControl>
                </FormItem>
              )}
            />
          </div>

          <div className="grid gap-2">
            <p className="text-body leading-body text-fg">Your agent will be reachable at:</p>
            <p className="flex h-10 items-center gap-2.5 rounded-pill bg-subtle px-2.5 text-body text-fg">
              <span className="flex size-7 items-center justify-center rounded-pill bg-pink text-rose">
                <GlobeIcon weight="fill" className="size-5.5" />
              </span>
              {handle || "acme-support"}.inkboxwire.com
            </p>
          </div>

          <FormField
            control={form.control}
            name="tls"
            render={({ field }) => (
              <FormItem className="gap-2">
                <FormLabel className="gap-1.5">
                  Tunnel TLS mode <InfoIcon weight="fill" aria-hidden className="size-4.5 text-fg-label" />
                </FormLabel>
                <FormControl>
                  <RadioGroup value={field.value} onValueChange={field.onChange}>
                    <div className="flex items-center gap-2">
                      <RadioGroupItem value="edge" id="tls-edge" />
                      <Label htmlFor="tls-edge">Edge (default)</Label>
                    </div>
                    <div className="flex items-center gap-2">
                      <RadioGroupItem value="passthrough" id="tls-passthrough" />
                      <Label htmlFor="tls-passthrough">Passthrough</Label>
                    </div>
                  </RadioGroup>
                </FormControl>
                <FormDescription>Edge ends TLS at Inkbox; passthrough sends it to your agent untouched.</FormDescription>
              </FormItem>
            )}
          />
        </fieldset>

        <Button type="submit" className="w-full" disabled={submitting || check === "checking"}>
          {submitting ? (
            <>
              <Spinner aria-hidden className="size-5" />
              Creating Agent Identity...
            </>
          ) : (
            "Create Agent Identity"
          )}
        </Button>
      </form>
    </Form>
  );
}

export function Login() {
  const form = useForm<{ email: string; password: string }>({ defaultValues: { email: "", password: "" } });
  const [done, setDone] = React.useState(false);
  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(() => setDone(true))} noValidate className="mx-auto grid w-full max-w-86 gap-3">
        <FormField
          control={form.control}
          name="email"
          rules={{ required: "Enter your email address.", pattern: { value: /^\S+@\S+\.\S+$/, message: "Enter a valid email address." } }}
          render={({ field }) => (
            <FormItem>
              <FormLabel>Email address</FormLabel>
              <FormControl>
                <Input type="email" placeholder="your@email.com" autoComplete="email" {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />
        <FormField
          control={form.control}
          name="password"
          rules={{ required: "Enter your password.", minLength: { value: 8, message: "Passwords have at least 8 characters." } }}
          render={({ field }) => (
            <FormItem>
              <div className="flex items-center justify-between gap-3">
                <FormLabel>Password</FormLabel>
                <a href="#forgot" className="text-body leading-body text-fg-brand underline-offset-4 hover:underline">Forgot password?</a>
              </div>
              <FormControl>
                <Input type="password" autoComplete="current-password" {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />
        <Button type="submit" className="mt-1 w-full" disabled={form.formState.isSubmitting}>
          {form.formState.isSubmitting ? <Spinner aria-hidden className="size-5" /> : null}
          {done ? "Logged in" : "Log in"}
        </Button>
      </form>
    </Form>
  );
}

```

## Source

components/ui/form.tsx

```tsx
"use client";

import * as React from "react";
import { chakra } from "@chakra-ui/react";
import { Controller, FormProvider, useFormContext, useFormState, type ControllerProps, type FieldPath, type FieldValues } from "react-hook-form";

import { Label } from "@/components/ui/label";
import { cn } from "@/lib/utils";

// A react-hook-form form laid out as the console's (Figma 427:2715, Create Agent Identity, Login, Vault). Each FormItem
// is a field: its 14px regular ink label on a 24px line, 4px above the control; fields sit 12px apart in the form. A
// FormDescription is 14px muted under the control; a FormMessage is the 12px red line ("(is not available)"). A field
// that fails keeps its label ink: only the control (aria-invalid, the red edge) and the message turn red.
const Form = FormProvider;

type FormFieldContextValue<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = { name: TName };

const FormFieldContext = React.createContext<FormFieldContextValue | null>(null);

function FormField<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>>(props: ControllerProps<TFieldValues, TName>) {
  return (
    <FormFieldContext.Provider value={{ name: props.name }}>
      <Controller {...props} />
    </FormFieldContext.Provider>
  );
}

type FormItemContextValue = { id: string };

const FormItemContext = React.createContext<FormItemContextValue | null>(null);

/** The state of the field around it: its ids for labels and messages, and react-hook-form's error, dirty and touched state. */
function useFormField() {
  const fieldContext = React.useContext(FormFieldContext);
  const itemContext = React.useContext(FormItemContext);
  const { getFieldState } = useFormContext();
  if (!fieldContext) throw new Error("useFormField should be used within <FormField>");
  if (!itemContext) throw new Error("useFormField should be used within <FormItem>");
  const formState = useFormState({ name: fieldContext.name });
  const fieldState = getFieldState(fieldContext.name, formState);
  const { id } = itemContext;
  return { id, name: fieldContext.name, formItemId: `${id}-form-item`, formDescriptionId: `${id}-form-item-description`, formMessageId: `${id}-form-item-message`, ...fieldState };
}

function FormItem({ className, ...props }: React.ComponentProps<"div">) {
  const id = React.useId();
  return (
    <FormItemContext.Provider value={{ id }}>
      <div data-slot="form-item" className={cn("grid min-w-0 gap-1", className)} {...props} />
    </FormItemContext.Provider>
  );
}

function FormLabel({ className, ...props }: React.ComponentProps<typeof Label>) {
  const { error, formItemId } = useFormField();
  return <Label data-slot="form-label" data-error={!!error} htmlFor={formItemId} className={cn("w-fit", className)} {...props} />;
}

/** Hands the field's id, its description and message ids and aria-invalid to the one control inside it. */
function FormControl(props: React.ComponentProps<typeof chakra.div>) {
  const { error, formItemId, formDescriptionId, formMessageId } = useFormField();
  return <chakra.div data-slot="form-control" id={formItemId} aria-describedby={!error ? formDescriptionId : `${formDescriptionId} ${formMessageId}`} aria-invalid={!!error} {...props} />;
}

function FormDescription({ className, ...props }: React.ComponentProps<"p">) {
  const { formDescriptionId } = useFormField();
  return <p data-slot="form-description" id={formDescriptionId} className={cn("m-0 font-sans text-body leading-body text-fg-muted", className)} {...props} />;
}

function FormMessage({ className, children, ...props }: React.ComponentProps<"p">) {
  const { error, formMessageId } = useFormField();
  const body = error ? String(error.message ?? "") : children;
  if (!body) return null;
  return (
    <p data-slot="form-message" id={formMessageId} role={error ? "alert" : undefined} className={cn("m-0 font-sans text-caption leading-body text-danger", className)} {...props}>
      {body}
    </p>
  );
}

export { Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, useFormField };

```

# Hover Card
A raised white preview card with 16px corners that opens after a short pause on a link or handle.

Install: npx inkbox-ds add hover-card
Requires: theme, surface, utils
Packages: radix-ui
Exports: HoverCard, HoverCardContent, HoverCardTrigger
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the raised white panels and the avatar tile, with the shared popup radius


## Usage
Use to preview what a link or an agent handle points to (the agent's addresses, its channels) for people with a pointer. Keep the same information reachable by clicking: hover cards do not open on touch.
- Avoid: Actions that exist only inside the card
- Avoid: A card that opens instantly on hover
- Avoid: Long content


## Examples
Example components: npx inkbox-ds add hover-card
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/hover-card/Preview) | [Open](https://inkbox-ds.vercel.app/preview/hover-card/Open)

examples/hover-card.tsx

```tsx
import { EnvelopeSimpleIcon, PhoneIcon } from "@phosphor-icons/react/ssr";

import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/ui/hover-card";

function AgentCard() {
  return (
    <div className="flex gap-3">
      <span className="flex size-10 shrink-0 items-center justify-center rounded-pill bg-avatar text-body-lg font-medium text-white">A</span>
      <div className="grid min-w-0 gap-1">
        <p className="text-body font-medium text-fg">@acme</p>
        <p className="text-body text-fg-muted">Support agent for Acme. Created Jul 27, 2026.</p>
        <p className="mt-1 flex items-center gap-2 text-body text-fg">
          <EnvelopeSimpleIcon weight="fill" className="size-4.5 text-icon-secondary" /> acme@inkboxmail.com
        </p>
        <p className="flex items-center gap-2 text-body text-fg">
          <PhoneIcon weight="fill" className="size-4.5 text-icon-secondary" /> +1 650 474 9720
        </p>
      </div>
    </div>
  );
}

export function Preview() {
  return (
    <p className="text-body text-fg">
      Messages to{" "}
      <HoverCard>
        <HoverCardTrigger href="#agent" className="text-rose underline-offset-4 hover:underline">
          @acme
        </HoverCardTrigger>
        <HoverCardContent>
          <AgentCard />
        </HoverCardContent>
      </HoverCard>{" "}
      are answered within a minute.
    </p>
  );
}

export function Open() {
  return (
    <div className="flex min-h-60 items-start justify-center">
      <HoverCard defaultOpen>
        <HoverCardTrigger href="#agent" className="text-rose underline-offset-4 hover:underline">
          @acme
        </HoverCardTrigger>
        <HoverCardContent>
          <AgentCard />
        </HoverCardContent>
      </HoverCard>
    </div>
  );
}

```

## Source

components/ui/hover-card.tsx

```tsx
"use client";

import * as React from "react";
import { HoverCard as HoverCardPrimitive } from "radix-ui";

import { usePortalContainer } from "@/lib/surface";
import { cn } from "@/lib/utils";

// A preview on hover, extrapolated from the console's raised white panels (Figma 427:2715): white, 16px corners, the
// floating shadow, 16px of padding, 14px ink. It waits before opening (so a passing pointer does not trigger it), then
// uses a short opacity fade without scaling. The dwell prevents accidental previews; it never delays the link action.
function HoverCard({ openDelay = 400, closeDelay = 150, ...props }: React.ComponentProps<typeof HoverCardPrimitive.Root>) {
  return <HoverCardPrimitive.Root data-slot="hover-card" openDelay={openDelay} closeDelay={closeDelay} {...props} />;
}

function HoverCardTrigger(props: React.ComponentProps<typeof HoverCardPrimitive.Trigger>) {
  return <HoverCardPrimitive.Trigger data-slot="hover-card-trigger" {...props} />;
}

function HoverCardContent({ className, align = "center", sideOffset = 6, ...props }: React.ComponentProps<typeof HoverCardPrimitive.Content>) {
  const container = usePortalContainer();
  return (
    <HoverCardPrimitive.Portal container={container} data-slot="hover-card-portal">
      <HoverCardPrimitive.Content
        data-slot="hover-card-content"
        align={align}
        sideOffset={sideOffset}
        className={cn(
          "z-50 w-72 max-w-[calc(100vw-2rem)] origin-(--radix-hover-card-content-transform-origin) rounded-panel bg-surface p-4 text-body leading-body text-fg shadow-floating outline-none data-[state=closed]:animate-fade-out data-[state=open]:animate-fade-in",
          className,
        )}
        {...props}
      />
    </HoverCardPrimitive.Portal>
  );
}

export { HoverCard, HoverCardContent, HoverCardTrigger };

```

# Input Group
The console's field with addons inside it: glyphs, text, a lilac suffix segment, buttons, or the handle check's state glyph.

Install: npx inkbox-ds add input-group
Requires: theme, button, utils
Packages: class-variance-authority
Exports: InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea
Client boundary: yes
Reference: Figma 427:2715: the Email card's handle field with @inboxmail.com and the handle check states (checking, Available, Not Available) in Modal States


## Usage
Use to attach context to a field: a fixed suffix (@inboxmail.com as a segment), a search glyph, a show or copy button, a character count under a textarea, or the live state of a check (spinner, green check-circle, red x-circle). Put InputGroupInput or InputGroupTextarea inside, then InputGroupAddon at inline-start, inline-end, block-start or block-end.
- Avoid: Putting a separate Input inside the group
- Avoid: More than one action at each end
- Avoid: A suffix that people can edit


## Examples
Example components: npx inkbox-ds add input-group kbd label
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/input-group/Preview) | [HandleCheck](https://inkbox-ds.vercel.app/preview/input-group/HandleCheck) | [Addons](https://inkbox-ds.vercel.app/preview/input-group/Addons) | [WithTextarea](https://inkbox-ds.vercel.app/preview/input-group/WithTextarea)

examples/input-group.tsx

```tsx
"use client";

import * as React from "react";
import { CheckCircleIcon, CopyIcon, EyeIcon, EyeSlashIcon, MagnifyingGlassIcon, SpinnerIcon, XCircleIcon } from "@phosphor-icons/react/ssr";

import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea } from "@/components/ui/input-group";
import { Kbd } from "@/components/ui/kbd";
import { Label } from "@/components/ui/label";

export function Preview() {
  const [handle, setHandle] = React.useState("acme-support");
  return (
    <div className="grid w-full max-w-114.5 gap-1">
      <Label htmlFor="mailbox">Mailbox</Label>
      <InputGroup>
        <InputGroupInput id="mailbox" value={handle} onChange={(e) => setHandle(e.target.value)} />
        <InputGroupAddon align="inline-end" variant="segment">
          @inboxmail.com
        </InputGroupAddon>
      </InputGroup>
    </div>
  );
}

export function HandleCheck() {
  return (
    <div className="grid w-full max-w-100.5 gap-3">
      <InputGroup>
        <InputGroupInput aria-label="Checking handle" defaultValue="acme-support" />
        <InputGroupAddon align="inline-end">
          <SpinnerIcon className="animate-spin-steady text-fg-faint" aria-label="Checking" />
        </InputGroupAddon>
      </InputGroup>
      <div className="grid gap-1">
        <InputGroup>
          <InputGroupInput aria-label="Available handle" defaultValue="acme-support" />
          <InputGroupAddon align="inline-end">
            <CheckCircleIcon weight="fill" className="text-success" aria-label="Available" />
          </InputGroupAddon>
        </InputGroup>
        <p className="flex items-center gap-2 text-caption text-fg-secondary">
          Will be displayed as <span className="rounded-pill bg-subtle px-2 py-1 text-fg">@acme-support</span>
        </p>
      </div>
      <div className="grid gap-1">
        <InputGroup>
          <InputGroupInput aria-label="Taken handle" defaultValue="acme-support" aria-invalid aria-describedby="taken" />
          <InputGroupAddon align="inline-end">
            <XCircleIcon weight="fill" className="text-danger-strong" aria-hidden />
          </InputGroupAddon>
        </InputGroup>
        <p id="taken" className="flex items-center gap-2 text-caption text-fg-secondary">
          Will be displayed as <span className="rounded-pill bg-subtle px-2 py-1 text-fg">@acme-support</span>
          <span className="text-danger">(is not available)</span>
        </p>
      </div>
    </div>
  );
}

export function Addons() {
  const [shown, setShown] = React.useState(false);
  return (
    <div className="grid w-full max-w-100.5 gap-3">
      <InputGroup>
        <InputGroupAddon>
          <MagnifyingGlassIcon />
        </InputGroupAddon>
        <InputGroupInput aria-label="Search mailboxes" placeholder="Search mailboxes" />
        <InputGroupAddon align="inline-end">
          <Kbd>⌘K</Kbd>
        </InputGroupAddon>
      </InputGroup>
      <InputGroup>
        <InputGroupInput aria-label="Vault key" type={shown ? "text" : "password"} defaultValue="correct-horse-battery" />
        <InputGroupAddon align="inline-end">
          <InputGroupButton size="icon-xs" aria-label={shown ? "Hide the key" : "Show the key"} onClick={() => setShown((s) => !s)} className="text-fg-brand">
            {shown ? <EyeSlashIcon weight="fill" /> : <EyeIcon weight="fill" />}
          </InputGroupButton>
        </InputGroupAddon>
      </InputGroup>
      <InputGroup>
        <InputGroupAddon>
          <InputGroupText>https://</InputGroupText>
        </InputGroupAddon>
        <InputGroupInput aria-label="Webhook URL" placeholder="api.example.com/inkbox" className="pl-1" />
        <InputGroupAddon align="inline-end">
          <InputGroupButton size="sm" variant="secondary">
            <CopyIcon weight="duotone" /> Copy
          </InputGroupButton>
        </InputGroupAddon>
      </InputGroup>
      <InputGroup>
        <InputGroupInput aria-label="Read-only mailbox" readOnly defaultValue="acme-support" />
        <InputGroupAddon align="inline-end" variant="segment">
          @inboxmail.com
        </InputGroupAddon>
      </InputGroup>
    </div>
  );
}

export function WithTextarea() {
  const [text, setText] = React.useState("");
  return (
    <InputGroup className="max-w-100.5">
      <InputGroupTextarea aria-label="Reply" placeholder="Write a reply to Ray Liao" value={text} onChange={(e) => setText(e.target.value.slice(0, 280))} />
      <InputGroupAddon align="block-end" className="justify-between">
        <InputGroupText className="text-caption">{text.length}/280</InputGroupText>
        <InputGroupButton size="sm" variant="default" className="rounded-pill" disabled={!text}>
          Send
        </InputGroupButton>
      </InputGroupAddon>
    </InputGroup>
  );
}

```

## Source

components/ui/input-group.tsx

```tsx
"use client";

import * as React from "react";
import { cva, type VariantProps } from "class-variance-authority";

import { Button } from "@/components/ui/button";
import { cn } from "@/lib/utils";

// The console's field with things inside it (Figma 427:2715, Create Agent Identity): the field's 40px, fully rounded corners and
// lilac-gray edge around a borderless control, with addons at either end: a muted glyph or text, the trailing state
// glyph of the handle check (a spinner while checking, a green check-circle when free, a red x-circle when taken), or a
// `segment`, the lilac suffix with a divider ("@inboxmail.com" in the Email card). Focus, invalid and read-only states
// belong to the whole group. Addons can also sit above or below a textarea (block-start, block-end).
function InputGroup({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="input-group"
      role="group"
      className={cn(
        "group/input-group relative flex h-10 w-full min-w-0 items-center overflow-hidden rounded-pill border border-line-field bg-surface transition-[border-color,box-shadow] duration-150 ease-out motion-reduce:transition-none",
        "has-[[data-slot=input-group-control]:focus-visible]:border-line-brand has-[[data-slot=input-group-control]:focus-visible]:shadow-focus",
        "has-[[data-slot][aria-invalid=true]]:border-danger has-[[data-slot][aria-invalid=true]]:shadow-none",
        "has-[[data-slot=input-group-control]:read-only]:border-line-field/50 has-[[data-slot=input-group-control]:read-only]:bg-subtle has-[[data-slot=input-group-control]:disabled]:border-line-field/50 has-[[data-slot=input-group-control]:disabled]:bg-subtle has-[[data-slot=input-group-control]:disabled]:opacity-70",
        "has-[>[data-align=block-end]]:h-auto has-[>[data-align=block-end]]:flex-col has-[>[data-align=block-start]]:h-auto has-[>[data-align=block-start]]:flex-col has-[>textarea]:h-auto has-[>textarea]:rounded-control has-[>[data-align=block-start]]:rounded-control has-[>[data-align=block-end]]:rounded-control",
        "has-[>[data-align=inline-start]]:[&>input]:pl-2 has-[>[data-align=inline-end]]:[&>input]:pr-2 has-[>[data-align=block-start]]:[&>textarea]:pt-1 has-[>[data-align=block-end]]:[&>textarea]:pb-1",
        className,
      )}
      {...props}
    />
  );
}

const inputGroupAddonVariants = cva(
  "flex h-auto shrink-0 cursor-text items-center justify-center gap-2 font-sans text-body leading-tight text-fg-muted select-none group-has-[[data-slot=input-group-control]:disabled]/input-group:cursor-not-allowed [&>kbd]:rounded-xs [&>svg:not([class*='size-'])]:size-5",
  {
    variants: {
      align: {
        "inline-start": "order-first pl-3.5 has-[>button]:pl-1",
        "inline-end": "order-last pr-3 has-[>button]:pr-1",
        "block-start": "order-first w-full justify-start px-3.5 pt-2.5",
        "block-end": "order-last w-full justify-start px-3.5 pb-2.5",
      },
      variant: {
        plain: "",
        segment: "self-stretch border-line-field bg-subtle px-3.5 group-has-[[data-slot=input-group-control]:read-only]/input-group:border-line-field/50 group-has-[[data-slot=input-group-control]:disabled]/input-group:border-line-field/50",
      },
    },
    compoundVariants: [
      { variant: "segment", align: "inline-end", className: "border-l pr-3.5" },
      { variant: "segment", align: "inline-start", className: "border-r pl-3.5" },
    ],
    defaultVariants: { align: "inline-start", variant: "plain" },
  },
);

function InputGroupAddon({ className, align = "inline-start", variant = "plain", ...props }: React.ComponentProps<"div"> & VariantProps<typeof inputGroupAddonVariants>) {
  return (
    <div
      role="group"
      data-slot="input-group-addon"
      data-align={align}
      data-variant={variant}
      className={cn(inputGroupAddonVariants({ align, variant }), className)}
      onClick={(e) => {
        // A click on the addon (not on a button in it) focuses the control, as a click inside a field would.
        if ((e.target as HTMLElement).closest("button")) return;
        e.currentTarget.parentElement?.querySelector<HTMLElement>("input, textarea")?.focus();
      }}
      {...props}
    />
  );
}

const inputGroupButtonVariants = cva("shadow-none", {
  variants: {
    size: {
      xs: "h-7 gap-1 rounded-pill px-2 text-body-sm [&>svg:not([class*='size-'])]:size-4",
      sm: "h-8 gap-1.5 rounded-pill px-2.5",
      "icon-xs": "size-7 rounded-pill p-0 [&>svg:not([class*='size-'])]:size-4",
      "icon-sm": "size-8 rounded-pill p-0",
    },
  },
  defaultVariants: { size: "xs" },
});

function InputGroupButton({ className, type = "button", variant = "ghost", size = "xs", ...props }: Omit<React.ComponentProps<typeof Button>, "size"> & VariantProps<typeof inputGroupButtonVariants>) {
  return <Button type={type} data-size={size} variant={variant} className={cn(inputGroupButtonVariants({ size }), className)} {...props} />;
}

function InputGroupText({ className, ...props }: React.ComponentProps<"span">) {
  return <span className={cn("flex items-center gap-2 font-sans text-body leading-tight text-fg-muted [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-5.5", className)} {...props} />;
}

function InputGroupInput({ className, ...props }: React.ComponentProps<"input">) {
  return (
    <input
      data-slot="input-group-control"
      className={cn(
        "h-full min-w-0 flex-1 bg-transparent px-3.5 font-sans text-body leading-tight text-fg outline-none placeholder:text-fg-subtle selection:bg-ring-tint read-only:text-fg-muted disabled:cursor-not-allowed disabled:text-fg-muted",
        className,
      )}
      {...props}
    />
  );
}

function InputGroupTextarea({ className, ...props }: React.ComponentProps<"textarea">) {
  return (
    <textarea
      data-slot="input-group-control"
      className={cn(
        "field-sizing-content flex min-h-16 w-full min-w-0 flex-1 resize-none bg-transparent px-3.5 py-2.5 font-sans text-body leading-5 text-fg outline-none placeholder:text-fg-subtle selection:bg-ring-tint read-only:text-fg-muted disabled:cursor-not-allowed disabled:text-fg-muted",
        className,
      )}
      {...props}
    />
  );
}

export { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea };

```

# Input OTP
Joined 40px slots in the field's edge with a purple active slot and a blinking caret.

Install: npx inkbox-ds add input-otp
Requires: theme, utils
Packages: @phosphor-icons/react
Exports: InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot, REGEXP_ONLY_CHARS, REGEXP_ONLY_DIGITS, REGEXP_ONLY_DIGITS_AND_CHARS
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): Form- Input's 40px, edge and focus


## Usage
Use for one-time codes from email or SMS (a login code, a vault unlock code). Set maxLength to the code's length and pattern to REGEXP_ONLY_DIGITS for numbers; split long codes into groups with InputOTPSeparator. Paste and SMS autofill fill every slot at once; onComplete fires when the code is full.
- Avoid: Separate inputs per digit
- Avoid: Auto-submitting without a visible result
- Avoid: Hiding the characters of a one-time code


## Examples
Example components: npx inkbox-ds add input-otp label
[Preview](https://inkbox-ds.vercel.app/preview/input-otp/Preview) | [States](https://inkbox-ds.vercel.app/preview/input-otp/States)

examples/input-otp.tsx

```tsx
"use client";

import * as React from "react";

import { InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot, REGEXP_ONLY_DIGITS, REGEXP_ONLY_DIGITS_AND_CHARS } from "@/components/ui/input-otp";
import { Label } from "@/components/ui/label";

export function Preview() {
  const [code, setCode] = React.useState("");
  const [done, setDone] = React.useState(false);
  return (
    <div className="grid gap-2">
      <Label htmlFor="login-code">Login code</Label>
      <InputOTP id="login-code" maxLength={6} pattern={REGEXP_ONLY_DIGITS} value={code} onChange={(v) => { setCode(v); setDone(false); }} onComplete={() => setDone(true)}>
        <InputOTPGroup>
          <InputOTPSlot index={0} />
          <InputOTPSlot index={1} />
          <InputOTPSlot index={2} />
        </InputOTPGroup>
        <InputOTPSeparator />
        <InputOTPGroup>
          <InputOTPSlot index={3} />
          <InputOTPSlot index={4} />
          <InputOTPSlot index={5} />
        </InputOTPGroup>
      </InputOTP>
      <p className="text-caption text-fg-muted" aria-live="polite">
        {done ? "Code entered. Checking it now." : "Enter the 6-digit code we sent to robert@acme.com."}
      </p>
    </div>
  );
}

export function States() {
  return (
    <div className="grid gap-4">
      <InputOTP aria-label="Recovery code" maxLength={4} pattern={REGEXP_ONLY_DIGITS_AND_CHARS} defaultValue="A7">
        <InputOTPGroup>
          <InputOTPSlot index={0} />
          <InputOTPSlot index={1} />
          <InputOTPSlot index={2} />
          <InputOTPSlot index={3} />
        </InputOTPGroup>
      </InputOTP>
      <InputOTP aria-label="Wrong code" maxLength={4} defaultValue="1234" aria-invalid>
        <InputOTPGroup>
          <InputOTPSlot index={0} />
          <InputOTPSlot index={1} />
          <InputOTPSlot index={2} />
          <InputOTPSlot index={3} />
        </InputOTPGroup>
      </InputOTP>
      <InputOTP aria-label="Disabled" maxLength={4} defaultValue="12" disabled>
        <InputOTPGroup>
          <InputOTPSlot index={0} />
          <InputOTPSlot index={1} />
          <InputOTPSlot index={2} />
          <InputOTPSlot index={3} />
        </InputOTPGroup>
      </InputOTP>
    </div>
  );
}

```

## Source

components/ui/input-otp.tsx

```tsx
"use client";

import * as React from "react";
import { MinusIcon } from "@phosphor-icons/react/ssr";

import { cn } from "@/lib/utils";

// A one-time code field, written for the console's look (extrapolated from Figma "Form- Input"): joined 40px slots in
// the field's lilac-gray edge with fully rounded outer corners, 16px medium ink characters, and the active slot in the purple edge
// with the soft focus ring and a blinking 1px caret. One real input lies over the slots, so typing, deleting, pasting
// a whole code, autofill from SMS and arrow keys all work as in any field. `pattern` limits each character.
const REGEXP_ONLY_DIGITS = "^\\d+$";
const REGEXP_ONLY_CHARS = "^[a-zA-Z]+$";
const REGEXP_ONLY_DIGITS_AND_CHARS = "^[a-zA-Z0-9]+$";

type Slot = { char: string | null; isActive: boolean; hasFakeCaret: boolean };
const InputOTPContext = React.createContext<{ slots: Slot[]; invalid: boolean; disabled: boolean }>({ slots: [], invalid: false, disabled: false });

type InputOTPProps = Omit<React.ComponentProps<"input">, "value" | "defaultValue" | "onChange" | "maxLength" | "pattern"> & {
  maxLength: number;
  value?: string;
  defaultValue?: string;
  onChange?: (value: string) => void;
  onComplete?: (value: string) => void;
  /** A regular expression (as a string) each character must match, such as REGEXP_ONLY_DIGITS. */
  pattern?: string;
  containerClassName?: string;
};

function InputOTP({ maxLength, value: valueProp, defaultValue = "", onChange, onComplete, pattern, containerClassName, className, children, disabled = false, onFocus, onBlur, onKeyDown, ...props }: InputOTPProps) {
  const [inner, setInner] = React.useState(defaultValue.slice(0, maxLength));
  const value = valueProp ?? inner;
  const input = React.useRef<HTMLInputElement>(null);
  const [focused, setFocused] = React.useState(false);
  const [selection, setSelection] = React.useState<[number, number]>([value.length, value.length]);
  const test = React.useMemo(() => (pattern ? new RegExp(pattern) : null), [pattern]);

  const sync = React.useCallback(() => {
    const el = input.current;
    if (el && document.activeElement === el) setSelection([el.selectionStart ?? el.value.length, el.selectionEnd ?? el.value.length]);
  }, []);
  React.useEffect(() => {
    document.addEventListener("selectionchange", sync);
    return () => document.removeEventListener("selectionchange", sync);
  }, [sync]);

  const commit = (next: string) => {
    if (valueProp === undefined) setInner(next);
    onChange?.(next);
    if (next.length === maxLength && next !== value) onComplete?.(next);
  };

  // A caret at the end, or the last character selected when the code is full, so typing replaces it.
  const placeCaret = (el: HTMLInputElement) => {
    const at = Math.min(el.value.length, maxLength - 1);
    if (el.value.length >= maxLength) el.setSelectionRange(at, maxLength);
    else el.setSelectionRange(el.value.length, el.value.length);
    sync();
  };

  const [start, end] = selection;
  const active = focused ? (start === end ? Math.min(start, maxLength - 1) : start) : -1;
  const slots: Slot[] = Array.from({ length: maxLength }, (_, i) => ({
    char: value[i] ?? null,
    isActive: i === active,
    hasFakeCaret: focused && start === end && i === start && !value[i],
  }));
  const invalid = props["aria-invalid"] === true || props["aria-invalid"] === "true";

  return (
    <InputOTPContext.Provider value={{ slots, invalid, disabled }}>
      <div data-slot="input-otp" className={cn("relative flex items-center gap-2 has-disabled:opacity-50", containerClassName)}>
        {children}
        <input
          ref={input}
          data-slot="input-otp-input"
          inputMode={pattern === REGEXP_ONLY_DIGITS ? "numeric" : "text"}
          autoComplete="one-time-code"
          spellCheck={false}
          maxLength={maxLength}
          value={value}
          disabled={disabled}
          className={cn("absolute inset-0 size-full cursor-text bg-transparent text-transparent caret-transparent opacity-0 outline-none disabled:cursor-not-allowed", className)}
          onChange={(e) => {
            const next = e.target.value.replace(/\s/g, "").slice(0, maxLength);
            if (next && test && !test.test(next)) return;
            commit(next);
          }}
          onPaste={(e) => {
            // A pasted code replaces the whole field, cut to length and checked against the pattern.
            const text = e.clipboardData.getData("text").replace(/\s/g, "").slice(0, maxLength);
            if (!text) return;
            e.preventDefault();
            if (test && !test.test(text)) return;
            commit(text);
            requestAnimationFrame(() => input.current && placeCaret(input.current));
          }}
          onFocus={(e) => {
            setFocused(true);
            placeCaret(e.currentTarget);
            onFocus?.(e);
          }}
          onMouseUp={(e) => placeCaret(e.currentTarget)}
          onBlur={(e) => {
            setFocused(false);
            onBlur?.(e);
          }}
          onKeyDown={(e) => {
            onKeyDown?.(e);
            if (e.defaultPrevented) return;
            const el = e.currentTarget;
            const at = el.selectionStart ?? 0;
            // Arrows move one slot and select it, so the next key replaces that character.
            if (e.key === "ArrowLeft" || e.key === "ArrowRight") {
              e.preventDefault();
              const to = Math.max(0, Math.min(e.key === "ArrowLeft" ? at - 1 : at + 1, el.value.length));
              el.setSelectionRange(to, to < el.value.length ? to + 1 : to);
              sync();
            } else if (e.key === "Home" || e.key === "End") {
              e.preventDefault();
              const to = e.key === "Home" ? 0 : el.value.length;
              el.setSelectionRange(to, to);
              sync();
            }
          }}
          {...props}
        />
      </div>
    </InputOTPContext.Provider>
  );
}

function InputOTPGroup({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="input-otp-group" className={cn("flex items-center rounded-pill", className)} {...props} />;
}

function InputOTPSlot({ index, className, ...props }: React.ComponentProps<"div"> & { index: number }) {
  const { slots, invalid } = React.useContext(InputOTPContext);
  const { char, hasFakeCaret, isActive } = slots[index] ?? { char: null, hasFakeCaret: false, isActive: false };
  return (
    <div
      data-slot="input-otp-slot"
      data-active={isActive || undefined}
      aria-invalid={invalid || undefined}
      className={cn(
        "relative -ml-px flex size-10 items-center justify-center border border-line-field bg-surface font-sans text-body-lg leading-none font-medium text-fg transition-[border-color,box-shadow] duration-150 ease-out first:ml-0 first:rounded-l-pill last:rounded-r-pill aria-invalid:border-danger data-active:z-10 data-active:border-line-brand data-active:shadow-focus aria-invalid:data-active:shadow-none motion-reduce:transition-none",
        className,
      )}
      {...props}
    >
      {char}
      {hasFakeCaret && (
        <div className="pointer-events-none absolute inset-0 flex items-center justify-center">
          <div className="h-5 w-px animate-caret-blink bg-fg" />
        </div>
      )}
    </div>
  );
}

function InputOTPSeparator(props: React.ComponentProps<"div">) {
  return (
    <div data-slot="input-otp-separator" role="separator" className="flex items-center text-fg-faint" {...props}>
      <MinusIcon weight="bold" className="size-4" />
    </div>
  );
}

export { InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot, REGEXP_ONLY_CHARS, REGEXP_ONLY_DIGITS, REGEXP_ONLY_DIGITS_AND_CHARS };

```

# Input
The 40px field with 8px corners, the lilac-gray edge and a light purple placeholder.

Install: npx inkbox-ds add input
Requires: theme, utils
Packages: @chakra-ui/react
Exports: Input, inputClassName
Client boundary: yes
Reference: Figma 427:2715: Form- Input in Create Agent Identity, Login and Vault


## Usage
Use for one line of text: a handle, an email, a key. Pair it with Label (or Field) above it. Set aria-invalid when the value is rejected and say why below it; set readOnly for a value the person cannot change (it sits on the lilac).
- Avoid: A placeholder used as the only label
- Avoid: A pill-shaped field
- Avoid: A gray field background for an editable value


## Examples
Example components: npx inkbox-ds add input label
[Preview](https://inkbox-ds.vercel.app/preview/input/Preview) | [States](https://inkbox-ds.vercel.app/preview/input/States)

examples/input.tsx

```tsx
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";

export function Preview() {
  return (
    <div className="grid w-full max-w-86 gap-1">
      <Label htmlFor="email">Email address</Label>
      <Input id="email" type="email" placeholder="your@email.com" autoComplete="email" />
    </div>
  );
}

export function States() {
  return (
    <div className="grid w-full max-w-100 gap-3">
      <Input aria-label="Agent display name" placeholder="Agent display name" />
      <Input aria-label="Agent handle" defaultValue="acme-support" aria-invalid />
      <Input aria-label="Mailbox" defaultValue="acme-support" readOnly />
      <Input aria-label="Disabled" placeholder="Disabled" disabled />
    </div>
  );
}

```

## Source

components/ui/input.tsx

```tsx
"use client";

import * as React from "react";
import { Input as ChakraInput } from "@chakra-ui/react";

import { cn } from "@/lib/utils";

// The console's field (Figma "Form- Input"): 40px tall, fully rounded corners, the lilac-gray edge on white, 14px ink text and a
// lighter purple placeholder, 14px in from the edge. Focus takes the purple edge and a soft ring; aria-invalid takes
// the red edge (Not Available). A read-only or disabled field sits on the lilac (the email local part in a channel
// card).
const FIELD =
  "h-10 w-full min-w-0 rounded-pill border border-line-field bg-surface px-3.5 font-sans text-body leading-tight text-fg outline-none transition-[border-color,box-shadow] duration-150 ease-out placeholder:text-fg-subtle selection:bg-ring-tint focus-visible:border-line-brand focus-visible:shadow-focus aria-invalid:border-danger aria-invalid:focus-visible:shadow-none read-only:bg-subtle read-only:text-fg-muted disabled:cursor-not-allowed disabled:bg-subtle disabled:text-fg-muted motion-reduce:transition-none file:mr-3 file:border-0 file:bg-transparent file:font-sans file:text-body file:font-medium file:text-fg";

function Input({ className, type = "text", size, ...props }: React.ComponentProps<"input">) {
  return <ChakraInput unstyled type={type} htmlSize={size} data-slot="input" className={cn(FIELD, className)} {...props} />;
}

export { Input, FIELD as inputClassName };

```

# Item
A row of content: an email in the inbox, a webhook event, or a rail row, washing lilac when hovered or selected.

Install: npx inkbox-ds add item
Requires: theme, utils, separator
Packages: @chakra-ui/react, class-variance-authority
Exports: Item, ItemActions, ItemContent, ItemDescription, ItemFooter, ItemGroup, ItemHeader, ItemMedia, ItemSeparator, ItemTitle
Client boundary: yes
Reference: Figma 427:2715: Agent Workspace - Inbox (email list), Webhooks - Event catalog (event list), the rail


## Usage
Use for list rows that open something. An email: ItemHeader (sender, date) over ItemContent (ItemTitle subject, ItemDescription preview). A webhook event: ItemHeader (a sm Badge and an arrow) over the event name and its count. A rail row: size sm with ItemMedia variant="icon" and a filled glyph. Mark the open one with aria-current="true". Separate rows with ItemSeparator.
- Avoid: Bold titles
- Avoid: Gray descriptions in email and event lists (they are purple)
- Avoid: A card border around every row in a list


## Examples
Example components: npx inkbox-ds add item badge button
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/item/Preview) | [Events](https://inkbox-ds.vercel.app/preview/item/Events) | [Rail](https://inkbox-ds.vercel.app/preview/item/Rail) | [Variants](https://inkbox-ds.vercel.app/preview/item/Variants)

examples/item.tsx

```tsx
import { ArrowRightIcon, EnvelopeIcon, GearIcon, KeyIcon, PencilSimpleIcon, PhoneIcon, RobotIcon, UsersThreeIcon } from "@phosphor-icons/react/ssr";

import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import { Item, ItemActions, ItemContent, ItemDescription, ItemGroup, ItemHeader, ItemMedia, ItemSeparator, ItemTitle } from "@/components/ui/item";

const EMAILS = [
  { from: "Ray Liao", when: "Yesterday", subject: "Inkbox A2A: publish your Agent Card and connect by...", preview: "Hello @acme, This is Ray, cofounder of Inkbox. This update is written for you..." },
  { from: "Ray Liao", when: "Jul 31", subject: "Agent-to-Agent on Inkbox: you can now delegate...", preview: "Hello @acme, This is Ray, cofounder of Inkbox. This week we took A2A across..." },
  { from: "Ray Liao", when: "Jul 31", subject: "Agent-to-Agent on Inkbox: you can now delegate...", preview: "Hello @acme, This is Ray, cofounder of Inkbox. Two new capabilities, with exact..." },
];

export function Preview() {
  return (
    <ItemGroup className="w-full max-w-96">
      {EMAILS.map((email, i) => (
        <div key={i}>
          {i > 0 && <ItemSeparator />}
          <Item asChild aria-current={i === 0 ? "true" : undefined}>
            <a href="#email">
              <ItemHeader>
                <span className="text-fg">{email.from}</span>
                <span className="text-fg-muted">{email.when}</span>
              </ItemHeader>
              <ItemContent>
                <ItemTitle className="w-full truncate">{email.subject}</ItemTitle>
                <ItemDescription className="line-clamp-1">{email.preview}</ItemDescription>
              </ItemContent>
            </a>
          </Item>
        </div>
      ))}
    </ItemGroup>
  );
}

export function Events() {
  return (
    <ItemGroup className="w-full max-w-96">
      {["message.sent", "message.delivered", "message.bounced"].map((event, i) => (
        <div key={event}>
          {i > 0 && <ItemSeparator />}
          <Item asChild data-selected={i === 0}>
            <button type="button" className="w-full text-left">
              <ItemHeader className="justify-start">
                <Badge variant="blue" size="sm">Email</Badge>
                <ArrowRightIcon aria-hidden className="size-4.5 text-fg-muted" />
              </ItemHeader>
              <ItemContent>
                <ItemTitle>{event}</ItemTitle>
                <ItemDescription>0 configured destinations</ItemDescription>
              </ItemContent>
            </button>
          </Item>
        </div>
      ))}
    </ItemGroup>
  );
}

export function Rail() {
  const rows = [
    { label: "Agent Workspace", icon: RobotIcon, current: true },
    { label: "Manage Agents", icon: UsersThreeIcon },
    { label: "API Keys", icon: KeyIcon },
    { label: "Email", icon: EnvelopeIcon },
    { label: "Phone", icon: PhoneIcon },
  ];
  return (
    <ItemGroup className="w-full max-w-66 gap-0.5">
      {rows.map(({ label, icon: Icon, current }) => (
        <Item key={label} size="sm" asChild aria-current={current ? "page" : undefined}>
          <a href={`#${label}`}>
            <ItemMedia variant="icon">
              <Icon weight="fill" />
            </ItemMedia>
            <ItemContent>
              <ItemTitle>{label}</ItemTitle>
            </ItemContent>
          </a>
        </Item>
      ))}
    </ItemGroup>
  );
}

export function Variants() {
  return (
    <div className="grid w-full max-w-120 gap-3">
      <Item variant="outline">
        <ItemMedia variant="icon">
          <EnvelopeIcon weight="fill" />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>acme@inkboxmail.com</ItemTitle>
          <ItemDescription>Created Jul 27, 2026</ItemDescription>
        </ItemContent>
        <ItemActions>
          <Button variant="ghost" size="icon" aria-label="Edit mailbox">
            <PencilSimpleIcon weight="fill" />
          </Button>
        </ItemActions>
      </Item>
      <Item variant="muted" size="sm">
        <ItemMedia variant="icon">
          <GearIcon weight="fill" />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Mailbox settings</ItemTitle>
        </ItemContent>
      </Item>
      <Item size="xs">
        <ItemContent>
          <ItemTitle>Shared iMessage Line: Enabled</ItemTitle>
        </ItemContent>
      </Item>
    </div>
  );
}

```

## Source

components/ui/item.tsx

```tsx
"use client";

import * as React from "react";
import { chakra } from "@chakra-ui/react";
import { cva, type VariantProps } from "class-variance-authority";

import { cn } from "@/lib/utils";
import { Separator } from "@/components/ui/separator";

// A row of content (Figma 427:2715): an email in the inbox list (sender and date over the subject and a purple preview),
// a webhook event (a tag and an arrow over the event name and a purple count), a rail row (a 22px filled glyph and a
// 14px label, 38px tall at size sm). `default` is bare and washes lilac under the pointer; a selected item
// (aria-current or data-selected) sits on the lilac with 8px corners. `outline` takes the field edge, `muted` the lilac.
function ItemGroup({ className, ...props }: React.ComponentProps<"div">) {
  return <div role="list" data-slot="item-group" className={cn("group/item-group flex flex-col", className)} {...props} />;
}

function ItemSeparator({ className, ...props }: React.ComponentProps<typeof Separator>) {
  return <Separator data-slot="item-separator" orientation="horizontal" className={cn("my-0.5", className)} {...props} />;
}

const itemVariants = cva(
  "group/item flex flex-wrap items-center rounded-control border border-transparent font-sans text-body leading-body text-fg outline-none transition-colors duration-150 ease-out focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus-ring aria-[current=page]:bg-subtle aria-[current=true]:bg-subtle data-[selected=true]:bg-subtle motion-reduce:transition-none [a]:hover:bg-subtle [button]:hover:bg-subtle",
  {
    variants: {
      variant: {
        default: "bg-transparent",
        outline: "border-line-field bg-surface",
        muted: "bg-subtle [a]:hover:bg-subtle-hover [button]:hover:bg-subtle-hover",
      },
      size: {
        default: "gap-3 p-3",
        sm: "min-h-9.5 gap-2.5 px-3 py-1.5",
        xs: "gap-2 px-2 py-1",
      },
    },
    defaultVariants: { variant: "default", size: "default" },
  },
);

function Item({ className, variant = "default", size = "default", asChild = false, ...props }: React.ComponentProps<"div"> & VariantProps<typeof itemVariants> & { asChild?: boolean }) {
  const Comp = asChild ? chakra.div : "div";
  // Chakra's factory renders its child in its place only when told to.
  const slotProps = asChild ? { asChild: true } : {};
  return <Comp {...slotProps} data-slot="item" data-variant={variant} data-size={size} className={cn(itemVariants({ variant, size, className }))} {...props} />;
}

const itemMediaVariants = cva("flex shrink-0 items-center justify-center gap-2 group-has-data-[slot=item-description]/item:self-start [&_svg]:pointer-events-none", {
  variants: {
    variant: {
      default: "bg-transparent",
      icon: "text-icon-default [&_svg:not([class*='size-'])]:size-6",
      image: "size-10 overflow-hidden rounded-pill [&_img]:size-full [&_img]:object-cover",
    },
  },
  defaultVariants: { variant: "default" },
});

function ItemMedia({ className, variant = "default", ...props }: React.ComponentProps<"div"> & VariantProps<typeof itemMediaVariants>) {
  return <div data-slot="item-media" data-variant={variant} className={cn(itemMediaVariants({ variant, className }))} {...props} />;
}

function ItemContent({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="item-content" className={cn("flex min-w-0 flex-1 flex-col gap-1 [&+[data-slot=item-content]]:flex-none", className)} {...props} />;
}

function ItemTitle({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="item-title" className={cn("flex w-fit min-w-0 items-center gap-2 text-body leading-tight text-fg", className)} {...props} />;
}

/** The purple line under a title (a preview, a count), clamped to two lines. */
function ItemDescription({ className, ...props }: React.ComponentProps<"p">) {
  return <p data-slot="item-description" className={cn("line-clamp-2 text-body leading-tight font-normal text-balance text-fg-brand [&>a]:underline [&>a]:underline-offset-4", className)} {...props} />;
}

function ItemActions({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="item-actions" className={cn("flex items-center gap-1", className)} {...props} />;
}

/** The top line of an item: what it is at the left (sender, tag), when or where at the right (date, arrow). */
function ItemHeader({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="item-header" className={cn("flex basis-full items-center justify-between gap-2 text-body leading-tight", className)} {...props} />;
}

function ItemFooter({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="item-footer" className={cn("flex basis-full items-center justify-between gap-2", className)} {...props} />;
}

export { Item, ItemActions, ItemContent, ItemDescription, ItemFooter, ItemGroup, ItemHeader, ItemMedia, ItemSeparator, ItemTitle };

```

# Kbd
A 20px lilac key cap with 4px corners and 12px medium text.

Install: npx inkbox-ds add kbd
Requires: theme, utils
Packages: none
Exports: Kbd, KbdGroup
Client boundary: not required by this entry file
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the lilac @handle chip and its 4px tag corners


## Usage
Use to show a keyboard shortcut in a menu, a tooltip or help text (Kbd for one key, KbdGroup for a combination). Write the keys as people see them on the keyboard (⌘, Shift, K).
- Avoid: A shortcut written in caps tracking
- Avoid: A dark key cap on white
- Avoid: Long words inside a key


## Examples
Example components: npx inkbox-ds add kbd
[Preview](https://inkbox-ds.vercel.app/preview/kbd/Preview)

examples/kbd.tsx

```tsx
import { Kbd, KbdGroup } from "@/components/ui/kbd";

export function Preview() {
  return (
    <div className="grid gap-3 text-body text-fg-secondary">
      <p className="flex items-center gap-2">
        Compose an email
        <KbdGroup>
          <Kbd>⌘</Kbd>
          <Kbd>N</Kbd>
        </KbdGroup>
      </p>
      <p className="flex items-center gap-2">
        Search mailboxes
        <KbdGroup>
          <Kbd>⌘</Kbd>
          <Kbd>K</Kbd>
        </KbdGroup>
      </p>
      <p className="flex items-center gap-2">
        Close a dialog <Kbd>Esc</Kbd>
      </p>
    </div>
  );
}

```

## Source

components/ui/kbd.tsx

```tsx
import * as React from "react";

import { cn } from "@/lib/utils";

// Extrapolated from the console's small lilac chips (the @handle chip under the handle field): a key is a 20px lilac
// cap with 4px corners and a hairline Shadow/S ring, 12px medium secondary ink in Inter; glyphs inside are 12px. In a
// tooltip (on the ink) it turns translucent white.
function Kbd({ className, ...props }: React.ComponentProps<"kbd">) {
  return (
    <kbd
      data-slot="kbd"
      className={cn(
        "pointer-events-none inline-flex h-5 w-fit min-w-5 items-center justify-center gap-1 rounded-xs bg-subtle px-1.5 font-sans text-caption leading-none font-medium text-fg-secondary shadow-line select-none in-data-[slot=tooltip-content]:bg-white/15 in-data-[slot=tooltip-content]:text-white in-data-[slot=tooltip-content]:shadow-none [&_svg:not([class*='size-'])]:size-3",
        className,
      )}
      {...props}
    />
  );
}

function KbdGroup({ className, ...props }: React.ComponentProps<"kbd">) {
  return <kbd data-slot="kbd-group" className={cn("inline-flex items-center gap-1", className)} {...props} />;
}

export { Kbd, KbdGroup };

```

# Label
A field's 14px regular ink label on a 24px line.

Install: npx inkbox-ds add label
Requires: theme, utils
Packages: @chakra-ui/react
Exports: Label
Client boundary: yes
Reference: Figma 427:2715: Login (Email address, Password), Vault (Vault key)


## Usage
Name every field with a Label tied to it by htmlFor, 4px above the field. For a label with a hint or an action beside it (Forgot password?), use Field.
- Avoid: Bold or caps labels
- Avoid: A label in the action purple


## Examples
Example components: npx inkbox-ds add label input
[Preview](https://inkbox-ds.vercel.app/preview/label/Preview)

examples/label.tsx

```tsx
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";

export function Preview() {
  return (
    <div className="grid w-full max-w-86 gap-1">
      <Label htmlFor="vault-key">Vault key</Label>
      <Input id="vault-key" type="password" placeholder="Enter a vault key" />
    </div>
  );
}

```

## Source

components/ui/label.tsx

```tsx
"use client";

import * as React from "react";
import { chakra } from "@chakra-ui/react";

import { cn } from "@/lib/utils";

// A field's label (Email address, Password, Vault key): 14px regular ink on a 24px line, 4px above its field. A
// disabled field's label fades with it.
function Label({ className, ...props }: React.ComponentProps<"label">) {
  return (
    <chakra.label
      data-slot="label"
      className={cn("flex items-center gap-2 font-sans text-body leading-body font-normal text-fg select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50", className)}
      {...props}
    />
  );
}

export { Label };

```

# Marker
A 12px muted marker in a conversation or list, alone, between two hairlines, ruled underneath, or as the purple unread line.

Install: npx inkbox-ds add marker
Requires: theme, utils
Packages: @chakra-ui/react, class-variance-authority
Exports: Marker, MarkerContent, MarkerIcon, markerVariants
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the inbox dates (muted) and the rail rules


## Usage
Mark where a day begins (separator, "Yesterday"), where unread messages start (unread), or an event in a thread (default with a MarkerIcon, "Ray joined the conversation"). Use border to head a short list.
- Avoid: Markers larger than 12px
- Avoid: A colored pill around a date
- Avoid: More than one unread line


## Examples
Example components: npx inkbox-ds add marker
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/marker/Preview) | [Variants](https://inkbox-ds.vercel.app/preview/marker/Variants)

examples/marker.tsx

```tsx
import { ArrowsLeftRightIcon, UserPlusIcon } from "@phosphor-icons/react/ssr";

import { Marker, MarkerContent, MarkerIcon } from "@/components/ui/marker";

export function Preview() {
  return (
    <div className="mx-auto grid w-full max-w-120 gap-5">
      <Marker variant="separator">
        <MarkerContent>Yesterday</MarkerContent>
      </Marker>
      <Marker>
        <MarkerIcon>
          <UserPlusIcon weight="fill" />
        </MarkerIcon>
        <MarkerContent>Ray Liao joined the conversation</MarkerContent>
      </Marker>
      <Marker variant="unread">
        <MarkerContent>2 unread</MarkerContent>
      </Marker>
    </div>
  );
}

export function Variants() {
  return (
    <div className="mx-auto grid w-full max-w-120 gap-5">
      <Marker variant="border">
        <MarkerContent>Threads</MarkerContent>
      </Marker>
      <Marker>
        <MarkerIcon>
          <ArrowsLeftRightIcon />
        </MarkerIcon>
        <MarkerContent>
          Delegated to @ops-agent over Agent2Agent. <a href="#session">View session</a>
        </MarkerContent>
      </Marker>
      <Marker variant="separator">
        <MarkerContent>Jul 31</MarkerContent>
      </Marker>
    </div>
  );
}

```

## Source

components/ui/marker.tsx

```tsx
"use client";

import * as React from "react";
import { chakra } from "@chakra-ui/react";
import { cva, type VariantProps } from "class-variance-authority";

import { cn } from "@/lib/utils";

// A marker in a conversation or a list: 12px muted text, as the inbox sets its dates (Figma 427:2715). `separator`
// centers it between two hairlines ("Yesterday"), `border` rules it underneath, and `unread` is the purple line where
// unread messages begin.
const markerVariants = cva(
  "group/marker relative flex min-h-4 w-full items-center gap-2 text-left font-sans text-caption leading-tight text-fg-muted [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 [a]:underline [a]:underline-offset-4 [a]:hover:text-fg",
  {
    variants: {
      variant: {
        default: "",
        separator: "before:mr-1 before:h-px before:min-w-0 before:flex-1 before:bg-line-subtle after:ml-1 after:h-px after:min-w-0 after:flex-1 after:bg-line-subtle",
        border: "border-b border-line-subtle pb-2",
        unread: "font-medium text-fg-brand before:mr-1 before:h-px before:min-w-0 before:flex-1 before:bg-line-brand after:ml-1 after:h-px after:min-w-0 after:flex-1 after:bg-line-brand",
      },
    },
    defaultVariants: { variant: "default" },
  },
);

function Marker({ className, variant = "default", asChild = false, ...props }: React.ComponentProps<"div"> & VariantProps<typeof markerVariants> & { asChild?: boolean }) {
  const Comp = asChild ? chakra.div : "div";
  // Chakra's factory renders its child in its place only when told to.
  const slotProps = asChild ? { asChild: true } : {};
  return <Comp {...slotProps} data-slot="marker" data-variant={variant} role={variant === "default" ? undefined : "separator"} className={cn(markerVariants({ variant }), className)} {...props} />;
}

function MarkerIcon({ className, ...props }: React.ComponentProps<"span">) {
  return <span data-slot="marker-icon" aria-hidden="true" className={cn("inline-flex size-4 shrink-0 items-center justify-center [&_svg:not([class*='size-'])]:size-4", className)} {...props} />;
}

function MarkerContent({ className, ...props }: React.ComponentProps<"span">) {
  return <span data-slot="marker-content" className={cn("min-w-0 break-words group-data-[variant=separator]/marker:flex-none group-data-[variant=separator]/marker:text-center group-data-[variant=unread]/marker:flex-none *:[a]:underline *:[a]:underline-offset-4 *:[a]:hover:text-fg", className)} {...props} />;
}

export { Marker, MarkerContent, MarkerIcon, markerVariants };

```

# Menubar
A lilac tab track of medium triggers whose menus are the dropdown menu's raised panels.

Install: npx inkbox-ds add menubar
Requires: theme, surface, utils
Packages: radix-ui, @phosphor-icons/react
Exports: Menubar, MenubarCheckboxItem, MenubarContent, MenubarGroup, MenubarItem, MenubarLabel, MenubarMenu, MenubarPortal, MenubarRadioGroup, MenubarRadioItem, MenubarSeparator, MenubarShortcut, MenubarSub, MenubarSubContent, MenubarSubTrigger, MenubarTrigger
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the tab track (Mailboxes, Contact rules, Custom domains) and the raised panel


## Usage
Use for an app-style menu of commands in a dense tool, such as an editor for an agent's notes. In the console's pages prefer buttons and row menus.
- Avoid: A menubar for site navigation (use Navigation Menu)
- Avoid: More than six triggers
- Avoid: Triggers without menus


## Examples
Example components: npx inkbox-ds add menubar
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/menubar/Preview) | [Open](https://inkbox-ds.vercel.app/preview/menubar/Open)

examples/menubar.tsx

```tsx
"use client";

import * as React from "react";
import { CopyIcon, FileTextIcon, PlusIcon, TrashIcon } from "@phosphor-icons/react/ssr";

import {
  Menubar,
  MenubarCheckboxItem,
  MenubarContent,
  MenubarGroup,
  MenubarItem,
  MenubarLabel,
  MenubarMenu,
  MenubarRadioGroup,
  MenubarRadioItem,
  MenubarSeparator,
  MenubarShortcut,
  MenubarSub,
  MenubarSubContent,
  MenubarSubTrigger,
  MenubarTrigger,
} from "@/components/ui/menubar";

function Bar({ open }: { open?: boolean }) {
  const [wrap, setWrap] = React.useState(true);
  const [format, setFormat] = React.useState("markdown");
  return (
    <Menubar defaultValue={open ? "note" : undefined}>
      <MenubarMenu value="note">
        <MenubarTrigger>Note</MenubarTrigger>
        <MenubarContent className="w-56">
          <MenubarGroup>
            <MenubarItem>
              <PlusIcon />
              New note
              <MenubarShortcut>⌘N</MenubarShortcut>
            </MenubarItem>
            <MenubarItem>
              <CopyIcon weight="duotone" />
              Duplicate
              <MenubarShortcut>⌘D</MenubarShortcut>
            </MenubarItem>
            <MenubarSub>
              <MenubarSubTrigger>
                <FileTextIcon weight="fill" />
                Export as
              </MenubarSubTrigger>
              <MenubarSubContent className="w-40">
                <MenubarItem>Markdown</MenubarItem>
                <MenubarItem>Plain text</MenubarItem>
              </MenubarSubContent>
            </MenubarSub>
          </MenubarGroup>
          <MenubarSeparator />
          <MenubarItem variant="destructive">
            <TrashIcon weight="fill" />
            Delete note
          </MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu value="edit">
        <MenubarTrigger>Edit</MenubarTrigger>
        <MenubarContent className="w-52">
          <MenubarItem>
            Undo <MenubarShortcut>⌘Z</MenubarShortcut>
          </MenubarItem>
          <MenubarItem disabled>
            Redo <MenubarShortcut>⇧⌘Z</MenubarShortcut>
          </MenubarItem>
        </MenubarContent>
      </MenubarMenu>
      <MenubarMenu value="view">
        <MenubarTrigger>View</MenubarTrigger>
        <MenubarContent className="w-52">
          <MenubarCheckboxItem checked={wrap} onCheckedChange={(v) => setWrap(v === true)}>
            Wrap lines
          </MenubarCheckboxItem>
          <MenubarSeparator />
          <MenubarLabel>Show as</MenubarLabel>
          <MenubarRadioGroup value={format} onValueChange={setFormat}>
            <MenubarRadioItem value="markdown">Markdown</MenubarRadioItem>
            <MenubarRadioItem value="formatted">Formatted</MenubarRadioItem>
          </MenubarRadioGroup>
        </MenubarContent>
      </MenubarMenu>
    </Menubar>
  );
}

export function Preview() {
  return <Bar />;
}

export function Open() {
  return (
    <div className="min-h-80">
      <Bar open />
    </div>
  );
}

```

## Source

components/ui/menubar.tsx

```tsx
"use client";

import * as React from "react";
import { Menubar as MenubarPrimitive } from "radix-ui";
import { CaretRightIcon, CheckIcon } from "@phosphor-icons/react/ssr";

import { usePortalContainer } from "@/lib/surface";
import { cn } from "@/lib/utils";

// A menu bar, extrapolated from the console (Figma 427:2715). The bar is the tab track: lilac with 10px corners and a
// 2px inset, its triggers 36px with 8px corners and 14px medium ink, the open one a white key with Shadow/S. Its menus
// are drawn as the dropdown menu (moving between them along the bar is instant: a closing panel that lingered would
// dismiss the next one, and the move is made by keyboard and pointer many times): the panel is a raised white panel (16px corners, the floating
// shadow) with 4px of padding; items are 36px rows with fully rounded corners like the rail's nav rows, a 20px glyph in the
// action-glyph purple 10px from a 14px ink label, and the lilac under the highlighted row. Section labels are 13px in
// the label purple ("Channels"), separators the rail's hairline, shortcuts 12px muted, destructive items red. The
// panel grows out of its trigger from 96 percent with a fade; highlighting a row is instant (menus are used by keyboard
// and many times a day).
const CONTENT =
  "z-50 max-h-(--radix-menubar-content-available-height) min-w-48 overflow-x-hidden overflow-y-auto rounded-panel bg-surface p-1 text-fg shadow-floating outline-none data-[state=open]:animate-fade-in";
const ITEM =
  "relative flex h-9 cursor-default items-center gap-2.5 rounded-pill px-2.5 font-sans text-body leading-tight text-fg outline-none select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[highlighted]:bg-subtle data-[inset]:pl-10.5 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-5.5 [&_svg:not([class*='text-'])]:text-icon-secondary";

function Menubar({ className, ...props }: React.ComponentProps<typeof MenubarPrimitive.Root>) {
  return <MenubarPrimitive.Root data-slot="menubar" className={cn("flex h-10 w-fit items-center gap-1 rounded-pill bg-subtle p-0.5", className)} {...props} />;
}

function MenubarMenu(props: React.ComponentProps<typeof MenubarPrimitive.Menu>) {
  return <MenubarPrimitive.Menu data-slot="menubar-menu" {...props} />;
}

function MenubarPortal(props: React.ComponentProps<typeof MenubarPrimitive.Portal>) {
  const container = usePortalContainer();
  return <MenubarPrimitive.Portal data-slot="menubar-portal" container={container} {...props} />;
}

function MenubarTrigger({ className, ...props }: React.ComponentProps<typeof MenubarPrimitive.Trigger>) {
  return (
    <MenubarPrimitive.Trigger
      data-slot="menubar-trigger"
      className={cn(
        "flex h-9 items-center gap-2 rounded-pill px-2.5 font-sans text-body leading-tight font-medium text-fg outline-none select-none transition-[background-color,box-shadow] duration-150 ease-out hover:bg-subtle-hover focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus-ring data-[state=open]:bg-surface data-[state=open]:shadow-s motion-reduce:transition-none",
        className,
      )}
      {...props}
    />
  );
}

function MenubarContent({ className, align = "start", alignOffset = -2, sideOffset = 8, ...props }: React.ComponentProps<typeof MenubarPrimitive.Content>) {
  return (
    <MenubarPortal>
      <MenubarPrimitive.Content data-slot="menubar-content" align={align} alignOffset={alignOffset} sideOffset={sideOffset} className={cn(CONTENT, "origin-(--radix-menubar-content-transform-origin)", className)} {...props} />
    </MenubarPortal>
  );
}

function MenubarGroup(props: React.ComponentProps<typeof MenubarPrimitive.Group>) {
  return <MenubarPrimitive.Group data-slot="menubar-group" {...props} />;
}

function MenubarItem({ className, inset, variant = "default", ...props }: React.ComponentProps<typeof MenubarPrimitive.Item> & { inset?: boolean; variant?: "default" | "destructive" }) {
  return (
    <MenubarPrimitive.Item
      data-slot="menubar-item"
      data-inset={inset || undefined}
      data-variant={variant}
      className={cn(ITEM, "data-[variant=destructive]:text-danger data-[variant=destructive]:[&_svg]:text-danger", className)}
      {...props}
    />
  );
}

function MenubarCheckboxItem({ className, children, checked, ...props }: React.ComponentProps<typeof MenubarPrimitive.CheckboxItem>) {
  return (
    <MenubarPrimitive.CheckboxItem data-slot="menubar-checkbox-item" checked={checked} className={cn(ITEM, "pl-10.5", className)} {...props}>
      <span className="pointer-events-none absolute left-2.5 flex size-5.5 items-center justify-center">
        <MenubarPrimitive.ItemIndicator>
          <CheckIcon weight="bold" className="size-4.5 text-fg-brand" />
        </MenubarPrimitive.ItemIndicator>
      </span>
      {children}
    </MenubarPrimitive.CheckboxItem>
  );
}

function MenubarRadioGroup(props: React.ComponentProps<typeof MenubarPrimitive.RadioGroup>) {
  return <MenubarPrimitive.RadioGroup data-slot="menubar-radio-group" {...props} />;
}

// The selected choice wears the console's radio mark: a pink ring around white.
function MenubarRadioItem({ className, children, ...props }: React.ComponentProps<typeof MenubarPrimitive.RadioItem>) {
  return (
    <MenubarPrimitive.RadioItem data-slot="menubar-radio-item" className={cn(ITEM, "pl-10.5", className)} {...props}>
      <span className="pointer-events-none absolute left-2.5 flex size-5.5 items-center justify-center">
        <MenubarPrimitive.ItemIndicator>
          <span className="block size-3.5 rounded-pill border-[3.5px] border-pink bg-surface" />
        </MenubarPrimitive.ItemIndicator>
      </span>
      {children}
    </MenubarPrimitive.RadioItem>
  );
}

function MenubarLabel({ className, inset, ...props }: React.ComponentProps<typeof MenubarPrimitive.Label> & { inset?: boolean }) {
  return <MenubarPrimitive.Label data-slot="menubar-label" data-inset={inset || undefined} className={cn("px-2.5 pt-2 pb-1 font-sans text-body-sm leading-tight text-fg-label data-[inset]:pl-10.5", className)} {...props} />;
}

function MenubarSeparator({ className, ...props }: React.ComponentProps<typeof MenubarPrimitive.Separator>) {
  return <MenubarPrimitive.Separator data-slot="menubar-separator" className={cn("-mx-1 my-1 h-px bg-line-subtle", className)} {...props} />;
}

function MenubarShortcut({ className, ...props }: React.ComponentProps<"span">) {
  return <span data-slot="menubar-shortcut" className={cn("ml-auto pl-4 font-sans text-caption text-fg-muted", className)} {...props} />;
}

function MenubarSub(props: React.ComponentProps<typeof MenubarPrimitive.Sub>) {
  return <MenubarPrimitive.Sub data-slot="menubar-sub" {...props} />;
}

function MenubarSubTrigger({ className, inset, children, ...props }: React.ComponentProps<typeof MenubarPrimitive.SubTrigger> & { inset?: boolean }) {
  return (
    <MenubarPrimitive.SubTrigger data-slot="menubar-sub-trigger" data-inset={inset || undefined} className={cn(ITEM, "data-[state=open]:bg-subtle", className)} {...props}>
      {children}
      <CaretRightIcon className="ml-auto size-4.5 text-fg-muted" />
    </MenubarPrimitive.SubTrigger>
  );
}

function MenubarSubContent({ className, ...props }: React.ComponentProps<typeof MenubarPrimitive.SubContent>) {
  return (
    <MenubarPortal>
      <MenubarPrimitive.SubContent data-slot="menubar-sub-content" className={cn(CONTENT, "max-h-(--radix-menubar-content-available-height) origin-(--radix-menubar-content-transform-origin)", className)} {...props} />
    </MenubarPortal>
  );
}

export {
  Menubar,
  MenubarCheckboxItem,
  MenubarContent,
  MenubarGroup,
  MenubarItem,
  MenubarLabel,
  MenubarMenu,
  MenubarPortal,
  MenubarRadioGroup,
  MenubarRadioItem,
  MenubarSeparator,
  MenubarShortcut,
  MenubarSub,
  MenubarSubContent,
  MenubarSubTrigger,
  MenubarTrigger,
};

```

# Message Scroller
A conversation's scroll area that opens at the newest message, stays pinned to it as messages arrive, and offers a white Jump to latest pill once the reader scrolls up.

Install: npx inkbox-ds add message-scroller
Requires: theme, button, utils
Packages: @phosphor-icons/react
Exports: MessageScroller, MessageScrollerButton, MessageScrollerContent, MessageScrollerItem, MessageScrollerProvider, MessageScrollerViewport, useMessageScroller, useMessageScrollerScrollable, useMessageScrollerVisibility
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the inbox list and reading pane, the white key with Shadow/S


## Usage
Wrap a conversation: MessageScroller, then MessageScrollerViewport around MessageScrollerContent, one MessageScrollerItem per message, and a MessageScrollerButton. Give the scroller a fixed height (it fills its parent). Set scrollAnchor on the item the person just sent so the reply grows below it. Use MessageScrollerProvider to reach the scroller from outside (a composer), and the hooks useMessageScroller, useMessageScrollerScrollable and useMessageScrollerVisibility for custom controls.
- Avoid: Sliding the jump pill in and out
- Avoid: Scrolling away from what the reader is reading when a message arrives
- Avoid: A scroller without a fixed height


## Examples
Example components: npx inkbox-ds add message-scroller bubble button input marker message
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/message-scroller/Preview) | [Streaming](https://inkbox-ds.vercel.app/preview/message-scroller/Streaming)

examples/message-scroller.tsx

```tsx
"use client";

import * as React from "react";
import { PaperPlaneRightIcon } from "@phosphor-icons/react/ssr";

import { Bubble, BubbleContent } from "@/components/ui/bubble";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Marker, MarkerContent } from "@/components/ui/marker";
import { Message, MessageContent, MessageHeader } from "@/components/ui/message";
import { MessageScroller, MessageScrollerButton, MessageScrollerContent, MessageScrollerItem, MessageScrollerProvider, MessageScrollerViewport, useMessageScroller } from "@/components/ui/message-scroller";

type Entry = { id: number; from: "contact" | "agent"; text: string };

const START: Entry[] = Array.from({ length: 14 }, (_, i) => ({
  id: i,
  from: i % 3 === 2 ? "agent" : "contact",
  text: i % 3 === 2 ? `Logged ticket #${4100 + i} and replied to the customer.` : `Message ${i + 1}: can you check the delivery log for message.sent?`,
}));

function Composer({ onSend }: { onSend: (text: string) => void }) {
  const { scrollToEnd } = useMessageScroller();
  const [text, setText] = React.useState("");
  return (
    <form
      className="flex items-center gap-2 border-t border-line-subtle p-3"
      onSubmit={(event) => {
        event.preventDefault();
        if (!text.trim()) return;
        onSend(text.trim());
        setText("");
        scrollToEnd({ behavior: "auto" });
      }}
    >
      <Input aria-label="Message" value={text} onChange={(e) => setText(e.target.value)} placeholder="Write to your agent" />
      <Button type="submit" size="icon-lg" aria-label="Send">
        <PaperPlaneRightIcon weight="fill" />
      </Button>
    </form>
  );
}

export function Preview() {
  const [entries, setEntries] = React.useState(START);
  return (
    <div className="mx-auto flex h-110 w-full max-w-140 flex-col overflow-hidden rounded-control border border-line-field bg-surface">
      <MessageScrollerProvider>
        <MessageScroller className="min-h-0 flex-1">
          <MessageScrollerViewport>
            <MessageScrollerContent className="gap-4">
              <Marker variant="separator">
                <MarkerContent>Yesterday</MarkerContent>
              </Marker>
              {entries.map((entry) => (
                <MessageScrollerItem key={entry.id}>
                  <Message align={entry.from === "agent" ? "end" : "start"}>
                    <MessageContent>
                      <MessageHeader>{entry.from === "agent" ? "@acme" : "Ray Liao"}</MessageHeader>
                      <Bubble variant={entry.from === "agent" ? "default" : "secondary"} align={entry.from === "agent" ? "end" : "start"}>
                        <BubbleContent>{entry.text}</BubbleContent>
                      </Bubble>
                    </MessageContent>
                  </Message>
                </MessageScrollerItem>
              ))}
            </MessageScrollerContent>
          </MessageScrollerViewport>
          <MessageScrollerButton />
        </MessageScroller>
        <Composer onSend={(text) => setEntries((all) => [...all, { id: all.length, from: "agent", text }])} />
      </MessageScrollerProvider>
    </div>
  );
}

export function Streaming() {
  const [count, setCount] = React.useState(3);
  React.useEffect(() => {
    if (count >= 12) return;
    // ds-latency: simulates incoming messages in this example; scrolling and input remain immediate.
    const t = setTimeout(() => setCount((c) => c + 1), 900);
    return () => clearTimeout(t);
  }, [count]);
  return (
    <div className="mx-auto h-80 w-full max-w-140 overflow-hidden rounded-control border border-line-field bg-surface">
      <MessageScroller>
        <MessageScrollerViewport>
          <MessageScrollerContent className="gap-2">
            {Array.from({ length: count }, (_, i) => (
              <MessageScrollerItem key={i}>
                <Bubble variant="secondary">
                  <BubbleContent>{`Delivery ${i + 1}: message.delivered to https://example.com/hooks returned 200.`}</BubbleContent>
                </Bubble>
              </MessageScrollerItem>
            ))}
          </MessageScrollerContent>
        </MessageScrollerViewport>
        <MessageScrollerButton direction="start" />
        <MessageScrollerButton />
      </MessageScroller>
    </div>
  );
}

```

## Source

components/ui/message-scroller.tsx

```tsx
"use client";

import * as React from "react";
import { ArrowDownIcon, ArrowUpIcon } from "@phosphor-icons/react/ssr";

import { Button } from "@/components/ui/button";
import { cn } from "@/lib/utils";

// A conversation's scroll area. It opens at the newest message and stays pinned there while new messages arrive, until
// the reader scrolls up; then a white "Jump to latest" pill with Shadow/S appears at the bottom center. The pill only
// fades (200ms, the strong ease-out): it shows while someone is reading, and sliding would pull the eye off the text.
// The jump scrolls smoothly, or instantly with reduced motion.

type ScrollOptions = { behavior?: ScrollBehavior };

type ScrollerState = {
  isAtStart: boolean;
  isAtEnd: boolean;
  scrollable: boolean;
  viewport: HTMLDivElement | null;
  setViewport: (el: HTMLDivElement | null) => void;
  setContent: (el: HTMLDivElement | null) => void;
  update: () => void;
  scrollToEnd: (options?: ScrollOptions) => void;
  scrollToStart: (options?: ScrollOptions) => void;
};

const ScrollerContext = React.createContext<ScrollerState | null>(null);

// How close to the end still counts as reading the newest message.
const END_SLACK = 24;

function smoothUnlessReduced(): ScrollBehavior {
  return typeof window !== "undefined" && window.matchMedia("(prefers-reduced-motion: reduce)").matches ? "auto" : "smooth";
}

/** Holds a scroller's state, so controls outside the scroll area (a composer's send button) can reach it. */
function MessageScrollerProvider({ children }: { children: React.ReactNode }) {
  const [viewport, setViewport] = React.useState<HTMLDivElement | null>(null);
  const [content, setContent] = React.useState<HTMLDivElement | null>(null);
  const [edges, setEdges] = React.useState({ isAtStart: true, isAtEnd: true, scrollable: false });
  // Pinned while the reader is at the newest message; new content then keeps the view at the end.
  const pinned = React.useRef(true);

  const update = React.useCallback(() => {
    if (!viewport) return;
    const { scrollTop, scrollHeight, clientHeight } = viewport;
    const isAtEnd = scrollHeight - scrollTop - clientHeight <= END_SLACK;
    const next = { isAtStart: scrollTop <= 1, isAtEnd, scrollable: scrollHeight > clientHeight + 1 };
    pinned.current = isAtEnd;
    setEdges((prev) => (prev.isAtStart === next.isAtStart && prev.isAtEnd === next.isAtEnd && prev.scrollable === next.scrollable ? prev : next));
  }, [viewport]);

  const scrollToEnd = React.useCallback(
    (options?: ScrollOptions) => {
      if (!viewport) return;
      pinned.current = true;
      viewport.scrollTo({ top: viewport.scrollHeight, behavior: options?.behavior ?? smoothUnlessReduced() });
    },
    [viewport],
  );

  const scrollToStart = React.useCallback(
    (options?: ScrollOptions) => {
      if (!viewport) return;
      pinned.current = false;
      viewport.scrollTo({ top: 0, behavior: options?.behavior ?? smoothUnlessReduced() });
    },
    [viewport],
  );

  // Open at the newest message.
  React.useLayoutEffect(() => {
    if (!viewport) return;
    viewport.scrollTop = viewport.scrollHeight;
    update();
  }, [viewport, update]);

  // Keep the newest message in view as content grows, unless the reader has scrolled away.
  React.useEffect(() => {
    if (!viewport || !content) return;
    const observer = new ResizeObserver(() => {
      if (pinned.current) viewport.scrollTop = viewport.scrollHeight;
      update();
    });
    observer.observe(content);
    observer.observe(viewport);
    return () => observer.disconnect();
  }, [viewport, content, update]);

  const value = React.useMemo<ScrollerState>(() => ({ ...edges, viewport, setViewport, setContent, update, scrollToEnd, scrollToStart }), [edges, viewport, update, scrollToEnd, scrollToStart]);
  return <ScrollerContext.Provider value={value}>{children}</ScrollerContext.Provider>;
}

function useScrollerContext(part: string) {
  const context = React.useContext(ScrollerContext);
  if (!context) throw new Error(`${part} must be used inside MessageScroller.`);
  return context;
}

/** The scroller's position and controls: whether it is at the start or the end, and functions to jump there. */
function useMessageScroller() {
  const { isAtStart, isAtEnd, scrollToEnd, scrollToStart } = useScrollerContext("useMessageScroller");
  return { isAtStart, isAtEnd, scrollToEnd, scrollToStart };
}

/** Whether there is more to scroll to in each direction. */
function useMessageScrollerScrollable() {
  const { isAtStart, isAtEnd, scrollable } = useScrollerContext("useMessageScrollerScrollable");
  return { scrollable, canScrollStart: scrollable && !isAtStart, canScrollEnd: scrollable && !isAtEnd };
}

/** Whether an element (an unread marker, a message) is in view inside the scroller. */
function useMessageScrollerVisibility(ref: React.RefObject<Element | null>, threshold = 0.5) {
  const { viewport } = useScrollerContext("useMessageScrollerVisibility");
  const [visible, setVisible] = React.useState(false);
  React.useEffect(() => {
    const el = ref.current;
    if (!viewport || !el) return;
    const observer = new IntersectionObserver(([entry]) => setVisible(entry.isIntersecting), { root: viewport, threshold });
    observer.observe(el);
    return () => observer.disconnect();
  }, [viewport, ref, threshold]);
  return visible;
}

function ScrollerRoot({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="message-scroller" className={cn("group/message-scroller relative flex size-full min-h-0 flex-col overflow-hidden", className)} {...props} />;
}

function MessageScroller(props: React.ComponentProps<"div">) {
  const parent = React.useContext(ScrollerContext);
  if (parent) return <ScrollerRoot {...props} />;
  return (
    <MessageScrollerProvider>
      <ScrollerRoot {...props} />
    </MessageScrollerProvider>
  );
}

function MessageScrollerViewport({ className, onScroll, ...props }: React.ComponentProps<"div">) {
  const { setViewport, update } = useScrollerContext("MessageScrollerViewport");
  return (
    <div
      ref={setViewport}
      data-slot="message-scroller-viewport"
      tabIndex={0}
      role="log"
      aria-live="polite"
      onScroll={(event) => {
        update();
        onScroll?.(event);
      }}
      className={cn("size-full min-h-0 min-w-0 overflow-y-auto overscroll-contain outline-none [scrollbar-gutter:stable] [scrollbar-width:thin] focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus-ring", className)}
      {...props}
    />
  );
}

function MessageScrollerContent({ className, ...props }: React.ComponentProps<"div">) {
  const { setContent } = useScrollerContext("MessageScrollerContent");
  return <div ref={setContent} data-slot="message-scroller-content" className={cn("flex h-max min-h-full flex-col justify-end gap-6 p-4", className)} {...props} />;
}

/**
 * One entry of the conversation. `scrollAnchor` brings it to the top of the view when it mounts (the message just
 * sent, so its reply grows below it).
 */
function MessageScrollerItem({ className, scrollAnchor = false, ...props }: React.ComponentProps<"div"> & { scrollAnchor?: boolean }) {
  const { viewport } = useScrollerContext("MessageScrollerItem");
  const ref = React.useRef<HTMLDivElement>(null);
  React.useLayoutEffect(() => {
    const el = ref.current;
    if (!scrollAnchor || !viewport || !el) return;
    viewport.scrollTop += el.getBoundingClientRect().top - viewport.getBoundingClientRect().top;
  }, [scrollAnchor, viewport]);
  return <div ref={ref} data-slot="message-scroller-item" data-scroll-anchor={scrollAnchor || undefined} className={cn("min-w-0 shrink-0", className)} {...props} />;
}

function MessageScrollerButton({ direction = "end", className, children, variant = "secondary", size = "sm", onClick, ...props }: React.ComponentProps<typeof Button> & { direction?: "start" | "end" }) {
  const { isAtStart, isAtEnd, scrollable, scrollToEnd, scrollToStart } = useScrollerContext("MessageScrollerButton");
  const active = scrollable && (direction === "end" ? !isAtEnd : !isAtStart);
  return (
    <Button
      data-slot="message-scroller-button"
      data-direction={direction}
      data-active={active}
      aria-hidden={!active || undefined}
      tabIndex={active ? undefined : -1}
      variant={variant}
      size={size}
      onClick={(event) => {
        onClick?.(event);
        if (!event.defaultPrevented) (direction === "end" ? scrollToEnd : scrollToStart)();
      }}
      className={cn(
        "absolute left-1/2 z-10 -translate-x-1/2 gap-1.5 bg-surface px-3.5 text-body shadow-floating transition-[opacity,background-color] duration-200 ease-out hover:bg-subtle data-[active=false]:pointer-events-none data-[active=false]:opacity-0 data-[direction=end]:bottom-4 data-[direction=start]:top-4 [&_svg:not([class*='size-'])]:size-4",
        className,
      )}
      {...props}
    >
      {children ?? (
        <>
          {direction === "end" ? <ArrowDownIcon weight="bold" /> : <ArrowUpIcon weight="bold" />}
          {direction === "end" ? "Jump to latest" : "Jump to first"}
        </>
      )}
    </Button>
  );
}

export {
  MessageScroller,
  MessageScrollerButton,
  MessageScrollerContent,
  MessageScrollerItem,
  MessageScrollerProvider,
  MessageScrollerViewport,
  useMessageScroller,
  useMessageScrollerScrollable,
  useMessageScrollerVisibility,
};

```

# Message
One message in a conversation: a 32px avatar tile, the sender and time in 14px, the bubbles, and a 12px muted footer.

Install: npx inkbox-ds add message
Requires: theme, utils
Packages: none
Exports: Message, MessageAvatar, MessageContent, MessageFooter, MessageGroup, MessageHeader
Client boundary: not required by this entry file
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the inbox rows (sender in ink, date muted) and the rail's initial tile


## Usage
Build a conversation from Message rows inside a MessageGroup: MessageAvatar with an initial or a picture, MessageContent with a MessageHeader (the name, then a time element), the Bubble pieces and an optional MessageFooter (Delivered, Read). Set align end for the person's own messages; the row mirrors to the right.
- Avoid: Round avatars
- Avoid: A bold sender name
- Avoid: Timestamps darker than the muted purple


## Examples
Example components: npx inkbox-ds add message bubble
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/message/Preview) | [AgentOutput](https://inkbox-ds.vercel.app/preview/message/AgentOutput)

examples/message.tsx

```tsx
import { CheckIcon } from "@phosphor-icons/react/ssr";

import { Bubble, BubbleContent, BubbleGroup } from "@/components/ui/bubble";
import { Message, MessageAvatar, MessageContent, MessageFooter, MessageGroup, MessageHeader } from "@/components/ui/message";

export function Preview() {
  return (
    <MessageGroup className="mx-auto w-full max-w-140">
      <Message>
        <MessageAvatar>R</MessageAvatar>
        <MessageContent>
          <MessageHeader>
            Ray Liao <time dateTime="2026-08-08T19:16">7:16 PM</time>
          </MessageHeader>
          <BubbleGroup>
            <Bubble variant="secondary">
              <BubbleContent>Can your agent publish its Agent Card?</BubbleContent>
            </Bubble>
            <Bubble variant="secondary">
              <BubbleContent>Then other organizations can find it and delegate to it.</BubbleContent>
            </Bubble>
          </BubbleGroup>
        </MessageContent>
      </Message>
      <Message align="end">
        <MessageAvatar>A</MessageAvatar>
        <MessageContent>
          <MessageHeader>
            @acme <time dateTime="2026-08-08T19:18">7:18 PM</time>
          </MessageHeader>
          <Bubble align="end">
            <BubbleContent>Done. It is listed in the public directory now.</BubbleContent>
          </Bubble>
          <MessageFooter>
            <CheckIcon weight="bold" /> Delivered
          </MessageFooter>
        </MessageContent>
      </Message>
    </MessageGroup>
  );
}

export function AgentOutput() {
  return (
    <Message className="mx-auto max-w-140">
      <MessageAvatar>
        {/* eslint-disable-next-line @next/next/no-img-element */}
        <img src="/octopus.png" alt="" className="bg-subtle" />
      </MessageAvatar>
      <MessageContent>
        <MessageHeader>
          test-agent <time dateTime="2026-08-08T19:20">7:20 PM</time>
        </MessageHeader>
        <Bubble variant="ghost">
          <BubbleContent>I sent the first email from test-agent-233@inkboxmail.com and saved my identity for future sessions. The tunnel at test-agent-233.inkboxwire.com is idle until a request arrives.</BubbleContent>
        </Bubble>
      </MessageContent>
    </Message>
  );
}

```

## Source

components/ui/message.tsx

```tsx
import * as React from "react";

import { cn } from "@/lib/utils";

// One message in an agent conversation (Figma 427:2715, the inbox and iMessage): a 32px avatar tile (the initial on
// the avatar blue, circular, as the rail's "R"), the sender's name in 14px ink with the time in 14px muted beside
// it, the bubbles, and a 12px muted footer (Delivered). Outgoing messages (align end) mirror to the right.
function MessageGroup({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="message-group" className={cn("flex min-w-0 flex-col gap-4", className)} {...props} />;
}

function Message({ className, align = "start", ...props }: React.ComponentProps<"div"> & { align?: "start" | "end" }) {
  return <div data-slot="message" data-align={align} className={cn("group/message relative flex w-full min-w-0 gap-2.5 font-sans text-body data-[align=end]:flex-row-reverse", className)} {...props} />;
}

function MessageAvatar({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="message-avatar"
      className={cn(
        "flex size-8 shrink-0 items-center justify-center self-end overflow-hidden rounded-pill bg-avatar text-body leading-tight font-medium text-white group-has-data-[slot=message-footer]/message:-translate-y-6 *:[img]:size-full *:[img]:object-cover",
        className,
      )}
      {...props}
    />
  );
}

function MessageContent({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="message-content" className={cn("flex w-full min-w-0 flex-col gap-1.5 break-words group-data-[align=end]/message:items-end", className)} {...props} />;
}

/** The sender and the time: "Ray Liao" in ink, "Yesterday" muted, as an inbox row. */
function MessageHeader({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="message-header"
      className={cn("flex max-w-full min-w-0 items-baseline gap-2 px-1 text-body leading-tight text-fg group-data-[align=end]/message:flex-row-reverse [&_time]:text-fg-muted group-has-data-[variant=ghost]/message:px-0", className)}
      {...props}
    />
  );
}

function MessageFooter({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="message-footer"
      className={cn("flex max-w-full min-w-0 items-center gap-1 px-1 text-caption leading-tight text-fg-muted group-data-[align=end]/message:justify-end group-has-data-[variant=ghost]/message:px-0 [&_svg:not([class*='size-'])]:size-3.5", className)}
      {...props}
    />
  );
}

export { Message, MessageAvatar, MessageContent, MessageFooter, MessageGroup, MessageHeader };

```

# Native Select
The browser's own select dressed as the console's: a white 40px field with the Shadow/S ring and an ink caret.

Install: npx inkbox-ds add native-select
Requires: theme, utils
Packages: @phosphor-icons/react
Exports: NativeSelect, NativeSelectOptGroup, NativeSelectOption
Client boundary: not required by this entry file
Reference: Figma 427:2715: the Any State and Shared selects in Create Agent Identity


## Usage
Use when the platform's own picker is better: on phones, for long lists such as countries or states, or in forms that must work without script. Otherwise use Select. Use NativeSelectOptGroup to group options.
- Avoid: A field edge instead of the Shadow/S ring
- Avoid: A custom arrow image
- Avoid: A native select styled differently from Select on the same form


## Examples
Example components: npx inkbox-ds add native-select label
[Preview](https://inkbox-ds.vercel.app/preview/native-select/Preview) | [States](https://inkbox-ds.vercel.app/preview/native-select/States)

examples/native-select.tsx

```tsx
import { Label } from "@/components/ui/label";
import { NativeSelect, NativeSelectOptGroup, NativeSelectOption } from "@/components/ui/native-select";

export function Preview() {
  return (
    <div className="grid w-full max-w-114.5 gap-1">
      <Label htmlFor="state">Phone number state</Label>
      <NativeSelect id="state" defaultValue="any" className="w-full">
        <NativeSelectOption value="any">Any State</NativeSelectOption>
        <NativeSelectOptGroup label="West">
          <NativeSelectOption value="ca">California</NativeSelectOption>
          <NativeSelectOption value="or">Oregon</NativeSelectOption>
          <NativeSelectOption value="wa">Washington</NativeSelectOption>
        </NativeSelectOptGroup>
        <NativeSelectOptGroup label="East">
          <NativeSelectOption value="ny">New York</NativeSelectOption>
          <NativeSelectOption value="ma">Massachusetts</NativeSelectOption>
        </NativeSelectOptGroup>
      </NativeSelect>
    </div>
  );
}

export function States() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <NativeSelect aria-label="Line" size="sm" defaultValue="shared">
        <NativeSelectOption value="shared">Shared</NativeSelectOption>
        <NativeSelectOption value="dedicated">Dedicated</NativeSelectOption>
      </NativeSelect>
      <NativeSelect aria-label="Disabled" disabled defaultValue="shared">
        <NativeSelectOption value="shared">Shared</NativeSelectOption>
      </NativeSelect>
      <NativeSelect aria-label="Invalid" aria-invalid defaultValue="">
        <NativeSelectOption value="" disabled>
          Choose a mode
        </NativeSelectOption>
        <NativeSelectOption value="edge">Edge</NativeSelectOption>
      </NativeSelect>
    </div>
  );
}

```

## Source

components/ui/native-select.tsx

```tsx
import * as React from "react";
import { CaretDownIcon } from "@phosphor-icons/react/ssr";

import { cn } from "@/lib/utils";

// The browser's own select dressed as the console's select ("Any State", "Shared" in Create Agent Identity): a white
// 40px field with 8px corners and the Shadow/S ring, 14px ink at 14px from the left and a 20px ink caret 12px from the
// right. `size="sm"` is 36px. Use it where the platform picker is better (phones, long lists, forms without script).
type NativeSelectProps = Omit<React.ComponentProps<"select">, "size"> & { size?: "sm" | "default" };

function NativeSelect({ className, size = "default", ...props }: NativeSelectProps) {
  return (
    <div data-slot="native-select-wrapper" data-size={size} className={cn("group/native-select relative w-fit has-[select:disabled]:opacity-50", className)}>
      <select
        data-slot="native-select"
        data-size={size}
        className="h-10 w-full min-w-0 cursor-pointer appearance-none rounded-pill bg-surface py-0 pr-10 pl-3.5 font-sans text-body leading-tight text-fg shadow-s outline-none transition-[box-shadow] duration-150 ease-out focus-visible:shadow-[var(--ds-shadow-s),var(--ds-shadow-focus)] disabled:cursor-not-allowed aria-invalid:shadow-[0_0_0_1px_var(--ds-color-status-danger)] data-[size=sm]:h-9 motion-reduce:transition-none"
        {...props}
      />
      <CaretDownIcon aria-hidden data-slot="native-select-icon" weight="bold" className="pointer-events-none absolute top-1/2 right-3 size-4 -translate-y-1/2 text-fg" />
    </div>
  );
}

function NativeSelectOption({ className, ...props }: React.ComponentProps<"option">) {
  return <option data-slot="native-select-option" className={cn("bg-surface text-fg", className)} {...props} />;
}

function NativeSelectOptGroup({ className, ...props }: React.ComponentProps<"optgroup">) {
  return <optgroup data-slot="native-select-optgroup" className={cn("bg-surface text-fg", className)} {...props} />;
}

export { NativeSelect, NativeSelectOptGroup, NativeSelectOption };

```

# Navigation Menu
Nav-row triggers and links with panels that open in a raised white viewport.

Install: npx inkbox-ds add navigation-menu
Requires: theme, utils
Packages: radix-ui, @phosphor-icons/react, class-variance-authority
Exports: NavigationMenu, NavigationMenuContent, NavigationMenuIndicator, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, NavigationMenuViewport, navigationMenuTriggerStyle
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the rail's nav rows and the raised panel


## Usage
Use for a site's top navigation with grouped destinations (Product, Docs). Put NavigationMenuLink rows with a title and a muted line inside each NavigationMenuContent. Pass viewport={false} to open each panel under its own trigger. navigationMenuTriggerStyle styles a plain link as a trigger; call it from a client component.
- Avoid: Actions in a navigation menu
- Avoid: A navigation menu inside the console's rail (use Sidebar)
- Avoid: Panels taller than the screen


## Examples
Example components: npx inkbox-ds add navigation-menu
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/navigation-menu/Preview) | [Open](https://inkbox-ds.vercel.app/preview/navigation-menu/Open)

examples/navigation-menu.tsx

```tsx
"use client";


import { ChatCircleTextIcon, EnvelopeSimpleIcon, LockKeyIcon, PhoneIcon, ArrowsLeftRightIcon, WebhooksLogoIcon } from "@phosphor-icons/react/ssr";

import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  navigationMenuTriggerStyle,
} from "@/components/ui/navigation-menu";

const CHANNELS = [
  { title: "Email", body: "A mailbox for every agent, on inkboxmail.com or your domain.", icon: EnvelopeSimpleIcon },
  { title: "Phone", body: "Calls and texts on a number the agent owns.", icon: PhoneIcon },
  { title: "iMessage", body: "Shared or dedicated lines that also handle calls.", icon: ChatCircleTextIcon },
  { title: "Agent2Agent", body: "Publish an Agent Card and take tasks from other agents.", icon: ArrowsLeftRightIcon },
];

function Menu({ defaultValue }: { defaultValue?: string }) {
  return (
    <NavigationMenu defaultValue={defaultValue}>
      <NavigationMenuList>
        <NavigationMenuItem value="channels">
          <NavigationMenuTrigger>Channels</NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul className="grid w-[min(34rem,calc(100vw-2rem))] gap-1 sm:grid-cols-2">
              {CHANNELS.map(({ title, body, icon: Icon }) => (
                <li key={title}>
                  <NavigationMenuLink href={`#${title.toLowerCase()}`}>
                    <span className="flex items-center gap-2.5 font-medium">
                      <Icon weight="fill" />
                      {title}
                    </span>
                    <span className="text-fg-muted">{body}</span>
                  </NavigationMenuLink>
                </li>
              ))}
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem value="shared">
          <NavigationMenuTrigger>Shared</NavigationMenuTrigger>
          <NavigationMenuContent>
            <ul className="grid w-[min(16rem,calc(100vw-2rem))] gap-1">
              <li>
                <NavigationMenuLink href="#vault">
                  <span className="flex items-center gap-2.5 font-medium">
                    <LockKeyIcon weight="fill" />
                    Vault
                  </span>
                  <span className="text-fg-muted">Zero-knowledge secrets for your agents.</span>
                </NavigationMenuLink>
              </li>
              <li>
                <NavigationMenuLink href="#webhooks">
                  <span className="flex items-center gap-2.5 font-medium">
                    <WebhooksLogoIcon weight="fill" />
                    Webhooks
                  </span>
                  <span className="text-fg-muted">Event payloads, signed and delivered.</span>
                </NavigationMenuLink>
              </li>
            </ul>
          </NavigationMenuContent>
        </NavigationMenuItem>
        <NavigationMenuItem>
          <NavigationMenuLink href="#docs" className={navigationMenuTriggerStyle()}>
            Docs
          </NavigationMenuLink>
        </NavigationMenuItem>
      </NavigationMenuList>
    </NavigationMenu>
  );
}

export function Preview() {
  return (
    <div className="flex justify-center">
      <Menu />
    </div>
  );
}

export function Open() {
  return (
    <div className="flex min-h-80 items-start justify-center">
      <Menu defaultValue="channels" />
    </div>
  );
}

```

## Source

components/ui/navigation-menu.tsx

```tsx
"use client";

import * as React from "react";
import { NavigationMenu as NavigationMenuPrimitive } from "radix-ui";
import { CaretDownIcon } from "@phosphor-icons/react/ssr";
import { cva } from "class-variance-authority";

import { cn } from "@/lib/utils";

// Site navigation with panels, extrapolated from the console's nav rows (Figma 427:2715: Agent Workspace, Manage
// Agents): triggers and links are 38px rows with fully rounded corners, 12px of side padding and a 14px regular ink label, the
// lilac under the pointer and under an open trigger; the trigger's 16px caret turns over when open (on-screen motion,
// 200ms in-out). The panel opens below in a raised white viewport (16px corners, the floating shadow) that grows from
// a short fade, with no animated resizing (centered under the menu on phones, at its start from 768px); links inside are nav rows with a 14px title and a 14px muted line.
function NavigationMenu({ className, children, viewport = true, ...props }: React.ComponentProps<typeof NavigationMenuPrimitive.Root> & { viewport?: boolean }) {
  return (
    <NavigationMenuPrimitive.Root data-slot="navigation-menu" data-viewport={viewport} className={cn("group/navigation-menu relative flex max-w-max flex-1 items-center justify-center", className)} {...props}>
      {children}
      {viewport && <NavigationMenuViewport />}
    </NavigationMenuPrimitive.Root>
  );
}

function NavigationMenuList({ className, ...props }: React.ComponentProps<typeof NavigationMenuPrimitive.List>) {
  return <NavigationMenuPrimitive.List data-slot="navigation-menu-list" className={cn("group flex flex-1 list-none items-center justify-center gap-1", className)} {...props} />;
}

function NavigationMenuItem({ className, ...props }: React.ComponentProps<typeof NavigationMenuPrimitive.Item>) {
  return <NavigationMenuPrimitive.Item data-slot="navigation-menu-item" className={cn("relative", className)} {...props} />;
}

const navigationMenuTriggerStyle = cva(
  "group inline-flex h-9.5 w-max items-center justify-center gap-1.5 rounded-pill px-3 font-sans text-body leading-tight text-fg outline-none active:brightness-95 active:transition-none transition-colors duration-150 ease-out hover:bg-subtle active:bg-subtle focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus-ring disabled:pointer-events-none disabled:opacity-50 data-[active]:bg-subtle data-[state=open]:bg-subtle motion-reduce:transition-none [&_svg:not([class*='size-'])]:size-5.5",
);

function NavigationMenuTrigger({ className, children, ...props }: React.ComponentProps<typeof NavigationMenuPrimitive.Trigger>) {
  return (
    <NavigationMenuPrimitive.Trigger data-slot="navigation-menu-trigger" className={cn(navigationMenuTriggerStyle(), className)} {...props}>
      {children}
      <CaretDownIcon aria-hidden className="size-4.5 text-fg-muted transition-transform duration-200 ease-in-out group-data-[state=open]:rotate-180 motion-reduce:transition-none" />
    </NavigationMenuPrimitive.Trigger>
  );
}

function NavigationMenuContent({ className, ...props }: React.ComponentProps<typeof NavigationMenuPrimitive.Content>) {
  return (
    <NavigationMenuPrimitive.Content
      data-slot="navigation-menu-content"
      className={cn(
        "top-0 left-0 w-full p-1.5 md:absolute md:w-auto",
        "group-data-[viewport=false]/navigation-menu:top-full group-data-[viewport=false]/navigation-menu:mt-1.5 group-data-[viewport=false]/navigation-menu:overflow-hidden group-data-[viewport=false]/navigation-menu:rounded-panel group-data-[viewport=false]/navigation-menu:bg-surface group-data-[viewport=false]/navigation-menu:shadow-floating group-data-[viewport=false]/navigation-menu:data-[state=closed]:animate-fade-out group-data-[viewport=false]/navigation-menu:data-[state=open]:animate-fade-in",
        "data-[motion^=from-]:animate-fade-in data-[motion^=to-]:animate-fade-out",
        className,
      )}
      {...props}
    />
  );
}

function NavigationMenuViewport({ className, ...props }: React.ComponentProps<typeof NavigationMenuPrimitive.Viewport>) {
  return (
    <div className="absolute top-full left-1/2 isolate z-50 flex -translate-x-1/2 justify-center md:left-0 md:translate-x-0">
      <NavigationMenuPrimitive.Viewport
        data-slot="navigation-menu-viewport"
        className={cn(
          "relative mt-1.5 h-(--radix-navigation-menu-viewport-height) w-(--radix-navigation-menu-viewport-width) max-w-[calc(100vw-2rem)] origin-top md:origin-top-left overflow-hidden rounded-panel bg-surface text-fg shadow-floating data-[state=closed]:animate-fade-out data-[state=open]:animate-fade-in motion-reduce:transition-none",
          className,
        )}
        {...props}
      />
    </div>
  );
}

function NavigationMenuLink({ className, ...props }: React.ComponentProps<typeof NavigationMenuPrimitive.Link>) {
  return (
    <NavigationMenuPrimitive.Link
      data-slot="navigation-menu-link"
      className={cn(
        "flex flex-col gap-0.5 rounded-control p-3 text-body leading-tight text-fg outline-none transition-colors duration-150 ease-out hover:bg-subtle focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus-ring data-[active=true]:bg-subtle motion-reduce:transition-none [&_svg:not([class*='size-'])]:size-5.5 [&_svg:not([class*='text-'])]:text-icon-default",
        className,
      )}
      {...props}
    />
  );
}

function NavigationMenuIndicator({ className, ...props }: React.ComponentProps<typeof NavigationMenuPrimitive.Indicator>) {
  return (
    <NavigationMenuPrimitive.Indicator
      data-slot="navigation-menu-indicator"
      className={cn("top-full z-10 flex h-1.5 items-end justify-center overflow-hidden data-[state=hidden]:animate-fade-out data-[state=visible]:animate-fade-in", className)}
      {...props}
    >
      <div className="relative top-[60%] size-2.5 rotate-45 rounded-tl-xs bg-surface shadow-floating" />
    </NavigationMenuPrimitive.Indicator>
  );
}

export {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuIndicator,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
  NavigationMenuViewport,
  navigationMenuTriggerStyle,
};

```

# Pagination
Muted Previous and Next with carets around ink page numbers; the current page is a white key with Shadow/S.

Install: npx inkbox-ds add pagination
Requires: theme, utils
Packages: @phosphor-icons/react
Exports: Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious
Client boundary: not required by this entry file
Reference: Figma 427:2715: the pagination bar under the Email and iMessage tables


## Usage
Use under a table or list that has more than one page. Pass bar to set it in the lilac bar that sits 8px under a table, as the console does. Mark the current page with isActive and disable Previous on the first page with aria-disabled.
- Avoid: A purple current page
- Avoid: Page numbers in the action purple
- Avoid: More than seven page links at once


## Examples
Example components: npx inkbox-ds add pagination
[Preview](https://inkbox-ds.vercel.app/preview/pagination/Preview) | [Plain](https://inkbox-ds.vercel.app/preview/pagination/Plain)

examples/pagination.tsx

```tsx
import { Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious } from "@/components/ui/pagination";

export function Preview() {
  return (
    <Pagination bar>
      <PaginationContent>
        <PaginationItem>
          <PaginationPrevious href="#" aria-disabled />
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#" isActive>
            1
          </PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#">2</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationNext href="#" />
        </PaginationItem>
      </PaginationContent>
    </Pagination>
  );
}

export function Plain() {
  return (
    <Pagination>
      <PaginationContent>
        <PaginationItem>
          <PaginationPrevious href="#" />
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#">1</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationEllipsis />
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#">7</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#" isActive>
            8
          </PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#">9</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationEllipsis />
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#">24</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationNext href="#" />
        </PaginationItem>
      </PaginationContent>
    </Pagination>
  );
}

```

## Source

components/ui/pagination.tsx

```tsx
import * as React from "react";
import { CaretLeftIcon, CaretRightIcon, DotsThreeIcon } from "@phosphor-icons/react/ssr";

import { cn } from "@/lib/utils";

// The console's pagination (Figma 427:2715, under the Email and iMessage tables): 14px muted "Previous" and "Next" with
// 16px carets, the page numbers in 14px ink, and the current page a 40 by 30 white key with fully rounded corners and Shadow/S.
// `bar` sets it in the 42px lilac bar with 10px corners that sits 8px under a table, the pages at its right end.
function Pagination({ className, bar = false, ...props }: React.ComponentProps<"nav"> & { bar?: boolean }) {
  return (
    <nav
      role="navigation"
      aria-label="pagination"
      data-slot="pagination"
      data-bar={bar || undefined}
      className={cn("flex w-full justify-center", bar && "min-h-10.5 items-center justify-end rounded-panel bg-subtle px-2 py-1.5", className)}
      {...props}
    />
  );
}

function PaginationContent({ className, ...props }: React.ComponentProps<"ul">) {
  return <ul data-slot="pagination-content" className={cn("flex flex-row flex-wrap items-center gap-1", className)} {...props} />;
}

function PaginationItem(props: React.ComponentProps<"li">) {
  return <li data-slot="pagination-item" {...props} />;
}

type PaginationLinkProps = { isActive?: boolean; size?: "icon" | "default" } & React.ComponentProps<"a">;

const LINK =
  "inline-flex h-7.5 shrink-0 items-center justify-center gap-1 rounded-pill font-sans text-body leading-tight whitespace-nowrap outline-none transition-[background-color,color,box-shadow] duration-150 ease-out active:brightness-95 active:transition-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring aria-disabled:pointer-events-none aria-disabled:opacity-50 motion-reduce:transition-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4";

function PaginationLink({ className, isActive, size = "icon", ...props }: PaginationLinkProps) {
  return (
    <a
      aria-current={isActive ? "page" : undefined}
      data-slot="pagination-link"
      data-active={isActive || undefined}
      className={cn(
        LINK,
        size === "icon" ? "min-w-10 px-2" : "px-2.5",
        isActive ? "bg-surface text-fg shadow-s" : "text-fg hover:bg-subtle-hover in-data-[bar=true]:hover:bg-surface/70",
        className,
      )}
      {...props}
    />
  );
}

function PaginationPrevious({ className, children = "Previous", ...props }: React.ComponentProps<typeof PaginationLink>) {
  return (
    <PaginationLink aria-label="Go to previous page" size="default" className={cn("text-fg-muted hover:text-fg", className)} {...props}>
      <CaretLeftIcon aria-hidden />
      <span>{children}</span>
    </PaginationLink>
  );
}

function PaginationNext({ className, children = "Next", ...props }: React.ComponentProps<typeof PaginationLink>) {
  return (
    <PaginationLink aria-label="Go to next page" size="default" className={cn("text-fg-muted hover:text-fg", className)} {...props}>
      <span>{children}</span>
      <CaretRightIcon aria-hidden />
    </PaginationLink>
  );
}

function PaginationEllipsis({ className, ...props }: React.ComponentProps<"span">) {
  return (
    <span aria-hidden data-slot="pagination-ellipsis" className={cn("flex h-7.5 min-w-8 items-center justify-center text-fg-muted", className)} {...props}>
      <DotsThreeIcon weight="bold" className="size-4" />
      <span className="sr-only">More pages</span>
    </span>
  );
}

export { Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious };

```

# Popover
A raised white panel with 16px corners and the floating shadow that grows out of the control that opened it.

Install: npx inkbox-ds add popover
Requires: theme, surface, utils
Packages: @chakra-ui/react
Exports: Popover, PopoverAnchor, PopoverContent, PopoverDescription, PopoverHeader, PopoverTitle, PopoverTrigger
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the raised white panel of the select and the selected tab (Shadow/S), the field and button sizes


## Usage
Use for a small form or detail tied to one control (rename a mailbox, set a phone line's state). Put a PopoverHeader with a PopoverTitle and PopoverDescription first, then the fields. For choosing one value from a list use Select or Combobox; for actions use Dropdown Menu.
- Avoid: A popover that opens on hover (use Hover Card)
- Avoid: A dark or lilac popover panel
- Avoid: Scaling from the center instead of the trigger
- Avoid: Long forms that scroll inside a popover


## Examples
Example components: npx inkbox-ds add popover button input label
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/popover/Preview) | [Open](https://inkbox-ds.vercel.app/preview/popover/Open)

examples/popover.tsx

```tsx
"use client";

import * as React from "react";
import { PencilSimpleIcon } from "@phosphor-icons/react/ssr";

import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
import { Popover, PopoverContent, PopoverDescription, PopoverHeader, PopoverTitle, PopoverTrigger } from "@/components/ui/popover";

function RenameForm({ onDone }: { onDone?: () => void }) {
  const [name, setName] = React.useState("Acme support");
  return (
    <form
      className="grid gap-3"
      onSubmit={(event) => {
        event.preventDefault();
        onDone?.();
      }}
    >
      <PopoverHeader>
        <PopoverTitle>Display name</PopoverTitle>
        <PopoverDescription>Shown as the sender on acme@inkboxmail.com.</PopoverDescription>
      </PopoverHeader>
      <div className="grid gap-1">
        <Label htmlFor="display-name">Name</Label>
        <Input id="display-name" value={name} onChange={(e) => setName(e.target.value)} />
      </div>
      <Button type="submit" className="w-full">
        Save
      </Button>
    </form>
  );
}

export function Preview() {
  const [open, setOpen] = React.useState(false);
  return (
    <div className="flex justify-center">
      <Popover open={open} onOpenChange={setOpen}>
        <PopoverTrigger asChild>
          <Button variant="outline">
            <PencilSimpleIcon weight="fill" />
            Rename mailbox
          </Button>
        </PopoverTrigger>
        <PopoverContent align="start">
          <RenameForm onDone={() => setOpen(false)} />
        </PopoverContent>
      </Popover>
    </div>
  );
}

export function Open() {
  return (
    <div className="flex min-h-80 items-start justify-center">
      <Popover defaultOpen>
        <PopoverTrigger asChild>
          <Button variant="outline">
            <PencilSimpleIcon weight="fill" />
            Rename mailbox
          </Button>
        </PopoverTrigger>
        <PopoverContent>
          <RenameForm />
        </PopoverContent>
      </Popover>
    </div>
  );
}

```

## Source

components/ui/popover.tsx

```tsx
"use client";

import * as React from "react";
import { Popover as ChakraPopover, Portal } from "@chakra-ui/react";

import { usePortalContainer } from "@/lib/surface";
import { cn } from "@/lib/utils";

// A popover, extrapolated from the console's raised white panels (Figma 427:2715: the select and the selected tab
// carry Shadow/S): white with 16px corners and the floating shadow (Shadow/S's ring with a softer, longer drop), 16px of
// padding, 14px ink text. It grows out of its trigger from 96 percent with a fade (200ms, the strong ease-out) and
// leaves faster than it came.
type PopoverProps = Omit<React.ComponentProps<typeof ChakraPopover.Root>, "onOpenChange"> & { onOpenChange?: (open: boolean) => void };
function Popover({ onOpenChange, ...props }: PopoverProps) {
  return <ChakraPopover.Root unstyled data-slot="popover" onOpenChange={(details) => onOpenChange?.(details.open)} {...props} />;
}

function PopoverTrigger(props: React.ComponentProps<typeof ChakraPopover.Trigger>) {
  return <ChakraPopover.Trigger data-slot="popover-trigger" {...props} />;
}

function PopoverAnchor(props: React.ComponentProps<typeof ChakraPopover.Anchor>) {
  return <ChakraPopover.Anchor data-slot="popover-anchor" {...props} />;
}

type PopoverContentProps = Omit<React.ComponentProps<typeof ChakraPopover.Content>, "positioning"> & { align?: "start" | "center" | "end"; sideOffset?: number; onOpenAutoFocus?: (event: { preventDefault(): void }) => void };
function PopoverContent({ className, align = "center", sideOffset = 6, onOpenAutoFocus: _onOpenAutoFocus, ...props }: PopoverContentProps) {
  const container = usePortalContainer();
  const portalRef = React.useMemo(() => container ? { current: container } : undefined, [container]);
  return (
    <Portal container={portalRef}>
      <ChakraPopover.Positioner>
      <ChakraPopover.Content
        unstyled
        data-slot="popover-content"
        className={cn(
          "z-50 flex w-72 max-w-[calc(100vw-2rem)] origin-(--transform-origin) flex-col gap-3 rounded-panel bg-surface p-4 text-body leading-body text-fg shadow-floating outline-none data-[state=closed]:animate-fade-out data-[state=open]:animate-fade-in",
          className,
        )}
        {...props}
      />
      </ChakraPopover.Positioner>
    </Portal>
  );
}

/** The popover's head: its title over a short muted line. */
function PopoverHeader({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="popover-header" className={cn("flex flex-col gap-0.5", className)} {...props} />;
}

function PopoverTitle({ className, ...props }: React.ComponentProps<"h2">) {
  return <h2 data-slot="popover-title" className={cn("font-sans text-body-lg leading-body font-medium text-fg", className)} {...props} />;
}

function PopoverDescription({ className, ...props }: React.ComponentProps<"p">) {
  return <p data-slot="popover-description" className={cn("text-body leading-body text-fg-muted", className)} {...props} />;
}

export { Popover, PopoverAnchor, PopoverContent, PopoverDescription, PopoverHeader, PopoverTitle, PopoverTrigger };

```

# Progress
An 8px lilac pill track filled with the purple.

Install: npx inkbox-ds add progress
Requires: theme, utils
Packages: @chakra-ui/react
Exports: Progress
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the Email table's Storage column, the lilac wells and the purple action color


## Usage
Use for a known amount (mailbox storage used, an upload, setup steps done). Put the value as text beside it (0%) and give it an aria-label. For unknown waits use Spinner.
- Avoid: Striped or gradient fills
- Avoid: Progress for something that takes under a second
- Avoid: A track thicker than 8px


## Examples
Example components: npx inkbox-ds add progress
[Preview](https://inkbox-ds.vercel.app/preview/progress/Preview) | [Values](https://inkbox-ds.vercel.app/preview/progress/Values)

examples/progress.tsx

```tsx
"use client";

import * as React from "react";

import { Progress } from "@/components/ui/progress";

export function Preview() {
  const [value, setValue] = React.useState(12);
  React.useEffect(() => {
    // ds-latency: advances a presentation-only progress example; no user input is waiting.
    const t = setTimeout(() => setValue(64), 600);
    return () => clearTimeout(t);
  }, []);
  return (
    <div className="grid w-full max-w-100 gap-2">
      <div className="flex justify-between text-body">
        <span className="text-fg">Mailbox storage</span>
        <span className="text-fg-muted">{value}%</span>
      </div>
      <Progress value={value} aria-label="Mailbox storage used" />
    </div>
  );
}

export function Values() {
  return (
    <div className="grid w-full max-w-100 gap-4">
      <Progress value={0} aria-label="Empty" />
      <Progress value={33} aria-label="A third" />
      <Progress value={100} aria-label="Full" />
    </div>
  );
}

```

## Source

components/ui/progress.tsx

```tsx
"use client";

import * as React from "react";
import { Progress as ChakraProgress } from "@chakra-ui/react";

import { cn } from "@/lib/utils";

// How far along something is (mailbox storage, an upload): an 8px lilac pill track with the purple filling it from the
// left. A new value slides the fill there (300ms, the strong ease-out); with reduced motion it jumps.
function Progress({ className, value, ...props }: React.ComponentProps<typeof ChakraProgress.Root>) {
  return (
    <ChakraProgress.Root unstyled data-slot="progress" value={value} className={cn("relative h-2 w-full overflow-hidden rounded-pill bg-subtle", className)} {...props}>
      <ChakraProgress.Track className="size-full overflow-hidden rounded-pill bg-transparent">
      <ChakraProgress.Range
        data-slot="progress-indicator"
        className="size-full flex-1 rounded-pill bg-primary transition-[translate] duration-300 ease-out motion-reduce:transition-none"
        style={{ translate: `-${100 - (value ?? 0)}%` }}
      />
      </ChakraProgress.Track>
    </ChakraProgress.Root>
  );
}

export { Progress };

```

# Questionnaire
Questions asked one at a time: white choice cards with the brand's radio or checkbox and a shortcut key, a typed answer, a progress count and Previous, Skip and Next pills.

Install: npx inkbox-ds add questionnaire
Requires: theme, button, input, kbd, progress, utils
Packages: @phosphor-icons/react
Exports: Questionnaire, QuestionnaireActions, QuestionnaireChoice, QuestionnaireChoiceDescription, QuestionnaireChoices, QuestionnaireDescription, QuestionnaireError, QuestionnaireInput, QuestionnaireItem, QuestionnaireNext, QuestionnairePrevious, QuestionnaireProgress, QuestionnaireSkip, QuestionnaireSubmit, QuestionnaireTitle
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the radio and checks in Create Agent Identity and the Where does this agent run? picker


## Usage
Use when an agent or a setup flow needs a few answers in a row (how to route calls, what to include in a summary). Pass the questions as items to Questionnaire, then render a QuestionnaireItem per question with a QuestionnaireTitle, a QuestionnaireDescription, QuestionnaireChoices of QuestionnaireChoice (add QuestionnaireInput for another answer) and a QuestionnaireError; end with QuestionnaireActions holding Previous, Skip, Next and Submit. Mark required questions; set multiple to allow several answers. onSubmit receives the native form event: read the answers with FormData.
- Avoid: More than one question on screen
- Avoid: Animating between questions
- Avoid: A required question without its error message
- Avoid: A purple card fill for a chosen answer


## Examples
Example components: npx inkbox-ds add questionnaire
[Preview](https://inkbox-ds.vercel.app/preview/questionnaire/Preview) | [Disabled](https://inkbox-ds.vercel.app/preview/questionnaire/Disabled)

examples/questionnaire.tsx

```tsx
"use client";

import * as React from "react";

import {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoiceDescription,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireInput,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSkip,
  QuestionnaireSubmit,
  QuestionnaireTitle,
} from "@/components/ui/questionnaire";

const ITEMS = [
  { name: "channel", required: true, choices: [{ value: "email" }, { value: "phone" }, { value: "imessage" }] },
  { name: "include", multiple: true, choices: [{ value: "sender" }, { value: "summary" }, { value: "attachments" }, { value: "next-step" }] },
  { name: "when", required: true, choices: [{ value: "now" }, { value: "hourly" }, { value: "daily" }] },
] as const;

function Saved({ answers }: { answers: string }) {
  return (
    <p role="status" className="rounded-control bg-success-bg px-3.5 py-2.5 text-body text-fg">
      Saved. {answers}
    </p>
  );
}

export function Preview() {
  const [saved, setSaved] = React.useState<string>();
  return (
    <div className="mx-auto grid w-full max-w-110 gap-4">
      <Questionnaire
        items={ITEMS}
        onSubmit={(event) => {
          event.preventDefault();
          const data = new FormData(event.currentTarget);
          setSaved(`Channel: ${data.get("channel")}. Include: ${data.getAll("include").join(", ") || "nothing"}. When: ${data.get("when")}.`);
        }}
      >
        <QuestionnaireProgress />
        <QuestionnaireItem name="channel" required>
          <QuestionnaireTitle>Where should @acme tell you about new mail?</QuestionnaireTitle>
          <QuestionnaireDescription>Choose a channel, or type another one.</QuestionnaireDescription>
          <QuestionnaireChoices>
            <QuestionnaireChoice value="email">
              <span className="font-medium">Email</span>
              <QuestionnaireChoiceDescription>A note to robert@acme.com</QuestionnaireChoiceDescription>
            </QuestionnaireChoice>
            <QuestionnaireChoice value="phone">
              <span className="font-medium">Phone</span>
              <QuestionnaireChoiceDescription>A text from the agent&apos;s number</QuestionnaireChoiceDescription>
            </QuestionnaireChoice>
            <QuestionnaireChoice value="imessage">
              <span className="font-medium">iMessage</span>
              <QuestionnaireChoiceDescription>Through the shared iMessage line</QuestionnaireChoiceDescription>
            </QuestionnaireChoice>
            <QuestionnaireInput aria-label="Another channel" placeholder="Another channel" />
          </QuestionnaireChoices>
          <QuestionnaireError />
        </QuestionnaireItem>
        <QuestionnaireItem name="include" multiple>
          <QuestionnaireTitle>What should each note include?</QuestionnaireTitle>
          <QuestionnaireDescription>Choose any, or skip this question.</QuestionnaireDescription>
          <QuestionnaireChoices>
            <QuestionnaireChoice value="sender">The sender</QuestionnaireChoice>
            <QuestionnaireChoice value="summary">A one-line summary</QuestionnaireChoice>
            <QuestionnaireChoice value="attachments">Attachments</QuestionnaireChoice>
            <QuestionnaireChoice value="next-step">The suggested next step</QuestionnaireChoice>
          </QuestionnaireChoices>
          <QuestionnaireError />
        </QuestionnaireItem>
        <QuestionnaireItem name="when" required>
          <QuestionnaireTitle>How often?</QuestionnaireTitle>
          <QuestionnaireDescription>Batched notes arrive once per period.</QuestionnaireDescription>
          <QuestionnaireChoices>
            <QuestionnaireChoice value="now">As each email arrives</QuestionnaireChoice>
            <QuestionnaireChoice value="hourly">Once an hour</QuestionnaireChoice>
            <QuestionnaireChoice value="daily">Once a day</QuestionnaireChoice>
          </QuestionnaireChoices>
          <QuestionnaireError />
        </QuestionnaireItem>
        <QuestionnaireActions>
          <QuestionnairePrevious />
          <QuestionnaireSkip />
          <QuestionnaireNext />
          <QuestionnaireSubmit>Save rule</QuestionnaireSubmit>
        </QuestionnaireActions>
      </Questionnaire>
      {saved && <Saved answers={saved} />}
    </div>
  );
}

const PLAN = [{ name: "line", required: true, choices: [{ value: "shared" }, { value: "dedicated" }, { value: "port" }] }] as const;

export function Disabled() {
  return (
    <Questionnaire items={PLAN} shortcuts="letters" className="mx-auto max-w-110" onSubmit={(event) => event.preventDefault()}>
      <QuestionnaireItem name="line" required>
        <QuestionnaireTitle>Which iMessage line should the agent use?</QuestionnaireTitle>
        <QuestionnaireDescription>No dedicated lines are available to assign right now.</QuestionnaireDescription>
        <QuestionnaireChoices>
          <QuestionnaireChoice value="shared">
            <span className="font-medium">Shared</span>
            <QuestionnaireChoiceDescription>Assigned when someone connects</QuestionnaireChoiceDescription>
          </QuestionnaireChoice>
          <QuestionnaireChoice value="dedicated" disabled>
            <span className="font-medium">Dedicated</span>
            <QuestionnaireChoiceDescription>None available</QuestionnaireChoiceDescription>
          </QuestionnaireChoice>
          <QuestionnaireChoice value="port">
            <span className="font-medium">Port a number</span>
            <QuestionnaireChoiceDescription>Bring an existing number</QuestionnaireChoiceDescription>
          </QuestionnaireChoice>
        </QuestionnaireChoices>
        <QuestionnaireError />
      </QuestionnaireItem>
      <QuestionnaireActions>
        <QuestionnaireSubmit>Assign line</QuestionnaireSubmit>
      </QuestionnaireActions>
    </Questionnaire>
  );
}

```

## Source

components/ui/questionnaire.tsx

```tsx
"use client";

import * as React from "react";
import { CheckIcon } from "@phosphor-icons/react/ssr";

import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Kbd } from "@/components/ui/kbd";
import { Progress } from "@/components/ui/progress";
import { cn } from "@/lib/utils";

// A short set of questions asked one at a time (extrapolated from the console, Figma 427:2715: Create Agent Identity's
// choices and the Where does this agent run? picker). A choice is a 44px white card with the field edge and 8px
// corners, the brand's radio (a thick pink ring when chosen) or checkbox (purple when checked) 14px in, a 14px ink label
// and its number or letter key at the right; a chosen card takes the purple edge. The question is 16px medium ink with
// a 14px secondary line under it; progress is a 12px muted count over a thin purple bar. Changing questions is instant:
// it is driven by the keyboard as often as by the pointer. The answers submit as one native form (FormData), every
// question's inputs included, so the page owns saving and what happens next.

type Choice = { readonly value: string; readonly disabled?: boolean };
type ItemConfig = { readonly name: string; readonly required?: boolean; readonly multiple?: boolean; readonly choices?: readonly Choice[] };
type Shortcuts = "numbers" | "letters" | "none";

type QuestionnaireContextValue = {
  order: string[];
  active: string | undefined;
  goTo: (name: string) => void;
  shortcuts: Shortcuts;
  answers: Record<string, string[]>;
  other: Record<string, string>;
  errors: Record<string, string | undefined>;
  configs: React.RefObject<Map<string, ItemConfig>>;
  register: (config: ItemConfig) => () => void;
  setAnswer: (name: string, value: string, checked: boolean) => void;
  setOther: (name: string, text: string) => void;
  next: () => void;
  previous: () => void;
  skip: () => void;
};

const QuestionnaireContext = React.createContext<QuestionnaireContextValue | null>(null);
const ItemContext = React.createContext<{ name: string; required: boolean; multiple: boolean; id: string } | null>(null);

function useQuestionnaire() {
  const context = React.useContext(QuestionnaireContext);
  if (!context) throw new Error("Questionnaire parts must be inside a Questionnaire.");
  return context;
}

function useItem() {
  const context = React.useContext(ItemContext);
  if (!context) throw new Error("This part must be inside a QuestionnaireItem.");
  return context;
}

const shortcutKey = (index: number, shortcuts: Shortcuts) => (shortcuts === "none" || index > 8 ? undefined : shortcuts === "letters" ? String.fromCharCode(65 + index) : String(index + 1));

/**
 * The questions and their answers. Pass `items` (name, required, multiple, choices) so the order, progress and shortcuts
 * are known on the server; without it the order is the QuestionnaireItems' order. `defaultItem` or a controlled
 * `item` with `onItemChange` picks the question shown. `shortcuts` puts 1 to 9 (or A to I) on the choices.
 */
function Questionnaire({
  items,
  defaultItem,
  item,
  onItemChange,
  shortcuts = "numbers",
  className,
  onSubmit,
  onKeyDown,
  children,
  ...props
}: Omit<React.ComponentProps<"form">, "onSubmit"> & {
  items?: readonly ItemConfig[];
  defaultItem?: string;
  item?: string;
  onItemChange?: (name: string) => void;
  shortcuts?: Shortcuts;
  onSubmit?: (event: React.FormEvent<HTMLFormElement>) => void;
}) {
  const form = React.useRef<HTMLFormElement>(null);
  const configs = React.useRef(new Map<string, ItemConfig>(items?.map((i) => [i.name, i])));
  const [registered, setRegistered] = React.useState<string[]>([]);
  const order = items ? items.map((i) => i.name) : registered;
  const [internal, setInternal] = React.useState(defaultItem ?? items?.[0]?.name);
  const active = item ?? internal ?? order[0];
  const [answers, setAnswers] = React.useState<Record<string, string[]>>({});
  const [other, setOtherState] = React.useState<Record<string, string>>({});
  const [errors, setErrors] = React.useState<Record<string, string | undefined>>({});

  const focusItem = React.useCallback((name: string) => {
    requestAnimationFrame(() => {
      const fieldset = form.current?.querySelector<HTMLElement>(`[data-slot=questionnaire-item][data-name="${CSS.escape(name)}"]`);
      fieldset?.querySelector<HTMLElement>("input:not(:disabled)")?.focus({ preventScroll: true });
    });
  }, []);

  const goTo = React.useCallback(
    (name: string) => {
      if (item === undefined) setInternal(name);
      onItemChange?.(name);
      focusItem(name);
    },
    [item, onItemChange, focusItem],
  );

  const register = React.useCallback((config: ItemConfig) => {
    configs.current.set(config.name, { ...configs.current.get(config.name), ...config });
    setRegistered((list) => (list.includes(config.name) ? list : [...list, config.name]));
    return () => setRegistered((list) => list.filter((n) => n !== config.name));
  }, []);

  const answered = React.useCallback((name: string) => (answers[name]?.length ?? 0) > 0 || (other[name] ?? "").trim() !== "", [answers, other]);

  const validate = React.useCallback(
    (name: string) => {
      const config = configs.current.get(name);
      const message = config?.required && !answered(name) ? (config.multiple ? "Choose at least one answer to continue." : "Choose an answer to continue.") : undefined;
      setErrors((e) => ({ ...e, [name]: message }));
      return !message;
    },
    [answered],
  );

  const setAnswer = React.useCallback((name: string, value: string, checked: boolean) => {
    const multiple = configs.current.get(name)?.multiple;
    setAnswers((a) => ({ ...a, [name]: multiple ? (checked ? [...(a[name] ?? []).filter((v) => v !== value), value] : (a[name] ?? []).filter((v) => v !== value)) : checked ? [value] : [] }));
    if (!multiple && checked) setOtherState((o) => ({ ...o, [name]: "" }));
    setErrors((e) => ({ ...e, [name]: undefined }));
  }, []);

  const setOther = React.useCallback((name: string, text: string) => {
    setOtherState((o) => ({ ...o, [name]: text }));
    if (text && !configs.current.get(name)?.multiple) setAnswers((a) => ({ ...a, [name]: [] }));
    setErrors((e) => ({ ...e, [name]: undefined }));
  }, []);

  const index = active ? order.indexOf(active) : -1;
  const next = React.useCallback(() => {
    if (!active || !validate(active)) return focusItem(active ?? "");
    const following = order[index + 1];
    if (following) goTo(following);
  }, [active, validate, focusItem, order, index, goTo]);
  const previous = React.useCallback(() => {
    const before = order[index - 1];
    if (before) goTo(before);
  }, [order, index, goTo]);
  const skip = React.useCallback(() => {
    if (!active) return;
    setAnswers((a) => ({ ...a, [active]: [] }));
    setOtherState((o) => ({ ...o, [active]: "" }));
    setErrors((e) => ({ ...e, [active]: undefined }));
    const following = order[index + 1];
    if (following) goTo(following);
  }, [active, order, index, goTo]);

  const value = React.useMemo<QuestionnaireContextValue>(
    () => ({ order, active, goTo, shortcuts, answers, other, errors, configs, register, setAnswer, setOther, next, previous, skip }),
    [order, active, goTo, shortcuts, answers, other, errors, register, setAnswer, setOther, next, previous, skip],
  );

  return (
    <QuestionnaireContext.Provider value={value}>
      <form
        ref={form}
        data-slot="questionnaire"
        noValidate
        className={cn("flex w-full min-w-0 flex-col gap-4", className)}
        onSubmit={(event) => {
          // Every required question must be answered; the first one that is not is shown with its message.
          const missing = order.find((name) => !validate(name));
          if (missing) {
            event.preventDefault();
            goTo(missing);
            return;
          }
          onSubmit?.(event);
        }}
        onKeyDown={(event) => {
          onKeyDown?.(event);
          if (event.defaultPrevented || !active || event.metaKey || event.ctrlKey || event.altKey) return;
          const target = event.target as HTMLElement;
          const typing = target instanceof HTMLInputElement && target.type === "text";
          if (event.key === "Enter" && !(target instanceof HTMLButtonElement) && !(target instanceof HTMLTextAreaElement)) {
            event.preventDefault();
            if (index < order.length - 1) next();
            else form.current?.requestSubmit();
            return;
          }
          if (typing || shortcuts === "none") return;
          const key = event.key.toUpperCase();
          const at = shortcuts === "letters" ? key.charCodeAt(0) - 65 : Number(key) - 1;
          if (key.length !== 1 || Number.isNaN(at) || at < 0 || at > 8) return;
          const choice = form.current?.querySelectorAll<HTMLInputElement>(`[data-slot=questionnaire-item][data-name="${CSS.escape(active)}"] [data-slot=questionnaire-choice-input]`)[at];
          if (!choice || choice.disabled) return;
          event.preventDefault();
          choice.focus();
          setAnswer(active, choice.value, choice.type === "checkbox" ? !choice.checked : true);
        }}
        {...props}
      >
        {children}
      </form>
    </QuestionnaireContext.Provider>
  );
}

/** Where the person is: "Question 2 of 3" in 12px muted medium over a 4px purple bar. */
function QuestionnaireProgress({ className, children, ...props }: React.ComponentProps<"div">) {
  const { order, active } = useQuestionnaire();
  const at = active ? order.indexOf(active) + 1 : 0;
  const total = order.length;
  return (
    <div data-slot="questionnaire-progress" className={cn("grid w-full gap-1.5", className)} {...props}>
      <span className="font-sans text-caption leading-tight font-medium text-fg-muted tabular-nums" aria-live="polite">
        {children ?? (total ? `Question ${at} of ${total}` : " ")}
      </span>
      <Progress value={total ? (at / total) * 100 : 0} aria-label="Progress" className="h-1" />
    </div>
  );
}

/** One question. Only the current one shows; the others stay in the form so their answers submit with it. */
function QuestionnaireItem({ name, required = false, multiple = false, className, children, ...props }: Omit<React.ComponentProps<"fieldset">, "name"> & { name: string; required?: boolean; multiple?: boolean }) {
  const { active, register, errors } = useQuestionnaire();
  const id = React.useId();
  React.useLayoutEffect(() => register({ name, required, multiple }), [register, name, required, multiple]);
  const context = React.useMemo(() => ({ name, required, multiple, id }), [name, required, multiple, id]);
  const isActive = active === name;
  return (
    <ItemContext.Provider value={context}>
      <fieldset
        data-slot="questionnaire-item"
        data-name={name}
        data-active={isActive || undefined}
        hidden={!isActive}
        aria-labelledby={`${id}-title`}
        aria-describedby={`${id}-description${errors[name] ? ` ${id}-error` : ""}`}
        aria-invalid={errors[name] ? true : undefined}
        className={cn("m-0 flex min-w-0 flex-col gap-4 border-0 p-0 outline-none", className)}
        {...props}
      >
        {children}
      </fieldset>
    </ItemContext.Provider>
  );
}

function QuestionnaireTitle({ className, ...props }: React.ComponentProps<"div">) {
  const { id } = useItem();
  return <div id={`${id}-title`} data-slot="questionnaire-title" className={cn("font-sans text-body-lg leading-snug font-medium text-pretty text-fg", className)} {...props} />;
}

function QuestionnaireDescription({ className, ...props }: React.ComponentProps<"p">) {
  const { id } = useItem();
  return <p id={`${id}-description`} data-slot="questionnaire-description" className={cn("-mt-3 font-sans text-body leading-body text-pretty text-fg-secondary", className)} {...props} />;
}

/** The choices of a question, 8px apart; each direct QuestionnaireChoice gets its shortcut in order. */
function QuestionnaireChoices({ className, children, ...props }: React.ComponentProps<"div">) {
  const { multiple, id } = useItem();
  let index = 0;
  return (
    <div data-slot="questionnaire-choices" role={multiple ? "group" : "radiogroup"} aria-labelledby={`${id}-title`} className={cn("group/questionnaire-choices grid min-w-0 gap-2", className)} {...props}>
      {React.Children.map(children, (child) => (React.isValidElement<{ index?: number }>(child) && child.type === QuestionnaireChoice ? React.cloneElement(child, { index: index++ }) : child))}
    </div>
  );
}

function QuestionnaireChoice({ value, disabled = false, index = 0, className, children, ...props }: Omit<React.ComponentProps<"label">, "children"> & { value: string; disabled?: boolean; index?: number; children?: React.ReactNode }) {
  const { answers, setAnswer, shortcuts } = useQuestionnaire();
  const { name, multiple } = useItem();
  const checked = answers[name]?.includes(value) ?? false;
  const key = shortcutKey(index, shortcuts);
  return (
    <label
      data-slot="questionnaire-choice"
      data-type={multiple ? "checkbox" : "radio"}
      data-checked={checked || undefined}
      data-disabled={disabled || undefined}
      className={cn(
        "group/questionnaire-choice relative flex min-h-11 cursor-pointer items-start gap-2.5 rounded-control border border-line-field bg-surface px-3.5 py-2.5 text-start font-sans text-body leading-snug text-fg select-none transition-[background-color,border-color] duration-150 ease-out hover:bg-subtle has-focus-visible:outline-2 has-focus-visible:outline-offset-2 has-focus-visible:outline-focus-ring data-checked:border-line-brand data-disabled:pointer-events-none data-disabled:cursor-not-allowed data-disabled:opacity-50 motion-reduce:transition-none",
        className,
      )}
      {...props}
    >
      <input
        data-slot="questionnaire-choice-input"
        type={multiple ? "checkbox" : "radio"}
        name={name}
        value={value}
        checked={checked}
        disabled={disabled}
        onChange={(event) => setAnswer(name, value, event.target.checked)}
        className="peer sr-only"
      />
      <span
        aria-hidden
        data-slot="questionnaire-choice-indicator"
        className={cn(
          "pointer-events-none mt-px flex size-4.5 shrink-0 items-center justify-center border-[1.5px] border-line-strong bg-surface text-on-primary transition-[background-color,border-color,border-width] duration-150 ease-out motion-reduce:transition-none",
          multiple ? "rounded-pill group-data-checked/questionnaire-choice:border-primary group-data-checked/questionnaire-choice:bg-primary" : "rounded-pill group-data-checked/questionnaire-choice:border-4 group-data-checked/questionnaire-choice:border-pink",
        )}
      >
        {multiple && <CheckIcon weight="bold" className="hidden size-3.5 group-data-checked/questionnaire-choice:block" />}
      </span>
      <span data-slot="questionnaire-choice-label" className="flex min-w-0 flex-1 flex-col gap-0.5">
        {children}
      </span>
      {key && (
        <Kbd data-slot="questionnaire-choice-shortcut" aria-hidden className="ml-auto hidden shrink-0 sm:inline-flex">
          {key}
        </Kbd>
      )}
    </label>
  );
}

/** A choice's second line: 14px muted. */
function QuestionnaireChoiceDescription({ className, ...props }: React.ComponentProps<"span">) {
  return <span data-slot="questionnaire-choice-description" className={cn("text-fg-muted", className)} {...props} />;
}

/** A free answer typed instead of a choice (another answer); typing clears a single choice, choosing clears the text. */
function QuestionnaireInput({ className, ...props }: Omit<React.ComponentProps<typeof Input>, "name" | "value" | "onChange">) {
  const { other, setOther } = useQuestionnaire();
  const { name } = useItem();
  return (
    <div data-slot="questionnaire-input-wrapper" className="group/questionnaire-input relative w-full min-w-0">
      <Input data-slot="questionnaire-input" type="text" name={name} value={other[name] ?? ""} onChange={(event) => setOther(name, event.target.value)} className={cn("h-11", className)} {...props} />
    </div>
  );
}

/** Why the question cannot be passed yet: 12px red, read out when it appears. */
function QuestionnaireError({ className, children, ...props }: React.ComponentProps<"p">) {
  const { errors } = useQuestionnaire();
  const { name, id } = useItem();
  const message = children ?? errors[name];
  if (!message) return null;
  return (
    <p id={`${id}-error`} role="alert" data-slot="questionnaire-error" className={cn("-mt-2 font-sans text-caption leading-tight text-danger", className)} {...props}>
      {message}
    </p>
  );
}

/** The buttons under the question: Previous at the left, then Skip and Next (or Submit on the last question). */
function QuestionnaireActions({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="questionnaire-actions" className={cn("grid min-h-11 w-full grid-cols-[minmax(0,1fr)_auto_auto] items-center gap-2", className)} {...props} />;
}

type ActionProps = Omit<React.ComponentProps<typeof Button>, "onClick" | "type"> & { onClick?: React.MouseEventHandler<HTMLButtonElement> };

function QuestionnairePrevious({ children, className, variant = "secondary", onClick, ...props }: ActionProps) {
  const { order, active, previous } = useQuestionnaire();
  const first = !active || order.indexOf(active) <= 0;
  return (
    <Button
      data-slot="questionnaire-previous"
      variant={variant}
      disabled={first}
      className={cn("col-start-1 row-start-1 justify-self-start", first && "invisible", className)}
      onClick={(event) => {
        onClick?.(event);
        if (!event.defaultPrevented) previous();
      }}
      {...props}
    >
      {children ?? "Previous"}
    </Button>
  );
}

function QuestionnaireSkip({ children, className, variant = "ghost", onClick, ...props }: ActionProps) {
  const { active, configs, order, skip } = useQuestionnaire();
  const required = active ? configs.current.get(active)?.required : true;
  const last = !active || order.indexOf(active) === order.length - 1;
  if (required || last) return null;
  return (
    <Button
      data-slot="questionnaire-skip"
      variant={variant}
      className={cn("col-start-2 row-start-1 justify-self-end px-4 text-fg-secondary", className)}
      onClick={(event) => {
        onClick?.(event);
        if (!event.defaultPrevented) skip();
      }}
      {...props}
    >
      {children ?? "Skip"}
    </Button>
  );
}

function QuestionnaireNext({ children, className, variant = "default", onClick, ...props }: ActionProps) {
  const { order, active, next } = useQuestionnaire();
  if (!active || order.indexOf(active) >= order.length - 1) return null;
  return (
    <Button
      data-slot="questionnaire-next"
      variant={variant}
      className={cn("col-start-3 row-start-1 justify-self-end", className)}
      onClick={(event) => {
        onClick?.(event);
        if (!event.defaultPrevented) next();
      }}
      {...props}
    >
      {children ?? "Next"}
    </Button>
  );
}

function QuestionnaireSubmit({ children, className, variant = "default", ...props }: Omit<React.ComponentProps<typeof Button>, "type">) {
  const { order, active } = useQuestionnaire();
  if (!active || order.indexOf(active) !== order.length - 1) return null;
  return (
    <Button data-slot="questionnaire-submit" type="submit" variant={variant} className={cn("col-start-3 row-start-1 justify-self-end", className)} {...props}>
      {children ?? "Submit"}
    </Button>
  );
}

export {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoiceDescription,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireInput,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSkip,
  QuestionnaireSubmit,
  QuestionnaireTitle,
};

```

# Radio Group
18px circles; the chosen one takes a thick pink ring around a white center.

Install: npx inkbox-ds add radio-group
Requires: theme, utils
Packages: @chakra-ui/react
Exports: RadioGroup, RadioGroupItem
Client boundary: yes
Reference: Figma 427:2715: Tunnel TLS mode radios in Create Agent Identity (Modal States)


## Usage
Use for one choice among two to five visible options (Tunnel TLS mode: Edge (default), Passthrough). Stack options 8px apart, each with its label 8px from the circle. For more options use Select; for an immediate view switch use Tabs or Toggle Group.
- Avoid: A purple or filled dot for the chosen option
- Avoid: Radios laid out without labels
- Avoid: A single radio on its own


## Examples
Example components: npx inkbox-ds add radio-group label
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/radio-group/Preview) | [States](https://inkbox-ds.vercel.app/preview/radio-group/States)

examples/radio-group.tsx

```tsx
"use client";

import { InfoIcon } from "@phosphor-icons/react/ssr";

import { Label } from "@/components/ui/label";
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";

export function Preview() {
  return (
    <div className="grid gap-2">
      <p id="tls-mode" className="flex items-center gap-1.5 text-body leading-body text-fg">
        Tunnel TLS mode <InfoIcon weight="fill" aria-hidden className="size-4 text-fg-label" />
      </p>
      <RadioGroup defaultValue="edge" aria-labelledby="tls-mode">
        <div className="flex items-center gap-2">
          <RadioGroupItem value="edge" id="edge" />
          <Label htmlFor="edge">Edge (default)</Label>
        </div>
        <div className="flex items-center gap-2">
          <RadioGroupItem value="passthrough" id="passthrough" />
          <Label htmlFor="passthrough">Passthrough</Label>
        </div>
      </RadioGroup>
    </div>
  );
}

export function States() {
  return (
    <RadioGroup defaultValue="shared" aria-label="iMessage line">
      <div className="flex items-center gap-2">
        <RadioGroupItem value="shared" id="shared" />
        <Label htmlFor="shared">Shared line</Label>
      </div>
      <div className="flex items-center gap-2">
        <RadioGroupItem value="dedicated" id="dedicated" disabled />
        <Label htmlFor="dedicated">Dedicated line (none available)</Label>
      </div>
      <div className="flex items-center gap-2">
        <RadioGroupItem value="none" id="none" aria-invalid />
        <Label htmlFor="none">No line (invalid)</Label>
      </div>
    </RadioGroup>
  );
}

```

## Source

components/ui/radio-group.tsx

```tsx
"use client";

import * as React from "react";
import { RadioGroup as ChakraRadioGroup } from "@chakra-ui/react";

import { cn } from "@/lib/utils";

// The console's radios (Tunnel TLS mode: Edge (default), Passthrough): an 18px circle on white. Unselected it has a
// 1.5px gray edge; selected it takes a thick 4px pink ring around a white center. Options stack 8px apart, each label
// 14px ink 8px from its circle (wrap item and label in a `label`, or pair them with htmlFor).
type RadioGroupProps = Omit<React.ComponentProps<typeof ChakraRadioGroup.Root>, "onValueChange"> & { onValueChange?: (value: string | null) => void };
function RadioGroup({ className, onValueChange, ...props }: RadioGroupProps) {
  return <ChakraRadioGroup.Root unstyled data-slot="radio-group" className={cn("grid gap-2", className)} onValueChange={(details) => onValueChange?.(details.value)} {...props} />;
}

function RadioGroupItem({ className, ...props }: React.ComponentProps<typeof ChakraRadioGroup.Item>) {
  return (
    <ChakraRadioGroup.Item
      data-slot="radio-group-item"
      unstyled
      className={cn(
        "peer relative aspect-square size-4.5 shrink-0 cursor-pointer rounded-pill border-[1.5px] border-line-strong bg-surface outline-none active:brightness-95 active:transition-none transition-[border-color,border-width] duration-150 ease-out hover:border-fg-muted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-danger data-[state=checked]:border-4 data-[state=checked]:border-pink motion-reduce:transition-none",
        className,
      )}
      {...props}
    >
      <ChakraRadioGroup.ItemHiddenInput />
      <ChakraRadioGroup.ItemControl className="contents">
        <ChakraRadioGroup.ItemIndicator data-slot="radio-group-indicator" className="sr-only" />
      </ChakraRadioGroup.ItemControl>
    </ChakraRadioGroup.Item>
  );
}

export { RadioGroup, RadioGroupItem };

```

# Resizable
Panels split by the console's 1px lilac rule, which can be dragged or moved with the arrow keys.

Install: npx inkbox-ds add resizable
Requires: theme, utils
Packages: @phosphor-icons/react
Exports: ResizableHandle, ResizablePanel, ResizablePanelGroup
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the 1px rules between the rails and the inbox list


## Usage
Use for a workspace whose panes people size themselves (the inbox list beside a message, a log beside its detail). Give each ResizablePanel a defaultSize in percent and sensible minSize; add withHandle when the edge needs to be found.
- Avoid: Thick or colored dividers
- Avoid: Panels that can collapse to nothing without a minSize
- Avoid: Animating the panes while dragging


## Examples
Example components: npx inkbox-ds add resizable
[Preview](https://inkbox-ds.vercel.app/preview/resizable/Preview) | [Nested](https://inkbox-ds.vercel.app/preview/resizable/Nested)

examples/resizable.tsx

```tsx
import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from "@/components/ui/resizable";

function Pane({ label, className }: { label: string; className?: string }) {
  return <div className={"flex h-full items-center justify-center p-6 text-body text-fg-muted " + (className ?? "")}>{label}</div>;
}

export function Preview() {
  return (
    <ResizablePanelGroup direction="horizontal" className="min-h-64 max-w-2xl overflow-hidden rounded-panel border border-line-subtle">
      <ResizablePanel defaultSize={36} minSize={20}>
        <Pane label="Inbox" className="bg-subtle" />
      </ResizablePanel>
      <ResizableHandle withHandle />
      <ResizablePanel defaultSize={64} minSize={30}>
        <Pane label="Message" />
      </ResizablePanel>
    </ResizablePanelGroup>
  );
}

export function Nested() {
  return (
    <ResizablePanelGroup direction="horizontal" className="min-h-72 max-w-2xl overflow-hidden rounded-panel border border-line-subtle">
      <ResizablePanel defaultSize={30} minSize={15}>
        <Pane label="Agents" className="bg-subtle" />
      </ResizablePanel>
      <ResizableHandle />
      <ResizablePanel defaultSize={70}>
        <ResizablePanelGroup direction="vertical">
          <ResizablePanel defaultSize={40} minSize={20}>
            <Pane label="Delivery log" />
          </ResizablePanel>
          <ResizableHandle withHandle />
          <ResizablePanel defaultSize={60} minSize={20}>
            <Pane label="Payload" />
          </ResizablePanel>
        </ResizablePanelGroup>
      </ResizablePanel>
    </ResizablePanelGroup>
  );
}

```

## Source

components/ui/resizable.tsx

```tsx
"use client";

import * as React from "react";
import { DotsSixVerticalIcon } from "@phosphor-icons/react/ssr";

import { cn } from "@/lib/utils";

// Panels with a draggable edge between them (extrapolated from the Inkbox console, Figma 427:2715: the 1px rules
// between its rails and the inbox list). The handle is the console's 1px lilac rule with a wide invisible grip; with
// `withHandle` it carries a 12 by 20 white tab with 4px corners, the field edge and a grip glyph. Drag it, or focus it
// and use the arrow keys (Home and End go to the limits). Sizes are percentages of the group; dragging follows the
// pointer directly, with no animation.

type Direction = "horizontal" | "vertical";
type PanelInfo = { id: string; defaultSize?: number; minSize: number; maxSize: number; order: number };
type GroupContext = {
  direction: Direction;
  sizes: Record<string, number>;
  register: (info: PanelInfo) => () => void;
  resize: (handleEl: HTMLElement, delta: number) => void;
  set: (handleEl: HTMLElement, to: "min" | "max") => void;
  limits: (handleEl: HTMLElement) => { before?: string; value: number; min: number; max: number };
};

const ResizableContext = React.createContext<GroupContext | null>(null);
const useGroup = () => {
  const ctx = React.useContext(ResizableContext);
  if (!ctx) throw new Error("Resizable parts must be used within a <ResizablePanelGroup />");
  return ctx;
};

function ResizablePanelGroup({ direction = "horizontal", className, onLayout, children, ...props }: Omit<React.ComponentProps<"div">, "dir"> & { direction?: Direction; onLayout?: (sizes: number[]) => void }) {
  const [panels, setPanels] = React.useState<PanelInfo[]>([]);
  const [sizes, setSizes] = React.useState<Record<string, number>>({});
  const group = React.useRef<HTMLDivElement>(null);
  const counter = React.useRef(0);

  const register = React.useCallback((info: PanelInfo) => {
    setPanels((p) => [...p.filter((x) => x.id !== info.id), { ...info, order: counter.current++ }]);
    return () => setPanels((p) => p.filter((x) => x.id !== info.id));
  }, []);

  // Panels without a default size share what the others leave.
  React.useEffect(() => {
    setSizes((current) => {
      const ids = panels.map((p) => p.id);
      if (ids.every((id) => id in current) && Object.keys(current).length === ids.length) return current;
      const fixed = panels.filter((p) => p.defaultSize !== undefined).reduce((s, p) => s + (p.defaultSize ?? 0), 0);
      const free = panels.filter((p) => p.defaultSize === undefined).length;
      return Object.fromEntries(panels.map((p) => [p.id, p.defaultSize ?? Math.max(0, (100 - fixed) / Math.max(1, free))]));
    });
  }, [panels]);

  const ordered = React.useCallback(() => {
    const els = Array.from(group.current?.querySelectorAll<HTMLElement>(":scope > [data-slot=resizable-panel]") ?? []);
    return els.map((el) => el.dataset.panelId!);
  }, []);

  const neighbors = React.useCallback((handleEl: HTMLElement) => {
    let prev = handleEl.previousElementSibling as HTMLElement | null;
    while (prev && prev.dataset.slot !== "resizable-panel") prev = prev.previousElementSibling as HTMLElement | null;
    let next = handleEl.nextElementSibling as HTMLElement | null;
    while (next && next.dataset.slot !== "resizable-panel") next = next.nextElementSibling as HTMLElement | null;
    return [prev?.dataset.panelId, next?.dataset.panelId] as const;
  }, []);

  const info = (id?: string) => panels.find((p) => p.id === id);

  const apply = React.useCallback((a: string, b: string, nextA: number) => {
    setSizes((s) => {
      const pa = panels.find((p) => p.id === a);
      const pb = panels.find((p) => p.id === b);
      if (!pa || !pb) return s;
      const total = s[a] + s[b];
      const lo = Math.max(pa.minSize, total - pb.maxSize);
      const hi = Math.min(pa.maxSize, total - pb.minSize);
      const clamped = Math.min(hi, Math.max(lo, nextA));
      if (clamped === s[a]) return s;
      const out = { ...s, [a]: clamped, [b]: total - clamped };
      onLayout?.(ordered().map((id) => out[id]));
      return out;
    });
  }, [onLayout, ordered, panels]);

  const resize = React.useCallback((handleEl: HTMLElement, delta: number) => {
    const [a, b] = neighbors(handleEl);
    if (a && b) apply(a, b, (sizes[a] ?? 0) + delta);
  }, [apply, neighbors, sizes]);

  const set = React.useCallback((handleEl: HTMLElement, to: "min" | "max") => {
    const [a, b] = neighbors(handleEl);
    if (a && b) apply(a, b, to === "min" ? 0 : 100);
  }, [apply, neighbors]);

  const limits = (handleEl: HTMLElement) => {
    const [a] = neighbors(handleEl);
    const p = info(a);
    return { before: a, value: a ? Math.round(sizes[a] ?? 0) : 0, min: p?.minSize ?? 0, max: p?.maxSize ?? 100 };
  };

  return (
    <ResizableContext.Provider value={{ direction, sizes, register, resize, set, limits }}>
      <div
        ref={group}
        data-slot="resizable-panel-group"
        data-panel-group-direction={direction}
        className={cn("flex h-full w-full", direction === "vertical" && "flex-col", className)}
        {...props}
      >
        {children}
      </div>
    </ResizableContext.Provider>
  );
}

function ResizablePanel({ defaultSize, minSize = 0, maxSize = 100, className, style, id: idProp, ...props }: React.ComponentProps<"div"> & { defaultSize?: number; minSize?: number; maxSize?: number }) {
  const { register, sizes } = useGroup();
  const auto = React.useId();
  const id = idProp ?? auto;
  React.useLayoutEffect(() => register({ id, defaultSize, minSize, maxSize, order: 0 }), [register, id, defaultSize, minSize, maxSize]);
  const size = sizes[id] ?? defaultSize;
  return (
    <div
      data-slot="resizable-panel"
      data-panel-id={id}
      data-panel-size={size === undefined ? undefined : Math.round(size)}
      className={cn("min-h-0 min-w-0 overflow-hidden", className)}
      style={{ flexGrow: size ?? 1, flexShrink: 1, flexBasis: 0, ...style }}
      {...props}
    />
  );
}

function ResizableHandle({ withHandle, className, ...props }: React.ComponentProps<"div"> & { withHandle?: boolean }) {
  const { direction, resize, set, limits } = useGroup();
  const ref = React.useRef<HTMLDivElement>(null);
  const drag = React.useRef<{ start: number; size: number; pointer: number } | null>(null);
  const [, force] = React.useReducer((n: number) => n + 1, 0);
  const vertical = direction === "vertical";
  React.useEffect(() => force(), []);
  const lim = ref.current ? limits(ref.current) : { value: 0, min: 0, max: 100 };

  return (
    <div
      ref={ref}
      role="separator"
      tabIndex={0}
      aria-orientation={vertical ? "horizontal" : "vertical"}
      aria-valuenow={lim.value}
      aria-valuemin={lim.min}
      aria-valuemax={lim.max}
      aria-label="Resize"
      data-slot="resizable-handle"
      data-panel-group-direction={direction}
      className={cn(
        "relative flex shrink-0 touch-none items-center justify-center bg-line-subtle outline-none select-none after:absolute focus-visible:bg-line-brand focus-visible:outline-none data-[dragging]:bg-line-brand",
        vertical ? "h-px w-full cursor-row-resize after:inset-x-0 after:-inset-y-1.5" : "w-px cursor-col-resize after:inset-y-0 after:-inset-x-1.5",
        className,
      )}
      onPointerDown={(e) => {
        if (drag.current || e.button !== 0) return;
        const group = ref.current?.parentElement;
        if (!group) return;
        e.currentTarget.setPointerCapture(e.pointerId);
        e.currentTarget.dataset.dragging = "";
        drag.current = { start: vertical ? e.clientY : e.clientX, size: vertical ? group.clientHeight : group.clientWidth, pointer: e.pointerId };
      }}
      onPointerMove={(e) => {
        const d = drag.current;
        if (!d || e.pointerId !== d.pointer || !ref.current) return;
        const pos = vertical ? e.clientY : e.clientX;
        const delta = ((pos - d.start) / d.size) * 100;
        if (Math.abs(delta) < 0.1) return;
        resize(ref.current, delta);
        d.start = pos;
      }}
      onPointerUp={(e) => {
        drag.current = null;
        delete e.currentTarget.dataset.dragging;
      }}
      onPointerCancel={(e) => {
        drag.current = null;
        delete e.currentTarget.dataset.dragging;
      }}
      onKeyDown={(e) => {
        if (!ref.current) return;
        const step = e.shiftKey ? 10 : 2;
        const back = vertical ? "ArrowUp" : "ArrowLeft";
        const forward = vertical ? "ArrowDown" : "ArrowRight";
        if (e.key === back || e.key === forward) {
          e.preventDefault();
          resize(ref.current, e.key === back ? -step : step);
        } else if (e.key === "Home" || e.key === "End") {
          e.preventDefault();
          set(ref.current, e.key === "Home" ? "min" : "max");
        }
      }}
      {...props}
    >
      {withHandle && (
        <div className={cn("z-10 flex items-center justify-center rounded-xs border border-line-field bg-surface text-icon-secondary", vertical ? "h-3 w-5" : "h-5 w-3")}>
          <DotsSixVerticalIcon weight="bold" className={cn("size-3", vertical && "rotate-90")} />
        </div>
      )}
    </div>
  );
}

export { ResizableHandle, ResizablePanel, ResizablePanelGroup };

```

# Scroll Area
A region that scrolls inside the page with a thin lilac-gray bar.

Install: npx inkbox-ds add scroll-area
Requires: theme, utils
Packages: @chakra-ui/react
Exports: ScrollArea, ScrollBar
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the inbox and event lists, the field edge color for the thumb


## Usage
Use for a panel with its own scroll (the email list, the event catalog, a long menu) inside a fixed-height layout. Give it a height (h-80, flex-1 in a column). Add a horizontal ScrollBar for wide content.
- Avoid: Nested scroll areas in the same direction
- Avoid: Hiding the bar entirely on desktop
- Avoid: A dark thumb


## Examples
Example components: npx inkbox-ds add scroll-area separator
[Preview](https://inkbox-ds.vercel.app/preview/scroll-area/Preview) | [Horizontal](https://inkbox-ds.vercel.app/preview/scroll-area/Horizontal)

examples/scroll-area.tsx

```tsx
import { ScrollArea, ScrollBar } from "@/components/ui/scroll-area";
import { Separator } from "@/components/ui/separator";

const EVENTS = Array.from({ length: 24 }, (_, i) => `message.${["sent", "delivered", "bounced", "received"][i % 4]}.${i + 1}`);

export function Preview() {
  return (
    <ScrollArea className="h-72 w-64 rounded-panel border border-line-subtle">
      <div className="p-3">
        <p className="mb-2 text-body-sm text-fg-label">Events</p>
        {EVENTS.map((event, i) => (
          <div key={event}>
            {i > 0 && <Separator className="my-2" />}
            <p className="text-body text-fg">{event}</p>
          </div>
        ))}
      </div>
    </ScrollArea>
  );
}

export function Horizontal() {
  return (
    <ScrollArea className="w-full max-w-96 rounded-panel border border-line-subtle whitespace-nowrap">
      <div className="flex w-max gap-3 p-3">
        {["Hermes", "Openclaw", "Codex", "Claude Code", "OpenCode", "Other", "Cursor", "Windsurf"].map((name) => (
          <span key={name} className="flex h-9 items-center rounded-pill bg-subtle px-3 text-body text-fg">
            {name}
          </span>
        ))}
      </div>
      <ScrollBar orientation="horizontal" />
    </ScrollArea>
  );
}

```

## Source

components/ui/scroll-area.tsx

```tsx
"use client";

import * as React from "react";
import { ScrollArea as ChakraScrollArea } from "@chakra-ui/react";

import { cn } from "@/lib/utils";

// A region that scrolls inside the page (the email list, a long event catalog) with the console's thin bar: a 6px
// thumb in the field's lilac-gray on a clear track, darkening under the pointer.
function ScrollArea({ className, children, ...props }: React.ComponentProps<typeof ChakraScrollArea.Root>) {
  return (
    <ChakraScrollArea.Root data-slot="scroll-area" className={cn("relative overflow-hidden", className)} {...props}>
      <ChakraScrollArea.Viewport data-slot="scroll-area-viewport" className="size-full rounded-[inherit] outline-none focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus-ring">
        {children}
      </ChakraScrollArea.Viewport>
      <ScrollBar />
      <ChakraScrollArea.Corner />
    </ChakraScrollArea.Root>
  );
}

function ScrollBar({ className, orientation = "vertical", ...props }: React.ComponentProps<typeof ChakraScrollArea.Scrollbar>) {
  return (
    <ChakraScrollArea.Scrollbar
      data-slot="scroll-area-scrollbar"
      orientation={orientation}
      className={cn("flex touch-none p-0.5 select-none", orientation === "vertical" && "h-full w-2.5", orientation === "horizontal" && "h-2.5 flex-col", className)}
      {...props}
    >
      <ChakraScrollArea.Thumb data-slot="scroll-area-thumb" className="relative flex-1 rounded-pill bg-line-field transition-colors duration-150 ease-out hover:bg-line-strong motion-reduce:transition-none" />
    </ChakraScrollArea.Scrollbar>
  );
}

export { ScrollArea, ScrollBar };

```

# Select
A white 40px field with the Shadow/S ring and an ink caret that opens the console's white menu.

Install: npx inkbox-ds add select
Requires: theme, surface, utils
Packages: radix-ui, @phosphor-icons/react
Exports: Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue
Client boundary: yes
Reference: Figma 427:2715: Any State and Shared in Create Agent Identity (Modal States); the list is extrapolated as the console's menu


## Usage
Use to choose one value from a list of five or more (Any State for a phone number, Shared or Dedicated for an iMessage line). Give it a Label or an aria-label, a placeholder when nothing is chosen, and group long lists with SelectGroup and SelectLabel. Control it with value and onValueChange (values are non-empty strings), and give the root a name so a form submits the value with FormData.
- Avoid: A field edge instead of the Shadow/S ring
- Avoid: A dark or purple list
- Avoid: Checkmarks at the left of the items
- Avoid: Animating items as they are highlighted


## Examples
Example components: npx inkbox-ds add select button label
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/select/Preview) | [WithIcons](https://inkbox-ds.vercel.app/preview/select/WithIcons) | [States](https://inkbox-ds.vercel.app/preview/select/States)

examples/select.tsx

```tsx
"use client";

import * as React from "react";
import { EnvelopeSimpleIcon, PhoneIcon, ChatCircleIcon } from "@phosphor-icons/react/ssr";

import { Button } from "@/components/ui/button";
import { Label } from "@/components/ui/label";
import { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, SelectValue } from "@/components/ui/select";

export function Preview() {
  const [state, setState] = React.useState("any");
  const [saved, setSaved] = React.useState<string>();
  return (
    <form
      className="grid w-full max-w-114.5 gap-1"
      onSubmit={(event) => {
        event.preventDefault();
        setSaved(String(new FormData(event.currentTarget).get("state")));
      }}
    >
      <Label htmlFor="any-state">Phone number state</Label>
      <Select name="state" value={state} onValueChange={setState}>
        <SelectTrigger id="any-state">
          <SelectValue placeholder="Choose a state" />
        </SelectTrigger>
        <SelectContent>
          <SelectItem value="any">Any State</SelectItem>
          <SelectSeparator />
          <SelectGroup>
            <SelectLabel>West</SelectLabel>
            <SelectItem value="ca">California</SelectItem>
            <SelectItem value="or">Oregon</SelectItem>
            <SelectItem value="wa">Washington</SelectItem>
          </SelectGroup>
          <SelectGroup>
            <SelectLabel>East</SelectLabel>
            <SelectItem value="ny">New York</SelectItem>
            <SelectItem value="ma">Massachusetts</SelectItem>
            <SelectItem value="fl" disabled>
              Florida (no numbers left)
            </SelectItem>
          </SelectGroup>
        </SelectContent>
      </Select>
      <div className="mt-3 flex items-center gap-3">
        <Button type="submit">Save</Button>
        <p aria-live="polite" className="text-body text-fg-muted">
          {saved ? `Saved: ${saved}` : ""}
        </p>
      </div>
    </form>
  );
}

export function WithIcons() {
  return (
    <Select defaultValue="email">
      <SelectTrigger aria-label="Channel" className="w-60">
        <SelectValue />
      </SelectTrigger>
      <SelectContent>
        <SelectItem value="email">
          <EnvelopeSimpleIcon weight="fill" /> Email
        </SelectItem>
        <SelectItem value="phone">
          <PhoneIcon weight="fill" /> Phone
        </SelectItem>
        <SelectItem value="imessage">
          <ChatCircleIcon weight="fill" /> iMessage
        </SelectItem>
      </SelectContent>
    </Select>
  );
}

export function States() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Select>
        <SelectTrigger aria-label="Line" size="sm" className="w-44">
          <SelectValue placeholder="Choose a line" />
        </SelectTrigger>
        <SelectContent>
          <SelectItem value="shared">Shared</SelectItem>
          <SelectItem value="dedicated">Dedicated</SelectItem>
        </SelectContent>
      </Select>
      <Select defaultValue="shared" disabled>
        <SelectTrigger aria-label="Disabled" className="w-44">
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          <SelectItem value="shared">Shared</SelectItem>
        </SelectContent>
      </Select>
      <Select>
        <SelectTrigger aria-label="Invalid" aria-invalid className="w-44">
          <SelectValue placeholder="Required" />
        </SelectTrigger>
        <SelectContent>
          <SelectItem value="edge">Edge</SelectItem>
        </SelectContent>
      </Select>
    </div>
  );
}

```

## Source

components/ui/select.tsx

```tsx
"use client";

import * as React from "react";
import { Select as SelectPrimitive } from "radix-ui";
import { CaretDownIcon, CaretUpIcon, CheckIcon } from "@phosphor-icons/react/ssr";

import { usePortalContainer } from "@/lib/surface";
import { cn } from "@/lib/utils";

// The console's select (Figma 427:2715, Create Agent Identity: "Any State" under Phone Number, "Shared" under
// iMessage): a white 40px field with fully rounded corners and the Shadow/S ring instead of an edge, the value in 14px ink 14px
// in, a 16px bold caret 12px from the right; the placeholder is the light purple. `size="sm"` is 36px. The list is the
// console's menu: white, 16px corners, the floating shadow, 4px inside; 36px rows with fully rounded corners, 14px ink, the
// highlighted row on the lilac and a purple check at the right of the chosen one. It opens and closes with a subtle 150ms fade.
function Select(props: React.ComponentProps<typeof SelectPrimitive.Root>) {
  return <SelectPrimitive.Root data-slot="select" {...props} />;
}

function SelectGroup({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.Group>) {
  return <SelectPrimitive.Group data-slot="select-group" className={cn("scroll-my-1", className)} {...props} />;
}

function SelectValue(props: React.ComponentProps<typeof SelectPrimitive.Value>) {
  return <SelectPrimitive.Value data-slot="select-value" {...props} />;
}

function SelectTrigger({ className, size = "default", children, ...props }: React.ComponentProps<typeof SelectPrimitive.Trigger> & { size?: "sm" | "default" }) {
  return (
    <SelectPrimitive.Trigger
      data-slot="select-trigger"
      data-size={size}
      className={cn(
        "flex w-full min-w-0 cursor-pointer items-center justify-between gap-2 rounded-pill bg-surface pr-3 pl-3.5 font-sans text-body leading-tight whitespace-nowrap text-fg shadow-s outline-none transition-[box-shadow] duration-150 ease-out focus-visible:shadow-[var(--ds-shadow-s),var(--ds-shadow-focus)] disabled:cursor-not-allowed disabled:bg-subtle disabled:text-fg-muted aria-invalid:shadow-[0_0_0_1px_var(--ds-color-status-danger)] data-placeholder:text-fg-subtle data-[size=default]:h-10 data-[size=sm]:h-9 motion-reduce:transition-none *:data-[slot=select-value]:flex *:data-[slot=select-value]:min-w-0 *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-2 *:data-[slot=select-value]:truncate [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-5.5",
        className,
      )}
      {...props}
    >
      {children}
      <SelectPrimitive.Icon asChild>
        <CaretDownIcon weight="bold" className="size-4 text-fg" />
      </SelectPrimitive.Icon>
    </SelectPrimitive.Trigger>
  );
}

function SelectContent({ className, children, position = "popper", align = "center", ...props }: React.ComponentProps<typeof SelectPrimitive.Content>) {
  const container = usePortalContainer();
  return (
    <SelectPrimitive.Portal container={container}>
      <SelectPrimitive.Content
        data-slot="select-content"
        className={cn(
          "relative z-50 max-h-(--radix-select-content-available-height) min-w-36 origin-(--radix-select-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-panel bg-surface text-fg shadow-floating data-[state=closed]:animate-fade-out data-[state=open]:animate-fade-in",
          position === "popper" && "w-full min-w-(--radix-select-trigger-width) data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1",
          className,
        )}
        position={position}
        align={align}
        {...props}
      >
        <SelectScrollUpButton />
        <SelectPrimitive.Viewport data-position={position} className={cn("p-1", position === "popper" && "h-(--radix-select-trigger-height) w-full min-w-(--radix-select-trigger-width) scroll-my-1")}>
          {children}
        </SelectPrimitive.Viewport>
        <SelectScrollDownButton />
      </SelectPrimitive.Content>
    </SelectPrimitive.Portal>
  );
}

function SelectLabel({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.Label>) {
  return <SelectPrimitive.Label data-slot="select-label" className={cn("px-2.5 pt-2 pb-1 text-body-sm leading-tight text-fg-label", className)} {...props} />;
}

function SelectItem({ className, children, ...props }: React.ComponentProps<typeof SelectPrimitive.Item>) {
  return (
    <SelectPrimitive.Item
      data-slot="select-item"
      className={cn(
        "relative flex h-9 w-full cursor-default items-center gap-2.5 rounded-pill pr-9 pl-2.5 font-sans text-body leading-tight text-fg outline-none select-none data-disabled:pointer-events-none data-disabled:text-fg-faint data-highlighted:bg-subtle [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-5.5 [&_svg:not([class*='text-'])]:text-icon-secondary *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2.5",
        className,
      )}
      {...props}
    >
      <span data-slot="select-item-indicator" className="absolute right-2.5 flex size-4 items-center justify-center">
        <SelectPrimitive.ItemIndicator>
          <CheckIcon weight="bold" className="size-4 text-fg-brand" />
        </SelectPrimitive.ItemIndicator>
      </span>
      <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
    </SelectPrimitive.Item>
  );
}

function SelectSeparator({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.Separator>) {
  return <SelectPrimitive.Separator data-slot="select-separator" className={cn("pointer-events-none -mx-1 my-1 h-px bg-line-subtle", className)} {...props} />;
}

function SelectScrollUpButton({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.ScrollUpButton>) {
  return (
    <SelectPrimitive.ScrollUpButton data-slot="select-scroll-up-button" className={cn("flex h-6 cursor-default items-center justify-center bg-surface text-fg-muted", className)} {...props}>
      <CaretUpIcon weight="bold" className="size-3.5" />
    </SelectPrimitive.ScrollUpButton>
  );
}

function SelectScrollDownButton({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.ScrollDownButton>) {
  return (
    <SelectPrimitive.ScrollDownButton data-slot="select-scroll-down-button" className={cn("flex h-6 cursor-default items-center justify-center bg-surface text-fg-muted", className)} {...props}>
      <CaretDownIcon weight="bold" className="size-3.5" />
    </SelectPrimitive.ScrollDownButton>
  );
}

export { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue };

```

# Separator
A 1px rule in the faint lilac, across or down.

Install: npx inkbox-ds add separator
Requires: theme, utils
Packages: @chakra-ui/react
Exports: Separator
Client boundary: yes
Reference: Figma 427:2715: the rail's footer rule, page head rules, inbox list dividers


## Usage
Use between groups: under a page head, above the rail's footer, between list rows, between toolbar groups (orientation="vertical"). It is decorative unless you set decorative={false}.
- Avoid: Darker rules than the faint lilac between rows
- Avoid: Double rules
- Avoid: Rules inside a lilac panel


## Examples
Example components: npx inkbox-ds add separator
[Preview](https://inkbox-ds.vercel.app/preview/separator/Preview)

examples/separator.tsx

```tsx
import { Separator } from "@/components/ui/separator";

export function Preview() {
  return (
    <div className="w-full max-w-96">
      <p className="text-body text-fg">Webhooks</p>
      <p className="text-body text-fg-muted">Manage subscriptions and review payloads.</p>
      <Separator className="my-4" />
      <div className="flex h-5 items-center gap-4 text-body whitespace-nowrap text-fg">
        <span>Mailboxes</span>
        <Separator orientation="vertical" />
        <span>Contact rules</span>
        <Separator orientation="vertical" />
        <span>Custom domains</span>
      </div>
    </div>
  );
}

```

## Source

components/ui/separator.tsx

```tsx
"use client";

import * as React from "react";
import { Separator as ChakraSeparator } from "@chakra-ui/react";

import { cn } from "@/lib/utils";

// The console's rules: a 1px line in the faint lilac (#F3F1F5) under a page head, at the rail's edge, between list
// items and above the rail's footer. Decorative by default.
function Separator({ className, orientation = "horizontal", decorative = true, ...props }: Omit<React.ComponentProps<typeof ChakraSeparator>, "orientation"> & { orientation?: "horizontal" | "vertical"; decorative?: boolean }) {
  return (
    <ChakraSeparator
      unstyled
      data-slot="separator"
      aria-hidden={decorative || undefined}
      orientation={orientation}
      className={cn("shrink-0 bg-line-subtle data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-px", className)}
      {...props}
    />
  );
}

export { Separator };

```

# Sheet
A white panel that slides from an edge over the blurred, ink-tinted page, with the dialog's title and close glyph.

Install: npx inkbox-ds add sheet
Requires: theme, surface, utils
Packages: radix-ui, @phosphor-icons/react
Exports: Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): Modal - Create Agent (panel, title, close glyph, scrim)


## Usage
Use for a task beside the page that keeps its context, such as editing a mailbox or reading a call's details. Use side="right" by default and side="left" for the rail on phones. Put the title in SheetHeader and the main action in SheetFooter.
- Avoid: A sheet that opens another sheet
- Avoid: A dark scrim
- Avoid: A sheet for a short confirmation (use Alert Dialog)


## Examples
Example components: npx inkbox-ds add sheet button input label
[Preview](https://inkbox-ds.vercel.app/preview/sheet/Preview) | [Sides](https://inkbox-ds.vercel.app/preview/sheet/Sides) | [Open](https://inkbox-ds.vercel.app/preview/sheet/Open)

examples/sheet.tsx

```tsx
"use client";

import * as React from "react";

import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
import { Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger } from "@/components/ui/sheet";

function EditMailbox() {
  return (
    <>
      <SheetHeader>
        <SheetTitle>Edit mailbox</SheetTitle>
        <SheetDescription>Mailboxes are provisioned and deleted with their owning identity.</SheetDescription>
      </SheetHeader>
      <div className="grid gap-4 px-6">
        <div className="grid gap-1">
          <Label htmlFor="sheet-name">Display name</Label>
          <Input id="sheet-name" defaultValue="Acme support" />
        </div>
        <div className="grid gap-1">
          <Label htmlFor="sheet-reply">Reply-to address</Label>
          <Input id="sheet-reply" type="email" placeholder="support@acme.com" />
        </div>
      </div>
      <SheetFooter>
        <Button>Save changes</Button>
        <SheetClose asChild>
          <Button variant="secondary">Cancel</Button>
        </SheetClose>
      </SheetFooter>
    </>
  );
}

export function Preview() {
  return (
    <div className="flex justify-center">
      <Sheet>
        <SheetTrigger asChild>
          <Button variant="outline">Edit mailbox</Button>
        </SheetTrigger>
        <SheetContent>
          <EditMailbox />
        </SheetContent>
      </Sheet>
    </div>
  );
}

export function Sides() {
  const sides = ["top", "right", "bottom", "left"] as const;
  return (
    <div className="flex flex-wrap justify-center gap-3">
      {sides.map((side) => (
        <Sheet key={side}>
          <SheetTrigger asChild>
            <Button variant="outline" className="capitalize">
              {side}
            </Button>
          </SheetTrigger>
          <SheetContent side={side}>
            <SheetHeader>
              <SheetTitle>Sheet from the {side}</SheetTitle>
              <SheetDescription>Slides from its edge on the drawer curve.</SheetDescription>
            </SheetHeader>
          </SheetContent>
        </Sheet>
      ))}
    </div>
  );
}

export function Open() {
  return (
    <div className="min-h-120">
      <Sheet defaultOpen>
        <SheetContent>
          <EditMailbox />
        </SheetContent>
      </Sheet>
    </div>
  );
}

```

## Source

components/ui/sheet.tsx

```tsx
"use client";

import * as React from "react";
import { Dialog as SheetPrimitive } from "radix-ui";
import { XIcon } from "@phosphor-icons/react/ssr";

import { usePortalContainer } from "@/lib/surface";
import { cn } from "@/lib/utils";

// A panel from the edge of the screen, drawn as the console's dialog (Figma 427:2715: Create Agent Identity): white
// over the blurred, ink-tinted page, a 20px regular title 24px in, a faint 20px close glyph and the same 24px sides. It
// travels its own size from its edge on the drawer curve (300ms in, 200ms out); its inner corner takes the dialog's
// 16px. Side panels are 384px wide (the full width on phones); top and bottom panels take their content's height.
function Sheet(props: React.ComponentProps<typeof SheetPrimitive.Root>) {
  return <SheetPrimitive.Root data-slot="sheet" {...props} />;
}

function SheetTrigger(props: React.ComponentProps<typeof SheetPrimitive.Trigger>) {
  return <SheetPrimitive.Trigger data-slot="sheet-trigger" {...props} />;
}

function SheetClose(props: React.ComponentProps<typeof SheetPrimitive.Close>) {
  return <SheetPrimitive.Close data-slot="sheet-close" {...props} />;
}

function SheetPortal(props: React.ComponentProps<typeof SheetPrimitive.Portal>) {
  const container = usePortalContainer();
  return <SheetPrimitive.Portal data-slot="sheet-portal" container={container} {...props} />;
}

function SheetOverlay({ className, ...props }: React.ComponentProps<typeof SheetPrimitive.Overlay>) {
  return (
    <SheetPrimitive.Overlay
      data-slot="sheet-overlay"
      className={cn("fixed inset-0 z-50 bg-scrim backdrop-blur-[var(--ds-blur-scrim)] data-[state=closed]:animate-fade-out data-[state=open]:animate-fade-in", className)}
      {...props}
    />
  );
}

const SIDES = {
  right: "inset-y-0 right-0 h-full w-full rounded-l-panel sm:max-w-96 data-[state=closed]:animate-sheet-out-right data-[state=open]:animate-sheet-in-right",
  left: "inset-y-0 left-0 h-full w-full rounded-r-panel sm:max-w-96 data-[state=closed]:animate-sheet-out-left data-[state=open]:animate-sheet-in-left",
  top: "inset-x-0 top-0 h-auto max-h-[85dvh] rounded-b-panel data-[state=closed]:animate-sheet-out-top data-[state=open]:animate-sheet-in-top",
  bottom: "inset-x-0 bottom-0 h-auto max-h-[85dvh] rounded-t-panel data-[state=closed]:animate-sheet-out-bottom data-[state=open]:animate-sheet-in-bottom",
} as const;

function SheetContent({ className, children, side = "right", showCloseButton = true, instant = false, ...props }: React.ComponentProps<typeof SheetPrimitive.Content> & { side?: keyof typeof SIDES; showCloseButton?: boolean; instant?: boolean }) {
  return (
    <SheetPortal>
      <SheetOverlay data-ds-motion={instant ? "instant" : undefined} />
      <SheetPrimitive.Content
        data-slot="sheet-content"
        data-ds-motion={instant ? "instant" : undefined}
        data-side={side}
        className={cn("fixed z-50 flex flex-col overflow-y-auto bg-surface text-fg shadow-dialog outline-none", SIDES[side], className)}
        {...props}
      >
        {children}
        {showCloseButton && (
          <SheetPrimitive.Close
            data-slot="sheet-close"
            className="absolute top-5 right-5 inline-flex size-7 items-center justify-center rounded-pill text-fg-faint outline-none active:brightness-95 active:transition-none transition-colors duration-150 ease-out hover:text-fg-muted focus-visible:outline-2 focus-visible:outline-focus-ring motion-reduce:transition-none"
          >
            <XIcon className="size-5.5" />
            <span className="sr-only">Close</span>
          </SheetPrimitive.Close>
        )}
      </SheetPrimitive.Content>
    </SheetPortal>
  );
}

function SheetHeader({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="sheet-header" className={cn("flex min-h-17 shrink-0 flex-col justify-center gap-1 py-5 pr-14 pl-6", className)} {...props} />;
}

function SheetFooter({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="sheet-footer" className={cn("mt-auto flex shrink-0 flex-col gap-3 p-6", className)} {...props} />;
}

function SheetTitle({ className, ...props }: React.ComponentProps<typeof SheetPrimitive.Title>) {
  return <SheetPrimitive.Title data-slot="sheet-title" className={cn("font-sans text-h3 leading-heading font-normal text-fg", className)} {...props} />;
}

function SheetDescription({ className, ...props }: React.ComponentProps<typeof SheetPrimitive.Description>) {
  return <SheetPrimitive.Description data-slot="sheet-description" className={cn("text-body leading-body text-fg-secondary", className)} {...props} />;
}

export { Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger };

```

# Sidebar
The console's rail: 288px of white with a hairline edge, the lockup, 38px rows with filled glyphs, purple group labels and a ruled foot; the lilac second rail for an agent's workspace.

Install: npx inkbox-ds add sidebar
Requires: theme, button, input, separator, sheet, skeleton, tooltip, utils
Packages: @chakra-ui/react, class-variance-authority, @phosphor-icons/react
Exports: Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, useSidebar
Client boundary: yes
Reference: Figma 427:2715: the rail in Dashboard - empty state and every console screen; the second rail in Agent Workspace - Inbox


## Usage
Use for an app's main navigation. Wrap the app in SidebarProvider; put the lockup in SidebarHeader, groups of SidebarMenuButton rows (isActive on the current page, a filled Phosphor glyph first) in SidebarContent, and Help, the organization (SidebarMenuBadge with ADMIN) and the account in SidebarFooter; the page goes in SidebarInset. Use variant secondary for a second rail beside it (an agent's workspace), collapsible icon to let it narrow to its glyphs (rows then show their tooltip), and SidebarTrigger or Cmd B to toggle. On phones it opens in a sheet.
- Avoid: A dark or purple rail
- Avoid: Line glyphs in the rows
- Avoid: Bold or purple row labels
- Avoid: A purple pill for the current row
- Avoid: Animating the rail when the keyboard shortcut toggles it


## Examples
Example components: npx inkbox-ds add sidebar avatar badge
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/sidebar/Preview) | [Icons](https://inkbox-ds.vercel.app/preview/sidebar/Icons) | [SecondRail](https://inkbox-ds.vercel.app/preview/sidebar/SecondRail) | [Loading](https://inkbox-ds.vercel.app/preview/sidebar/Loading)

examples/sidebar.tsx

```tsx
"use client";

import * as React from "react";
import {
  AppleLogoIcon,
  ArrowsClockwiseIcon,
  ArrowsLeftRightIcon,
  BuildingOfficeIcon,
  CaretDownIcon,
  ChatTextIcon,
  CirclesThreeIcon,
  EnvelopeSimpleIcon,
  KeyIcon,
  NotepadIcon,
  PaperPlaneTiltIcon,
  PhoneIcon,
  ProhibitIcon,
  QuestionIcon,
  RobotIcon,
  SidebarSimpleIcon,
  SlidersHorizontalIcon,
  TerminalWindowIcon,
  TrayIcon,
  UsersIcon,
  VaultIcon,
  WarningIcon,
  WebhooksLogoIcon,
} from "@phosphor-icons/react/ssr";

import { Avatar, AvatarFallback } from "@/components/ui/avatar";
import { Badge } from "@/components/ui/badge";
import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupAction,
  SidebarGroupContent,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarInset,
  SidebarMenu,
  SidebarMenuBadge,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarMenuSkeleton,
  SidebarProvider,
  SidebarRail,
  SidebarTrigger,
  useSidebar,
} from "@/components/ui/sidebar";

type Row = { title: string; icon: React.ComponentType<{ weight?: "fill" | "regular"; className?: string }>; weight?: "fill" | "regular"; beta?: boolean };

const TOP: Row[] = [
  { title: "Agent Workspace", icon: RobotIcon },
  { title: "Manage Agents", icon: CirclesThreeIcon },
  { title: "API Keys", icon: KeyIcon },
];
const CHANNELS: Row[] = [
  { title: "Email", icon: EnvelopeSimpleIcon },
  { title: "Phone", icon: PhoneIcon },
  { title: "iMessage", icon: AppleLogoIcon },
  { title: "Agent2Agent", icon: ArrowsLeftRightIcon, weight: "regular", beta: true },
];
const SHARED: Row[] = [
  { title: "Contacts", icon: UsersIcon },
  { title: "Notes", icon: NotepadIcon },
  { title: "Vault", icon: VaultIcon },
  { title: "Webhooks", icon: WebhooksLogoIcon, weight: "regular" },
];

function Rows({ rows, current, onSelect }: { rows: Row[]; current: string; onSelect: (title: string) => void }) {
  return (
    <SidebarMenu>
      {rows.map(({ title, icon: Icon, weight = "fill", beta }) => (
        <SidebarMenuItem key={title}>
          <SidebarMenuButton isActive={current === title} tooltip={title} onClick={() => onSelect(title)}>
            <Icon weight={weight} />
            <span>{title}</span>
            {beta && (
              <Badge variant="pink" className="ml-px">
                BETA
              </Badge>
            )}
          </SidebarMenuButton>
        </SidebarMenuItem>
      ))}
    </SidebarMenu>
  );
}

function Lockup() {
  return (
    <div className="flex h-6 items-center gap-1.5 px-1">
      {/* eslint-disable-next-line @next/next/no-img-element */}
      <img src="/logo-mark.png" alt="" width={28} height={28} className="size-7 shrink-0" />
      <svg viewBox="0 0 81.7305 18.6738" role="img" aria-label="Inkbox" fill="currentColor" className="h-4.5 w-auto text-ink group-data-[collapsible=icon]/sidebar:hidden">
        <path d="M41.5693 6.50098C41.8857 6.15243 42.2423 5.86128 42.6406 5.62695C43.4871 5.1291 44.4744 4.87988 45.6035 4.87988C46.8644 4.87993 47.9964 5.1613 49.001 5.72656C50.0057 6.29043 50.8028 7.08757 51.3916 8.11719C51.9801 9.1466 52.2763 10.3825 52.2764 11.7764C52.2764 13.1706 51.9803 14.3825 51.3916 15.4121C50.8029 16.4402 50.0056 17.2408 49.001 17.8135C47.9964 18.3861 46.8644 18.6738 45.6035 18.6738C44.4245 18.6738 43.412 18.4247 42.5654 17.9268C42.1202 17.6646 41.7294 17.329 41.3955 16.9219V18.4746H37.6855V0H41.5693V6.50098ZM60.8281 4.88184C62.2559 4.88189 63.5008 5.17593 64.6123 5.76465C65.7239 6.35342 66.5953 7.16375 67.2266 8.19336C67.8577 9.22291 68.1729 10.4178 68.1729 11.7783C68.1729 13.1388 67.8577 14.2883 67.2266 15.3252C66.5953 16.3621 65.7239 17.1813 64.6123 17.7773C63.5008 18.3748 62.2384 18.6738 60.8281 18.6738C59.4002 18.6738 58.1345 18.3748 57.0303 17.7773C55.926 17.1798 55.0546 16.3621 54.416 15.3252C53.7775 14.2883 53.458 13.1052 53.458 11.7783C53.458 10.4515 53.7775 9.24345 54.416 8.20508C55.0546 7.16814 55.926 6.35342 57.0303 5.76465C58.1345 5.17595 59.4002 4.88184 60.8281 4.88184ZM4.0332 18.4746H0V1.0459H4.0332V18.4746ZM14.3066 4.87988C15.3683 4.87994 16.3186 5.09144 17.1562 5.51465C17.9954 5.93791 18.6549 6.58469 19.1367 7.45605C19.6171 8.32746 19.8584 9.44366 19.8584 10.8057V18.4746H15.9746V11.4033C15.9746 10.3239 15.7367 9.52676 15.2637 9.0127C14.7907 8.4975 14.123 8.24127 13.2607 8.24121C12.6471 8.24121 12.0942 8.37065 11.6035 8.62695C11.1147 8.88467 10.7327 9.27832 10.459 9.80957C10.1851 10.3398 10.0488 11.0211 10.0488 11.8516V18.4746H6.16406V5.0791H9.87402V6.6709C10.2577 6.2418 10.7154 5.88666 11.2441 5.60254C12.1404 5.12074 13.1614 4.87988 14.3066 4.87988ZM25.5254 10.4619L31.2021 5.0791H35.833L30.2539 10.75L36.3311 18.4746H31.625L27.4014 13.2295L25.5254 15.0752V18.4746H21.6406V0H25.5254V10.4619ZM74.4883 8.99121L77.3984 5.0791H81.5312L76.5488 11.6309L81.7305 18.4746H77.3223L74.3896 14.3721L71.3477 18.4746H67.1152L72.2676 11.7188L67.2891 5.0791H71.6465L74.4883 8.99121ZM44.9307 8.06738C44.2835 8.06742 43.7025 8.21694 43.1885 8.51562C42.6729 8.8144 42.2666 9.2374 41.9678 9.78516C41.6691 10.3328 41.5196 11.0136 41.5195 11.7764C41.5195 12.5394 41.669 13.2008 41.9678 13.7559C42.2665 14.3123 42.673 14.7393 43.1885 15.0381C43.7025 15.3368 44.2835 15.4863 44.9307 15.4863C45.578 15.4863 46.1534 15.3368 46.6602 15.0381C47.1669 14.7393 47.5733 14.3123 47.8809 13.7559C48.1884 13.2008 48.3418 12.557 48.3418 11.7764C48.3417 10.9961 48.1883 10.3328 47.8809 9.78516C47.5733 9.2374 47.1669 8.8144 46.6602 8.51562C46.1534 8.2169 45.578 8.06738 44.9307 8.06738ZM60.8281 8.06543C60.1808 8.06543 59.599 8.21493 59.085 8.51367C58.5709 8.81241 58.1591 9.23554 57.8516 9.7832C57.544 10.331 57.3906 10.9948 57.3906 11.7754C57.3906 12.556 57.544 13.1993 57.8516 13.7559C58.1591 14.3123 58.5695 14.7379 59.085 15.0381C59.599 15.3369 60.1808 15.4863 60.8281 15.4863C61.4753 15.4863 62.0564 15.3368 62.5703 15.0381C63.0844 14.7393 63.4922 14.3124 63.791 13.7559C64.0898 13.1993 64.2393 12.5399 64.2393 11.7754C64.2393 11.0109 64.0898 10.331 63.791 9.7832C63.4922 9.23548 63.0844 8.81243 62.5703 8.51367C62.0564 8.21505 61.4752 8.06549 60.8281 8.06543Z" />
      </svg>
    </div>
  );
}

function CollapseRow() {
  const { toggleSidebar, state } = useSidebar();
  return (
    <SidebarMenuItem>
      <SidebarMenuButton tooltip="Expand" onClick={toggleSidebar} aria-expanded={state === "expanded"}>
        <SidebarSimpleIcon weight="fill" />
        <span>{state === "expanded" ? "Collapse" : "Expand"}</span>
      </SidebarMenuButton>
    </SidebarMenuItem>
  );
}

function ConsoleRail({ collapsible = "offcanvas" }: { collapsible?: "offcanvas" | "icon" | "none" }) {
  const [current, setCurrent] = React.useState("Agent Workspace");
  return (
    <Sidebar collapsible={collapsible}>
      <SidebarHeader className="px-4 py-5">
        <Lockup />
      </SidebarHeader>
      <SidebarContent>
        <SidebarGroup>
          <Rows rows={TOP} current={current} onSelect={setCurrent} />
        </SidebarGroup>
        <SidebarGroup>
          <SidebarGroupLabel>Channels</SidebarGroupLabel>
          <SidebarGroupContent>
            <Rows rows={CHANNELS} current={current} onSelect={setCurrent} />
          </SidebarGroupContent>
        </SidebarGroup>
        <SidebarGroup>
          <SidebarGroupLabel>Shared</SidebarGroupLabel>
          <SidebarGroupContent>
            <Rows rows={SHARED} current={current} onSelect={setCurrent} />
          </SidebarGroupContent>
        </SidebarGroup>
      </SidebarContent>
      <SidebarFooter>
        <SidebarMenu>
          <SidebarMenuItem>
            <SidebarMenuButton tooltip="Help">
              <QuestionIcon weight="fill" />
              <span>Help</span>
            </SidebarMenuButton>
          </SidebarMenuItem>
          <SidebarMenuItem>
            <SidebarMenuButton tooltip="My Organisation">
              <BuildingOfficeIcon weight="fill" />
              <span>My Organisation</span>
            </SidebarMenuButton>
            <SidebarMenuBadge>ADMIN</SidebarMenuBadge>
          </SidebarMenuItem>
          <SidebarMenuItem>
            <SidebarMenuButton tooltip="Robert Ligthart">
              <Avatar size="sm" className="m-px size-5">
                <AvatarFallback className="text-body-sm">R</AvatarFallback>
              </Avatar>
              <span className="ml-0.5">Robert Ligthart</span>
            </SidebarMenuButton>
          </SidebarMenuItem>
          {collapsible === "icon" && <CollapseRow />}
          {collapsible !== "icon" && (
            <SidebarMenuItem>
              <SidebarMenuButton>
                <SidebarSimpleIcon weight="fill" />
                <span>Collapse</span>
              </SidebarMenuButton>
            </SidebarMenuItem>
          )}
        </SidebarMenu>
      </SidebarFooter>
      <SidebarRail />
    </Sidebar>
  );
}

function PageHead({ title, description }: { title: string; description: string }) {
  return (
    <header className="flex items-start gap-3 border-b border-line-subtle px-6 py-4">
      <SidebarTrigger className="-ml-2 md:hidden" />
      <div>
        <h1 className="text-h3 leading-heading font-normal text-fg">{title}</h1>
        <p className="text-body text-fg-muted">{description}</p>
      </div>
    </header>
  );
}

export function Preview() {
  return (
    <SidebarProvider className="h-270 min-h-0 overflow-hidden rounded-panel border border-line-subtle">
      <ConsoleRail />
      <SidebarInset>
        <PageHead title="Vault" description="Zero-knowledge encrypted secret store for your agents." />
      </SidebarInset>
    </SidebarProvider>
  );
}

export function Icons() {
  return (
    <SidebarProvider defaultOpen={false} className="h-270 min-h-0 overflow-hidden rounded-panel border border-line-subtle">
      <ConsoleRail collapsible="icon" />
      <SidebarInset>
        <PageHead title="Agent Workspace" description="Press Cmd B, or Collapse, to switch between the full rail and its glyphs." />
      </SidebarInset>
    </SidebarProvider>
  );
}

const WORKSPACE: { label: string; action?: boolean; rows: Row[] }[] = [
  { label: "Email", action: true, rows: [{ title: "Inkbox", icon: TrayIcon }, { title: "Sent", icon: PaperPlaneTiltIcon }, { title: "Spam", icon: WarningIcon }, { title: "Blocked", icon: ProhibitIcon, weight: "regular" }] },
  { label: "Phone", rows: [{ title: "Calls", icon: PhoneIcon }, { title: "Texts", icon: ChatTextIcon }, { title: "iMessage ", icon: AppleLogoIcon }, { title: "Blocked ", icon: ProhibitIcon, weight: "regular" }] },
  { label: "Agent2Agent", action: true, rows: [{ title: "Sessions", icon: ArrowsClockwiseIcon, weight: "regular" }] },
  { label: "Tunnel", rows: [{ title: "Tunnel", icon: ArrowsLeftRightIcon, weight: "regular" }] },
  { label: "Other", rows: [{ title: "Contacts", icon: UsersIcon }, { title: "Notes", icon: NotepadIcon }, { title: "Vault", icon: VaultIcon }] },
];

export function SecondRail() {
  const [current, setCurrent] = React.useState("Inkbox");
  return (
    <SidebarProvider className="h-270 min-h-0 overflow-hidden rounded-panel border border-line-subtle">
      <Sidebar variant="secondary" collapsible="none">
        <SidebarHeader>
          <SidebarMenu>
            <SidebarMenuItem>
              <SidebarMenuButton aria-haspopup="menu">
                <Avatar size="sm" className="m-px size-5">
                  <AvatarFallback className="text-body-sm">A</AvatarFallback>
                </Avatar>
                <span className="ml-0.5 flex-1">@acme</span>
                <CaretDownIcon weight="bold" className="size-4 text-fg" />
              </SidebarMenuButton>
            </SidebarMenuItem>
          </SidebarMenu>
        </SidebarHeader>
        <SidebarContent>
          <SidebarGroup>
            <Rows rows={[{ title: "Quickstart", icon: TerminalWindowIcon }]} current={current} onSelect={setCurrent} />
          </SidebarGroup>
          {WORKSPACE.map((group) => (
            <SidebarGroup key={group.label}>
              <SidebarGroupLabel>{group.label}</SidebarGroupLabel>
              {group.action && (
                <SidebarGroupAction aria-label={`${group.label} settings`}>
                  <SlidersHorizontalIcon weight="fill" />
                </SidebarGroupAction>
              )}
              <SidebarGroupContent>
                <Rows rows={group.rows} current={current} onSelect={setCurrent} />
              </SidebarGroupContent>
            </SidebarGroup>
          ))}
        </SidebarContent>
      </Sidebar>
      <SidebarInset>
        <PageHead title="Inbox" description="acme@inkboxmail.com" />
      </SidebarInset>
    </SidebarProvider>
  );
}

export function Loading() {
  return (
    <SidebarProvider className="h-120 min-h-0 overflow-hidden rounded-panel border border-line-subtle">
      <Sidebar collapsible="none">
        <SidebarHeader className="px-4 py-5">
          <Lockup />
        </SidebarHeader>
        <SidebarContent>
          <SidebarGroup>
            <SidebarGroupLabel>Channels</SidebarGroupLabel>
            <SidebarMenu>
              {Array.from({ length: 5 }, (_, i) => (
                <SidebarMenuItem key={i}>
                  <SidebarMenuSkeleton showIcon />
                </SidebarMenuItem>
              ))}
            </SidebarMenu>
          </SidebarGroup>
        </SidebarContent>
      </Sidebar>
      <SidebarInset>
        <PageHead title="Email" description="Loading mailboxes" />
      </SidebarInset>
    </SidebarProvider>
  );
}

```

## Source

components/ui/sidebar.tsx

```tsx
"use client";

import * as React from "react";
import { chakra } from "@chakra-ui/react";
import { cva, type VariantProps } from "class-variance-authority";
import { SidebarSimpleIcon } from "@phosphor-icons/react/ssr";

import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Separator } from "@/components/ui/separator";
import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle } from "@/components/ui/sheet";
import { Skeleton } from "@/components/ui/skeleton";
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip";
import { cn } from "@/lib/utils";

// The console's rail (Figma 427:2715: Dashboard - empty state, Agent Workspace - Inbox). The rail is 288px of white
// with a 1px #F3F1F5 edge; a 64px head holds the lockup 16px in. Rows are 38px with 8px corners on a 40px pitch, 12px in
// from the rail's sides: a filled glyph (the design's 22px, Phosphor's 24px) and a 14px regular ink label at 44px; the
// current row sits on the lilac. A labeled group starts 12px below the last one with a 13px purple label 16px in and its
// rows 8px under it; a group's action (the sliders glyph) sits 16px from the rail's right edge. The foot is ruled off
// above. `secondary` is the agent workspace's second rail: lilac, with the current row in white. Collapsing to icons
// narrows the rail to 63px (200ms, the strong ease-out); the keyboard shortcut toggles it instantly.
const SIDEBAR_WIDTH = "var(--ds-layout-rail)";
const SIDEBAR_WIDTH_ICON = "calc(var(--ds-space-9-5) + var(--ds-space-6) + 1px)";
const SIDEBAR_KEYBOARD_SHORTCUT = "b";
const MOBILE_QUERY = "(max-width: 767px)";

type SidebarContextProps = {
  state: "expanded" | "collapsed";
  open: boolean;
  setOpen: (open: boolean) => void;
  openMobile: boolean;
  setOpenMobile: (open: boolean) => void;
  isMobile: boolean;
  instant: boolean;
  toggleSidebar: () => void;
};

const SidebarContext = React.createContext<SidebarContextProps | null>(null);

function useSidebar() {
  const context = React.useContext(SidebarContext);
  if (!context) throw new Error("useSidebar must be used within a SidebarProvider.");
  return context;
}

function useIsMobile() {
  const [isMobile, setIsMobile] = React.useState(false);
  React.useEffect(() => {
    const query = window.matchMedia(MOBILE_QUERY);
    const update = () => setIsMobile(query.matches);
    update();
    query.addEventListener("change", update);
    return () => query.removeEventListener("change", update);
  }, []);
  return isMobile;
}

/**
 * Holds whether the rail is open (expanded or collapsed on a desktop, shown in a sheet on a phone). Uncontrolled with
 * `defaultOpen`, or controlled with `open` and `onOpenChange`. Nothing is stored: keep the state yourself if it should
 * survive a reload. Cmd or Ctrl and B toggles it.
 */
function SidebarProvider({ defaultOpen = true, open: openProp, onOpenChange: setOpenProp, className, style, children, ...props }: React.ComponentProps<"div"> & { defaultOpen?: boolean; open?: boolean; onOpenChange?: (open: boolean) => void }) {
  const isMobile = useIsMobile();
  const [openMobile, setOpenMobile] = React.useState(false);
  const [instant, setInstant] = React.useState(false);
  const [internalOpen, setInternalOpen] = React.useState(defaultOpen);
  const open = openProp ?? internalOpen;
  const setOpen = React.useCallback(
    (value: boolean | ((value: boolean) => boolean)) => {
      const next = typeof value === "function" ? value(open) : value;
      if (setOpenProp) setOpenProp(next);
      else setInternalOpen(next);
    },
    [setOpenProp, open],
  );
  const toggleSidebar = React.useCallback(() => {
    setInstant(false);
    return isMobile ? setOpenMobile((o) => !o) : setOpen((o) => !o);
  }, [isMobile, setOpen]);

  React.useEffect(() => {
    // A shortcut is pressed many times a day: it changes the rail at once, with no motion.
    const onKeyDown = (event: KeyboardEvent) => {
      if (event.key !== SIDEBAR_KEYBOARD_SHORTCUT || !(event.metaKey || event.ctrlKey)) return;
      event.preventDefault();
      setInstant(true);
      if (isMobile) setOpenMobile((o) => !o);
      else setOpen((o) => !o);
    };
    window.addEventListener("keydown", onKeyDown);
    return () => window.removeEventListener("keydown", onKeyDown);
  }, [isMobile, setOpen]);

  const state = open ? "expanded" : "collapsed";
  const value = React.useMemo<SidebarContextProps>(() => ({ state, open, setOpen, isMobile, openMobile, setOpenMobile, toggleSidebar, instant }), [state, open, setOpen, isMobile, openMobile, toggleSidebar, instant]);

  return (
    <SidebarContext.Provider value={value}>
      <TooltipProvider delayDuration={0}>
        <div
          data-slot="sidebar-wrapper"
          data-instant={instant || undefined}
          style={{ "--sidebar-width": SIDEBAR_WIDTH, "--sidebar-width-icon": SIDEBAR_WIDTH_ICON, ...style } as React.CSSProperties}
          className={cn("group/sidebar-wrapper flex min-h-svh w-full has-data-[variant=inset]:bg-subtle", className)}
          {...props}
        >
          {children}
        </div>
      </TooltipProvider>
    </SidebarContext.Provider>
  );
}

/**
 * The rail. `variant`: sidebar (the console's white rail), secondary (the lilac second rail), floating (a white panel
 * with Shadow/S, 8px from the edges) or inset (the rail on the lilac with the page as a raised white panel beside it).
 * `collapsible`: offcanvas (slides away), icon (narrows to its glyphs) or none.
 */
function Sidebar({
  side = "left",
  variant = "sidebar",
  collapsible = "offcanvas",
  className,
  children,
  ...props
}: React.ComponentProps<"div"> & { side?: "left" | "right"; variant?: "sidebar" | "secondary" | "floating" | "inset"; collapsible?: "offcanvas" | "icon" | "none" }) {
  const { isMobile, state, openMobile, setOpenMobile, instant } = useSidebar();
  const ground = variant === "secondary" || variant === "inset" ? "bg-subtle" : "bg-surface";

  if (collapsible === "none") {
    return (
      <div data-slot="sidebar" data-variant={variant} className={cn("group/sidebar flex h-full w-(--sidebar-width) flex-col text-fg", ground, variant === "sidebar" && "border-r border-line-subtle", className)} {...props}>
        {children}
      </div>
    );
  }

  if (isMobile) {
    return (
      <Sheet open={openMobile} onOpenChange={setOpenMobile}>
        <SheetContent instant={instant} data-slot="sidebar" data-sidebar="sidebar" data-mobile="true" data-variant={variant} side={side} showCloseButton={false} className={cn("group/sidebar w-(--ds-layout-rail) max-w-[calc(100vw-var(--ds-space-12))] p-0 text-fg sm:max-w-(--ds-layout-rail) [&>button]:hidden", ground)}>
          <SheetHeader className="sr-only">
            <SheetTitle>Navigation</SheetTitle>
            <SheetDescription>The app's sections and settings.</SheetDescription>
          </SheetHeader>
          <div className="flex h-full w-full flex-col">{children}</div>
        </SheetContent>
      </Sheet>
    );
  }

  return (
    <div
      data-slot="sidebar"
      data-state={state}
      data-collapsible={state === "collapsed" ? collapsible : ""}
      data-variant={variant}
      data-side={side}
      className="group/sidebar peer hidden shrink-0 text-fg md:block"
    >
      {/* Holds the rail's room in the row, so the page beside it moves as it opens and closes. */}
      <div
        data-slot="sidebar-gap"
        className={cn(
          "relative h-full w-(--sidebar-width) bg-transparent transition-[width] duration-200 ease-out group-data-[collapsible=offcanvas]/sidebar:w-0 group-data-[collapsible=icon]/sidebar:w-(--sidebar-width-icon) in-data-[instant=true]:transition-none motion-reduce:transition-none",
          (variant === "floating" || variant === "inset") && "group-data-[collapsible=icon]/sidebar:w-[calc(var(--sidebar-width-icon)+var(--ds-space-4))]",
        )}
      >
        <div
          data-slot="sidebar-container"
          className={cn(
            "sticky top-0 z-10 flex h-svh max-h-full w-(--sidebar-width) overflow-hidden transition-[translate,width] duration-200 ease-out in-data-[instant=true]:transition-none motion-reduce:transition-none",
            side === "left" ? "left-0 group-data-[collapsible=offcanvas]/sidebar:-translate-x-full" : "ml-auto group-data-[collapsible=offcanvas]/sidebar:translate-x-full",
            variant === "floating" || variant === "inset" ? "p-2 group-data-[collapsible=icon]/sidebar:w-[calc(var(--sidebar-width-icon)+var(--ds-space-4))]" : "group-data-[collapsible=icon]/sidebar:w-(--sidebar-width-icon)",
            variant === "sidebar" && (side === "left" ? "border-r border-line-subtle" : "border-l border-line-subtle"),
            className,
          )}
          {...props}
        >
          <div data-sidebar="sidebar" data-slot="sidebar-inner" className={cn("flex h-full w-full flex-col", ground, variant === "floating" && "rounded-panel shadow-s")}>
            {children}
          </div>
        </div>
      </div>
    </div>
  );
}

function SidebarTrigger({ className, onClick, ...props }: React.ComponentProps<typeof Button>) {
  const { toggleSidebar, open, isMobile, openMobile } = useSidebar();
  return (
    <Button
      data-sidebar="trigger"
      data-slot="sidebar-trigger"
      variant="ghost"
      size="icon"
      aria-expanded={isMobile ? openMobile : open}
      className={cn("text-icon-default", className)}
      onClick={(event) => {
        onClick?.(event);
        toggleSidebar();
      }}
      {...props}
    >
      <SidebarSimpleIcon weight="fill" className="size-6" />
      <span className="sr-only">Toggle the rail</span>
    </Button>
  );
}

/** A thin strip along the rail's edge that toggles it, with a 2px line in the field edge color under the pointer. */
function SidebarRail({ className, ...props }: React.ComponentProps<"button">) {
  const { toggleSidebar } = useSidebar();
  return (
    <button
      data-sidebar="rail"
      data-slot="sidebar-rail"
      aria-label="Toggle the rail"
      tabIndex={-1}
      onClick={toggleSidebar}
      title="Toggle the rail"
      className={cn(
        "absolute inset-y-0 z-20 hidden w-4 -translate-x-1/2 outline-none after:absolute after:inset-y-0 after:left-1/2 after:w-0.5 after:bg-transparent after:transition-colors after:duration-150 after:ease-out hover:after:bg-line-field sm:flex",
        "in-data-[side=left]:-right-4 in-data-[side=left]:cursor-w-resize in-data-[side=right]:left-0 in-data-[side=right]:cursor-e-resize",
        "[[data-side=left][data-state=collapsed]_&]:cursor-e-resize [[data-side=right][data-state=collapsed]_&]:cursor-w-resize",
        className,
      )}
      {...props}
    />
  );
}

/** The page beside the rail. With the inset rail it becomes a raised white panel with Shadow/S and 10px corners. */
function SidebarInset({ className, ...props }: React.ComponentProps<"main">) {
  return (
    <main
      data-slot="sidebar-inset"
      className={cn("relative flex w-full min-w-0 flex-1 flex-col bg-surface", "md:peer-data-[variant=inset]:m-2 md:peer-data-[variant=inset]:ml-0 md:peer-data-[variant=inset]:rounded-panel md:peer-data-[variant=inset]:shadow-s", className)}
      {...props}
    />
  );
}

function SidebarInput({ className, ...props }: React.ComponentProps<typeof Input>) {
  return <Input data-slot="sidebar-input" data-sidebar="input" className={cn("h-9 bg-surface", className)} {...props} />;
}

/** The rail's 64px head: the lockup 16px in, or the second rail's agent switcher. */
function SidebarHeader({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="sidebar-header" data-sidebar="header" className={cn("flex min-h-16 shrink-0 flex-col justify-center gap-2 px-3 py-3", className)} {...props} />;
}

/** The rail's foot (Help, the organization, the account, Collapse), ruled off above. */
function SidebarFooter({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="sidebar-footer" data-sidebar="footer" className={cn("flex shrink-0 flex-col gap-0.5 border-t border-line-subtle p-3", className)} {...props} />;
}

function SidebarSeparator({ className, ...props }: React.ComponentProps<typeof Separator>) {
  return <Separator data-slot="sidebar-separator" data-sidebar="separator" className={cn("mx-3 w-auto", className)} {...props} />;
}

function SidebarContent({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="sidebar-content"
      data-sidebar="content"
      className={cn("flex min-h-0 flex-1 flex-col overflow-auto overscroll-contain [scrollbar-width:none] group-data-[collapsible=icon]/sidebar:overflow-hidden", className)}
      {...props}
    />
  );
}

/** A group of rows. A labeled group keeps 12px above and below it; an unlabeled one (the rows under the head) none. */
function SidebarGroup({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="sidebar-group" data-sidebar="group" className={cn("relative flex w-full min-w-0 flex-col px-3 py-3 [&:not(:has(>[data-slot=sidebar-group-label]))]:py-0", className)} {...props} />;
}

/** A group's 13px purple label, 16px in from the rail; it folds away when the rail is narrowed to its glyphs. */
function SidebarGroupLabel({ className, asChild = false, ...props }: React.ComponentProps<"div"> & { asChild?: boolean }) {
  const Comp = asChild ? chakra.div : "div";
  // Chakra's factory renders its child in its place only when told to.
  const slotProps = asChild ? { asChild: true } : {};
  return (
    <Comp {...slotProps}
      data-slot="sidebar-group-label"
      data-sidebar="group-label"
      className={cn(
        "mb-2 flex h-4 shrink-0 items-center px-1 font-sans text-body-sm leading-4 whitespace-nowrap text-fg-label outline-none transition-[margin,opacity] duration-200 ease-out focus-visible:outline-2 focus-visible:outline-focus-ring group-data-[collapsible=icon]/sidebar:-mt-4 group-data-[collapsible=icon]/sidebar:opacity-0 motion-reduce:transition-none [&>svg]:size-4 [&>svg]:shrink-0",
        className,
      )}
      {...props}
    />
  );
}

/** A group's action beside its label (the sliders glyph by Email and Agent2Agent): a 16px glyph, 16px from the edge. */
function SidebarGroupAction({ className, asChild = false, ...props }: React.ComponentProps<"button"> & { asChild?: boolean }) {
  const Comp = asChild ? chakra.button : "button";
  // Chakra's factory renders its child in its place only when told to.
  const slotProps = asChild ? { asChild: true } : {};
  return (
    <Comp {...slotProps}
      data-slot="sidebar-group-action"
      data-sidebar="group-action"
      className={cn(
        "absolute top-2 right-3 flex size-6 cursor-pointer items-center justify-center rounded-pill text-icon-secondary outline-none active:brightness-95 active:transition-none transition-colors duration-150 ease-out hover:bg-subtle-hover active:bg-subtle-hover hover:text-fg focus-visible:outline-2 focus-visible:outline-focus-ring group-data-[collapsible=icon]/sidebar:hidden motion-reduce:transition-none [&>svg]:size-4.5 [&>svg]:shrink-0 after:absolute after:-inset-2 md:after:hidden",
        className,
      )}
      {...props}
    />
  );
}

function SidebarGroupContent({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="sidebar-group-content" data-sidebar="group-content" className={cn("w-full", className)} {...props} />;
}

function SidebarMenu({ className, ...props }: React.ComponentProps<"ul">) {
  return <ul data-slot="sidebar-menu" data-sidebar="menu" className={cn("flex w-full min-w-0 flex-col gap-0.5", className)} {...props} />;
}

function SidebarMenuItem({ className, ...props }: React.ComponentProps<"li">) {
  return <li data-slot="sidebar-menu-item" data-sidebar="menu-item" className={cn("group/menu-item relative", className)} {...props} />;
}

// A row: the glyph sits 11px in (Phosphor's 24px box puts its center where the design's 22px glyph at 12px has it), the
// label 9px after it, at the design's 44px. Hover washes the row; the current row takes the lilac (white on the lilac
// rail). Narrowed to icons, the row is a 38px square around its glyph.
const sidebarMenuButtonVariants = cva(
  "peer/menu-button active:brightness-95 active:transition-none flex w-full cursor-pointer items-center gap-2.25 overflow-hidden rounded-pill pr-3 pl-2.75 text-left font-sans text-fg outline-none transition-[background-color,color] duration-150 ease-out group-has-data-[sidebar=menu-action]/menu-item:pr-9 group-data-[collapsible=icon]/sidebar:size-9.5! group-data-[collapsible=icon]/sidebar:justify-center group-data-[collapsible=icon]/sidebar:p-0! group-data-[collapsible=icon]/sidebar:[&>span:not([data-slot=avatar])]:sr-only focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus-ring disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-[active=true]:bg-subtle group-data-[variant=secondary]/sidebar:data-[active=true]:bg-surface group-data-[variant=inset]/sidebar:data-[active=true]:bg-surface data-[state=open]:bg-subtle motion-reduce:transition-none [&>span:last-child]:truncate [&>svg]:shrink-0 [&>svg:not([class*='size-'])]:size-6",
  {
    variants: {
      variant: {
        default: "hover:bg-subtle group-data-[variant=secondary]/sidebar:hover:bg-subtle-hover group-data-[variant=secondary]/sidebar:data-[active=true]:hover:bg-surface group-data-[variant=inset]/sidebar:hover:bg-subtle-hover",
        outline: "bg-surface shadow-s hover:bg-subtle",
      },
      size: {
        default: "h-9.5 text-body leading-tight",
        sm: "h-8 text-body-sm leading-tight [&>svg:not([class*='size-'])]:size-5",
        lg: "h-12 text-body leading-tight group-data-[collapsible=icon]/sidebar:p-0!",
      },
    },
    defaultVariants: { variant: "default", size: "default" },
  },
);

function SidebarMenuButton({
  asChild = false,
  isActive = false,
  variant = "default",
  size = "default",
  tooltip,
  className,
  ...props
}: React.ComponentProps<"button"> & { asChild?: boolean; isActive?: boolean; tooltip?: string | React.ComponentProps<typeof TooltipContent> } & VariantProps<typeof sidebarMenuButtonVariants>) {
  const Comp = asChild ? chakra.button : "button";
  // Chakra's factory renders its child in its place only when told to.
  const slotProps = asChild ? { asChild: true } : {};
  const { isMobile, state } = useSidebar();
  // The tooltip names a row only while the rail shows glyphs alone; otherwise it stays shut, so it never catches Escape.
  const [tipOpen, setTipOpen] = React.useState(false);
  const showTip = state === "collapsed" && !isMobile;
  const button = (
    <Comp {...slotProps}
      data-slot="sidebar-menu-button"
      data-sidebar="menu-button"
      data-size={size}
      data-active={isActive || undefined}
      aria-current={isActive ? "page" : undefined}
      className={cn(sidebarMenuButtonVariants({ variant, size }), className)}
      {...props}
    />
  );
  if (!tooltip) return button;
  const content = typeof tooltip === "string" ? { children: tooltip } : tooltip;
  return (
    <Tooltip open={showTip && tipOpen} onOpenChange={setTipOpen}>
      <TooltipTrigger asChild>{button}</TooltipTrigger>
      <TooltipContent side="right" align="center" {...content} />
    </Tooltip>
  );
}

/** An action at a row's right end (a row's more glyph). `showOnHover` keeps it hidden until the row is hovered or open. */
function SidebarMenuAction({ className, asChild = false, showOnHover = false, ...props }: React.ComponentProps<"button"> & { asChild?: boolean; showOnHover?: boolean }) {
  const Comp = asChild ? chakra.button : "button";
  // Chakra's factory renders its child in its place only when told to.
  const slotProps = asChild ? { asChild: true } : {};
  return (
    <Comp {...slotProps}
      data-slot="sidebar-menu-action"
      data-sidebar="menu-action"
      className={cn(
        "absolute top-1.25 right-1.5 flex size-7 cursor-pointer items-center justify-center rounded-pill text-icon-secondary outline-none active:brightness-95 active:transition-none transition-[background-color,color,opacity] duration-150 ease-out hover:bg-subtle-hover active:bg-subtle-hover hover:text-fg focus-visible:outline-2 focus-visible:outline-focus-ring group-data-[collapsible=icon]/sidebar:hidden motion-reduce:transition-none [&>svg]:size-5 [&>svg]:shrink-0 after:absolute after:-inset-2 md:after:hidden",
        "peer-data-[size=sm]/menu-button:top-0.5 peer-data-[size=lg]/menu-button:top-2.5",
        showOnHover && "group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 data-[state=open]:opacity-100 peer-data-[active=true]/menu-button:text-fg md:opacity-0",
        className,
      )}
      {...props}
    />
  );
}

/**
 * A mark at a row's right end, 12px in (ADMIN by My Organisation): the pink edge, pill corners and 12px pink text.
 * `count` is a quiet 13px number instead (unread mail). For a mark right after the label (BETA by Agent2Agent), put a
 * Badge with variant pink inside the row's button.
 */
function SidebarMenuBadge({ className, variant = "mark", ...props }: React.ComponentProps<"div"> & { variant?: "mark" | "count" }) {
  return (
    <div
      data-slot="sidebar-menu-badge"
      data-sidebar="menu-badge"
      className={cn(
        "pointer-events-none absolute top-2 right-3 flex h-5.5 items-center justify-center font-sans whitespace-nowrap select-none group-data-[collapsible=icon]/sidebar:hidden",
        "peer-data-[size=sm]/menu-button:top-1.25 peer-data-[size=lg]/menu-button:top-3.25",
        variant === "mark" ? "rounded-pill border border-pink bg-surface px-1.5 pt-px text-caption leading-none text-pink" : "min-w-5 px-1 text-body-sm text-fg-muted tabular-nums",
        className,
      )}
      {...props}
    />
  );
}

/** A row's placeholder while the rail loads: a glyph circle and a label of varying width on the lilac. */
function SidebarMenuSkeleton({ className, showIcon = false, ...props }: React.ComponentProps<"div"> & { showIcon?: boolean }) {
  // A width between 50 and 90 percent that differs from row to row but is the same on the server and in the browser.
  const id = React.useId();
  const width = `${50 + (([...id].reduce((sum, c) => (sum * 31 + c.charCodeAt(0)) % 997, 7) % 41))}%`;
  return (
    <div data-slot="sidebar-menu-skeleton" data-sidebar="menu-skeleton" className={cn("flex h-9.5 items-center gap-2.25 rounded-pill pr-3 pl-2.75", className)} {...props}>
      {showIcon && <Skeleton className="size-5.5 rounded-pill" data-sidebar="menu-skeleton-icon" />}
      <Skeleton className="h-3.5 max-w-(--skeleton-width) flex-1 rounded-xs" data-sidebar="menu-skeleton-text" style={{ "--skeleton-width": width } as React.CSSProperties} />
    </div>
  );
}

/** Rows nested under a row, hung from a hairline under the parent's glyph. */
function SidebarMenuSub({ className, ...props }: React.ComponentProps<"ul">) {
  return (
    <ul
      data-slot="sidebar-menu-sub"
      data-sidebar="menu-sub"
      className={cn("mx-5.5 mt-0.5 flex min-w-0 flex-col gap-0.5 border-l border-line-subtle py-0.5 pl-2.5 group-data-[collapsible=icon]/sidebar:hidden", className)}
      {...props}
    />
  );
}

function SidebarMenuSubItem({ className, ...props }: React.ComponentProps<"li">) {
  return <li data-slot="sidebar-menu-sub-item" data-sidebar="menu-sub-item" className={cn("group/menu-sub-item relative", className)} {...props} />;
}

function SidebarMenuSubButton({ asChild = false, size = "md", isActive = false, className, ...props }: React.ComponentProps<"a"> & { asChild?: boolean; size?: "sm" | "md"; isActive?: boolean }) {
  const Comp = asChild ? chakra.a : "a";
  // Chakra's factory renders its child in its place only when told to.
  const slotProps = asChild ? { asChild: true } : {};
  return (
    <Comp {...slotProps}
      data-slot="sidebar-menu-sub-button"
      data-sidebar="menu-sub-button"
      data-size={size}
      data-active={isActive || undefined}
      aria-current={isActive ? "page" : undefined}
      className={cn(
        "flex h-8 min-w-0 cursor-pointer items-center gap-2 overflow-hidden rounded-pill px-2.5 font-sans text-fg-secondary outline-none active:brightness-95 active:transition-none transition-[background-color,color] duration-150 ease-out hover:bg-subtle active:bg-subtle hover:text-fg focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus-ring aria-disabled:pointer-events-none aria-disabled:opacity-50 data-[active=true]:bg-subtle data-[active=true]:text-fg group-data-[variant=secondary]/sidebar:hover:bg-subtle-hover group-data-[variant=secondary]/sidebar:data-[active=true]:bg-surface motion-reduce:transition-none [&>span:last-child]:truncate [&>svg]:size-5 [&>svg]:shrink-0",
        size === "sm" ? "text-body-sm" : "text-body",
        className,
      )}
      {...props}
    />
  );
}

export {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupAction,
  SidebarGroupContent,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarInput,
  SidebarInset,
  SidebarMenu,
  SidebarMenuAction,
  SidebarMenuBadge,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarMenuSkeleton,
  SidebarMenuSub,
  SidebarMenuSubButton,
  SidebarMenuSubItem,
  SidebarProvider,
  SidebarRail,
  SidebarSeparator,
  SidebarTrigger,
  useSidebar,
};

```

# Skeleton
A lilac placeholder with 8px corners that breathes softly while content loads.

Install: npx inkbox-ds add skeleton
Requires: theme, utils
Packages: none
Exports: Skeleton
Client boundary: not required by this entry file
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the lilac fill and 8px corners of its wells


## Usage
Use in the shape of what will load (rows of the email list, a table's rows, an avatar), matching each part's size and corners (rounded-pill for buttons, avatars and small icon tiles). Show it only for loads longer than about 300ms.
- Avoid: Shimmer gradients
- Avoid: Skeletons for content already on screen
- Avoid: A skeleton for a single button


## Examples
Example components: npx inkbox-ds add skeleton
[Preview](https://inkbox-ds.vercel.app/preview/skeleton/Preview) | [Row](https://inkbox-ds.vercel.app/preview/skeleton/Row)

examples/skeleton.tsx

```tsx
import { Skeleton } from "@/components/ui/skeleton";

export function Preview() {
  return (
    <div className="grid w-full max-w-96 gap-1" aria-busy="true" aria-label="Loading emails">
      {[0, 1, 2].map((i) => (
        <div key={i} className="grid gap-2.5 p-3">
          <div className="flex justify-between">
            <Skeleton className="h-4 w-20" />
            <Skeleton className="h-4 w-12" />
          </div>
          <Skeleton className="h-4 w-11/12" />
          <Skeleton className="h-4 w-3/4" />
        </div>
      ))}
    </div>
  );
}

export function Row() {
  return (
    <div className="flex w-full max-w-120 items-center gap-4" aria-busy="true" aria-label="Loading mailbox">
      <Skeleton className="size-5.5 rounded-pill" />
      <Skeleton className="h-4 flex-1" />
      <Skeleton className="h-10 w-28 rounded-pill" />
    </div>
  );
}

```

## Source

components/ui/skeleton.tsx

```tsx
import { cn } from "@/lib/utils";

// A placeholder while content loads: the lilac with 8px corners, breathing between full and 55 percent (1.6s, the
// in-out curve). With reduced motion it holds still.
function Skeleton({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="skeleton" aria-hidden className={cn("animate-pulse-soft rounded-control bg-subtle motion-reduce:animate-none", className)} {...props} />;
}

export { Skeleton };

```

# Slider
A 6px lilac-gray track filled purple to the value, with the switch's white knob.

Install: npx inkbox-ds add slider
Requires: theme, utils
Packages: @chakra-ui/react
Exports: Slider
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the switch's knob and purple, the field's lilac-gray


## Usage
Use to pick an approximate value in a range where the exact number matters less than its position (a daily send limit, a retry delay, a storage quota). Show the current value next to its label. Pass two values for a range.
- Avoid: A slider for exact numbers (use Input)
- Avoid: A thick or colored knob
- Avoid: Ticks on every step


## Examples
Example components: npx inkbox-ds add slider label
[Preview](https://inkbox-ds.vercel.app/preview/slider/Preview) | [Range](https://inkbox-ds.vercel.app/preview/slider/Range) | [States](https://inkbox-ds.vercel.app/preview/slider/States)

examples/slider.tsx

```tsx
"use client";

import * as React from "react";

import { Label } from "@/components/ui/label";
import { Slider } from "@/components/ui/slider";

export function Preview() {
  const [limit, setLimit] = React.useState([250]);
  return (
    <div className="grid w-full max-w-100 gap-3">
      <div className="flex items-center justify-between">
        <Label id="limit-label">Daily send limit</Label>
        <span className="text-body text-fg-muted">{limit[0]} emails</span>
      </div>
      <Slider aria-labelledby="limit-label" value={limit} onValueChange={setLimit} max={1000} step={50} />
    </div>
  );
}

export function Range() {
  const [hours, setHours] = React.useState([9, 17]);
  return (
    <div className="grid w-full max-w-100 gap-3">
      <div className="flex items-center justify-between">
        <Label id="hours-label">Calling hours</Label>
        <span className="text-body text-fg-muted">
          {hours[0]}:00 to {hours[1]}:00
        </span>
      </div>
      <Slider aria-labelledby="hours-label" value={hours} onValueChange={setHours} min={0} max={24} step={1} minStepsBetweenThumbs={1} />
    </div>
  );
}

export function States() {
  return (
    <div className="grid w-full max-w-100 gap-6">
      <Slider aria-label="Disabled" defaultValue={[40]} disabled />
      <div className="flex h-40 gap-8">
        <Slider aria-label="Vertical" defaultValue={[60]} orientation="vertical" />
        <Slider aria-label="Vertical range" defaultValue={[20, 70]} orientation="vertical" />
      </div>
    </div>
  );
}

```

## Source

components/ui/slider.tsx

```tsx
"use client";

import * as React from "react";
import { Slider as ChakraSlider } from "@chakra-ui/react";

import { cn } from "@/lib/utils";

// Extrapolated from the console's switch (Figma "Toggle"): a 6px pill track in the field's lilac-gray, filled with the
// action purple up to the value, and a 20px white knob with the switch knob's soft drop. Under the pointer or keyboard
// focus the knob takes a soft purple halo; it never animates its position (it follows the pointer). Pass two values for
// a range.
type SliderProps = Omit<React.ComponentProps<typeof ChakraSlider.Root>, "onValueChange" | "aria-label" | "aria-labelledby"> & { onValueChange?: (value: number[]) => void; "aria-label"?: string | string[]; "aria-labelledby"?: string | string[] };
function Slider({ className, defaultValue, value, min = 0, max = 100, onValueChange, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, ...props }: SliderProps) {
  const values = React.useMemo(() => (Array.isArray(value) ? value : Array.isArray(defaultValue) ? defaultValue : [min, max]), [value, defaultValue, min, max]);
  return (
    <ChakraSlider.Root
      unstyled
      data-slot="slider"
      defaultValue={defaultValue}
      value={value}
      onValueChange={(details) => onValueChange?.(details.value)}
      aria-label={ariaLabel === undefined ? undefined : Array.isArray(ariaLabel) ? ariaLabel : [ariaLabel]}
      aria-labelledby={ariaLabelledBy === undefined ? undefined : Array.isArray(ariaLabelledBy) ? ariaLabelledBy : [ariaLabelledBy]}
      min={min}
      max={max}
      className={cn(
        "relative flex w-full touch-none items-center select-none data-disabled:opacity-50 data-[orientation=vertical]:h-full data-[orientation=vertical]:min-h-40 data-[orientation=vertical]:w-auto data-[orientation=vertical]:flex-col",
        className,
      )}
      {...props}
    >
      <ChakraSlider.Control>
      <ChakraSlider.Track
        data-slot="slider-track"
        className="relative grow overflow-hidden rounded-pill bg-line-field data-[orientation=horizontal]:h-1.5 data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-1.5"
      >
        <ChakraSlider.Range data-slot="slider-range" className="absolute bg-primary data-[orientation=horizontal]:h-full data-[orientation=vertical]:w-full" />
      </ChakraSlider.Track>
      {Array.from({ length: values.length }, (_, index) => (
        <ChakraSlider.Thumb
          data-slot="slider-thumb"
          index={index}
          key={index}
          aria-label={Array.isArray(ariaLabel) ? ariaLabel[index] : ariaLabel ?? (values.length > 1 ? (index === 0 ? "Minimum" : "Maximum") : undefined)}
          className="block size-5 shrink-0 cursor-grab rounded-pill bg-surface shadow-knob outline-none transition-[box-shadow] duration-150 ease-out hover:shadow-[var(--ds-shadow-knob),0_0_0_4px_var(--ds-color-ring-tint)] focus-visible:shadow-[var(--ds-shadow-knob),0_0_0_4px_var(--ds-color-ring-tint)] active:cursor-grabbing disabled:pointer-events-none motion-reduce:transition-none"
        ><ChakraSlider.HiddenInput /></ChakraSlider.Thumb>
      ))}
      </ChakraSlider.Control>
    </ChakraSlider.Root>
  );
}

export { Slider };

```

# Sonner
Toasts as white floating panels with a filled status glyph, an ink title, a muted description and a purple action.

Install: npx inkbox-ds add sonner
Requires: theme
Packages: @phosphor-icons/react, sonner
Exports: Toaster
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): white floating panels, filled status glyphs and the purple action


## Usage
Use to confirm something that happened in the background or will undo (API key copied, agent created, webhook paused). Mount Toaster once near the root and call toast(), toast.success(), toast.error() or toast.promise() from anywhere. Give undoable actions an action button.
- Avoid: A toast for an error that blocks the task (say it in place instead)
- Avoid: Colored toast backgrounds
- Avoid: More than one sentence of description


## Examples
Example components: npx inkbox-ds add sonner button
Example packages: sonner
[Preview](https://inkbox-ds.vercel.app/preview/sonner/Preview)

examples/sonner.tsx

```tsx
"use client";

import { toast } from "sonner";

import { Button } from "@/components/ui/button";
import { Toaster } from "@/components/ui/sonner";

export function Preview() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Toaster />
      <Button
        variant="outline"
        onClick={() =>
          toast("Webhook paused", {
            description: "message.sent stops delivering to api.acme.dev.",
            action: { label: "Undo", onClick: () => toast.success("Webhook resumed") },
          })
        }
      >
        Pause webhook
      </Button>
      <Button variant="outline" onClick={() => toast.success("Agent created", { description: "@test-agent is ready to send its first email." })}>
        Success
      </Button>
      <Button variant="outline" onClick={() => toast.error("Handle not available", { description: "acme-support is taken. Try another." })}>
        Error
      </Button>
      <Button variant="outline" onClick={() => toast.warning("Copy this API key now", { description: "For security, the full key cannot be shown again." })}>
        Warning
      </Button>
      <Button variant="outline" onClick={() => toast.info("The vault is zero-knowledge", { description: "Encryption happens in your browser." })}>
        Info
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          // ds-latency: demonstrates a pending notification; no control or input waits for the demo timer.
          toast.promise(new Promise((resolve) => setTimeout(resolve, 1600)), {
            loading: "Provisioning phone line...",
            success: "Line +1 650 474 9720 is live",
            error: "Could not provision a line",
          })
        }
      >
        Promise
      </Button>
    </div>
  );
}

```

## Source

components/ui/sonner.tsx

```tsx
"use client";

import * as React from "react";
import { CheckCircleIcon, InfoIcon, SpinnerGapIcon, WarningIcon, XCircleIcon, XIcon } from "@phosphor-icons/react/ssr";
import { Toaster as Sonner, type ToasterProps } from "sonner";

// Toasts (extrapolated from the Inkbox console, Figma 427:2715: its white floating panels, 16px corners, filled status
// glyphs and the purple action). A toast is a white panel with the floating shadow and 16px of padding: a 20px filled
// glyph (green success, red error, amber warning, teal info, a spinning loader), the 14px medium ink title, the 14px
// muted description, and a small purple pill for its action beside a lilac one for cancel. Sonner stacks, swipes and
// times them; its motion (400ms, ease) is kept as Emil Kowalski tuned it.
function Toaster({ toastOptions, ...props }: ToasterProps) {
  return (
    <Sonner
      data-slot="sonner"
      className="toaster group"
      icons={{
        success: <CheckCircleIcon weight="fill" className="size-5.5 text-success" />,
        info: <InfoIcon weight="fill" className="size-5.5 text-info" />,
        warning: <WarningIcon weight="fill" className="size-5.5 text-warning" />,
        error: <XCircleIcon weight="fill" className="size-5.5 text-danger-strong" />,
        loading: <SpinnerGapIcon className="size-5.5 animate-spin-steady text-fg-muted" />,
        close: <XIcon className="size-3.5" />,
      }}
      toastOptions={{
        ...toastOptions,
        classNames: {
          toast: "group/toast flex! w-(--width) items-start! gap-3! rounded-panel bg-surface p-4! font-sans text-fg shadow-floating!",
          icon: "mt-px flex size-5 shrink-0 items-center justify-center",
          content: "grid min-w-0 flex-1 gap-0.5",
          title: "text-body! leading-body font-medium! text-fg",
          description: "text-body! leading-body text-fg-muted!",
          actionButton: "inline-flex h-8! shrink-0 items-center rounded-pill! bg-primary! px-3.5! font-sans text-body! leading-tight font-normal! text-on-primary! outline-none transition-[background-color] duration-150 ease-out hover:bg-primary-hover! active:bg-primary-hover! active:brightness-95 active:transition-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring",
          cancelButton: "inline-flex h-8! shrink-0 items-center rounded-pill! bg-subtle! px-3.5! font-sans text-body! leading-tight font-normal! text-fg! outline-none transition-[background-color] duration-150 ease-out hover:bg-subtle-hover! active:bg-subtle-hover! active:brightness-95 active:transition-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring",
          closeButton: "absolute -top-2 -left-2 inline-flex size-5 items-center justify-center rounded-pill bg-surface text-fg-muted shadow-s outline-none active:brightness-95 active:transition-none transition-colors duration-150 ease-out hover:text-fg focus-visible:outline-2 focus-visible:outline-focus-ring",
          ...toastOptions?.classNames,
        },
      }}
      style={
        {
          "--width": "22.25rem",
          "--normal-bg": "var(--ds-color-bg-default)",
          "--normal-text": "var(--ds-color-text-default)",
          "--normal-border": "transparent",
          "--border-radius": "var(--ds-radius-panel)",
        } as React.CSSProperties
      }
      {...props}
    />
  );
}

export { Toaster };

```

# Spinner
The console's turning eight-spoke glyph, in the color of the text around it.

Install: npx inkbox-ds add spinner
Requires: theme, utils
Packages: @phosphor-icons/react
Exports: Spinner
Client boundary: not required by this entry file
Reference: Figma 427:2715: Modal States (Handle check, Creating...)


## Usage
Use inside the thing that is working: at the right of a field while the handle is checked (text-fg-brand), before the label of a button that is creating (Creating Agent Identity...). Disable the button while it spins.
- Avoid: A full-page spinner for a short wait
- Avoid: A spinner without a label or button text saying what is happening
- Avoid: Colored spinners


## Examples
Example components: npx inkbox-ds add spinner button input
[Preview](https://inkbox-ds.vercel.app/preview/spinner/Preview) | [Sizes](https://inkbox-ds.vercel.app/preview/spinner/Sizes)

examples/spinner.tsx

```tsx
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Spinner } from "@/components/ui/spinner";

export function Preview() {
  return (
    <div className="grid w-full max-w-100 gap-4">
      <div className="relative">
        <Input aria-label="Agent handle" defaultValue="acme-support" className="pr-10" />
        <Spinner className="absolute top-1/2 right-3 -translate-y-1/2 text-fg-brand" />
      </div>
      <Button disabled className="w-full">
        <Spinner />
        Creating Agent Identity...
      </Button>
    </div>
  );
}

export function Sizes() {
  return (
    <div className="flex items-center gap-4 text-fg-brand">
      <Spinner className="size-4" />
      <Spinner />
      <Spinner className="size-8" />
    </div>
  );
}

```

## Source

components/ui/spinner.tsx

```tsx
import { SpinnerIcon } from "@phosphor-icons/react/ssr";

import { cn } from "@/lib/utils";

// The console's loading glyph (Figma 427:2715: the handle check, Creating Agent Identity...): eight short spokes
// turning once every 0.8s at a constant speed, in the color of the text around it (the purple in a field, white on the
// purple pill). It keeps turning with reduced motion: the turning is the only sign that work is happening.
function Spinner({ className, ...props }: React.ComponentProps<"svg">) {
  return <SpinnerIcon role="status" weight="bold" aria-label="Loading" data-slot="spinner" className={cn("size-5.5 shrink-0 animate-spin-steady", className)} {...props} />;
}

export { Spinner };

```

# Surface
A white or lilac ground that also keeps the dialogs, menus and tooltips opened inside it.

Install: npx inkbox-ds add surface
Requires: utils
Packages: none
Exports: Surface, usePortalContainer
Client boundary: yes

## Usage
Wrap an embedded panel or a preview in Surface so its overlays render inside it. Pick lilac for the second rail or a channel card's ground.


## Source

lib/surface.tsx

```tsx
"use client";

import * as React from "react";

import { cn } from "@/lib/utils";

// A ground: white (the page and dialogs) or lilac (the second rail, a channel card, a table's head). Dialogs, menus
// and tooltips opened inside a Surface render inside it, so a preview or an embedded panel keeps its overlays.
const PortalContainer = React.createContext<HTMLElement | null>(null);

const GROUNDS = {
  white: "bg-surface text-fg",
  lilac: "bg-subtle text-fg",
} as const;

export function Surface({ ground = "white", className, children, ...props }: React.ComponentProps<"div"> & { ground?: keyof typeof GROUNDS }) {
  const [element, setElement] = React.useState<HTMLDivElement | null>(null);
  return (
    <div ref={setElement} data-ground={ground} className={cn(GROUNDS[ground], className)} {...props}>
      <PortalContainer.Provider value={element}>{children}</PortalContainer.Provider>
    </div>
  );
}

/** Where overlays render: the nearest Surface, else the page body. */
export function usePortalContainer() {
  return React.useContext(PortalContainer) ?? undefined;
}

```

# Switch
A 44 by 24 pill: off gray, purple when on, with a white knob that slides across.

Install: npx inkbox-ds add switch
Requires: theme, utils
Packages: @chakra-ui/react
Exports: Switch
Client boundary: yes
Reference: Figma 427:2715: Toggle (44 by 24) in the channel cards of Create Agent Identity, off and on states in Modal States


## Usage
Use to turn a setting or a channel on and off immediately (Phone Number, iMessage, Agent2Agent in Create Agent Identity). Put the label at the left and the switch at the right of the row, and give the switch an accessible name with aria-label or a Label. Use size sm in dense lists.
- Avoid: A switch that needs a save button to apply
- Avoid: A label inside the track
- Avoid: A colored track other than purple when on
- Avoid: A knob that bounces


## Examples
Example components: npx inkbox-ds add switch label
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/switch/Preview) | [States](https://inkbox-ds.vercel.app/preview/switch/States)

examples/switch.tsx

```tsx
"use client";

import * as React from "react";
import { AppleLogoIcon, ArrowsLeftRightIcon, PhoneIcon } from "@phosphor-icons/react/ssr";

import { Label } from "@/components/ui/label";
import { Switch } from "@/components/ui/switch";

export function Preview() {
  const [phone, setPhone] = React.useState(true);
  const [imessage, setImessage] = React.useState(false);
  const rows = [
    { id: "phone", label: "Phone Number", icon: PhoneIcon, checked: phone, set: setPhone },
    { id: "imessage", label: "iMessage", icon: AppleLogoIcon, checked: imessage, set: setImessage },
  ];
  return (
    <div className="grid w-full max-w-121.5 gap-2">
      {rows.map(({ id, label, icon: Icon, checked, set }) => (
        <div key={id} className="flex h-13 items-center gap-2.5 rounded-pill bg-subtle px-3.5">
          <span className="flex size-7 items-center justify-center rounded-pill bg-pink text-rose">
            <Icon weight="fill" className="size-5" />
          </span>
          <Label htmlFor={id} className="flex-1 text-body-lg font-medium">
            {label}
          </Label>
          <Switch id={id} checked={checked} onCheckedChange={set} />
        </div>
      ))}
    </div>
  );
}

export function States() {
  return (
    <div className="grid gap-4">
      <div className="flex items-center gap-3">
        <Switch id="a2a" />
        <Label htmlFor="a2a">
          <ArrowsLeftRightIcon className="size-5" /> Agent2Agent
        </Label>
      </div>
      <div className="flex items-center gap-3">
        <Switch id="on" defaultChecked />
        <Label htmlFor="on">Shared iMessage line</Label>
      </div>
      <div className="flex items-center gap-3">
        <Switch id="off-disabled" disabled />
        <Label htmlFor="off-disabled">Dedicated line (none available)</Label>
      </div>
      <div className="flex items-center gap-3">
        <Switch id="on-disabled" disabled defaultChecked />
        <Label htmlFor="on-disabled">Email (always on)</Label>
      </div>
      <div className="flex items-center gap-3">
        <Switch id="small" size="sm" defaultChecked />
        <Label htmlFor="small">Small</Label>
      </div>
    </div>
  );
}

```

## Source

components/ui/switch.tsx

```tsx
"use client";

import * as React from "react";
import { Switch as ChakraSwitch } from "@chakra-ui/react";

import { cn } from "@/lib/utils";

// The console's toggle (Figma "Toggle", 44 by 24 in every channel card of Create Agent Identity): a pill track in the
// off gray #B1ADBB, the action purple when on, with a 20px white knob 2px in that carries a soft drop. The knob slides
// across on the strong in-out curve (it travels on screen); with reduced motion it jumps. `size="sm"` is a 36 by 20
// variant for dense rows.
type SwitchProps = Omit<React.ComponentProps<typeof ChakraSwitch.Root>, "onCheckedChange"> & { size?: "default" | "sm"; onCheckedChange?: (checked: boolean) => void };

function Switch({ className, size = "default", onCheckedChange, ...props }: SwitchProps) {
  return (
    <ChakraSwitch.Root
      data-slot="switch"
      data-size={size}
      onCheckedChange={(details) => onCheckedChange?.(details.checked)}
      className={cn(
        "peer group/switch inline-flex shrink-0 cursor-pointer items-center rounded-pill bg-off p-0.5 outline-none transition-[background-color] duration-200 ease-out focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:outline-2 aria-invalid:outline-danger data-[state=checked]:bg-primary data-[size=default]:h-6 data-[size=default]:w-11 data-[size=sm]:h-5 data-[size=sm]:w-9 motion-reduce:transition-none",
        className,
      )}
      {...props}
    >
      <ChakraSwitch.HiddenInput role="switch" />
      <ChakraSwitch.Control data-slot="switch-control" className="flex size-full items-center rounded-pill bg-transparent p-0">
      <ChakraSwitch.Thumb
        data-slot="switch-thumb"
        className="pointer-events-none block rounded-pill bg-surface shadow-knob transition-transform duration-200 ease-in-out group-data-[size=default]/switch:size-5 group-data-[size=sm]/switch:size-4 data-[state=checked]:translate-x-5 motion-reduce:transition-none group-data-[size=sm]/switch:data-[state=checked]:translate-x-4"
      />
      </ChakraSwitch.Control>
    </ChakraSwitch.Root>
  );
}

export { Switch };

```

# Table
The console's table: a lilac head with muted labels, a separate white body with Shadow/S and 64px rows, and a lilac foot.

Install: npx inkbox-ds add table
Requires: theme, utils
Packages: none
Exports: Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow
Client boundary: not required by this entry file
Reference: Figma 427:2715: Email (Mailboxes table) and iMessage (Agents and lines table)


## Usage
Use for rows of records people scan and act on (mailboxes, agents and lines, webhooks). Put labels in TableHeader, rows in TableBody, totals or Pagination with bar in a TableFooter or under the table, and row actions as ghost icon buttons in the last cell. Keep cells to one line; truncate long values.
- Avoid: Zebra striping
- Avoid: Vertical rules between cells
- Avoid: A dark or purple head row
- Avoid: Bold cell text


## Examples
Example components: npx inkbox-ds add table button pagination
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/table/Preview) | [WithFooter](https://inkbox-ds.vercel.app/preview/table/WithFooter)

examples/table.tsx

```tsx
import { ArrowsClockwiseIcon, PencilSimpleIcon } from "@phosphor-icons/react/ssr";

import { Button } from "@/components/ui/button";
import { Pagination, PaginationContent, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious } from "@/components/ui/pagination";
import { Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow } from "@/components/ui/table";

const MAILBOXES = [
  { address: "acme@inkboxmail.com", agent: "@acme", webhooks: "None", storage: "0%", created: "Jul 27, 2026" },
  { address: "support@inkboxmail.com", agent: "@support-desk", webhooks: "2", storage: "4%", created: "Jul 29, 2026" },
  { address: "ops@inkboxmail.com", agent: "@ops-runner", webhooks: "1", storage: "12%", created: "Aug 2, 2026" },
];

export function Preview() {
  return (
    <div className="grid gap-0">
      <Table>
        <TableHeader>
          <TableRow>
            <TableHead>Email address</TableHead>
            <TableHead>Agent</TableHead>
            <TableHead>Webhooks</TableHead>
            <TableHead>Storage</TableHead>
            <TableHead>Created</TableHead>
            <TableHead className="w-12 text-right">
              <Button variant="ghost" size="icon" aria-label="Refresh mailboxes">
                <ArrowsClockwiseIcon />
              </Button>
            </TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {MAILBOXES.map((m) => (
            <TableRow key={m.address}>
              <TableCell>{m.address}</TableCell>
              <TableCell className="text-rose">{m.agent}</TableCell>
              <TableCell>{m.webhooks}</TableCell>
              <TableCell>{m.storage}</TableCell>
              <TableCell>{m.created}</TableCell>
              <TableCell className="text-right">
                <Button variant="ghost" size="icon" aria-label={`Edit ${m.address}`}>
                  <PencilSimpleIcon weight="fill" />
                </Button>
              </TableCell>
            </TableRow>
          ))}
        </TableBody>
      </Table>
      <Pagination bar className="mt-1">
        <PaginationContent>
          <PaginationItem>
            <PaginationPrevious href="#" aria-disabled />
          </PaginationItem>
          <PaginationItem>
            <PaginationLink href="#" isActive>
              1
            </PaginationLink>
          </PaginationItem>
          <PaginationItem>
            <PaginationLink href="#">2</PaginationLink>
          </PaginationItem>
          <PaginationItem>
            <PaginationNext href="#" />
          </PaginationItem>
        </PaginationContent>
      </Pagination>
    </div>
  );
}

export function WithFooter() {
  return (
    <Table>
      <TableCaption>Usage this billing period.</TableCaption>
      <TableHeader>
        <TableRow>
          <TableHead>Channel</TableHead>
          <TableHead>Messages</TableHead>
          <TableHead className="text-right">Cost</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        <TableRow>
          <TableCell>Email</TableCell>
          <TableCell>1,204</TableCell>
          <TableCell className="text-right">$12.04</TableCell>
        </TableRow>
        <TableRow data-state="selected">
          <TableCell>Phone</TableCell>
          <TableCell>86</TableCell>
          <TableCell className="text-right">$4.30</TableCell>
        </TableRow>
        <TableRow>
          <TableCell>iMessage</TableCell>
          <TableCell>412</TableCell>
          <TableCell className="text-right">$8.24</TableCell>
        </TableRow>
      </TableBody>
      <TableFooter>
        <TableRow>
          <TableCell colSpan={2}>Total</TableCell>
          <TableCell className="text-right">$24.58</TableCell>
        </TableRow>
      </TableFooter>
    </Table>
  );
}

```

## Source

components/ui/table.tsx

```tsx
import * as React from "react";

import { cn } from "@/lib/utils";

// The console's table (Figma 427:2715, Email: Mailboxes; iMessage: Agents and lines). Three separate panels: a 48px
// lilac head with 10px corners and 14px muted labels; 8px below it a white body with 8px corners, the Shadow/S ring
// and its short drop, 64px rows of 14px ink ruled by Line/S Bottom; and a lilac foot 8px below (the pagination bar or
// totals). Cells keep 16px sides. The table scrolls sideways inside its frame on a narrow screen.
function Table({ className, ...props }: React.ComponentProps<"table">) {
  return (
    <div data-slot="table-container" className="relative w-full overflow-x-auto px-px pt-px pb-1">
      <table data-slot="table" className={cn("w-full caption-bottom border-separate border-spacing-0 font-sans text-body leading-tight text-fg", className)} {...props} />
    </div>
  );
}

function TableHeader({ className, ...props }: React.ComponentProps<"thead">) {
  return (
    <thead
      data-slot="table-header"
      className={cn(
        "after:table-row after:h-2 after:content-[''] [&>tr>th]:bg-subtle [&>tr>th:first-child]:rounded-l-panel [&>tr>th:last-child]:rounded-r-panel",
        className,
      )}
      {...props}
    />
  );
}

function TableBody({ className, ...props }: React.ComponentProps<"tbody">) {
  return (
    <tbody
      data-slot="table-body"
      className={cn(
        "[&>tr>td]:bg-surface [&>tr:not(:last-child)>td]:border-b [&>tr:not(:last-child)>td]:border-b-line-row [&>tr>td:first-child]:border-l [&>tr>td:first-child]:border-l-line-ring [&>tr>td:last-child]:border-r [&>tr>td:last-child]:border-r-line-ring [&>tr:first-child>td]:border-t [&>tr:first-child>td]:border-t-line-ring [&>tr:first-child>td:first-child]:rounded-tl-control [&>tr:first-child>td:last-child]:rounded-tr-control [&>tr:last-child>td]:border-b [&>tr:last-child>td]:border-b-line-ring [&>tr:last-child]:shadow-[0_2px_4px_-1px_var(--ds-color-shadow-drop)] [&>tr:last-child]:[clip-path:inset(0_-8px_-8px_-8px_round_0_0_8px_8px)] [&>tr:last-child>td:first-child]:rounded-bl-control [&>tr:last-child>td:last-child]:rounded-br-control",
        className,
      )}
      {...props}
    />
  );
}

function TableFooter({ className, ...props }: React.ComponentProps<"tfoot">) {
  return (
    <tfoot
      data-slot="table-footer"
      className={cn(
        "before:table-row before:h-2 before:content-[''] [&>tr>td]:h-10.5 [&>tr>td]:bg-subtle [&>tr>td]:font-medium [&>tr>td:first-child]:rounded-l-panel [&>tr>td:last-child]:rounded-r-panel [&>tr>th]:bg-subtle",
        className,
      )}
      {...props}
    />
  );
}

function TableRow({ className, ...props }: React.ComponentProps<"tr">) {
  return (
    <tr
      data-slot="table-row"
      className={cn("transition-colors duration-150 ease-out hover:[&>td]:bg-subtle/60 data-[state=selected]:[&>td]:bg-subtle motion-reduce:transition-none", className)}
      {...props}
    />
  );
}

function TableHead({ className, ...props }: React.ComponentProps<"th">) {
  return (
    <th
      data-slot="table-head"
      className={cn("h-12 px-4 text-left align-middle text-body leading-tight font-normal whitespace-nowrap text-fg-muted [&:has([role=checkbox])]:w-10 [&:has([role=checkbox])]:pr-0", className)}
      {...props}
    />
  );
}

function TableCell({ className, ...props }: React.ComponentProps<"td">) {
  return (
    <td
      data-slot="table-cell"
      className={cn("h-16 px-4 align-middle whitespace-nowrap transition-colors duration-150 ease-out motion-reduce:transition-none [&:has([role=checkbox])]:w-10 [&:has([role=checkbox])]:pr-0", className)}
      {...props}
    />
  );
}

function TableCaption({ className, ...props }: React.ComponentProps<"caption">) {
  return <caption data-slot="table-caption" className={cn("mt-3 text-body-sm leading-body text-fg-muted", className)} {...props} />;
}

export { Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow };

```

# Tabs
A lilac track of medium labels; the selected tab is a white key with Shadow/S.

Install: npx inkbox-ds add tabs
Requires: theme, utils
Packages: @chakra-ui/react
Exports: Tabs, TabsList, TabsTrigger, TabsContent
Client boundary: yes
Reference: Figma 427:2715: Email, iMessage, Webhooks and Login tabs


## Usage
Use to switch between views of the same thing on a page (Mailboxes, Contact rules, Custom domains). Pass full to TabsList for two equal choices that fill a form's width (Login, Sign up).
- Avoid: Underlined tabs
- Avoid: A purple selected tab
- Avoid: Animating the white key between tabs


## Examples
Example components: npx inkbox-ds add tabs
[Preview](https://inkbox-ds.vercel.app/preview/tabs/Preview) | [Full](https://inkbox-ds.vercel.app/preview/tabs/Full)

examples/tabs.tsx

```tsx
"use client";

import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";

export function Preview() {
  return (
    <Tabs defaultValue="mailboxes" className="w-full">
      <TabsList>
        <TabsTrigger value="mailboxes">Mailboxes</TabsTrigger>
        <TabsTrigger value="rules">Contact rules</TabsTrigger>
        <TabsTrigger value="domains">Custom domains</TabsTrigger>
      </TabsList>
      <TabsContent value="mailboxes" className="text-body text-fg-muted">Manage mailboxes for your organization.</TabsContent>
      <TabsContent value="rules" className="text-body text-fg-muted">Allow or block who can reach each agent.</TabsContent>
      <TabsContent value="domains" className="text-body text-fg-muted">Send and receive from your own domain.</TabsContent>
    </Tabs>
  );
}

export function Full() {
  return (
    <Tabs defaultValue="login" className="w-full max-w-86">
      <TabsList full>
        <TabsTrigger value="login">Login</TabsTrigger>
        <TabsTrigger value="signup">Sign up</TabsTrigger>
      </TabsList>
    </Tabs>
  );
}

```

## Source

components/ui/tabs.tsx

```tsx
"use client";

import * as React from "react";
import { Tabs as ChakraTabs } from "@chakra-ui/react";

import { cn } from "@/lib/utils";

// The console's tabs (Email: Mailboxes, Contact rules, Custom domains; Login and Sign up): a 42px lilac track with
// fully rounded corners and a 2px inset, 38px tabs 8px apart with 9px of side padding and a 14px medium ink label. The selected
// tab is a white key with fully rounded corners and Shadow/S. `full` stretches the tabs to share the track (Login, Sign up).
// Switching is instant: tabs are used many times a day, and the white key moving would only slow the eye.
type TabsProps = Omit<React.ComponentProps<typeof ChakraTabs.Root>, "onValueChange"> & { onValueChange?: (value: string) => void };
function Tabs({ className, onValueChange, ...props }: TabsProps) {
  return <ChakraTabs.Root unstyled data-slot="tabs" className={cn("flex flex-col gap-4", className)} onValueChange={(details) => onValueChange?.(details.value)} {...props} />;
}

function TabsList({ className, full = false, ...props }: React.ComponentProps<typeof ChakraTabs.List> & { full?: boolean }) {
  return (
    <ChakraTabs.List
      data-slot="tabs-list"
      data-full={full ? "true" : undefined}
      className={cn("inline-flex h-10.5 w-fit max-w-full items-center gap-2 overflow-x-auto rounded-pill bg-subtle p-0.5 [scrollbar-width:none]", full && "flex w-full", className)}
      {...props}
    />
  );
}

function TabsTrigger({ className, ...props }: React.ComponentProps<typeof ChakraTabs.Trigger>) {
  return (
    <ChakraTabs.Trigger
      data-slot="tabs-trigger"
      className={cn(
        "inline-flex h-9.5 shrink-0 items-center justify-center gap-2 rounded-pill px-2.25 font-sans text-body leading-tight font-medium whitespace-nowrap text-fg outline-none active:brightness-95 active:transition-none transition-[background-color,box-shadow,color] duration-150 ease-out hover:text-fg-brand focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus-ring disabled:pointer-events-none disabled:text-fg-muted data-[selected]:bg-surface data-[selected]:shadow-s data-[selected]:hover:text-fg motion-reduce:transition-none in-data-[full=true]:flex-1 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-5.5",
        className,
      )}
      {...props}
    />
  );
}

function TabsContent({ className, ...props }: React.ComponentProps<typeof ChakraTabs.Content>) {
  return <ChakraTabs.Content data-slot="tabs-content" className={cn("min-w-0 outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring", className)} {...props} />;
}

export { Tabs, TabsList, TabsTrigger, TabsContent };

```

# Textarea
The field's 8px corners and lilac-gray edge around several lines of 14px text, 72px tall to start.

Install: npx inkbox-ds add textarea
Requires: theme, utils
Packages: @chakra-ui/react
Exports: Textarea
Client boundary: yes
Reference: Figma 427:2715: Agent Description (Form- Input, 72px) in Create Agent Identity


## Usage
Use for free text longer than a line (Agent Description, a note, a message). Label it above like Input. It grows with its content; set rows or a min-h class to change the starting height.
- Avoid: A textarea without a label
- Avoid: A gray background for an editable value
- Avoid: A fixed height that hides what was typed


## Examples
Example components: npx inkbox-ds add textarea label
[Preview](https://inkbox-ds.vercel.app/preview/textarea/Preview) | [States](https://inkbox-ds.vercel.app/preview/textarea/States)

examples/textarea.tsx

```tsx
import { Label } from "@/components/ui/label";
import { Textarea } from "@/components/ui/textarea";

export function Preview() {
  return (
    <div className="grid w-full max-w-100.5 gap-1">
      <Label htmlFor="description">Agent description</Label>
      <Textarea id="description" placeholder="Agent Description" />
    </div>
  );
}

export function States() {
  return (
    <div className="grid w-full max-w-100.5 gap-3">
      <Textarea aria-label="Note" defaultValue="Answers billing questions for Acme and forwards anything about refunds to Robert." />
      <Textarea aria-label="Invalid note" defaultValue="" placeholder="Required" aria-invalid />
      <Textarea aria-label="Read-only" readOnly defaultValue="Created by the Inkbox CLI on Jul 27, 2026." />
      <Textarea aria-label="Disabled" disabled placeholder="Disabled" />
    </div>
  );
}

```

## Source

components/ui/textarea.tsx

```tsx
"use client";

import * as React from "react";
import { Textarea as ChakraTextarea } from "@chakra-ui/react";

import { cn } from "@/lib/utils";

// The console's multi-line field (Agent Description in Create Agent Identity, 72px tall): the field's 8px corners and
// lilac-gray edge on white, 14px ink on 20px lines with 10px above and 14px at the sides, the light purple placeholder.
// It grows with its content (field-sizing), from 72px. Focus, invalid and read-only states match Input.
function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
  return (
    <ChakraTextarea
      unstyled
      data-slot="textarea"
      className={cn(
        "field-sizing-content flex min-h-18 w-full min-w-0 resize rounded-control border border-line-field bg-surface px-3.5 py-2.5 font-sans text-body leading-5 text-fg outline-none transition-[border-color,box-shadow] duration-150 ease-out placeholder:text-fg-subtle selection:bg-ring-tint focus-visible:border-line-brand focus-visible:shadow-focus aria-invalid:border-danger aria-invalid:focus-visible:shadow-none read-only:bg-subtle read-only:text-fg-muted disabled:cursor-not-allowed disabled:bg-subtle disabled:text-fg-muted motion-reduce:transition-none",
        className,
      )}
      {...props}
    />
  );
}

export { Textarea };

```

# Toast
The Radix toast API in the same white floating look, with an outline action and a red edge for destructive toasts.

Install: npx inkbox-ds add toast
Requires: theme, utils
Packages: radix-ui, class-variance-authority, @phosphor-icons/react
Exports: Toast, ToastAction, ToastClose, ToastDescription, Toaster, ToastProvider, ToastTitle, ToastViewport, toast, useToast, ToastActionElement, ToastProps
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): white floating panels and outline keys


## Usage
Use when an app already calls the older toast() and useToast() API. Mount Toaster once and call toast({ title, description, action }); pass variant destructive for failures. For new work, use Sonner.
- Avoid: Stacking more than three toasts
- Avoid: A toast that needs a decision before work continues
- Avoid: A purple or dark toast


## Examples
Example components: npx inkbox-ds add toast button
[Preview](https://inkbox-ds.vercel.app/preview/toast/Preview)

examples/toast.tsx

```tsx
"use client";

import { Button } from "@/components/ui/button";
import { ToastAction, Toaster, useToast } from "@/components/ui/toast";

export function Preview() {
  const { toast } = useToast();
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Toaster />
      <Button
        variant="outline"
        onClick={() =>
          toast({
            title: "Mailbox archived",
            description: "support@inkboxmail.com no longer receives mail.",
            action: <ToastAction altText="Undo the archive">Undo</ToastAction>,
          })
        }
      >
        Archive mailbox
      </Button>
      <Button
        variant="outline"
        onClick={() =>
          toast({
            variant: "destructive",
            title: "Delivery failed",
            description: "api.acme.dev answered 500 three times.",
            action: <ToastAction altText="Retry the delivery">Retry</ToastAction>,
          })
        }
      >
        Destructive
      </Button>
      <Button variant="outline" onClick={() => toast({ title: "Contact rule saved" })}>
        Title only
      </Button>
    </div>
  );
}

```

## Source

components/ui/toast.tsx

```tsx
"use client";

import * as React from "react";
import { Toast as ToastPrimitive } from "radix-ui";
import { cva, type VariantProps } from "class-variance-authority";
import { XIcon } from "@phosphor-icons/react/ssr";

import { cn } from "@/lib/utils";

// The Radix toast (shadcn's older toast API; prefer Sonner for new work). Same look as the Sonner toasts (extrapolated
// from the Inkbox console, Figma 427:2715): a white panel with 16px corners, the floating shadow and 16px of padding, a
// 14px medium ink title over a 14px muted description, an outline action key and a faint close glyph. `destructive`
// edges it in red with a red title. It slides in from the right edge it lives on (300ms, the drawer curve) and fades
// out faster; a swipe to the right drags it with the finger and lets it go.
const ToastProvider = ToastPrimitive.Provider;

function ToastViewport({ className, ...props }: React.ComponentProps<typeof ToastPrimitive.Viewport>) {
  return (
    <ToastPrimitive.Viewport
      data-slot="toast-viewport"
      className={cn("fixed right-0 bottom-0 z-[100] flex max-h-dvh w-full flex-col-reverse gap-2 p-4 outline-none sm:max-w-sm sm:flex-col", className)}
      {...props}
    />
  );
}

const toastVariants = cva(
  "group/toast pointer-events-auto relative flex w-full items-start justify-between gap-3 overflow-hidden rounded-panel bg-surface p-4 pr-10 font-sans text-fg shadow-floating data-[state=closed]:animate-fade-out data-[state=open]:animate-sheet-in-right data-[swipe=cancel]:translate-x-0 data-[swipe=cancel]:transition-[translate] data-[swipe=cancel]:duration-200 data-[swipe=cancel]:ease-out data-[swipe=end]:translate-x-(--radix-toast-swipe-end-x) data-[swipe=end]:animate-fade-out data-[swipe=move]:translate-x-(--radix-toast-swipe-move-x) data-[swipe=move]:transition-none motion-reduce:data-[swipe=cancel]:transition-none",
  {
    variants: {
      variant: {
        default: "",
        destructive: "border border-danger [&_[data-slot=toast-title]]:text-danger-strong",
      },
    },
    defaultVariants: { variant: "default" },
  },
);

function Toast({ className, variant, ...props }: React.ComponentProps<typeof ToastPrimitive.Root> & VariantProps<typeof toastVariants>) {
  return <ToastPrimitive.Root data-slot="toast" data-variant={variant ?? "default"} className={cn(toastVariants({ variant }), className)} {...props} />;
}

function ToastAction({ className, ...props }: React.ComponentProps<typeof ToastPrimitive.Action>) {
  return (
    <ToastPrimitive.Action
      data-slot="toast-action"
      className={cn(
        "inline-flex h-8 shrink-0 items-center justify-center self-center rounded-pill border border-line-field bg-surface px-2.5 font-sans text-body leading-tight font-medium text-fg-brand outline-none transition-[background-color] duration-150 ease-out hover:bg-subtle active:bg-subtle active:brightness-95 active:transition-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring disabled:pointer-events-none disabled:opacity-50 group-data-[variant=destructive]/toast:text-danger-strong motion-reduce:transition-none",
        className,
      )}
      {...props}
    />
  );
}

function ToastClose({ className, ...props }: React.ComponentProps<typeof ToastPrimitive.Close>) {
  return (
    <ToastPrimitive.Close
      data-slot="toast-close"
      aria-label="Close"
      className={cn("absolute top-3 right-3 inline-flex size-6 items-center justify-center rounded-pill text-fg-faint outline-none active:brightness-95 active:transition-none transition-colors duration-150 ease-out hover:text-fg-muted focus-visible:outline-2 focus-visible:outline-focus-ring motion-reduce:transition-none", className)}
      {...props}
    >
      <XIcon className="size-4" />
    </ToastPrimitive.Close>
  );
}

function ToastTitle({ className, ...props }: React.ComponentProps<typeof ToastPrimitive.Title>) {
  return <ToastPrimitive.Title data-slot="toast-title" className={cn("text-body leading-body font-medium text-fg", className)} {...props} />;
}

function ToastDescription({ className, ...props }: React.ComponentProps<typeof ToastPrimitive.Description>) {
  return <ToastPrimitive.Description data-slot="toast-description" className={cn("text-body leading-body text-fg-muted", className)} {...props} />;
}

type ToastProps = React.ComponentProps<typeof Toast>;
type ToastActionElement = React.ReactElement<React.ComponentProps<typeof ToastAction>>;

// The toast queue: a tiny store any part of the app can push to with toast(), read by useToast() and <Toaster />.
const TOAST_LIMIT = 3;
const REMOVE_DELAY = 1000;

type ToasterToast = ToastProps & { id: string; title?: React.ReactNode; description?: React.ReactNode; action?: ToastActionElement };
type State = { toasts: ToasterToast[] };

let count = 0;
const nextId = () => String((count = (count + 1) % Number.MAX_SAFE_INTEGER));
const listeners: Array<(state: State) => void> = [];
let memory: State = { toasts: [] };
const timeouts = new Map<string, ReturnType<typeof setTimeout>>();

function setState(update: (state: State) => State) {
  memory = update(memory);
  listeners.forEach((l) => l(memory));
}

function scheduleRemove(id: string) {
  if (timeouts.has(id)) return;
  // ds-latency: removes an already dismissed toast from memory; dismissal and input stay immediate.
  timeouts.set(id, setTimeout(() => {
    timeouts.delete(id);
    setState((s) => ({ toasts: s.toasts.filter((t) => t.id !== id) }));
  }, REMOVE_DELAY));
}

function dismiss(id?: string) {
  setState((s) => ({ toasts: s.toasts.map((t) => (id === undefined || t.id === id ? { ...t, open: false } : t)) }));
  memory.toasts.filter((t) => id === undefined || t.id === id).forEach((t) => scheduleRemove(t.id));
}

function toast(props: Omit<ToasterToast, "id">) {
  const id = nextId();
  const update = (next: Partial<ToasterToast>) => setState((s) => ({ toasts: s.toasts.map((t) => (t.id === id ? { ...t, ...next } : t)) }));
  setState((s) => ({
    toasts: [{ ...props, id, open: true, onOpenChange: (open: boolean) => { if (!open) dismiss(id); props.onOpenChange?.(open); } }, ...s.toasts].slice(0, TOAST_LIMIT),
  }));
  return { id, dismiss: () => dismiss(id), update };
}

function useToast() {
  const [state, setLocal] = React.useState(memory);
  React.useEffect(() => {
    listeners.push(setLocal);
    return () => {
      const i = listeners.indexOf(setLocal);
      if (i > -1) listeners.splice(i, 1);
    };
  }, []);
  return { ...state, toast, dismiss };
}

/** Renders the queue. Mount it once, near the root. */
function Toaster() {
  const { toasts } = useToast();
  return (
    <ToastProvider swipeDirection="right">
      {toasts.map(({ id, title, description, action, ...props }) => (
        <Toast key={id} {...props}>
          <div className="grid min-w-0 gap-0.5">
            {title && <ToastTitle>{title}</ToastTitle>}
            {description && <ToastDescription>{description}</ToastDescription>}
          </div>
          {action}
          <ToastClose />
        </Toast>
      ))}
      <ToastViewport />
    </ToastProvider>
  );
}

export { Toast, ToastAction, ToastClose, ToastDescription, Toaster, ToastProvider, ToastTitle, ToastViewport, toast, useToast };
export type { ToastActionElement, ToastProps };

```

# Toggle Group
The segmented choice: a lilac track of 38px choices where the chosen one is a white key with Shadow/S.

Install: npx inkbox-ds add toggle-group
Requires: theme, toggle, utils
Packages: radix-ui, class-variance-authority
Exports: ToggleGroup, ToggleGroupItem
Client boundary: yes
Reference: Figma 427:2715: Where does this agent run? in Modal - Created


## Usage
Use for a choice among a few options that changes what is shown next (Where does this agent run? Hermes, Openclaw, Codex, Claude Code). Use type single for one choice, multiple for several. Put a 24px logo tile or a 20px glyph before each label. Use variant outline for separate keys.
- Avoid: A purple chosen key
- Avoid: A sliding indicator between choices
- Avoid: More than seven choices in one track


## Examples
Example components: npx inkbox-ds add toggle-group
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/toggle-group/Preview) | [Outline](https://inkbox-ds.vercel.app/preview/toggle-group/Outline) | [Sizes](https://inkbox-ds.vercel.app/preview/toggle-group/Sizes)

examples/toggle-group.tsx

```tsx
"use client";

import * as React from "react";
import { CodeIcon, CodeBlockIcon, LightningIcon, RobotIcon, SparkleIcon, TerminalWindowIcon, TextAlignCenterIcon, TextAlignLeftIcon, TextAlignRightIcon } from "@phosphor-icons/react/ssr";

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

// The runners as 24px logo tiles; a real app puts each runner's own logo in the tile.
const RUNNERS = [
  { value: "hermes", label: "Hermes", icon: RobotIcon },
  { value: "openclaw", label: "Openclaw", icon: LightningIcon },
  { value: "codex", label: "Codex", icon: TerminalWindowIcon },
  { value: "claude-code", label: "Claude Code", icon: SparkleIcon },
  { value: "opencode", label: "OpenCode", icon: CodeBlockIcon },
];

export function Preview() {
  const [runner, setRunner] = React.useState("hermes");
  return (
    <div className="grid w-full gap-3">
      <p id="runner" className="text-body leading-tight font-medium text-fg">Where does this agent run?</p>
      <ToggleGroup type="single" value={runner} onValueChange={(v) => v && setRunner(v)} aria-labelledby="runner" className="w-full">
        {RUNNERS.map(({ value, label, icon: Icon }) => (
          <ToggleGroupItem key={value} value={value}>
            <span className="flex size-6 items-center justify-center rounded-pill bg-surface text-fg-brand shadow-s">
              <Icon weight="fill" className="size-4" />
            </span>
            {label}
          </ToggleGroupItem>
        ))}
        <ToggleGroupItem value="other">
          <CodeIcon weight="bold" />
          Other
        </ToggleGroupItem>
      </ToggleGroup>
    </div>
  );
}

export function Outline() {
  return (
    <ToggleGroup type="multiple" variant="outline" defaultValue={["email"]} aria-label="Channels">
      <ToggleGroupItem value="email">Email</ToggleGroupItem>
      <ToggleGroupItem value="phone">Phone</ToggleGroupItem>
      <ToggleGroupItem value="imessage">iMessage</ToggleGroupItem>
    </ToggleGroup>
  );
}

export function Sizes() {
  return (
    <div className="grid gap-3">
      <ToggleGroup type="single" size="sm" defaultValue="left" aria-label="Alignment, small">
        <ToggleGroupItem value="left" aria-label="Align left">
          <TextAlignLeftIcon weight="bold" />
        </ToggleGroupItem>
        <ToggleGroupItem value="center" aria-label="Align center">
          <TextAlignCenterIcon weight="bold" />
        </ToggleGroupItem>
        <ToggleGroupItem value="right" aria-label="Align right">
          <TextAlignRightIcon weight="bold" />
        </ToggleGroupItem>
      </ToggleGroup>
      <ToggleGroup type="single" spacing={0} defaultValue="day" aria-label="Range">
        <ToggleGroupItem value="day">Day</ToggleGroupItem>
        <ToggleGroupItem value="week">Week</ToggleGroupItem>
        <ToggleGroupItem value="month">Month</ToggleGroupItem>
        <ToggleGroupItem value="year" disabled>
          Year
        </ToggleGroupItem>
      </ToggleGroup>
      <ToggleGroup type="single" orientation="vertical" defaultValue="inbox" aria-label="Folder" className="w-48">
        <ToggleGroupItem value="inbox" className="justify-start">Inbox</ToggleGroupItem>
        <ToggleGroupItem value="sent" className="justify-start">Sent</ToggleGroupItem>
        <ToggleGroupItem value="spam" className="justify-start">Spam</ToggleGroupItem>
      </ToggleGroup>
    </div>
  );
}

```

## Source

components/ui/toggle-group.tsx

```tsx
"use client";

import * as React from "react";
import { ToggleGroup as ToggleGroupPrimitive } from "radix-ui";
import { type VariantProps } from "class-variance-authority";

import { toggleVariants } from "@/components/ui/toggle";
import { cn } from "@/lib/utils";

// The console's segmented choice (Figma 427:2715, Modal - Created: "Where does this agent run?"): a lilac track with
// 10px corners and a 2px inset holding 38px choices 8px apart; each choice is a 24px logo tile 8px from a 14px medium
// ink label, 8px from the sides, and the chosen one is a white key with 8px corners and Shadow/S. With `spacing={0}`
// the choices sit flush in the track. `variant="outline"` drops the track: separate keys with the field edge, the chosen
// one white with Shadow/S. Choosing is instant (no sliding key): the choice is made often and must feel immediate.
const ToggleGroupContext = React.createContext<VariantProps<typeof toggleVariants> & { spacing?: number; orientation?: "horizontal" | "vertical" }>({
  size: "default",
  variant: "default",
  spacing: 2,
  orientation: "horizontal",
});

function ToggleGroup({
  className,
  variant = "default",
  size = "default",
  spacing = 2,
  orientation = "horizontal",
  children,
  ...props
}: React.ComponentProps<typeof ToggleGroupPrimitive.Root> & VariantProps<typeof toggleVariants> & { spacing?: number; orientation?: "horizontal" | "vertical" }) {
  return (
    <ToggleGroupPrimitive.Root
      data-slot="toggle-group"
      data-variant={variant}
      data-size={size}
      data-spacing={spacing}
      data-orientation={orientation}
      orientation={orientation}
      style={{ "--gap": spacing } as React.CSSProperties}
      className={cn(
        "group/toggle-group flex w-fit max-w-full items-center gap-[calc(var(--spacing)*var(--gap))] data-[orientation=vertical]:flex-col data-[orientation=vertical]:items-stretch",
        variant === "default" && "overflow-x-auto rounded-pill data-[orientation=vertical]:rounded-dialog bg-subtle p-0.5 [scrollbar-width:none]",
        className,
      )}
      {...props}
    >
      <ToggleGroupContext.Provider value={{ variant, size, spacing, orientation }}>{children}</ToggleGroupContext.Provider>
    </ToggleGroupPrimitive.Root>
  );
}

function ToggleGroupItem({ className, children, variant, size, ...props }: React.ComponentProps<typeof ToggleGroupPrimitive.Item> & VariantProps<typeof toggleVariants>) {
  const context = React.useContext(ToggleGroupContext);
  const v = context.variant || variant || "default";
  return (
    <ToggleGroupPrimitive.Item
      data-slot="toggle-group-item"
      data-variant={v}
      data-size={context.size || size}
      data-spacing={context.spacing}
      className={cn(
        toggleVariants({ variant: v, size: context.size || size }),
        // In the track the chosen choice is the white key, as in the segmented choice.
        v === "default" && "hover:bg-subtle-hover data-[state=on]:bg-surface data-[state=on]:text-fg data-[state=on]:shadow-s data-[state=on]:hover:bg-surface",
        "focus-visible:z-10",
        className,
      )}
      {...props}
    >
      {children}
    </ToggleGroupPrimitive.Item>
  );
}

export { ToggleGroup, ToggleGroupItem };

```

# Toggle
A 38px key with a glyph or a medium label that holds the lilac (or turns white in outline) while pressed.

Install: npx inkbox-ds add toggle
Requires: theme, utils
Packages: radix-ui, class-variance-authority
Exports: Toggle, toggleVariants
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the soft key (Tunnel quickstart) and the segmented choice


## Usage
Use for a two-state control that changes how something shows (bold, show archived, pin). Give an icon-only toggle an aria-label. For a group of exclusive choices use Toggle Group; for a setting use Switch.
- Avoid: A toggle that submits a form
- Avoid: A purple filled toggle
- Avoid: Icon motion when it turns on


## Examples
Example components: npx inkbox-ds add toggle
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/toggle/Preview) | [Variants](https://inkbox-ds.vercel.app/preview/toggle/Variants)

examples/toggle.tsx

```tsx
"use client";

import { ArchiveIcon, PushPinIcon, TextBIcon, TextItalicIcon } from "@phosphor-icons/react/ssr";

import { Toggle } from "@/components/ui/toggle";

export function Preview() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Toggle aria-label="Pin the thread" defaultPressed>
        <PushPinIcon weight="fill" />
      </Toggle>
      <Toggle>
        <ArchiveIcon weight="fill" />
        Show archived
      </Toggle>
    </div>
  );
}

export function Variants() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Toggle variant="outline" aria-label="Bold" defaultPressed>
        <TextBIcon weight="bold" />
      </Toggle>
      <Toggle variant="outline" aria-label="Italic">
        <TextItalicIcon weight="bold" />
      </Toggle>
      <Toggle size="sm" aria-label="Pin, small">
        <PushPinIcon weight="fill" />
      </Toggle>
      <Toggle size="lg">Large</Toggle>
      <Toggle disabled>Disabled</Toggle>
    </div>
  );
}

```

## Source

components/ui/toggle.tsx

```tsx
"use client";

import * as React from "react";
import { Toggle as TogglePrimitive } from "radix-ui";
import { cva, type VariantProps } from "class-variance-authority";

import { cn } from "@/lib/utils";

// Extrapolated from the console's soft key (Tunnel quickstart) and its segmented choice (Where does this agent run?):
// a 38px key with fully rounded corners, 8px of side padding and a 14px medium ink label beside a 20px glyph. Off it is bare and
// washes lilac under the pointer; on it holds the lilac. `outline` adds the field edge and turns white with the Shadow/S
// ring when on. In a ToggleGroup the default variant becomes the segmented track (see toggle-group). Press feedback is immediate and changes styling without resizing.
const toggleVariants = cva(
  "inline-flex shrink-0 cursor-pointer items-center justify-center gap-2 rounded-pill font-sans text-body leading-tight font-medium whitespace-nowrap text-fg outline-none select-none transition-[background-color,box-shadow,color] duration-150 ease-out active:brightness-95 active:transition-none focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus-ring disabled:pointer-events-none disabled:opacity-50 aria-invalid:text-danger motion-reduce:transition-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-5.5",
  {
    variants: {
      variant: {
        default: "bg-transparent hover:bg-subtle data-[state=on]:bg-subtle data-[state=on]:text-fg-brand",
        outline: "border border-line-field bg-surface hover:bg-subtle data-[state=on]:border-transparent data-[state=on]:bg-surface data-[state=on]:text-fg-brand data-[state=on]:shadow-s",
      },
      size: {
        default: "h-9.5 min-w-9.5 px-2",
        sm: "h-8 min-w-8 px-1.5 text-body-sm [&_svg:not([class*='size-'])]:size-4",
        lg: "h-10.5 min-w-10.5 px-3",
      },
    },
    defaultVariants: { variant: "default", size: "default" },
  },
);

function Toggle({ className, variant, size, ...props }: React.ComponentProps<typeof TogglePrimitive.Root> & VariantProps<typeof toggleVariants>) {
  return <TogglePrimitive.Root data-slot="toggle" className={cn(toggleVariants({ variant, size, className }))} {...props} />;
}

export { Toggle, toggleVariants };

```

# Tooltip
A short ink label with white 13px text, 16px corners and a small arrow.

Install: npx inkbox-ds add tooltip
Requires: theme, surface, utils
Packages: radix-ui
Exports: Tooltip, TooltipContent, TooltipProvider, TooltipTrigger
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the info glyphs beside Tunnel, Connection, TLS and Tunnel TLS mode


## Usage
Use to explain an icon button or an info glyph in a few words (Tunnel, Connection, TLS). Wrap a toolbar or page in TooltipProvider so neighboring tooltips open at once after the first.
- Avoid: Essential information only in a tooltip
- Avoid: Interactive content inside a tooltip
- Avoid: Sentences longer than one line or two
- Avoid: A white tooltip


## Examples
Example components: npx inkbox-ds add tooltip button
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/tooltip/Preview) | [Info](https://inkbox-ds.vercel.app/preview/tooltip/Info)

examples/tooltip.tsx

```tsx
import { ArrowsClockwiseIcon, GearSixIcon, InfoIcon, PencilSimpleIcon } from "@phosphor-icons/react/ssr";

import { Button } from "@/components/ui/button";
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip";

export function Preview() {
  return (
    <TooltipProvider>
      <div className="flex items-center gap-1">
        <Tooltip>
          <TooltipTrigger asChild>
            <Button variant="ghost" size="icon" aria-label="Edit mailbox">
              <PencilSimpleIcon weight="fill" />
            </Button>
          </TooltipTrigger>
          <TooltipContent>Edit mailbox</TooltipContent>
        </Tooltip>
        <Tooltip>
          <TooltipTrigger asChild>
            <Button variant="ghost" size="icon" aria-label="Refresh">
              <ArrowsClockwiseIcon />
            </Button>
          </TooltipTrigger>
          <TooltipContent>Refresh</TooltipContent>
        </Tooltip>
        <Tooltip>
          <TooltipTrigger asChild>
            <Button variant="ghost" size="icon" aria-label="Mailbox settings">
              <GearSixIcon weight="fill" />
            </Button>
          </TooltipTrigger>
          <TooltipContent>Mailbox settings</TooltipContent>
        </Tooltip>
      </div>
    </TooltipProvider>
  );
}

export function Info() {
  return (
    <div className="flex min-h-40 items-start justify-center pt-14">
      <p className="flex items-center gap-1.5 text-body text-fg">
        Tunnel TLS mode
        <Tooltip defaultOpen>
          <TooltipTrigger className="rounded-pill text-fg-label outline-none focus-visible:outline-2 focus-visible:outline-focus-ring" aria-label="About TLS modes">
            <InfoIcon weight="fill" className="size-4.5" />
          </TooltipTrigger>
          <TooltipContent side="top">Edge ends TLS at Inkbox. Passthrough sends it to your agent.</TooltipContent>
        </Tooltip>
      </p>
    </div>
  );
}

```

## Source

components/ui/tooltip.tsx

```tsx
"use client";

import * as React from "react";
import { Tooltip as TooltipPrimitive } from "radix-ui";

import { usePortalContainer } from "@/lib/surface";
import { cn } from "@/lib/utils";

// A tooltip, extrapolated from the console's info glyphs (Figma 427:2715: Tunnel, Connection, TLS, Tunnel TLS mode):
// the ink with 13px white text, 16px corners, 6px by 10px of padding and a small ink arrow. The first one waits 400ms;
// once one is open its neighbors open at once and without motion (the provider's skip delay), as a toolbar should.
// Whether a TooltipProvider is above: tooltips under one share its delay, so neighbors open at once. A lone Tooltip
// brings its own provider. The dwell avoids incidental hover popups; it never delays the underlying button action.
const HasProvider = React.createContext(false);

function TooltipProvider({ delayDuration = 400, skipDelayDuration = 300, ...props }: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
  return (
    <HasProvider.Provider value>
      <TooltipPrimitive.Provider data-slot="tooltip-provider" delayDuration={delayDuration} skipDelayDuration={skipDelayDuration} {...props} />
    </HasProvider.Provider>
  );
}

function Tooltip(props: React.ComponentProps<typeof TooltipPrimitive.Root>) {
  const root = <TooltipPrimitive.Root data-slot="tooltip" {...props} />;
  return React.useContext(HasProvider) ? root : <TooltipProvider>{root}</TooltipProvider>;
}

function TooltipTrigger(props: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />;
}

function TooltipContent({ className, sideOffset = 6, children, ...props }: React.ComponentProps<typeof TooltipPrimitive.Content>) {
  const container = usePortalContainer();
  return (
    <TooltipPrimitive.Portal container={container}>
      <TooltipPrimitive.Content
        data-slot="tooltip-content"
        sideOffset={sideOffset}
        className={cn(
          "z-50 w-fit max-w-72 origin-(--radix-tooltip-content-transform-origin) rounded-panel bg-inverse px-2.5 py-1.5 font-sans text-body-sm leading-tight text-balance text-fg-inverse data-[state=closed]:animate-fade-out data-[state=delayed-open]:animate-fade-in",
          className,
        )}
        {...props}
      >
        {children}
        <TooltipPrimitive.Arrow className="z-50 fill-inverse" width={10} height={5} />
      </TooltipPrimitive.Content>
    </TooltipPrimitive.Portal>
  );
}

export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger };

```

# Trace
An agent's steps as quiet 14px lines with a glyph, a running step that breathes and steps that open to their detail on a hairline.

Install: npx inkbox-ds add trace
Requires: theme, collapsible, utils
Packages: @phosphor-icons/react
Exports: Trace, TraceCollapsible, TraceCollapsibleContent, TraceCollapsibleTrigger, TraceDescription, TraceIcon, TraceLine, TraceTitle
Client boundary: yes
Reference: Extrapolated from the Inkbox console (Figma 427:2715): the inbox list's muted text and the Advanced settings disclosure


## Usage
Use to show what an agent did or is doing: each TraceLine has a TraceIcon (a filled Phosphor glyph for the tool), a TraceTitle and an optional TraceDescription (a duration or a count). Set status running, pending or error. Put a step with detail in TraceCollapsible with a TraceCollapsibleTrigger around its line and the detail in TraceCollapsibleContent. Wrap a line in a link or button to make it open something.
- Avoid: Bold or ink step titles
- Avoid: A spinner on every running step
- Avoid: Colors other than the muted purple and red
- Avoid: Detail that opens without its hairline


## Examples
Example components: npx inkbox-ds add trace
Example packages: @phosphor-icons/react
[Preview](https://inkbox-ds.vercel.app/preview/trace/Preview) | [Failed](https://inkbox-ds.vercel.app/preview/trace/Failed) | [Linked](https://inkbox-ds.vercel.app/preview/trace/Linked)

examples/trace.tsx

```tsx
import { EnvelopeSimpleIcon, LightningIcon, MagnifyingGlassIcon, PaperPlaneTiltIcon, PhoneIcon, VaultIcon, WarningCircleIcon } from "@phosphor-icons/react/ssr";

import { Trace, TraceCollapsible, TraceCollapsibleContent, TraceCollapsibleTrigger, TraceDescription, TraceIcon, TraceLine, TraceTitle } from "@/components/ui/trace";

export function Preview() {
  return (
    <Trace className="mx-auto max-w-120">
      <TraceLine>
        <TraceIcon>
          <EnvelopeSimpleIcon weight="fill" />
        </TraceIcon>
        <TraceTitle>Read 3 new emails in acme@inkboxmail.com</TraceTitle>
        <TraceDescription>0.8s</TraceDescription>
      </TraceLine>
      <TraceCollapsible defaultOpen>
        <TraceCollapsibleTrigger>
          <TraceLine>
            <TraceIcon>
              <MagnifyingGlassIcon weight="bold" />
            </TraceIcon>
            <TraceTitle>Searched the Agent2Agent directory</TraceTitle>
            <TraceDescription>2 results</TraceDescription>
          </TraceLine>
        </TraceCollapsibleTrigger>
        <TraceCollapsibleContent>
          Found <span className="font-mono text-fg">@summarize</span> and <span className="font-mono text-fg">@translate</span>, both public and accepting delegated tasks.
        </TraceCollapsibleContent>
      </TraceCollapsible>
      <TraceLine status="running">
        <TraceIcon>
          <PaperPlaneTiltIcon weight="fill" />
        </TraceIcon>
        <TraceTitle>Sending the summary to ray@inkbox.ai</TraceTitle>
      </TraceLine>
      <TraceLine status="pending">
        <TraceIcon>
          <PhoneIcon weight="fill" />
        </TraceIcon>
        <TraceTitle>Call +1 650 474 9720 with the result</TraceTitle>
      </TraceLine>
    </Trace>
  );
}

export function Failed() {
  return (
    <Trace className="mx-auto max-w-120">
      <TraceLine>
        <TraceIcon>
          <VaultIcon weight="fill" />
        </TraceIcon>
        <TraceTitle>Unlocked the vault</TraceTitle>
        <TraceDescription>0.2s</TraceDescription>
      </TraceLine>
      <TraceCollapsible>
        <TraceCollapsibleTrigger>
          <TraceLine status="error">
            <TraceIcon>
              <WarningCircleIcon weight="fill" />
            </TraceIcon>
            <TraceTitle>Webhook delivery to https://example.com/inkbox failed</TraceTitle>
          </TraceLine>
        </TraceCollapsibleTrigger>
        <TraceCollapsibleContent>
          The endpoint answered <span className="font-mono text-fg">503 Service Unavailable</span>. Inkbox logs the failure and keeps processing mail.
        </TraceCollapsibleContent>
      </TraceCollapsible>
      <TraceLine>
        <TraceIcon>
          <LightningIcon weight="fill" />
        </TraceIcon>
        <TraceTitle>Retry scheduled</TraceTitle>
        <TraceDescription>in 30s</TraceDescription>
      </TraceLine>
    </Trace>
  );
}

export function Linked() {
  return (
    <Trace className="mx-auto max-w-120">
      <a href="#message">
        <TraceLine>
          <TraceIcon>
            <EnvelopeSimpleIcon weight="fill" />
          </TraceIcon>
          <TraceTitle>Opened Inkbox A2A: publish your Agent Card</TraceTitle>
        </TraceLine>
      </a>
      <button type="button">
        <TraceLine>
          <TraceIcon>
            <PaperPlaneTiltIcon weight="fill" />
          </TraceIcon>
          <TraceTitle>Drafted a reply</TraceTitle>
        </TraceLine>
      </button>
    </Trace>
  );
}

```

## Source

components/ui/trace.tsx

```tsx
"use client";

import * as React from "react";
import { CaretRightIcon } from "@phosphor-icons/react/ssr";

import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible";
import { cn } from "@/lib/utils";

// An agent's steps as it works (extrapolated from the console, Figma 427:2715: the inbox's muted dates and the
// "Advanced settings" disclosure). Each line is 14px muted purple with an 18px glyph 8px before it; a line that is a
// link or button turns ink under the pointer. A running step breathes (1.6s, held still with reduced motion), a pending
// one is faded, a failed one is red. A step that can open shows a caret after its title that turns a quarter when open;
// its detail hangs from a hairline 16px in, in 14px secondary ink, and opens with its height (200ms, the strong ease-out).
function Trace({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="trace"
      className={cn(
        "flex w-full min-w-0 flex-col gap-2 *:has-[>[data-slot=trace-line]]:flex *:has-[>[data-slot=trace-line]]:w-fit *:has-[>[data-slot=trace-line]]:max-w-full *:has-[>[data-slot=trace-line]]:min-w-0 *:has-[>[data-slot=trace-line]]:rounded-pill *:has-[>[data-slot=trace-line]]:text-left *:has-[>[data-slot=trace-line]]:outline-none *:has-[>[data-slot=trace-line]]:focus-visible:outline-2 *:has-[>[data-slot=trace-line]]:focus-visible:outline-offset-2 *:has-[>[data-slot=trace-line]]:focus-visible:outline-focus-ring",
        className,
      )}
      {...props}
    />
  );
}

function TraceLine({ className, status, ...props }: React.ComponentProps<"span"> & { status?: "running" | "error" | "pending" }) {
  return (
    <span
      data-slot="trace-line"
      data-status={status}
      className={cn(
        "flex w-fit max-w-full min-w-0 items-center gap-2 font-sans text-body leading-body text-fg-muted transition-colors duration-150 ease-out in-[a,button]:cursor-pointer in-[a:hover,button:hover]:text-fg data-[status=error]:text-danger data-[status=error]:in-[a:hover,button:hover]:text-danger-strong data-[status=pending]:opacity-60 data-[status=running]:*:data-[slot=trace-title]:animate-pulse-soft motion-reduce:transition-none motion-reduce:data-[status=running]:*:data-[slot=trace-title]:animate-none",
        className,
      )}
      {...props}
    />
  );
}

function TraceIcon({ className, ...props }: React.ComponentProps<"span">) {
  return (
    <span
      data-slot="trace-icon"
      aria-hidden="true"
      className={cn("flex size-4.5 shrink-0 items-center justify-center [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4.5 [[data-slot=trace-title]~&]:-ml-1", className)}
      {...props}
    />
  );
}

function TraceTitle({ className, ...props }: React.ComponentProps<"span">) {
  return <span data-slot="trace-title" className={cn("min-w-0 truncate", className)} {...props} />;
}

/** A step's quiet detail at its end: a duration or a count, in the faint purple with even figures. */
function TraceDescription({ className, ...props }: React.ComponentProps<"span">) {
  return <span data-slot="trace-description" className={cn("shrink-0 text-fg-subtle tabular-nums", className)} {...props} />;
}

function TraceCollapsible({
  className,
  ...props
}: Omit<React.ComponentProps<typeof Collapsible>, "asChild" | "open"> & ({ open?: undefined } | { open: boolean; onOpenChange: NonNullable<React.ComponentProps<typeof Collapsible>["onOpenChange"]> })) {
  return <Collapsible data-slot="trace-collapsible" className={cn("flex w-full min-w-0 flex-col", className)} {...props} />;
}

function TraceCollapsibleTrigger({ className, children, ...props }: Omit<React.ComponentProps<typeof CollapsibleTrigger>, "asChild">) {
  return (
    <CollapsibleTrigger
      data-slot="trace-collapsible-trigger"
      className={cn(
        "group/trace-collapsible-trigger flex w-fit max-w-full min-w-0 cursor-pointer items-center gap-1 rounded-pill text-left text-fg-muted outline-none active:brightness-95 active:transition-none transition-colors duration-150 ease-out hover:text-fg focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring has-[[data-status=error]]:text-danger motion-reduce:transition-none",
        className,
      )}
      {...props}
    >
      {children}
      <TraceIcon className="transition-transform duration-200 ease-out group-aria-expanded/trace-collapsible-trigger:rotate-90 motion-reduce:transition-none">
        <CaretRightIcon weight="bold" className="size-3.5" />
      </TraceIcon>
    </CollapsibleTrigger>
  );
}

function TraceCollapsibleContent({ className, children, ...props }: Omit<React.ComponentProps<typeof CollapsibleContent>, "asChild">) {
  return (
    <CollapsibleContent data-slot="trace-collapsible-content" className="min-w-0" {...props}>
      <div data-slot="trace-collapsible-content-inner" className={cn("mt-2 mb-1 ml-2 min-w-0 border-l border-line-field pr-1 pl-4 font-sans text-body leading-body [overflow-wrap:anywhere] text-fg-secondary", className)}>
        {children}
      </div>
    </CollapsibleContent>
  );
}

export { Trace, TraceCollapsible, TraceCollapsibleContent, TraceCollapsibleTrigger, TraceDescription, TraceIcon, TraceLine, TraceTitle };

```

# Typography
The console's type as components: regular titles, 14px body copy, muted lines, lists, quotes and inline keys.

Install: npx inkbox-ds add typography
Requires: theme, utils
Packages: none
Exports: TypographyBlockquote, TypographyH1, TypographyH2, TypographyH3, TypographyH4, TypographyInlineCode, TypographyLarge, TypographyLead, TypographyList, TypographyMuted, TypographyP, TypographySmall, TypographyTable
Client boundary: not required by this entry file
Reference: Figma 427:2715: page titles (Vault, Webhooks), dialog titles, the email body, inline hosts and keys


## Usage
Use for written content (docs, help panes, agent prompts). TypographyH3 is the 20px page or dialog title; TypographyP is body copy; TypographyMuted the line under a title; TypographyInlineCode a key, host or ID. Interfaces built from components rarely need these.
- Avoid: Bold titles
- Avoid: Letter spacing
- Avoid: Text sizes outside the scale
- Avoid: Purple body copy


## Examples
Example components: npx inkbox-ds add typography
[Preview](https://inkbox-ds.vercel.app/preview/typography/Preview) | [Scale](https://inkbox-ds.vercel.app/preview/typography/Scale)

examples/typography.tsx

```tsx
import { TypographyBlockquote, TypographyH1, TypographyH2, TypographyH3, TypographyH4, TypographyInlineCode, TypographyLarge, TypographyLead, TypographyList, TypographyMuted, TypographyP, TypographySmall, TypographyTable } from "@/components/ui/typography";

export function Preview() {
  return (
    <article className="w-full max-w-160">
      <TypographyH3>Tunnel</TypographyH3>
      <TypographyMuted>Stable hostname routing inbound traffic to @acme.</TypographyMuted>
      <TypographyP>
        Each agent gets a public host such as <TypographyInlineCode>acme.inkboxwire.com</TypographyInlineCode>. Traffic reaches the agent wherever it runs, with TLS handled at the edge by default.
      </TypographyP>
      <TypographyBlockquote>Direct card URLs stay public whether or not you list in the directory. Listing only controls discovery.</TypographyBlockquote>
      <TypographyList>
        <li>Opt your card into the public directory with an admin key.</li>
        <li>View the card Inkbox serves for you.</li>
        <li>Find workers in the public directory.</li>
      </TypographyList>
      <TypographyTable>
        <thead>
          <tr>
            <th>Field</th>
            <th>Value</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>Handle</td>
            <td>@test-agent-233</td>
          </tr>
          <tr>
            <td>Email</td>
            <td>test-agent-233@inkboxmail.com</td>
          </tr>
        </tbody>
      </TypographyTable>
    </article>
  );
}

export function Scale() {
  return (
    <div className="grid w-full max-w-160 gap-3">
      <TypographyH1>Agent Workspace</TypographyH1>
      <TypographyH2>Create Your First Agent</TypographyH2>
      <TypographyH3>Create Agent Identity</TypographyH3>
      <TypographyH4>Email</TypographyH4>
      <TypographyLead>Set up an identity to unlock mailbox, phone, and vault features.</TypographyLead>
      <TypographyLarge>Your agent will be reachable at</TypographyLarge>
      <TypographySmall>Shared lines are assigned when someone connects.</TypographySmall>
      <TypographyList ordered>
        <li>Create the agent.</li>
        <li>Copy its API key.</li>
      </TypographyList>
    </div>
  );
}

```

## Source

components/ui/typography.tsx

```tsx
import * as React from "react";

import { cn } from "@/lib/utils";

// The console's type as components (Figma 427:2715). Inter throughout, no tracking. Titles are regular, not bold: a page
// or dialog title is 20px (H3); H1 and H2 are 24px and 22px for the rare larger heading; H4 is a 16px medium card
// title. Body copy is 14px on a 1.5 line in ink, P under a title in the secondary purple; Muted is the 14px muted line
// under a page title; Small is 12px; Lead is 16px secondary.
function TypographyH1({ className, ...props }: React.ComponentProps<"h1">) {
  return <h1 data-slot="typography-h1" className={cn("font-sans text-h1 leading-heading font-normal text-balance text-fg", className)} {...props} />;
}

function TypographyH2({ className, ...props }: React.ComponentProps<"h2">) {
  return <h2 data-slot="typography-h2" className={cn("font-sans text-h2 leading-heading font-normal text-balance text-fg", className)} {...props} />;
}

function TypographyH3({ className, ...props }: React.ComponentProps<"h3">) {
  return <h3 data-slot="typography-h3" className={cn("font-sans text-h3 leading-heading font-normal text-fg", className)} {...props} />;
}

function TypographyH4({ className, ...props }: React.ComponentProps<"h4">) {
  return <h4 data-slot="typography-h4" className={cn("font-sans text-h4 leading-body font-medium text-fg", className)} {...props} />;
}

function TypographyP({ className, ...props }: React.ComponentProps<"p">) {
  return <p data-slot="typography-p" className={cn("font-sans text-body leading-body text-pretty text-fg [&:not(:first-child)]:mt-4", className)} {...props} />;
}

function TypographyLead({ className, ...props }: React.ComponentProps<"p">) {
  return <p data-slot="typography-lead" className={cn("font-sans text-body-lg leading-body text-fg-secondary", className)} {...props} />;
}

function TypographyLarge({ className, ...props }: React.ComponentProps<"div">) {
  return <div data-slot="typography-large" className={cn("font-sans text-body-lg leading-body font-medium text-fg", className)} {...props} />;
}

function TypographySmall({ className, ...props }: React.ComponentProps<"small">) {
  return <small data-slot="typography-small" className={cn("font-sans text-caption leading-tight text-fg", className)} {...props} />;
}

function TypographyMuted({ className, ...props }: React.ComponentProps<"p">) {
  return <p data-slot="typography-muted" className={cn("font-sans text-body leading-body text-fg-muted", className)} {...props} />;
}

/** A quote: indented behind a 2px pink rule, in the secondary purple. */
function TypographyBlockquote({ className, ...props }: React.ComponentProps<"blockquote">) {
  return <blockquote data-slot="typography-blockquote" className={cn("mt-4 border-l-2 border-pink pl-4 font-sans text-body leading-body text-fg-secondary", className)} {...props} />;
}

function TypographyList({ className, ordered = false, ...props }: Omit<React.ComponentProps<"ul">, "ref"> & { ordered?: boolean }) {
  const classes = cn("my-4 ml-5 grid gap-1.5 font-sans text-body leading-body text-fg marker:text-fg-muted", ordered ? "list-decimal" : "list-disc", className);
  return ordered ? <ol data-slot="typography-list" className={classes} {...props} /> : <ul data-slot="typography-list" className={classes} {...props} />;
}

/** A key, host or ID inside text: IBM Plex Mono on the lilac with 4px corners. */
function TypographyInlineCode({ className, ...props }: React.ComponentProps<"code">) {
  return <code data-slot="typography-inline-code" className={cn("rounded-xs bg-subtle px-1 py-px font-mono text-body-sm text-fg [box-decoration-break:clone]", className)} {...props} />;
}

/** A plain table in running text: the lilac head row and faint rules. For data, use Table. */
function TypographyTable({ className, ...props }: React.ComponentProps<"table">) {
  return (
    <div data-slot="typography-table" className="my-4 w-full overflow-x-auto">
      <table
        className={cn(
          "w-full border-collapse font-sans text-body leading-body text-fg [&_td]:border-b [&_td]:border-line-subtle [&_td]:px-4 [&_td]:py-2.5 [&_th]:bg-subtle [&_th]:px-4 [&_th]:py-2.5 [&_th]:text-left [&_th]:font-normal [&_th]:text-fg-muted [&_th:first-child]:rounded-l-panel [&_th:last-child]:rounded-r-panel",
          className,
        )}
        {...props}
      />
    </div>
  );
}

export { TypographyBlockquote, TypographyH1, TypographyH2, TypographyH3, TypographyH4, TypographyInlineCode, TypographyLarge, TypographyLead, TypographyList, TypographyMuted, TypographyP, TypographySmall, TypographyTable };

```

# cn
Merges class names and resolves conflicts between the brand's own scales (text-body, rounded-control, shadow-s).

Install: npx inkbox-ds add utils
Requires: none
Packages: clsx, tailwind-merge
Exports: cn
Client boundary: not required by this entry file

## Usage
Compose every component's classes with cn so a caller's className replaces the default it conflicts with.


## Source

lib/utils.ts

```tsx
import { type ClassValue, clsx } from "clsx";
import { extendTailwindMerge } from "tailwind-merge";

// The brand's scales have their own names (text-body-sm, rounded-control, shadow-s). Without teaching tailwind-merge,
// it reads text-body-sm as a text color and drops the real color beside it, and keeps a default rounded-md next to a
// brand radius meant to replace it. Brand text sizes do not set line height: keep explicit leading in either order.
const twMerge = extendTailwindMerge<"brand-font-size">({
  extend: {
    theme: {
      leading: ["tight", "heading", "display", "snug", "body", "relaxed", "code"],
      tracking: ["normal", "tight", "caps"],
      radius: ["xs", "sm", "control", "panel", "dialog", "pill"],
      shadow: ["s", "line", "card", "floating", "dialog", "knob", "focus"],
    },
    classGroups: {
      "brand-font-size": [{ text: ["display", "h1", "h2", "h3", "h4", "body-lg", "body", "body-sm", "caption", "micro"] }],
    },
    conflictingClassGroups: {
      "brand-font-size": ["font-size"],
      "font-size": ["brand-font-size"],
    },
    conflictingClassGroupModifiers: { "brand-font-size": ["leading"] },
  },
});

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

```