# opendraft

> opendraft is a React + Tailwind CSS v4 design system distributed as a shadcn registry and built to be used by AI assistants. Components install as source files into your project with the shadcn CLI, behavior comes from Radix, and every color, radius and timing comes from a small set of theme tokens. Building for a specific industry (security, logistics, healthcare, fintech and others)? Read the matching playbook in the Use cases section below before choosing components.

## How to build with opendraft

You are building a React interface with the opendraft design system. Follow these rules. They matter more than your own taste, but the person you're building for comes first: when they ask for their own fonts, colors or corner radius, apply them through the brand tokens in section 4.

### 1. Set up the project once

opendraft ships through a shadcn registry. Components install as source files into the project. There is no npm package to import.

Requirements: React 19, Tailwind CSS v4, TypeScript, and a shadcn `components.json`. Next.js is supported but not required.

If you can't run `npx shadcn` (a blocked network, a chat assistant, or a hosted builder such as Lovable or v0), install by hand. This is not optional: the steps below replace the CLI.

- For each item, fetch `https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/r/<name>.json`. Its `files[].content` is the source and `files[].path` is where to write it in the project. Skip any file you've already written.
- Repeat for every name in its `registryDependencies`, and for theirs in turn (it is transitive). Strip the `@opendraft/` prefix; a bare name such as `utils` is an opendraft item too. Add every package in each item's `dependencies` with the project's package manager.
- Some items have no files: they only list other items. The `kit-*` items (industry starter kits) are like this, so install everything in their `registryDependencies`.
- The `theme` item's `css` field is a nested JSON object, not text you can paste. Instead save https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/theme.css as your global stylesheet: it is the same theme as one ready-made file, with the dark-mode setup and the font links included. Do this first.

Not on Next.js (Vite, Lovable, Remix, Astro): everything works the same with these changes.

- Use `theme.css` as your global stylesheet (it loads the fonts and sets the font variables for you). In a Next.js project the CLI installs the theme and you load fonts with `next/font` instead.
- Item paths such as `components/ui/button.tsx` map to `src/components/ui/button.tsx` when your source folder is `src`; keep the `@/` alias pointing at `src`. In `components.json` set `"rsc": false` and point `tailwind.css` at your stylesheet.
- In `tsconfig`, use `paths` for the `@/*` alias without `baseUrl` (newer TypeScript rejects `baseUrl`).
- Ignore `"use client"` lines; they are harmless.
- Add the `dark` class to `<html>` yourself. For no flash on load, put the string exported as `themeScript` from `theme-toggle` in an inline `<script>` in `index.html`; it uses the localStorage key `theme`.

1. If the project has no `components.json`, run `npx shadcn@latest init`. That command fetches from ui.shadcn.com. If it fails (a blocked network), write the file by hand:

```json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "iconLibrary": "lucide",
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  }
}
```

2. Add the registry to `components.json`:

```json
{
  "registries": {
    "@opendraft": "https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/r/{name}.json"
  }
}
```

3. Install the theme first. It writes the tokens into the global stylesheet:

```bash
npx shadcn@latest add @opendraft/theme
```

4. Clean up the starter stylesheet. Projects made with `create-next-app` leave rules in `app/globals.css` that fight the theme, and after the theme is added they can sit in the middle of the file, so search the whole file. Delete them:
   - the `@media (prefers-color-scheme: dark) { :root { … } }` block (dark mode here is the `dark` class, not the operating system setting)
   - the starter's `body { background: …; color: …; font-family: Arial, … }` rule (the theme sets the body styles)
   - the starter's own `:root { --background; --foreground }` values, if they remain after the theme's (the theme's must win)
   - the starter's `@theme inline { … }` block that maps `--font-sans` / `--font-mono` to `--font-geist-sans` / `--font-geist-mono` (the theme maps the fonts itself)
5. Install each component you use, by name:

```bash
npx shadcn@latest add @opendraft/button @opendraft/card @opendraft/prompt-bar
```

6. Load three fonts and expose them as CSS variables: Geist as `--font-geist`, Geist Mono as `--font-geist-mono`, Newsreader as `--font-newsreader`. In Next.js use `next/font/google` (the starter's `--font-geist-sans` is not the same variable; rename it).
7. Dark mode is the `dark` class on `<html>`. The `theme-toggle` component (`npx shadcn@latest add @opendraft/theme-toggle`) handles it: it switches system, light and dark and remembers the choice. To avoid a flash of the wrong theme on load, also run its exported `themeScript` before the page paints, and add `suppressHydrationWarning` to `<html>` because the script changes its class:

```tsx
import { themeScript } from "@/components/ui/theme-toggle"

// app/layout.tsx
;<html lang="en" suppressHydrationWarning>
  <head>
    <script dangerouslySetInnerHTML={{ __html: themeScript }} />
  </head>
  <body>{children}</body>
</html>
```

Without opendraft's toggle you can use `next-themes` with `attribute="class"` instead. 8. Wrap the app once so motion respects the user's "reduce motion" setting, and mount the toaster. A layout is a server component, so do this in a small client file (for example `components/providers.tsx` with `"use client"`) and wrap `{children}` with it in `app/layout.tsx`:

```tsx
import { MotionConfig } from "motion/react"

import { Toaster } from "@/components/ui/sonner"

;<MotionConfig reducedMotion="user">
  {children}
  <Toaster />
</MotionConfig>
```

On Next.js 16 with Cache Components (the new `create-next-app` default), a component that reads `usePathname()`, `useSearchParams()`, `params` or `searchParams` must sit inside a `<Suspense>` boundary, or the build fails. Also, a server component can't pass a function (including an icon component such as a lucide icon) to a client component as a prop: pass the element (`<Icon />`) or an icon name instead.

### 2. Use components before writing your own

- If the product is for a specific industry or job (security, IT and infrastructure, aviation, logistics, healthcare, fintech, ecommerce, education, energy and utilities, government and civic, manufacturing, HR and people, and so on), read the matching playbook in the Use cases list first, before choosing components. It names the components that serve each need, rates how well they fit, lists the typical screens, and gives one install command for a starter kit. Follow its domain principles (for example how to show severity, status and time). Before you rely on a component, open its page and check that its props and data shape fit what you're building: a component can be named after one domain's data (a `Gap` or `Adapt` rating in a playbook tells you where it isn't a straight fit). If no playbook matches, pick by need from the component list and apply the same care.
- If the user asks for a whole screen (a dashboard, settings page, sign-in, CRM board, agent chat), check the Blocks list first. A block is a complete, working screen. Install it, then change the content through its props (it renders sample data when given none). Restyle it with tokens, not by rewriting it, and trim sections the user didn't ask for. Blocks fill the space they're given and lay out from their own width, so put one in a container that has a width and a height (for example a `w-full` parent with `h-screen` or a fixed height); in a shrink-to-fit parent it collapses. Give every page the same width with `PageContainer`, and head it with `PageHeader`. Build forms with `Field`, with `FieldGroup` for rows, and use `DatePicker` for single dates and `RepeaterField` for add-and-remove rows.
- Check the component list below before building any UI. If a component fits, install and use it, even if you'd only use part of it.
- Import from where the CLI installs them (the page for each component shows its exact import; for example `Table` is `@/components/motion/table`): `@/components/ui/*` for core pieces, `@/components/motion/*` for motion pieces, `@/components/agents/*` for AI and data pieces.
- Compose screens from components. Don't copy a component's internals into a page.
- Many components render sample content when you give them no data (their pages say "sample content") (ice-cream shop names, example transactions, demo prompts). Always pass the real content through their props: rows, items, labels, options, callbacks. Check the component's page for its props. Leaving the defaults in a real screen is a bug.
- Some components have a `fill` or `demo` prop. `demo` runs a self-playing walkthrough, so set `demo={false}` in a real screen. `fill` makes a scrolling area take its container's height instead of a fixed maximum, so give the container a height.
- Know the limits before you pick one. `SearchList` takes plain strings only and isn't a way to filter a grid of rich cards: use `Input` and filter your own data. `Table` needs a fixed pixel `rowHeight`; give it `height` for a scrolling area or `maxHeight` to size to its rows. `CardTitle` and `DialogTitle` are already styled: don't add `heading` to them.
- Only write a new component when nothing fits. Build it from the existing parts and follow the rules below.

### 3. Style only with tokens

Never hard-code colors, shadows, radii, easings or spring values. Use these Tailwind classes, which read the theme tokens:

| Purpose                                         | Use                                                                                                 |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Page background / text                          | `bg-background`, `text-foreground`                                                                  |
| Cards and panels                                | `bg-card`, `border` (a hairline)                                                                    |
| Quiet areas, inputs, wells                      | `bg-muted`, `bg-surface`                                                                            |
| Secondary text                                  | `text-muted-foreground`                                                                             |
| Hover background                                | `bg-accent`                                                                                         |
| Primary action                                  | `bg-primary text-primary-foreground` (blue by default)                                              |
| Accent text, links, focus strokes               | `text-brand`, `border-brand`                                                                        |
| Solid black buttons and bands                   | `bg-ink text-ink-foreground` (inverts in dark mode)                                                 |
| Status                                          | `text-success`, `text-warning`, `text-destructive` (tints: `bg-success/10`, etc.)                   |
| Lines                                           | `border-border`, `border-input`                                                                     |
| Floating layers only (menus, popovers, dialogs) | `bg-popover shadow-md`                                                                              |
| Extra blues for charts and textures             | `bg-blue-50` … `bg-blue-950`                                                                        |
| Headings and big numbers (stats, prices)        | `heading` (the heading font at its weight and tracking)                                             |
| Corners                                         | `rounded-md` / `rounded-control` for controls, `rounded-lg` / `rounded-surface` for cards and menus |

Text over a texture (`PixelField`, `bg-dots`): don't put it straight on the texture and don't add a gradient scrim. Put the text in a `dark` section, or on a solid `bg-background` panel, so it stays readable. Fonts: `font-sans` is the body font, `font-display` (or the `heading` utility) the heading font, `font-mono` the code font; use `font-mono` for money, dates and IDs.

Don't use Tailwind's palette colors (`bg-gray-100`, `text-emerald-600`, …) and don't add `dark:` color twins. The tokens already switch between light and dark.

### 4. The look, and making it yours

opendraft ships with a look: editorial headings, square corners, hairline borders, a blue primary. Treat it as the default. If the person asks for something different, their request wins, and you apply it by changing the brand tokens at the top of `:root` in the global stylesheet. Never restyle individual components to get a new look; change the token and every component follows.

| They ask for                                                  | Change                                                                                                                                                                                                                                           |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| A heading font (any Google Font, e.g. Inter)                  | `--font-heading`, plus `--heading-weight` (about 300 for light serifs like the default Newsreader, 500 to 600 for sans faces like Inter) and `--heading-tracking`                                                                                |
| A body / interface font (any Google Font, e.g. IBM Plex Sans) | `--font-body`                                                                                                                                                                                                                                    |
| A code font                                                   | `--font-code`                                                                                                                                                                                                                                    |
| A primary color (e.g. black)                                  | `--primary` and `--brand` in `:root` and in `.dark`. Set `--primary-foreground` to a color that reads on it (white on dark colors, near-black on light ones). For black, use `var(--ink)` and `var(--ink-foreground)`: they invert in dark mode. |
| Rounder buttons and inputs (e.g. 12px)                        | `--control-radius`                                                                                                                                                                                                                               |
| Rounder cards, menus and dialogs                              | `--surface-radius` (usually the same as or a little larger than `--control-radius`)                                                                                                                                                              |
| Larger or smaller text                                        | `--text-scale` (1 is the default; 1.1 makes every text size 10% larger, 0.9 10% smaller). Spacing stays the same.                                                                                                                                |

Any of the roughly 1,900 Google Fonts works. Load it with `next/font/google` (the export name replaces spaces with underscores, e.g. `IBM_Plex_Sans`; pass `variable: "--font-ibm-plex-sans"`, and `weight` for fonts that aren't variable), or with a `<link>` from fonts.google.com outside Next.js. Point the token at the variable, falling back to the family name and a generic stack so it works either way:

```css
:root {
  --font-heading:
    var(--font-inter, "Inter"), ui-sans-serif, system-ui, sans-serif;
  --font-body:
    var(--font-ibm-plex-sans, "IBM Plex Sans"), ui-sans-serif, system-ui,
    sans-serif;
  --heading-weight: 600;
  --heading-tracking: -0.03em;
  --primary: var(--ink);
  --brand: var(--ink);
  --primary-foreground: var(--ink-foreground);
  --control-radius: 12px;
  --surface-radius: 16px;
  --text-scale: 1.1;
}
```

The defaults, for anything they haven't asked to change:

- **Corners.** Controls use `rounded-md`, cards and menus `rounded-lg`; both follow the radius tokens. Use `rounded-full` only for avatars, status dots and spinners.
- **Hairlines over shadows.** Structure comes from 1px borders. Shadows are only for things that float above the page.
- **One primary color.** Use it for the main action and focus. Keep everything else neutral.
- **Type.** Headings use the `heading` utility. Interface text uses the default sans (`font-sans`, which is `--font-body`). Labels, counts and metadata use `font-mono`; small uppercase section labels use the `eyebrow` utility.
- **Texture.** Use `bg-dots` or the `PixelField` component for background texture. Don't use gradients or blobs.
- **Dark sections.** Add the `dark` class to any section to render it dark in either theme.

### 5. Motion

- Import timings from `@/lib/motion` (installed with any animated component): `spring.snappy` for presses and toggles, `spring.smooth` for panels and layout, `spring.pop` for arrivals, `ease.out` with `duration.base` for fades.
- For menus, popovers and tooltips use the CSS utilities `animate-pop-in` and `animate-pop-out`. For entrances use `animate-fade-up` and stagger with `animation-delay`.
- Use Motion (`motion/react`) for state changes: layout, enter and exit, springs.
- Animate `transform` and `opacity`, not layout properties, and keep motion short.

### 6. Accessibility

Components use Radix primitives and come with keyboard and screen-reader support. Keep it: give icon-only buttons an `aria-label`, keep visible focus rings (`focus-visible:ring-ring`), and don't remove roles or labels when you customise a component.

### 7. Before you finish

- Every color, radius, shadow and timing comes from a token, and any look the person asked for lives in the brand tokens, not in component overrides.
- Every piece of UI that exists in opendraft uses the opendraft component.
- The screen works in both light and dark mode.
- Headings use the `heading` utility; nothing else does.

---

# Building Security and compliance products with opendraft

> Security operations, threat detection, access control and audit products. Used by analysts under pressure: dense data, fast triage, irreversible actions.

Read this before building for this domain. Follow the rules in https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt as well. Names below link to each component's page (props, types, example).

## Use this playbook when the product involves

security, soc, siem, threat, incident response, vulnerability, edr, iam, access control, audit log, compliance, soc 2, firewall, fraud, zero trust, pentest.

## Principles for this domain

- Never show severity by color alone. Pair every severity color with a text label (Critical, High, Medium, Low) and use the same scale everywhere.
- Show times as absolute UTC in `font-mono` with a relative hint (for example `14:02:09Z · 3 min ago`). Analysts compare timestamps across systems. `timeline` renders `time` in mono and takes an ISO `timestamp`.
- Make destructive or far-reaching actions (isolate a host, revoke a session, delete a key) require a confirmation that names the consequence, and show who did it and when afterward. Do not offer 'Always allow' (`tool-approval`'s optional `onAlwaysAllow`) for these.
- Mask secrets by default (tokens, keys, hashes). Use `secret-input` for entering or showing a secret (masked, with reveal, copy and optional auto-hide) and never log or echo the value.
- Favor dense tables and a `command-palette` (Cmd/Ctrl+K) for jumping to an entity. Default these products to the dark theme (add the `dark` class), but keep both themes working.
- Every state change should leave an audit trail the user can see. Plan for an audit-log screen from the start. Record who and when in your backend; the UI components only display it.
- Show what the system knows, not what it concludes: label automated or AI verdicts as such and link the evidence. Do not state or imply that the product makes anyone compliant with a standard.

## What the product needs, and what to use

Fit: **Ready** means use as is. **Adapt** means it works with the caveat given. **Gap** means nothing fits yet: build it from primitives and follow the principles above.

### Triage a stream of alerts

- Fit: **Adapt**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/table.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Bulk Action Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/bulk-action-bar.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md)
- How: Start with the `data-table` block: `columns`, `rows`, `getRowId`, `searchable`, `filters` (a `filter-bar` config with chips and clear-all), `views` (tabs such as Open, Acknowledged, Closed), `selectable` with `bulkActions` (Acknowledge, Close, Assign receive the selected rows) and a card layout when narrow. Render severity and status as `badge` (with `dot`) in a column `cell`. For a very large live stream use the virtualized `table` (pass `rowHeight` and `height` or `maxHeight`) with `filter-bar` above and `bulk-action-bar` shown when ids are selected.
- Missing: `data-table` pages its rows rather than virtualizing them, so it suits thousands of rows, not an unbounded stream. There is no four-level severity component (use `badge`: Critical to `destructive`, High and Medium to `warning`, Low to `secondary`, always with the word) and no saved-filter control: store the `filter-bar` value yourself.

### Investigate an incident: timeline of events and evidence

- Fit: **Ready**
- Use: [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Code Block](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/code-block.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [File Diff](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/file-diff.md), [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Copy Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/copy-button.md)
- How: `timeline` is the event feed: per item `time` (mono), ISO `timestamp`, `title`, `description`, `meta` (actor or source), `status` (default, success, warning, destructive, current, upcoming; markers are never color only) and expandable `children` for raw evidence. Use `align="right-time"` for a time column, `collapsible` with `max` for long lists, and pass events newest first yourself (`newestFirst` only changes the label). `code-block` shows a raw event or command, `file-diff` a config change, `stepper` (horizontal or vertical) the response stages.

### Confirm and run response actions

- Fit: **Adapt**
- Use: [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md), [Tool Approval](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tool-approval.md), [Dialog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dialog.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Toast](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/sonner.md)
- How: `approval-card` takes a `title`, body `children` and `onApprove`, `onRequestChanges`, `onReject` (the last two render only when passed), a controlled `status` and a `result` slot where you put 'Approved by X at 14:02:09Z'. Use `tool-approval` when an AI agent proposes an action: it lists `parameters` and has allow once and deny. For the dangerous ones, build a `dialog` with an `input` the user types the host name into, and keep the confirm `Button` disabled until it matches (the type-to-confirm in `settings-page`'s danger zone does this). `sonner` reports the result.
- Missing: No built-in typed-confirmation or two-person approval component: assemble it from `dialog` + `input` + `button`. Who approved and when comes from your backend.

### Manage users, roles and permissions

- Fit: **Adapt**
- Use: [Settings Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/settings-page.md), [Permission Matrix](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/permission-matrix.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md), [Switch](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/switch.md), [Repeater Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/repeater-field.md)
- How: `settings-page` with `sections={["team"]}` gives a member list, invite (`onInvite`) and role change. Use `permission-matrix` for the custom-roles screen: `roles` by `groups` of permissions, select-all per role, row and group, read-only built-in roles and a change summary to review before saving (`onValueChange`). Long user lists belong in `data-table`. `repeater-field` edits rule lists such as allowed IP ranges.
- Missing: `settings-page` roles are fixed to owner, admin, member and viewer; use `permission-matrix` for anything custom. The matrix edits grants only: who may change roles, and enforcement, come from your backend.

### Search and review an audit log

- Fit: **Adapt**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Date Range Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-range-picker.md), [Date Time Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-time-picker.md), [Description List](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/description-list.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [File Diff](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/file-diff.md), [Command Palette](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/command-palette.md)
- How: `data-table` with `searchable`, `filters` (actor, action, outcome as select or multi-select), sortable mono columns for IDs and times, and `onRowOpen` to show one entry in a `description-list` (actor, target, IP, request ID with `copyable`). Show a change with `file-diff` and one entity's history with `timeline`. Use `date-range-picker` for the day range and `date-time-picker` (with a named `timeZone`, UTC by default here) for exact from and to bounds.
- Missing: No dedicated audit-log viewer with live tail, saved queries or export; assemble it from `data-table` and `filter-bar`, and page from your backend. `date-range-picker` itself has no time of day, which is why the exact bounds use `date-time-picker`.

### Show security posture and compliance coverage

- Fit: **Adapt**
- Use: [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md), [Analytics Dashboard](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/analytics-dashboard.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md)
- How: `stat` and `StatGroup` for headline numbers, with `delta` and `goodWhen="down"` for counts where fewer is better. `gauge` shows a posture or risk score with `thresholds` bands and a text status (never color alone). `progress` for control coverage: set `invert` with `tone="auto"` where a low value is bad. `time-series-chart` plots findings over time with `thresholds`, brush zoom and a data-table fallback. `analytics-dashboard` can still frame a findings overview through `labels`, `metrics`, `rows` and `channels`; pass `fill={false}` inside a scrolling page.
- Missing: `analytics-dashboard` ranges are fixed at 7d, 30d and 90d and its table columns are fixed to name, visitors, conversion and duration (relabel or replace the last with `valueColumn`). Prefer `time-series-chart` when you need your own series. Do not present a score as proof of compliance with a standard.

### Sign in with SSO and MFA

- Fit: **Adapt**
- Use: [Auth Screen](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/auth-screen.md), [MFA Step](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/mfa-step.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md)
- How: `auth-screen` handles email and password, remember me, forgot password and provider buttons (`providers`, `onProvider`); `onSubmit` may throw to show an error. After it succeeds, show `mfa-step` for the second factor: `methods` (authenticator app, SMS, security key), `onVerify` (async, returns the result), `onResend` with a countdown, and verifying, error and `locked` states. Use an `alert` for session-expired or lockout notices.
- Missing: `mfa-step` collects and submits a code but the verification, rate limits and lockout come from your auth provider or backend. There is no passkey enrolment screen or SSO-by-domain flow.

### Manage API keys and secrets

- Fit: **Ready**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Secret Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/secret-input.md), [Dialog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dialog.md), [Copy Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/copy-button.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md)
- How: List keys in `data-table` with created, last used and a `badge` for status (never show the full secret in a row). Reveal a new key once in a `dialog` with `secret-input` (masked, reveal, `copyable`, `autoHideMs`), a `copy-button` and an `alert` that it will not be shown again. Revoke with a type-to-confirm `dialog`.

### Show active incidents and degraded feeds

- Fit: **Ready**
- Use: [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md)
- How: `alert` has variants default, info, success, warning and destructive, a `banner` mode for full-width notices, an `AlertAction` slot for a button and optional `dismissible`.

### Ask an AI analyst to summarize or investigate

- Fit: **Ready**
- Use: [Agent Workspace](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/agent-workspace.md), [Citations](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/citations.md), [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md), [Tool Approval](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tool-approval.md)
- How: `agent-workspace` takes your `conversations`, `messages`, `tasks` and an async `onSend` that returns the reply (thinking rows, tool steps, streamed `answer` tokens, `sources`, `followUps`). Show evidence with `citations` and gate any action behind `approval-card` or `tool-approval`.

### Show assets or attack paths on a map

- Fit: **Adapt**
- Use: [Map View](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/map-view.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md)
- How: `map-view` is a token-styled MapLibre GL map: pass `markers` (each with a text `label` and a `status`), `routes` and `areas`, and use `selectedId` with `onSelect` to sync it with a `data-table` of assets. It includes a keyboard-reachable list of the same locations, so the map is never the only view.
- Missing: `map-view` is geographic only. There is no network or attack-path graph (`flowchart` is a workflow canvas). Use a graph library (see integrations) for nodes and edges and keep the entity list in `data-table` beside it.

## Libraries and services that pair well

- Network or attack-path graph: React Flow, Cytoscape.js. Draw nodes and edges with our tokens for color and type; keep the severity text labels.
- Geographic threat or asset map: MapLibre GL JS, deck.gl. map-view is already built on MapLibre GL JS; reach for deck.gl only for very dense layers. Always give each marker a text label for assistive technology.
- Event volume and trend charts: Recharts, uPlot. Use time-series-chart for multi-series trends with thresholds and zoom. uPlot copes with very large series; the chart inside analytics-dashboard is fixed to its own metrics.
- Single sign-on and MFA: Clerk, Auth0, WorkOS. Put the provider's flow behind the auth-screen block (onSubmit and onProvider) and use mfa-step for the second factor, wiring onVerify to the provider.

## Typical screens

- **Security operations overview**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md) + [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md) + [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md) + [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md)
- **Alert queue**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md) + [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md) + [Command Palette](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/command-palette.md)
- **Incident detail**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md) + [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md) + [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md) + [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md) + [Code Block](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/code-block.md) + [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md) + [Copy Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/copy-button.md)
- **Access management**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Settings Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/settings-page.md) + [Permission Matrix](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/permission-matrix.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md) + [Dialog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dialog.md)
- **Audit log**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md) + [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md) + [Date Time Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-time-picker.md) + [Description List](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/description-list.md) + [File Diff](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/file-diff.md)

## Install the starter kit

One command installs the theme and the components this playbook uses:

```bash
npx shadcn@latest add @opendraft/kit-security
```

## Known gaps

- Triage a stream of alerts: `data-table` pages its rows rather than virtualizing them, so it suits thousands of rows, not an unbounded stream. There is no four-level severity component (use `badge`: Critical to `destructive`, High and Medium to `warning`, Low to `secondary`, always with the word) and no saved-filter control: store the `filter-bar` value yourself.
- Confirm and run response actions: No built-in typed-confirmation or two-person approval component: assemble it from `dialog` + `input` + `button`. Who approved and when comes from your backend.
- Manage users, roles and permissions: `settings-page` roles are fixed to owner, admin, member and viewer; use `permission-matrix` for anything custom. The matrix edits grants only: who may change roles, and enforcement, come from your backend.
- Search and review an audit log: No dedicated audit-log viewer with live tail, saved queries or export; assemble it from `data-table` and `filter-bar`, and page from your backend. `date-range-picker` itself has no time of day, which is why the exact bounds use `date-time-picker`.
- Show security posture and compliance coverage: `analytics-dashboard` ranges are fixed at 7d, 30d and 90d and its table columns are fixed to name, visitors, conversion and duration (relabel or replace the last with `valueColumn`). Prefer `time-series-chart` when you need your own series. Do not present a score as proof of compliance with a standard.
- Sign in with SSO and MFA: `mfa-step` collects and submits a code but the verification, rate limits and lockout come from your auth provider or backend. There is no passkey enrolment screen or SSO-by-domain flow.
- Show assets or attack paths on a map: `map-view` is geographic only. There is no network or attack-path graph (`flowchart` is a workflow canvas). Use a graph library (see integrations) for nodes and edges and keep the entity list in `data-table` beside it.

Docs: https://ui-system-virid.vercel.app/docs/use-cases

---

# Building IT, DevOps and infrastructure products with opendraft

> Monitoring, incident management, deployments, logs and internal tools for engineers and IT teams.

Read this before building for this domain. Follow the rules in https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt as well. Names below link to each component's page (props, types, example).

## Use this playbook when the product involves

devops, sre, infrastructure, monitoring, observability, uptime, status page, deployment, ci/cd, pipeline, logs, kubernetes, cloud, helpdesk, it service, on-call, incident, internal tool, admin panel.

## Principles for this domain

- Status needs a word and a shape, not just a color: Operational, Degraded, Down, Maintenance. `status-indicator` already uses exactly this vocabulary (plus Unknown) with a distinct shape per state; keep one vocabulary across the product.
- Show times in UTC with `font-mono`, and let the user switch to local time in one place (a single setting or toggle that every screen reads; `settings-page` has a timezone select in its profile section).
- Numbers that change should use `tabular-nums` so columns don't jitter; use `animated-number` sparingly on dashboards, never in tables or logs.
- Long-running work (deploys, migrations) shows progress, current step and a way to cancel. Never leave a spinner with no step. Cancel is a `Button` you add; none of the progress components includes one.
- Provide a copy button next to every ID, command, hash and URL.
- Treat logs and code as data: monospaced, wrap toggle, selectable, searchable. `code-block` has a `wrap` prop and line numbers; search and filtering are yours to build.
- Never put real secrets in props that end up in client bundles or logs; show masked values and fetch reveals on demand.

## What the product needs, and what to use

Fit: **Ready** means use as is. **Adapt** means it works with the caveat given. **Gap** means nothing fits yet: build it from primitives and follow the principles above.

### Service health overview

- Fit: **Ready**
- Use: [Status Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/status-indicator.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md)
- How: `StatusIndicator` (`status` operational, degraded, down, maintenance, unknown; optional `pulse`) next to each service name, and `UptimeBar` for the 90-day bars: pass `segments` (one `{status, label}` per day), `uptime` text and `name` for the accessible summary. `stat` tiles for headline numbers, `gauge` (with `thresholds` and a text status) or `progress` for utilization and quota, `alert` (info or warning, `banner`) for planned maintenance.

### Public status page

- Fit: **Ready**
- Use: [Site Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/site-header.md), [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Status Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/status-indicator.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md)
- How: `alert` banner for the current incident, `StatusIndicator` and `UptimeBar` per component, and `timeline` for past incident updates (newest first, `collapsible` with `max`).

### Incident management and on-call

- Fit: **Adapt**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Checklist](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checklist.md), [Scheduler](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/scheduler.md), [Avatar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/avatar.md)
- How: Incident list in `data-table` (severity and status as `badge` cells, `views` for Open, Mitigated, Resolved, `filters` for service and severity). Incident updates in `timeline` (`status` warning, destructive, current, success; expandable `children` for notes). Lifecycle stages (Investigating, Identified, Monitoring, Resolved) in `stepper`. Runbook steps in `checklist` (tickable items, per-item notes, progress and a sign-off step). The on-call rota is a `scheduler` block: `resources` are people or teams, `events` are shifts, with conflict marking and keyboard moves.
- Missing: No paging or acknowledge control and no escalation policy editor; those come from your paging service. `scheduler` draws the rota but overrides and swaps are your logic.

### Browse and search logs

- Fit: **Adapt**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/table.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Code Block](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/code-block.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Copy Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/copy-button.md)
- How: Use the virtualized `table` with fixed `rowHeight`, mono cells, a level `badge` column, `onEndReached` and `loading` for paging, and `filter-bar` above it for level, service and text filters (chips with clear-all). `code-block` (`showLineNumbers`, `highlightLines`, `wrap`, `maxHeight`, `copyable`, `status="streaming"`) shows one entry's full payload or a stack trace. `code-panel` is not suited: it is a small sample-shaped card capped at about 420px wide.
- Missing: No log viewer. There is no follow or live-tail mode, so you append rows to `data` and manage scroll position yourself; no match highlighting; columns hide into a sideways scroll on phones (use `data-table`'s card layout only for modest result sets).

### Metrics dashboards

- Fit: **Adapt**
- Use: [Analytics Dashboard](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/analytics-dashboard.md), [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md), [Insight Cards](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/insight-cards.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Date Range Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-range-picker.md)
- How: `time-series-chart` is the metric chart: several `series` of `{t, v}` points (null `v` leaves a gap), a named `timeZone` (UTC by default here), `thresholds` for an SLO or alert line, brush zoom (`onZoomChange`), keyboard stepping and a data-table fallback. `analytics-dashboard` still gives KPI cards with deltas and a ranked table; relabel it through `labels` and feed it `data` per range. `date-range-picker` takes YYYY-MM-DD dates.
- Missing: No auto-refresh or live streaming in the chart: replace `series` as new points arrive. `analytics-dashboard` ranges are fixed at 7d, 30d and 90d and its table columns are name, visitors, conversion and duration (swap the last for `valueColumn`). For millions of points use a canvas chart library (see integrations).

### Deployments and pipelines

- Fit: **Adapt**
- Use: [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Checklist](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checklist.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [File Diff](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/file-diff.md), [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md)
- How: Stages in a `stepper` (use `description` for the commit, duration or environment). Pre-deploy and post-deploy checks in `checklist` (tickable, with a sign-off step). Deploy history in `timeline`. Gate production with `approval-card`; show the change with `file-diff`. Add your own Cancel `Button`.
- Missing: No pipeline or dependency graph. `flowchart` is NOT a status graph: it is an editable Trigger and If/Else workflow canvas with draggable cards and condition chips. `task-rows` is payment-shaped (label, amount, details) and does not fit.

### Configuration, environment variables and secrets

- Fit: **Adapt**
- Use: [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Repeater Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/repeater-field.md), [Secret Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/secret-input.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Copy Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/copy-button.md), [Switch](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/switch.md), [Dialog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dialog.md), [File Diff](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/file-diff.md)
- How: `repeater-field` (`value`, `renderRow`, `createItem`, `min`, `max`) for key and value rows, with an `input` for the name and a `secret-input` for the value (masked, reveal, optional auto-hide). Show a config change before saving with `file-diff`. Use `dialog` to confirm changes to production.
- Missing: No dedicated environment editor: no .env import, per-environment inheritance or secret rotation. Fetch reveals on demand from your backend.

### Inventory of servers, services or assets

- Fit: **Ready**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/table.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Bulk Action Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/bulk-action-bar.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Status Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/status-indicator.md), [Command Palette](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/command-palette.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md)
- How: Virtualized `table` for thousands of rows: sortable, resizable and reorderable columns, `selectable` with `onSelectionChange`, inline `editable` cells with `onCellEdit`. Put `filter-bar` above it and show `bulk-action-bar` (count, actions, clear) when rows are selected. For a few hundred rows the `data-table` block does all of this with paging and a card layout on phones.

### Command or terminal-style tools

- Fit: **Gap**
- Use: [Command Palette](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/command-palette.md), [Code Block](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/code-block.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Kbd](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/kbd.md)
- How: `command-palette` runs actions (items with `onSelect`, groups, hints and keywords). `code-block` can show command output, appended as it streams (`status="streaming"`). `agent-screen` is NOT a terminal: it is a card that views an agent's remote screen image or video.
- Missing: No terminal emulator (no PTY, ANSI colors or input line). Embed one such as xterm.js if users need a real shell.

### Team, access and settings

- Fit: **Ready**
- Use: [Settings Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/settings-page.md), [Auth Screen](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/auth-screen.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/table.md)
- How: Pass the real workspace name, members and billing; `sections` chooses which tabs show. Team roles are fixed to owner, admin, member and viewer.

### AI assistant for operations

- Fit: **Ready**
- Use: [Agent Workspace](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/agent-workspace.md), [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md), [Tool Approval](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tool-approval.md), [Citations](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/citations.md)
- How: Supply `conversations`, `messages` and an `onSend` that returns the reply. Ask for approval (`approval-card` or `tool-approval`) before any action that changes production.

## Libraries and services that pair well

- Metrics and time-series dashboards: Recharts, uPlot, Apache ECharts. time-series-chart covers multi-series metrics with thresholds, zoom and a table fallback. For heavier dashboards wrap the library so colors come from CSS variables, and keep a table fallback for accessibility.
- Log search at scale: OpenSearch, Loki, Elasticsearch. The Table is already virtualized; for millions of lines the filtering and paging belong server-side (feed it with onEndReached).
- Pipeline and dependency graphs: React Flow, Dagre layout. Use stepper or timeline for linear pipelines and a graph library when stages branch or users must pan and zoom.
- Terminal emulator: xterm.js. opendraft has no terminal; theme xterm.js with the code font and background tokens.
- Live updates: Server-sent events, WebSockets, Ably. Update rows in place and highlight what changed without moving the layout under the cursor.

## Typical screens

- **Status overview**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md) + [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md) + [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md) + [Status Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/status-indicator.md) + [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md)
- **Incident list and detail**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md) + [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md) + [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md) + [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md) + [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md) + [Checklist](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checklist.md)
- **Deployments**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md) + [Checklist](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checklist.md) + [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md) + [File Diff](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/file-diff.md) + [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md)
- **Logs**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md) + [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/table.md) + [Code Block](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/code-block.md)
- **Public status page**: [Site Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/site-header.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md) + [Status Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/status-indicator.md) + [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md)
- **Settings and access**: [Settings Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/settings-page.md)

## Install the starter kit

One command installs the theme and the components this playbook uses:

```bash
npx shadcn@latest add @opendraft/kit-it-infrastructure
```

## Known gaps

- Incident management and on-call: No paging or acknowledge control and no escalation policy editor; those come from your paging service. `scheduler` draws the rota but overrides and swaps are your logic.
- Browse and search logs: No log viewer. There is no follow or live-tail mode, so you append rows to `data` and manage scroll position yourself; no match highlighting; columns hide into a sideways scroll on phones (use `data-table`'s card layout only for modest result sets).
- Metrics dashboards: No auto-refresh or live streaming in the chart: replace `series` as new points arrive. `analytics-dashboard` ranges are fixed at 7d, 30d and 90d and its table columns are name, visitors, conversion and duration (swap the last for `valueColumn`). For millions of points use a canvas chart library (see integrations).
- Deployments and pipelines: No pipeline or dependency graph. `flowchart` is NOT a status graph: it is an editable Trigger and If/Else workflow canvas with draggable cards and condition chips. `task-rows` is payment-shaped (label, amount, details) and does not fit.
- Configuration, environment variables and secrets: No dedicated environment editor: no .env import, per-environment inheritance or secret rotation. Fetch reveals on demand from your backend.
- Command or terminal-style tools: No terminal emulator (no PTY, ANSI colors or input line). Embed one such as xterm.js if users need a real shell.

Docs: https://ui-system-virid.vercel.app/docs/use-cases

---

# Building Aviation and travel operations products with opendraft

> Airline and airport operations, flight information, booking and check-in, crew and maintenance tools. Safety-critical context: clarity and correctness beat flourish.

Read this before building for this domain. Follow the rules in https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt as well. Names below link to each component's page (props, types, example).

## Use this playbook when the product involves

aviation, airline, airport, flight, aircraft, pilot, crew, boarding, check-in, mro, maintenance, notam, metar, air traffic, charter, fbo, ground handling.

## Principles for this domain

- State times with an explicit zone. Use 24-hour time, mark UTC as `Z`, and show the airport's local time beside it. Never leave a time ambiguous. `date-time-picker` picks a date and time in a named IANA `timeZone` (with DST gap and overlap handling and an other-zone readout); `eta-indicator`, `time-series-chart` and `scheduler` also take a `timeZone`. Store the zone with every time you save.
- Flight status is always a word first (On time, Delayed, Boarding, Departed, Cancelled) with a color second (`badge` with `dot`). Show the reason and the new time for any delay.
- Use IATA or ICAO codes in `font-mono` with the full name on hover or beneath, for example `LIS` and Lisbon.
- On safety-critical screens (maintenance sign-off, checklists, weather) avoid decorative motion (skip `text-scramble` and `animated-number`), show who signed and when, and require an explicit confirm. Prefer `approval-card` over a quiet toggle. These screens record a sign-off; they do not replace your approved maintenance or operational records system.
- Design for tablets, gloves and bright light: large touch targets, high contrast, no hover-only information.
- A live board updates in place without shifting the layout under a user's cursor. Highlight what changed, then settle. No component does the highlight for you.

## What the product needs, and what to use

Fit: **Ready** means use as is. **Adapt** means it works with the caveat given. **Gap** means nothing fits yet: build it from primitives and follow the principles above.

### Departures and arrivals board

- Fit: **Adapt**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Text Scramble](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/text-scramble.md)
- How: `data-table` with a sortable time column, mono code and flight-number cells (`mono`), a status `badge` (`dot`) in a column `cell`, `views` for Departures and Arrivals, `filters` for airline, terminal and status, and a card layout on narrow screens. `text-scramble` can resolve a changed gate or time to its new text. `alert` for a disruption banner. For a very long board use the virtualized `table` with `filter-bar` instead.
- Missing: No split-flap display. No built-in highlight when a row changes: flash the changed cell yourself, then settle.

### Flight detail and itinerary

- Fit: **Adapt**
- Use: [Record Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/record-page.md), [ETA Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/eta-indicator.md), [Map View](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/map-view.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Copy Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/copy-button.md)
- How: `record-page` is the flight detail: `title` (flight number), `status` (a word first), `summary` stats for scheduled and estimated times, gate and aircraft, `fields`, `activity` as the leg-by-leg `timeline` and `related` for connecting flights. `eta-indicator` shows the estimated arrival as a range with a confidence word and a stale state, in a named `timeZone`. `map-view` can draw the route as a `routes` line between airports. Put `alert` above for the delay reason and new time. `detail-page` is NOT this: it is an event-ticket purchase page.
- Missing: `map-view` draws straight routes between coordinates on a street-style basemap; it does not animate a live aircraft position or great-circle arcs, and you supply flight data from your provider.

### Search for a flight

- Fit: **Adapt**
- Use: [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md), [Date Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-picker.md), [Date Range Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-range-picker.md), [Date Time Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-time-picker.md), [Quantity Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/quantity-stepper.md), [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md), [Command Palette](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/command-palette.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- How: Form built from `field` / `FieldGroup`: origin and destination, one date with `date-picker` or an outbound and return range with `date-range-picker` (YYYY-MM-DD, no time of day), passengers with `quantity-stepper`, cabin with `radio-group` or `select`. Use `date-time-picker` where a departure time in a named zone matters. For an airport picker, a controlled `command-palette` (`open`, `onOpenChange`, items with IATA codes in `keywords`, `onSelect` sets the field) is a workable hack. Render results in `data-table` with a select `Button` in a `cell`.
- Missing: No airport or route picker and no fare comparison grid. `catalog` is NOT a flight list: its items are events {title, host, location, category, date, price, capacity, remaining}, with no origin, destination or times.

### Passenger details and payment

- Fit: **Gap**
- Use: [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md), [Date Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-picker.md), [Repeater Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/repeater-field.md), [Address Form](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/address-form.md), [Checkbox](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checkbox.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md)
- How: `checkout` is event-booking shaped: fixed fields (name, email, phone, an optional attendee, delivery by email or desk, pay by card or later) and a cart of items with quantity, fees and discount codes. It cannot collect per-passenger details such as date of birth or travel documents. Build a `stepper` wizard with one `FieldSet` per passenger (`repeater-field` for several, or a loop), `date-picker` for dates of birth, `select` for title and nationality, `checkbox` for consents, and `address-form` for a billing or contact address. Take payment with your provider's hosted fields.
- Missing: No passenger form and no payment step that fits a flight booking; do not push passenger data through `checkout`.

### Booking confirmation

- Fit: **Adapt**
- Use: [Order Confirmation](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/order-confirmation.md), [Ticket Pass](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/ticket-pass.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md)
- How: `order-confirmation` can be relabelled as a booking confirmation through `labels` (title, order number, buttons) and `order` (lines with price, `tickets` with `fields` and a `code`). It shows one `ticket-pass` per ticket.
- Missing: It is ticket-shaped with a fixed 3-step stepper (`labels.steps` renames the three steps, you cannot add or remove one), a stat row for date, tickets and total, and a QR code per ticket.

### Boarding pass

- Fit: **Adapt**
- Use: [Ticket Pass](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/ticket-pass.md), [QR Code](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/qr-code.md)
- How: `ticket-pass` takes `title`, `eyebrow`, free-form `fields` (Gate, Seat, Group, Boards at, Terminal), `code`, `status` (valid, used, expired, void), `dark`, `tone` and an `actions` slot. The QR drawn is real and encodes `code`.
- Missing: It draws only a QR code. Airline boarding passes use a PDF417, Aztec or QR code carrying data formatted and issued by the airline's system; encode only what your airline system gives you, and use a barcode library for other symbologies. Treat this as a display of the pass, not the credential.

### Seat selection

- Fit: **Ready**
- Use: [Seat Map](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/seat-map.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- How: `seat-map` is a keyboard-navigable grid picker: `layout` (rows and aisles, `rowLabels`, `columnLabels`), per-seat `seats` with state (available, occupied, blocked, premium), optional `price` and `tier`, `value` / `onChange` for the selection, `max` for the passenger count, a legend and a running total. Every state has a text label as well as a shape. Load the cabin layout and availability from your reservation system and re-check at payment.

### Crew and roster scheduling

- Fit: **Adapt**
- Use: [Scheduler](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/scheduler.md), [Gantt](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gantt.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Avatar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/avatar.md), [Date Range Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-range-picker.md)
- How: `scheduler` block for the roster: `resources` are crew members, `events` are duties and rest periods (`status` word plus `tone`), day and week views, conflict marking, drag or keyboard moves (`onEventMove`) and an agenda on narrow widths. Give it the airport zone through `timeZone`. `gantt` suits a multi-day pairing or rotation plan with groups. `data-table` lists the crew with a duty `badge` per day.
- Missing: `scheduler` marks overlaps only; duty-time limits, rest rules and qualification checks must come from your crew-planning system, never from the UI.

### Maintenance logs and pre-flight checklists

- Fit: **Adapt**
- Use: [Checklist](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checklist.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Textarea](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/textarea.md), [Photo Capture](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/photo-capture.md), [Signature Pad](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/signature-pad.md), [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Dropzone](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dropzone.md)
- How: `checklist` for pre-flight and maintenance items: tickable rows with `notes`, progress, `onComplete` and a sign-off step that stays disabled until every item is done. Capture photos with `photo-capture` (camera or file, optional captions) and documents with `dropzone`. `signature-pad` takes a drawn or typed signature; `approval-card` records the sign-off (its `result` slot can show 'Signed by X at 08:14Z'). History in `timeline` and `data-table`. `todo-list` is NOT a checklist: it is a read-only display of an agent's task plan.
- Missing: Who signed and when must come from your authenticated backend and be written by it; a captured signature image is not a credential. These screens record a sign-off, they do not replace your approved maintenance records system.

### Disruption, weather and NOTAM notices

- Fit: **Ready**
- Use: [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md)
- How: `alert` has info, warning and destructive variants, a `banner` mode and an `AlertAction` slot (for example a View affected flights button). Pass bulletin text as supplied by your data source, with its issue and validity times in UTC, and link to the source.

### Operations control overview

- Fit: **Adapt**
- Use: [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md), [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md), [Map View](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/map-view.md), [Analytics Dashboard](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/analytics-dashboard.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Status Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/status-indicator.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Command Palette](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/command-palette.md)
- How: On-time performance and disruption counts in `StatGroup` tiles (`delta` with `goodWhen`). `StatusIndicator` for airport or system status, `gauge` for stand or gate utilisation, `time-series-chart` for movements per hour in the airport zone with a capacity `threshold`, `map-view` for an airport or network status map (status markers with text labels), and `data-table` for the exceptions list.
- Missing: `analytics-dashboard` ranges are fixed at 7d, 30d and 90d and its table columns are name, visitors, conversion and duration; prefer `time-series-chart` here. `map-view` is not a radar or live-traffic display.

## Libraries and services that pair well

- Flight path and airport maps: MapLibre GL JS, deck.gl, Mapbox GL JS. map-view draws routes as straight lines between coordinates; great-circle arcs, tracks and live traffic are a map-library job (deck.gl). Keep times and codes in the table beside it.
- Flight data: FlightAware AeroAPI, OpenSky Network, AviationStack. Normalize to UTC and show local airport time beside it.
- Time zones: Temporal API, Luxon, date-fns-tz. date-time-picker picks and displays a time in a named IANA zone (DST gaps and overlaps handled). Use one of these to convert and format stored instants elsewhere.
- Barcodes for passes: bwip-js. qr-code only draws QR. bwip-js can render PDF417 and Aztec; scanning is a separate job, for example with zxing-js.
- Crew and maintenance scheduling: FullCalendar, DHTMLX Gantt, Bryntum. scheduler (resource day and week views) and gantt (task bars with dependencies) cover rosters and maintenance plans. Embed one of these only for what they lack, such as recurrence rules or very large resource timelines.

## Typical screens

- **Departures board**: [Site Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/site-header.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md) + [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md)
- **Flight detail**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Record Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/record-page.md) + [ETA Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/eta-indicator.md) + [Map View](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/map-view.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md)
- **Search and booking**: [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md) + [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md) + [Date Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-picker.md) + [Date Range Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-range-picker.md) + [Date Time Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-time-picker.md) + [Quantity Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/quantity-stepper.md) + [Seat Map](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/seat-map.md) + [Address Form](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/address-form.md) + [Order Confirmation](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/order-confirmation.md)
- **Boarding pass**: [Site Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/site-header.md) + [Ticket Pass](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/ticket-pass.md) + [QR Code](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/qr-code.md)
- **Maintenance sign-off**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Checklist](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checklist.md) + [Photo Capture](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/photo-capture.md) + [Signature Pad](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/signature-pad.md) + [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md) + [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md) + [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md)
- **Operations overview**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md) + [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md) + [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md) + [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md) + [Map View](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/map-view.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md)

## Install the starter kit

One command installs the theme and the components this playbook uses:

```bash
npx shadcn@latest add @opendraft/kit-aviation
```

## Known gaps

- Departures and arrivals board: No split-flap display. No built-in highlight when a row changes: flash the changed cell yourself, then settle.
- Flight detail and itinerary: `map-view` draws straight routes between coordinates on a street-style basemap; it does not animate a live aircraft position or great-circle arcs, and you supply flight data from your provider.
- Search for a flight: No airport or route picker and no fare comparison grid. `catalog` is NOT a flight list: its items are events {title, host, location, category, date, price, capacity, remaining}, with no origin, destination or times.
- Passenger details and payment: No passenger form and no payment step that fits a flight booking; do not push passenger data through `checkout`.
- Booking confirmation: It is ticket-shaped with a fixed 3-step stepper (`labels.steps` renames the three steps, you cannot add or remove one), a stat row for date, tickets and total, and a QR code per ticket.
- Boarding pass: It draws only a QR code. Airline boarding passes use a PDF417, Aztec or QR code carrying data formatted and issued by the airline's system; encode only what your airline system gives you, and use a barcode library for other symbologies. Treat this as a display of the pass, not the credential.
- Crew and roster scheduling: `scheduler` marks overlaps only; duty-time limits, rest rules and qualification checks must come from your crew-planning system, never from the UI.
- Maintenance logs and pre-flight checklists: Who signed and when must come from your authenticated backend and be written by it; a captured signature image is not a credential. These screens record a sign-off, they do not replace your approved maintenance records system.
- Operations control overview: `analytics-dashboard` ranges are fixed at 7d, 30d and 90d and its table columns are name, visitors, conversion and duration; prefer `time-series-chart` here. `map-view` is not a radar or live-traffic display.

Docs: https://ui-system-virid.vercel.app/docs/use-cases

---

# Building Logistics, supply chain and fleet products with opendraft

> Shipment tracking, dispatch, warehouse and fleet products for operators, drivers and customers who need to know where things are and when they'll arrive.

Read this before building for this domain. Follow the rules in https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt as well. Names below link to each component's page (props, types, example).

## Use this playbook when the product involves

logistics, shipping, shipment, freight, carrier, courier, delivery, last mile, fleet, driver, dispatch, warehouse, inventory, supply chain, tracking, 3pl, customs, proof of delivery.

## Principles for this domain

- Every shipment shows three things at a glance: status (as a word), where it is, and when it will arrive (an ETA with a confidence or a delay reason). `eta-indicator` shows the estimate as a range with a confidence word and a stale state; `map-view` shows where.
- Tracking IDs, container numbers and SKUs go in `font-mono` with a `copy-button`.
- Exceptions come first: delayed, held and failed deliveries sort to the top (sort your data; `tabs` for Exceptions first) and carry the reason and the next action.
- Show dates and times in the location's own time zone, and say which zone. `date-time-picker` picks a time in a named IANA `timeZone` and can show the same moment in other zones; `eta-indicator` and `scheduler` take a `timeZone` too. Store the zone with the instant.
- Operators work in bulk: lists need row selection with a bulk action bar and filters that survive a reload. `data-table` has `selectable` with `bulkActions`, and `bulk-action-bar` and `filter-bar` stand alone for other layouts; persist the filter value yourself.
- Driver and warehouse screens are used one-handed on a phone: large targets, one primary action per screen, works on a poor connection. `data-table` switches to a card layout when narrow; the virtualized `table` still scrolls sideways, so avoid it on driver screens.

## What the product needs, and what to use

Fit: **Ready** means use as is. **Adapt** means it works with the caveat given. **Gap** means nothing fits yet: build it from primitives and follow the principles above.

### Track one shipment (customer-facing)

- Fit: **Adapt**
- Use: [Site Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/site-header.md), [Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/card.md), [ETA Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/eta-indicator.md), [Map View](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/map-view.md), [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Copy Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/copy-button.md), [Description List](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/description-list.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md)
- How: `detail-page` is NOT this: it is an event-ticket purchase page. Compose: `site-header`, a `card` with the tracking ID plus `copy-button` and a status `badge`; `eta-indicator` for the estimate (range, confidence word, stale and past-window states, destination `timeZone`); `map-view` for the last known position and route (with a text list of the same stops); `stepper` for milestones with `description` carrying 'time zone · place'; `description-list` for carrier, service and weight; `alert` for a delay or exception. A `timeline` (`time`, ISO `timestamp`, `meta` for the location, `status`) is the better fit for the full scan history. For an internal view of one shipment use the `record-page` block.
- Missing: No ready-made tracking page; compose it from the pieces. Position and ETA values come from your carrier or telematics data; `map-view` does not animate live movement.

### Manage a list of shipments or orders

- Fit: **Adapt**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Bulk Action Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/bulk-action-bar.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Copy Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/copy-button.md), [Date Range Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-range-picker.md)
- How: `data-table` block: `columns` (status `badge` and a mono ID with `copy-button` in column `cell`s), `searchable`, `filters` (`filter-bar` chips for carrier, lane, date), `views` for Exceptions, In transit, Delivered, `selectable` with `bulkActions` (Reassign, Hold, Export receive the selected rows), paging and a card layout on phones. Sort exceptions first in your data. For tens of thousands of rows use the virtualized `table` with `filter-bar` and `bulk-action-bar`.
- Missing: No saved filters: keep the `filter-bar` value in your own state or URL.

### Dispatch board

- Fit: **Adapt**
- Use: [Scheduler](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/scheduler.md), [Stage Board](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stage-board.md), [Avatar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/avatar.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md)
- How: Two views of the same jobs. `scheduler` block: `resources` are drivers or vehicles, `events` are jobs on a day or week axis, with conflict marking, drag or keyboard reassignment (`onEventMove`) and an agenda on narrow widths. `stage-board` block: columns for Unassigned, Assigned, In transit, Delivered with drag or keyboard moves, WIP `limit`s, per-stage totals and a detail panel. Show unassigned jobs in a `data-table` beside the scheduler.
- Missing: Neither does route optimisation or capacity checks; the UI marks time overlaps only, and assignment rules and ETAs come from your dispatch system.

### Create a shipment or booking

- Fit: **Adapt**
- Use: [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md), [Address Form](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/address-form.md), [Date Time Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-time-picker.md), [Repeater Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/repeater-field.md), [Quantity Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/quantity-stepper.md), [Switch](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/switch.md), [Order Confirmation](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/order-confirmation.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md)
- How: Wizard with `stepper`; `address-form` for pickup and delivery addresses (per-country rules, postal validation, autocomplete tokens); packages as rows in `repeater-field` (weight, size, quantity with `quantity-stepper`). Pickup window with `date-time-picker` in the pickup location's `timeZone`. Finish with `order-confirmation` relabelled as a booking confirmation (`labels`, `order.lines`, `order.tickets` with `fields` and a `code`).
- Missing: `order-confirmation` is ticket-shaped with a fixed 3-step stepper (rename only) and a QR per ticket. `checkout` is event-booking shaped (name, email, phone, attendee, card) and does not fit. `address-form` does not look up or autocomplete addresses from a provider.

### Fleet and driver overview

- Fit: **Adapt**
- Use: [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Map View](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/map-view.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Status Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/status-indicator.md), [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md), [Avatar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/avatar.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Analytics Dashboard](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/analytics-dashboard.md)
- How: `StatGroup` for utilization and on-time rate (`delta`, `goodWhen`). `map-view` for vehicle positions: `markers` with a text `label` and `status`, `selectedId` synced to a `data-table` of drivers and vehicles with `avatar` and `StatusIndicator` cells. `gauge` or `progress` for hours or fuel. `analytics-dashboard` works if the shape is KPIs, a trend per metric, a ranked list and a share breakdown; relabel via `labels`, `valueColumn` and the format props.
- Missing: `map-view` shows the positions you pass; it has no live tracking, clustering of thousands of vehicles or geofencing. `analytics-dashboard` ranges are fixed at 7d, 30d and 90d.

### Warehouse inventory and capacity

- Fit: **Adapt**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/table.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md)
- How: `table` with `editable` columns and `onCellEdit` for counts (`editable` is ignored on a column that sets `cell`), `filter-bar` for zone and SKU. Zones as `progress` or `gauge`: the default `tone="auto"` measures consumption, so a nearly full zone turns warning then destructive; for stock remaining set `invert`. A hardware scanner that types like a keyboard can fill an `input`.
- Missing: No camera barcode scan input and no heat map of locations.

### Proof of delivery

- Fit: **Ready**
- Use: [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md), [Signature Pad](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/signature-pad.md), [Photo Capture](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/photo-capture.md), [Checkbox](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checkbox.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md), [QR Code](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/qr-code.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md)
- How: Recipient name in `field` and `input`; a signature with `signature-pad` (drawn or typed name; `onSign` returns the result); photos of the parcel with `photo-capture` (camera or file, `max`, optional captions; `onChange` gives the files); a failure reason in `select`. `qr-code` can show a handover code the recipient presents. Upload the files and stamp time, location and driver from your backend. `qr-code` only generates codes; scanning is a device job.

### Rates, quotes and invoicing

- Fit: **Gap**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/card.md)
- How: Compose: rate options in `data-table` (carrier, service, transit time, price in mono, a select `Button` in a `cell`) or `radio-group` cards, totals in `stat`, invoices in `data-table` with a status `badge`. `checkout` is NOT a quote flow: it is an event-booking checkout with fixed contact and payment fields.
- Missing: No rate-comparison table and no quote or invoice component.

### ETA with confidence or delay reason

- Fit: **Ready**
- Use: [ETA Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/eta-indicator.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md)
- How: `eta-indicator` takes `eta`, optional `earliest` and `latest` (drawn as a range bar), a numeric `confidence` mapped to a high, medium or low word with an icon (never color alone), `updatedAt` with a stale state after `staleAfterMs`, a past-window state, and a `timeZone`. Add a `badge` for On time, At risk or Delayed and an `alert` with the reason for a delay. The estimate and confidence are computed by your backend.

### Operations analytics

- Fit: **Adapt**
- Use: [Analytics Dashboard](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/analytics-dashboard.md), [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Insight Cards](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/insight-cards.md)
- How: Relabel `analytics-dashboard` (shipments, on-time rate, cost per delivery) through `labels`, `data` per range, the format props and `valueColumn` for cost. For your own series (volume per hour, on-time rate against a target) use `time-series-chart`: several series, `thresholds`, brush zoom, a named `timeZone` and a data-table fallback.
- Missing: `analytics-dashboard` range tabs are fixed at 7d, 30d and 90d (so no `date-range-picker` link) and its table columns are page-analytics shaped (name, visitors, conversion, duration).

## Libraries and services that pair well

- Live fleet and route map: MapLibre GL JS, Google Maps Platform, HERE. map-view is built on MapLibre GL JS and draws markers, routes and areas. For clustering, geofencing or traffic layers reach for the library directly; keep ETA and status in opendraft components.
- Carrier and tracking data: Shippo, EasyPost, project44. Map each carrier's status codes to one status vocabulary before it reaches the UI.
- Barcode scanning: zxing-js, Dynamsoft, Scandit. Scanning is a device capability; opendraft's qr-code only generates codes and photo-capture takes pictures.
- Signature capture: signature_pad, react-signature-canvas. signature-pad and photo-capture cover proof of delivery; use a library only for exotic needs such as vector signature export.
- Drag and drop for a dispatch board: dnd-kit. stage-board has drag and keyboard moves built in; add dnd-kit only for cross-board or multi-select dragging.
- Time zones: Temporal API, Luxon, date-fns-tz. date-time-picker handles a named zone; use one of these to convert and format stored instants elsewhere.

## Typical screens

- **Public tracking page**: [Site Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/site-header.md) + [Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/card.md) + [ETA Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/eta-indicator.md) + [Map View](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/map-view.md) + [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md) + [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md) + [Description List](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/description-list.md) + [Copy Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/copy-button.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md)
- **Shipments list**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md) + [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md) + [Bulk Action Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/bulk-action-bar.md) + [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md)
- **Dispatch board**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Scheduler](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/scheduler.md) + [Stage Board](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stage-board.md) + [Avatar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/avatar.md) + [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md)
- **Create shipment**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md) + [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md) + [Address Form](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/address-form.md) + [Date Time Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-time-picker.md) + [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md) + [Repeater Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/repeater-field.md) + [Order Confirmation](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/order-confirmation.md)
- **Operations overview**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md) + [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md) + [Map View](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/map-view.md) + [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md) + [Analytics Dashboard](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/analytics-dashboard.md)

## Install the starter kit

One command installs the theme and the components this playbook uses:

```bash
npx shadcn@latest add @opendraft/kit-logistics
```

## Known gaps

- Track one shipment (customer-facing): No ready-made tracking page; compose it from the pieces. Position and ETA values come from your carrier or telematics data; `map-view` does not animate live movement.
- Manage a list of shipments or orders: No saved filters: keep the `filter-bar` value in your own state or URL.
- Dispatch board: Neither does route optimisation or capacity checks; the UI marks time overlaps only, and assignment rules and ETAs come from your dispatch system.
- Create a shipment or booking: `order-confirmation` is ticket-shaped with a fixed 3-step stepper (rename only) and a QR per ticket. `checkout` is event-booking shaped (name, email, phone, attendee, card) and does not fit. `address-form` does not look up or autocomplete addresses from a provider.
- Fleet and driver overview: `map-view` shows the positions you pass; it has no live tracking, clustering of thousands of vehicles or geofencing. `analytics-dashboard` ranges are fixed at 7d, 30d and 90d.
- Warehouse inventory and capacity: No camera barcode scan input and no heat map of locations.
- Rates, quotes and invoicing: No rate-comparison table and no quote or invoice component.
- Operations analytics: `analytics-dashboard` range tabs are fixed at 7d, 30d and 90d (so no `date-range-picker` link) and its table columns are page-analytics shaped (name, visitors, conversion, duration).

Docs: https://ui-system-virid.vercel.app/docs/use-cases

---

# Building Healthcare and patient care products with opendraft

> Clinical and patient-facing health products: EHR views, scheduling, telehealth and patient portals. Clinicians work under time pressure with safety-critical data; patients need calm, plain-language screens.

Read this before building for this domain. Follow the rules in https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt as well. Names below link to each component's page (props, types, example).

## Use this playbook when the product involves

healthcare, health, clinical, ehr, emr, patient, patient portal, telehealth, telemedicine, appointment, clinic, hospital, medication, prescription, lab results, care plan, pharmacy, triage.

## Principles for this domain

- Show patient identity on every clinical screen: full name, date of birth and an identifier in `font-mono`, in a header that stays pinned (wrap it in your own `sticky top-0 bg-background` container; `page-header` is not sticky by itself). Wrong-patient errors are the failure to design against.
- Always print units and reference ranges beside a measurement (`5.4 mmol/L, ref 3.9 to 5.6`), and never round or reformat a value without saying so. Do not rely on color alone to mark an abnormal or critical value; pair it with a text flag such as High, Low or Critical.
- Critical values and allergy warnings stay visible until a named user acknowledges them. Never auto-dismiss a clinical alert or put one in a toast. Use a persistent `alert` (it only gets a close button if you pass `dismissible`, so don't) with an acknowledge `button` in `AlertAction`, and have your backend record who acknowledged it and when.
- Privacy by default: mask identifiers and sensitive fields until revealed, keep reveals logged, and avoid showing patient names in browser titles, notifications and URLs.
- Write patient-facing copy in plain language at a low reading level, explain medical terms in place, and say what happens next. Lead with the answer (`Your results are normal`), not the data.
- Confirm irreversible or high-risk actions (sign an order, discharge, cancel a procedure) in a `dialog` that names the patient and the consequence. Where your rules require it, keep an audit trail of who viewed or changed a record.
- opendraft is presentation only. It does not check doses, interactions or reference ranges and it makes no clinical-safety or privacy-law guarantee. Every value, flag and warning must come from your system of record, and you remain responsible for clinical validation.
- State the time zone wherever a time is shown or chosen. `date-time-picker` picks a date and time in a named IANA zone (it handles DST gaps and overlaps), and `time-series-chart` and `scheduler` take a `timeZone`. Show when a result was last updated.

## What the product needs, and what to use

Fit: **Ready** means use as is. **Adapt** means it works with the caveat given. **Gap** means nothing fits yet: build it from primitives and follow the principles above.

### Patient banner and chart overview

- Fit: **Adapt**
- Use: [Record Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/record-page.md), [Description List](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/description-list.md), [Avatar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/avatar.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Copy Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/copy-button.md)
- How: The `record-page` block gives the chart shell: header with `title`, `id` and `status`, `summary` stats for latest vitals (value with units, hint for the reference range or time taken), `fields` (a `description-list`: date of birth, sex, MRN with `copyable` and `mono`), an `activity` timeline and `related` items; extra `tabs` for Orders, Notes and Results. Add `avatar` and `badge` for name, age and flags, a persistent `alert` for allergies, and `gauge` for a single score with a text status.
- Missing: No patient-banner component and nothing is sticky: wrap the banner in your own sticky container so it never scrolls away.

### Lab results and vitals with abnormal flags

- Fit: **Adapt**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md), [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md), [Date Range Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-range-picker.md)
- How: `data-table` with columns for test, value with unit, range, flag and date, a text-labelled `badge` (High, Low, Critical) in the `cell`, `filters` by panel or flag and a card layout on phones. `gauge` shows a single vital against `thresholds` bands with a text status. `time-series-chart` plots a trend: `series` of `{t, v}` points, `thresholds` with a band (`value` to `to`) for the reference range, brush zoom, keyboard stepping and a built-in data-table fallback, in a named `timeZone`. `stat` for the latest reading and `date-range-picker` for the period.
- Missing: Reference ranges, flags and units must come from your system of record. `time-series-chart` is not a waveform viewer (ECG) and does not annotate events; always keep the values in a table beside any chart.

### Critical-value and safety alerts

- Fit: **Ready**
- Use: [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md), [Dialog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dialog.md), [Status Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/status-indicator.md)
- How: `alert` is persistent by default and has info, success, warning and destructive variants, a `banner` mode and an `AlertAction` slot: put an Acknowledge `button` in it and call your backend with the user and time. Use `dialog` when the acknowledgement needs a reason. `approval-card` can also gate an action but its resolved badge always reads Approved or Rejected (it cannot say Acknowledged), so prefer `alert` plus `button`. Do not use `sonner` for clinical alerts.

### Appointment booking and scheduling

- Fit: **Adapt**
- Use: [Scheduler](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/scheduler.md), [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Date Time Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-time-picker.md), [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md), [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Order Confirmation](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/order-confirmation.md), [Ticket Pass](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/ticket-pass.md)
- How: Patient booking: `stepper` (steps accept a `description`, e.g. the chosen clinician and time) for reason, clinician, time and confirm. `date-time-picker` picks the slot in the clinic's named `timeZone` and can show the same moment in the patient's zone; or a `radio-group` you style as slots. For the confirmation, `order-confirmation` works if you relabel it (`labels.steps`, `title`, `tickets`, `ticketsHeading`, `admitOne`) and put the visit details in the `fields` of one ticket whose `code` is an opaque booking reference. Clinic staff schedules use the `scheduler` block: `resources` are clinicians or rooms, `events` are appointments, with conflict marking and drag or keyboard moves.
- Missing: `order-confirmation` is ticket-shaped: it always prints the email sentence, a Total in money format (a free visit shows 0.00), an order summary of priced lines and a QR ticket. For free visits compose a `ticket-pass`, a `stat` row and `button`s instead. Availability, double-booking rules and reminders come from your scheduling system; `scheduler` only marks overlaps.

### Medication list and orders

- Fit: **Adapt**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/table.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Dialog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dialog.md), [Repeater Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/repeater-field.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md), [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md)
- How: Active medications in a `table` (dose, route, frequency columns and a status `badge`); `repeater-field` edits multi-line prescriptions, each row built with `field`, `input` and `select` in `renderRow`. Confirm signing in a `dialog` that names the patient and drug. `approval-card` can wrap an order summary with `approveLabel` set to the action, but its resolved badge always says Approved, so use it only where that wording is acceptable.
- Missing: No drug-interaction or dose-check UI, and no medication-specific component; interaction warnings come from your clinical decision support service and are shown with a persistent `alert`.

### Telehealth visit

- Fit: **Adapt**
- Use: [Video Player](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/video-player.md), [Avatar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/avatar.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Status Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/status-indicator.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Tooltip](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tooltip.md)
- How: `video-player` plays recorded video (patient education, a pre-visit explainer) with captions, chapters and speed. For the live visit, controls (mute, camera, leave) are icon `button`s with `tooltip`s, a waiting-room state is a `badge`, connection quality is a `status-indicator` with a label override, and a connection warning is an `alert`. `avatar` fills a tile when the camera is off.
- Missing: `video-player` plays a file or stream URL; it is not a call surface. No live video tile grid or device check: embed a video SDK and lay out the tiles yourself. For an in-visit text chat compose `message`, `message-bubble` and `prompt-input` (leave `models` empty).

### Patient intake forms and consent

- Fit: **Adapt**
- Use: [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Textarea](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/textarea.md), [Checkbox](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checkbox.md), [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md), [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md), [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Photo Capture](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/photo-capture.md), [Signature Pad](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/signature-pad.md), [Dropzone](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dropzone.md), [Repeater Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/repeater-field.md), [Question Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/question-card.md), [Address Form](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/address-form.md)
- How: `stepper` (with step `description`) splits a long form into short steps; `field` and `FieldGroup` give labels, hints and inline errors; `repeater-field` for medications and allergies; `address-form` for the home address; `photo-capture` (camera or file) for insurance card and ID photos, `dropzone` for documents. Consent is signed with `signature-pad` (drawn or typed name) beside the consent text. `question-card` suits a short screening questionnaire: one question at a time, single choice auto-advances, `onSubmitted` returns the answers by index.
- Missing: Store the signature with a timestamp and the consent text version in your backend; the pad only returns an image. No rich text editor needed here. For date of birth use three `input`/`select` fields: `date-picker` only has previous and next month buttons, so going back decades is slow. `question-card` always shows a Skip action and a free-text 'Something else' option and has no scoring or branching.

### Care plan and visit history

- Fit: **Adapt**
- Use: [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Checklist](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checklist.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Accordion](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/accordion.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Rich Text Editor](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/rich-text-editor.md)
- How: `timeline` is a strong fit for encounters and events: statuses (success, warning, destructive, current, upcoming) never rely on color alone, mono timestamps, an `items` array, expandable detail for notes or attachments, and collapsible long lists. `progress` with `label` and `valueLabel` for goals (`3 of 5 sessions`). `checklist` for care-plan tasks the patient or nurse ticks off, with notes per item and a sign-off step. `rich-text-editor` for clinical notes (formatting toolbar, link validation, character limit) with its read-only renderer for display.
- Missing: Clinical documentation standards, templates and coding are your system's job; the editor only captures formatted text (HTML or JSON) and does not autosave or track versions.

### Secure messaging with the care team

- Fit: **Adapt**
- Use: [Chat App](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/chat-app.md), [Message](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/message.md), [Message Bubble](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/message-bubble.md), [Message Scroller](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/message-scroller.md), [Prompt Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/prompt-input.md), [Avatar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/avatar.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Sidebar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/animated-sidebar.md)
- How: `message` rows (`from` is `user` or `assistant`, mapped to patient and clinician) with `avatar`, a header for name and time, and a footer for 'Read 14:02' text; `message-bubble` variants; `message-scroller` for the transcript; `prompt-input` as the composer (omit `models` to hide the model picker). `chat-app` is the shell with a folding sidebar, and the thread list is built with `animated-sidebar`. Keep an `alert` visible saying messages are not for emergencies.
- Missing: No attachment preview, read-receipt logic, thread list data model or clinician routing (only the slots to render them); only two sides (`user`/`assistant`). Keep the thread data on your own secure backend.

### Sign in with MFA and a proxy or caregiver

- Fit: **Adapt**
- Use: [Auth Screen](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/auth-screen.md), [MFA Step](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/mfa-step.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md), [Settings Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/settings-page.md), [Permission Matrix](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/permission-matrix.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md)
- How: `auth-screen` handles email and password (and optional provider buttons); after its `onSubmit` resolves, show `mfa-step` (`methods`, async `onVerify`, `onResend` with a countdown, error and locked states). Caregiver access can use the `team` section of `settings-page` (members with an invite by email and a role); a `permission-matrix` can show what each proxy role may see.
- Missing: `settings-page` roles are fixed to owner, admin, member and viewer (viewer is the nearest to a read-only proxy), and the section has no consent scope or expiry, so build those with `switch`, `date-picker` and a `data-table`. Verification of the code is your auth provider's job.

## Libraries and services that pair well

- Clinical data exchange (patients, observations, medications): HL7 FHIR (SMART on FHIR), Epic FHIR APIs, Medplum. opendraft is presentation only; map FHIR resources to the props of `table`, `stat` and `timeline` in a thin adapter and keep PHI out of client logs.
- Telehealth video: Twilio Video, Daily, Zoom Video SDK. video-player covers recorded video; the SDK renders the live call. Use opendraft buttons, badges and `alert` for controls, waiting-room state and connection warnings around it.
- Vitals and lab trend charts: Recharts, visx, Apache ECharts. time-series-chart ships axes, threshold bands, keyboard stepping and a data-table fallback; use a charting library only for clinical waveforms or dense annotations, styled with the semantic tokens and with a text legend.
- Scheduling and calendar: FullCalendar, react-big-calendar, Cal.com. The scheduler block covers clinician schedules (resource day and week views); embed one of these only for recurrence or very large calendars, and keep date-time-picker and radio-group for the patient-facing booking path.
- Consent signatures and identity verification: react-signature-canvas, DocuSign, Persona. signature-pad captures a drawn or typed signature as an image; store it with a timestamp and the consent text version. Use these services for legally binding e-signature and identity verification.

## Typical screens

- **Patient chart**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md) + [Record Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/record-page.md) + [Description List](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/description-list.md) + [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md) + [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md) + [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md) + [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md)
- **Results review**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Date Range Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-range-picker.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md) + [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md) + [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md) + [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md) + [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- **Book an appointment**: [Site Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/site-header.md) + [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md) + [Date Time Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-time-picker.md) + [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md) + [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md) + [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md) + [Order Confirmation](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/order-confirmation.md)
- **Patient portal home**: [Site Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/site-header.md) + [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md) + [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md) + [Empty State](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/empty-state.md) + [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- **Intake and consent**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md) + [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md) + [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md) + [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md) + [Checkbox](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checkbox.md) + [Photo Capture](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/photo-capture.md) + [Signature Pad](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/signature-pad.md) + [Question Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/question-card.md)

## Install the starter kit

One command installs the theme and the components this playbook uses:

```bash
npx shadcn@latest add @opendraft/kit-healthcare
```

## Known gaps

- Patient banner and chart overview: No patient-banner component and nothing is sticky: wrap the banner in your own sticky container so it never scrolls away.
- Lab results and vitals with abnormal flags: Reference ranges, flags and units must come from your system of record. `time-series-chart` is not a waveform viewer (ECG) and does not annotate events; always keep the values in a table beside any chart.
- Appointment booking and scheduling: `order-confirmation` is ticket-shaped: it always prints the email sentence, a Total in money format (a free visit shows 0.00), an order summary of priced lines and a QR ticket. For free visits compose a `ticket-pass`, a `stat` row and `button`s instead. Availability, double-booking rules and reminders come from your scheduling system; `scheduler` only marks overlaps.
- Medication list and orders: No drug-interaction or dose-check UI, and no medication-specific component; interaction warnings come from your clinical decision support service and are shown with a persistent `alert`.
- Telehealth visit: `video-player` plays a file or stream URL; it is not a call surface. No live video tile grid or device check: embed a video SDK and lay out the tiles yourself. For an in-visit text chat compose `message`, `message-bubble` and `prompt-input` (leave `models` empty).
- Patient intake forms and consent: Store the signature with a timestamp and the consent text version in your backend; the pad only returns an image. No rich text editor needed here. For date of birth use three `input`/`select` fields: `date-picker` only has previous and next month buttons, so going back decades is slow. `question-card` always shows a Skip action and a free-text 'Something else' option and has no scoring or branching.
- Care plan and visit history: Clinical documentation standards, templates and coding are your system's job; the editor only captures formatted text (HTML or JSON) and does not autosave or track versions.
- Secure messaging with the care team: No attachment preview, read-receipt logic, thread list data model or clinician routing (only the slots to render them); only two sides (`user`/`assistant`). Keep the thread data on your own secure backend.
- Sign in with MFA and a proxy or caregiver: `settings-page` roles are fixed to owner, admin, member and viewer (viewer is the nearest to a read-only proxy), and the section has no consent scope or expiry, so build those with `switch`, `date-picker` and a `data-table`. Verification of the code is your auth provider's job.

Docs: https://ui-system-virid.vercel.app/docs/use-cases

---

# Building Fintech and banking products with opendraft

> Banking, payments, trading, personal finance and lending products. Money moves, so precision, clear fees and honest balances matter more than delight; many actions cannot be undone.

Read this before building for this domain. Follow the rules in https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt as well. Names below link to each component's page (props, types, example).

## Use this playbook when the product involves

fintech, banking, bank, payments, payment, transfer, card, neobank, trading, brokerage, portfolio, personal finance, budget, lending, loan, mortgage, invoice, crypto.

## Principles for this domain

- Format money with the locale and ISO 4217 currency (`Intl.NumberFormat`), show the currency on every amount that might be ambiguous, align figures right in `tabular-nums` and keep minor units. Never compute with floating point; use integer minor units or a decimal library.
- Treat transfers, payouts and trades as irreversible: show a review step with payee, amount, fee, rate and arrival time, then confirm. Require step-up authentication (a one-time code or biometric) before a high-risk action.
- Show every fee, rate and the final total before the user commits, not after. If the amount can change (FX, market orders), say so and show when the quote expires.
- Be honest about balance: label Available versus Pending versus Current, show `as of` time, and mark data that is delayed. Never show an optimistic balance as if it had settled.
- Never use red and green alone for gain and loss; add a sign and an arrow or word (`+2.4%`, `Down`). `stat`'s `delta` does this (arrow plus a screen-reader word) and `goodWhen` says which direction is good news, so a falling expense reads as good. Do not use red for a number that is merely negative in an accounting sense when it is not an error.
- Keep an audit trail the user can see (activity, statements, who approved what) and mask account and card numbers by default, showing only the last four digits with an explicit reveal and `copy-button`.
- opendraft is presentation only: it does not move money, price orders or check balances, and nothing here is a compliance or regulatory guarantee. Show regulatory disclosures and risk warnings your jurisdiction requires as plain text next to the action, and take quotes, balances and fees only from your backend.

## What the product needs, and what to use

Fit: **Ready** means use as is. **Adapt** means it works with the caveat given. **Gap** means nothing fits yet: build it from primitives and follow the principles above.

### Account overview and balances

- Fit: **Ready**
- Use: [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Animated Number](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/animated-number.md), [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md)
- How: `stat` tiles for each account: `value` and `hint` accept ReactNode, so pass a pre-formatted string and an `as of` hint; `delta` gives a signed change with an arrow. `animated-number` takes a plain number and an `Intl.NumberFormat` `format` (for example currency), so use it only for a hero balance and convert from minor units for display only; never inside tables. `time-series-chart` shows balance history with a `unit` formatter and a data-table fallback; `data-table` lists accounts or recent activity.

### Transaction history and search

- Fit: **Adapt**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Bulk Action Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/bulk-action-bar.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Copy Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/copy-button.md), [Date Range Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-range-picker.md)
- How: `data-table` block: `searchable`, `filters` (`filter-bar` chips for account, category, status), sortable columns, `views` (All, Pending, Posted), paging and a card layout on phones. Right-align the amount in a `cell` renderer (`mono`, `align="right"`) and render status as `badge` (Pending, Posted, Failed). `selectable` with `bulkActions` (Export, Categorize) receives the selected rows; `copy-button` for a reference id. For years of history use the virtualized `table` with `onEndReached`.
- Missing: No saved searches. Date narrowing is by calendar day (`date-range-picker`); use `date-time-picker` for exact bounds. CSV export and statement PDFs are yours to build.

### Send money / transfer with review and step-up auth

- Fit: **Adapt**
- Use: [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [MFA Step](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/mfa-step.md), [Dialog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dialog.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Description List](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/description-list.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Copy Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/copy-button.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- How: `stepper` flow (payee, amount, review, verify, done; `description` can carry the chosen payee). Review step is a `description-list` or `stat`/`StatGroup` of payee, amount, fee, rate and arrival, then a confirm `button` (optionally in a `dialog`). `mfa-step` for step-up (`methods`, async `onVerify`, `onResend` with a countdown, error and `locked` states). Receipt: `alert` success, `description-list` with a `copyable` reference and a `timeline` of the transfer status (initiated, processing, arrives).
- Missing: No review or receipt component. `order-confirmation` is ticket-shaped (QR tickets, qty by price lines, email sentence) and `approval-card` ends with an Approved badge, so neither suits a transfer. `mfa-step` only collects the code; verification, limits and lockout policy are your backend's.

### Card checkout and payment methods

- Fit: **Gap**
- Use: [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md), [Address Form](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/address-form.md), [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- How: The `checkout` block is built for ticket and booking purchases: details step is name, email, phone, an 'I'm booking for someone else' attendee and a delivery choice (digital pass by email or collect at front desk), payment is card or pay later, and the confirmation prints a ticket pass per item. Most of this copy is fixed. Build a payment form from `field`, `input` and `radio-group` (saved methods as radio cards), `address-form` for the billing address (per-country postal rules), a `stepper`, and mount your provider's hosted fields for the card.
- Missing: `checkout` does not fit bank or card products and its card form cannot be lifted out of the block. There is no card-number component: card entry belongs in your provider's hosted fields. Compose the rest from primitives.

### Portfolio, positions and market data

- Fit: **Adapt**
- Use: [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md), [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md), [Analytics Dashboard](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/analytics-dashboard.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Insight Cards](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/insight-cards.md)
- How: Holdings in `data-table` with a signed change cell (sign, arrow or word, not color alone). `time-series-chart` plots portfolio value or a price line: several `series`, a named `timeZone`, brush zoom, keyboard stepping, thresholds (for example a target) and a data-table fallback. `analytics-dashboard` can be relabelled for portfolio value: KPI metrics take `Intl` `format` (currency), the `channels` share bar can show asset allocation, and `valueColumn`/`formatVisitors`/`formatConversion` repurpose table columns (quantity, weight, value).
- Missing: No candlestick or OHLC chart, no crosshair across panes, no order book and no live ticker; use a charting library for those and keep numbers in tabular figures. `analytics-dashboard` ranges are fixed at 7/30/90 days.

### Place a trade or order

- Fit: **Adapt**
- Use: [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Slider](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/slider.md), [Quantity Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/quantity-stepper.md), [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md), [Dialog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dialog.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md)
- How: `tabs` for Buy and Sell (label them in words); `quantity-stepper` for whole units (`min`, `max`, `step`) or `input` for fractional ones; `slider` with `marks` and `formatValue` for a percent of balance; an order preview in a `dialog` with `stat`s for estimated cost, fees and quote time, and a confirm button. An `alert` for market-closed or price-moved warnings.
- Missing: No market-depth or order-ticket component; the estimated price must come from your pricing service and show when it was quoted.

### Spending insights and budgets

- Fit: **Adapt**
- Use: [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md), [Analytics Dashboard](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/analytics-dashboard.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md)
- How: `progress` with `tone="auto"` measures consumption by default (a fuller bar turns warning, then destructive), which suits category budgets; set `label` and `valueLabel` (`$320 of $400`). `gauge` shows overall budget used with `thresholds` and a text status. `stat` for totals with `delta` and `goodWhen="down"` for spend. `time-series-chart` for monthly spend against a budget `threshold`. `analytics-dashboard` (relabelled) adds a stacked share bar for category breakdown.
- Missing: No donut chart and no cash-flow (Sankey) chart; the category breakdown is a single stacked horizontal bar with five tones. `analytics-dashboard` ranges are fixed at 7, 30 and 90 day tabs (relabel them).

### Loan or credit application

- Fit: **Adapt**
- Use: [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Slider](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/slider.md), [Repeater Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/repeater-field.md), [Address Form](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/address-form.md), [Photo Capture](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/photo-capture.md), [Dropzone](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dropzone.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md)
- How: `slider` for amount and term (`formatValue`, `marks`), a live repayment summary in `stat`s, `repeater-field` for income sources or existing debts, `address-form` for the residential address, `dropzone` or `photo-capture` for income documents, and an `alert` plus `timeline` for 'application received' and next steps.
- Missing: No amortization schedule with built-in calculations; compute it server-side and render it with `table`. `order-confirmation` is ticket-shaped, so it is not used for the submitted state.

### KYC and identity verification

- Fit: **Adapt**
- Use: [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Address Form](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/address-form.md), [Photo Capture](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/photo-capture.md), [Dropzone](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dropzone.md), [MFA Step](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/mfa-step.md), [Status Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/status-indicator.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md)
- How: `stepper` (with `description`) for the checks; `address-form` for the residential address; `photo-capture` takes ID and selfie photos from the phone camera (camera or file, `max`, `facing`); `dropzone` for proof-of-address documents; `mfa-step` for phone or email codes. Show each check with a `status-indicator` using `label` and `tone` overrides (Pending, Verified, Needs attention) or a `badge`.
- Missing: `photo-capture` only takes still images: there is no live camera preview, document frame overlay or liveness check. Use your identity provider's SDK for those.

### Security, limits and audit trail

- Fit: **Adapt**
- Use: [Switch](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/switch.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Slider](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/slider.md), [Secret Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/secret-input.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Dialog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dialog.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Settings Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/settings-page.md), [MFA Step](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/mfa-step.md), [Permission Matrix](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/permission-matrix.md)
- How: Card freeze and alert preferences as `switch` rows, limits with `field` or `slider`, login and device history in `data-table` or `timeline` (mono timestamps, status markers), and a type-to-confirm `dialog` for closing an account. `mfa-step` re-verifies before changing limits. `secret-input` for API tokens on business accounts and `permission-matrix` for what each delegate may do. `settings-page` can supply the grouped switch rows (its `notifications` groups) and a type-to-confirm danger zone (`dangerLabels`, `sections`).
- Missing: `settings-page` sections are fixed to profile, notifications, team and billing and the danger-zone confirmation requires typing the `workspaceName`; there is no security, devices or limits section, so compose those from the primitives.

## Libraries and services that pair well

- Payments and card acceptance: Stripe Elements, Adyen Drop-in, Braintree. Mount the provider's hosted fields inside your own payment form (built from `field` and `radio-group`) so card data never touches your app; send your backend a token only.
- Bank account linking and open banking data: Plaid Link, TrueLayer, MX. These open their own modal; surround it with an opendraft `dialog` that explains what is shared and wait for the result before updating balances.
- Money math and currency formatting: Intl.NumberFormat, dinero.js, decimal.js. Pass already formatted strings to `stat` and to `table` cell renderers; keep amounts in integer minor units in your data layer.
- Price and performance charts: TradingView Lightweight Charts, Recharts, visx. time-series-chart ships a line chart with axes, thresholds, zoom and a table fallback. For candlesticks, crosshair or live price charts, theme a library with design tokens and add a text value readout so gain and loss do not rely on color.
- Identity verification and fraud signals: Persona, Onfido, Sumsub. Use their SDK for document and liveness capture; photo-capture only takes still photos. Show the outcome with `status-indicator` and `alert`.

## Typical screens

- **Accounts overview**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md) + [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md) + [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md)
- **Transactions**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md) + [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md) + [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md) + [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- **Send money**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md) + [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md) + [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md) + [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md) + [MFA Step](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/mfa-step.md) + [Description List](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/description-list.md) + [Dialog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dialog.md) + [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md) + [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md) + [Copy Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/copy-button.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md)
- **Portfolio**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md) + [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md)
- **Security and limits**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Switch](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/switch.md) + [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md) + [Secret Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/secret-input.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md) + [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md) + [Dialog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dialog.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md)

## Install the starter kit

One command installs the theme and the components this playbook uses:

```bash
npx shadcn@latest add @opendraft/kit-fintech
```

## Known gaps

- Transaction history and search: No saved searches. Date narrowing is by calendar day (`date-range-picker`); use `date-time-picker` for exact bounds. CSV export and statement PDFs are yours to build.
- Send money / transfer with review and step-up auth: No review or receipt component. `order-confirmation` is ticket-shaped (QR tickets, qty by price lines, email sentence) and `approval-card` ends with an Approved badge, so neither suits a transfer. `mfa-step` only collects the code; verification, limits and lockout policy are your backend's.
- Card checkout and payment methods: `checkout` does not fit bank or card products and its card form cannot be lifted out of the block. There is no card-number component: card entry belongs in your provider's hosted fields. Compose the rest from primitives.
- Portfolio, positions and market data: No candlestick or OHLC chart, no crosshair across panes, no order book and no live ticker; use a charting library for those and keep numbers in tabular figures. `analytics-dashboard` ranges are fixed at 7/30/90 days.
- Place a trade or order: No market-depth or order-ticket component; the estimated price must come from your pricing service and show when it was quoted.
- Spending insights and budgets: No donut chart and no cash-flow (Sankey) chart; the category breakdown is a single stacked horizontal bar with five tones. `analytics-dashboard` ranges are fixed at 7, 30 and 90 day tabs (relabel them).
- Loan or credit application: No amortization schedule with built-in calculations; compute it server-side and render it with `table`. `order-confirmation` is ticket-shaped, so it is not used for the submitted state.
- KYC and identity verification: `photo-capture` only takes still images: there is no live camera preview, document frame overlay or liveness check. Use your identity provider's SDK for those.
- Security, limits and audit trail: `settings-page` sections are fixed to profile, notifications, team and billing and the danger-zone confirmation requires typing the `workspaceName`; there is no security, devices or limits section, so compose those from the primitives.

Docs: https://ui-system-virid.vercel.app/docs/use-cases

---

# Building E-commerce and marketplaces products with opendraft

> Storefronts, marketplaces and seller dashboards. Shoppers need honest prices and stock and a fast path to pay; sellers need to manage orders and inventory in bulk.

Read this before building for this domain. Follow the rules in https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt as well. Names below link to each component's page (props, types, example).

## Use this playbook when the product involves

ecommerce, e-commerce, store, storefront, shop, marketplace, cart, checkout, product, catalog, inventory, orders, seller, merchant, retail, returns, wishlist, discount.

## Principles for this domain

- Be honest about price and availability: show the total with tax, shipping and fees before checkout, strike through a compare-at price only when it is real, and show stock states in words (In stock, Only 3 left, Sold out) from live data. `progress` with `tone="auto"` and `invert` can show remaining stock, but pair it with the words.
- Persist the cart across sessions and devices, never silently change a quantity or price, and if something changed since the user added it, say what changed (an `alert`) and let them decide.
- Show trust signals where the decision happens: delivery date, return window, secure payment note, ratings with the review count and who can leave a review. Do not invent urgency such as fake countdowns or invented stock numbers.
- Offer guest checkout and fast payment options; ask for the fewest fields, validate inline and keep the order summary visible while the user fills the form.
- State returns, refunds and shipping costs in plain words before purchase, and give the order status and the next step on every order screen.
- Make sold-out and error states useful: offer a back-in-stock notification or similar items, keep filters on a no-results page and keep the user's progress when a payment fails.
- Check which opendraft blocks fit before using them: `catalog`, `detail-page`, `checkout` and `order-confirmation` are built for dated, seat-limited, ticketed things (classes, tours, events). For physical goods use `product-card` (with `ProductGrid`), `image-gallery`, `rating` and `address-form` and compose the rest from primitives; the playbook below says which.

## What the product needs, and what to use

Fit: **Ready** means use as is. **Adapt** means it works with the caveat given. **Gap** means nothing fits yet: build it from primitives and follow the principles above.

### Browse, search and filter products

- Fit: **Adapt**
- Use: [Product Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/product-card.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Empty State](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/empty-state.md), [Skeleton](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/skeleton.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- How: `ProductGrid` (from the `product-card` file) lays out `product-card` tiles: `title`, `image` (or `renderImage` for your framework's image), `price` with `compareAtPrice`, `currency`/`locale`, text `badges`, a `rating` slot (pass a `rating` display), `outOfStock` and `onAdd`/`href`. Above it, `filter-bar` gives search, single and multi-select facets (size, color, brand) as removable chips with clear-all, and `select` handles sort. `skeleton` while loading; `empty-state` (with `live`) for no results and a Clear filters action that keeps the other filters.
- Missing: `filter-bar` renders the controls from a config; you compute the facets and counts and filter or query your own data (`search-list` takes plain strings only). No price-range slider facet, no infinite scroll or pagination component. `catalog` is not for retail products: every item requires `host`, an ISO `date`, `capacity` and `remaining`.

### Sell bookable things: classes, tours, workshops, tickets

- Fit: **Ready**
- Use: [Catalog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/catalog.md), [Detail Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/detail-page.md), [Checkout](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checkout.md), [Order Confirmation](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/order-confirmation.md), [Ticket Pass](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/ticket-pass.md)
- How: This is what the blocks are built for. `catalog` (search, category chips, sort, price buckets, availability switch, grid or compact list, ISO `currency`) lists items shaped title, host, location, category, date, price, capacity, remaining. `detail-page` shows media, key facts, About, Schedule and FAQ tabs, tiers with quantity, running total, checkout and waitlist (`onWaitlist`, relabel to Notify me via `labels`). `checkout` takes `items`, `fees`, `currency`, `discountCodes` and an async `onPay` that gets masked card data (last four only). `order-confirmation` and `ticket-pass` give the receipt and QR passes. Map `DetailCheckout` ({tierId, quantity}) to `CheckoutItem`s yourself.

### Product detail with variants and purchase panel

- Fit: **Adapt**
- Use: [Image Gallery](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/image-gallery.md), [Rating](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/rating.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Accordion](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/accordion.md), [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md), [Quantity Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/quantity-stepper.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Description List](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/description-list.md)
- How: Compose: `image-gallery` for the main image with thumbnails, keyboard and swipe navigation and a click-to-zoom lightbox (`images` need real `alt` text); `rating` (display) with the review count; `tabs` or `accordion` for description, specs, shipping and returns, with specs in `description-list`; `radio-group` styled as size chips or swatches for variants (disable out-of-stock options); `quantity-stepper` with `max` set to stock; a `badge` for In stock or Sold out; `progress` with `tone="auto"` and `invert` for a low-stock bar; a primary `button` plus a Notify me action when sold out.
- Missing: `detail-page` is an event-ticket page, not a product page: it requires `date` and a `host` and its options are seat-limited 'tiers'. There is no variant picker or swatch component, no size guide and no 360 or video media in `image-gallery` (use `video-player` for a product video).

### Ratings and reviews

- Fit: **Adapt**
- Use: [Rating](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/rating.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Avatar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/avatar.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Accordion](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/accordion.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md), [Textarea](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/textarea.md), [Rich Text Editor](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/rich-text-editor.md)
- How: `rating` shows stars with half steps, a text value and a count (`Rating` with `value`, `count`) and a distribution breakdown (rows per star count); as an input (`RatingInput`) it takes `onValueChange`, `allowHalf`, `required` and keyboard arrows for the review form. Reviews are your own list with `avatar`, a 'Verified purchase' `badge` only when you can verify it, `accordion` for long text and `textarea` for the form body.
- Missing: No review list, sorting or helpful-vote component; show only reviews you can verify and moderate them in your backend.

### Shopping cart and mini-cart

- Fit: **Adapt**
- Use: [Drawer](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/drawer.md), [Quantity Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/quantity-stepper.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Empty State](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/empty-state.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Separator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/separator.md), [Toast](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/sonner.md)
- How: A cart in a `drawer` (side sheet, closes on Esc or backdrop; you supply the header, since it has no title slot) with `quantity-stepper` lines (`max` = stock), a subtotal and a checkout `button`; `empty-state` when empty; `alert` when a price or availability changed; `sonner` for 'added to cart' feedback.
- Missing: No cart component: build the line list yourself and persist the cart on your backend. `checkout` has a quantity-stepper order summary but only inside its ticket flow.

### Checkout (guest or account) and payment for physical goods

- Fit: **Adapt**
- Use: [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Address Form](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/address-form.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md), [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md), [Checkbox](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checkbox.md), [Quantity Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/quantity-stepper.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- How: Build with `stepper` (shipping, delivery, payment, review; steps take a `description`), `address-form` for shipping and billing addresses (per-country postal and region rules, validation and correct autocomplete tokens), `radio-group` for shipping methods (price and arrival date in each option), `checkbox` for billing same as shipping, an order summary list with totals, a discount code `input`, and your payment provider's hosted fields and wallet buttons.
- Missing: The `checkout` block cannot do this: its details step is Full name, Email, Phone and an 'I'm booking for someone else' attendee, then a delivery choice of 'Digital pass by email' or 'Collect at the front desk' (hard-coded), payment is card or 'Pay later (within 3 days)', and the confirmation prints a QR ticket pass per item. There is no shipping-method picker, order-summary component or wallet-button slot, and `address-form` does not look up addresses. Tax and shipping rates come from your backend.

### Order confirmation and tracking

- Fit: **Adapt**
- Use: [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Copy Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/copy-button.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- How: `timeline` is a ready tracking view: statuses success, current and upcoming for Placed, Packed, Shipped and Delivered, `timestamp` and `time`, `meta` for the carrier or location, expandable detail for scan events, and a loading state. `stepper` (steps accept `description` for an estimated date) for the coarse stages; `copy-button` for the tracking number; `alert` for a delay. Order totals in `stat`s and your own line list.
- Missing: `order-confirmation` is ticket-shaped: it always prints 'A confirmation was sent to' with the email, a Tickets stat, a 'Your tickets' section with a QR pass per ticket (an empty list leaves a bare heading), a priced line list, and a stepper that is always fully completed (Details, Payment, Confirmation), with no shipping status. Use it only for tickets and bookings.

### Returns and refunds

- Fit: **Adapt**
- Use: [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md), [Checkbox](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checkbox.md), [Textarea](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/textarea.md), [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md), [Dropzone](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dropzone.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- How: A `stepper` flow: choose items (`checkbox`), reason (`select`), notes (`textarea`), photos with `dropzone` (`accept`, `maxFiles`, `capture`), then refund or exchange (`radio-group`) and a review step; show the return deadline in an `alert`.
- Missing: No printable return-label view; render it from your carrier's PDF.

### Seller dashboard: sales and performance

- Fit: **Adapt**
- Use: [Analytics Dashboard](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/analytics-dashboard.md), [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md), [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md)
- How: Relabel `analytics-dashboard` for revenue, orders and conversion: metrics have `Intl` `format` and a delta vs the previous period, there is a single-series line chart with metric tabs, a sortable table (name, visitors, conversion 0-1, and a custom `valueColumn` for revenue) and a stacked share bar in `channels`. For your own series (revenue against last period, orders per hour) use `time-series-chart`: several series, a named `timeZone`, brush zoom and a data-table fallback.
- Missing: The `analytics-dashboard` range tabs are fixed to 7d, 30d and 90d and are not driven by `date-range-picker`; its table columns are page-analytics shaped; only one stacked bar for breakdowns, no donut.

### Seller order and inventory management

- Fit: **Ready**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Bulk Action Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/bulk-action-bar.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md)
- How: `data-table` block: `views` for New, To ship and Returns, `filters` (`filter-bar` chips for channel, carrier, date), a status `badge` in a `cell`, `selectable` with `bulkActions` (Print labels, Mark shipped receive the selected rows), paging and a card layout on phones. A `progress` bar in a stock cell with `tone="auto"` and `invert`. For very long order lists use the virtualized `table` with `filter-bar` and `bulk-action-bar`.

### Create and edit a product listing

- Fit: **Adapt**
- Use: [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Rich Text Editor](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/rich-text-editor.md), [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md), [Repeater Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/repeater-field.md), [Photo Capture](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/photo-capture.md), [Dropzone](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dropzone.md), [Image Gallery](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/image-gallery.md), [Switch](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/switch.md), [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md)
- How: `field` and `FieldGroup`, `rich-text-editor` for the description (formatting toolbar, validated links, `maxLength`; store its HTML or JSON and render with its read-only renderer), `repeater-field` for variants and prices (rows built in `renderRow`), `dropzone` or `photo-capture` for photos (`multiple`, `accept`, `maxFiles`), `image-gallery` for a storefront preview, `switch` for published, `stepper` to split a long form.
- Missing: No image reordering or cropping. Sanitize rich text on the server before it reaches a storefront.

### Promotions and discount codes

- Fit: **Ready**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Dialog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dialog.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Date Range Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-range-picker.md), [Switch](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/switch.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- How: A `data-table` of codes (sortable, status `badge`, `filters` for active and expired), a `dialog` with a `field` form to create one, `date-range-picker` for the validity window and `switch` to enable it.

## Libraries and services that pair well

- Commerce backend and product data: Shopify Storefront API, Medusa, commercetools. Map products, carts and orders to the props of `product-card`, `data-table` and `timeline` in an adapter; map to `catalog`, `detail-page` and `checkout` only for dated, seat-limited items. Keep the cart on the server so it persists across devices.
- Payments, wallets and tax: Stripe, Adyen, PayPal. Mount the provider's hosted card fields and wallet buttons inside your own payment step; send your backend a token only. Tax should come from the provider so the total shown is the total charged.
- Product search and filtering: Algolia, Typesense, Meilisearch. Drive filter-bar facets and product-card grids from the search results; filter-bar renders the chips but you supply facet options and counts. For event-style items, results can feed `catalog` through its `items` prop.
- Shipping rates and tracking: Shippo, EasyPost, AfterShip. Show their rates as `radio-group` options in your checkout and their tracking events in a `timeline`.
- Reviews and ratings: Yotpo, Judge.me, Trustpilot. rating draws stars with a text value and count, and a distribution breakdown. These services supply the reviews; display only reviews you can verify.

## Typical screens

- **Shop and category**: [Site Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/site-header.md) + [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md) + [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md) + [Product Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/product-card.md) + [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md) + [Skeleton](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/skeleton.md) + [Empty State](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/empty-state.md)
- **Product page**: [Site Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/site-header.md) + [Image Gallery](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/image-gallery.md) + [Rating](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/rating.md) + [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md) + [Accordion](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/accordion.md) + [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md) + [Quantity Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/quantity-stepper.md) + [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md) + [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md) + [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- **Cart**: [Drawer](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/drawer.md) + [Quantity Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/quantity-stepper.md) + [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md) + [Separator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/separator.md) + [Empty State](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/empty-state.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md)
- **Checkout**: [Site Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/site-header.md) + [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md) + [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md) + [Address Form](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/address-form.md) + [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md) + [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md) + [Checkbox](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checkbox.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md) + [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- **Order status**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md) + [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md) + [Copy Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/copy-button.md) + [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md) + [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- **Book a class or event**: [Site Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/site-header.md) + [Catalog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/catalog.md) + [Detail Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/detail-page.md) + [Checkout](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checkout.md) + [Order Confirmation](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/order-confirmation.md)
- **Seller orders**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md) + [Bulk Action Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/bulk-action-bar.md) + [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md) + [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- **Seller overview**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md) + [Analytics Dashboard](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/analytics-dashboard.md)

## Install the starter kit

One command installs the theme and the components this playbook uses:

```bash
npx shadcn@latest add @opendraft/kit-ecommerce
```

## Known gaps

- Browse, search and filter products: `filter-bar` renders the controls from a config; you compute the facets and counts and filter or query your own data (`search-list` takes plain strings only). No price-range slider facet, no infinite scroll or pagination component. `catalog` is not for retail products: every item requires `host`, an ISO `date`, `capacity` and `remaining`.
- Product detail with variants and purchase panel: `detail-page` is an event-ticket page, not a product page: it requires `date` and a `host` and its options are seat-limited 'tiers'. There is no variant picker or swatch component, no size guide and no 360 or video media in `image-gallery` (use `video-player` for a product video).
- Ratings and reviews: No review list, sorting or helpful-vote component; show only reviews you can verify and moderate them in your backend.
- Shopping cart and mini-cart: No cart component: build the line list yourself and persist the cart on your backend. `checkout` has a quantity-stepper order summary but only inside its ticket flow.
- Checkout (guest or account) and payment for physical goods: The `checkout` block cannot do this: its details step is Full name, Email, Phone and an 'I'm booking for someone else' attendee, then a delivery choice of 'Digital pass by email' or 'Collect at the front desk' (hard-coded), payment is card or 'Pay later (within 3 days)', and the confirmation prints a QR ticket pass per item. There is no shipping-method picker, order-summary component or wallet-button slot, and `address-form` does not look up addresses. Tax and shipping rates come from your backend.
- Order confirmation and tracking: `order-confirmation` is ticket-shaped: it always prints 'A confirmation was sent to' with the email, a Tickets stat, a 'Your tickets' section with a QR pass per ticket (an empty list leaves a bare heading), a priced line list, and a stepper that is always fully completed (Details, Payment, Confirmation), with no shipping status. Use it only for tickets and bookings.
- Returns and refunds: No printable return-label view; render it from your carrier's PDF.
- Seller dashboard: sales and performance: The `analytics-dashboard` range tabs are fixed to 7d, 30d and 90d and are not driven by `date-range-picker`; its table columns are page-analytics shaped; only one stacked bar for breakdowns, no donut.
- Create and edit a product listing: No image reordering or cropping. Sanitize rich text on the server before it reaches a storefront.

Docs: https://ui-system-virid.vercel.app/docs/use-cases

---

# Building Education and learning products with opendraft

> Learning platforms, courses, classrooms and student information systems. Learners need to know where they are and what is next; instructors need to see a whole class at a glance and act in bulk.

Read this before building for this domain. Follow the rules in https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt as well. Names below link to each component's page (props, types, example).

## Use this playbook when the product involves

education, learning, lms, course, courses, classroom, student, teacher, instructor, school, university, lesson, quiz, assignment, grades, gradebook, enrollment, edtech.

## Principles for this domain

- Make progress visible everywhere: where the learner is in the course, what is done, what is next and how long it takes. Use `progress` (`label` and `valueLabel`, e.g. `3 of 8 lessons`) and always offer a clear Continue action. Keep the default brand tone, or `success` at 100%: `tone="auto"` treats a full bar as bad.
- Accessibility first: sufficient contrast, full keyboard use, captions and transcripts for media, readable text sizes, no time limits that cannot be extended, and no meaning by color alone. Learners often use shared, older or assistive devices.
- Give low-pressure feedback: say what was right and what to try next, avoid red-X shaming, let learners retry, and show a grade only when the instructor chooses to release it. Celebrate completion without confetti that cannot be turned off.
- Separate instructor and learner views: the same course shows authoring, grading and class analytics to instructors, and only the learner's own work and progress to students. Never expose other students' names or grades.
- Be offline-tolerant: save drafts and answers locally as the learner types, show a visible Saved or Not saved state, and queue submissions with a clear status when the connection drops.
- Protect minors' data: avoid public profiles by default, show only what a guardian or teacher needs, and put sensitive records behind explicit access. Where your rules require it, keep consent and access records; opendraft makes no compliance guarantee.

## What the product needs, and what to use

Fit: **Ready** means use as is. **Adapt** means it works with the caveat given. **Gap** means nothing fits yet: build it from primitives and follow the principles above.

### Course catalog and enrollment

- Fit: **Adapt**
- Use: [Catalog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/catalog.md), [Detail Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/detail-page.md), [Checkout](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checkout.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md)
- How: Works for cohort or scheduled courses. `catalog`: `host` is the instructor (set `labels.hostLabel` to 'Taught by'), `date` the start date, `capacity` and `remaining` the seats, `category` the subject, `priceRanges` and `currency` for fees (price 0 shows the free label). `detail-page`: tiers are enrolment options (full price, concession), the Schedule tab is the week-by-week outline, key facts for length and level, FAQ, `onWaitlist` for full cohorts; relabel with `labels`. `checkout` for paid enrolment.
- Missing: Item shape is event-shaped: `host`, `date`, `capacity` and `remaining` are required and the date block and seats are always shown, so self-paced courses with no start date or seat limit don't fit (use `card`, `input`, `select` and `badge`). No prerequisite or level filters. `checkout` has fixed copy (booking for someone else, digital pass or desk collection, a QR ticket on confirmation); free enrolment can skip it and call your API from `onCheckout`.

### Learner dashboard: courses in progress

- Fit: **Ready**
- Use: [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/card.md), [Empty State](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/empty-state.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- How: One `card` per course with `progress` (`label` is the course, `valueLabel` '3 of 8 lessons') and a Continue `button`; `stat` for streak or time spent; `tabs` for In progress and Completed; `empty-state` for a new learner. Don't set `tone="auto"` on completion bars: it reads a full bar as bad.

### Lesson and module navigation

- Fit: **Ready**
- Use: [Step Navigation](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/step-nav.md), [Accordion](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/accordion.md), [Sidebar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/animated-sidebar.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- How: `step-nav` is the syllabus: `steps` with status complete, current, available or locked (a `lockedReason` explains why), non-linear jumping with `onSelect`, a `{done} of {total} complete` summary and a vertical layout for a sidebar or horizontal for a short path. Group modules in an `accordion` with a `step-nav` inside, or use an `animated-sidebar` menu (menu buttons with `isActive`, `disabled`, a `badge` slot, sub-menus, a mobile sheet) around it. `progress` for the module. `sidebar-nav` is an AI chat sidebar, not course navigation.

### Video and reading lesson content

- Fit: **Adapt**
- Use: [Video Player](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/video-player.md), [Document Viewer](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/document-viewer.md), [Transcript Viewer](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/transcript-viewer.md), [Audio Player](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/audio-player.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Accordion](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/accordion.md), [Code Block](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/code-block.md), [Skeleton](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/skeleton.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md)
- How: `video-player` for the lesson video: seek, volume, speed, captions (`tracks`), `chapters`, keyboard shortcuts, `startAt` to resume, `onProgress` to report watched time into `progress`, and an error state with retry. `transcript-viewer` and `audio-player` for podcasts and audio lessons. `document-viewer` is the shell for slides and PDFs: page navigation, zoom, search and download with thumbnails; it renders pages through `renderPage` or `src`. Transcript, notes and resources sit in `tabs` beside the player; `accordion` for chapters; `code-block` for programming lessons.
- Missing: `document-viewer` is a shell, not a PDF engine: you supply the page rendering (for example with PDF.js) or an embeddable `src`. `video-player` plays a file or HLS-capable source; DRM, adaptive streaming setup and watch-time analytics come from your video host.

### Quizzes and assessments

- Fit: **Gap**
- Use: [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md), [Checkbox](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checkbox.md), [Textarea](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/textarea.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Dialog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dialog.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md), [Question Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/question-card.md)
- How: Compose a quiz: `radio-group` and `checkbox` for answers, `textarea` for short answers, `progress` with `label` '4 of 10', a `dialog` that confirms submit and names unanswered questions, and an `alert` for time remaining. Keep scoring and explanations in your code and show them with `badge` and `alert`. `question-card` suits ungraded warm-up questions or polls.
- Missing: `question-card` is survey-shaped, not a quiz: questions are `{q, type, options}` strings with no correct answer, single choice auto-advances so answers cannot be reviewed first, there is always a Skip button and a free-text 'Something else' option, and it returns answers by index with no scoring or feedback. No timer with accessibility extensions, no question-bank authoring.

### Assignment submission and files

- Fit: **Ready**
- Use: [Dropzone](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dropzone.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Textarea](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/textarea.md), [Rich Text Editor](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/rich-text-editor.md), [Photo Capture](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/photo-capture.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- How: `dropzone` for uploads (`accept`, `maxSize`, `maxFiles`, a `files` list with progress and per-file error; you handle the upload), `rich-text-editor` for a written answer, `photo-capture` to photograph handwritten work, a status `badge` (Not started, Submitted, Late, Graded), `timeline` for submission history, and an `alert` for the deadline.

### Gradebook and feedback (instructor)

- Fit: **Adapt**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/table.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Bulk Action Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/bulk-action-bar.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Textarea](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/textarea.md), [Slider](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/slider.md), [Drawer](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/drawer.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Rating](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/rating.md)
- How: `table` is the grid: virtualized (fixed `rowHeight`, `height`), sticky header, sortable, resizable and reorderable columns, `selectable` with `onSelectionChange` (ids) and `getRowId`, and `editable` columns with `onCellEdit` for inline score entry (plain text input, so validate the number yourself). `filter-bar` above it for section and status, and `bulk-action-bar` over the selection (Release grades, Send reminder). Open feedback in a `drawer` with `textarea` (or `rich-text-editor`) and a `slider` per rubric criterion (`marks`, `formatValue`). For a small class `data-table` also gives cards on phones.
- Missing: No rubric component and no sticky first column. The virtualized `table` scrolls sideways on phones. Grade calculation and release rules belong in your backend.

### Class and cohort analytics

- Fit: **Adapt**
- Use: [Analytics Dashboard](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/analytics-dashboard.md), [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md), [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md)
- How: Relabel `analytics-dashboard`: KPI cards with delta (completion, average score), one metric line chart with tabs, a sortable table per assignment, and the `channels` stacked bar can show grade bands. `time-series-chart` plots your own series (submissions per day against the deadline, several cohorts) with `thresholds` and a data-table fallback. `gauge` for cohort completion with a text status; `progress` per assignment.
- Missing: `analytics-dashboard` ranges are fixed to three tabs (7d, 30d, 90d; relabel to week, month, term) and are not driven by `date-range-picker`. No histogram and no per-student drill-down chart.

### Timetable, deadlines and events

- Fit: **Adapt**
- Use: [Scheduler](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/scheduler.md), [Gantt](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gantt.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Date Time Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-time-picker.md)
- How: `scheduler` block for a timetable: `resources` are rooms, classes or teachers, `events` are sessions, with day and week views and an agenda on narrow widths. `gantt` for a term plan with assignment due dates and dependencies. `timeline` lists upcoming deadlines in order (`time`, `timestamp`, status current, upcoming or destructive for overdue, `meta` for the course); `alert` for due soon; `date-time-picker` to set a reminder or a due time in a named `timeZone`.
- Missing: `scheduler` is a resource day and week view, not a month grid with event dots; no recurrence rules or iCal sync, so expand repeats and export calendars in your backend.

### Discussion and AI tutor

- Fit: **Adapt**
- Use: [Chat App](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/chat-app.md), [Message](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/message.md), [Message Bubble](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/message-bubble.md), [Message Scroller](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/message-scroller.md), [Prompt Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/prompt-input.md), [Rich Text Editor](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/rich-text-editor.md), [Streaming Response](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/streaming-response.md), [Citations](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/citations.md), [Avatar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/avatar.md)
- How: `message` rows (`from` is `user` or `assistant`) with `avatar`; `prompt-input` as the composer (omit `models`); `streaming-response` for tutor answers (status streaming, complete or error, copy, retry, up or down feedback, and a `sources` list); `citations` lets a tutor point to course material; `message-scroller` follows streamed output. For longer forum posts use `rich-text-editor` with its read-only renderer. Label AI answers clearly.
- Missing: No threaded forum with replies, reactions or moderation, and no instructor review queue; only two message sides. Build those from `message` and `table`.

## Libraries and services that pair well

- Video lessons with captions: Mux Player, Video.js, Vimeo Player API. video-player covers captions, chapters, speed and resume; use these only for adaptive streaming, DRM or analytics. Report progress back to update `progress` and place the transcript beside it.
- LMS interoperability and content standards: LTI 1.3, xAPI, SCORM Cloud. These sit in your backend; opendraft only renders the resulting course, grade and progress data, so map them into the props of `progress`, `table` and `stepper`.
- Rostering and sign-in with school accounts: Clever, ClassLink, Google Workspace for Education. `auth-screen` takes a `providers` list for the provider buttons but always shows the email and password form; keep roles (student, teacher, guardian) in your own data so views can differ.
- Offline sync and draft saving: Dexie (IndexedDB), TanStack Query persistence, RxDB. Save answers and drafts locally and show a Saved or Queued state with `badge`; flush the queue on reconnect.
- Calendar and timetable: FullCalendar, react-big-calendar, Schedule-X. scheduler (resource day and week views) and gantt (term plans) ship. Use one of these for month grids and recurrence, and keep the opendraft `timeline` for a simple upcoming-deadlines list.

## Typical screens

- **Learner home**: [Site Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/site-header.md) + [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md) + [Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/card.md) + [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md) + [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md) + [Empty State](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/empty-state.md) + [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- **Course catalog**: [Site Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/site-header.md) + [Catalog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/catalog.md) + [Detail Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/detail-page.md)
- **Lesson player**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Step Navigation](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/step-nav.md) + [Accordion](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/accordion.md) + [Video Player](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/video-player.md) + [Document Viewer](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/document-viewer.md) + [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md) + [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md) + [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- **Quiz**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md) + [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md) + [Checkbox](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checkbox.md) + [Textarea](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/textarea.md) + [Dialog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dialog.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md) + [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- **Assignment**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md) + [Textarea](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/textarea.md) + [Dropzone](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dropzone.md) + [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md) + [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md) + [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- **Deadlines**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Scheduler](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/scheduler.md) + [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md) + [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md)
- **Instructor gradebook**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/table.md) + [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md) + [Bulk Action Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/bulk-action-bar.md) + [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md) + [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md) + [Drawer](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/drawer.md) + [Slider](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/slider.md) + [Textarea](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/textarea.md)

## Install the starter kit

One command installs the theme and the components this playbook uses:

```bash
npx shadcn@latest add @opendraft/kit-education
```

## Known gaps

- Course catalog and enrollment: Item shape is event-shaped: `host`, `date`, `capacity` and `remaining` are required and the date block and seats are always shown, so self-paced courses with no start date or seat limit don't fit (use `card`, `input`, `select` and `badge`). No prerequisite or level filters. `checkout` has fixed copy (booking for someone else, digital pass or desk collection, a QR ticket on confirmation); free enrolment can skip it and call your API from `onCheckout`.
- Video and reading lesson content: `document-viewer` is a shell, not a PDF engine: you supply the page rendering (for example with PDF.js) or an embeddable `src`. `video-player` plays a file or HLS-capable source; DRM, adaptive streaming setup and watch-time analytics come from your video host.
- Quizzes and assessments: `question-card` is survey-shaped, not a quiz: questions are `{q, type, options}` strings with no correct answer, single choice auto-advances so answers cannot be reviewed first, there is always a Skip button and a free-text 'Something else' option, and it returns answers by index with no scoring or feedback. No timer with accessibility extensions, no question-bank authoring.
- Gradebook and feedback (instructor): No rubric component and no sticky first column. The virtualized `table` scrolls sideways on phones. Grade calculation and release rules belong in your backend.
- Class and cohort analytics: `analytics-dashboard` ranges are fixed to three tabs (7d, 30d, 90d; relabel to week, month, term) and are not driven by `date-range-picker`. No histogram and no per-student drill-down chart.
- Timetable, deadlines and events: `scheduler` is a resource day and week view, not a month grid with event dots; no recurrence rules or iCal sync, so expand repeats and export calendars in your backend.
- Discussion and AI tutor: No threaded forum with replies, reactions or moderation, and no instructor review queue; only two message sides. Build those from `message` and `table`.

Docs: https://ui-system-virid.vercel.app/docs/use-cases

---

# Building Energy, utilities and EV charging products with opendraft

> Grid operations, smart metering, solar and storage, EV charging networks, field service and customer billing for electricity, gas and water providers. Numbers carry units, time carries a zone, and some actions can hurt people or equipment.

Read this before building for this domain. Follow the rules in https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt as well. Names below link to each component's page (props, types, example).

## Use this playbook when the product involves

energy, utility, utilities, grid, smart meter, metering, scada, outage, solar, battery storage, ev charging, ocpp, kwh, tariff, demand response, field service, billing.

## Principles for this domain

- Always show the unit and the magnitude together, in `font-mono` with `tabular-nums`: `4.2 kW`, `18.6 MWh`, `230 V`. `stat` takes any node as `value`, so wrap the number and unit in a `font-mono` span. Do not auto-switch between W, kW and MW inside one column; pick one unit per column and say it in the header.
- Be honest about time series. Label the interval and aggregation (15-min average, hourly sum, daily peak), mark gaps and estimated reads as such instead of drawing a line through them, and never smooth data without saying so.
- Outage and alarm severity uses a fixed scale with a word and an icon, not color alone (for example Critical, Major, Minor, Advisory). Show start time, affected customers or assets, and estimated restoration time with its source.
- Switching, isolating or energizing equipment is guarded by interlocks: show the current state, the precondition that blocks the action, and require a confirmation that names the asset and consequence. Show who did it and when, and never allow a one-click remote switch.
- Show every timestamp with its zone, and show the asset's own local time beside the operator's. Grids span regions, and daylight saving shifts create 23- and 25-hour days; billing periods and tariffs must follow the meter's zone. `time-series-chart`, `scheduler` and `date-time-picker` take a named IANA `timeZone` (`date-time-picker` handles DST gaps and overlaps); `date-picker` and `date-range-picker` work on plain calendar dates with no zone, so keep the zone in your own data and print it next to the value.
- Separate measured, estimated and forecast values visually and in text (solid, dashed, labeled). A billing or settlement figure always shows its status: actual, estimated or disputed.

## What the product needs, and what to use

Fit: **Ready** means use as is. **Adapt** means it works with the caveat given. **Gap** means nothing fits yet: build it from primitives and follow the principles above.

### Grid and asset status overview

- Fit: **Adapt**
- Use: [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md), [Status Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/status-indicator.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Map View](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/map-view.md), [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md)
- How: `stat` tiles for load, generation and frequency (unit inside `value`, `delta` with `goodWhen` for the change chip). `gauge` shows loading against a limit with `thresholds` bands and a text status. `status-indicator` gives a shape plus a word; its five built-in statuses are operational, degraded, down, maintenance and unknown, and `label`, `tone` and `shape` override them for words like Energized or Islanded. `progress` with `tone="auto"` shows headroom against a limit. `map-view` shows substations and feeders as labelled status markers with a synced list. `alert` for active network notices, `badge` for a text severity.
- Missing: `stat` has no threshold or limit marking (use `gauge` or `progress` beside it), and there is no single-line diagram or network topology view.

### Live and historical load, generation and consumption charts

- Fit: **Adapt**
- Use: [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Date Range Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-range-picker.md), [Date Time Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-time-picker.md), [Analytics Dashboard](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/analytics-dashboard.md)
- How: `time-series-chart` is the interval chart: several `series` of `{t, v}` points where a null `v` leaves a visible gap (missing reads are not drawn through), a per-series `dash` for forecast or estimated values, `thresholds` for a capacity limit or a tariff band (a line, or a shaded band with `to`), a `unit` and `formatValue`, a named `timeZone` (so 23- and 25-hour days render correctly), brush zoom with `onZoomChange`, keyboard stepping and a built-in data-table fallback. Drive the range with `date-range-picker` for days or `date-time-picker` for exact bounds. `analytics-dashboard` still suits a KPI-plus-table overview.
- Missing: One value axis (shared `unit`): no two-axis view and no stacked area for generation mix. Aggregation (15-min average, hourly sum) happens in your backend; the chart does not resample. For tens of thousands of points per series use uPlot or ECharts.

### Smart meter list and reads

- Fit: **Ready**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Bulk Action Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/bulk-action-bar.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Date Range Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-range-picker.md), [Copy Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/copy-button.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/table.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md)
- How: `data-table` block with a meter ID in `mono` plus `copy-button`, read quality as a text `badge` (Actual, Estimated, Missing), `filters` (`filter-bar` chips for feeder, quality, tariff), `views` and `selectable` with `bulkActions` for bulk reads or commands, and a card layout on phones. For hundreds of thousands of meters use the virtualized `table` (pixel `rowHeight`, plus `height` or `maxHeight`) with `filter-bar` and `bulk-action-bar`.

### Outage management and restoration tracking

- Fit: **Adapt**
- Use: [Map View](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/map-view.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Status Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/status-indicator.md), [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md)
- How: `map-view` shows outages as labelled markers (`status` plus text) with `areas` for affected polygons and `routes` for feeders, `selectedId` synced to a `data-table` of outages with a severity `badge`. Each outage's updates go in `timeline` (`timestamp`, `status`, and `meta` for the author); restoration stages (reported, crew dispatched, repair, restored) in a vertical `stepper` where each step's `description` can carry the time and the estimated restoration source.
- Missing: `map-view` draws the shapes you pass; it does not compute affected areas, customer counts or crew routes, and it has no heat map layer. `stepper` only makes completed steps clickable.

### EV charging network and charge point status

- Fit: **Adapt**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Map View](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/map-view.md), [Status Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/status-indicator.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md)
- How: Charge points in `data-table` with a `status-indicator` per connector (use `label`, `tone` and `shape` for Available, Charging, Faulted, Offline since the built-in kinds are service-status words) and `filters` for status and connector type. `map-view` shows the stations as labelled markers with a synced list. `gauge` for session state of charge or site load against a limit; `stat` for uptime and energy delivered.
- Missing: `map-view` has no marker clustering for very large networks or live availability feed; stream status from your backend (OCPP gateway) and update the markers.

### Start and monitor a charging session (driver)

- Fit: **Adapt**
- Use: [OTP Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/otp-input.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Toast](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/sonner.md)
- How: Enter the charger code with `otp-input` (set `length` and `pattern="alphanumeric"`), show `progress` (brand tone) for charge level, `stat` for kWh, cost and time remaining, and a clear stop `button`. Use `alert` for a faulted connector.
- Missing: No QR scanner (`qr-code` only renders codes, it cannot read them) and no payment-method selector built for tap-to-pay. `checkout` is an event-ticket flow and does not fit a session payment.

### Solar and battery site dashboard

- Fit: **Adapt**
- Use: [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md), [Slider](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/slider.md), [Switch](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/switch.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md)
- How: Production, consumption, export and battery level in `stat` and `gauge` (a low battery warns with a text status; or `progress` with `invert` and `valueLabel` such as `64%`). `time-series-chart` draws the day curve with production, consumption and a dashed forecast series in the site's `timeZone`. `slider` (with `label`, `formatValue`, `marks` and `onValueCommit` so you save on release) and `switch` for reserve level and backup mode.
- Missing: No energy-flow diagram (solar to home to battery to grid). The chart has one value axis, so plot kW and state of charge in separate charts.

### Field service work orders and technician dispatch

- Fit: **Adapt**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Scheduler](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/scheduler.md), [Map View](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/map-view.md), [Checklist](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checklist.md), [Signature Pad](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/signature-pad.md), [Photo Capture](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/photo-capture.md), [Record Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/record-page.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md)
- How: Work orders in `data-table`; dispatch in the `scheduler` block (`resources` are technicians or crews, `events` are jobs, conflict marking, drag or keyboard reassignment) beside a `map-view` of job sites. Job detail is the `record-page` block (header facts, status, activity `timeline`, related items); `detail-page` is an event-ticket purchase page and does not fit. The safety and completion list is `checklist` (tickable items, notes per item, progress, sign-off); `todo-list` is a read-only plan display. Capture the customer's signature with `signature-pad` and evidence photos with `photo-capture`; supervisor approval through `approval-card`.
- Missing: `scheduler` marks time overlaps only; skills matching, travel time and routing come from your dispatch system. Offline sync of work orders is your app's job.

### Customer billing, usage and tariffs

- Fit: **Adapt**
- Use: [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Date Range Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-range-picker.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Address Form](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/address-form.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Document Viewer](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/document-viewer.md)
- How: Bill summary in `stat`, line items in `data-table`, usage over the period in `time-series-chart` (with tariff bands as threshold bands), budget used in `progress` (consumption tone), a statement period chosen with `date-range-picker`, bill status as a `badge` (Paid, Open, Disputed). `document-viewer` can show the bill PDF page by page (you supply the page rendering or `src`), with a download link. Build the payment form from `field`, `input`, `address-form` and `radio-group`, with the provider's hosted card fields.
- Missing: `checkout` and `order-confirmation` are event-ticket shaped (attendee, front-desk delivery, ticket passes) and `settings-page` billing is a SaaS plan panel with a fixed Change plan button, so none fit a utility bill. Tariff calculation is your billing system's job.

### Demand response, switching and control actions

- Fit: **Adapt**
- Use: [Dialog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dialog.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md), [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md), [Switch](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/switch.md), [Toast](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/sonner.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/table.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md)
- How: Build the typed-name confirmation yourself in a `dialog` with an `input` that must match the asset name before the confirm `button` enables. `approval-card` shows the parameters in its `children` with Approve, Request changes and Reject (`approveLabel` is relabelable) for one decision; `sonner` for the result; `timeline` for who did what and when; `table` for the pending requests.
- Missing: `approval-card` is a single decision with no approver identity, time or reason field, so two-person sign-off (two cards or two statuses) and the recorded actor come from your code. Interlock rules and permissions come from your control system.

## Libraries and services that pair well

- Time-series charts for load, generation and meter data: Recharts, Apache ECharts, uPlot. time-series-chart handles gaps, forecast dashes, threshold bands and DST-correct zones for typical interval views; theme uPlot or ECharts with the color tokens only when you plot tens of thousands of interval reads.
- Maps of outages, substations, feeders and charge points: MapLibre GL JS, Mapbox GL JS, Leaflet. map-view is built on MapLibre GL JS with token-styled labelled markers, routes and areas, and a synced list. Use the library directly for heat maps or very large layers, and encode severity with shape and label as well as color.
- Live telemetry and charger status: MQTT over WebSockets, OCPP gateway (for example SteVe), Server-Sent Events. Stream into `table` and `stat` and keep the last-update time visible; show a stale state when the feed drops rather than the last value as if it were current.
- Time zones, daylight saving and interval math: Temporal API, date-fns-tz, Luxon. Do billing and interval aggregation in the meter's zone, and format with the zone abbreviation next to `font-mono` timestamps.
- Payments for charging sessions and bills: Stripe, Adyen. Build the payment form with `field` and `input` (opendraft's `checkout` is an event-ticket flow) and let the provider's hosted fields handle card data.
- Barcode and QR scanning for meters, chargers and assets: html5-qrcode, zxing-js, Barcode Detection API. opendraft's `qr-code` only draws codes; add a scanner component and show a manual-entry `field` as the fallback.

## Typical screens

- **Network operations overview**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md) + [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md) + [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md) + [Status Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/status-indicator.md) + [Map View](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/map-view.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md)
- **Outage detail**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md) + [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md) + [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md) + [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md)
- **Charge point network**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md) + [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md) + [Status Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/status-indicator.md) + [Map View](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/map-view.md) + [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md)
- **Work order and field checklist**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Record Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/record-page.md) + [Checklist](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checklist.md) + [Signature Pad](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/signature-pad.md) + [Photo Capture](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/photo-capture.md) + [Scheduler](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/scheduler.md) + [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md)
- **Customer usage and bill**: [Site Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/site-header.md) + [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md) + [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md) + [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md) + [Date Range Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-range-picker.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md) + [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md) + [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)

## Install the starter kit

One command installs the theme and the components this playbook uses:

```bash
npx shadcn@latest add @opendraft/kit-energy-utilities
```

## Known gaps

- Grid and asset status overview: `stat` has no threshold or limit marking (use `gauge` or `progress` beside it), and there is no single-line diagram or network topology view.
- Live and historical load, generation and consumption charts: One value axis (shared `unit`): no two-axis view and no stacked area for generation mix. Aggregation (15-min average, hourly sum) happens in your backend; the chart does not resample. For tens of thousands of points per series use uPlot or ECharts.
- Outage management and restoration tracking: `map-view` draws the shapes you pass; it does not compute affected areas, customer counts or crew routes, and it has no heat map layer. `stepper` only makes completed steps clickable.
- EV charging network and charge point status: `map-view` has no marker clustering for very large networks or live availability feed; stream status from your backend (OCPP gateway) and update the markers.
- Start and monitor a charging session (driver): No QR scanner (`qr-code` only renders codes, it cannot read them) and no payment-method selector built for tap-to-pay. `checkout` is an event-ticket flow and does not fit a session payment.
- Solar and battery site dashboard: No energy-flow diagram (solar to home to battery to grid). The chart has one value axis, so plot kW and state of charge in separate charts.
- Field service work orders and technician dispatch: `scheduler` marks time overlaps only; skills matching, travel time and routing come from your dispatch system. Offline sync of work orders is your app's job.
- Customer billing, usage and tariffs: `checkout` and `order-confirmation` are event-ticket shaped (attendee, front-desk delivery, ticket passes) and `settings-page` billing is a SaaS plan panel with a fixed Change plan button, so none fit a utility bill. Tariff calculation is your billing system's job.
- Demand response, switching and control actions: `approval-card` is a single decision with no approver identity, time or reason field, so two-person sign-off (two cards or two statuses) and the recorded actor come from your code. Interlock rules and permissions come from your control system.

Docs: https://ui-system-virid.vercel.app/docs/use-cases

---

# Building Government and civic services products with opendraft

> Public-sector portals for permits, licences, benefits, tax, records requests, case management and civic engagement. Used by everyone, including people in stress, on old phones and with assistive technology, so clarity and access come before polish.

Read this before building for this domain. Follow the rules in https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt as well. Names below link to each component's page (props, types, example).

## Use this playbook when the product involves

government, public sector, civic, citizen, permit, licence, benefits, welfare, tax, council, municipal, case management, foi, records request, immigration, public service.

## Principles for this domain

- Write in plain language: short sentences, common words, one idea per paragraph, the action in the button label (`Apply for a parking permit`, not `Submit`). Explain any term of art the first time it appears.
- Design to a high accessibility bar (aim for WCAG 2.2 AA or better; in many places public bodies are legally required to): visible focus, 4.5:1 text contrast, full keyboard use, errors announced and linked to their fields (`field` wires the ids and ARIA), no information by color alone, and a tested screen reader path for every form. opendraft's components do not make a page compliant by themselves, so test the finished screen.
- Long forms must be save-and-resume: ask one thing per step, show the steps with a `stepper`, let people leave and return with a reference number, never lose entered data on an error, and offer a final review page before submission. Neither `stepper` nor `field` stores anything, so draft saving is your backend's job.
- Be transparent about status: every application shows its reference number in `font-mono` with a `copy-button`, the current stage in words, what happens next, the expected time, and who to contact. Never leave a person guessing.
- Support many languages and reading directions from the start: text can grow 30 to 40 percent, names and addresses are not a US shape, dates and numbers follow the locale, and the language switcher is always visible and labeled in its own language.
- No dark patterns: no pre-ticked consent, no countdown pressure on benefits, equal prominence for decline and accept. Ask only for data you need and explain why. Assume a poor connection and an old device: keep pages light, show upload progress, retry safely, and always offer a phone, paper or in-person alternative.

## What the product needs, and what to use

Fit: **Ready** means use as is. **Adapt** means it works with the caveat given. **Gap** means nothing fits yet: build it from primitives and follow the principles above.

### Apply for a permit, licence or benefit (multi-step form)

- Fit: **Adapt**
- Use: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md), [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Step Navigation](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/step-nav.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Textarea](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/textarea.md), [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md), [Checkbox](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checkbox.md), [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md), [Date Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-picker.md), [Address Form](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/address-form.md), [Description List](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/description-list.md), [Repeater Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/repeater-field.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- How: `stepper` for stages (each step takes a `description`, and only completed steps are clickable) or `step-nav` when people may jump between sections and later ones stay locked until earlier ones are done. `field` for label, hint and linked error (`FieldSet` for a legend around radio groups), `address-form` for postal addresses with per-country rules, validation and correct autocomplete tokens, `repeater-field` for household members or prior addresses (`min`, `max`, `renderRow`, `createItem`). `date-picker` takes ISO dates with `min`, `max`, `locale` and `isDateDisabled`. Build the check-your-answers page from `description-list` grouped by step, with a change link per group.
- Missing: No built-in save-and-resume or draft persistence (store drafts server side) and no address lookup (`address-form` validates what is typed). There is no dedicated check-your-answers component; `description-list` is the building block.

### Upload supporting documents

- Fit: **Ready**
- Use: [Dropzone](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dropzone.md), [Photo Capture](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/photo-capture.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- How: `dropzone` validates `accept`, `maxSize` and `maxFiles`, reports `onReject` reasons (file-too-large, file-invalid-type, too-many-files), opens the phone camera with `capture="environment"`, and renders a file list from `files` with per-file `progress`, `error` and `onRemove`. `photo-capture` is the phone-first alternative for photographing a document (camera or file, `max`, optional captions). Show accepted types and size in a `field` hint, and a `badge` for Uploaded or Needs attention. Neither has upload logic: you run the upload and feed `progress` back. Always keep a plain file-input path working.

### Application status and history tracking

- Fit: **Ready**
- Use: [Record Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/record-page.md), [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Description List](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/description-list.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Copy Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/copy-button.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md)
- How: `stepper` (vertical, with `description` for the expected date) for the stage, `timeline` for dated events (received, in review, more information needed, decided; `timestamp`, `status`, `meta` for who), `description-list` for the application facts, `badge` with words for status, `copy-button` for the reference number, `alert` when action is needed from the applicant. The `record-page` block assembles header, status, summary, details and activity in one go. `detail-page` is an event-ticket purchase page, so do not use it.

### Sign in and verify identity

- Fit: **Adapt**
- Use: [Auth Screen](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/auth-screen.md), [MFA Step](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/mfa-step.md), [Secret Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/secret-input.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- How: `auth-screen` is email and password with sign-in and sign-up tabs, a remember checkbox, a forgot-password callback, optional `providers` buttons (use one per identity provider) and a brand panel. `mfa-step` for the second factor: `methods` (authenticator app, SMS, and a non-SMS route), async `onVerify`, `onResend` with a countdown, and error and `locked` states. `secret-input` for entering a reference or recovery code with reveal.
- Missing: No digital identity (eID, login.gov style) hand-off flow and no knowledge-based verification; wire your identity provider and show its error states in `alert`. Code verification and lockout come from your backend.

### Case management for caseworkers

- Fit: **Adapt**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Bulk Action Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/bulk-action-bar.md), [Stage Board](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stage-board.md), [Record Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/record-page.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md), [Checklist](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checklist.md), [Document Viewer](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/document-viewer.md), [Rich Text Editor](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/rich-text-editor.md), [Drawer](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/drawer.md)
- How: Case queue in `data-table` (`selectable` with `bulkActions` such as Assign; `filter-bar` chips for status, officer and priority; `views` for My cases and Unassigned) or as a `stage-board` (Received, In review, Decision, with drag or keyboard moves and WIP limits). The case file is the `record-page` block: header facts, status, activity `timeline` as the case history, related cases and `tabs` for documents and notes. `document-viewer` shows uploaded documents (you supply page rendering or `src`), `rich-text-editor` for case notes, and `checklist` for eligibility checks with a sign-off. Decisions go through `approval-card` (put a `textarea` for the reason in its `children`; it has Approve, Request changes and Reject but no reason field or decision log of its own). `drawer` for a quick preview.
- Missing: No SLA timers or automatic assignment; those and the decision log come from your case system. `detail-page` is an event-ticket page and does not fit.

### Book an appointment or inspection slot

- Fit: **Adapt**
- Use: [Date Time Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-time-picker.md), [Scheduler](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/scheduler.md), [Date Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-picker.md), [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Ticket Pass](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/ticket-pass.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- How: Citizen booking: `date-time-picker` in the office's named `timeZone` (it handles DST and can show the same moment in another zone), or `date-picker` (`min`, `max`, `isDateDisabled` for closed days) plus a `radio-group` of times with booked slots `disabled`. `ticket-pass` makes a confirmation pass with a QR `code`, fields and a status (valid, used, expired, void). Staff manage capacity in the `scheduler` block (`resources` are officers or inspection teams, conflict marking, drag or keyboard moves).
- Missing: No patient-facing availability grid showing open and booked slots (compose it with `radio-group`), and availability, reschedule and cancel rules come from your booking system. `order-confirmation` is ticket-shaped with a fixed three-step stepper.

### Pay a fee, fine or tax

- Fit: **Gap**
- Use: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Description List](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/description-list.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Address Form](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/address-form.md), [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md)
- How: Show amount, due date and what it is for in `stat` and a short `description-list` or line-item `data-table`. Build the payment form from `field`, `input`, `address-form` (billing address) and `radio-group` with the provider's hosted card fields, and a receipt from `stat`, a `stepper` marked `complete` and a `copy-button` reference.
- Missing: `checkout` is an event-ticket flow (quantity steppers, attendee, front-desk delivery, pay later, ticket passes) and `order-confirmation` renders ticket passes, so neither fits a fine or tax. Add instalment-plan and concession options yourself.

### Service notices, closures and emergency banners

- Fit: **Ready**
- Use: [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Site Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/site-header.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- How: `alert` with `banner` for a full-width, dismissible (`dismissible`, `onDismiss`) notice at the top for service disruption or deadlines, with an `AlertAction` button; keep the same severity words across services. `site-header` for the page frame.

### Find a service, office or document (search and directory)

- Fit: **Adapt**
- Use: [Search List](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/search-list.md), [Map View](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/map-view.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Accordion](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/accordion.md), [Empty State](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/empty-state.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md)
- How: `search-list` filters a plain list of strings with a live result list and an empty message; `accordion` for FAQs; `empty-state` (`live`) for no results with a next step. For offices and locations, `map-view` shows labelled markers with a synced list (opening hours and accessibility in your own list item via `renderListItem`) beside a `data-table` or list with `filter-bar` for service type. For results that need a description or link, filter your own data into a list.
- Missing: `search-list` takes strings only. `map-view` has no address search or directions: geocoding and routing come from your provider. `catalog` is event shaped (date, price, capacity, places left) and not a service directory. `command-palette` is a keyboard action menu over in-memory items.

### Civic data and public dashboards (budgets, performance, open data)

- Fit: **Adapt**
- Use: [Analytics Dashboard](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/analytics-dashboard.md), [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md), [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Date Range Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-range-picker.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Map View](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/map-view.md)
- How: `time-series-chart` plots spending or service volumes: several series, `thresholds` (a budget line or target band), a `unit` formatter, a named `timeZone`, brush zoom, keyboard stepping and a built-in data-table fallback. `analytics-dashboard` pairs a chart with a sortable table: rows are `name`, `visitors`, `conversion` (0 to 1) and `duration`, or a custom `valueColumn` for money; relabel with `labels` and the format props (its tabs are fixed 7d, 30d, 90d, relabel with `labels.ranges`). `gauge` for a single performance measure against a target with a text status, `map-view` for areas, and always keep the numbers in `data-table`.
- Missing: No bar or choropleth chart; `map-view` markers and areas are not a data-driven shading layer. `analytics-dashboard` has no fiscal-year ranges beyond 90 days, so prefer `time-series-chart` for annual data.

## Libraries and services that pair well

- Translations and locale-aware formatting: next-intl, react-i18next, FormatJS (react-intl). Keep all copy in message files, test with long German and Finnish strings, and set `dir` for right-to-left languages; check each opendraft component in RTL, since some spacing uses left and right classes.
- Digital identity and sign-in: OpenID Connect provider (Keycloak, Auth0), Login.gov, eIDAS-based national eID. Use auth-screen's `providers` buttons for the identity provider hand-off and its email form as the fallback path, `mfa-step` for second-factor codes, and show a clear error and recovery route when identity checks fail.
- Accessibility testing: axe-core, Pa11y, NVDA and VoiceOver manual checks. Automated tools catch only part of the problems; test each form with a keyboard and a screen reader, and test at 200 percent zoom.
- Address lookup and validation: Google Places, Loqate, National address register APIs. Offer manual entry with `address-form` as the fallback and never block submission when lookup fails; `address-form` validates postal codes per country but does not look addresses up.
- Document storage and e-signature: S3-compatible storage with virus scanning, DocuSign, Adobe Sign. Pair with `dropzone` or `photo-capture` for intake (neither has upload logic). `signature-pad` captures a drawn or typed signature and `document-viewer` shows a document you render; use the provider's embedded signing for legally binding signatures.
- Notifications by email, SMS and letter: GOV.UK Notify, Twilio, Postmark. Mirror each notification as a dated entry in `timeline` so a person can see what was sent without needing the message.

## Typical screens

- **Service start page**: [Site Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/site-header.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md) + [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Accordion](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/accordion.md) + [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- **Multi-step application**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md) + [Step Navigation](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/step-nav.md) + [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md) + [Address Form](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/address-form.md) + [Repeater Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/repeater-field.md) + [Dropzone](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dropzone.md) + [Photo Capture](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/photo-capture.md) + [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- **Check your answers and submit**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md) + [Description List](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/description-list.md) + [Checkbox](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checkbox.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md) + [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md)
- **Application status**: [Site Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/site-header.md) + [Record Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/record-page.md) + [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md) + [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md) + [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md) + [Copy Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/copy-button.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md)
- **Caseworker queue and case file**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md) + [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md) + [Stage Board](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stage-board.md) + [Record Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/record-page.md) + [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md) + [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md) + [Rich Text Editor](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/rich-text-editor.md)

## Install the starter kit

One command installs the theme and the components this playbook uses:

```bash
npx shadcn@latest add @opendraft/kit-government-civic
```

## Known gaps

- Apply for a permit, licence or benefit (multi-step form): No built-in save-and-resume or draft persistence (store drafts server side) and no address lookup (`address-form` validates what is typed). There is no dedicated check-your-answers component; `description-list` is the building block.
- Sign in and verify identity: No digital identity (eID, login.gov style) hand-off flow and no knowledge-based verification; wire your identity provider and show its error states in `alert`. Code verification and lockout come from your backend.
- Case management for caseworkers: No SLA timers or automatic assignment; those and the decision log come from your case system. `detail-page` is an event-ticket page and does not fit.
- Book an appointment or inspection slot: No patient-facing availability grid showing open and booked slots (compose it with `radio-group`), and availability, reschedule and cancel rules come from your booking system. `order-confirmation` is ticket-shaped with a fixed three-step stepper.
- Pay a fee, fine or tax: `checkout` is an event-ticket flow (quantity steppers, attendee, front-desk delivery, pay later, ticket passes) and `order-confirmation` renders ticket passes, so neither fits a fine or tax. Add instalment-plan and concession options yourself.
- Find a service, office or document (search and directory): `search-list` takes strings only. `map-view` has no address search or directions: geocoding and routing come from your provider. `catalog` is event shaped (date, price, capacity, places left) and not a service directory. `command-palette` is a keyboard action menu over in-memory items.
- Civic data and public dashboards (budgets, performance, open data): No bar or choropleth chart; `map-view` markers and areas are not a data-driven shading layer. `analytics-dashboard` has no fiscal-year ranges beyond 90 days, so prefer `time-series-chart` for annual data.

Docs: https://ui-system-virid.vercel.app/docs/use-cases

---

# Building Manufacturing and industrial operations products with opendraft

> Manufacturing execution (MES), shop-floor terminals, quality control, maintenance and industrial IoT dashboards. Used by operators on a feet-and-gloves schedule and by engineers and managers reviewing lines, lots and downtime.

Read this before building for this domain. Follow the rules in https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt as well. Names below link to each component's page (props, types, example).

## Use this playbook when the product involves

manufacturing, mes, shop floor, factory, production line, oee, downtime, quality control, inspection, cmms, maintenance, work order, andon, batch, traceability.

## Principles for this domain

- Make state glanceable from across the room. Line, machine and order status uses large type, a word (Running, Idle, Down, Changeover) plus an icon, and high contrast; a wall display needs no reading beyond the status and one number.
- Design for gloves and noise: touch targets of at least 56 px on shop-floor terminals, generous spacing, no hover-only or drag-only actions, and confirmations that do not rely on sound alone. opendraft's largest button (`size="xl"`) is 48 px tall and `checkbox`, `radio-group` and `switch` are 16 to 20 px, so enlarge them with classes or wrap each in a full-width 56 px row that carries the click.
- Every unit of product has traceability: lot, batch, serial, shift, operator and machine appear on the record, in `font-mono` with a `copy-button` and a scannable code, and corrections add a new entry rather than overwrite an old one.
- Rank alarms by priority, not arrival time: Critical (stop and act), Warning (act this shift), Info. Keep alarm text specific (what, where, what to do), require acknowledgement with a name and time, and avoid alarm floods by grouping repeats.
- Show shift and time context everywhere: the current shift, shift start, counts since shift start, and timestamps in the plant's local zone. Handovers between shifts need a visible notes and open-issues summary.
- Tolerate offline and flaky networks: queue entries locally, show an explicit Saved locally, Syncing and Synced state, never lose a count or a quality reading, and show how stale a displayed value is.

## What the product needs, and what to use

Fit: **Ready** means use as is. **Adapt** means it works with the caveat given. **Gap** means nothing fits yet: build it from primitives and follow the principles above.

### Line and machine status wall display (andon)

- Fit: **Adapt**
- Use: [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md), [Status Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/status-indicator.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Animated Number](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/animated-number.md), [ETA Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/eta-indicator.md)
- How: `stat` tiles for output, target and OEE (`value` takes any node, so wrap the number in a large span or `animated-number`; `delta` with `goodWhen` for against-target), a `status-indicator` per machine (relabel with `label`, `tone`, `shape` for Running, Idle, Down, Changeover), `gauge` for OEE or utilization against `thresholds` with a text status, `progress` (`size="lg"`) for output against target, `alert` for stoppages. `eta-indicator` can show the projected end time of the current order with a confidence word.
- Missing: No large-format kiosk or full-screen display mode and no auto-rotating screen layout; build it with a scaled container. `stat` renders its value at a fixed `text-3xl`, so check it reads from across the room and enlarge the node you pass as `value`.

### Production order execution on a terminal

- Fit: **Adapt**
- Use: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md), [Step Navigation](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/step-nav.md), [Checklist](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checklist.md), [Quantity Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/quantity-stepper.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Dialog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dialog.md)
- How: Work instructions as `checklist` (tickable items with notes, progress and a sign-off step) or as `step-nav` (steps complete, current, available or locked, so operators cannot skip ahead; `lockedReason` says why). `todo-list` is a read-only plan display with no tick action, and `detail-page` is an event-ticket page, so neither fits. `quantity-stepper` (`min`, `max`, `step`, hold-to-repeat) for good and scrap counts, `progress` for count against order quantity, `approval-card` or a `dialog` to confirm completion.
- Missing: Controls are desktop sized (`button` tops out at 48 px, `quantity-stepper` has only `sm` and default), so set larger sizes through classes and verify 56 px targets. No barcode scan input or numeric keypad (use an `input` with `inputMode="numeric"`).

### Quality inspection and checklists

- Fit: **Adapt**
- Use: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md), [Checklist](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checklist.md), [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Textarea](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/textarea.md), [Photo Capture](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/photo-capture.md), [Signature Pad](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/signature-pad.md), [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md), [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md)
- How: `checklist` for the inspection plan (tickable items, a note per item, progress, sign-off), a `radio-group` (Pass, Fail, N/A) inside a `field` where a step needs a verdict, a measured value in `input`, notes in `textarea`, defect photos with `photo-capture` (camera or file, captions), operator sign-off with `signature-pad` and `approval-card`, and past inspections in `data-table`. `time-series-chart` can draw an SPC run chart: a series of measurements with `thresholds` for the centre line and the upper and lower control limits (or a band with `to` for the tolerance zone). `todo-list` is a read-only plan and `records-table` a fixed contact-list grid, so neither fits.
- Missing: No dedicated X-bar or R control chart: `time-series-chart` draws the points and limit lines, but the control limits, run rules and Cpk are computed in your backend. No measurement-instrument input.

### Alarm and event management

- Fit: **Adapt**
- Use: [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Bulk Action Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/bulk-action-bar.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Toast](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/sonner.md)
- How: Alarm list in `data-table` sorted by priority with a text `badge`; `filters` (`filter-bar` chips for area, priority, state), `views` for Active and Acknowledged, `selectable` with `bulkActions` for bulk acknowledge (`selection-actions` is an AI text-rewrite bar, not a bulk bar); `timeline` for the event history; `alert` for the active critical banner. For a high-rate alarm stream use the virtualized `table` with `bulk-action-bar`.
- Missing: No alarm-shelving or suppression workflow and no audible alarm control; those are logic you build around the table.

### Downtime and OEE analysis

- Fit: **Adapt**
- Use: [Analytics Dashboard](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/analytics-dashboard.md), [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md), [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Date Range Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-range-picker.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md)
- How: OEE, availability, performance and quality in `gauge`, `stat` and `progress`. `time-series-chart` plots OEE or downtime per shift against a target `threshold` in the plant's `timeZone`, with several series, gaps for no-data periods and brush zoom. `analytics-dashboard` can be relabelled for machines: each row is `name` (machine), `visitors` (a count, such as stops), `conversion` (a 0 to 1 rate, such as availability) and `duration` (seconds, such as downtime), with `valueColumn` for one custom number; the share bar can show downtime reasons by percent. `date-range-picker` for custom periods.
- Missing: No Pareto chart (the share bar has no cumulative line) and no stacked shift-by-shift chart. `analytics-dashboard` range tabs are fixed to the keys 7d, 30d and 90d (relabel them with `labels.ranges` and supply your own data per key).

### Maintenance work orders and preventive schedules

- Fit: **Adapt**
- Use: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md), [Scheduler](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/scheduler.md), [Gantt](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gantt.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Record Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/record-page.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Checklist](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checklist.md), [Date Time Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-time-picker.md), [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md)
- How: Work orders in `data-table` (status `badge`, `views` for Open, Due, Done); the planned-maintenance calendar in the `scheduler` block (`resources` are machines or crews, `events` are jobs, conflict marking, drag or keyboard moves) and a shutdown plan in `gantt` (tasks, dependencies, groups, critical flags, today marker). The job page is the `record-page` block with a `checklist` for the procedure (sign-off), history in `timeline` and sign-off in `approval-card`. `date-time-picker` for the planned start in the plant's `timeZone`. `detail-page` is an event-ticket page and `todo-list` is read-only, so they do not fit.
- Missing: No recurrence rules and no meter-based trigger view (run hours, cycle counts): generate the occurrences and triggers in your CMMS and feed them in.

### Lot, batch and serial traceability

- Fit: **Adapt**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Description List](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/description-list.md), [Record Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/record-page.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Copy Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/copy-button.md), [QR Code](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/qr-code.md), [Command Palette](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/command-palette.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md)
- How: Search a lot with an `input` that queries your API (`command-palette` filters only an in-memory `items` list, with no query callback, so it suits a small set), show genealogy rows in `data-table`, the lot's facts in `description-list` (`mono`, `copyable` ID values) or the `record-page` block, record history in `timeline`, and a label preview with `qr-code`. `records-table` is a fixed contact-list grid and does not fit.
- Missing: No tree or graph view for forward and backward genealogy (`flowchart` is a two-card trigger and if-else canvas), and no barcode formats other than QR (Code 128, DataMatrix).

### Equipment and sensor live data

- Fit: **Adapt**
- Use: [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md), [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md), [Status Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/status-indicator.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Slider](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/slider.md), [Switch](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/switch.md), [Dialog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dialog.md)
- How: Current readings in `stat` and `data-table` with unit and last-update time; `gauge` (`variant` ring or arc, `thresholds` bands, a text status) for a reading against its limits. `time-series-chart` trends a sensor: several series, `thresholds` for alarm limits, gaps where the feed dropped, brush zoom and a data-table fallback. `slider` (`onValueCommit`) and `switch` can drive setpoints, behind a `dialog` confirmation.
- Missing: No P&ID or floor-plan view. `time-series-chart` redraws from the series you pass, so stream and window the data yourself. Writes to a PLC need your own interlocks and confirmation.

### Inventory, materials and shift handover

- Fit: **Adapt**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Stage Board](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stage-board.md), [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Quantity Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/quantity-stepper.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Rich Text Editor](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/rich-text-editor.md), [Textarea](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/textarea.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Empty State](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/empty-state.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Checklist](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checklist.md)
- How: Stock levels as `gauge` or `progress` with `invert` so low stock warns (the bar measures what remains), in `data-table` with a `filter-bar`; counts with `quantity-stepper`; material requests on a `stage-board` (Requested, Picking, Delivered; drag or keyboard moves); shift handover as `rich-text-editor` or `textarea` posted to a `timeline`, with a `checklist` of open issues to acknowledge.
- Missing: No barcode scan input. `stage-board` totals use the value you give it; stock accounting stays in your ERP.

## Libraries and services that pair well

- Machine and sensor data over industrial protocols: OPC UA, MQTT with Sparkplug B, Node-RED. Bridge to the browser through a gateway or WebSocket and show the timestamp from the source, not the browser's receive time, so stale data is obvious.
- Time-series storage and trend charts: InfluxDB or TimescaleDB with Grafana, Apache ECharts, uPlot. time-series-chart draws trends, threshold lines and bands with a data-table fallback. Grafana panels can still be embedded beside opendraft `stat` tiles for very high-rate historian data, and uPlot or ECharts suit millions of points.
- Barcode and QR scanning on the floor: Hardware scanners that act as keyboards, Zebra DataWedge, zxing-js. Most scanners type into a focused field; keep one large focused `input` ready and show the scanned value back clearly. `qr-code` only renders codes and `photo-capture` takes still photos, so scanning needs one of these.
- ERP, MES and quality system connections: SAP, Oracle NetSuite, ISA-95 based middleware. Keep the order, lot and BOM data read through your API and write corrections as new records, which matches the audit trail the UI shows.
- Offline-first data and sync on terminals: PowerSync, RxDB, Workbox with IndexedDB. Surface the Saved locally, Syncing and Synced state with a `badge` and use `sonner` only for failures that need action.
- Label and document printing: Zebra Browser Print, ZPL over a print server. Render the on-screen label with `qr-code` and `font-mono` text, then send the matching ZPL to the printer.

## Typical screens

- **Line status wall display**: [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md) + [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md) + [Status Indicator](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/status-indicator.md) + [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md)
- **Operator work order terminal**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Step Navigation](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/step-nav.md) + [Checklist](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checklist.md) + [Quantity Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/quantity-stepper.md) + [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md) + [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md)
- **Quality inspection**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Checklist](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checklist.md) + [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md) + [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md) + [Photo Capture](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/photo-capture.md) + [Signature Pad](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/signature-pad.md) + [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md) + [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md)
- **Alarm console**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md) + [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md) + [Bulk Action Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/bulk-action-bar.md) + [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md) + [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md)
- **Plant performance overview**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md) + [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md) + [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md) + [Analytics Dashboard](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/analytics-dashboard.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md) + [Date Range Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-range-picker.md)

## Install the starter kit

One command installs the theme and the components this playbook uses:

```bash
npx shadcn@latest add @opendraft/kit-manufacturing
```

## Known gaps

- Line and machine status wall display (andon): No large-format kiosk or full-screen display mode and no auto-rotating screen layout; build it with a scaled container. `stat` renders its value at a fixed `text-3xl`, so check it reads from across the room and enlarge the node you pass as `value`.
- Production order execution on a terminal: Controls are desktop sized (`button` tops out at 48 px, `quantity-stepper` has only `sm` and default), so set larger sizes through classes and verify 56 px targets. No barcode scan input or numeric keypad (use an `input` with `inputMode="numeric"`).
- Quality inspection and checklists: No dedicated X-bar or R control chart: `time-series-chart` draws the points and limit lines, but the control limits, run rules and Cpk are computed in your backend. No measurement-instrument input.
- Alarm and event management: No alarm-shelving or suppression workflow and no audible alarm control; those are logic you build around the table.
- Downtime and OEE analysis: No Pareto chart (the share bar has no cumulative line) and no stacked shift-by-shift chart. `analytics-dashboard` range tabs are fixed to the keys 7d, 30d and 90d (relabel them with `labels.ranges` and supply your own data per key).
- Maintenance work orders and preventive schedules: No recurrence rules and no meter-based trigger view (run hours, cycle counts): generate the occurrences and triggers in your CMMS and feed them in.
- Lot, batch and serial traceability: No tree or graph view for forward and backward genealogy (`flowchart` is a two-card trigger and if-else canvas), and no barcode formats other than QR (Code 128, DataMatrix).
- Equipment and sensor live data: No P&ID or floor-plan view. `time-series-chart` redraws from the series you pass, so stream and window the data yourself. Writes to a PLC need your own interlocks and confirmation.
- Inventory, materials and shift handover: No barcode scan input. `stage-board` totals use the value you give it; stock accounting stays in your ERP.

Docs: https://ui-system-virid.vercel.app/docs/use-cases

---

# Building HR and people operations products with opendraft

> HRIS, recruiting, onboarding, payroll, performance and time-off products used by employees, managers and HR teams. The data is personal and sensitive, so who can see what, and who changed what, is part of the design.

Read this before building for this domain. Follow the rules in https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt as well. Names below link to each component's page (props, types, example).

## Use this playbook when the product involves

human resources, hris, people ops, recruiting, applicant, candidate, onboarding, offboarding, payroll, payslip, performance review, time off, leave, timesheet, employee directory.

## Principles for this domain

- Make views permission-aware: show each person only the fields their role allows, and say so (`Visible to HR only`) rather than leaving a blank. Managers see their reports, employees see themselves, and a view-as preview helps admins check it.
- Mask sensitive data by default (salary, national ID, bank details, health and leave reasons, performance ratings) with an explicit reveal that is logged: `secret-input` gives a masked value with reveal, copy and optional auto-hide. Never put such values in URLs, toasts, page titles or exports without a clear warning.
- Approval flows show the whole chain: who requested, who must approve now, who is next, what was decided and when. Give every request a status word (Pending, Approved, Declined, Withdrawn) and always allow the requester to withdraw or edit before a decision.
- Use inclusive language and flexible data: do not require a binary gender field, allow preferred and legal names, support names that do not fit first and last, and keep pronouns optional. Dates, currencies and working weeks follow the person's country.
- Make changes auditable: every edit to pay, title, manager, status or personal data records who, when, old value and new value, visible in a history view. Keep effective dates separate from edit dates so retroactive changes are clear.
- Treat people-related decisions with care: show the reason and next step on rejections, avoid ranking people by a single score, label AI-generated summaries or suggestions as such, and keep a human decision-maker on hiring, pay and performance outcomes.

## What the product needs, and what to use

Fit: **Ready** means use as is. **Adapt** means it works with the caveat given. **Gap** means nothing fits yet: build it from primitives and follow the principles above.

### Employee directory and org chart

- Fit: **Adapt**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md), [Avatar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/avatar.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Command Palette](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/command-palette.md), [Drawer](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/drawer.md), [Record Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/record-page.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md)
- How: `data-table` block: a searchable table whose name cell renders an `avatar`, role and location, `filters` (`filter-bar` chips for department, location, status), sortable columns and a card layout on phones; a profile in a `drawer` (or its own page with the `record-page` block); jump-to-person with `command-palette` (`label`, `group`, `hint`, `badge` per item, filtered in memory, so it suits a few thousand people at most). `search-list` takes plain strings only, so it cannot show avatars or roles.
- Missing: No org chart tree or reporting-line visualization: show the manager and direct reports as links in the profile and use a graph or tree library for a full chart. `detail-page` is an event-ticket purchase page, not a person profile.

### Employee profile with sensitive fields

- Fit: **Adapt**
- Use: [Record Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/record-page.md), [Description List](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/description-list.md), [Secret Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/secret-input.md), [Permission Matrix](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/permission-matrix.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Copy Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/copy-button.md), [Dialog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dialog.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md)
- How: The `record-page` block is the profile shell (header, status, summary, details, activity `timeline`, related items, extra `tabs`). Show fields in `description-list` (`copyable`, `mono`) with a `badge` such as Visible to HR only; show sensitive values (bank details, national ID) in `secret-input` (masked, reveal, optional auto-hide, copy) and put a `dialog` in front of the reveal when it needs a reason. Edit details with `field` and `input`. `permission-matrix` can document which roles may see which fields.
- Missing: `secret-input` masks and reveals in the browser only: the logged reveal, the permission check and withholding the value until it is requested are your backend's. `settings-page` has fixed profile fields (name, email, bio, timezone) and a SaaS team and billing layout, and `detail-page` is an event-ticket page, so neither fits.

### Time-off requests and approvals

- Fit: **Adapt**
- Use: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md), [Date Range Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-range-picker.md), [Scheduler](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/scheduler.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md), [Textarea](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/textarea.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md)
- How: Request with `date-range-picker` (ISO `{from, to}` dates, `min`, `max`, `presets`), balance in `stat` and `progress` (`valueLabel` such as 12 of 25 days), decision with `approval-card` (Approve, Request changes, Reject; put a `textarea` for a decision note in its `children`), approval chain in `timeline` using `current` and `upcoming` statuses, requests in `data-table`. The team calendar is the `scheduler` block: `resources` are people, `events` are absences (a status word plus `tone`), week view and an agenda on narrow widths.
- Missing: No half-day support in `date-range-picker`. Do not mark public holidays or weekends with `isDateDisabled`: the range picker refuses any range that spans a disabled day, so people could not book leave across a holiday. Count working days in your own code and show the result next to the range.

### Recruiting pipeline and candidate review

- Fit: **Ready**
- Use: [Stage Board](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stage-board.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Record Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/record-page.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Avatar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/avatar.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Drawer](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/drawer.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Rating](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/rating.md), [Rich Text Editor](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/rich-text-editor.md), [Document Viewer](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/document-viewer.md), [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md), [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md)
- How: `stage-board` block is the hiring pipeline: `stages` (Applied, Screen, Interview, Offer), candidate cards via `renderCard` (`avatar`, role, `badge`), drag or keyboard moves with `onMove`, WIP limits, per-stage totals and a detail panel (`renderDetail`) for the candidate with `tabs`, `timeline` for activity and `approval-card` for an offer decision. A `data-table` with `filter-bar` is the list view of the same candidates. `rating` records a scorecard score (half steps, keyboard arrows) and `rich-text-editor` captures interview notes. `document-viewer` shows a resume you render (or an embeddable `src`). You decide which columns and fields exist, so blind early-stage review is easy.

### Job application form (candidate-facing)

- Fit: **Ready**
- Use: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md), [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md), [Textarea](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/textarea.md), [Select](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/select.md), [Dropzone](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dropzone.md), [Checkbox](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checkbox.md), [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md), [Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/button.md), [Alert](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/alert.md), [Copy Button](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/copy-button.md)
- How: Steps in `stepper`, fields in `field`, resume upload in `dropzone` (`accept`, `maxSize`, and you run the upload), optional diversity questions as `radio-group` options that include Prefer not to say, an unticked consent `checkbox`, and a confirmation built from `alert` (success), a `stepper` marked `complete` and a `copy-button` reference. `order-confirmation` is ticket-shaped and does not fit.

### Onboarding and offboarding checklists

- Fit: **Adapt**
- Use: [Checklist](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checklist.md), [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Accordion](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/accordion.md), [Dropzone](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dropzone.md), [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Date Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-picker.md), [Scheduler](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/scheduler.md)
- How: Tasks per owner (HR, IT, manager, employee) in `checklist` (tickable items, a note per item, progress and a sign-off step) with an owner `badge` and due date, grouped by phase in an `accordion` or `stepper`, documents with `dropzone`, sign-offs with `approval-card`, and completions posted to `timeline`. The first-week plan can be a `scheduler` with the new hire as a resource.
- Missing: You hold the checked state and ownership rules; `todo-list` is a read-only display of an agent's plan and `task-rows` plays a fixed failed, retry, done animation, so neither works as an interactive checklist.

### Payroll runs and payslips

- Fit: **Adapt**
- Use: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Date Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-picker.md), [Dialog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dialog.md), [Dropzone](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dropzone.md), [Document Viewer](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/document-viewer.md), [Secret Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/secret-input.md)
- How: Run stages in `stepper` (draft, review, approved, paid), differences against the last run in `data-table` with old and new values in custom `cell` renderers (struck-through old, new beside it), final approval via `approval-card`, a `dialog` before submitting, and `dropzone` for imports. Payslips open in `document-viewer` (page navigation, zoom, download; you supply the page rendering or `src`) and bank details show in `secret-input`. `diff-table` is a one-shot demo of an email-directory edit (rows of id, dept, email) and does not take payroll data.
- Missing: `document-viewer` is a shell, not a PDF engine. Calculation, tax and legal rules come from your payroll provider.

### Performance reviews and goals

- Fit: **Adapt**
- Use: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md), [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md), [Field](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/field.md), [Rich Text Editor](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/rich-text-editor.md), [Rating](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/rating.md), [Radio Group](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/radio-group.md), [Slider](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/slider.md), [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md)
- How: Review cycle in `stepper`, rating with `rating` (stars with text labels), `radio-group` or a `slider` with text `marks` for each level, long-form feedback in `rich-text-editor` (toolbar, link validation, character limit, read-only renderer), goals with `progress`, sections in `tabs`, manager sign-off via `approval-card`. `detail-page` is an event-ticket page and does not fit.
- Missing: No 9-box or calibration grid (a grid of `stage-board` columns is the nearest start). Keep a human decision-maker on outcomes.

### Audit history of changes

- Fit: **Ready**
- Use: [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md), [Date Time Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-time-picker.md), [Description List](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/description-list.md), [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md), [Date Range Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-range-picker.md), [Tabs](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/tabs.md), [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md), [Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/input.md)
- How: `timeline` for who changed what (`timestamp`, `meta` for the actor, expandable `children` for the old and new value), and a searchable log in `data-table` (sortable, `filters` for actor, field and date, `cell` renderers that show old and new values). `date-range-picker` or `date-time-picker` narrows the period; `description-list` shows one entry. `diff-table` and `filter-table` do not fit: one is a fixed demo shape and the other lists task rows.

### HR analytics (headcount, attrition, time to hire)

- Fit: **Adapt**
- Use: [Analytics Dashboard](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/analytics-dashboard.md), [Time Series Chart](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/time-series-chart.md), [Gauge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/gauge.md), [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md), [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md), [Date Range Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-range-picker.md)
- How: Relabel `analytics-dashboard` for headcount and attrition: metrics each carry a series per range, rows are `name` (department), `visitors` (a count such as headcount), `conversion` (a 0 to 1 rate such as retention) and `duration` (seconds, or use `valueColumn`), and the share bar suits composition. `time-series-chart` plots monthly headcount or time to hire with several series and a target `threshold`. Apply minimum group sizes in your data so small teams cannot be identified.
- Missing: No funnel or cohort chart. `analytics-dashboard` range tabs are fixed to the keys 7d, 30d and 90d (relabel with `labels.ranges` and supply your own data under each key).

## Libraries and services that pair well

- Payroll, benefits and tax calculation: Gusto, ADP, Deel. Let the provider own the calculation and show its output in `table` and `stat`; never recompute pay in the browser.
- Applicant tracking and job boards: Greenhouse, Lever, Ashby. Map their stages onto the `stages` of the `stage-board` and keep candidate notes in your own detail panel rather than copying them.
- Single sign-on, provisioning and directory sync: Okta, Microsoft Entra ID, SCIM. Use SCIM to create and remove accounts at hire and exit, and drive the onboarding checklist from the same events.
- E-signature for contracts and policies: DocuSign, Dropbox Sign, Adobe Sign. signature-pad captures a drawn or typed signature and document-viewer shows a document you render; embed the provider's signing view for legally binding contracts and record the result in `timeline`.
- Calendars, holidays and working-time rules: Nager.Date, Google Calendar API, Microsoft Graph. Compute working days and holidays in your own code and show them beside the `date-range-picker`; do not disable holiday dates in the picker, because it rejects ranges that span disabled days. Sync approved leave to the team calendar.
- Permissions and field-level access control: CASL, Oso, OpenFGA. Evaluate on the server and pass the allowed fields to the UI as props, so hidden data is never sent to the browser.

## Typical screens

- **Employee directory**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md) + [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md) + [Avatar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/avatar.md) + [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md) + [Command Palette](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/command-palette.md) + [Drawer](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/drawer.md)
- **Employee profile**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Record Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/record-page.md) + [Description List](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/description-list.md) + [Secret Input](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/secret-input.md) + [Badge](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/badge.md) + [Dialog](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dialog.md) + [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md)
- **Time off and approvals**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md) + [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md) + [Date Range Picker](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/date-range-picker.md) + [Scheduler](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/scheduler.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md) + [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md) + [Timeline](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/timeline.md)
- **Hiring pipeline**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Stage Board](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stage-board.md) + [Data Table](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/data-table.md) + [Filter Bar](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/filter-bar.md) + [Stat](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stat.md) + [Record Page](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/record-page.md) + [Rating](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/rating.md) + [Approval Card](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/approval-card.md)
- **New hire onboarding**: [Page Header](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/page-header.md) + [Checklist](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/checklist.md) + [Progress](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/progress.md) + [Accordion](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/accordion.md) + [Stepper](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/stepper.md) + [Dropzone](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/dropzone.md) + [Scheduler](https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms/scheduler.md)

## Install the starter kit

One command installs the theme and the components this playbook uses:

```bash
npx shadcn@latest add @opendraft/kit-hr-people
```

## Known gaps

- Employee directory and org chart: No org chart tree or reporting-line visualization: show the manager and direct reports as links in the profile and use a graph or tree library for a full chart. `detail-page` is an event-ticket purchase page, not a person profile.
- Employee profile with sensitive fields: `secret-input` masks and reveals in the browser only: the logged reveal, the permission check and withholding the value until it is requested are your backend's. `settings-page` has fixed profile fields (name, email, bio, timezone) and a SaaS team and billing layout, and `detail-page` is an event-ticket page, so neither fits.
- Time-off requests and approvals: No half-day support in `date-range-picker`. Do not mark public holidays or weekends with `isDateDisabled`: the range picker refuses any range that spans a disabled day, so people could not book leave across a holiday. Count working days in your own code and show the result next to the range.
- Onboarding and offboarding checklists: You hold the checked state and ownership rules; `todo-list` is a read-only display of an agent's plan and `task-rows` plays a fixed failed, retry, done animation, so neither works as an interactive checklist.
- Payroll runs and payslips: `document-viewer` is a shell, not a PDF engine. Calculation, tax and legal rules come from your payroll provider.
- Performance reviews and goals: No 9-box or calibration grid (a grid of `stage-board` columns is the nearest start). Keep a human decision-maker on outcomes.
- HR analytics (headcount, attrition, time to hire): No funnel or cohort chart. `analytics-dashboard` range tabs are fixed to the keys 7d, 30d and 90d (relabel with `labels.ranges` and supply your own data under each key).

Docs: https://ui-system-virid.vercel.app/docs/use-cases

---

# Data Table

Generic table for any domain: search, filters, view tabs, sorting, selection with bulk actions, paging and a card layout when narrow.

Category: Blocks

## Install

```bash
npx shadcn@latest add @opendraft/data-table
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { DataTable } from "@/components/blocks/data-table"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/checkbox`, `@opendraft/empty-state`, `@opendraft/input`, `@opendraft/tabs`, `@opendraft/filter-bar`, `@opendraft/bulk-action-bar`

## Props and types

```ts
export type DataTableColumn<T> = {
  /** Unique column key. Also the default field read from the row. */
  key: string
  header: React.ReactNode
  /** Plain-text header used for aria and the card view. Defaults to `header` when it is a string. */
  headerText?: string
  /** Custom cell render. Defaults to the stringified field. */
  cell?: (row: T) => React.ReactNode
  /** Value used for sorting and search. Defaults to row[key]. */
  accessor?: (row: T) => string | number | boolean | null | undefined
  sortable?: boolean
  align?: "left" | "center" | "right"
  /** Use the mono font (IDs, dates, amounts). */
  mono?: boolean
  /** CSS width for the table column, e.g. "8rem". */
  width?: string
  /** Hide this column in the card view. */
  hideInCard?: boolean
}

export type DataTableView<T> = {
  id: string
  label: string
  /** Rows kept by this view. Omit for an "all" view. */
  filter?: (row: T) => boolean
}

export type DataTableBulkAction<T> = Omit<BulkAction, "onSelect"> & {
  onSelect: (rows: T[]) => void
}

export type DataTableLabels = {
  search: string
  searchPlaceholder: string
  selectAll: string
  selectRow: (rowName: string) => string
  emptyTitle: string
  emptyDescription: string
  noResultsTitle: string
  noResultsDescription: string
  clearFilters: string
  previous: string
  next: string
  range: (from: number, to: number, total: number) => string
  page: (page: number, pages: number) => string
  views: string
  sortedAscending: string
  sortedDescending: string
}

export type DataTableSort = { key: string; direction: "asc" | "desc" }

export type DataTableProps<T> = {
  columns?: DataTableColumn<T>[]
  rows?: T[]
  getRowId?: (row: T) => string
  /** Plain-text name of a row, for checkbox labels. Defaults to the id. */
  getRowName?: (row: T) => string
  /** Show the search field. Default true. */
  searchable?: boolean
  /** Filter controls shown beside the search field. */
  filters?: FilterConfig[]
  /** Decide whether a row matches the filter values. Default compares row[key] to the value(s). */
  filterRow?: (row: T, values: FilterValues) => boolean
  /** Tabs above the table, each keeping a subset of rows. */
  views?: DataTableView<T>[]
  defaultView?: string
  /** Show a checkbox column and the bulk action bar. */
  selectable?: boolean
  bulkActions?: DataTableBulkAction<T>[]
  selectedIds?: string[]
  defaultSelectedIds?: string[]
  onSelectedIdsChange?: (ids: string[]) => void
  defaultSort?: DataTableSort
  /** Rows per page. Set to 0 to show every row. Default 8. */
  pageSize?: number
  /** Called when a row is clicked or activated with Enter. */
  onRowOpen?: (row: T) => void
  /** Replaces the empty state when there are no rows at all. */
  empty?: React.ReactNode
  labels?: Partial<DataTableLabels>
  className?: string
}

export type SampleRow = {
  id: string
  name: string
  owner: string
  email: string
  status: "Active" | "Pending" | "Archived"
  updated: string
  amount: number
}

function DataTable(props: DataTableProps<T>)
```

## Example

```tsx
"use client"

import { Archive, Download } from "lucide-react"

import { Badge } from "@/components/ui/badge"
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"
import { DataTable, type DataTableColumn } from "@/components/blocks/data-table"

type Shipment = {
  id: string
  origin: string
  destination: string
  mode: "Air" | "Sea" | "Road"
  status: "In transit" | "Delayed" | "Delivered"
  eta: string
  weightKg: number
}

type Employee = {
  id: string
  name: string
  team: string
  location: string
  status: "Active" | "On leave"
  start: string
  salary: number
}

const modes = ["Air", "Sea", "Road"] as const
const shipStatus = ["In transit", "Delayed", "Delivered"] as const
const cities = ["Rotterdam", "Singapore", "Chicago", "Lagos", "Santos"]

const shipments: Shipment[] = Array.from({ length: 18 }, (_, i) => ({
  id: `SHP-${4100 + i}`,
  origin: cities[i % 5],
  destination: cities[(i * 2 + 1) % 5],
  mode: modes[i % 3],
  status: shipStatus[(i * 2) % 3],
  eta: `2026-11-${String((i % 28) + 1).padStart(2, "0")}`,
  weightKg: 180 + ((i * 431) % 9000),
}))

const teams = ["Engineering", "Support", "Finance", "Design"]
const employees: Employee[] = Array.from({ length: 16 }, (_, i) => ({
  id: `EMP-${200 + i}`,
  name: `Employee ${i + 1}`,
  team: teams[i % 4],
  location: ["Remote", "Berlin", "Austin"][i % 3],
  status: i % 5 === 4 ? "On leave" : "Active",
  start: `202${(i % 5) + 1}-0${(i % 9) + 1}-15`,
  salary: 52000 + ((i * 7919) % 60000),
}))

const money = new Intl.NumberFormat("en", {
  style: "currency",
  currency: "EUR",
  maximumFractionDigits: 0,
})
const kg = new Intl.NumberFormat("en")

const shipmentColumns: DataTableColumn<Shipment>[] = [
  { key: "id", header: "Shipment", mono: true, sortable: true },
  { key: "origin", header: "Origin", sortable: true },
  { key: "destination", header: "Destination", sortable: true },
  { key: "mode", header: "Mode" },
  {
    key: "status",
    header: "Status",
    sortable: true,
    cell: (r) => (
      <Badge
        dot
        variant={
          r.status === "Delayed"
            ? "warning"
            : r.status === "Delivered"
              ? "success"
              : "secondary"
        }
      >
        {r.status}
      </Badge>
    ),
  },
  { key: "eta", header: "ETA", mono: true, sortable: true },
  {
    key: "weightKg",
    header: "Weight (kg)",
    mono: true,
    sortable: true,
    align: "right",
    cell: (r) => kg.format(r.weightKg),
  },
]

const employeeColumns: DataTableColumn<Employee>[] = [
  { key: "name", header: "Name", sortable: true },
  { key: "team", header: "Team", sortable: true },
  { key: "location", header: "Location" },
  {
    key: "status",
    header: "Status",
    cell: (r) => (
      <Badge dot variant={r.status === "Active" ? "success" : "outline"}>
        {r.status}
      </Badge>
    ),
  },
  { key: "start", header: "Start date", mono: true, sortable: true },
  {
    key: "salary",
    header: "Salary",
    mono: true,
    sortable: true,
    align: "right",
    cell: (r) => money.format(r.salary),
  },
]

const frame = "h-[680px] w-full overflow-hidden rounded-lg border bg-background"

export default function DataTableDemo() {
  return (
    <Tabs defaultValue="shipments" className="w-full">
      <TabsList>
        <TabsTrigger value="shipments">Shipments</TabsTrigger>
        <TabsTrigger value="employees">Employees</TabsTrigger>
      </TabsList>
      <TabsContent value="shipments">
        <div className={frame}>
          <DataTable<Shipment>
            columns={shipmentColumns}
            rows={shipments}
            getRowId={(r) => r.id}
            selectable
            pageSize={8}
            defaultSort={{ key: "eta", direction: "asc" }}
            labels={{
              searchPlaceholder: "Search shipments...",
              emptyTitle: "No shipments",
            }}
            filters={[
              {
                key: "mode",
                type: "multi-select",
                label: "Mode",
                options: modes.map((m) => ({ value: m, label: m })),
              },
            ]}
            views={[
              { id: "all", label: "All" },
              {
                id: "delayed",
                label: "Delayed",
                filter: (r) => r.status === "Delayed",
              },
              {
                id: "delivered",
                label: "Delivered",
                filter: (r) => r.status === "Delivered",
              },
            ]}
            bulkActions={[
              {
                id: "export",
                label: "Export",
                icon: <Download />,
                onSelect: () => {},
              },
            ]}
            onRowOpen={() => {}}
          />
        </div>
      </TabsContent>
      <TabsContent value="employees">
        <div className={frame}>
          <DataTable<Employee>
            columns={employeeColumns}
            rows={employees}
            getRowId={(r) => r.id}
            getRowName={(r) => r.name}
            selectable
            pageSize={6}
            labels={{
              searchPlaceholder: "Search people...",
              selectRow: (n) => `Select ${n}`,
              range: (f, t, total) => `Showing ${f} to ${t} of ${total} people`,
            }}
            filters={[
              {
                key: "team",
                type: "select",
                label: "Team",
                options: teams.map((t) => ({ value: t, label: t })),
              },
            ]}
            bulkActions={[
              {
                id: "archive",
                label: "Archive",
                icon: <Archive />,
                destructive: true,
                onSelect: () => {},
              },
            ]}
          />
        </div>
      </TabsContent>
    </Tabs>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/data-table. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Record Page

Generic record detail page: header, status, summary stats, details, activity timeline and related items.

Category: Blocks

## Install

```bash
npx shadcn@latest add @opendraft/record-page
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { RecordPage } from "@/components/blocks/record-page"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/page-header`, `@opendraft/stat`, `@opendraft/status-indicator`, `@opendraft/tabs`, `@opendraft/timeline`

## Props and types

```ts
export type RecordStatus = {
  label: string
  tone?: StatusTone
}

export type RecordSummaryItem = Pick<
  StatProps,
  "label" | "value" | "hint" | "delta" | "icon"
> & { id?: string }

export type RecordField = {
  id?: string
  label: React.ReactNode
  value: React.ReactNode
  /** Render the value in mono (IDs, dates, amounts). */
  mono?: boolean
  /** Span two columns when the grid has room. */
  wide?: boolean
}

export type RecordRelated = {
  id: string
  title: React.ReactNode
  /** Secondary line, e.g. type or reference. */
  meta?: React.ReactNode
  status?: RecordStatus
  href?: string
  onSelect?: () => void
}

export type RecordTab = {
  id: string
  label: React.ReactNode
  content: React.ReactNode
}

export type RecordPageLabels = {
  details: string
  activity: string
  related: string
  emptyValue: string
  noFields: string
  noActivity: string
  noRelated: string
  summary: string
  tabs: string
}

export type RecordPageProps = {
  title: React.ReactNode
  subtitle?: React.ReactNode
  /** Record identifier, shown in mono above the title. */
  id?: string
  status?: RecordStatus
  /** Buttons or menus for the header. */
  actions?: React.ReactNode
  /** Breadcrumb or back link above the header. */
  breadcrumb?: React.ReactNode
  summary?: RecordSummaryItem[]
  fields?: RecordField[]
  activity?: TimelineItemData[]
  related?: RecordRelated[]
  /** Replaces the default Details and Activity tabs. */
  tabs?: RecordTab[]
  /** Active tab (controlled). */
  tab?: string
  defaultTab?: string
  onTabChange?: (id: string) => void
  labels?: Partial<RecordPageLabels>
  className?: string
}
```

## Example

```tsx
import { Button } from "@/components/ui/button"
import { RecordPage } from "@/components/blocks/record-page"

const frame = "h-[680px] w-full overflow-hidden rounded-lg border bg-background"

function ShipmentView() {
  return (
    <RecordPage
      id="SHP-48213"
      title="Pallet order to Rotterdam"
      subtitle="Dock 4 to Port of Rotterdam, 12 pallets"
      status={{ label: "In transit", tone: "brand" }}
      actions={
        <>
          <Button variant="outline">Reassign</Button>
          <Button>Mark delivered</Button>
        </>
      }
      summary={[
        { label: "Weight", value: "4,120 kg" },
        { label: "ETA", value: "Oct 14", hint: "On schedule" },
        {
          label: "Distance",
          value: "1,240 km",
          delta: { value: "3%", direction: "down", goodWhen: "down" },
        },
      ]}
      fields={[
        { label: "Carrier", value: "Northline Freight" },
        { label: "Origin", value: "Dock 4, Antwerp" },
        { label: "Destination", value: "Port of Rotterdam" },
        { label: "Tracking", value: "TRK-90017732", mono: true },
        { label: "Picked up", value: "2026-10-09 07:40", mono: true },
        { label: "Customs note", value: "Cleared for export.", wide: true },
      ]}
      activity={[
        {
          time: "Oct 11, 06:10",
          timestamp: "2026-10-11T06:10:00Z",
          title: "Departed hub",
          meta: "Antwerp",
          status: "current",
        },
        {
          time: "Oct 10, 18:02",
          timestamp: "2026-10-10T18:02:00Z",
          title: "Customs cleared",
          status: "success",
        },
        {
          time: "Oct 9, 07:40",
          timestamp: "2026-10-09T07:40:00Z",
          title: "Picked up",
          status: "success",
        },
      ]}
      related={[
        {
          id: "i1",
          title: "Invoice 2291",
          meta: "INV-2291",
          status: { label: "Paid", tone: "success" },
          onSelect: () => {},
        },
        {
          id: "i2",
          title: "Return label",
          meta: "RTN-118",
          status: { label: "Pending", tone: "warning" },
          onSelect: () => {},
        },
      ]}
      labels={{ related: "Linked documents" }}
    />
  )
}

function EmployeeView() {
  return (
    <RecordPage
      id="EMP-0231"
      title="Jordan Lee"
      subtitle="Senior designer, Product team"
      status={{ label: "On leave", tone: "warning" }}
      actions={<Button variant="outline">Edit profile</Button>}
      summary={[
        { label: "Tenure", value: "4.2 y" },
        { label: "Leave left", value: "11 d" },
        { label: "Reviews", value: "8" },
        { label: "Direct reports", value: "2" },
      ]}
      fields={[
        { label: "Manager", value: "Priya Nair" },
        { label: "Location", value: "Lisbon" },
        { label: "Email", value: "jordan.lee@example.com", mono: true },
        { label: "Start date", value: "2022-07-18", mono: true },
        { label: "Cost centre", value: null },
        { label: "Equipment", value: "Laptop, monitor" },
      ]}
      activity={[
        {
          time: "Oct 1",
          timestamp: "2026-10-01T00:00:00Z",
          title: "Leave started",
          description: "Parental leave until Jan 12.",
          status: "warning",
        },
        {
          time: "Jul 15",
          timestamp: "2026-07-15T00:00:00Z",
          title: "Promotion approved",
          status: "success",
        },
      ]}
      related={[{ id: "p1", title: "Priya Nair", meta: "Manager", href: "#" }]}
      labels={{
        details: "Profile",
        related: "People",
        noActivity: "No history",
      }}
    />
  )
}

export default function RecordPageDemo() {
  return (
    <div className="flex w-full flex-col gap-8">
      <div className={frame}>
        <ShipmentView />
      </div>
      <div className={frame}>
        <EmployeeView />
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/record-page. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Stage Board

Generic kanban board with drag or keyboard moves, WIP limits, per-stage totals and a detail panel.

Category: Blocks

## Install

```bash
npx shadcn@latest add @opendraft/stage-board
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { StageBoard } from "@/components/blocks/stage-board"
```

## Dependencies

- npm: `lucide-react`, `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/badge`, `@opendraft/dropdown-menu`, `@opendraft/select`

## Props and types

```ts
export interface StageBoardStage {
  id: string
  label: string
  /** Work-in-progress limit. Counts above it show an over-limit state. */
  limit?: number
}

export interface StageBoardCardState {
  stage: StageBoardStage
  /** Zero-based position inside the stage. */
  index: number
  dragging: boolean
  /** The stage holds more items than its limit. */
  overLimit: boolean
}

export interface StageBoardDetailContext {
  stage: StageBoardStage
  stages: StageBoardStage[]
  close: () => void
  /** Move the open item to another stage (appended at the end). */
  moveTo: (stageId: string) => void
}

export interface StageBoardLabels {
  eyebrow: string
  title: string
  /** Summary under the title. Tokens: {count}. */
  summary: string
  /** Empty column text. */
  empty: string
  /** Empty column text while an item is being dragged over it. */
  emptyDrop: string
  /** Aggregate caption on each column, e.g. "Total". */
  total: string
  limit: string
  atLimit: string
  overLimit: string
  /** Tokens: {stage}, {limit}. */
  limitReached: string
  openDetails: string
  /** Menu button name. Tokens: {item}. */
  actionsFor: string
  moveTo: string
  stage: string
  close: string
  detail: string
  /** Keyboard hint read with every card. */
  keyboardHint: string
  /** Live announcement. Tokens: {item}, {stage}, {position}, {total}. */
  moved: string
  /** Column landmark name. Tokens: {stage}. */
  stageRegion: string
}

export interface StageBoardProps<T> {
  stages: StageBoardStage[]
  items: T[]
  getItemId: (item: T) => string
  /** Stage id the item belongs to. Items with an unknown stage are not shown. */
  getStage: (item: T) => string
  /** Card content. Avoid interactive elements inside; the card is one button. */
  renderCard?: (item: T, state: StageBoardCardState) => React.ReactNode
  /** Plain-text name for announcements and menus. Defaults to the id. */
  getItemLabel?: (item: T) => string
  /**
   * Called for every move (drag, menu, keyboard). `index` is the item's
   * position in the destination stage after the move. The board is
   * controlled: update `items` in response.
   */
  onMove?: (itemId: string, toStage: string, index: number) => void
  /** Numeric value per item, summed into a per-stage aggregate. */
  getValue?: (item: T) => number
  /** Format the aggregate. Defaults to a plain locale number. */
  formatValue?: (value: number) => string
  /** Refuse moves into a stage that is already at its limit. Default false. */
  enforceLimits?: boolean
  /** Side panel content for the opened item. Omit to disable the panel. */
  renderDetail?: (item: T, ctx: StageBoardDetailContext) => React.ReactNode
  onOpen?: (item: T) => void
  /** Buttons or filters shown at the right of the header. */
  actions?: React.ReactNode
  labels?: Partial<StageBoardLabels>
  className?: string
}

export interface StageBoardSampleItem {
  id: string
  title: string
  stage: string
  assignee: string
  amount: number
}

function StageBoard(props: StageBoardProps<T>)
```

## Example

```tsx
"use client"

import * as React from "react"

import {
  StageBoard,
  type StageBoardStage,
} from "@/components/blocks/stage-board"
import { Badge } from "@/components/ui/badge"

type Ticket = {
  id: string
  subject: string
  requester: string
  stage: string
  priority: "Low" | "High" | "Urgent"
}

type Candidate = {
  id: string
  name: string
  role: string
  stage: string
  offer: number
  email: string
}

const ticketStages: StageBoardStage[] = [
  { id: "new", label: "New" },
  { id: "working", label: "Working", limit: 2 },
  { id: "waiting", label: "Waiting on customer" },
  { id: "resolved", label: "Resolved" },
]

const tickets: Ticket[] = [
  {
    id: "T-1041",
    subject: "Cannot export report",
    requester: "Dana Whitfield",
    stage: "new",
    priority: "High",
  },
  {
    id: "T-1042",
    subject: "Invoice shows wrong address",
    requester: "Ravi Menon",
    stage: "new",
    priority: "Low",
  },
  {
    id: "T-1038",
    subject: "Login loop on mobile",
    requester: "Chloe Park",
    stage: "working",
    priority: "Urgent",
  },
  {
    id: "T-1036",
    subject: "Webhook retries failing",
    requester: "Marcus Bell",
    stage: "working",
    priority: "High",
  },
  {
    id: "T-1035",
    subject: "Slow dashboard load",
    requester: "Ines Duarte",
    stage: "working",
    priority: "High",
  },
  {
    id: "T-1030",
    subject: "Update billing contact",
    requester: "Noah Kim",
    stage: "resolved",
    priority: "Low",
  },
]

const hiringStages: StageBoardStage[] = [
  { id: "applied", label: "Applied" },
  { id: "screen", label: "Phone screen", limit: 4 },
  { id: "onsite", label: "Onsite", limit: 3 },
  { id: "offer", label: "Offer" },
]

const candidates: Candidate[] = [
  {
    id: "c1",
    name: "Priya Shah",
    role: "Product designer",
    stage: "applied",
    offer: 0,
    email: "priya@example.com",
  },
  {
    id: "c2",
    name: "Tomas Reyes",
    role: "Backend engineer",
    stage: "screen",
    offer: 0,
    email: "tomas@example.com",
  },
  {
    id: "c3",
    name: "Hana Ito",
    role: "Backend engineer",
    stage: "onsite",
    offer: 0,
    email: "hana@example.com",
  },
  {
    id: "c4",
    name: "Leo Grant",
    role: "Data analyst",
    stage: "offer",
    offer: 92000,
    email: "leo@example.com",
  },
]

const priorityVariant = {
  Low: "secondary",
  High: "warning",
  Urgent: "destructive",
} as const

export default function StageBoardDemo() {
  const [domain, setDomain] = React.useState<"support" | "hiring">("support")
  return (
    <div className="grid w-full gap-3">
      <div role="group" aria-label="Sample data" className="flex gap-2">
        {(["support", "hiring"] as const).map((d) => (
          <button
            key={d}
            type="button"
            aria-pressed={domain === d}
            onClick={() => setDomain(d)}
            className="rounded-sm border px-2.5 py-1 text-xs outline-none focus-visible:ring-[3px] focus-visible:ring-ring aria-pressed:bg-ink aria-pressed:text-ink-foreground"
          >
            {d === "support" ? "Support tickets" : "Hiring"}
          </button>
        ))}
      </div>
      <div className="h-[680px] w-full overflow-hidden rounded-lg border bg-background">
        {domain === "support" ? <SupportBoard /> : <HiringBoard />}
      </div>
    </div>
  )
}

function useBoard<T extends { id: string; stage: string }>(initial: T[]) {
  const [items, setItems] = React.useState(initial)
  function onMove(id: string, toStage: string, index: number) {
    setItems((all) => {
      const moving = all.find((i) => i.id === id)
      if (!moving) return all
      const rest = all.filter((i) => i.id !== id)
      const dest = rest.filter((i) => i.stage === toStage)
      const before = dest[index]
      const next = { ...moving, stage: toStage }
      if (!before) {
        const last = dest[dest.length - 1]
        const at = last ? rest.indexOf(last) + 1 : rest.length
        return [...rest.slice(0, at), next, ...rest.slice(at)]
      }
      const at = rest.indexOf(before)
      return [...rest.slice(0, at), next, ...rest.slice(at)]
    })
  }
  return { items, onMove }
}

function SupportBoard() {
  const { items, onMove } = useBoard(tickets)
  return (
    <StageBoard
      stages={ticketStages}
      items={items}
      getItemId={(t) => t.id}
      getStage={(t) => t.stage}
      getItemLabel={(t) => t.subject}
      onMove={onMove}
      labels={{
        eyebrow: "Support",
        title: "Tickets",
        summary: "{count} open or recent",
        empty: "No tickets",
        emptyDrop: "Drop ticket here",
      }}
      renderCard={(t) => (
        <>
          <span className="font-mono text-xs text-muted-foreground">
            {t.id}
          </span>
          <span className="text-sm leading-tight font-medium">{t.subject}</span>
          <span className="flex items-center justify-between gap-2">
            <span className="truncate text-xs text-muted-foreground">
              {t.requester}
            </span>
            <Badge variant={priorityVariant[t.priority]}>{t.priority}</Badge>
          </span>
        </>
      )}
      renderDetail={(t) => (
        <dl className="grid grid-cols-2 gap-4 text-sm">
          <div>
            <dt className="eyebrow text-muted-foreground">Ticket</dt>
            <dd className="font-mono">{t.id}</dd>
          </div>
          <div>
            <dt className="eyebrow text-muted-foreground">Priority</dt>
            <dd>{t.priority}</dd>
          </div>
          <div className="col-span-2">
            <dt className="eyebrow text-muted-foreground">Requester</dt>
            <dd>{t.requester}</dd>
          </div>
        </dl>
      )}
    />
  )
}

function HiringBoard() {
  const { items, onMove } = useBoard(candidates)
  const money = new Intl.NumberFormat("en-GB", {
    style: "currency",
    currency: "GBP",
    maximumFractionDigits: 0,
  })
  return (
    <StageBoard
      stages={hiringStages}
      items={items}
      getItemId={(c) => c.id}
      getStage={(c) => c.stage}
      getItemLabel={(c) => c.name}
      onMove={onMove}
      enforceLimits
      getValue={(c) => c.offer}
      formatValue={(v) => (v ? money.format(v) : "")}
      labels={{
        eyebrow: "Recruiting",
        title: "Candidates",
        summary: "{count} in process",
        empty: "No candidates",
        emptyDrop: "Drop candidate here",
        total: "Offers",
      }}
      renderCard={(c) => (
        <>
          <span className="text-sm leading-tight font-medium">{c.name}</span>
          <span className="text-xs text-muted-foreground">{c.role}</span>
        </>
      )}
      renderDetail={(c) => (
        <dl className="grid gap-4 text-sm">
          <div>
            <dt className="eyebrow text-muted-foreground">Role</dt>
            <dd>{c.role}</dd>
          </div>
          <div>
            <dt className="eyebrow text-muted-foreground">Email</dt>
            <dd className="font-mono">{c.email}</dd>
          </div>
        </dl>
      )}
    />
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/stage-board. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Scheduler

Resource scheduler for rosters, dispatch and appointments: day and week views, drag and keyboard moves, conflicts, agenda on narrow widths.

Category: Blocks

## Install

```bash
npx shadcn@latest add @opendraft/scheduler
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Scheduler } from "@/components/blocks/scheduler"
```

## Dependencies

- Registry (installed with it): `@opendraft/utils`, `@opendraft/badge`, `@opendraft/button`

## Props and types

```ts
export type SchedulerDate = string | Date

export type SchedulerView = "day" | "week"

export type SchedulerTone =
  "default" | "brand" | "success" | "warning" | "destructive"

/** A row: a crew member, room, vehicle, engineer, machine, on-call slot... */
export type SchedulerResource = {
  id: string
  label: string
  /** Second line under the label (role, capacity, plate number...). */
  meta?: string
}

export type SchedulerEvent = {
  id: string
  resourceId: string
  start: SchedulerDate
  end: SchedulerDate
  title: string
  /** Shown as text on the bar and in the agenda, never colour alone. */
  status?: string
  tone?: SchedulerTone
}

export type SchedulerMove = {
  resourceId: string
  start: Date
  end: Date
}

/**
 * Fixed copy. Every string can be replaced through the `labels` prop.
 * Placeholders in braces are filled in: {count} {title} {resource} {start} {end}.
 */
export type SchedulerLabels = {
  schedule: string
  resource: string
  previous: string
  next: string
  today: string
  view: string
  day: string
  week: string
  now: string
  conflict: string
  /** Uses {count}. */
  conflicts: string
  noResources: string
  noEvents: string
  /** Uses {resource}. */
  addEvent: string
  /** Read out for draggable events. */
  moveHint: string
  /** Uses {title} {resource} {start} {end}. */
  pickedUp: string
  /** Uses {title} {resource} {start} {end}. */
  moving: string
  /** Uses {title} {resource} {start} {end}. */
  dropped: string
  cancelled: string
}

export type SchedulerProps = {
  resources?: SchedulerResource[]
  events?: SchedulerEvent[]
  view?: SchedulerView
  defaultView?: SchedulerView
  onViewChange?: (view: SchedulerView) => void
  /** Any instant inside the visible day or week. */
  date?: SchedulerDate
  defaultDate?: SchedulerDate
  onDateChange?: (date: Date) => void
  /** IANA zone used for day boundaries and every formatted time. Default "UTC". */
  timeZone?: string
  /** BCP 47 locale for formatted dates and times. */
  locale?: string
  /** First visible hour of each day (0-23). Default 8. */
  startHour?: number
  /** Last visible hour of each day, exclusive (1-24). Default 18. */
  endHour?: number
  /** 0 = Sunday, 1 = Monday. Default 1. */
  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6
  /** Move and slot snapping in minutes. Default 15. */
  snapMinutes?: number
  /** Current time for the now-line and the Today button. Passed in, never read from the clock. */
  now?: SchedulerDate
  onEventClick?: (event: SchedulerEvent) => void
  onSlotClick?: (resourceId: string, start: Date) => void
  /** Enables drag and keyboard moves. Receives the new resource and times. */
  onEventMove?: (id: string, move: SchedulerMove) => void
  labels?: Partial<SchedulerLabels>
  className?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"

import {
  Scheduler,
  type SchedulerEvent,
  type SchedulerMove,
  type SchedulerResource,
  type SchedulerView,
} from "@/components/blocks/scheduler"
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"

type Domain = "roster" | "clinic"

const CREW: SchedulerResource[] = [
  { id: "c1", label: "Ana Torres", meta: "Crew lead" },
  { id: "c2", label: "Ben Okafor", meta: "Electrician" },
  { id: "c3", label: "Chen Wei", meta: "Electrician" },
  { id: "c4", label: "Dana Cole", meta: "Apprentice" },
  { id: "c5", label: "Eli Brandt", meta: "Driver" },
]

const SHIFTS: SchedulerEvent[] = [
  {
    id: "s1",
    resourceId: "c1",
    start: "2026-10-12T06:00:00Z",
    end: "2026-10-12T14:00:00Z",
    title: "Site A",
    status: "Confirmed",
    tone: "brand",
  },
  {
    id: "s2",
    resourceId: "c1",
    start: "2026-10-13T06:00:00Z",
    end: "2026-10-13T14:00:00Z",
    title: "Site A",
    status: "Confirmed",
    tone: "brand",
  },
  {
    id: "s3",
    resourceId: "c1",
    start: "2026-10-14T10:00:00Z",
    end: "2026-10-14T18:00:00Z",
    title: "Site B",
    status: "Pending",
    tone: "warning",
  },
  {
    id: "s4",
    resourceId: "c2",
    start: "2026-10-12T14:00:00Z",
    end: "2026-10-12T22:00:00Z",
    title: "Late shift",
    status: "Confirmed",
    tone: "brand",
  },
  {
    id: "s5",
    resourceId: "c2",
    start: "2026-10-13T14:00:00Z",
    end: "2026-10-13T22:00:00Z",
    title: "Late shift",
    status: "Confirmed",
    tone: "brand",
  },
  {
    id: "s6",
    resourceId: "c2",
    start: "2026-10-13T20:00:00Z",
    end: "2026-10-14T00:00:00Z",
    title: "Call-out",
    status: "On call",
    tone: "destructive",
  },
  {
    id: "s7",
    resourceId: "c3",
    start: "2026-10-12T06:00:00Z",
    end: "2026-10-12T14:00:00Z",
    title: "Site A",
    status: "Confirmed",
    tone: "brand",
  },
  {
    id: "s8",
    resourceId: "c3",
    start: "2026-10-15T06:00:00Z",
    end: "2026-10-15T14:00:00Z",
    title: "Site C",
    status: "Confirmed",
    tone: "success",
  },
  {
    id: "s9",
    resourceId: "c4",
    start: "2026-10-13T06:00:00Z",
    end: "2026-10-13T12:00:00Z",
    title: "Training",
    status: "Draft",
  },
  {
    id: "s10",
    resourceId: "c5",
    start: "2026-10-14T06:00:00Z",
    end: "2026-10-14T14:00:00Z",
    title: "Deliveries",
    status: "Confirmed",
    tone: "success",
  },
  {
    id: "s11",
    resourceId: "c5",
    start: "2026-10-16T06:00:00Z",
    end: "2026-10-16T14:00:00Z",
    title: "Deliveries",
    status: "Pending",
    tone: "warning",
  },
]

const ROOMS: SchedulerResource[] = [
  { id: "m1", label: "Room 1", meta: "Consultation" },
  { id: "m2", label: "Room 2", meta: "Consultation" },
  { id: "m3", label: "Room 3", meta: "Procedure" },
  { id: "m4", label: "Dr. Rivera", meta: "Practitioner" },
]

// Times are New York wall-clock (UTC-4 in October).
const APPOINTMENTS: SchedulerEvent[] = [
  {
    id: "a1",
    resourceId: "m1",
    start: "2026-10-13T09:00:00-04:00",
    end: "2026-10-13T09:30:00-04:00",
    title: "Check-up",
    status: "Arrived",
    tone: "success",
  },
  {
    id: "a2",
    resourceId: "m1",
    start: "2026-10-13T10:00:00-04:00",
    end: "2026-10-13T11:00:00-04:00",
    title: "Follow-up",
    status: "Booked",
    tone: "brand",
  },
  {
    id: "a3",
    resourceId: "m2",
    start: "2026-10-13T09:30:00-04:00",
    end: "2026-10-13T10:30:00-04:00",
    title: "New patient",
    status: "Booked",
    tone: "brand",
  },
  {
    id: "a4",
    resourceId: "m3",
    start: "2026-10-13T13:00:00-04:00",
    end: "2026-10-13T15:00:00-04:00",
    title: "Minor procedure",
    status: "Confirmed",
    tone: "warning",
  },
  {
    id: "a5",
    resourceId: "m4",
    start: "2026-10-13T09:00:00-04:00",
    end: "2026-10-13T10:15:00-04:00",
    title: "Rounds",
    status: "Booked",
  },
  {
    id: "a6",
    resourceId: "m4",
    start: "2026-10-13T10:00:00-04:00",
    end: "2026-10-13T11:00:00-04:00",
    title: "Consult",
    status: "Booked",
    tone: "brand",
  },
  {
    id: "a7",
    resourceId: "m2",
    start: "2026-10-13T14:00:00-04:00",
    end: "2026-10-13T14:45:00-04:00",
    title: "Review",
    status: "Booked",
    tone: "brand",
  },
]

export default function SchedulerDemo() {
  const [domain, setDomain] = React.useState<Domain>("roster")
  const [view, setView] = React.useState<SchedulerView>("week")
  const [shifts, setShifts] = React.useState(SHIFTS)
  const [appointments, setAppointments] = React.useState(APPOINTMENTS)
  const [picked, setPicked] = React.useState("")

  const apply =
    (set: React.Dispatch<React.SetStateAction<SchedulerEvent[]>>) =>
    (id: string, move: SchedulerMove) =>
      set((list) => list.map((e) => (e.id === id ? { ...e, ...move } : e)))

  return (
    <div className="flex w-full min-w-0 flex-col gap-3">
      <div className="flex flex-wrap items-center gap-3">
        <Tabs value={domain} onValueChange={(v) => setDomain(v as Domain)}>
          <TabsList>
            <TabsTrigger value="roster">Crew roster</TabsTrigger>
            <TabsTrigger value="clinic">Clinic appointments</TabsTrigger>
          </TabsList>
        </Tabs>
        <p
          className="font-mono text-xs text-muted-foreground"
          aria-live="polite"
        >
          {picked}
        </p>
      </div>
      <div className="h-[680px] w-full overflow-hidden rounded-lg border bg-background">
        {domain === "roster" ? (
          <Scheduler
            key="roster"
            resources={CREW}
            events={shifts}
            view={view}
            onViewChange={setView}
            defaultDate="2026-10-13T12:00:00Z"
            now="2026-10-13T10:20:00Z"
            timeZone="UTC"
            startHour={6}
            endHour={24}
            onEventMove={apply(setShifts)}
            onEventClick={(e) => setPicked(`${e.title} (${e.status})`)}
            onSlotClick={(resourceId, start) =>
              setPicked(`New shift: ${resourceId} at ${start.toISOString()}`)
            }
            labels={{
              resource: "Crew",
              conflict: "Double-booked",
              noEvents: "No shifts",
            }}
          />
        ) : (
          <Scheduler
            key="clinic"
            resources={ROOMS}
            events={appointments}
            defaultView="day"
            defaultDate="2026-10-13T12:00:00-04:00"
            now="2026-10-13T10:20:00-04:00"
            timeZone="America/New_York"
            startHour={8}
            endHour={17}
            snapMinutes={15}
            onEventMove={apply(setAppointments)}
            onEventClick={(e) => setPicked(`${e.title} (${e.status})`)}
            onSlotClick={(resourceId, start) =>
              setPicked(
                `New appointment: ${resourceId} at ${start.toISOString()}`
              )
            }
            labels={{
              resource: "Room / practitioner",
              conflict: "Overlap",
              noEvents: "No appointments",
            }}
          />
        )}
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/scheduler. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# CRM Pipeline

Sales pipeline with a stage board, sortable list view, search, drag or menu moves, and a deal detail panel with an activity timeline. Data shape: A sales board: company, USD value and 'deal' wording are fixed and there is no `labels` prop. Not a general stage board.

Category: Blocks

## Install

```bash
npx shadcn@latest add @opendraft/crm-pipeline
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { CrmPipeline } from "@/components/blocks/crm-pipeline"
```

## Dependencies

- npm: `lucide-react`, `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/badge`, `@opendraft/avatar`, `@opendraft/input`, `@opendraft/label`, `@opendraft/select`, `@opendraft/dialog`, `@opendraft/dropdown-menu`, `@opendraft/tabs`, `@opendraft/animated-number`

## Props and types

```ts
export interface CrmStage {
  id: string
  label: string
}

export interface CrmActivity {
  id: string
  /** What happened, e.g. "Sent revised proposal". */
  text: string
  /** Display label, e.g. "2 days ago". */
  when: string
  kind?: "note" | "email" | "call" | "stage"
}

export interface CrmDeal {
  id: string
  company: string
  contact: string
  email?: string
  phone?: string
  /** Deal value in whole currency units. */
  value: number
  stage: string
  owner: string
  /** ISO date (YYYY-MM-DD) for the expected close. */
  due: string
  /** Display label, e.g. "3 days ago". */
  lastTouched: string
  tags?: string[]
  activity?: CrmActivity[]
}

export interface CrmPipelineProps {
  stages?: CrmStage[]
  deals?: CrmDeal[]
  /** Called after a deal is moved to another stage. */
  onMove?: (dealId: string, toStage: string, deal: CrmDeal) => void
  /** Called with the deal created from the Add deal form. */
  onAdd?: (deal: CrmDeal) => void
  /** Called when a deal is opened in the detail panel. */
  onSelect?: (deal: CrmDeal) => void
  className?: string
}
```

## Example

```tsx
"use client"

import { CrmPipeline } from "@/components/blocks/crm-pipeline"

export default function CrmPipelineDemo() {
  return (
    <div className="h-[680px] w-full overflow-hidden rounded-lg border bg-background">
      <CrmPipeline />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/crm-pipeline. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Analytics Dashboard

Analytics screen with range tabs, KPI cards, a metric chart, a sortable top-pages table and a channel breakdown. Data shape: Web-analytics shaped: ranges are fixed 7d, 30d and 90d and table columns are name, visitors, conversion and duration (relabel with `labels`, `valueColumn` and the format props).

Category: Blocks

## Install

```bash
npx shadcn@latest add @opendraft/analytics-dashboard
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { AnalyticsDashboard } from "@/components/blocks/analytics-dashboard"
```

## Dependencies

- npm: `lucide-react`, `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/insight-cards`, `@opendraft/animated-number`, `@opendraft/badge`, `@opendraft/button`, `@opendraft/tabs`

## Props and types

```ts
export type AnalyticsRange = "7d" | "30d" | "90d"

export type AnalyticsMetric = {
  id: string
  label: string
  value: number
  /** Percent change versus the previous period, e.g. 12.4 or -3.1. */
  delta: number
  /** Intl.NumberFormat options for the value. */
  format?: Intl.NumberFormatOptions
  tone?: InsightTone
}

export type AnalyticsRow = {
  id: string
  /** Page path or traffic source. */
  name: string
  visitors: number
  /** 0-1 */
  conversion: number
  /** Seconds. */
  duration: number
  /** Custom number for the optional `valueColumn` (revenue, orders, ...). Used for sorting and as the default display. */
  value?: number
}

export type AnalyticsChannel = {
  id: string
  label: string
  /** Share of traffic, 0-100. */
  share: number
  tone: InsightTone
}

export type AnalyticsRangeData = {
  metrics: AnalyticsMetric[]
  /** Axis labels, one per point. */
  labels: string[]
  /** Chart values per metric id, one per label. */
  series: Record<string, number[]>
  rows: AnalyticsRow[]
  channels: AnalyticsChannel[]
}

/** Every fixed piece of text, so the screen can describe any product. */
export type AnalyticsLabels = {
  /** Small line above the title. A string is static; a function receives the selected range. */
  eyebrow: string | ((range: AnalyticsRange) => string)
  export: string
  channels: string
  channelsAria: string
  /** Heading and accessible name of the table. */
  table: string
  /** aria-label of the KPI section. */
  keyMetrics: string
  /** aria-label of the chart section. */
  trend: string
  /** aria-label of the range tabs. */
  dateRange: string
  /** aria-label of the chart metric tabs. */
  chartMetric: string
  /** Chart heading for the selected metric label. */
  overTime: (metricLabel: string) => string
  /** Range tab text: `short` below the container breakpoint, `long` above it. */
  ranges: Record<AnalyticsRange, { short: string; long: string }>
  /** Table column headings. The row fields stay name / visitors / conversion / duration. */
  columns: {
    name: string
    visitors: string
    conversion: string
    duration: string
  }
}

export type AnalyticsDashboardProps = {
  data?: Record<AnalyticsRange, AnalyticsRangeData>
  /** Controlled range. Uncontrolled when omitted. */
  range?: AnalyticsRange
  defaultRange?: AnalyticsRange
  onRangeChange?: (range: AnalyticsRange) => void
  onExport?: (range: AnalyticsRange) => void
  title?: string
  /** Override any fixed text, for example to relabel the table for events. */
  labels?: Partial<Omit<AnalyticsLabels, "columns" | "ranges">> & {
    columns?: Partial<AnalyticsLabels["columns"]>
    ranges?: Partial<
      Record<AnalyticsRange, Partial<{ short: string; long: string }>>
    >
  }
  /** Fill the parent's height and scroll inside (default). Set false to size to content inside a scrolling page. */
  fill?: boolean
  /** Format the visitors column. Default: en-US grouped integer. */
  formatVisitors?: (value: number, row: AnalyticsRow) => string
  /** Format the conversion column. `value` is the raw 0-1 field. Default: percent with one decimal. */
  formatConversion?: (value: number, row: AnalyticsRow) => string
  /** Format the duration column (seconds). Default: m:ss. */
  formatDuration?: (seconds: number, row: AnalyticsRow) => string
  /** Replaces the "Avg. time" column with a custom one (money, orders, ...). Reads `row.value` unless `format` is given. */
  valueColumn?: { label: string; format?: (row: AnalyticsRow) => string }
  className?: string
}
```

## Example

```tsx
"use client"

import { AnalyticsDashboard } from "@/components/blocks/analytics-dashboard"

export default function AnalyticsDashboardDemo() {
  return (
    <div className="h-[680px] w-full overflow-hidden rounded-lg border bg-background">
      <AnalyticsDashboard />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/analytics-dashboard. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Settings Page

Settings with profile, notifications, team and billing sections, an unsaved-changes bar and a type-to-confirm danger zone. Data shape: SaaS-shaped sections (profile, notifications, team, billing); the billing Change plan button needs your handler.

Category: Blocks

## Install

```bash
npx shadcn@latest add @opendraft/settings-page
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { SettingsPage } from "@/components/blocks/settings-page"
```

## Dependencies

- npm: `lucide-react`, `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/avatar`, `@opendraft/badge`, `@opendraft/button`, `@opendraft/dialog`, `@opendraft/input`, `@opendraft/label`, `@opendraft/select`, `@opendraft/switch`, `@opendraft/textarea`

## Props and types

```ts
export type SettingsSection = "profile" | "notifications" | "team" | "billing"

export type ProfileValues = {
  name: string
  email: string
  bio: string
  timezone: string
  avatarUrl?: string
}

export type NotificationItem = {
  id: string
  label: string
  description: string
  enabled: boolean
}

export type NotificationGroup = {
  id: string
  title: string
  description?: string
  items: NotificationItem[]
}

export type TeamRole = "owner" | "admin" | "member" | "viewer"

export type TeamMember = {
  id: string
  name: string
  email: string
  role: TeamRole
  status?: "active" | "pending"
}

export type UsageMeter = {
  id: string
  label: string
  used: number
  limit: number
  unit?: string
}

export type Invoice = {
  id: string
  date: string
  amount: string
  status: "paid" | "open" | "failed"
}

export type BillingValues = {
  plan: string
  price: string
  interval: string
  renewsOn: string
  features: string[]
  usage: UsageMeter[]
  invoices: Invoice[]
}

export type SettingsSaveValues = {
  profile: ProfileValues
  notifications: Record<string, boolean>
  members: TeamMember[]
}

export type SettingsPageProps = {
  profile?: ProfileValues
  notifications?: NotificationGroup[]
  members?: TeamMember[]
  billing?: BillingValues
  workspaceName?: string
  /** Which sections render, in order. Default: all four. */
  sections?: SettingsSection[]
  /** Show the danger zone (profile) and the delete dialog. Default true. */
  showDangerZone?: boolean
  /** Danger zone copy. `description` replaces the default sentence; `action` is the button label. */
  dangerLabels?: {
    title?: string
    description?: string
    action?: string
    dialogTitle?: string
  }
  timezones?: { value: string; label: string }[]
  onSave?: (values: SettingsSaveValues) => void | Promise<void>
  onInvite?: (invite: { email: string; role: TeamRole }) => void
  onDelete?: () => void
  onDownloadInvoice?: (invoice: Invoice) => void
  className?: string
}
```

## Example

```tsx
"use client"

import { SettingsPage } from "@/components/blocks/settings-page"

export default function SettingsPageDemo() {
  return (
    <div className="h-[680px] w-full overflow-hidden rounded-lg border bg-background">
      <SettingsPage />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/settings-page. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Auth Screen

Split sign-in and sign-up screen with validation, social providers, loading and error states, and a brand panel.

Category: Blocks

## Install

```bash
npx shadcn@latest add @opendraft/auth-screen
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { AuthScreen } from "@/components/blocks/auth-screen"
```

## Dependencies

- npm: `lucide-react`, `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/input`, `@opendraft/label`, `@opendraft/checkbox`, `@opendraft/tabs`, `@opendraft/pixel-field`

## Props and types

```ts
export type AuthMode = "sign-in" | "sign-up"

export type AuthValues = {
  mode: AuthMode
  email: string
  password: string
  remember: boolean
}

export type AuthProvider = {
  id: string
  label: string
  icon?: React.ReactNode
}

export type AuthBrand = {
  name: string
  quote: string
  author: string
  role?: string
}

export type AuthScreenProps = {
  /** Async. Throw (or reject) to show the error message above the button. */
  onSubmit?: (values: AuthValues) => void | Promise<void>
  /** Called when a "Continue with" button is pressed. */
  onProvider?: (providerId: string) => void
  onForgotPassword?: () => void
  providers?: AuthProvider[]
  brand?: AuthBrand
  defaultMode?: AuthMode
  /** Replaces the default monogram mark. */
  logo?: React.ReactNode
  /** Show `brand.name` next to the logo. Set false when `logo` already contains the name. Default true. */
  showBrandName?: boolean
  /** Text before the provider label on each button. Default "Continue with". */
  providerPrefix?: string
  /** Full control of the provider button text (overrides `providerPrefix`), e.g. to shorten long labels. */
  providerLabel?: (provider: AuthProvider) => string
  className?: string
  /** Extra classes for inner parts. `providers` targets the provider button grid. */
  classNames?: { providers?: string }
}
```

## Example

```tsx
import { AuthScreen } from "@/components/blocks/auth-screen"

export default function AuthScreenDemo() {
  return (
    <div className="h-[680px] w-full overflow-hidden rounded-lg border bg-background">
      <AuthScreen
        onSubmit={async ({ password }) => {
          await new Promise((r) => setTimeout(r, 1200))
          if (password === "password1")
            throw new Error("Incorrect email or password.")
        }}
      />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/auth-screen. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Agent Workspace

AI agent chat workspace: conversation rail, thread with thinking, tool calls and streamed answers, prompt bar and a live task panel.

Category: Blocks

## Install

```bash
npx shadcn@latest add @opendraft/agent-workspace
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { AgentWorkspace } from "@/components/blocks/agent-workspace"
```

## Dependencies

- npm: `lucide-react`, `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/sidebar-nav`, `@opendraft/prompt-bar`, `@opendraft/thinking-trace`, `@opendraft/tool-chips`, `@opendraft/streaming-answer`, `@opendraft/todo-list`, `@opendraft/shimmer-text`

## Props and types

```ts
export type AgentConversation = SidebarRecent

export type AgentUserMessage = {
  id: string
  role: "user"
  text: string
}

export type AgentReply = {
  /** Trace rows shown while the agent thinks. */
  thinking?: ThinkingTraceRow[]
  /** Tool calls run after thinking. */
  tools?: {
    steps: ToolStep[]
    diffs?: ToolDiff[]
    diffLines?: Record<string, ToolDiffLine[]>
    labels?: Partial<ToolChipsLabels>
  }
  /** The streamed answer. */
  answer: StreamingToken[]
  sources?: StreamingSource[]
  followUps?: string[]
}

export type AgentAssistantMessage = AgentReply & {
  id: string
  role: "assistant"
  /** Play thinking and tools before the answer. Defaults to false for history. */
  live?: boolean
}

export type AgentMessage = AgentUserMessage | AgentAssistantMessage

export type AgentWorkspaceProps = {
  conversations?: AgentConversation[]
  messages?: AgentMessage[]
  tasks?: TodoItem[]
  /**
   * Supply the reply for a prompt. When omitted the workspace simulates one;
   * when it returns nothing no reply is added.
   */
  onSend?: (text: string) => AgentReply | void | Promise<AgentReply | void>
  /** Title shown above the thread. */
  title?: string
  placeholder?: string
  /** Workspace shown at the top of the history rail. */
  workspace?: SidebarWorkspace
  className?: string
}
```

## Example

```tsx
import { AgentWorkspace } from "@/components/blocks/agent-workspace"

export default function AgentWorkspaceDemo() {
  return (
    <div className="h-[680px] w-full overflow-hidden rounded-lg border bg-background">
      <AgentWorkspace />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/agent-workspace. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Checkout

Three-step checkout (details, payment, confirmation) with validation, a sticky order summary with quantity steppers and discount codes, and ticket-pass confirmation. Card details stay in the form; only the last four digits reach your code. Data shape: Booking-shaped: contact, attendee, digital or front-desk delivery, card or pay later, ticket confirmation. No shipping address.

Category: Blocks

## Install

```bash
npx shadcn@latest add @opendraft/checkout
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Checkout } from "@/components/blocks/checkout"
```

## Dependencies

- npm: `lucide-react`, `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/badge`, `@opendraft/button`, `@opendraft/checkbox`, `@opendraft/empty-state`, `@opendraft/input`, `@opendraft/label`, `@opendraft/quantity-stepper`, `@opendraft/radio-group`, `@opendraft/stepper`, `@opendraft/ticket-pass`

## Props and types

```ts
export type CheckoutItem = {
  id: string
  title: string
  subtitle?: string
  /** Unit price in major currency units. */
  price: number
  quantity: number
  max?: number
  /** Optional image url. Falls back to an icon tile. */
  image?: string
}

export type CheckoutFee = {
  id: string
  label: string
  amount: number
}

export type CheckoutDelivery = "email" | "desk"

export type CheckoutPaymentMethod = "card" | "later"

export type CheckoutSummary = {
  items: CheckoutItem[]
  subtotal: number
  discount: number
  discountCode: string | null
  fees: CheckoutFee[]
  total: number
  currency: string
}

export type CheckoutValues = {
  contact: { name: string; email: string; phone: string }
  attendee: { someoneElse: boolean; name: string; email: string }
  delivery: CheckoutDelivery
  /**
   * Masked on purpose: the full card number and CVC never leave the form.
   * To charge a card, mount your payment provider's hosted fields in place of
   * the card inputs, so card data goes to the provider and not through your app.
   */
  payment: {
    method: CheckoutPaymentMethod
    cardName: string
    last4: string
    expiry: string
  }
  summary: CheckoutSummary
}

export type CheckoutResult = {
  orderNumber?: string
}

export type CheckoutLabels = {
  eyebrow: string
  title: string
  detailsTitle: string
  detailsDescription: string
  paymentTitle: string
  paymentDescription: string
  confirmationTitle: string
  /** Receives the contact email and the order number. */
  confirmationDescription: (email: string, orderNumber: string) => string
  emptyTitle: string
  emptyDescription: string
  continue: string
  back: string
  pay: string
  reserve: string
  done: string
  summary: string
  subtotal: string
  discount: string
  total: string
  discountCode: string
  discountPlaceholder: string
  discountApply: string
  discountRemove: string
  /** Receives the percentage off. */
  discountApplied: (percent: number) => string
  /** Eyebrow of each ticket on the confirmation step. */
  ticketEyebrow: (item: CheckoutItem) => string
}

export type CheckoutTicketField = {
  label: string
  value: React.ReactNode
}

export type CheckoutProps = {
  /**
   * Cart lines. Controlled when passed together with `onChange`. When omitted,
   * the block starts with `SAMPLE_CHECKOUT_ITEMS` (generic placeholder tickets).
   */
  items?: CheckoutItem[]
  /** Extra charges added to the total. Defaults to none. */
  fees?: CheckoutFee[]
  /** ISO 4217 currency code. */
  currency?: string
  /** Valid discount codes mapped to a percentage off the subtotal. Defaults to none. */
  discountCodes?: Record<string, number>
  onChange?: (items: CheckoutItem[]) => void
  /**
   * Async. Called with the form values on the payment step. Throw (or reject)
   * to show the error message. May resolve with an order number.
   * No payment is processed by this component.
   */
  onPay?: (
    values: CheckoutValues
  ) => void | CheckoutResult | Promise<void | CheckoutResult>
  /** Called when the person finishes on the confirmation step. */
  onComplete?: (order: { orderNumber: string; values: CheckoutValues }) => void
  /** Labels for the three steps. */
  steps?: [string, string, string]
  /** Shown in the empty-cart state. */
  emptyAction?: React.ReactNode
  /** Override any fixed copy. Merged over the defaults. */
  labels?: Partial<CheckoutLabels>
  /**
   * Fields shown on each confirmation ticket. Defaults to Attendee, Quantity
   * and Order.
   */
  ticketFields?: (
    item: CheckoutItem,
    order: { orderNumber: string; values: CheckoutValues }
  ) => CheckoutTicketField[]
  className?: string
}
```

## Example

```tsx
import {
  Checkout,
  SAMPLE_CHECKOUT_DISCOUNTS,
  SAMPLE_CHECKOUT_FEES,
} from "@/components/blocks/checkout"

export default function CheckoutDemo() {
  return (
    <div className="h-[680px] w-full overflow-hidden rounded-lg border bg-background">
      <Checkout
        fees={SAMPLE_CHECKOUT_FEES}
        discountCodes={SAMPLE_CHECKOUT_DISCOUNTS}
        onPay={async ({ payment }) => {
          await new Promise((r) => setTimeout(r, 1200))
          if (payment.last4 === "0002")
            throw new Error("Your card was declined.")
        }}
      />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/checkout. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Catalog

Browse and discovery screen: featured band, search, category chips, sort, price filter, availability switch, card grid, active filters, empty state and loading skeleton. Data shape: Event-shaped items (host, date, capacity, remaining). Not a retail product grid.

Category: Blocks

## Install

```bash
npx shadcn@latest add @opendraft/catalog
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Catalog } from "@/components/blocks/catalog"
```

## Dependencies

- npm: `lucide-react`, `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/badge`, `@opendraft/input`, `@opendraft/select`, `@opendraft/switch`, `@opendraft/progress`, `@opendraft/skeleton`, `@opendraft/empty-state`

## Props and types

```ts
export type CatalogItem = {
  id: string
  title: string
  host: string
  /** Venue or city, shown on cards and the featured band. */
  location?: string
  category: string
  /** ISO date (YYYY-MM-DD). Used for sorting and the date block. */
  date: string
  /** Price in whole units of the catalog `currency`. 0 renders as the free label. */
  price: number
  capacity: number
  /** Places left. 0 means sold out. */
  remaining: number
  image?: string
  favourite?: boolean
  featured?: boolean
}

export type CatalogProps = {
  items?: CatalogItem[]
  categories?: string[]
  onSelect?: (item: CatalogItem) => void
  onFavourite?: (id: string, next: boolean) => void
  /** Show a skeleton instead of the grid. */
  loading?: boolean
  title?: string
  eyebrow?: string
  /** ISO 4217 code used for every price and the default price filter. */
  currency?: string
  /** Price filter buckets (min and max both inclusive). Defaults are computed in `currency`. */
  priceRanges?: CatalogPriceRange[]
  /** "cards" is a grid; "compact" is a list-style row per item. */
  layout?: "cards" | "compact"
  /** Override any fixed copy. */
  labels?: Partial<CatalogLabels>
  className?: string
}

export type CatalogPriceRange = { label: string; min?: number; max?: number }

export type CatalogLabels = {
  /** Prefix before the host on the featured band. Empty string for none. */
  hostLabel: string
  placesLeft: string
  placesValue: (remaining: number, capacity: number) => string
  soldOut: string
  sellingFast: string
  free: string
  all: string
  featured: string
  viewDetails: string
  searchLabel: string
  searchPlaceholder: string
  categoryGroup: string
  sortBy: string
  sortRelevance: string
  sortPriceAsc: string
  sortPriceDesc: string
  sortDate: string
  price: string
  anyPrice: string
  hideSoldOut: string
  hidingSoldOut: string
  active: string
  clear: string
  loading: string
  results: (shown: number, total: number) => string
  emptyTitle: string
  emptyDescription: string
  clearFilters: string
}
```

## Example

```tsx
import { Catalog } from "@/components/blocks/catalog"

export default function CatalogDemo() {
  return (
    <div className="h-[680px] w-full overflow-hidden rounded-lg border bg-background">
      <Catalog />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/catalog. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Detail Page

Detail page with a sticky purchase panel: media, meta, key facts, tabs, tier selection with quantity, running total, checkout and waitlist. Data shape: An event-ticket purchase page (date, host, tiers, waitlist). Not a generic record or product page.

Category: Blocks

## Install

```bash
npx shadcn@latest add @opendraft/detail-page
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { DetailPage } from "@/components/blocks/detail-page"
```

## Dependencies

- npm: `lucide-react`, `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/avatar`, `@opendraft/badge`, `@opendraft/button`, `@opendraft/accordion`, `@opendraft/progress`, `@opendraft/quantity-stepper`, `@opendraft/radio-group`, `@opendraft/stat`, `@opendraft/tabs`

## Props and types

```ts
export type DetailTier = {
  id: string
  name: string
  description?: string
  /** Unit price in major currency units. */
  price: number
  /** Total seats / units in this tier. */
  capacity: number
  /** Units still available. 0 means sold out. */
  remaining: number
}

export type DetailScheduleItem = {
  time: string
  title: string
  description?: string
}

export type DetailFaq = { question: string; answer: string }

export type DetailFact = { label: string; value: string; hint?: string }

export type DetailHost = { name: string; role?: string; avatar?: string }

export type DetailItem = {
  title: string
  /** Optional hero image URL. Falls back to a muted placeholder. */
  image?: string
  imageAlt?: string
  category?: string
  /** Free-form date/time text, e.g. "Sat 14 Nov, 09:30 to 17:00". */
  date: string
  /** Venue or place; shown in the meta row when provided. */
  location?: string
  host: DetailHost
  currency?: string
  facts: DetailFact[]
  tiers: DetailTier[]
  sections: {
    about: string[]
    schedule: DetailScheduleItem[]
    faqs: DetailFaq[]
  }
}

export type DetailCheckout = { tierId: string; quantity: number }

export type DetailPageLabels = {
  /** Heading of the purchase panel. */
  reserveTitle: string
  /** aria-label of the option radio group. */
  chooseOption: string
  quantity: string
  total: string
  checkout: string
  save: string
  unsave: string
  showOptions: string
  hideOptions: string
  soldOut: string
  joinWaitlist: string
  onWaitlist: string
  available: string
  /** Receives the tier name. */
  availability: (name: string) => string
  /** Receives remaining and capacity. */
  left: (remaining: number, capacity: number) => string
  tabsLabel: string
  tabAbout: string
  tabSchedule: string
  tabFaq: string
  keyFacts: string
  purchase: string
  breadcrumb: string
  date: string
  location: string
  host: string
}

export type DetailPageProps = {
  item?: DetailItem
  onCheckout?: (selection: DetailCheckout) => void
  onWaitlist?: (tierId: string) => void
  onSaveChange?: (saved: boolean) => void
  /** Label for the back link. */
  backLabel?: string
  onBack?: () => void
  /** Makes the breadcrumb category a button instead of plain text. */
  onCategoryClick?: (category: string) => void
  /** Override any fixed copy (for localisation or other domains). */
  labels?: Partial<DetailPageLabels>
  className?: string
}
```

## Example

```tsx
import { DetailPage } from "@/components/blocks/detail-page"

export default function DetailPageDemo() {
  return (
    <div className="h-[680px] w-full overflow-hidden rounded-lg border bg-background">
      <DetailPage />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/detail-page. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Order Confirmation

Order confirmed screen with a completed stepper, order number, stat row, one ticket pass per ticket, an order summary and download, calendar, view-tickets and continue actions. Data shape: Ticket-shaped: always shows tickets and a QR pass, with a fixed three-step stepper.

Category: Blocks

## Install

```bash
npx shadcn@latest add @opendraft/order-confirmation
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { OrderConfirmation } from "@/components/blocks/order-confirmation"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/empty-state`, `@opendraft/stat`, `@opendraft/stepper`, `@opendraft/ticket-pass`

## Props and types

```ts
export type OrderLine = {
  id: string
  title: string
  detail?: string
  quantity: number
  /** Unit price in major currency units. */
  price: number
}

export type OrderTicket = {
  id: string
  title: string
  fields: TicketPassField[]
  code: string
  status?: TicketPassStatus
}

export type Order = {
  number: string
  email: string
  /** Pre-formatted date string. */
  date: string
  currency: string
  lines: OrderLine[]
  /** Total in major currency units. */
  total: number
  tickets: OrderTicket[]
}

export type OrderConfirmationLabels = {
  steps: [string, string, string]
  progress: string
  title: string
  orderNumber: string
  emailSent: string
  date: string
  tickets: string
  total: string
  ticketsHeading: string
  admitOne: string
  summaryHeading: string
  quantity: string
  download: string
  addToCalendar: string
  viewTickets: string
  continue: string
  emptyTitle: string
  emptyDescription: string
}

export type OrderConfirmationProps = {
  /** Omit or pass null to show the empty state. Defaults to sample data. */
  order?: Order | null
  labels?: Partial<OrderConfirmationLabels>
  onDownload?: () => void
  onAddToCalendar?: () => void
  onViewTickets?: () => void
  onContinue?: () => void
  className?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { OrderConfirmation } from "@/components/blocks/order-confirmation"

export default function OrderConfirmationDemo() {
  return (
    <div className="h-[680px] w-full overflow-hidden rounded-lg border bg-background">
      <OrderConfirmation
        onDownload={() => {}}
        onAddToCalendar={() => {}}
        onViewTickets={() => {}}
        onContinue={() => {}}
      />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/order-confirmation. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Voice Orb

Breathing WebGL liquid orb that reacts to a voice level or an audio analyser.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/voice-orb
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { VoiceOrb } from "@/components/agents/voice-orb"
```

Files added to the project:

- `components/agents/voice-orb.tsx`
- `components/agents/voice-orb/renderer.ts`

## Dependencies

- npm: `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`

## Props and types

```ts
type OrbColors = readonly [base: string, highlight: string, shadow: string]

type VoiceOrbProps = Omit<
  React.ComponentProps<"div">,
  "children" | "onError"
> & {
  /** Normalized activity, 0 to 1. Pass a MotionValue to avoid re-rendering every frame. */
  activity?: number | MotionValue<number>
  /** Optional caller-owned audio analyser. The orb never requests a microphone itself. */
  analyser?: AnalyserNode | null
  /** A preset name or [base, highlight, shadow] as #RGB / #RRGGBB hex. */
  colors?: keyof typeof ORB_PALETTES | OrbColors
  /** Pause the surface while keeping the current frame visible. */
  active?: boolean
  speed?: number
  onError?: (error: Error) => void
}
```

## Example

```tsx
"use client"

import * as React from "react"
import {
  useAnimationFrame,
  useMotionValue,
  useReducedMotion,
} from "motion/react"
import { Mic, MicOff, Pause, Play } from "lucide-react"
import { toast } from "sonner"

import { ORB_PALETTES, VoiceOrb } from "@/components/agents/voice-orb"
import { ShimmerText } from "@/components/motion/shimmer-text"
import { Button } from "@/components/ui/button"
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"

type Palette = keyof typeof ORB_PALETTES

export default function VoiceOrbDemo() {
  const activity = useMotionValue(0)
  const reduce = useReducedMotion()
  const [palette, setPalette] = React.useState<Palette>("brand")
  const [active, setActive] = React.useState(true)
  const [analyser, setAnalyser] = React.useState<AnalyserNode | null>(null)
  const audio = React.useRef<{ ctx: AudioContext; stream: MediaStream } | null>(
    null
  )

  // Simulated syllables and pauses while the microphone is off.
  useAnimationFrame((time) => {
    if (analyser) return
    if (reduce) return activity.set(0)
    const t = time / 1000
    const phrase = Math.max(0, Math.sin(t * 0.85))
    const syllable = Math.max(0, Math.sin(t * 9.3 + Math.sin(t * 2.1)))
    activity.set(phrase * (0.12 + syllable ** 2 * 0.72))
  })

  const stopMic = React.useCallback(() => {
    audio.current?.stream.getTracks().forEach((track) => track.stop())
    void audio.current?.ctx.close()
    audio.current = null
    setAnalyser(null)
  }, [])

  React.useEffect(() => stopMic, [stopMic])

  async function toggleMic() {
    if (analyser) return stopMic()
    try {
      const stream = await navigator.mediaDevices.getUserMedia({ audio: true })
      const ctx = new AudioContext()
      const node = ctx.createAnalyser()
      node.fftSize = 1024
      ctx.createMediaStreamSource(stream).connect(node)
      audio.current = { ctx, stream }
      setAnalyser(node)
    } catch {
      toast.error("Microphone unavailable", {
        description:
          "Allow microphone access to drive the orb with your voice.",
      })
    }
  }

  return (
    <div className="grid w-full items-center gap-8 md:grid-cols-[1fr_auto]">
      <div className="flex flex-col items-center gap-6">
        <VoiceOrb
          activity={activity}
          analyser={analyser}
          colors={palette}
          active={active}
          aria-label="Voice visualization"
          className="w-56"
        />
        <ShimmerText className="text-sm font-medium">
          {!active ? "Paused" : analyser ? "Listening…" : "Speaking…"}
        </ShimmerText>
      </div>
      <div className="grid gap-5 md:w-64">
        <Tabs value={palette} onValueChange={(v) => setPalette(v as Palette)}>
          <TabsList className="w-full">
            {Object.keys(ORB_PALETTES).map((name) => (
              <TabsTrigger key={name} value={name} className="capitalize">
                {name}
              </TabsTrigger>
            ))}
          </TabsList>
        </Tabs>
        <div className="flex gap-2">
          <Button
            variant={analyser ? "default" : "outline"}
            size="sm"
            className="flex-1"
            onClick={toggleMic}
          >
            {analyser ? <MicOff /> : <Mic />}
            {analyser ? "Stop mic" : "Use mic"}
          </Button>
          <Button
            variant="outline"
            size="icon-sm"
            aria-label={active ? "Pause" : "Resume"}
            onClick={() => setActive((v) => !v)}
          >
            {active ? <Pause /> : <Play />}
          </Button>
        </div>
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/voice-orb. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Message Bubble

Chat bubble surfaces with variants, a pop-in entrance and a collapsible body.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/message-bubble
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { MessageBubble, MessageBubbleContent, MessageBubbleGroup, MessageBubbleCollapsible } from "@/components/agents/message-bubble"
```

Files added to the project:

- `components/agents/message-bubble.tsx`
- `components/agents/message-context.tsx`

## Dependencies

- npm: `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`

## Props and types

```ts
export type MessageBubbleVariant =
  "solid" | "soft" | "tint" | "outline" | "ghost" | "danger"

export type MessageBubbleAlign = "start" | "end"

export interface MessageBubbleProps extends Omit<
  HTMLMotionProps<"div">,
  "children"
> {
  variant?: MessageBubbleVariant
  /** Defaults to the surrounding Message alignment when omitted. */
  align?: MessageBubbleAlign
  /** Plays the bubble entrance once when this component mounts. */
  animateIn?: boolean
  children?: ReactNode
}

export interface MessageBubbleContentProps extends ComponentPropsWithRef<"div"> {
  /** Replaces the content element while preserving bubble styling. */
  render?: ReactElement
}

export interface MessageBubbleGroupProps extends ComponentPropsWithRef<"div"> {
  spacing?: "compact" | "default"
}

export interface MessageBubbleCollapsibleProps extends ComponentPropsWithRef<"div"> {
  open?: boolean
  defaultOpen?: boolean
  onOpenChange?: (open: boolean) => void
  collapsedLines?: 2 | 3 | 4 | 5 | 6
  moreLabel?: ReactNode
  lessLabel?: ReactNode
  contentClassName?: string
  triggerClassName?: string
  children?: ReactNode
}
```

## Example

```tsx
import { Sparkles } from "lucide-react"

import {
  Message,
  MessageAvatar,
  MessageBubble,
  MessageBubbleCollapsible,
  MessageBubbleContent,
  MessageContent,
  MessageGroup,
  MessageTyping,
} from "@/components/agents/message"

const VARIANTS = ["solid", "soft", "tint", "outline", "danger"] as const

export default function MessageBubbleDemo() {
  return (
    <MessageGroup spacing="default" className="w-full max-w-xl">
      <Message from="assistant">
        <MessageAvatar>
          <Sparkles />
        </MessageAvatar>
        <MessageContent>
          <MessageBubble variant="soft">
            <MessageBubbleContent>
              <MessageBubbleCollapsible collapsedLines={2}>
                <p>
                  Launch in three phases. First, an internal beta with the core
                  chat flow and streaming. Second, a private preview with tool
                  results, approvals and citations. Third, general availability
                  with the full sidebar, voice input and analytics.
                </p>
                <p>
                  Each phase ends with a short review of reliability and
                  latency.
                </p>
              </MessageBubbleCollapsible>
            </MessageBubbleContent>
          </MessageBubble>
        </MessageContent>
      </Message>
      <div className="flex flex-wrap gap-2 pt-2">
        {VARIANTS.map((variant) => (
          <MessageBubble key={variant} variant={variant} className="w-auto">
            <MessageBubbleContent className="max-w-none">
              {variant}
            </MessageBubbleContent>
          </MessageBubble>
        ))}
        <MessageBubble variant="soft" className="w-auto">
          <MessageBubbleContent className="max-w-none text-muted-foreground">
            <MessageTyping />
          </MessageBubbleContent>
        </MessageBubble>
      </div>
    </MessageGroup>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/message-bubble. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Message

Message rows with avatar, header, footer, markers and a typing indicator.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/message
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Message, MessageGroup, MessageAvatar, MessageContent, MessageHeader, MessageFooter, MessageMarker, MessageTyping, MessageBubble, MessageBubbleCollapsible, MessageBubbleContent, MessageBubbleGroup, MessageScroller } from "@/components/agents/message"
```

## Dependencies

- npm: `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`, `@opendraft/message-bubble`, `@opendraft/message-scroller`

## Props and types

```ts
export type MessageFrom = "user" | "assistant"

export interface MessageProps extends Omit<
  ComponentPropsWithRef<typeof motion.article>,
  "children"
> {
  from: MessageFrom
  /** Plays a trailing-edge pop-up once when this message row mounts. */
  animateIn?: boolean
  children: ReactNode
}

export interface MessageGroupProps extends ComponentPropsWithRef<"div"> {
  spacing?: "compact" | "default"
}

export interface MessageAvatarProps extends ComponentPropsWithRef<"div"> {
  /** Keep an empty avatar slot so grouped messages remain aligned. */
  placeholder?: boolean
}

export type MessageContentProps = ComponentPropsWithRef<"div">

export type MessageHeaderProps = ComponentPropsWithRef<"div">

export type MessageFooterProps = ComponentPropsWithRef<"div">

export type MessageMarkerProps = ComponentPropsWithRef<"div">

export interface MessageTypingProps extends ComponentPropsWithRef<"span"> {
  label?: string
}
```

## Example

```tsx
import { Sparkles } from "lucide-react"

import {
  Message,
  MessageAvatar,
  MessageBubble,
  MessageBubbleContent,
  MessageContent,
  MessageFooter,
  MessageGroup,
  MessageHeader,
  MessageMarker,
  MessageTyping,
} from "@/components/agents/message"

export default function MessageDemo() {
  return (
    <MessageGroup spacing="default" className="w-full max-w-xl">
      <MessageMarker>Today</MessageMarker>
      <Message from="user">
        <MessageAvatar className="bg-brand/15 text-brand">NM</MessageAvatar>
        <MessageContent>
          <MessageHeader>You · 9:41</MessageHeader>
          <MessageBubble variant="solid">
            <MessageBubbleContent>
              Summarise yesterday&apos;s deploys.
            </MessageBubbleContent>
          </MessageBubble>
          <MessageFooter>Read</MessageFooter>
        </MessageContent>
      </Message>
      <Message from="assistant">
        <MessageAvatar>
          <Sparkles />
        </MessageAvatar>
        <MessageContent>
          <MessageHeader>Agent · 9:41</MessageHeader>
          <MessageBubble variant="ghost">
            <MessageBubbleContent>
              <p>
                Three deploys shipped. One rolled back after a failed health
                check.
              </p>
            </MessageBubbleContent>
          </MessageBubble>
        </MessageContent>
      </Message>
      <Message from="assistant">
        <MessageAvatar placeholder />
        <MessageContent>
          <MessageBubble>
            <MessageBubbleContent>
              <MessageTyping />
            </MessageBubbleContent>
          </MessageBubble>
        </MessageContent>
      </Message>
    </MessageGroup>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/message. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Message Scroller

Transcript that follows streamed output, with a rail for jumping between turns.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/message-scroller
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { MessageScroller } from "@/components/agents/message-scroller"
```

## Dependencies

- npm: `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/preview-rail`

## Props and types

```ts
export interface MessageScrollerProps extends ComponentPropsWithRef<"div"> {
  /** Keep streamed output pinned while the reader remains near the end. */
  followOutput?: boolean
  /** Distance from the end that still counts as following the output. */
  followThreshold?: number
  /** Smoothly follow growing content. */
  smooth?: boolean
  /** Reports when the reader leaves or returns to the live edge. */
  onFollowChange?: (following: boolean) => void
  /** Accessible label for the scrollable transcript. */
  label?: string
  /** Marks the transcript as waiting for more streamed content. */
  busy?: boolean
  /** Adds a compact rail for navigating between rendered Message rows. */
  navigation?: "rail"
  /** Accessible label for the optional message navigation rail. */
  navigationLabel?: string
  viewportClassName?: string
  contentClassName?: string
  railClassName?: string
  viewportRef?: Ref<HTMLElement>
  viewportProps?: Omit<
    ComponentPropsWithRef<"section">,
    "children" | "className" | "ref"
  >
  contentProps?: Omit<
    ComponentPropsWithRef<"div">,
    "children" | "className" | "ref"
  >
}
```

## Example

```tsx
"use client"

import * as React from "react"
import { AnimatePresence, useReducedMotion } from "motion/react"
import { Brain, FileText, ImagePlus, Puzzle, Sparkles, Zap } from "lucide-react"
import { toast } from "sonner"

import {
  Message,
  MessageAvatar,
  MessageBubble,
  MessageBubbleContent,
  MessageContent,
  MessageMarker,
  MessageScroller,
  MessageTyping,
} from "@/components/agents/message"
import { PromptInput } from "@/components/agents/prompt-input"
import { StreamingResponse } from "@/components/agents/streaming-response"

const MODELS = [
  { value: "fast", label: "Fast", icon: <Zap /> },
  { value: "balanced", label: "Balanced", icon: <Sparkles /> },
  { value: "deep", label: "Deep thinking", icon: <Brain /> },
]

const ACTIONS = [
  {
    value: "image",
    label: "Attach image",
    description: "Add a screenshot or visual reference.",
    icon: <ImagePlus />,
  },
  {
    value: "skill",
    label: "Use a skill",
    description: "Give the agent a specialized workflow.",
    icon: <Puzzle />,
  },
  {
    value: "context",
    label: "Add context",
    description: "Include a file with supporting details.",
    icon: <FileText />,
  },
]

type ChatMessage = { id: string; from: "user" | "assistant"; text: string }

const SEED: ChatMessage[] = [
  { id: "1", from: "user", text: "What should the first release include?" },
  {
    id: "2",
    from: "assistant",
    text: "Start with the smallest workflow that still feels complete: a prompt, a streamed answer and a way to recover from errors.",
  },
  { id: "3", from: "user", text: "Include streaming and recovery states too." },
  {
    id: "4",
    from: "assistant",
    text: "Yes. Those states make the first version feel dependable, and they're cheap to add now.",
  },
  { id: "5", from: "user", text: "How should we present tool results?" },
  {
    id: "6",
    from: "assistant",
    text: "Keep results close to the action that produced them, collapsed by default.",
  },
]

const REPLIES = [
  "The view follows the newest message while you're at the bottom. Scroll up while this streams and it leaves your reading position alone.",
  "Hover the rail on the right to preview each turn, then click to jump there.",
  "Every animation here reads from lib/motion.ts, so it feels like the rest of the system.",
]

/** Streams `text` at a steady rate; returns the visible slice and whether it's done. */
function useStream(text: string | null, cps = 90) {
  const reduce = useReducedMotion() ?? false
  const [state, setState] = React.useState({ text, cursor: 0 })
  // Restart from zero whenever the text changes (state adjusted during render).
  if (state.text !== text) setState({ text, cursor: 0 })

  React.useEffect(() => {
    if (!text || reduce) return
    const start = performance.now()
    let frame = 0
    const tick = (now: number) => {
      const cursor = Math.min(
        text.length,
        Math.floor(((now - start) / 1000) * cps)
      )
      setState({ text, cursor })
      if (cursor < text.length) frame = requestAnimationFrame(tick)
    }
    frame = requestAnimationFrame(tick)
    return () => cancelAnimationFrame(frame)
  }, [text, cps, reduce])

  const cursor = reduce ? (text?.length ?? 0) : state.cursor
  return {
    visible: text ? text.slice(0, cursor) : "",
    done: !!text && cursor >= text.length,
  }
}

export default function MessageScrollerDemo() {
  const [messages, setMessages] = React.useState(SEED)
  const [pending, setPending] = React.useState<string | null>(null)
  const [thinking, setThinking] = React.useState(false)
  const replyIndex = React.useRef(0)
  const thinkTimer = React.useRef<number | undefined>(undefined)
  const stream = useStream(pending)

  // When the stream finishes, move it into the transcript.
  React.useEffect(() => {
    if (!pending || !stream.done) return
    const t = window.setTimeout(() => {
      setMessages((m) => [
        ...m,
        { id: crypto.randomUUID(), from: "assistant", text: pending },
      ])
      setPending(null)
    }, 250)
    return () => window.clearTimeout(t)
  }, [pending, stream.done])

  React.useEffect(() => () => window.clearTimeout(thinkTimer.current), [])

  const send = (text: string) => {
    setMessages((m) => [...m, { id: crypto.randomUUID(), from: "user", text }])
    setThinking(true)
    thinkTimer.current = window.setTimeout(() => {
      setThinking(false)
      setPending(REPLIES[replyIndex.current++ % REPLIES.length])
    }, 700)
  }

  const stop = () => {
    window.clearTimeout(thinkTimer.current)
    setThinking(false)
    if (pending) {
      setMessages((m) => [
        ...m,
        {
          id: crypto.randomUUID(),
          from: "assistant",
          text: stream.visible + "…",
        },
      ])
    }
    setPending(null)
  }

  const busy = thinking || !!pending

  return (
    <div className="flex h-[560px] w-full flex-col overflow-hidden border bg-background">
      <MessageScroller
        navigation="rail"
        busy={busy}
        className="flex-1"
        contentClassName="flex flex-col gap-5 px-1 py-4 sm:px-4"
      >
        <MessageMarker>Today</MessageMarker>
        <AnimatePresence initial={false}>
          {messages.map((message) => (
            <ChatRow key={message.id} message={message} />
          ))}
          {thinking ? (
            <Message key="thinking" from="assistant" animateIn>
              <MessageAvatar>
                <Sparkles />
              </MessageAvatar>
              <MessageContent>
                <MessageBubble>
                  <MessageBubbleContent>
                    <MessageTyping />
                  </MessageBubbleContent>
                </MessageBubble>
              </MessageContent>
            </Message>
          ) : null}
          {pending ? (
            <Message key="streaming" from="assistant">
              <MessageAvatar>
                <Sparkles />
              </MessageAvatar>
              <MessageContent>
                <MessageBubble variant="ghost">
                  <MessageBubbleContent>
                    <StreamingResponse status="streaming" announce={false}>
                      <p>{stream.visible}</p>
                    </StreamingResponse>
                  </MessageBubbleContent>
                </MessageBubble>
              </MessageContent>
            </Message>
          ) : null}
        </AnimatePresence>
      </MessageScroller>
      <div className="border-t bg-background/60 p-3">
        <PromptInput
          models={MODELS}
          actions={ACTIONS}
          minRows={1}
          loading={busy}
          onSubmit={send}
          onStop={stop}
          onAction={(value) =>
            toast(ACTIONS.find((a) => a.value === value)?.label ?? "Action")
          }
          placeholder="Send a message…"
        />
      </div>
    </div>
  )
}

function ChatRow({ message }: { message: ChatMessage }) {
  const user = message.from === "user"
  return (
    <Message from={message.from} animateIn>
      <MessageAvatar className={user ? "bg-brand/15 text-brand" : undefined}>
        {user ? "NM" : <Sparkles />}
      </MessageAvatar>
      <MessageContent>
        <MessageBubble variant={user ? "solid" : "ghost"} animateIn>
          <MessageBubbleContent>
            {user ? message.text : <p>{message.text}</p>}
          </MessageBubbleContent>
        </MessageBubble>
      </MessageContent>
    </Message>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/message-scroller. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Prompt Input

Auto-growing prompt box with a model picker, an action menu and send / stop.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/prompt-input
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { PromptInput } from "@/components/agents/prompt-input"
```

## Dependencies

- npm: `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`, `@opendraft/button`, `@opendraft/popover`, `@opendraft/select`

## Props and types

```ts
export interface PromptModel {
  value: string
  label: ReactNode
  icon?: ReactNode
  disabled?: boolean
}

export interface PromptAction {
  value: string
  label: ReactNode
  description?: ReactNode
  icon?: ReactNode
  disabled?: boolean
}

export interface PromptInputProps extends Omit<
  TextareaHTMLAttributes<HTMLTextAreaElement>,
  "value" | "defaultValue" | "onChange" | "onSubmit" | "children"
> {
  value?: string
  defaultValue?: string
  onValueChange?: (value: string) => void
  models?: PromptModel[]
  model?: string
  defaultModel?: string
  onModelChange?: (model: string) => void
  actions?: PromptAction[]
  onAction?: (action: string) => void
  onSubmit?: (value: string, model?: string) => void | Promise<void>
  loading?: boolean
  onStop?: () => void
  minRows?: number
  maxRows?: number
  leadingAction?: ReactNode
  className?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"
import { Brain, FileText, ImagePlus, Puzzle, Sparkles, Zap } from "lucide-react"
import { toast } from "sonner"

import { PromptInput } from "@/components/agents/prompt-input"

const MODELS = [
  { value: "fast", label: "Fast", icon: <Zap /> },
  { value: "balanced", label: "Balanced", icon: <Sparkles /> },
  { value: "deep", label: "Deep thinking", icon: <Brain /> },
]

const ACTIONS = [
  {
    value: "image",
    label: "Attach image",
    description: "Add a screenshot or visual reference.",
    icon: <ImagePlus />,
  },
  {
    value: "skill",
    label: "Use a skill",
    description: "Give the agent a specialized workflow.",
    icon: <Puzzle />,
  },
  {
    value: "context",
    label: "Add context",
    description: "Include a file with supporting details.",
    icon: <FileText />,
  },
]

export default function PromptInputDemo() {
  const [loading, setLoading] = React.useState(false)
  const timer = React.useRef<number | undefined>(undefined)

  React.useEffect(() => () => window.clearTimeout(timer.current), [])

  return (
    <div className="w-full max-w-xl">
      <PromptInput
        models={MODELS}
        actions={ACTIONS}
        defaultModel="balanced"
        defaultValue="Review the current implementation and suggest the next improvement."
        loading={loading}
        onSubmit={(prompt, model) => {
          setLoading(true)
          timer.current = window.setTimeout(() => {
            setLoading(false)
            toast("Prompt sent", { description: `${model}: ${prompt}` })
          }, 1200)
        }}
        onStop={() => {
          window.clearTimeout(timer.current)
          setLoading(false)
        }}
        onAction={(value) =>
          toast(ACTIONS.find((a) => a.value === value)?.label ?? "Action")
        }
      />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/prompt-input. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Streaming Response

Streamed answer with copy, retry, feedback and a sources footer.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/streaming-response
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { StreamingResponse } from "@/components/agents/streaming-response"
```

## Dependencies

- npm: `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`, `@opendraft/citations`, `@opendraft/agent-disclosure`

## Props and types

```ts
export type StreamingResponseStatus = "streaming" | "complete" | "error"

export type StreamingResponseFeedback = "up" | "down" | null

export interface StreamingResponseProps {
  /** Rendered response content. Pass plain text or the output of a Markdown renderer. */
  children: ReactNode
  status?: StreamingResponseStatus
  /** Plain-text value copied by the built-in copy action. */
  copyText?: string
  /** Overrides the built-in clipboard action. */
  onCopy?: () => void | Promise<void>
  onRetry?: () => void
  /** Optional sources shown as a compact footer disclosure after streaming. */
  sources?: CitationItem[]
  sourcesOpen?: boolean
  defaultSourcesOpen?: boolean
  onSourcesOpenChange?: (open: boolean) => void
  sourceIdPrefix?: string
  feedback?: StreamingResponseFeedback
  defaultFeedback?: StreamingResponseFeedback
  onFeedbackChange?: (feedback: StreamingResponseFeedback) => void
  /** Set false when a surrounding conversation log announces streamed text. */
  announce?: boolean
  /** Hides the built-in completion actions without changing response status. */
  showActions?: boolean
  className?: string
  contentClassName?: string
  actionsClassName?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"
import { useReducedMotion } from "motion/react"

import type { CitationItem } from "@/components/agents/citations"
import { StreamingResponse } from "@/components/agents/streaming-response"

const SOURCES: CitationItem[] = [
  {
    id: "motion",
    title: "Motion for React",
    domain: "motion.dev",
    url: "https://motion.dev/docs/react",
  },
  {
    id: "aria",
    title: "ARIA live regions",
    domain: "developer.mozilla.org",
    url: "https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions",
  },
  {
    id: "radix",
    title: "Radix Primitives",
    domain: "radix-ui.com",
    url: "https://www.radix-ui.com/primitives",
  },
]

const ANSWER =
  "Streaming answers keep structure as they arrive. Links stay clickable, lists keep their spacing, and the actions only appear once the response is complete, so nothing jumps under the reader's cursor."

function Run({ onRetry }: { onRetry: () => void }) {
  const reduce = useReducedMotion() ?? false
  const [cursor, setCursor] = React.useState(0)
  const [complete, setComplete] = React.useState(false)

  React.useEffect(() => {
    if (reduce) return
    const start = performance.now()
    let frame = 0
    let doneTimer: number | undefined
    const tick = (now: number) => {
      const next = Math.min(
        ANSWER.length,
        Math.floor(((now - start) / 1000) * 110)
      )
      setCursor(next)
      if (next < ANSWER.length) frame = requestAnimationFrame(tick)
      else doneTimer = window.setTimeout(() => setComplete(true), 350)
    }
    frame = requestAnimationFrame(tick)
    return () => {
      cancelAnimationFrame(frame)
      window.clearTimeout(doneTimer)
    }
  }, [reduce])

  const shown = reduce ? ANSWER.length : cursor
  return (
    <StreamingResponse
      status={reduce || complete ? "complete" : "streaming"}
      copyText={ANSWER}
      onRetry={onRetry}
      sources={SOURCES}
    >
      <p>{ANSWER.slice(0, shown)}</p>
    </StreamingResponse>
  )
}

export default function StreamingResponseDemo() {
  const [run, setRun] = React.useState(0)
  return (
    <div className="w-full max-w-xl">
      <Run key={run} onRetry={() => setRun((r) => r + 1)} />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/streaming-response. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Citations

Inline citation markers, favicon stacks and a collapsible source list.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/citations
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Citation, CitationFavicon, CitationStack, CitationList, Citations } from "@/components/agents/citations"
```

## Dependencies

- npm: `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`, `@opendraft/agent-disclosure`, `@opendraft/use-favicon`

## Props and types

```ts
export interface CitationItem {
  id: string
  title: ReactNode
  domain?: ReactNode
  url?: string
}

export interface CitationsProps {
  citations: CitationItem[]
  title?: ReactNode
  open?: boolean
  defaultOpen?: boolean
  onOpenChange?: (open: boolean) => void
  idPrefix?: string
  className?: string
}

export interface CitationProps {
  citationId: string
  index: number
  /** Must match the related Citations idPrefix. */
  idPrefix: string
  className?: string
}

export interface CitationListProps {
  citations: CitationItem[]
  idPrefix?: string
  className?: string
}

export interface CitationStackProps {
  citations: CitationItem[]
  limit?: number
  className?: string
}

function CitationFavicon(props: {
  url?: string
  className?: string
})
```

## Example

```tsx
import {
  Citation,
  Citations,
  type CitationItem,
} from "@/components/agents/citations"

const SOURCES: CitationItem[] = [
  {
    id: "motion",
    title: "Motion for React",
    domain: "motion.dev",
    url: "https://motion.dev/docs/react",
  },
  {
    id: "radix",
    title: "Radix Primitives",
    domain: "radix-ui.com",
    url: "https://www.radix-ui.com/primitives",
  },
  {
    id: "tailwind",
    title: "Tailwind CSS v4",
    domain: "tailwindcss.com",
    url: "https://tailwindcss.com/docs",
  },
]

export default function CitationsDemo() {
  return (
    <div className="grid w-full max-w-xl gap-4 text-sm leading-6">
      <p>
        Springs come from Motion
        <Citation citationId="motion" index={1} idPrefix="demo" />, behavior
        from Radix
        <Citation citationId="radix" index={2} idPrefix="demo" /> and styling
        from Tailwind
        <Citation citationId="tailwind" index={3} idPrefix="demo" />.
      </p>
      <Citations citations={SOURCES} idPrefix="demo" defaultOpen />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/citations. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Agent Activity

Collapsible run log of steps, web searches and tool calls.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/agent-activity
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { AgentActivity } from "@/components/agents/agent-activity"
```

Files added to the project:

- `components/agents/agent-activity/index.tsx`
- `components/agents/agent-activity/activity-row.tsx`
- `components/agents/agent-activity/types.ts`

## Dependencies

- npm: `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`, `@opendraft/agent-disclosure`, `@opendraft/loading-states`

## Props and types

```ts
export type AgentActivityStatus = "working" | "complete"

export type AgentStepStatus = "pending" | "active" | "complete"

export interface AgentActivityStep {
  id: string
  type: "step"
  label: ReactNode
  status?: AgentStepStatus
  meta?: ReactNode
}

export interface AgentActivityText {
  id: string
  type: "text"
  content: ReactNode
}

export interface AgentSearchResult {
  id: string
  title: ReactNode
  domain?: ReactNode
  url?: string
  icon?: ReactNode
}

export interface AgentActivitySearch {
  id: string
  type: "search"
  query: ReactNode
  results?: AgentSearchResult[]
  moreCount?: number
}

export interface AgentActivityTool {
  id: string
  type: "tool"
  action: "read" | "edit" | "run" | (string & {})
  target: ReactNode
  additions?: number
  deletions?: number
}

export type AgentTraceKind =
  "thinking" | "message" | "write" | "run" | "read" | (string & {})

export interface AgentActivityTrace {
  id: string
  type: "trace"
  kind: AgentTraceKind
  label: ReactNode
  detail?: ReactNode
  icon?: ReactNode
}

export type AgentActivityItem =
  | AgentActivityStep
  | AgentActivityText
  | AgentActivitySearch
  | AgentActivityTool
  | AgentActivityTrace

export type AgentActivityContentType = AgentActivityItem["type"] | "mixed"

export interface AgentActivityProps {
  /** Chronological activity entries. Append or update items as events stream. */
  items: AgentActivityItem[]
  /** Expected activity kind before the first streamed item arrives. */
  contentType?: AgentActivityContentType
  /** Current run phase. Active runs always stay expanded. */
  status?: AgentActivityStatus
  /** Elapsed run time, in seconds. Used by the step-only summary. */
  duration?: number
  /** Controlled expanded state used after the run completes. */
  open?: boolean
  /** Initial expanded state used after the run completes. */
  defaultOpen?: boolean
  /** Called when the completed activity disclosure changes state. */
  onOpenChange?: (open: boolean) => void
  /** Collapse the disclosure when status changes from working to complete. */
  collapseOnComplete?: boolean
  /** Optional label shown while the run is active. */
  activeLabel?: ReactNode
  /** Optional completed summary. Derived from the item types by default. */
  summary?: ReactNode
  /** Optional renderer for the contents of the active status row. */
  renderWorkingStatus?: (context: {
    label: ReactNode
    duration: number
  }) => ReactNode
  /** Optional renderer for the contents before the built-in disclosure chevron. */
  renderCompletedStatus?: (context: {
    summary: ReactNode
    duration: number
  }) => ReactNode
  /** Maximum visible activity height before the stream begins gliding. */
  maxHeight?: number
  className?: string
  contentClassName?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"
import { useReducedMotion } from "motion/react"

import {
  AgentActivity,
  type AgentActivityItem,
} from "@/components/agents/agent-activity"

const BRIEF: AgentActivityItem = {
  id: "brief",
  type: "step",
  label: "Reading the launch brief",
  status: "active",
}
const SEARCH: AgentActivityItem = {
  id: "search",
  type: "search",
  query: "design systems with motion tokens",
  results: [],
}
const SEARCH_DONE: AgentActivityItem = {
  ...SEARCH,
  results: [
    { id: "linear", title: "Linear Method", domain: "linear.app" },
    { id: "vercel", title: "Geist Design System", domain: "vercel.com" },
    { id: "stripe", title: "Stripe Sessions UI", domain: "stripe.com" },
  ],
  moreCount: 4,
}
const READ: AgentActivityItem = {
  id: "read",
  type: "tool",
  action: "read",
  target: "lib/motion.ts",
}
const FRAMES: AgentActivityItem[][] = [
  [BRIEF],
  [{ ...BRIEF, status: "complete" }, SEARCH],
  [{ ...BRIEF, status: "complete" }, SEARCH_DONE],
  [{ ...BRIEF, status: "complete" }, SEARCH_DONE, READ],
  [
    { ...BRIEF, status: "complete" },
    SEARCH_DONE,
    READ,
    {
      id: "edit",
      type: "tool",
      action: "edit",
      target: "components/ui/tabs.tsx",
      additions: 42,
      deletions: 8,
    },
    { id: "run", type: "tool", action: "run", target: "pnpm build" },
    {
      id: "verify",
      type: "step",
      label: "Checking both themes",
      status: "complete",
    },
  ],
]

export default function AgentActivityDemo() {
  const reduce = useReducedMotion() ?? false
  const [frame, setFrame] = React.useState(0)
  const [complete, setComplete] = React.useState(false)

  React.useEffect(() => {
    if (reduce) return
    const timers = FRAMES.slice(1).map((_, i) =>
      window.setTimeout(() => setFrame(i + 1), 850 + i * 1050)
    )
    timers.push(
      window.setTimeout(
        () => setComplete(true),
        850 + (FRAMES.length - 2) * 1050 + 900
      )
    )
    return () => timers.forEach(window.clearTimeout)
  }, [reduce])

  const done = reduce || complete
  return (
    <AgentActivity
      items={FRAMES[reduce ? FRAMES.length - 1 : frame]}
      status={done ? "complete" : "working"}
      duration={5.1}
      defaultOpen={reduce}
      collapseOnComplete={!reduce}
      maxHeight={220}
    />
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/agent-activity. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Agent Loading States

Thinking shimmer, elapsed-time progress and rotating reasoning text.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/loading-states
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { AgentProgress, ReasoningText, ThinkingShimmer } from "@/components/agents/loading-states"
```

Files added to the project:

- `components/agents/loading-states/index.ts`
- `components/agents/loading-states/agent-progress.tsx`
- `components/agents/loading-states/reasoning-text.tsx`
- `components/agents/loading-states/thinking-shimmer.tsx`

## Dependencies

- npm: `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`, `@opendraft/shimmer-text`, `@opendraft/text-scramble`, `@opendraft/loader`, `@opendraft/text-shimmer`

## Props and types

```ts
export interface AgentProgressProps {
  /** Verb describing the agent's current activity. */
  label?: string
  /** Controlled elapsed time in seconds. */
  elapsedSeconds?: number
  /** Starting time for the internal timer, in seconds. */
  initialSeconds?: number
  /** Whether the internal timer should advance. Ignored when elapsedSeconds is provided. */
  running?: boolean
  className?: string
}

export type ReasoningTextVariant = "cascade" | "swap" | "scramble"

export interface ReasoningTextProps {
  /** Phrases cycled through while the agent works. */
  phrases?: string[]
  /** Animation used when the active phrase changes. */
  variant?: ReasoningTextVariant
  /** Milliseconds each phrase remains visible. */
  interval?: number
  /** Seconds taken for one shimmer pass. */
  shimmerDuration?: number
  /** Optional leading visual. Defaults to a terminal-style ASCII loader. */
  indicator?: ReactNode
  className?: string
}

export interface ThinkingShimmerProps {
  /** Loading message shown to the user. */
  children?: ReactNode
  /** Seconds taken for one shimmer pass. */
  duration?: number
  className?: string
}
```

## Example

```tsx
import {
  AgentProgress,
  ReasoningText,
  ThinkingShimmer,
} from "@/components/agents/loading-states"

const PHRASES = [
  "Thinking",
  "Reading the request",
  "Working through the details",
  "Preparing the answer",
]

export default function LoadingStatesDemo() {
  return (
    <div className="grid w-full gap-8 sm:grid-cols-2">
      <div className="grid content-start gap-6">
        <Labeled label="ThinkingShimmer">
          <ThinkingShimmer className="text-base" />
        </Labeled>
        <Labeled label="AgentProgress">
          <AgentProgress
            label="Churning"
            initialSeconds={151.6}
            className="text-base"
          />
        </Labeled>
      </div>
      <div className="grid content-start gap-6">
        <Labeled label="ReasoningText · cascade">
          <ReasoningText
            variant="cascade"
            phrases={PHRASES}
            className="text-base"
          />
        </Labeled>
        <Labeled label="ReasoningText · swap">
          <ReasoningText
            variant="swap"
            phrases={PHRASES}
            className="text-base"
          />
        </Labeled>
        <Labeled label="ReasoningText · scramble">
          <ReasoningText
            variant="scramble"
            phrases={["Thinking", "Searching", "Reasoning", "Composing"]}
            className="text-base"
          />
        </Labeled>
      </div>
    </div>
  )
}

function Labeled({
  label,
  children,
}: {
  label: string
  children: React.ReactNode
}) {
  return (
    <div className="grid gap-2">
      <span className="eyebrow text-muted-foreground">{label}</span>
      {children}
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/loading-states. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Todo List

Live task plan with per-item progress and a rolling completed count. Data shape: A read-only view of an agent's plan: items expand but can't be ticked. For a tickable checklist use `checkbox` rows with `progress`.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/todo-list
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { TodoList } from "@/components/agents/todo-list"
```

## Dependencies

- npm: `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`, `@opendraft/agent-disclosure`, `@opendraft/action-swap`

## Props and types

```ts
export type TodoItemStatus =
  "pending" | "in-progress" | "completed" | "cancelled"

export interface TodoItem {
  id: string
  title: ReactNode
  status?: TodoItemStatus
  progress?: number
  detail?: ReactNode
}

export interface TodoListProps {
  items: TodoItem[]
  title?: ReactNode
  open?: boolean
  defaultOpen?: boolean
  onOpenChange?: (open: boolean) => void
  collapseOnComplete?: boolean
  maxHeight?: number
  className?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"
import { useReducedMotion } from "motion/react"

import { TodoList, type TodoItem } from "@/components/agents/todo-list"

const TASKS = [
  "Inspect the current data flow",
  "Update the response schema",
  "Add coverage for edge cases",
  "Run checks and prepare the result",
]
const TICKS = 4

export default function TodoListDemo() {
  const reduce = useReducedMotion() ?? false
  const [tick, setTick] = React.useState(0)

  React.useEffect(() => {
    if (reduce || tick >= TASKS.length * TICKS) return
    const t = window.setTimeout(() => setTick((v) => v + 1), 280)
    return () => window.clearTimeout(t)
  }, [tick, reduce])

  const step = reduce ? TASKS.length * TICKS : tick
  const items: TodoItem[] = TASKS.map((title, i) => {
    const active = step >= i * TICKS && step < (i + 1) * TICKS
    const pct = ((step % TICKS) + 1) * 25
    return {
      id: `task-${i}`,
      title,
      status:
        step >= (i + 1) * TICKS
          ? "completed"
          : active
            ? "in-progress"
            : "pending",
      progress: active ? pct : undefined,
      detail: active ? `${pct}%` : undefined,
    }
  })

  return <TodoList items={items} title="Implementation plan" />
}
```

Live docs: https://ui-system-virid.vercel.app/docs/todo-list. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Tool Result

Tool call card for terminal, request and file output with status, copy and retry.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/tool-result
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { ToolResultOutput, ToolResult } from "@/components/agents/tool-result"
```

## Dependencies

- npm: `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`, `@opendraft/agent-disclosure`, `@opendraft/action-swap`, `@opendraft/agent-code`

## Props and types

```ts
export type ToolResultStatus = "running" | "success" | "error" | "cancelled"

export type ToolResultKind = "terminal" | "request" | "custom"

export interface ToolResultProps {
  tool: ReactNode
  title: ReactNode
  children: ReactNode
  status?: ToolResultStatus
  kind?: ToolResultKind
  meta?: ReactNode
  icon?: ReactNode
  open?: boolean
  defaultOpen?: boolean
  onOpenChange?: (open: boolean) => void
  collapseOnComplete?: boolean
  maxHeight?: number
  copyText?: string
  onCopy?: () => void | Promise<void>
  onRetry?: () => void
  className?: string
  contentClassName?: string
}

export interface ToolResultOutputProps {
  children: string
  language?: AgentCodeLanguage
  className?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"
import { useReducedMotion } from "motion/react"

import { AgentCode } from "@/components/agents/agent-code"
import {
  ToolResult,
  ToolResultOutput,
  type ToolResultStatus,
} from "@/components/agents/tool-result"

/** Reveals `steps` items one by one, then settles on `finalStatus`. */
function useSteps(
  steps: number,
  interval = 420,
  finalStatus: Exclude<ToolResultStatus, "running"> = "success"
) {
  const reduce = useReducedMotion() ?? false
  const [visible, setVisible] = React.useState(0)
  const [status, setStatus] = React.useState<ToolResultStatus>("running")

  React.useEffect(() => {
    if (reduce) return
    const timers = Array.from({ length: steps }, (_, i) =>
      window.setTimeout(() => setVisible(i + 1), i * interval + 180)
    )
    timers.push(
      window.setTimeout(() => setStatus(finalStatus), steps * interval + 480)
    )
    return () => timers.forEach(window.clearTimeout)
  }, [finalStatus, interval, reduce, steps])

  return reduce
    ? { visible: steps, status: finalStatus as ToolResultStatus }
    : { visible, status }
}

const TERMINAL = [
  "$ pnpm build",
  "▲ Next.js 16.4.0 (Turbopack)",
  "✓ Compiled successfully in 1.3s",
  "✓ Finished TypeScript in 4.3s",
  "✓ Generating static pages (4/4)",
  "registry.json: 58 items",
] as const

function TerminalRun({ onReplay }: { onReplay: () => void }) {
  const { visible, status } = useSteps(TERMINAL.length)
  const output = TERMINAL.slice(0, visible).join("\n")
  return (
    <ToolResult
      tool="terminal.run"
      title={status === "running" ? "Building the library" : "Build passed"}
      kind="terminal"
      status={status}
      meta={status === "success" ? "6.1s" : undefined}
      copyText={output}
      onRetry={onReplay}
      maxHeight={150}
    >
      <ToolResultOutput>{output}</ToolResultOutput>
    </ToolResult>
  )
}

const RESPONSE = `{
  "error": "rate_limit_exceeded",
  "retryAfter": 30,
  "requestId": "req_8f21"
}`

function RequestRun({ onReplay }: { onReplay: () => void }) {
  const { visible, status } = useSteps(3, 600, "error")
  return (
    <ToolResult
      tool="http.request"
      title={
        status === "running" ? "Fetching project activity" : "Request failed"
      }
      kind="request"
      status={status}
      meta={status === "error" ? "429" : "GET /v1/activity"}
      copyText={RESPONSE}
      onRetry={onReplay}
      collapseOnComplete={false}
      maxHeight={150}
    >
      {visible < 3 ? (
        <ToolResultOutput>
          {visible === 0
            ? "Preparing request…"
            : visible === 1
              ? "GET /v1/activity\nConnecting…"
              : "GET /v1/activity\nWaiting for response…"}
        </ToolResultOutput>
      ) : (
        <AgentCode code={RESPONSE} language="json" />
      )}
    </ToolResult>
  )
}

export default function ToolResultDemo() {
  const [run, setRun] = React.useState(0)
  const replay = () => setRun((r) => r + 1)
  return (
    <div key={run} className="grid w-full max-w-xl gap-3">
      <TerminalRun onReplay={replay} />
      <RequestRun onReplay={replay} />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/tool-result. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Code Block

Streaming code with Shiki highlighting, line highlights and copy.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/code-block
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { CodeBlock } from "@/components/agents/code-block"
```

## Dependencies

- npm: `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`, `@opendraft/agent-code`

## Props and types

```ts
export type CodeBlockStatus = "streaming" | "complete"

export interface CodeBlockProps {
  code: string
  language?: AgentCodeLanguage
  filename?: ReactNode
  status?: CodeBlockStatus
  showLineNumbers?: boolean
  highlightLines?: number[]
  maxHeight?: number
  wrap?: boolean
  copyable?: boolean
  onCopy?: () => void | Promise<void>
  className?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"
import { useReducedMotion } from "motion/react"

import { CodeBlock } from "@/components/agents/code-block"

const CODE = [
  'import { motion } from "motion/react"',
  'import { spring } from "@/lib/motion"',
  "",
  "export function Indicator({ active }: { active: boolean }) {",
  "  return (",
  "    <motion.span",
  "      layout",
  "      transition={spring.smooth}",
  '      className={active ? "bg-brand" : "bg-muted"}',
  "    />",
  "  )",
  "}",
]

export default function CodeBlockDemo() {
  const reduce = useReducedMotion() ?? false
  const [lines, setLines] = React.useState(1)

  React.useEffect(() => {
    if (reduce || lines >= CODE.length) return
    const t = window.setTimeout(() => setLines((v) => v + 1), 220)
    return () => window.clearTimeout(t)
  }, [lines, reduce])

  const shown = reduce ? CODE.length : lines
  return (
    <CodeBlock
      filename="indicator.tsx"
      language="tsx"
      code={CODE.slice(0, shown).join("\n")}
      status={shown === CODE.length ? "complete" : "streaming"}
      highlightLines={[7, 8]}
      maxHeight={240}
    />
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/code-block. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# File Diff

Streaming unified diff with added and removed counts.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/file-diff
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { FileDiff } from "@/components/agents/file-diff"
```

## Dependencies

- npm: `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`, `@opendraft/agent-disclosure`, `@opendraft/agent-code`

## Props and types

```ts
export type FileDiffStatus = "streaming" | "complete"

export type FileDiffLineType = "added" | "removed" | "context"

export interface FileDiffLine {
  id: string
  type?: FileDiffLineType
  oldLine?: number
  newLine?: number
  content: string
}

export interface FileDiffProps {
  file: ReactNode
  lines: FileDiffLine[]
  status?: FileDiffStatus
  open?: boolean
  defaultOpen?: boolean
  onOpenChange?: (open: boolean) => void
  collapseOnComplete?: boolean
  maxHeight?: number
  language?: AgentCodeLanguage
  copyText?: string
  onCopy?: () => void | Promise<void>
  className?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"
import { useReducedMotion } from "motion/react"

import { FileDiff, type FileDiffLine } from "@/components/agents/file-diff"
import type { ToolResultStatus } from "@/components/agents/tool-result"

/** Reveals `steps` items one by one, then settles on `finalStatus`. */
function useSteps(
  steps: number,
  interval = 420,
  finalStatus: Exclude<ToolResultStatus, "running"> = "success"
) {
  const reduce = useReducedMotion() ?? false
  const [visible, setVisible] = React.useState(0)
  const [status, setStatus] = React.useState<ToolResultStatus>("running")

  React.useEffect(() => {
    if (reduce) return
    const timers = Array.from({ length: steps }, (_, i) =>
      window.setTimeout(() => setVisible(i + 1), i * interval + 180)
    )
    timers.push(
      window.setTimeout(() => setStatus(finalStatus), steps * interval + 480)
    )
    return () => timers.forEach(window.clearTimeout)
  }, [finalStatus, interval, reduce, steps])

  return reduce
    ? { visible: steps, status: finalStatus as ToolResultStatus }
    : { visible, status }
}

const DIFF: FileDiffLine[] = [
  {
    id: "1",
    oldLine: 12,
    newLine: 12,
    content: "export const spring = {",
  },
  {
    id: "2",
    type: "removed",
    oldLine: 13,
    content: '  snappy: { type: "spring", stiffness: 400, damping: 28 },',
  },
  {
    id: "3",
    type: "added",
    newLine: 13,
    content:
      '  snappy: { type: "spring", stiffness: 520, damping: 36, mass: 0.8 },',
  },
  {
    id: "4",
    type: "added",
    newLine: 14,
    content:
      '  pop: { type: "spring", stiffness: 500, damping: 30, mass: 0.58 },',
  },
  { id: "5", oldLine: 14, newLine: 15, content: "}" },
]

export default function FileDiffDemo() {
  const { visible, status } = useSteps(DIFF.length, 360)
  return (
    <FileDiff
      file="lib/motion.ts"
      lines={DIFF.slice(0, visible)}
      status={status === "success" ? "complete" : "streaming"}
      copyText={DIFF.map((l) => l.content).join("\n")}
      collapseOnComplete={false}
      maxHeight={180}
    />
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/file-diff. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Approval Card

Human-in-the-loop card: stepped questions, or approve / request changes / reject. Data shape: One decision (Approve, Request changes, Reject) with no approver or timestamp, and fixed resolved wording.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/approval-card
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { ApprovalCard } from "@/components/agents/approval-card"
```

Files added to the project:

- `components/agents/approval-card/index.tsx`
- `components/agents/approval-card/types.ts`

## Dependencies

- npm: `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`, `@opendraft/agent-disclosure`, `@opendraft/action-swap`, `@opendraft/button`, `@opendraft/checkbox`, `@opendraft/radio-group`, `@opendraft/input`

## Props and types

```ts
export type ApprovalCardStatus =
  | "pending"
  | "submitting"
  | "approved"
  | "rejected"
  | "changes-requested"
  | "answered"

export interface ApprovalCardOption {
  value: string
  label: string
  disabled?: boolean
}

export interface ApprovalCardQuestion {
  id: string
  title: ReactNode
  description?: ReactNode
  options?: ApprovalCardOption[]
  multiple?: boolean
  autoAdvance?: boolean
  allowCustom?: boolean
  customPlaceholder?: string
}

export interface ApprovalCardAnswer {
  selected: string[]
  custom?: string
}

export type ApprovalCardAnswers = Record<string, ApprovalCardAnswer>

export interface ApprovalCardProps {
  title?: ReactNode
  description?: ReactNode
  children?: ReactNode
  questions?: ApprovalCardQuestion[]
  status?: ApprovalCardStatus
  answers?: ApprovalCardAnswers
  defaultAnswers?: ApprovalCardAnswers
  onAnswersChange?: (answers: ApprovalCardAnswers) => void
  step?: number
  defaultStep?: number
  onStepChange?: (step: number) => void
  onSubmit?: (answers: ApprovalCardAnswers) => void
  onApprove?: () => void
  onReject?: () => void
  onRequestChanges?: () => void
  onDismiss?: () => void
  approveLabel?: ReactNode
  submitLabel?: ReactNode
  result?: ReactNode
  className?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"

import {
  ApprovalCard,
  type ApprovalCardQuestion,
  type ApprovalCardStatus,
} from "@/components/agents/approval-card"

/** Runs `fn` after `ms`; pending timers clear on unmount. */
function useTimers() {
  const timers = React.useRef<number[]>([])
  React.useEffect(() => () => timers.current.forEach(window.clearTimeout), [])
  return React.useCallback((fn: () => void, ms: number) => {
    timers.current.push(window.setTimeout(fn, ms))
  }, [])
}

const QUESTIONS: ApprovalCardQuestion[] = [
  {
    id: "scope",
    title: "How focused should the first release be?",
    options: [
      { value: "focused", label: "A focused starter set" },
      { value: "broad", label: "A broader collection" },
      { value: "flagship", label: "One flagship experience" },
    ],
    allowCustom: true,
    customPlaceholder: "Describe another scope…",
  },
  {
    id: "checks",
    title: "Which checks should block publishing?",
    description: "Select every check the agent must pass before it continues.",
    multiple: true,
    options: [
      { value: "types", label: "Type safety" },
      { value: "accessibility", label: "Accessibility" },
      { value: "registry", label: "Registry validation" },
    ],
  },
  {
    id: "preserve",
    title: "Anything the agent should preserve?",
    allowCustom: true,
    customPlaceholder: "Add a final constraint…",
  },
]

function QuestionFlow() {
  const [status, setStatus] = React.useState<ApprovalCardStatus>("pending")
  const later = useTimers()
  return (
    <ApprovalCard
      questions={QUESTIONS}
      status={status}
      onSubmit={() => {
        setStatus("submitting")
        later(() => setStatus("answered"), 750)
      }}
      result="Three responses sent to the agent."
    />
  )
}

function ReviewFlow() {
  const [status, setStatus] = React.useState<ApprovalCardStatus>("pending")
  const later = useTimers()
  const finish = (next: ApprovalCardStatus) => {
    setStatus("submitting")
    later(() => setStatus(next), 700)
  }
  return (
    <ApprovalCard
      title="Publish the component update?"
      description="The agent has prepared the release and is waiting for your decision."
      status={status}
      onApprove={() => finish("approved")}
      onRequestChanges={() => finish("changes-requested")}
      onReject={() => finish("rejected")}
      result={
        status === "approved"
          ? "Publishing was approved."
          : status === "changes-requested"
            ? "The agent will wait for revision notes."
            : "Publishing was declined."
      }
    >
      <dl className="grid gap-1 text-xs">
        {[
          ["Release", "opendraft 0.2"],
          ["Checks", "4 passed"],
          ["Visibility", "Public registry"],
        ].map(([term, value]) => (
          <div
            key={term}
            className="flex items-center justify-between gap-4 py-1"
          >
            <dt className="text-muted-foreground">{term}</dt>
            <dd className="font-mono text-foreground/80">{value}</dd>
          </div>
        ))}
      </dl>
    </ApprovalCard>
  )
}

export default function ApprovalCardDemo() {
  return (
    <div className="grid w-full items-start gap-6 lg:grid-cols-2">
      <QuestionFlow />
      <ReviewFlow />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/approval-card. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Tool Approval

Permission prompt for a tool call: parameters, allow once or always, deny.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/tool-approval
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { ToolApprovalCode, ToolApproval } from "@/components/agents/tool-approval"
```

## Dependencies

- npm: `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`, `@opendraft/agent-disclosure`, `@opendraft/agent-code`

## Props and types

```ts
export type ToolApprovalStatus =
  | "pending"
  | "approving"
  | "approved"
  | "denied"
  | "running"
  | "complete"
  | "error"

export interface ToolApprovalParameter {
  id: string
  label: ReactNode
  value: ReactNode
}

export interface ToolApprovalCodeProps {
  code: string
  language?: AgentCodeLanguage
  className?: string
}

export interface ToolApprovalProps {
  tool: ReactNode
  title?: ReactNode
  description?: ReactNode
  parameters?: ToolApprovalParameter[]
  status?: ToolApprovalStatus
  open?: boolean
  defaultOpen?: boolean
  onOpenChange?: (open: boolean) => void
  onApprove?: () => void
  onAlwaysAllow?: () => void
  onDeny?: () => void
  className?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"

import {
  ToolApproval,
  ToolApprovalCode,
  type ToolApprovalStatus,
} from "@/components/agents/tool-approval"

/** Runs `fn` after `ms`; pending timers clear on unmount. */
function useTimers() {
  const timers = React.useRef<number[]>([])
  React.useEffect(() => () => timers.current.forEach(window.clearTimeout), [])
  return React.useCallback((fn: () => void, ms: number) => {
    timers.current.push(window.setTimeout(fn, ms))
  }, [])
}

export default function ToolApprovalDemo() {
  const [status, setStatus] = React.useState<ToolApprovalStatus>("pending")
  const [open, setOpen] = React.useState(true)
  const later = useTimers()
  const approve = () => {
    setStatus("approving")
    later(() => setStatus("approved"), 600)
    later(() => setStatus("running"), 1150)
    later(() => setStatus("complete"), 2200)
  }
  return (
    <ToolApproval
      tool="terminal.run"
      title={
        status === "pending" ? "Allow this tool to run?" : "Terminal access"
      }
      description="The agent wants to run the build and registry checks in this workspace."
      status={status}
      open={open}
      onOpenChange={setOpen}
      parameters={[
        {
          id: "command",
          label: "Command",
          value: <ToolApprovalCode code="pnpm build" language="bash" />,
        },
        { id: "directory", label: "Directory", value: "UI-System" },
      ]}
      onApprove={approve}
      onAlwaysAllow={approve}
      onDeny={() => setStatus("denied")}
    />
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/tool-approval. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Image Generation

Image frame with queued, generating, refining and complete states.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/image-generation
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { ImageGeneration } from "@/components/agents/image-generation"
```

## Dependencies

- npm: `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`, `@opendraft/use-hover-capable`

## Props and types

```ts
export type ImageGenerationStatus =
  "queued" | "generating" | "refining" | "complete" | "error"

export interface ImageGenerationProps {
  /** The completed media. Pass an img, Next Image, canvas, video, or custom preview. */
  children?: ReactNode
  status?: ImageGenerationStatus
  /** Accessible description. Defaults to a description derived from prompt. */
  label?: string
  prompt?: string
  resolution?: string
  /** CSS aspect ratio reserved before generated media is available. */
  aspectRatio?: CSSProperties["aspectRatio"]
  size?: "compact" | "fluid"
  /** Lets the active dither cluster follow fine-pointer movement. */
  interactive?: boolean
  statusText?: string
  showStatus?: boolean
  onRetry?: () => void
  className?: string
  mediaClassName?: string
  statusClassName?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"
import { useReducedMotion } from "motion/react"

import {
  ImageGeneration,
  type ImageGenerationStatus,
} from "@/components/agents/image-generation"
import { PixelField } from "@/components/motion/pixel-field"

function GenerationRun({ onReplay }: { onReplay: () => void }) {
  const reduce = useReducedMotion() ?? false
  const [status, setStatus] = React.useState<ImageGenerationStatus>("queued")

  React.useEffect(() => {
    if (reduce) return
    const timers = [
      window.setTimeout(() => setStatus("generating"), 500),
      window.setTimeout(() => setStatus("refining"), 3000),
      window.setTimeout(() => setStatus("complete"), 5200),
    ]
    return () => timers.forEach(window.clearTimeout)
  }, [reduce])

  return (
    <ImageGeneration
      label="Blue pixel study, vertical streaks"
      prompt="a soft blue pixel mosaic with vertical streaks"
      resolution="1024 × 1024"
      status={reduce ? "complete" : status}
      onRetry={onReplay}
    >
      <PixelField
        variant="mosaic"
        cell={24}
        speed={0.4}
        className="size-full"
      />
    </ImageGeneration>
  )
}

export default function ImageGenerationDemo() {
  const [run, setRun] = React.useState(0)
  return <GenerationRun key={run} onReplay={() => setRun((r) => r + 1)} />
}
```

Live docs: https://ui-system-virid.vercel.app/docs/image-generation. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# AI Sidebar

Resource tree for agent workspaces: select, expand, drag to move and rename.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/ai-sidebar
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { AISidebar } from "@/components/agents/ai-sidebar"
```

## Dependencies

- npm: `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`, `@opendraft/popover`, `@opendraft/use-touch-capable`

## Props and types

```ts
export type SidebarResourceKind = "folder" | "project" | "file" | "bookmark"

export interface SidebarResource {
  id: string
  label: string
  kind: SidebarResourceKind
  children?: SidebarResource[]
  disabled?: boolean
}

export type SidebarResourceDropPosition = "before" | "inside" | "after"

export interface SidebarResourceMove {
  itemId: string
  targetId: string | null
  position: SidebarResourceDropPosition
}

/**
 * The moves this row can make right now, the same four the keyboard offers on
 * `Alt+Shift+Arrow`. A pointer drag is the fast path for them; a finger has no
 * drag to give, so the row menu carries them too. Absent keys are moves this
 * row cannot make from where it sits.
 */
export interface SidebarResourceMoveCommands {
  up?: () => void
  down?: () => void
  into?: { label: string; run: () => void }
  out?: () => void
}

export interface SidebarResourceMenuControls {
  close: () => void
  rename: () => void
  moves: SidebarResourceMoveCommands
}

export interface AISidebarProps {
  items?: SidebarResource[]
  defaultItems?: SidebarResource[]
  onItemsChange?: (items: SidebarResource[]) => void
  /** Reject the promise to roll the optimistic move back. */
  onMove?: (move: SidebarResourceMove) => void | Promise<void>
  onMoveError?: (error: unknown, move: SidebarResourceMove) => void
  onRename?: (item: SidebarResource, label: string) => void | Promise<void>
  activeId?: string | null
  defaultActiveId?: string | null
  onActiveChange?: (id: string) => void
  defaultExpandedIds?: string[]
  renderIcon?: (item: SidebarResource) => ReactNode
  renderMenu?: (
    item: SidebarResource,
    controls: SidebarResourceMenuControls
  ) => ReactNode
  ariaLabel?: string
  className?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"
import {
  Clock3,
  GitPullRequest,
  LayoutGrid,
  PanelLeft,
  Plug,
  SquarePen,
} from "lucide-react"

import { AISidebar, type SidebarResource } from "@/components/agents/ai-sidebar"
import {
  AnimatedSidebar,
  AnimatedSidebarContent,
  AnimatedSidebarGroup,
  AnimatedSidebarGroupContent,
  AnimatedSidebarGroupLabel,
  AnimatedSidebarInset,
  AnimatedSidebarMenu,
  AnimatedSidebarMenuButton,
  AnimatedSidebarMenuItem,
  AnimatedSidebarProvider,
  AnimatedSidebarRail,
  AnimatedSidebarTrigger,
} from "@/components/motion/animated-sidebar"
import { Badge } from "@/components/ui/badge"

const RESOURCES: SidebarResource[] = [
  { id: "design-system", label: "Design system", kind: "project" },
  { id: "client-portal", label: "Client portal", kind: "project" },
  {
    id: "platform",
    label: "Platform",
    kind: "project",
    children: [
      { id: "api", label: "API migration", kind: "file" },
      { id: "billing", label: "Billing states", kind: "file" },
      { id: "docs", label: "Read platform docs", kind: "bookmark" },
    ],
  },
  { id: "research", label: "Research lab", kind: "folder" },
  {
    id: "agents",
    label: "Agent workspace",
    kind: "project",
    children: [
      {
        id: "review",
        label: "Review sidebar interaction details",
        kind: "file",
      },
      { id: "release", label: "Prepare release announcement", kind: "file" },
      {
        id: "motion",
        label: "Research motion implementation patterns",
        kind: "bookmark",
      },
    ],
  },
  { id: "notes", label: "Release notes", kind: "file" },
]

const ACTIONS = [
  { label: "New workspace", icon: SquarePen },
  { label: "Pull requests", icon: GitPullRequest },
  { label: "Sites", icon: LayoutGrid },
  { label: "Scheduled", icon: Clock3 },
  { label: "Extensions", icon: Plug },
] as const

function findLabel(items: SidebarResource[], id: string): string | undefined {
  for (const item of items) {
    if (item.id === id) return item.label
    const child = item.children ? findLabel(item.children, id) : undefined
    if (child) return child
  }
}

export default function AISidebarDemo() {
  const [active, setActive] = React.useState("review")
  const [items, setItems] = React.useState(RESOURCES)

  return (
    <AnimatedSidebarProvider
      style={{ "--sidebar-width": "16rem" }}
      className="h-[600px] min-h-0 w-full overflow-hidden border bg-background"
    >
      <AnimatedSidebar
        ariaLabel="Workspace resources"
        collapsible="offcanvas"
        className="min-h-0 w-full"
        panelClassName="h-full bg-surface"
      >
        <AnimatedSidebarContent className="gap-4 overflow-hidden px-2 py-4">
          <AnimatedSidebarGroup className="shrink-0 px-1 py-0">
            <AnimatedSidebarGroupContent>
              <AnimatedSidebarMenu className="gap-0.5">
                {ACTIONS.map(({ label, icon: Icon }) => (
                  <AnimatedSidebarMenuItem key={label}>
                    <AnimatedSidebarMenuButton
                      icon={<Icon className="size-4" />}
                      onSelect={() => {}}
                      className="font-normal text-foreground"
                    >
                      {label}
                    </AnimatedSidebarMenuButton>
                  </AnimatedSidebarMenuItem>
                ))}
              </AnimatedSidebarMenu>
            </AnimatedSidebarGroupContent>
          </AnimatedSidebarGroup>
          <AnimatedSidebarGroup className="min-h-0 flex-1 px-1 py-0">
            <AnimatedSidebarGroupLabel className="mb-1 h-8 px-2 eyebrow">
              Projects
            </AnimatedSidebarGroupLabel>
            <AnimatedSidebarGroupContent className="scrollbar-hide min-h-0 flex-1 overflow-y-auto overscroll-contain">
              <AISidebar
                items={items}
                activeId={active}
                defaultExpandedIds={["platform", "agents"]}
                onActiveChange={setActive}
                onItemsChange={setItems}
                onMove={() => new Promise((r) => window.setTimeout(r, 450))}
              />
            </AnimatedSidebarGroupContent>
          </AnimatedSidebarGroup>
        </AnimatedSidebarContent>
        <AnimatedSidebarRail />
      </AnimatedSidebar>

      <AnimatedSidebarInset className="min-h-0 bg-background">
        <header className="flex h-14 shrink-0 items-center justify-between gap-4 border-b px-5">
          <div className="flex min-w-0 items-center gap-3">
            <AnimatedSidebarTrigger className="-ml-2 size-8 rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-foreground">
              <PanelLeft aria-hidden className="size-4" />
            </AnimatedSidebarTrigger>
            <div className="min-w-0">
              <p className="eyebrow text-muted-foreground">Workspace</p>
              <p className="mt-1 truncate text-sm font-medium">
                Agent workspace
              </p>
            </div>
          </div>
          <Badge variant="outline">Draft</Badge>
        </header>
        <div className="min-h-0 flex-1 overflow-y-auto bg-dots p-6 sm:p-10">
          <div className="max-w-xl">
            <p className="flex items-center gap-2 eyebrow text-muted-foreground">
              <span className="size-2 bg-primary" /> Selected resource
            </p>
            <h3 className="mt-4 heading text-3xl leading-tight sm:text-4xl">
              {findLabel(items, active) ?? active}
            </h3>
            <p className="mt-4 max-w-lg text-sm leading-6 text-muted-foreground">
              Drag rows to move them between projects, rename from the row menu,
              and expand folders around the current selection.
            </p>
            <ul className="mt-8 grid border-t text-sm text-muted-foreground">
              {[
                "Folders only reveal their contents.",
                "Files can be selected, moved or renamed.",
                "Rejected moves return to their previous place.",
              ].map((line) => (
                <li key={line} className="border-b py-3">
                  {line}
                </li>
              ))}
            </ul>
          </div>
        </div>
      </AnimatedSidebarInset>
    </AnimatedSidebarProvider>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/ai-sidebar. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Chat App

Chat shell with a conversation sidebar that folds away when space runs out.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/chat-app
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { ChatApp } from "@/components/agents/chat-app"
```

## Dependencies

- Registry (installed with it): `@opendraft/utils`, `@opendraft/animated-sidebar`

## Props and types

```ts
export interface ChatAppProps extends AnimatedSidebarProviderProps {
  /** Docked sidebar width as a CSS length. Default `17rem`. */
  sidebarWidth?: string
  /**
   * Shell width in px under which the sidebar folds off-canvas. Ignored while
   * `open` is controlled — the consumer owns the state then.
   */
  collapseSidebarBelow?: number
}
```

## Example

```tsx
"use client"

import * as React from "react"
import { AnimatePresence } from "motion/react"
import { MessageSquare, PanelLeft, Sparkles, SquarePen } from "lucide-react"

import { ChatApp } from "@/components/agents/chat-app"
import {
  Message,
  MessageAvatar,
  MessageBubble,
  MessageBubbleContent,
  MessageContent,
  MessageScroller,
  MessageTyping,
} from "@/components/agents/message"
import { PromptInput } from "@/components/agents/prompt-input"
import {
  AnimatedSidebar,
  AnimatedSidebarContent,
  AnimatedSidebarGroup,
  AnimatedSidebarGroupContent,
  AnimatedSidebarGroupLabel,
  AnimatedSidebarInset,
  AnimatedSidebarMenu,
  AnimatedSidebarMenuButton,
  AnimatedSidebarMenuItem,
  AnimatedSidebarRail,
  AnimatedSidebarTrigger,
} from "@/components/motion/animated-sidebar"
import { Badge } from "@/components/ui/badge"

type Turn = { id: string; from: "user" | "assistant"; text: string }

const CONVERSATIONS: {
  id: string
  title: string
  when: string
  turns: Turn[]
}[] = [
  {
    id: "release",
    title: "First release scope",
    when: "Now",
    turns: [
      { id: "1", from: "user", text: "What should the first release include?" },
      {
        id: "2",
        from: "assistant",
        text: "A prompt, a streamed answer and a way to recover from errors.",
      },
    ],
  },
  {
    id: "tokens",
    title: "Blue scale for charts",
    when: "2h",
    turns: [
      { id: "1", from: "user", text: "Which blues should charts use?" },
      {
        id: "2",
        from: "assistant",
        text: "Steps 300, 500 and 700 stay distinct in both themes.",
      },
    ],
  },
  {
    id: "motion",
    title: "Spring tuning notes",
    when: "Yesterday",
    turns: [
      { id: "1", from: "user", text: "Is snappy too fast for dialogs?" },
      {
        id: "2",
        from: "assistant",
        text: "Use smooth for panels; keep snappy for toggles and presses.",
      },
    ],
  },
]

export default function ChatAppDemo() {
  const [activeId, setActiveId] = React.useState(CONVERSATIONS[0].id)
  const [turns, setTurns] = React.useState<Record<string, Turn[]>>(
    Object.fromEntries(CONVERSATIONS.map((c) => [c.id, c.turns]))
  )
  const [thinking, setThinking] = React.useState(false)
  const timer = React.useRef<number | undefined>(undefined)
  const active =
    CONVERSATIONS.find((c) => c.id === activeId) ?? CONVERSATIONS[0]

  React.useEffect(() => () => window.clearTimeout(timer.current), [])

  const send = (text: string) => {
    const id = activeId
    setTurns((all) => ({
      ...all,
      [id]: [...all[id], { id: crypto.randomUUID(), from: "user", text }],
    }))
    setThinking(true)
    timer.current = window.setTimeout(() => {
      setThinking(false)
      setTurns((all) => ({
        ...all,
        [id]: [
          ...all[id],
          {
            id: crypto.randomUUID(),
            from: "assistant",
            text: "Noted. I'll fold that into the plan.",
          },
        ],
      }))
    }, 900)
  }

  return (
    <ChatApp sidebarWidth="15rem" className="h-[560px] rounded-none">
      <AnimatedSidebar
        ariaLabel="Conversations"
        collapsible="offcanvas"
        className="min-h-0 w-full"
        panelClassName="h-full bg-surface"
      >
        <AnimatedSidebarContent className="gap-4 px-2 py-4">
          <AnimatedSidebarGroup className="px-1 py-0">
            <AnimatedSidebarGroupContent>
              <AnimatedSidebarMenu>
                <AnimatedSidebarMenuItem>
                  <AnimatedSidebarMenuButton
                    icon={<SquarePen className="size-4" />}
                    onSelect={() => {}}
                  >
                    New chat
                  </AnimatedSidebarMenuButton>
                </AnimatedSidebarMenuItem>
              </AnimatedSidebarMenu>
            </AnimatedSidebarGroupContent>
          </AnimatedSidebarGroup>
          <AnimatedSidebarGroup className="px-1 py-0">
            <AnimatedSidebarGroupLabel className="mb-1 h-8 px-2 eyebrow">
              Recent
            </AnimatedSidebarGroupLabel>
            <AnimatedSidebarGroupContent>
              <AnimatedSidebarMenu className="gap-0.5">
                {CONVERSATIONS.map((c) => (
                  <AnimatedSidebarMenuItem key={c.id}>
                    <AnimatedSidebarMenuButton
                      icon={<MessageSquare className="size-4" />}
                      isActive={c.id === activeId}
                      badge={
                        <span className="font-mono text-[10px] text-muted-foreground">
                          {c.when}
                        </span>
                      }
                      onSelect={() => setActiveId(c.id)}
                      className="font-normal"
                    >
                      {c.title}
                    </AnimatedSidebarMenuButton>
                  </AnimatedSidebarMenuItem>
                ))}
              </AnimatedSidebarMenu>
            </AnimatedSidebarGroupContent>
          </AnimatedSidebarGroup>
        </AnimatedSidebarContent>
        <AnimatedSidebarRail />
      </AnimatedSidebar>

      <AnimatedSidebarInset className="min-h-0 bg-background">
        <header className="flex h-14 shrink-0 items-center gap-3 border-b px-4">
          <AnimatedSidebarTrigger className="size-8 rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-foreground">
            <PanelLeft aria-hidden className="size-4" />
          </AnimatedSidebarTrigger>
          <p className="min-w-0 truncate heading text-lg">{active.title}</p>
          <Badge variant="brand" className="ml-auto">
            Agent 5.6
          </Badge>
        </header>
        <MessageScroller
          className="min-h-0 flex-1"
          contentClassName="flex flex-col gap-5 p-4"
        >
          <AnimatePresence initial={false}>
            {turns[activeId].map((turn) => (
              <Message
                key={`${activeId}-${turn.id}`}
                from={turn.from}
                animateIn
              >
                <MessageAvatar
                  className={
                    turn.from === "user" ? "bg-brand/15 text-brand" : undefined
                  }
                >
                  {turn.from === "user" ? "NM" : <Sparkles />}
                </MessageAvatar>
                <MessageContent>
                  <MessageBubble
                    variant={turn.from === "user" ? "solid" : "ghost"}
                    animateIn
                  >
                    <MessageBubbleContent>{turn.text}</MessageBubbleContent>
                  </MessageBubble>
                </MessageContent>
              </Message>
            ))}
            {thinking ? (
              <Message key="thinking" from="assistant" animateIn>
                <MessageAvatar>
                  <Sparkles />
                </MessageAvatar>
                <MessageContent>
                  <MessageBubble>
                    <MessageBubbleContent>
                      <MessageTyping />
                    </MessageBubbleContent>
                  </MessageBubble>
                </MessageContent>
              </Message>
            ) : null}
          </AnimatePresence>
        </MessageScroller>
        <div className="border-t p-3">
          <PromptInput
            minRows={1}
            loading={thinking}
            onSubmit={send}
            placeholder="Send a message…"
          />
        </div>
      </AnimatedSidebarInset>
    </ChatApp>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/chat-app. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Question Card

One question at a time in a sliding stack with an odometer step counter and auto-advance on single choice. Data shape: Survey-shaped: skip and free text are always shown and there is no scoring. Shows sample content (an ice cream shop) until you pass your own data through its props.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/question-card
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { QuestionCard } from "@/components/agents/question-card"
```

## Dependencies

- npm: `lucide-react`, `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/glide-menu`, `@opendraft/motion`

## Props and types

```ts
export type QuestionCardQuestion = {
  q: string
  type: "radio" | "check"
  options: string[]
}

export type QuestionCardLabels = {
  skip: string
  continue: string
  send: string
  customPlaceholder: string
  sentMessage: string
}

export type QuestionCardAnswers = Record<number, number[]>

export interface QuestionCardProps {
  questions?: QuestionCardQuestion[]
  labels?: Partial<QuestionCardLabels>
  onSubmitted?: (answers: QuestionCardAnswers) => void
  onAnswerChange?: (questionIndex: number, answer: number[]) => void
  /** Show a "Start over" action after sending. */
  resettable?: boolean
  className?: string
}
```

## Example

```tsx
"use client"

import { QuestionCard } from "@/components/agents/question-card"

export default function QuestionCardDemo() {
  return (
    <div className="flex w-full justify-center">
      <QuestionCard
        questions={[
          {
            q: "How many flavors should we launch?",
            type: "radio",
            options: ["Three (core line)", "Five (full case)", "Just one hero"],
          },
          {
            q: "Which mix-ins should we stock?",
            type: "check",
            options: ["Chocolate chips", "Waffle bits", "Sprinkles"],
          },
        ]}
        onSubmitted={(answers) => console.log(answers)}
      />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/question-card. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Chat Panel

Chat panel with context tabs, a scripted reply sequence that starts on send, and a composer. Shows sample content (an ice cream shop) until you pass your own data through its props.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/chat-panel
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { ChatPanel } from "@/components/agents/chat-panel"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
/** One scripted agent reply in the thread. */
export type ChatPanelMessage = {
  label: string
  sub: string
  time: string
  body: string
}

export type ChatPanelLabels = {
  /** The pre-filled prompt shown in the first user bubble. */
  initialPrompt: string
  /** Composer input placeholder. */
  placeholder: string
}

export interface ChatPanelProps {
  /** Scripted agent replies revealed in sequence after the user sends. */
  messages?: ChatPanelMessage[]
  /** Header chips (tabs) for switching context. */
  suggestions?: string[]
  labels?: Partial<ChatPanelLabels>
  /** Fired with the trimmed prompt text when the user sends. */
  onSend?: (text: string) => void
  className?: string
}
```

## Example

```tsx
"use client"

import { ChatPanel } from "@/components/agents/chat-panel"

export default function ChatPanelDemo() {
  return (
    <div className="flex w-full justify-center">
      <ChatPanel
        suggestions={["Flavors", "Suppliers"]}
        onSend={(text) => console.log("sent:", text)}
      />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/chat-panel. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Recommendation Card

Recommendation with a confidence meter, an alternatives drawer that swaps the pick, and a confirm action.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/recommendation-card
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { RecommendationCard } from "@/components/agents/recommendation-card"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`

## Props and types

```ts
export type RecommendationTone = "success" | "warning" | "muted"

export type RecommendationOption = {
  key: string
  body: ReactNode
  short: string
  /** Confidence bars lit, 0–3. */
  signal: number
  tone: RecommendationTone
  label: string
  cta: string
  ctaVariant: "default" | "ink" | "outline"
}

export type RecommendationLabels = {
  title: string
  alternatives: string
  otherOptions: string
  accepted: string
}

export interface RecommendationCardProps {
  options?: RecommendationOption[]
  labels?: Partial<RecommendationLabels>
  /** Fired with the option key when its action is pressed. */
  onAccept?: (key: string) => void
  className?: string
}
```

## Example

```tsx
"use client"

import { RecommendationCard } from "@/components/agents/recommendation-card"

export default function RecommendationCardDemo() {
  return (
    <div className="flex w-full justify-center">
      <RecommendationCard onAccept={(key) => console.log("accepted:", key)} />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/recommendation-card. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Context Cards

Retrieved context chunks that stagger in, then reveal their source file chips. Shows sample content (an ice cream shop) until you pass your own data through its props.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/context-cards
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { ContextCards } from "@/components/agents/context-cards"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
export type ContextChunkTone = "destructive" | "success" | "brand" | "muted"

export type ContextChunk = {
  title: string
  chars: string
  body: string
  source: string
  /** Short file-type badge, e.g. "PDF". */
  badge: string
  tone: ContextChunkTone
  href?: string
}

export type ContextCardsLabels = {
  header: string
  count: string
}

export interface ContextCardsProps {
  chunks?: ContextChunk[]
  labels?: Partial<ContextCardsLabels>
  className?: string
}
```

## Example

```tsx
"use client"

import { ContextCards } from "@/components/agents/context-cards"

export default function ContextCardsDemo() {
  return (
    <div className="flex w-full justify-center">
      <ContextCards labels={{ header: "Retrieved context", count: "2" }} />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/context-cards. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Prompt Bar

A composer with @ sources, / commands, a model picker, dictation and attachments, plus a self-running demo. Shows sample content (an ice cream shop) until you pass your own data through its props.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/prompt-bar
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { PromptBar } from "@/components/agents/prompt-bar"
```

## Dependencies

- npm: `lucide-react`, `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/glide-menu`, `@opendraft/motion`

## Props and types

```ts
export type PromptBarVariant = "Rounded" | "Pill"

/** An entry in the @ menu. `attach` adds a file chip; `connect` shows a Connect toggle. */
export type PromptBarSource = {
  key: string
  name: string
  description: string
  icon: ReactNode
  attach?: boolean
  connect?: boolean
}

/** An entry in the / menu. `name` includes the leading slash. */
export type PromptBarCommand = {
  key: string
  name: string
  description: string
}

/** A model in the picker. Selecting a `flagship` model plays a one-shot sweep. */
export type PromptBarModel = {
  key: string
  name: string
  tag?: string
  flagship?: boolean
}

export type PromptBarProps = {
  variant?: PromptBarVariant
  /** The self-running walkthrough; turn off when embedding in a real surface. */
  demo?: boolean
  /** Hero sizing: a multi-line input with controls on their own row. */
  tall?: boolean
  placeholder?: string
  /** Entries in the @ menu. */
  sources?: PromptBarSource[]
  /** Entries in the / menu. */
  commands?: PromptBarCommand[]
  /** Models in the picker; the second one starts selected (the first if only one). */
  models?: PromptBarModel[]
  onSend?: (text: string) => void
  className?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"
import { toast } from "sonner"

import {
  PromptBar,
  type PromptBarVariant,
} from "@/components/agents/prompt-bar"
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"

const VARIANTS: PromptBarVariant[] = ["Rounded", "Pill"]

export default function PromptBarDemo() {
  const [variant, setVariant] = React.useState<PromptBarVariant>("Rounded")

  return (
    <div className="flex w-full flex-col items-center gap-2">
      <Tabs
        value={variant}
        onValueChange={(v) => setVariant(v as PromptBarVariant)}
      >
        <TabsList>
          {VARIANTS.map((name) => (
            <TabsTrigger key={name} value={name}>
              {name}
            </TabsTrigger>
          ))}
        </TabsList>
      </Tabs>
      {/* Remount on switch so the self-running demo restarts. */}
      <PromptBar
        key={variant}
        variant={variant}
        onSend={(text) => toast("Prompt sent", { description: text })}
      />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/prompt-bar. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Selection Actions

A contextual AI bar under selected text that animates its width between modes and streams in a rewrite. Data shape: An AI text-rewrite bar over selected text, not a bulk-action bar for table rows. For bulk actions use `table` with `selectable` plus Buttons.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/selection-actions
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { SelectionActions } from "@/components/agents/selection-actions"
```

## Dependencies

- npm: `lucide-react`, `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/shimmer-text`, `@opendraft/motion`

## Props and types

```ts
/** The passage: lead-in text, the selected `original`, and the streamed `rewrite`. */
export type SelectionText = {
  lead: string
  original: string
  rewrite: string
}

/** A single AI action offered in the bar. Omit `action` for a no-op button
 * (e.g. Explain); `busyLabel` is the gerund shown while it runs. */
export type SelectionAction = {
  id: string
  icon: ReactNode
  action?: string
  busyLabel?: string
}

/** The action set: `primary` are always visible; `more` reveal on expand. */
export type SelectionActionSet = {
  primary: SelectionAction[]
  more: SelectionAction[]
}

/** Prominent copy strings. */
export type SelectionActionsLabels = {
  keep: string
  discard: string
  placeholder: string
}

export type SelectionActionsProps = {
  /** The passage shown above the bar. */
  text?: Partial<SelectionText>
  /** The AI actions offered in the bar. */
  actions?: SelectionActionSet
  /** Prominent copy strings. */
  labels?: Partial<SelectionActionsLabels>
  /** Called with the action name whenever an edit is run. */
  onAction?: (action: string) => void
  className?: string
}
```

## Example

```tsx
"use client"

import { toast } from "sonner"

import { SelectionActions } from "@/components/agents/selection-actions"

export default function SelectionActionsDemo() {
  return (
    <div className="flex w-full justify-center">
      <SelectionActions onAction={(action) => toast(`${action}…`)} />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/selection-actions. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Pixel Loader

A 3×3 pixel-grid loader with a shimmering status label and a live elapsed timer, in four motion variants.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/pixel-loader
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { PixelLoader } from "@/components/agents/pixel-loader"
```

## Dependencies

- Registry (installed with it): `@opendraft/utils`, `@opendraft/shimmer-text`

## Props and types

```ts
export type PixelLoaderVariant = "drive" | "dots" | "orbit" | "surfer"

export interface PixelLoaderProps {
  /** Status text next to the grid. Defaults to "Churning" ("Subway surfing" for surfer). */
  label?: string
  variant?: PixelLoaderVariant
  /** Video shown in the surfer variant's card. Without it the card shows the loader. */
  videoSrc?: string
  className?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"

import {
  PixelLoader,
  type PixelLoaderVariant,
} from "@/components/agents/pixel-loader"
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"

const VARIANTS: PixelLoaderVariant[] = ["drive", "dots", "orbit", "surfer"]

export default function PixelLoaderDemo() {
  const [variant, setVariant] = React.useState<PixelLoaderVariant>("drive")

  return (
    <div className="flex w-full flex-col items-center gap-8">
      <Tabs
        value={variant}
        onValueChange={(v) => setVariant(v as PixelLoaderVariant)}
      >
        <TabsList>
          {VARIANTS.map((v) => (
            <TabsTrigger key={v} value={v} className="capitalize">
              {v}
            </TabsTrigger>
          ))}
        </TabsList>
      </Tabs>
      <div className="flex min-h-40 items-start">
        {/* surfer takes a videoSrc; without one it shows the loader card */}
        <PixelLoader key={variant} variant={variant} />
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/pixel-loader. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Thinking Trace

An expandable agent trace that shimmers while working, then settles. Steps, reasoning, search and coding variants. Shows sample content (an ice cream shop) until you pass your own data through its props.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/thinking-trace
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { ThinkingTrace } from "@/components/agents/thinking-trace"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/shimmer-text`

## Props and types

```ts
export type ThinkingTraceVariant = "steps" | "reasoning" | "search" | "coding"

export type ThinkingTraceRow = {
  primary: string
  secondary?: string
  mono?: boolean
  add?: number
  del?: number
  href?: string
}

export interface ThinkingTraceProps {
  variant?: ThinkingTraceVariant
  /** Fires once, when the trace stops working. */
  onSettled?: () => void
  /** Override the built-in trace rows. */
  rows?: ThinkingTraceRow[]
  /** Label while working. */
  active?: string
  /** Label once settled. */
  done?: string
  /** Search query line (search variant). */
  query?: string
  /** Trailing "+N more" line (search variant). */
  more?: string
  /** Override the header glyph (defaults to the sparkle). */
  icon?: ReactNode
  className?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"

import {
  ThinkingTrace,
  type ThinkingTraceVariant,
} from "@/components/agents/thinking-trace"
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"

const VARIANTS: ThinkingTraceVariant[] = [
  "steps",
  "reasoning",
  "search",
  "coding",
]

export default function ThinkingTraceDemo() {
  const [variant, setVariant] = React.useState<ThinkingTraceVariant>("steps")

  return (
    <div className="flex w-full flex-col items-center gap-8">
      <Tabs
        value={variant}
        onValueChange={(v) => setVariant(v as ThinkingTraceVariant)}
      >
        <TabsList>
          {VARIANTS.map((v) => (
            <TabsTrigger key={v} value={v} className="capitalize">
              {v}
            </TabsTrigger>
          ))}
        </TabsList>
      </Tabs>
      {/* keyed so each switch replays the trace */}
      <ThinkingTrace key={variant} variant={variant} />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/thinking-trace. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Streaming Answer

An answer that streams in word by word with an inline citation, then shows actions, sources and follow-ups. Shows sample content (an ice cream shop) until you pass your own data through its props.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/streaming-answer
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { StreamingAnswer } from "@/components/agents/streaming-answer"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
/** One streamed word, or a `cite` placeholder that renders an inline source chip. */
export type StreamingToken = { text: string; cite?: boolean }

/** One cited source, shown in the inline chip, the avatar stack and the list. */
export type StreamingSource = {
  name: string
  domain: string
  href: string
  /** Favicon URL. When absent, `icon` (or the first letter) is shown. */
  image?: string
  icon?: ReactNode
}

export type StreamingAnswerAction = "copy" | "retry" | "like" | "dislike"

export type StreamingAnswerLabels = {
  /** Label on the collapsed sources toggle. */
  sources: string
  /** Heading above the follow-up prompts. */
  followUps: string
}

export interface StreamingAnswerProps {
  /** The streamed tokens; `cite` tokens render an inline source chip. */
  content?: StreamingToken[]
  /** Cited sources shown in the chip, avatar stack and expanded list. */
  sources?: StreamingSource[]
  /** Follow-up prompt suggestions shown once the stream completes. */
  followUps?: string[]
  labels?: Partial<StreamingAnswerLabels>
  /** Restart the stream after a hold; turn off when embedding in a real thread. */
  loop?: boolean
  /** Fill the parent width instead of the fixed measure. */
  fill?: boolean
  onDone?: () => void
  /** Fired when a follow-up prompt is chosen. */
  onFollowUp?: (text: string, index: number) => void
  /** Fired when an action icon is pressed. */
  onAction?: (action: StreamingAnswerAction) => void
  className?: string
}
```

## Example

```tsx
"use client"

import { StreamingAnswer } from "@/components/agents/streaming-answer"

export default function StreamingAnswerDemo() {
  return (
    <div className="flex w-full justify-center">
      <StreamingAnswer />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/streaming-answer. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Task Rows

Task rows with progress rings, status pills and expandable details, run through a failed, retry, done sequence. Data shape: A payment-shaped animated demo (label, amount; fixed failed, retry and done states), not an interactive task list.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/task-rows
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { TaskRows } from "@/components/agents/task-rows"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
export type TaskRowsVariant = "capsules" | "list"

/** One detail line shown when a task row is expanded. */
export type TaskDetail = { label: string; meta: string }

/**
 * A single task row.
 *  - "done"     → check badge + completed pill (static)
 *  - "running"  → active spinner showing `step`, no pill (static)
 *  - "sequence" → animation-driven: pending spinner → failed → completed
 */
export type TaskRow = {
  key: string
  label: string
  amount: string
  status: "done" | "running" | "sequence"
  step?: number
  details: TaskDetail[]
}

export type TaskRowsLabels = {
  completed: string
  failed: string
}

export interface TaskRowsProps {
  variant?: TaskRowsVariant
  rows?: TaskRow[]
  labels?: Partial<TaskRowsLabels>
  className?: string
  onToggleRow?: (key: string, open: boolean) => void
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { TaskRows, type TaskRowsVariant } from "@/components/agents/task-rows"
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"

export default function TaskRowsDemo() {
  const [variant, setVariant] = React.useState<TaskRowsVariant>("capsules")

  return (
    <div className="flex w-full flex-col items-center gap-8">
      <Tabs
        value={variant}
        onValueChange={(v) => setVariant(v as TaskRowsVariant)}
      >
        <TabsList>
          <TabsTrigger value="capsules">Capsules</TabsTrigger>
          <TabsTrigger value="list">List</TabsTrigger>
        </TabsList>
      </Tabs>
      {/* keyed so each switch replays the status run */}
      <TaskRows key={variant} variant={variant} />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/task-rows. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Tool Chips

An agent run as compact tool-call rows with inline chips, then file-diff chips that preview their diff on hover. Shows sample content (an ice cream shop) until you pass your own data through its props.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/tool-chips
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { ToolChips } from "@/components/agents/tool-chips"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
export type ToolStepIcon = "think" | "write" | "run" | "read"

export type ToolDetailLine = { text: string; tone?: "add" }

export type ToolStep = {
  icon: ToolStepIcon
  label: string
  chip: string
  mono: boolean
  detailMono: boolean
  detail: ToolDetailLine[]
}

export type ToolDiff = { file: string; add: number; del: number }

export type ToolDiffLine = { text: string; tone: "add" | "del" | "ctx" }

export type ToolChipsLabels = {
  header: string
  more: string
}

export interface ToolChipsProps {
  steps?: ToolStep[]
  diffs?: ToolDiff[]
  diffLines?: Record<string, ToolDiffLine[]>
  labels?: Partial<ToolChipsLabels>
  className?: string
  onOpenChange?: (open: boolean) => void
  onToggleRow?: (label: string, open: boolean) => void
  /** Fired when the trailing "+N more" chip is pressed. */
  onMore?: () => void
}
```

## Example

```tsx
"use client"

import * as React from "react"
import { RotateCw } from "lucide-react"

import { ToolChips } from "@/components/agents/tool-chips"
import { Button } from "@/components/ui/button"

export default function ToolChipsDemo() {
  const [run, setRun] = React.useState(0)

  return (
    <div className="flex w-full flex-col items-center gap-6">
      <ToolChips key={run} />
      <Button variant="ghost" size="xs" onClick={() => setRun((r) => r + 1)}>
        <RotateCw />
        Replay
      </Button>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/tool-chips. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Agent Screen

Live agent-screen card that expands to a full-screen viewer with Teach-a-task recording. Shows sample content (an ice cream shop) until you pass your own data through its props.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/agent-screen
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { AgentScreen } from "@/components/agents/agent-screen"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`

## Props and types

```ts
export type AgentScreenVariant = "Default" | "Loading"

export type AgentScreenProps = {
  /** Shown under the card and in the viewer's title bar. */
  agentName?: string
  /** Image or video URL of the agent's screen. Defaults to a faux window. */
  streamSrc?: string
  /** "Loading" shows the connecting state and disables opening. */
  variant?: AgentScreenVariant
  className?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"

import {
  AgentScreen,
  type AgentScreenVariant,
} from "@/components/agents/agent-screen"
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"

export default function AgentScreenDemo() {
  const [variant, setVariant] = React.useState<AgentScreenVariant>("Default")
  return (
    <div className="flex w-full flex-col items-center gap-4">
      <Tabs
        value={variant}
        onValueChange={(v) => setVariant(v as AgentScreenVariant)}
      >
        <TabsList>
          <TabsTrigger value="Default">Default</TabsTrigger>
          <TabsTrigger value="Loading">Loading</TabsTrigger>
        </TabsList>
      </Tabs>
      <AgentScreen key={variant} agentName="Scout" variant={variant} />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/agent-screen. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Code Panel

Light editor panel with a line-numbered Code view and a unified Diff view with word-level highlights. Shows sample content (an ice cream shop) until you pass your own data through its props.

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/code-panel
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { CodePanel } from "@/components/agents/code-panel"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
/** A single run of code within a diff row; `change` tints it as an add/del. */
export type CodePiece = { text: string; change?: "add" | "del" }

/** One row of a unified diff: old/new line numbers, its kind, and its pieces. */
export type DiffRow = {
  old: number | null
  cur: number | null
  type: "ctx" | "add" | "del"
  pieces: CodePiece[]
}

/** Prominent copy strings on the panel. */
export type CodePanelLabels = { copy: string; copied: string }

export type CodePanelVariant = "Code" | "Diff"

export type CodePanelProps = {
  /** Which view to render — "Code" (line-numbered listing) or "Diff". */
  variant?: CodePanelVariant
  /** The lines shown in the Code view. */
  lines?: string[]
  /** Raw text placed on the clipboard by Copy. Defaults to `lines` joined. */
  code?: string
  /** The unified-diff rows shown in the Diff view. */
  diff?: DiffRow[]
  /** Filename shown in the header. */
  filename?: string
  /** Prominent copy strings. */
  labels?: Partial<CodePanelLabels>
  /** Called with the copied text after a successful copy. */
  onCopy?: (text: string) => void
  className?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"

import {
  CodePanel,
  type CodePanelVariant,
} from "@/components/agents/code-panel"
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"

export default function CodePanelDemo() {
  const [view, setView] = React.useState<CodePanelVariant>("Code")
  return (
    <div className="flex w-full flex-col items-center gap-4">
      <Tabs value={view} onValueChange={(v) => setView(v as CodePanelVariant)}>
        <TabsList>
          <TabsTrigger value="Code">Code</TabsTrigger>
          <TabsTrigger value="Diff">Diff</TabsTrigger>
        </TabsList>
      </Tabs>
      <CodePanel variant={view} />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/code-panel. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Waveform

Static, clickable and scrubbable waveform bars drawn from normalized data, plus a scrolling variant and an accessible scrubber. Adapted from ElevenLabs UI (MIT).

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/waveform
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Waveform, ScrollingWaveform, AudioScrubber } from "@/components/agents/waveform"
```

## Dependencies

- npm: `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`

## Props and types

```ts
/**
 * A theme token name (`"foreground"`, `"primary"`, `"brand"`, `"muted-foreground"`...)
 * or any CSS color. Token names are read from the CSS variables at draw time,
 * so the canvas follows light, dark and `.dark` sections.
 */
type WaveformColor = string

type WaveformBaseProps = Omit<React.ComponentProps<"div">, "children"> & {
  /** Width of one bar in px. */
  barWidth?: number
  /** Minimum bar height in px. */
  barHeight?: number
  /** Gap between bars in px. */
  barGap?: number
  /** Bar corner radius in px. */
  barRadius?: number
  /** Theme token name or CSS color for the bars. */
  barColor?: WaveformColor
  /** Fade the left and right edges out. */
  fadeEdges?: boolean
  /** Width of the edge fade in px. */
  fadeWidth?: number
  /** Container height. Numbers are px. */
  height?: number | string
}

type WaveformProps = WaveformBaseProps & {
  /** Normalized bar values, 0 to 1. Resampled to fit the available width. */
  data?: number[]
  /** Playback position from 0 to 1. Bars before it use `playedColor`. */
  progress?: number
  /** Theme token name or CSS color for bars already played. */
  playedColor?: WaveformColor
  /** Fires when a bar is clicked. Pointer only; use `AudioScrubber` for keyboard seeking. */
  onBarClick?: (index: number, value: number) => void
  /** Accessible description of the audio. */
  "aria-label"?: string
}

type ScrollingWaveformProps = WaveformBaseProps & {
  /** Scroll speed in px per second. */
  speed?: number
  /** Normalized values (0 to 1) fed in from the right, looping. Omit for an ambient pattern. */
  data?: number[]
  /** Pause scrolling while keeping the current frame. */
  active?: boolean
  /** Accessible description of the audio. */
  "aria-label"?: string
}

type AudioScrubberProps = Omit<WaveformProps, "progress" | "onBarClick"> & {
  /** Current playback time, in the same unit as `duration`. */
  currentTime?: number
  /** Total length. */
  duration?: number
  /** Called while scrubbing and on keyboard seeks. */
  onSeek?: (time: number) => void
  /** Amount one arrow key press seeks. Defaults to 5% of `duration`. */
  keyboardStep?: number
  /** Formats the time for assistive tech. */
  formatTime?: (time: number) => string
  /** Show a thin playhead line. */
  showPlayhead?: boolean
}
```

## Example

```tsx
"use client"

import * as React from "react"
import { Pause, Play } from "lucide-react"

import {
  AudioScrubber,
  ScrollingWaveform,
  Waveform,
} from "@/components/agents/waveform"
import { Button } from "@/components/ui/button"

const DURATION = 42

/** A deterministic, speech-like envelope so server and client render the same bars. */
const SAMPLES = Array.from({ length: 160 }, (_, i) => {
  const phrase = 0.5 + 0.5 * Math.sin(i * 0.11)
  const syllable = 0.5 + 0.5 * Math.sin(i * 0.9 + Math.sin(i * 0.31) * 2)
  return Math.max(0.06, Math.min(1, 0.12 + phrase * 0.45 + syllable * 0.35))
})

const formatTime = (time: number) => {
  const total = Math.floor(time)
  return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, "0")}`
}

export default function WaveformDemo() {
  const [time, setTime] = React.useState(12)
  const [playing, setPlaying] = React.useState(false)
  const [picked, setPicked] = React.useState<string | null>(null)

  // A simulated playback clock keeps the demo silent and offline.
  React.useEffect(() => {
    if (!playing) return
    const timer = window.setInterval(() => {
      setTime((current) => {
        if (current >= DURATION) {
          setPlaying(false)
          return DURATION
        }
        return Math.min(DURATION, current + 0.25)
      })
    }, 250)
    return () => window.clearInterval(timer)
  }, [playing])

  return (
    <div className="grid w-full max-w-2xl gap-10">
      <section className="grid gap-3">
        <p className="eyebrow text-muted-foreground">Scrubbable</p>
        <div className="flex items-center gap-3">
          <Button
            variant="outline"
            size="icon"
            aria-label={playing ? "Pause" : "Play"}
            onClick={() => {
              if (time >= DURATION) setTime(0)
              setPlaying((value) => !value)
            }}
          >
            {playing ? <Pause /> : <Play />}
          </Button>
          <AudioScrubber
            data={SAMPLES}
            currentTime={time}
            duration={DURATION}
            onSeek={setTime}
            aria-label="Seek recording"
            height={56}
          />
          <span className="w-20 shrink-0 text-right font-mono text-xs text-muted-foreground tabular-nums">
            {formatTime(time)} / {formatTime(DURATION)}
          </span>
        </div>
      </section>

      <section className="grid gap-3">
        <p className="eyebrow text-muted-foreground">Static, clickable bars</p>
        <Waveform
          data={SAMPLES}
          height={96}
          barColor="brand"
          fadeEdges
          aria-label="Recording overview"
          onBarClick={(index, value) =>
            setPicked(`Bar ${index + 1} at ${Math.round(value * 100)}%`)
          }
        />
        <p className="min-h-5 text-sm text-muted-foreground" aria-live="polite">
          {picked ?? "Click a bar to read its level."}
        </p>
      </section>

      <section className="grid gap-3">
        <p className="eyebrow text-muted-foreground">Scrolling</p>
        <ScrollingWaveform
          height={72}
          barWidth={3}
          barGap={2}
          speed={30}
          barColor="muted-foreground"
          aria-label="Incoming audio level"
        />
      </section>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/waveform. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Live Waveform

Microphone-driven canvas waveform in static or scrolling mode with a processing animation; handles denied or missing microphones. Adapted from ElevenLabs UI (MIT).

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/live-waveform
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { LiveWaveform } from "@/components/agents/live-waveform"
```

## Dependencies

- npm: `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`

## Props and types

```ts
type LiveWaveformMode = "static" | "scrolling"

type LiveWaveformProps = Omit<
  React.ComponentProps<"div">,
  "children" | "onError"
> & {
  /** Capture the microphone and draw it. When false the tracks are stopped and the bars settle to idle. */
  active?: boolean
  /** Show a synthetic "thinking" wave while the microphone is off. */
  processing?: boolean
  /** Specific input device from `enumerateDevices()`. */
  deviceId?: string
  /** `static` mirrors the spectrum around the centre; `scrolling` scrolls recent loudness right to left. */
  mode?: LiveWaveformMode
  /** Width of one bar in px. */
  barWidth?: number
  /** Gap between bars in px. */
  barGap?: number
  /** Minimum bar height in px. */
  barHeight?: number
  /** Bar corner radius in px. */
  barRadius?: number
  /**
   * Theme token name (`"foreground"`, `"primary"`, `"brand"`, `"muted-foreground"`...)
   * or any CSS color. Tokens are read from the CSS variables on every frame.
   */
  barColor?: string
  /** Fade the left and right edges out. */
  fadeEdges?: boolean
  /** Width of the edge fade in px. */
  fadeWidth?: number
  /** Container height. Numbers are px. */
  height?: number | string
  /** Multiplier applied to the measured level. */
  sensitivity?: number
  /** AnalyserNode smoothing, 0 to 1. */
  smoothingTimeConstant?: number
  /** AnalyserNode FFT size (power of two). */
  fftSize?: number
  /** Number of samples kept in `scrolling` mode. */
  historySize?: number
  /** Minimum milliseconds between audio samples. */
  updateRate?: number
  /** Called when the microphone is unsupported, blocked or fails. */
  onError?: (error: Error) => void
  /** Called with the live stream once the microphone is open. */
  onStreamReady?: (stream: MediaStream) => void
  /** Called after the stream has been stopped. */
  onStreamEnd?: () => void
  /** Accessible name. Defaults to a description of the current state. */
  "aria-label"?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"
import { Loader2, Mic, MicOff } from "lucide-react"

import {
  LiveWaveform,
  type LiveWaveformMode,
} from "@/components/agents/live-waveform"
import { Button } from "@/components/ui/button"
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"

export default function LiveWaveformDemo() {
  const [active, setActive] = React.useState(false)
  const [processing, setProcessing] = React.useState(false)
  const [mode, setMode] = React.useState<LiveWaveformMode>("static")
  const [problem, setProblem] = React.useState<string | null>(null)

  function toggleMic() {
    setProblem(null)
    setProcessing(false)
    setActive((value) => !value)
  }

  return (
    <div className="grid w-full max-w-xl gap-5">
      <div className="rounded-lg border bg-card p-4">
        <LiveWaveform
          active={active}
          processing={processing}
          mode={mode}
          height={80}
          barWidth={3}
          barGap={2}
          barColor="foreground"
          onError={(error) => {
            setActive(false)
            setProblem(
              error.name === "NotAllowedError"
                ? "Microphone access was blocked. Allow it in your browser settings to try again."
                : "No microphone is available in this browser."
            )
          }}
        />
      </div>

      <div className="flex flex-wrap items-center gap-3">
        <Button
          variant={active ? "default" : "outline"}
          size="sm"
          onClick={toggleMic}
        >
          {active ? <MicOff /> : <Mic />}
          {active ? "Stop microphone" : "Start microphone"}
        </Button>
        <Button
          variant="outline"
          size="sm"
          disabled={active}
          aria-pressed={processing}
          onClick={() => setProcessing((value) => !value)}
        >
          <Loader2 />
          Processing
        </Button>
        <Tabs
          value={mode}
          onValueChange={(v) => setMode(v as LiveWaveformMode)}
        >
          <TabsList>
            <TabsTrigger value="static">Static</TabsTrigger>
            <TabsTrigger value="scrolling">Scrolling</TabsTrigger>
          </TabsList>
        </Tabs>
      </div>

      <p className="min-h-5 text-sm text-muted-foreground" aria-live="polite">
        {problem ??
          (active
            ? "Listening. Nothing is recorded or uploaded."
            : "Start the microphone to see your voice.")}
      </p>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/live-waveform. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Bar Visualizer

Volume or frequency bars that light up by agent state (connecting, listening, thinking, speaking). Adapted from ElevenLabs UI (MIT).

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/bar-visualizer
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { BarVisualizer } from "@/components/agents/bar-visualizer"
```

## Dependencies

- npm: `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`

## Props and types

```ts
/** What the voice agent is doing. Drives the highlight pattern. */
type BarVisualizerState =
  "connecting" | "initializing" | "listening" | "speaking" | "thinking"

type MultibandVolumeOptions = {
  /** Number of bands to produce. */
  bands?: number
  /** First FFT bin of the analysed slice. */
  loPass?: number
  /** Last FFT bin (exclusive) of the analysed slice. */
  hiPass?: number
  /** Minimum milliseconds between updates. */
  updateInterval?: number
  /** AnalyserNode FFT size (power of two). */
  fftSize?: number
  /** AnalyserNode smoothing, 0 to 1. */
  smoothingTimeConstant?: number
}

type BarVisualizerProps = Omit<React.ComponentProps<"div">, "children"> & {
  /** Agent state. Controls which bars light up. */
  state?: BarVisualizerState
  /** Number of bars. Ignored when `levels` is provided. */
  barCount?: number
  /** Per-bar levels, 0 to 1. Takes priority over `mediaStream` and `volume`. */
  levels?: number[]
  /** A single overall level, 0 to 1, shaped into a centred bell across the bars. */
  volume?: number
  /** Optional caller-owned stream to analyse. It is never stopped here. */
  mediaStream?: MediaStream | null
  /** Smallest bar height, as a percentage of the container. */
  minHeight?: number
  /** Largest bar height, as a percentage of the container. */
  maxHeight?: number
  /** Align bars to the vertical centre instead of the bottom. */
  centerAlign?: boolean
  /** Accessible name. Defaults to the current state. */
  "aria-label"?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"
import { Mic, MicOff } from "lucide-react"

import {
  BarVisualizer,
  type BarVisualizerState,
} from "@/components/agents/bar-visualizer"
import { Button } from "@/components/ui/button"
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"

const STATES: BarVisualizerState[] = [
  "connecting",
  "listening",
  "thinking",
  "speaking",
]
const BARS = 15

export default function BarVisualizerDemo() {
  const [state, setState] = React.useState<BarVisualizerState>("speaking")
  const [stream, setStream] = React.useState<MediaStream | null>(null)
  const [problem, setProblem] = React.useState<string | null>(null)
  const [levels, setLevels] = React.useState<number[]>(() =>
    Array.from({ length: BARS }, () => 0.2)
  )
  const streamRef = React.useRef<MediaStream | null>(null)

  // Simulated levels while the microphone is off.
  React.useEffect(() => {
    if (stream) return
    const moving = state === "speaking" || state === "listening"
    const timer = window.setInterval(() => {
      const t = performance.now() / 1000
      setLevels(
        Array.from({ length: BARS }, (_, i) =>
          moving
            ? Math.max(
                0.1,
                0.45 +
                  Math.sin(t * 3 + i * 0.6) * 0.3 +
                  Math.sin(t * 7.3 + i) * 0.12
              )
            : 0.2
        )
      )
    }, 80)
    return () => window.clearInterval(timer)
  }, [state, stream])

  const stopMic = React.useCallback(() => {
    streamRef.current?.getTracks().forEach((track) => track.stop())
    streamRef.current = null
    setStream(null)
  }, [])

  React.useEffect(() => stopMic, [stopMic])

  async function toggleMic() {
    if (stream) return stopMic()
    setProblem(null)
    try {
      const next = await navigator.mediaDevices.getUserMedia({ audio: true })
      streamRef.current = next
      setStream(next)
      setState("listening")
    } catch {
      setProblem("Microphone unavailable. Showing simulated levels instead.")
    }
  }

  return (
    <div className="grid w-full max-w-xl gap-5">
      <BarVisualizer
        state={state}
        barCount={BARS}
        levels={stream ? undefined : levels}
        mediaStream={stream}
      />
      <div className="flex flex-wrap items-center gap-3">
        <Tabs
          value={state}
          onValueChange={(v) => setState(v as BarVisualizerState)}
        >
          <TabsList className="h-auto max-w-full flex-wrap justify-start">
            {STATES.map((name) => (
              <TabsTrigger key={name} value={name} className="capitalize">
                {name}
              </TabsTrigger>
            ))}
          </TabsList>
        </Tabs>
        <Button
          variant={stream ? "default" : "outline"}
          size="sm"
          onClick={toggleMic}
        >
          {stream ? <MicOff /> : <Mic />}
          {stream ? "Stop mic" : "Use mic"}
        </Button>
      </div>
      <p className="min-h-5 text-sm text-muted-foreground" aria-live="polite">
        {problem ?? (stream ? "Reading your microphone." : "Simulated levels.")}
      </p>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/bar-visualizer. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Audio Player

Audio provider with play and pause, previous and next, seek, speed menu, volume, playlist and error state. Takes a source or a list of tracks. Adapted from ElevenLabs UI (MIT).

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/audio-player
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { AudioPlayer, AudioPlayerProvider, AudioPlayerButton, AudioPlayerSkip, AudioPlayerProgress, AudioPlayerTime, AudioPlayerDuration, AudioPlayerSpeed, AudioPlayerVolume, AudioPlayerPlaylist } from "@/components/agents/audio-player"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/dropdown-menu`, `@opendraft/slider`

## Props and types

```ts
type AudioPlayerTrack<TData = unknown> = {
  id: string | number
  src: string
  title?: string
  subtitle?: string
  /** Anything the host app wants to carry along with the track. */
  data?: TData
}

type AudioPlayerApi<TData = unknown> = {
  ref: React.RefObject<HTMLAudioElement | null>
  tracks: AudioPlayerTrack<TData>[]
  activeTrack: AudioPlayerTrack<TData> | null
  /** Seconds, or undefined until metadata has loaded. */
  duration: number | undefined
  isPlaying: boolean
  isBuffering: boolean
  hasError: boolean
  playbackRate: number
  /** 0 to 1. */
  volume: number
  muted: boolean
  hasNext: boolean
  hasPrevious: boolean
  isTrackActive: (id: string | number) => boolean
  /** Resume, or switch to the given track (by object or id) and play it. */
  play: (track?: AudioPlayerTrack<TData> | string | number) => void
  pause: () => void
  toggle: () => void
  seek: (time: number) => void
  next: () => void
  previous: () => void
  setPlaybackRate: (rate: number) => void
  setVolume: (volume: number) => void
  setMuted: (muted: boolean) => void
}

type AudioPlayerProviderProps<TData = unknown> = {
  /** A single audio source. Ignored when `tracks` is given. */
  src?: string
  /** A playlist. The first track is active until another is played. */
  tracks?: AudioPlayerTrack<TData>[]
  /** Play the next track when one ends. Defaults to true. */
  autoAdvance?: boolean
  children?: React.ReactNode
}

type AudioPlayerButtonProps<TData = unknown> = Omit<
  React.ComponentProps<typeof Button>,
  "children"
> & {
  /** Play this track instead of the active one. Shows its own play state. */
  track?: AudioPlayerTrack<TData>
}

type AudioPlayerSpeedProps = Omit<
  React.ComponentProps<typeof Button>,
  "children"
> & {
  /** Selectable rates. */
  speeds?: readonly number[]
}

type AudioPlayerProps<TData = unknown> = Omit<
  React.ComponentProps<"div">,
  "children"
> &
  Pick<AudioPlayerProviderProps<TData>, "src" | "tracks" | "autoAdvance"> & {
    /** Heading for a single `src`. Tracks use their own `title`. */
    title?: string
    /** Selectable playback rates. */
    speeds?: readonly number[]
    /** Show the volume control. Defaults to true. */
    showVolume?: boolean
    /** List the tracks under the controls when there is more than one. Defaults to true. */
    showPlaylist?: boolean
  }

function AudioPlayer(props: AudioPlayerProps<TData>)

function AudioPlayerProvider(props: AudioPlayerProviderProps<TData>)

function AudioPlayerButton(props: AudioPlayerButtonProps<TData>)

function AudioPlayerSkip(props: Omit<React.ComponentProps<typeof Button>, "children"> & {
  direction: "previous" | "next"
})

function AudioPlayerProgress(props: Omit<
  React.ComponentProps<typeof Slider>,
  "min" | "max" | "value" | "defaultValue" | "onValueChange" | "aria-label"
>)

function AudioPlayerTime(props: React.ComponentProps<"span">)

function AudioPlayerDuration(props: React.ComponentProps<"span">)

function AudioPlayerVolume(props: Omit<React.ComponentProps<"div">, "children">)

function AudioPlayerPlaylist(props: Omit<React.ComponentProps<"ul">, "children">)
```

## Example

```tsx
"use client"

import * as React from "react"

import {
  AudioPlayer,
  type AudioPlayerTrack,
} from "@/components/agents/audio-player"

const RATE = 8000

/** Builds a mono 16-bit PCM WAV from a sample function and returns a blob URL. */
function makeWavUrl(seconds: number, sample: (t: number) => number) {
  const count = Math.floor(seconds * RATE)
  const view = new DataView(new ArrayBuffer(44 + count * 2))
  const text = (offset: number, value: string) => {
    for (let i = 0; i < value.length; i++) {
      view.setUint8(offset + i, value.charCodeAt(i))
    }
  }
  text(0, "RIFF")
  view.setUint32(4, 36 + count * 2, true)
  text(8, "WAVEfmt ")
  view.setUint32(16, 16, true)
  view.setUint16(20, 1, true)
  view.setUint16(22, 1, true)
  view.setUint32(24, RATE, true)
  view.setUint32(28, RATE * 2, true)
  view.setUint16(32, 2, true)
  view.setUint16(34, 16, true)
  text(36, "data")
  view.setUint32(40, count * 2, true)
  for (let i = 0; i < count; i++) {
    const value = Math.max(-1, Math.min(1, sample(i / RATE)))
    view.setInt16(44 + i * 2, value * 0x7fff, true)
  }
  return URL.createObjectURL(new Blob([view.buffer], { type: "audio/wav" }))
}

/** A repeating melody: one note per beat with a soft attack and decay. */
function melody(notes: number[], beat: number) {
  return (t: number) => {
    const index = Math.floor(t / beat)
    const local = t - index * beat
    const envelope = Math.min(local / 0.02, 1) * Math.exp(-local * 4)
    const hz = notes[index % notes.length]
    return 0.25 * envelope * Math.sin(2 * Math.PI * hz * t)
  }
}

const SOURCES = [
  {
    id: "arpeggio",
    title: "Morning arpeggio",
    seconds: 12,
    beat: 0.4,
    notes: [262, 330, 392, 523],
  },
  {
    id: "pulse",
    title: "Slow pulse",
    seconds: 16,
    beat: 0.8,
    notes: [196, 196, 247, 220],
  },
  {
    id: "scale",
    title: "Rising scale",
    seconds: 9,
    beat: 0.3,
    notes: [262, 294, 330, 349, 392, 440, 494, 523],
  },
]

let cached: AudioPlayerTrack[] | undefined

// Built once on the client, so the server render and hydration both see no tracks first.
function getTracks() {
  cached ??= SOURCES.map(({ id, title, seconds, beat, notes }) => ({
    id,
    title,
    subtitle: `${seconds}s`,
    src: makeWavUrl(seconds, melody(notes, beat)),
  }))
  return cached
}

const subscribe = () => () => {}
const getServerTracks = () => undefined

export default function AudioPlayerDemo() {
  const tracks = React.useSyncExternalStore(
    subscribe,
    getTracks,
    getServerTracks
  )

  return (
    <div className="w-full max-w-md">
      <AudioPlayer tracks={tracks ?? []} />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/audio-player. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Scrub Bar

Seekable progress bar with time labels on a native range input, so pointer, touch and keyboard all work. Adapted from ElevenLabs UI (MIT).

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/scrub-bar
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { ScrubBar, ScrubBarContainer, ScrubBarTrack, ScrubBarProgress, ScrubBarThumb, ScrubBarTimeLabel } from "@/components/agents/scrub-bar"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
type ScrubBarContainerProps = React.ComponentProps<"div"> & {
  /** Total length in seconds. The bar is disabled while this is 0. */
  duration: number
  /** Current position in seconds. */
  value: number
  /** Called with the new position (seconds) while the user drags or presses a key. */
  onScrub?: (time: number) => void
  /** Called when a pointer drag begins. */
  onScrubStart?: () => void
  /** Called when a pointer drag ends. */
  onScrubEnd?: () => void
}

type ScrubBarTrackProps = Omit<React.ComponentProps<"div">, "onChange"> & {
  /** Accessible name of the seek control. */
  label?: string
  /** Keyboard and drag granularity in seconds. */
  step?: number
  /** Formats the spoken value of the slider. Defaults to `m:ss`. */
  formatValueText?: (time: number) => string
}

type ScrubBarTimeLabelProps = React.ComponentProps<"span"> & {
  /** Seconds to display. */
  time: number
  format?: (time: number) => string
}

type ScrubBarProps = Omit<ScrubBarContainerProps, "children"> & {
  /** Show elapsed and remaining time under the track. Defaults to true. */
  showTimeLabels?: boolean
  /** Show remaining time (`-0:12`) instead of total duration on the right. */
  showRemaining?: boolean
  /** Accessible name of the seek control. */
  label?: string
  step?: number
}

function ScrubBarProgress(props: React.ComponentProps<"div">)

function ScrubBarThumb(props: React.ComponentProps<"div">)
```

## Example

```tsx
"use client"

import * as React from "react"
import { Pause, Play } from "lucide-react"

import { Button } from "@/components/ui/button"
import { ScrubBar } from "@/components/agents/scrub-bar"

const DURATION = 184

export default function ScrubBarDemo() {
  const [time, setTime] = React.useState(42)
  const [playing, setPlaying] = React.useState(false)
  const [scrubbing, setScrubbing] = React.useState(false)

  const running = playing && time < DURATION

  // Simulated playback: advance a tenth of a second at a time.
  React.useEffect(() => {
    if (!running || scrubbing) return
    const id = window.setInterval(() => {
      setTime((t) => Math.min(t + 0.1, DURATION))
    }, 100)
    return () => window.clearInterval(id)
  }, [running, scrubbing])

  return (
    <div className="flex w-full max-w-md items-center gap-3 rounded-lg border bg-card p-4">
      <Button
        size="icon"
        aria-label={running ? "Pause" : "Play"}
        onClick={() => {
          if (time >= DURATION) setTime(0)
          setPlaying(!running)
        }}
      >
        {running ? <Pause /> : <Play />}
      </Button>
      <ScrubBar
        duration={DURATION}
        value={time}
        showRemaining
        label="Seek recording"
        onScrub={setTime}
        onScrubStart={() => setScrubbing(true)}
        onScrubEnd={() => setScrubbing(false)}
      />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/scrub-bar. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Transcript Viewer

Time-aligned transcript that highlights the current word and seeks when a word is clicked, from plain word timings. Adapted from ElevenLabs UI (MIT).

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/transcript-viewer
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { TranscriptViewer, TranscriptViewerContainer, TranscriptViewerWords, TranscriptViewerWord, TranscriptViewerPlayPauseButton, TranscriptViewerScrubBar } from "@/components/agents/transcript-viewer"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/scrub-bar`

## Props and types

```ts
/** One spoken word with its timing in seconds. Words must be sorted by `start`. */
type TranscriptWord = {
  text: string
  start: number
  end: number
}

type TranscriptWordStatus = "spoken" | "current" | "unspoken"

type UseTranscriptViewerProps = {
  words: TranscriptWord[]
  onPlay?: () => void
  onPause?: () => void
  onTimeUpdate?: (time: number) => void
  onEnded?: () => void
  onDurationChange?: (duration: number) => void
}

type UseTranscriptViewerResult = {
  words: TranscriptWord[]
  /**
   * Index of the word being spoken. Between words it stays on the last word
   * that started. -1 before the first word, `words.length` once playback has
   * passed the end of the last word.
   */
  currentIndex: number
  currentWord: TranscriptWord | null
  currentTime: number
  /** Seconds. Taken from the audio element, or from the last word until metadata loads. */
  duration: number
  isPlaying: boolean
  isScrubbing: boolean
  play: () => void
  pause: () => void
  seekToTime: (time: number) => void
  seekToWord: (word: number | TranscriptWord) => void
  startScrubbing: () => void
  endScrubbing: () => void
  /** Spread onto the `<audio>` element. Carries the ref and all event handlers. */
  audioProps: React.ComponentProps<"audio">
}

type TranscriptViewerContainerProps = Omit<
  React.ComponentProps<"div">,
  "children"
> &
  Omit<UseTranscriptViewerProps, "words"> & {
    /** URL of the audio the words are aligned to. Any playable URL, including blob URLs. */
    src: string
    /** Word timings in seconds, sorted by `start`. */
    words: TranscriptWord[]
    children?: React.ReactNode
  }

type TranscriptViewerWordProps = Omit<
  React.ComponentProps<"button">,
  "children"
> & {
  word: TranscriptWord
  status: TranscriptWordStatus
  children?: React.ReactNode
}

type TranscriptViewerWordsProps = Omit<
  React.ComponentProps<"div">,
  "children"
> & {
  /** Replace how a word renders. Receives its status. */
  renderWord?: (props: {
    word: TranscriptWord
    status: TranscriptWordStatus
  }) => React.ReactNode
  /** Class names applied to every word button. */
  wordClassName?: string
}

type PlayPauseChildren = (state: { isPlaying: boolean }) => React.ReactNode

type TranscriptViewerPlayPauseButtonProps = Omit<
  React.ComponentProps<typeof Button>,
  "children"
> & {
  /** Custom content, or a function of the playing state. Defaults to a play/pause icon. */
  children?: React.ReactNode | PlayPauseChildren
}

type TranscriptViewerScrubBarProps = Omit<
  React.ComponentProps<typeof ScrubBarContainer>,
  "duration" | "value" | "onScrub" | "onScrubStart" | "onScrubEnd" | "children"
> & {
  /** Show elapsed and remaining time. Defaults to true. */
  showTimeLabels?: boolean
}

type TranscriptViewerProps = Omit<TranscriptViewerContainerProps, "children">
```

## Example

```tsx
"use client"

import * as React from "react"

import {
  TranscriptViewer,
  type TranscriptWord,
} from "@/components/agents/transcript-viewer"

const RATE = 8000

const SCRIPT =
  "Welcome back to the weekly review. Three things shipped this week: the new onboarding flow, faster search, and a cleaner settings page. Next week we focus on reliability, so expect fewer features and more polish."

/** Word timings: about 0.32s per word plus a pause after each sentence. */
const WORDS: TranscriptWord[] = (() => {
  let cursor = 0.3
  return SCRIPT.split(" ").map((text) => {
    const start = cursor
    const end = start + 0.18 + Math.min(text.length, 9) * 0.02
    cursor = end + (/[.:]$/.test(text) ? 0.5 : 0.1)
    return { text, start, end }
  })
})()

/** Builds a mono 16-bit PCM WAV with one soft tone per word and returns a blob URL. */
function makeWavUrl(words: TranscriptWord[]) {
  const seconds = words[words.length - 1].end + 0.4
  const count = Math.floor(seconds * RATE)
  const view = new DataView(new ArrayBuffer(44 + count * 2))
  const text = (offset: number, value: string) => {
    for (let i = 0; i < value.length; i++) {
      view.setUint8(offset + i, value.charCodeAt(i))
    }
  }
  text(0, "RIFF")
  view.setUint32(4, 36 + count * 2, true)
  text(8, "WAVEfmt ")
  view.setUint32(16, 16, true)
  view.setUint16(20, 1, true)
  view.setUint16(22, 1, true)
  view.setUint32(24, RATE, true)
  view.setUint32(28, RATE * 2, true)
  view.setUint16(32, 2, true)
  view.setUint16(34, 16, true)
  text(36, "data")
  view.setUint32(40, count * 2, true)
  let w = 0
  for (let i = 0; i < count; i++) {
    const t = i / RATE
    while (w < words.length - 1 && t >= words[w].end) w++
    const word = words[w]
    let value = 0
    if (t >= word.start && t < word.end) {
      const local = t - word.start
      const envelope =
        Math.min(local / 0.015, 1) * Math.min((word.end - t) / 0.04, 1)
      const hz = 180 + (w % 5) * 40
      value = 0.18 * envelope * Math.sin(2 * Math.PI * hz * t)
    }
    view.setInt16(44 + i * 2, value * 0x7fff, true)
  }
  return URL.createObjectURL(new Blob([view.buffer], { type: "audio/wav" }))
}

let cached: string | undefined

// Built once on the client; the server render and hydration both start without audio.
function getSrc() {
  cached ??= makeWavUrl(WORDS)
  return cached
}

const subscribe = () => () => {}
const getServerSrc = () => undefined

export default function TranscriptViewerDemo() {
  const src = React.useSyncExternalStore(subscribe, getSrc, getServerSrc)

  return (
    <div className="w-full max-w-xl">
      <TranscriptViewer src={src ?? ""} words={WORDS} />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/transcript-viewer. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Mic Selector

Microphone picker in a dropdown with a mute toggle and a live level preview; handles permission denied and no devices. Adapted from ElevenLabs UI (MIT).

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/mic-selector
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { MicSelector } from "@/components/agents/mic-selector"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/dropdown-menu`, `@opendraft/live-waveform`

## Props and types

```ts
type AudioDevice = {
  deviceId: string
  label: string
  groupId: string
}

type AudioDevicesStatus = "loading" | "ready" | "denied" | "unsupported"

type MicSelectorProps = Omit<
  React.ComponentProps<typeof Button>,
  "value" | "onChange" | "children"
> & {
  /** Selected device id (controlled). Defaults to the first device. */
  value?: string
  /** Called when the user picks a device. */
  onValueChange?: (deviceId: string) => void
  /** Muted state (controlled). */
  muted?: boolean
  /** Called when the user toggles mute. */
  onMutedChange?: (muted: boolean) => void
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { MicSelector } from "@/components/agents/mic-selector"

export default function MicSelectorDemo() {
  const [deviceId, setDeviceId] = React.useState<string>()
  const [muted, setMuted] = React.useState(false)

  return (
    <div className="flex flex-col items-center gap-3">
      <MicSelector
        value={deviceId}
        onValueChange={setDeviceId}
        muted={muted}
        onMutedChange={setMuted}
      />
      <p className="eyebrow text-muted-foreground">
        {muted ? "Muted" : "Open the menu to preview your input level"}
      </p>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/mic-selector. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Voice Button

Toggle or push-to-talk record button with idle, recording, processing, success and error states, a shortcut hint and a compact live waveform. Adapted from ElevenLabs UI (MIT).

Category: AI Agents

## Install

```bash
npx shadcn@latest add @opendraft/voice-button
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { VoiceButton } from "@/components/agents/voice-button"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/kbd`, `@opendraft/live-waveform`

## Props and types

```ts
type VoiceButtonState =
  "idle" | "recording" | "processing" | "success" | "error"

type VoiceButtonProps = Omit<
  React.ComponentProps<typeof Button>,
  "children" | "onClick"
> & {
  /** Current state. Owned by the caller, who does the actual recording work. */
  state?: VoiceButtonState
  /** `toggle`: click to start and stop. `push-to-talk`: record while held. */
  mode?: "toggle" | "push-to-talk"
  /** Fires when the user asks to start recording. */
  onRecordStart?: () => void
  /** Fires when the user asks to stop recording. */
  onRecordEnd?: () => void
  /** Text label shown before the waveform. */
  label?: React.ReactNode
  /** Shortcut hint rendered with `Kbd`, e.g. "Space". */
  shortcut?: string
  /** `KeyboardEvent.code` that triggers the button globally, e.g. "Space". */
  hotkey?: string
  /** Icon for the `icon` size when idle. */
  icon?: React.ReactNode
  /** How long success and error feedback stays visible, in ms. */
  feedbackDuration?: number
  /** Extra classes for the waveform well. */
  waveformClassName?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"

import {
  VoiceButton,
  type VoiceButtonState,
} from "@/components/agents/voice-button"

export default function VoiceButtonDemo() {
  const [state, setState] = React.useState<VoiceButtonState>("idle")
  const timers = React.useRef<number[]>([])

  React.useEffect(() => {
    const pending = timers.current
    return () => pending.forEach((id) => window.clearTimeout(id))
  }, [])

  function stop() {
    setState("processing")
    timers.current.push(
      window.setTimeout(() => setState("success"), 1200),
      window.setTimeout(() => setState("idle"), 3000)
    )
  }

  return (
    <div className="flex flex-col items-center gap-6">
      <VoiceButton
        state={state}
        label="Dictate"
        shortcut="Space"
        hotkey="Space"
        onRecordStart={() => setState("recording")}
        onRecordEnd={stop}
      />
      <VoiceButton
        state={state}
        mode="push-to-talk"
        label="Hold to talk"
        onRecordStart={() => setState("recording")}
        onRecordEnd={stop}
      />
      <VoiceButton
        state={state}
        size="icon"
        aria-label="Record"
        onRecordStart={() => setState("recording")}
        onRecordEnd={stop}
      />
      <p className="eyebrow text-muted-foreground">State: {state}</p>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/voice-button. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Filter Table

Task table filtered by status chips; rows collapse in place and status pills are tinted by meaning. Data shape: Rows are task rows (task, date, status todo, progress or done, owner), not a general data table. For other data use `table`. Shows sample content (an ice cream shop) until you pass your own data through its props.

Category: Data & Workflows

## Install

```bash
npx shadcn@latest add @opendraft/filter-table
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { FilterTable } from "@/components/agents/filter-table"
```

## Dependencies

- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
export type FilterTableStatus = "todo" | "progress" | "done"

export type FilterTableRow = {
  task: string
  date: string
  status: FilterTableStatus
  owner: string
}

export type FilterTableLabels = {
  all: string
  status: Record<FilterTableStatus, string>
  columns: { task: string; date: string; status: string; owner: string }
}

export interface FilterTableProps {
  rows?: FilterTableRow[]
  labels?: Partial<FilterTableLabels>
  className?: string
}
```

## Example

```tsx
"use client"

import { FilterTable } from "@/components/agents/filter-table"

export default function FilterTableDemo() {
  return (
    <div className="flex w-full justify-center">
      <FilterTable />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/filter-table. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Flowchart

Workflow canvas with draggable Trigger and If/Else cards joined by a live bezier connector. Data shape: An editable trigger and if/else canvas, not a pipeline or status graph. Shows sample content (an ice cream shop) until you pass your own data through its props.

Category: Data & Workflows

## Install

```bash
npx shadcn@latest add @opendraft/flowchart
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Flowchart } from "@/components/agents/flowchart"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/glide-menu`

## Props and types

```ts
export type FlowchartTone = "brand" | "warning"

export type FlowchartStep = {
  id: string
  row: number
  /** 0–1 horizontal center of the node on the canvas. */
  x: number
  w: number
  kind?: { label: string; tone: FlowchartTone }
  tone?: FlowchartTone
  title?: string
  caption?: string
  /** Renders the if/else chip rows instead of a title + caption. */
  condition?: boolean
}

export type FlowchartEdge = { from: string; to: string }

export type FlowchartOption = { name: string; tag?: string }

export type FlowchartProps = {
  steps?: FlowchartStep[]
  edges?: FlowchartEdge[]
  /** Options for the property chips in the condition card. */
  properties?: FlowchartOption[]
  /** Options for the first value chip. */
  values?: FlowchartOption[]
  /** Options for the second value chip. */
  secondaryValues?: FlowchartOption[]
  /** Source label shown in the condition rows. */
  source?: string
  onSelectStep?: (id: string | null) => void
  className?: string
}
```

## Example

```tsx
"use client"

import { Flowchart } from "@/components/agents/flowchart"

export default function FlowchartDemo() {
  return (
    <div className="mx-auto w-full max-w-lg">
      <Flowchart />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/flowchart. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Insight Cards

Insights carousel with comparison, anomaly and allocation mini-charts and a blurred page crossfade. Data shape: An AI insight carousel. Only its exported `InsightChart` (a multi-line chart with one threshold line) is reusable on its own. Shows sample content (an ice cream shop) until you pass your own data through its props.

Category: Data & Workflows

## Install

```bash
npx shadcn@latest add @opendraft/insight-cards
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { InsightCards, InsightChart } from "@/components/agents/insight-cards"
```

## Dependencies

- npm: `lucide-react`, `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/motion`

## Props and types

```ts
export type InsightTone =
  "brand" | "blue" | "warning" | "destructive" | "success"

type ChartLine = { id: string; values: number[]; tone: InsightTone }

type TooltipRow = { label: string; value: string; tone: InsightTone }

/** content shape for the return-comparison card's two plotted series */
export type CompareSeries = {
  name: string
  values: number[]
  sub: string
  /** Text tone for the delta. */
  tone: "destructive" | "success"
  /** Line, legend dot and tooltip color. */
  color: InsightTone
}

/** content shape for the anomaly card's two toggled metric series */
export type AnomalyData = {
  spend: number[]
  usage: number[]
  /** Dashed threshold per metric. */
  threshold: { spend: number; usage: number }
}

/** content shape for one allocation segment */
export type AllocationSegment = {
  name: string
  label: string
  pct: number
  amount: string
  /** Bar and legend dot fill class, e.g. `bg-primary`. */
  cls: string
  /** Label text class, e.g. `text-brand`. */
  tone: string
}

/** content shape for one insight page in the carousel */
export type InsightPage = {
  key: string
  prose: React.ReactNode
  Card: React.ComponentType
  pill: string
}

export type InsightCardsLabels = {
  /** carousel heading shown before the page count */
  title: string
  previous: string
  next: string
}

export type InsightCardsProps = {
  pages?: InsightPage[]
  labels?: Partial<InsightCardsLabels>
  /** Called with the follow-up prompt when its pill is pressed. */
  onAsk?: (pill: string, page: InsightPage) => void
  onPageChange?: (index: number) => void
  className?: string
}

function InsightChart(props: {
  lines: ChartLine[]
  fill?: boolean
  grid?: boolean
  threshold?: number
  index: number | null
  onIndexChange: (index: number | null) => void
  tooltip: (index: number) => TooltipRow[]
  label: string
  className?: string
})
```

## Example

```tsx
"use client"

import { InsightCards } from "@/components/agents/insight-cards"

export default function InsightCardsDemo() {
  return (
    <div className="flex w-full justify-center">
      <InsightCards />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/insight-cards. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Fine-tune Card

Compact inspector with scrub-able number fields, a sliding segmented control and a Type menu. Shows sample content (an ice cream shop) until you pass your own data through its props.

Category: Data & Workflows

## Install

```bash
npx shadcn@latest add @opendraft/fine-tune-card
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { FineTuneCard } from "@/components/agents/fine-tune-card"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/glide-menu`, `@opendraft/shimmer-text`

## Props and types

```ts
/** A single scrub-able number property. `value` is the initial/default value. */
export type FineTuneField = {
  key: string
  label: string
  value: number
  min: number
  max: number
  step?: number
  suffix?: string
}

/** Prominent copy strings on the card. */
export type FineTuneCardLabels = {
  title: string
  layout: string
  type: string
  placeholder: string
  adjust: string
  edited: string
}

/** The editable state emitted by `onChange`. */
export type FineTuneState = {
  segment: number
  values: Record<string, number>
  type: string
}

export type FineTuneCardProps = {
  /** The scrub-able properties shown in the layout grid (rendered in pairs). */
  fields?: FineTuneField[]
  /** Options offered in the Type menu. */
  options?: string[]
  /** Prominent copy strings. */
  labels?: Partial<FineTuneCardLabels>
  /** Called with the full editable state whenever the user edits it. */
  onChange?: (state: FineTuneState) => void
  className?: string
}
```

## Example

```tsx
import { FineTuneCard } from "@/components/agents/fine-tune-card"

export default function FineTuneCardDemo() {
  return (
    <div className="flex w-full justify-center">
      <FineTuneCard />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/fine-tune-card. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Records Table

AI spreadsheet grid with property popovers, row-by-row calculation, resizable sticky columns and sorting. Data shape: An AI spreadsheet demo with fixed columns (name, tags, last, strength, website). For general records use `table`. Shows sample content (an ice cream shop) until you pass your own data through its props.

Category: Data & Workflows

## Install

```bash
npx shadcn@latest add @opendraft/records-table
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { RecordsTable } from "@/components/agents/records-table"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/glide-menu`, `@opendraft/checkbox`, `@opendraft/switch`

## Props and types

```ts
export type RecordStrength = "strong" | "weak" | "veryweak" | "none"

export type RecordRow = {
  id: string
  name: string
  tags: string[]
  last: string
  strength: RecordStrength
  website?: string
}

export type RecordsTableProps = {
  rows?: RecordRow[]
  /** Stretch to the parent's height instead of capping the scroller. */
  fill?: boolean
  className?: string
}
```

## Example

```tsx
import { RecordsTable } from "@/components/agents/records-table"

export default function RecordsTableDemo() {
  return (
    <div className="w-full max-w-5xl">
      <RecordsTable />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/records-table. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Diff Table

A proposed table edit that plays once; click each changed row to keep or drop it before applying. Data shape: A demo of an AI edit to a people table (id, dept, email). Not a general diff viewer; use `file-diff` for text changes. Shows sample content (an ice cream shop) until you pass your own data through its props.

Category: Data & Workflows

## Install

```bash
npx shadcn@latest add @opendraft/diff-table
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { DiffTable } from "@/components/agents/diff-table"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`

## Props and types

```ts
export type DiffRow = {
  key: string
  id: string
  dept: string
  email: string
  removed: boolean
}

export type DiffAddedRow = Omit<DiffRow, "removed">

export type DiffTableProps = {
  rows?: DiffRow[]
  /** The row the edit proposes to add; it slides in once the diff settles. */
  added?: DiffAddedRow
  title?: string
  columns?: [string, string, string]
  /** Called with the keys of the edits that were kept when "Apply" is pressed. */
  onApply?: (keys: string[]) => void
  className?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"
import { RotateCcw } from "lucide-react"

import { DiffTable } from "@/components/agents/diff-table"
import { Button } from "@/components/ui/button"

export default function DiffTableDemo() {
  const [run, setRun] = React.useState(0)

  return (
    <div className="flex w-full flex-col items-center gap-3">
      <DiffTable key={run} />
      <Button variant="ghost" size="xs" onClick={() => setRun((r) => r + 1)}>
        <RotateCcw />
        Replay
      </Button>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/diff-table. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Accordion

Stacked sections that expand with a spring-driven height animation.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/accordion
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

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

## Dependencies

- npm: `radix-ui`, `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`

## Props and types

```ts
function Accordion(props: React.ComponentProps<typeof AccordionPrimitive.Root>)

function AccordionItem(props: React.ComponentProps<typeof AccordionPrimitive.Item>)

function AccordionTrigger(props: React.ComponentProps<typeof AccordionPrimitive.Trigger>)

function AccordionContent(props: React.ComponentProps<typeof AccordionPrimitive.Content>)
```

## Example

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

export default function AccordionDemo() {
  return (
    <Accordion
      type="single"
      collapsible
      defaultValue="a"
      className="w-full max-w-md"
    >
      <AccordionItem value="a">
        <AccordionTrigger>Can I use this in any project?</AccordionTrigger>
        <AccordionContent>
          Yes. Components install as source, so they work in any React project
          with Tailwind.
        </AccordionContent>
      </AccordionItem>
      <AccordionItem value="b">
        <AccordionTrigger>
          Does it work with shadcn components?
        </AccordionTrigger>
        <AccordionContent>
          The token names match shadcn&apos;s, so stock shadcn components pick
          up this theme.
        </AccordionContent>
      </AccordionItem>
      <AccordionItem value="c">
        <AccordionTrigger>What about reduced motion?</AccordionTrigger>
        <AccordionContent>
          Motion respects the OS setting everywhere.
        </AccordionContent>
      </AccordionItem>
    </Accordion>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/accordion. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Sidebar

Docked, icon rail or off-canvas sidebar with a mobile sheet, menus and sub-menus.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/animated-sidebar
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { AnimatedSidebarProvider, AnimatedSidebarMenuSubButton, AnimatedSidebarMenuButton, AnimatedSidebar, AnimatedSidebarTrigger, AnimatedSidebarClose, AnimatedSidebarRail, AnimatedSidebarInset, AnimatedSidebarHeader, AnimatedSidebarContent, AnimatedSidebarFooter, AnimatedSidebarGroup, AnimatedSidebarGroupLabel, AnimatedSidebarGroupContent, AnimatedSidebarMenu, AnimatedSidebarMenuItem, AnimatedSidebarMenuSub, AnimatedSidebarMenuSubItem } from "@/components/motion/animated-sidebar"
```

Files added to the project:

- `components/motion/animated-sidebar.tsx`
- `components/motion/shared-layout-bg.tsx`

## Dependencies

- npm: `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`

## Props and types

```ts
type SidebarSide = "left" | "right"

type SidebarVariant = "sidebar" | "floating" | "inset"

type SidebarCollapsible = "offcanvas" | "icon" | "none"

type SidebarProviderStyle = CSSProperties & {
  "--sidebar-width"?: string
  "--sidebar-width-icon"?: string
  "--sidebar-width-mobile"?: string
}

export interface AnimatedSidebarProviderProps extends HTMLAttributes<HTMLDivElement> {
  open?: boolean
  defaultOpen?: boolean
  onOpenChange?: (open: boolean) => void
  openMobile?: boolean
  defaultOpenMobile?: boolean
  onOpenMobileChange?: (open: boolean) => void
  style?: SidebarProviderStyle
}

export interface AnimatedSidebarProps extends Omit<
  HTMLMotionProps<"aside">,
  "children"
> {
  children?: ReactNode
  side?: SidebarSide
  variant?: SidebarVariant
  collapsible?: SidebarCollapsible
  ariaLabel?: string
  panelClassName?: string
}

export type AnimatedSidebarTriggerProps =
  ButtonHTMLAttributes<HTMLButtonElement>

export type AnimatedSidebarCloseProps = ButtonHTMLAttributes<HTMLButtonElement>

export type AnimatedSidebarRailProps = ButtonHTMLAttributes<HTMLButtonElement>

export type AnimatedSidebarInsetProps = HTMLMotionProps<"main">

export interface AnimatedSidebarMenuSubProps extends Omit<
  HTMLMotionProps<"ul">,
  "children"
> {
  open: boolean
  children?: ReactNode
}

export interface AnimatedSidebarMenuSubButtonProps {
  children: ReactNode
  icon?: ReactNode
  href?: string
  isActive?: boolean
  disabled?: boolean
  closeOnSelect?: boolean
  target?: "_blank" | "_self" | "_parent" | "_top"
  rel?: string
  onSelect?: () => void
  className?: string
}

export interface AnimatedSidebarMenuButtonProps {
  children: ReactNode
  icon?: ReactNode
  badge?: ReactNode
  href?: string
  isActive?: boolean
  ariaExpanded?: boolean
  disabled?: boolean
  closeOnSelect?: boolean
  target?: "_blank" | "_self" | "_parent" | "_top"
  rel?: string
  onSelect?: () => void
  className?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"
import {
  Bot,
  Inbox,
  LayoutGrid,
  PanelLeft,
  Settings,
  Users,
} from "lucide-react"

import {
  AnimatedSidebar,
  AnimatedSidebarContent,
  AnimatedSidebarGroup,
  AnimatedSidebarGroupContent,
  AnimatedSidebarGroupLabel,
  AnimatedSidebarInset,
  AnimatedSidebarMenu,
  AnimatedSidebarMenuButton,
  AnimatedSidebarMenuItem,
  AnimatedSidebarProvider,
  AnimatedSidebarRail,
  AnimatedSidebarTrigger,
} from "@/components/motion/animated-sidebar"

const NAV = [
  { id: "inbox", label: "Inbox", icon: Inbox, badge: "12" },
  { id: "agents", label: "Agents", icon: Bot },
  { id: "projects", label: "Projects", icon: LayoutGrid },
  { id: "team", label: "Team", icon: Users },
  { id: "settings", label: "Settings", icon: Settings },
]

export default function AnimatedSidebarDemo() {
  const [active, setActive] = React.useState("inbox")
  const current = NAV.find((item) => item.id === active) ?? NAV[0]

  return (
    <AnimatedSidebarProvider
      style={{ "--sidebar-width": "15rem" }}
      className="h-[420px] min-h-0 w-full overflow-hidden border bg-background"
    >
      <AnimatedSidebar
        ariaLabel="Main navigation"
        collapsible="offcanvas"
        className="min-h-0 w-full"
        panelClassName="h-full bg-surface"
      >
        <AnimatedSidebarContent className="px-2 py-4">
          <AnimatedSidebarGroup className="px-1 py-0">
            <AnimatedSidebarGroupLabel className="mb-1 h-8 px-2 eyebrow">
              Workspace
            </AnimatedSidebarGroupLabel>
            <AnimatedSidebarGroupContent>
              <AnimatedSidebarMenu className="gap-0.5">
                {NAV.map(({ id, label, icon: Icon, badge }) => (
                  <AnimatedSidebarMenuItem key={id}>
                    <AnimatedSidebarMenuButton
                      icon={<Icon className="size-4" />}
                      isActive={id === active}
                      badge={
                        badge ? (
                          <span className="font-mono text-[10px] text-muted-foreground">
                            {badge}
                          </span>
                        ) : undefined
                      }
                      onSelect={() => setActive(id)}
                      className="font-normal"
                    >
                      {label}
                    </AnimatedSidebarMenuButton>
                  </AnimatedSidebarMenuItem>
                ))}
              </AnimatedSidebarMenu>
            </AnimatedSidebarGroupContent>
          </AnimatedSidebarGroup>
        </AnimatedSidebarContent>
        <AnimatedSidebarRail />
      </AnimatedSidebar>
      <AnimatedSidebarInset className="min-h-0 bg-background">
        <header className="flex h-14 shrink-0 items-center gap-3 border-b px-4">
          <AnimatedSidebarTrigger className="size-8 rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-foreground">
            <PanelLeft aria-hidden className="size-4" />
          </AnimatedSidebarTrigger>
          <p className="heading text-lg">{current.label}</p>
        </header>
        <div className="flex-1 bg-dots p-6 text-sm text-muted-foreground">
          Toggle the sidebar from the header, or drag its edge rail.
        </div>
      </AnimatedSidebarInset>
    </AnimatedSidebarProvider>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/animated-sidebar. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Avatar

Image or initials, alone or overlapped in a group.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/avatar
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Avatar, AvatarImage, AvatarFallback, AvatarGroup } from "@/components/ui/avatar"
```

## Dependencies

- npm: `radix-ui`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
function Avatar(props: React.ComponentProps<typeof AvatarPrimitive.Root>)

function AvatarImage(props: React.ComponentProps<typeof AvatarPrimitive.Image>)

function AvatarFallback(props: React.ComponentProps<typeof AvatarPrimitive.Fallback>)

function AvatarGroup(props: React.ComponentProps<"div">)
```

## Example

```tsx
import { Avatar, AvatarFallback, AvatarGroup } from "@/components/ui/avatar"

export default function AvatarDemo() {
  return (
    <div className="flex items-center gap-6">
      <Avatar className="size-10">
        <AvatarFallback>NM</AvatarFallback>
      </Avatar>
      <AvatarGroup>
        {["NM", "AL", "GH", "KT"].map((initials) => (
          <Avatar key={initials}>
            <AvatarFallback>{initials}</AvatarFallback>
          </Avatar>
        ))}
      </AvatarGroup>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/avatar. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Badge

Small square status label, with an optional dot.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/badge
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Badge } from "@/components/ui/badge"
```

## Dependencies

- npm: `radix-ui`, `class-variance-authority`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
function Badge(props: React.ComponentProps<"span"> &
  VariantProps<typeof badgeVariants> & { asChild?: boolean; dot?: boolean })
```

## Variants

- `variant`: `default` (default), `secondary`, `outline`, `brand`, `success`, `warning`, `destructive`

## Example

```tsx
import { Badge } from "@/components/ui/badge"

export default function BadgeDemo() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Badge>Default</Badge>
      <Badge variant="secondary">Secondary</Badge>
      <Badge variant="outline">Outline</Badge>
      <Badge variant="brand" dot>
        Brand
      </Badge>
      <Badge variant="success" dot>
        Paid
      </Badge>
      <Badge variant="warning" dot>
        Pending
      </Badge>
      <Badge variant="destructive" dot>
        Failed
      </Badge>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/badge. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Button

Primary, ink, secondary, outline, ghost, destructive and link, with a loading state.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/button
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Button, Spinner } from "@/components/ui/button"
```

## Dependencies

- npm: `radix-ui`, `class-variance-authority`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
type ButtonProps = React.ComponentProps<"button"> &
  VariantProps<typeof buttonVariants> & {
    asChild?: boolean
    loading?: boolean
  }

function Spinner(props: { className?: string })
```

## Variants

- `variant`: `default` (default), `brand`, `ink`, `secondary`, `outline`, `ghost`, `destructive`, `link`
- `size`: `xs`, `sm`, `default` (default), `lg`, `xl`, `icon`, `icon-sm`, `icon-xs`
- `caps`: `true`, `false` (default)

## Example

```tsx
"use client"

import * as React from "react"
import { ArrowRight, Plus, Sparkles, Trash2 } from "lucide-react"

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

export default function ButtonDemo() {
  const [loading, setLoading] = React.useState(false)

  return (
    <div className="grid gap-6">
      <div className="flex flex-wrap items-center gap-3">
        <Button>Default</Button>
        <Button variant="ink">Ink</Button>
        <Button variant="secondary">Secondary</Button>
        <Button variant="outline">Outline</Button>
        <Button variant="ghost">Ghost</Button>
        <Button variant="destructive">
          <Trash2 /> Delete
        </Button>
        <Button variant="link">Link</Button>
      </div>
      <div className="flex flex-wrap items-center gap-3">
        <Button size="sm">Small</Button>
        <Button size="lg">
          <Sparkles /> Large
        </Button>
        <Button size="icon" variant="outline" aria-label="Add">
          <Plus />
        </Button>
        <Button caps>
          Start for free <ArrowRight />
        </Button>
        <Button
          variant="outline"
          loading={loading}
          onClick={() => {
            setLoading(true)
            setTimeout(() => setLoading(false), 1500)
          }}
        >
          Click to load
        </Button>
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/button. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Card

Bordered surface with header, action, content and footer slots.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/card
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Card, CardHeader, CardFooter, CardTitle, CardAction, CardDescription, CardContent } from "@/components/ui/card"
```

## Dependencies

- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
function Card(props: React.ComponentProps<"div">)

function CardHeader(props: React.ComponentProps<"div">)

function CardFooter(props: React.ComponentProps<"div">)

function CardTitle(props: React.ComponentProps<"div">)

function CardAction(props: React.ComponentProps<"div">)

function CardDescription(props: React.ComponentProps<"div">)

function CardContent(props: React.ComponentProps<"div">)
```

## Example

```tsx
import { ArrowUpRight } from "lucide-react"

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 default function CardDemo() {
  return (
    <Card className="w-full max-w-sm">
      <CardHeader>
        <CardDescription>Monthly recurring revenue</CardDescription>
        <CardTitle className="heading text-4xl">$48,210</CardTitle>
        <CardAction>
          <Badge variant="success" dot>
            +12.4%
          </Badge>
        </CardAction>
      </CardHeader>
      <CardContent className="text-sm text-muted-foreground">
        Up from $42,890 last month, driven by 38 new team plans.
      </CardContent>
      <CardFooter className="justify-end border-t pt-6">
        <Button variant="ghost" size="sm">
          View report <ArrowUpRight />
        </Button>
      </CardFooter>
    </Card>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/card. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Checkbox

Checkbox with a drawn check and an indeterminate state.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/checkbox
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Checkbox } from "@/components/ui/checkbox"
```

## Dependencies

- npm: `radix-ui`, `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`

## Props and types

```ts
function Checkbox(props: React.ComponentProps<typeof CheckboxPrimitive.Root>)
```

## Example

```tsx
"use client"

import * as React from "react"

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

const ITEMS = ["Type safety", "Accessibility", "Registry validation"]

export default function CheckboxDemo() {
  const [checked, setChecked] = React.useState<string[]>(["Type safety"])
  const all = checked.length === ITEMS.length
  const some = checked.length > 0 && !all

  return (
    <div className="grid gap-3">
      <div className="flex items-center gap-3">
        <Checkbox
          id="all"
          checked={all ? true : some ? "indeterminate" : false}
          onCheckedChange={(value) => setChecked(value === true ? ITEMS : [])}
        />
        <Label htmlFor="all">All checks</Label>
      </div>
      <div className="grid gap-3 pl-7">
        {ITEMS.map((item) => (
          <div key={item} className="flex items-center gap-3">
            <Checkbox
              id={item}
              checked={checked.includes(item)}
              onCheckedChange={(value) =>
                setChecked((current) =>
                  value === true
                    ? [...current, item]
                    : current.filter((c) => c !== item)
                )
              }
            />
            <Label htmlFor={item}>{item}</Label>
          </div>
        ))}
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/checkbox. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Command Palette

⌘K palette with fuzzy search, groups, hints and keyboard navigation.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/command-palette
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { CommandPalette } from "@/components/motion/command-palette"
```

## Dependencies

- npm: `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`, `@opendraft/presence-gate`, `@opendraft/command-search`, `@opendraft/use-on-open`, `@opendraft/use-row-cursor`, `@opendraft/use-touch-capable`

## Props and types

```ts
export type CommandItem = {
  id: string
  label: string
  group?: string
  hint?: string
  keywords?: string[]
  icon?: LucideIcon
  badge?: ReactNode
  onSelect: () => void
}

export interface CommandPaletteProps {
  items: CommandItem[]
  /** Opens with Cmd/Ctrl + this key. Default: "k" */
  shortcut?: string
  placeholder?: string
  emptyMessage?: string
  open?: boolean
  onOpenChange?: (open: boolean) => void
}
```

## Example

```tsx
"use client"

import * as React from "react"
import {
  Bell,
  Bot,
  CreditCard,
  FileText,
  Moon,
  Search,
  Settings,
  Sparkles,
  User,
} from "lucide-react"
import { toast } from "sonner"

import {
  CommandPalette,
  type CommandItem,
} from "@/components/motion/command-palette"
import { Badge } from "@/components/ui/badge"
import { Button } from "@/components/ui/button"
import { Kbd, KbdGroup } from "@/components/ui/kbd"

export default function CommandPaletteDemo() {
  const [open, setOpen] = React.useState(false)
  const run = (label: string) => () => toast(label)

  const items: CommandItem[] = [
    {
      id: "new",
      label: "New chat",
      group: "Actions",
      icon: Sparkles,
      hint: "N",
      onSelect: run("New chat"),
    },
    {
      id: "agent",
      label: "Run agent on this page",
      group: "Actions",
      icon: Bot,
      onSelect: run("Agent started"),
    },
    {
      id: "search",
      label: "Search components",
      group: "Actions",
      icon: Search,
      keywords: ["find"],
      onSelect: run("Search"),
    },
    {
      id: "theme",
      label: "Toggle dark mode",
      group: "Preferences",
      icon: Moon,
      onSelect: () => document.documentElement.classList.toggle("dark"),
    },
    {
      id: "notifications",
      label: "Notification settings",
      group: "Preferences",
      icon: Bell,
      onSelect: run("Notifications"),
    },
    {
      id: "docs",
      label: "Registry docs",
      group: "Go to",
      icon: FileText,
      onSelect: run("Docs"),
    },
    {
      id: "profile",
      label: "Profile",
      group: "Account",
      icon: User,
      onSelect: run("Profile"),
    },
    {
      id: "billing",
      label: "Billing",
      group: "Account",
      icon: CreditCard,
      badge: <Badge variant="brand">Pro</Badge>,
      onSelect: run("Billing"),
    },
    {
      id: "settings",
      label: "Settings",
      group: "Account",
      icon: Settings,
      onSelect: run("Settings"),
    },
  ]

  return (
    <>
      <Button
        variant="outline"
        onClick={() => setOpen(true)}
        className="w-72 max-w-full justify-between text-muted-foreground"
      >
        <span className="flex items-center gap-2">
          <Search /> Search or run a command…
        </span>
        <KbdGroup>
          <Kbd>⌘</Kbd>
          <Kbd>K</Kbd>
        </KbdGroup>
      </Button>
      <CommandPalette items={items} open={open} onOpenChange={setOpen} />
    </>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/command-palette. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Data Table

Virtualized table: sort, resize and reorder columns, select rows, edit cells.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/table
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Table } from "@/components/motion/table"
```

Files added to the project:

- `components/motion/table/index.tsx`
- `components/motion/table/editable-cell.tsx`
- `components/motion/table/row-handle.tsx`
- `components/motion/table/skeleton-rows.tsx`
- `components/motion/table/table-header.tsx`
- `components/motion/table/table-menu.tsx`
- `components/motion/table/types.ts`
- `components/motion/table/use-column-reorder.ts`
- `components/motion/table/use-column-resize.ts`
- `components/motion/table/use-column-sort.ts`
- `components/motion/table/use-row-selection.ts`
- `components/motion/table/utils.ts`

## Dependencies

- npm: `motion`, `lucide-react`, `@tanstack/react-virtual`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`, `@opendraft/checkbox`, `@opendraft/touch`

## Props and types

```ts
export type SortDirection = "asc" | "desc"

export type SortState = {
  key: string
  direction: SortDirection
}

export type TableColumn<T> = {
  /** Stable key; also the default object property read for the cell + sort value. */
  key: string
  /** Header content. */
  header: ReactNode
  /** Allow clicking the header to sort by this column. */
  sortable?: boolean
  /** Cell text alignment. */
  align?: "left" | "center" | "right"
  /** Column width as a CSS length, e.g. "160px" or "20%". Omit to share remaining space equally. */
  width?: string
  /** Custom cell renderer. Falls back to `row[key]`. */
  cell?: (row: T) => ReactNode
  /** Render an inline text input for this column's cells (ignored when `cell` is set). */
  editable?: boolean
  /** Value used for sorting. Falls back to `row[key]`. */
  sortValue?: (row: T) => string | number
}

export type InsertPosition = "before" | "after"

export interface TableProps<T> {
  data: T[]
  columns: TableColumn<T>[]
  /** Stable id per row, required for correct selection across sorts. Defaults to row index. */
  getRowId?: (row: T, index: number) => string
  /** Render a leading checkbox column with select-all in the header. */
  selectable?: boolean
  selectedRowIds?: string[]
  defaultSelectedRowIds?: string[]
  onSelectionChange?: (ids: string[]) => void
  sort?: SortState | null
  defaultSort?: SortState | null
  onSortChange?: (sort: SortState | null) => void
  /** Allow dragging the right edge of a header to resize that column. */
  resizable?: boolean
  /** Minimum column width in px when resizing. */
  minColumnWidth?: number
  onColumnResize?: (key: string, width: number) => void
  /** Allow dragging a header grip to reorder columns. */
  reorderable?: boolean
  onColumnOrderChange?: (keys: string[]) => void
  /** Called when an `editable` cell changes. */
  onCellEdit?: (rowId: string, columnKey: string, value: string) => void
  /** When set, non-sortable headers become editable inputs for the column name. */
  onColumnRename?: (columnKey: string, value: string) => void
  /** Enables the row menu (Insert before / after). Receives the target index. */
  onInsertRow?: (index: number, position: InsertPosition) => void
  /** Enables Delete in the row menu. */
  onDeleteRow?: (rowId: string, index: number) => void
  /** Enables the column menu (Insert before / after). Receives the target column index. */
  onInsertColumn?: (index: number, position: InsertPosition) => void
  /** Enables Delete in the column menu. */
  onDeleteColumn?: (columnKey: string, index: number) => void
  /** Fixed row height in px — required for virtualization. */
  rowHeight?: number
  /** Scroll viewport height in px. */
  height?: number
  /** Size to the rows, up to this many px, instead of the fixed `height`. */
  maxHeight?: number
  /** Rows rendered above/below the viewport. */
  overscan?: number
  /** Fires when the viewport scrolls near the bottom — load the next page. */
  onEndReached?: () => void
  /** Currently fetching — shows skeleton rows and pauses `onEndReached`. */
  loading?: boolean
  /** How many skeleton rows to show while loading more (default 3). */
  skeletonRows?: number
  emptyState?: ReactNode
  className?: string
}

function Table(props: TableProps<T>)
```

## Example

```tsx
"use client"

import * as React from "react"

import { Table, type TableColumn } from "@/components/motion/table"
import { Badge } from "@/components/ui/badge"

type Person = {
  id: string
  name: string
  email: string
  role: string
  status: "active" | "invited" | "suspended"
  mrr: number
}

const FIRST = [
  "Ava",
  "Leo",
  "Mia",
  "Kai",
  "Zoe",
  "Eli",
  "Noa",
  "Ren",
  "Ivy",
  "Jude",
]
const LAST = [
  "Cole",
  "Frost",
  "Vale",
  "Reyes",
  "Okafor",
  "Sato",
  "Lund",
  "Marsh",
  "Bose",
  "Quinn",
]
const ROLES = ["Owner", "Admin", "Member", "Viewer"]
const STATUSES: Person["status"][] = ["active", "invited", "suspended"]
const STATUS_VARIANT = {
  active: "success",
  invited: "warning",
  suspended: "destructive",
} as const

// Deterministic so the server and the browser render the same rows.
function buildPeople(count: number): Person[] {
  return Array.from({ length: count }, (_, i) => {
    const first = FIRST[i % FIRST.length]
    const last = LAST[(i * 7) % LAST.length]
    return {
      id: String(i),
      name: `${first} ${last}`,
      email: `${first.toLowerCase()}.${last.toLowerCase()}${i}@example.com`,
      role: ROLES[(i * 3) % ROLES.length],
      status: STATUSES[(i * 5) % STATUSES.length],
      mrr: 12 + ((i * 37) % 488),
    }
  })
}

export default function TableDemo() {
  const data = React.useMemo(() => buildPeople(10_000), [])
  const [selected, setSelected] = React.useState<string[]>([])

  const columns = React.useMemo<TableColumn<Person>[]>(
    () => [
      {
        key: "name",
        header: "Name",
        sortable: true,
        width: "1.4fr",
        cell: (row) => <span className="font-medium">{row.name}</span>,
      },
      { key: "email", header: "Email", width: "1.8fr" },
      { key: "role", header: "Role", sortable: true, width: "120px" },
      {
        key: "status",
        header: "Status",
        width: "130px",
        cell: (row) => (
          <Badge
            variant={STATUS_VARIANT[row.status]}
            dot
            className="capitalize"
          >
            {row.status}
          </Badge>
        ),
      },
      {
        key: "mrr",
        header: "MRR",
        sortable: true,
        align: "right",
        width: "110px",
        cell: (row) => (
          <span className="tabular-nums">${row.mrr.toLocaleString()}</span>
        ),
      },
    ],
    []
  )

  return (
    <div className="flex w-full min-w-0 flex-col gap-2">
      <div className="flex items-center justify-between font-mono text-[11px] text-muted-foreground">
        <span>{data.length.toLocaleString()} rows · virtualized</span>
        {selected.length > 0 ? (
          <span>{selected.length.toLocaleString()} selected</span>
        ) : null}
      </div>
      <Table
        data={data}
        columns={columns}
        selectable
        resizable
        reorderable
        selectedRowIds={selected}
        onSelectionChange={setSelected}
        defaultSort={{ key: "mrr", direction: "desc" }}
        height={400}
        rowHeight={48}
      />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/table. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Date Range Picker

Range calendar in a popover, with month and year choosers and min / max.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/date-range-picker
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { DateRangePicker, DateRangePickerCalendar, DateRangePickerSummary, DateRangePickerHeader, DateRangePickerGrid, DateRangePickerSelection, DateRangePickerClear, DateRangePickerFooter, DateRangePickerPresets, DateRangePickerPreset, DateRangePickerTrigger, DateRangePickerContent, DateRangePickerDropdown } from "@/components/motion/date-range-picker"
```

Files added to the project:

- `components/motion/date-range-picker.tsx`
- `components/motion/date-range-picker/context.ts`
- `components/motion/date-range-picker/date-utils.ts`
- `components/motion/date-range-picker/types.ts`
- `components/motion/date-range-picker/use-date-range-picker.ts`

## Dependencies

- npm: `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`, `@opendraft/popover`, `@opendraft/use-hover-capable`

## Props and types

```ts
export interface DateRangePickerCalendarProps extends ComponentPropsWithoutRef<"section"> {
  showSummary?: boolean
}

export type DateRangePickerSummaryProps = Omit<
  ComponentPropsWithoutRef<"div">,
  "children"
>

export type DateRangePickerHeaderProps = Omit<
  ComponentPropsWithoutRef<"div">,
  "children"
>

export type DateRangePickerGridProps = Omit<
  ComponentPropsWithoutRef<"div">,
  "children"
>

export type DateRangePickerSelectionProps = ComponentPropsWithoutRef<"p">

export type DateRangePickerClearProps = ComponentPropsWithRef<"button">

export type DateRangePickerFooterProps = ComponentPropsWithoutRef<"div">

export type DateRangePickerPresetsProps = ComponentPropsWithoutRef<"div">

export interface DateRangePickerPresetProps extends Omit<
  ComponentPropsWithRef<"button">,
  "value"
> {
  value: DateRange
  /** Accessible preset name and selection announcement. */
  label: string
}

export interface DateRangePickerTriggerProps extends HTMLMotionProps<"button"> {
  placeholder?: string
}

export interface DateRangePickerContentProps {
  children: ReactNode
  side?: "top" | "right" | "bottom" | "left"
  align?: "start" | "center" | "end"
  /** Gap between trigger and panel, in px. Default 8. */
  sideOffset?: number
  /** Runs once the panel is open, with the panel element. */
  onOpenAutoFocus?: (content: HTMLDivElement) => void
  className?: string
  /** Move focus to the active calendar date when opened. Default true. */
  autoFocus?: boolean
}

export interface DateRangePickerDropdownProps extends Omit<
  DateRangePickerProps,
  "children"
> {
  placeholder?: string
  triggerClassName?: string
  calendarClassName?: string
}

/** Calendar dates, independent of a browser's timezone: YYYY-MM-DD. */
export interface DateRange {
  from: string
  to?: string
}

export interface DateRangePreset {
  label: string
  value: DateRange
}

export interface DateRangePickerProps {
  value?: DateRange | null
  defaultValue?: DateRange | null
  onValueChange?: (range: DateRange | null) => void
  defaultMonth?: string
  min?: string
  max?: string
  isDateDisabled?: (date: string) => boolean
  presets?: DateRangePreset[]
  locale?: string
  label?: string
  disabled?: boolean
  /** Move focus to the active date on mount, for use inside a popover. */
  autoFocus?: boolean
  /** Show the start/end summary above the calendar. Default true. */
  showSummary?: boolean
  className?: string
  /** Compose custom controls; omitted children render the inline calendar. */
  children?: ReactNode
  open?: boolean
  defaultOpen?: boolean
  onOpenChange?: (open: boolean) => void
  /** Close an open popover after a complete range or preset. Default false. */
  closeOnSelect?: boolean
}
```

## Example

```tsx
"use client"

import * as React from "react"

import {
  DateRangePicker,
  DateRangePickerCalendar,
  DateRangePickerClear,
  DateRangePickerContent,
  DateRangePickerFooter,
  DateRangePickerGrid,
  DateRangePickerHeader,
  DateRangePickerSelection,
  DateRangePickerTrigger,
} from "@/components/motion/date-range-picker"
import { Button } from "@/components/ui/button"

function isoDaysAgo(daysAgo: number) {
  const day = new Date()
  day.setDate(day.getDate() - daysAgo)
  return `${day.getFullYear()}-${String(day.getMonth() + 1).padStart(2, "0")}-${String(day.getDate()).padStart(2, "0")}`
}

const subscribeNever = () => () => {}

export default function DateRangePickerDemo() {
  // Dates are only known in the browser, so the server renders a placeholder.
  const today = React.useSyncExternalStore(
    subscribeNever,
    () => isoDaysAgo(0),
    () => null
  )
  if (!today) {
    return (
      <Button variant="outline" disabled>
        Reporting period
      </Button>
    )
  }

  return (
    <DateRangePicker
      label="Reporting period"
      defaultMonth={today}
      defaultValue={{ from: isoDaysAgo(6), to: today }}
      max={today}
    >
      <DateRangePickerTrigger />
      <DateRangePickerContent>
        <DateRangePickerCalendar className="w-full rounded-none border-0">
          <DateRangePickerHeader />
          <DateRangePickerGrid />
          <DateRangePickerFooter>
            <div className="flex items-center justify-between gap-2">
              <DateRangePickerSelection />
              <DateRangePickerClear />
            </div>
          </DateRangePickerFooter>
        </DateRangePickerCalendar>
      </DateRangePickerContent>
    </DateRangePicker>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/date-range-picker. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Dialog

Modal dialog that springs in, with header, body and footer slots.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/dialog
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui/dialog"
```

## Dependencies

- npm: `radix-ui`, `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`

## Props and types

```ts
function Dialog(props: React.ComponentProps<typeof DialogPrimitive.Root>)

function DialogClose(props: React.ComponentProps<typeof DialogPrimitive.Close>)

function DialogContent(props: React.ComponentProps<typeof DialogPrimitive.Content> & {
  showCloseButton?: boolean
})

function DialogDescription(props: React.ComponentProps<typeof DialogPrimitive.Description>)

function DialogFooter(props: React.ComponentProps<"div">)

function DialogHeader(props: React.ComponentProps<"div">)

function DialogTitle(props: React.ComponentProps<typeof DialogPrimitive.Title>)

function DialogTrigger(props: React.ComponentProps<typeof DialogPrimitive.Trigger>)
```

## Example

```tsx
"use client"

import { toast } from "sonner"

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

export default function DialogDemo() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="outline">Invite teammates</Button>
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Invite teammates</DialogTitle>
          <DialogDescription>
            They&apos;ll get an email with a link to join your workspace.
          </DialogDescription>
        </DialogHeader>
        <div className="grid gap-2">
          <Label htmlFor="invite">Email addresses</Label>
          <Input id="invite" placeholder="ada@example.com, alan@example.com" />
        </div>
        <DialogFooter>
          <DialogClose asChild>
            <Button variant="ghost">Cancel</Button>
          </DialogClose>
          <DialogClose asChild>
            <Button onClick={() => toast.success("Invites sent")}>
              Send invites
            </Button>
          </DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/dialog. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Drawer

Side sheet with a backdrop that closes on Esc or an outside click.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/drawer
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Drawer } from "@/components/motion/drawer"
```

## Dependencies

- npm: `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`, `@opendraft/presence-gate`

## Props and types

```ts
export interface DrawerProps {
  open: boolean
  onOpenChange: (open: boolean) => void
  side?: "left" | "right"
  children: ReactNode
  /** Class for the panel surface. */
  className?: string
  /** Class for the backdrop. */
  backdropClassName?: string
  ariaLabel?: string
  /** Close when the backdrop is clicked. Default true. */
  dismissable?: boolean
}
```

## Example

```tsx
"use client"

import * as React from "react"
import { toast } from "sonner"

import { Drawer } from "@/components/motion/drawer"
import { Button } from "@/components/ui/button"
import { Label } from "@/components/ui/label"
import { Switch } from "@/components/ui/switch"

const SETTINGS = [
  { id: "notify", label: "Email notifications", on: true },
  { id: "digest", label: "Weekly digest", on: false },
  { id: "agents", label: "Let agents run tools", on: true },
]

export default function DrawerDemo() {
  const [open, setOpen] = React.useState(false)
  const [side, setSide] = React.useState<"left" | "right">("right")

  const show = (next: "left" | "right") => {
    setSide(next)
    setOpen(true)
  }

  return (
    <div className="flex gap-3">
      <Button variant="outline" onClick={() => show("left")}>
        Open left
      </Button>
      <Button onClick={() => show("right")}>Open settings</Button>
      <Drawer
        open={open}
        onOpenChange={setOpen}
        side={side}
        ariaLabel="Workspace settings"
        className="gap-6 p-6"
      >
        <div>
          <p className="eyebrow text-muted-foreground">Workspace</p>
          <h2 className="mt-3 heading text-3xl">Settings</h2>
        </div>
        <div className="grid gap-4 border-t pt-6">
          {SETTINGS.map((setting) => (
            <div
              key={setting.id}
              className="flex items-center justify-between gap-4"
            >
              <Label htmlFor={`drawer-${setting.id}`}>{setting.label}</Label>
              <Switch id={`drawer-${setting.id}`} defaultChecked={setting.on} />
            </div>
          ))}
        </div>
        <div className="mt-auto flex gap-2">
          <Button
            variant="ghost"
            className="flex-1"
            onClick={() => setOpen(false)}
          >
            Cancel
          </Button>
          <Button
            className="flex-1"
            onClick={() => {
              setOpen(false)
              toast.success("Settings saved")
            }}
          >
            Save
          </Button>
        </div>
      </Drawer>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/drawer. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Dropdown Menu

Menu with shortcuts, checkbox items and sub-menus.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/dropdown-menu
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

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

## Dependencies

- npm: `radix-ui`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
function DropdownMenu(props: React.ComponentProps<typeof DropdownMenuPrimitive.Root>)

function DropdownMenuTrigger(props: React.ComponentProps<typeof DropdownMenuPrimitive.Trigger>)

function DropdownMenuContent(props: React.ComponentProps<typeof DropdownMenuPrimitive.Content>)

function DropdownMenuGroup(props: React.ComponentProps<typeof DropdownMenuPrimitive.Group>)

function DropdownMenuLabel(props: React.ComponentProps<typeof DropdownMenuPrimitive.Label> & {
  inset?: boolean
})

function DropdownMenuItem(props: React.ComponentProps<typeof DropdownMenuPrimitive.Item> & {
  inset?: boolean
  variant?: "default" | "destructive"
})

function DropdownMenuCheckboxItem(props: React.ComponentProps<typeof DropdownMenuPrimitive.CheckboxItem>)

function DropdownMenuRadioGroup(props: React.ComponentProps<typeof DropdownMenuPrimitive.RadioGroup>)

function DropdownMenuRadioItem(props: React.ComponentProps<typeof DropdownMenuPrimitive.RadioItem>)

function DropdownMenuSeparator(props: React.ComponentProps<typeof DropdownMenuPrimitive.Separator>)

function DropdownMenuShortcut(props: React.ComponentProps<"span">)

function DropdownMenuSub(props: React.ComponentProps<typeof DropdownMenuPrimitive.Sub>)

function DropdownMenuSubTrigger(props: React.ComponentProps<typeof DropdownMenuPrimitive.SubTrigger> & {
  inset?: boolean
})

function DropdownMenuSubContent(props: React.ComponentProps<typeof DropdownMenuPrimitive.SubContent>)
```

## Example

```tsx
"use client"

import * as React from "react"
import { CreditCard, LogOut, Settings, User } from "lucide-react"

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

export default function DropdownMenuDemo() {
  const [digest, setDigest] = React.useState(true)

  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="outline">Account</Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent className="w-56" align="start">
        <DropdownMenuLabel>My account</DropdownMenuLabel>
        <DropdownMenuItem>
          <User /> Profile <DropdownMenuShortcut>⇧⌘P</DropdownMenuShortcut>
        </DropdownMenuItem>
        <DropdownMenuItem>
          <CreditCard /> Billing <DropdownMenuShortcut>⌘B</DropdownMenuShortcut>
        </DropdownMenuItem>
        <DropdownMenuSub>
          <DropdownMenuSubTrigger>
            <Settings /> Settings
          </DropdownMenuSubTrigger>
          <DropdownMenuSubContent>
            <DropdownMenuItem>General</DropdownMenuItem>
            <DropdownMenuItem>Security</DropdownMenuItem>
          </DropdownMenuSubContent>
        </DropdownMenuSub>
        <DropdownMenuSeparator />
        <DropdownMenuCheckboxItem checked={digest} onCheckedChange={setDigest}>
          Weekly digest
        </DropdownMenuCheckboxItem>
        <DropdownMenuSeparator />
        <DropdownMenuItem variant="destructive">
          <LogOut /> Log out
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/dropdown-menu. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Input

Text field with focus, invalid and disabled states.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/input
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Input } from "@/components/ui/input"
```

## Dependencies

- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
function Input(props: React.ComponentProps<"input">)
```

## Example

```tsx
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export default function InputDemo() {
  return (
    <div className="grid w-full max-w-sm gap-4">
      <div className="grid gap-2">
        <Label htmlFor="email">Email</Label>
        <Input id="email" type="email" placeholder="you@example.com" />
      </div>
      <div className="grid gap-2">
        <Label htmlFor="invalid">Workspace URL</Label>
        <Input id="invalid" defaultValue="my workspace" aria-invalid />
        <p className="text-xs text-destructive">
          Use letters, numbers and dashes.
        </p>
      </div>
      <div className="grid gap-2">
        <Label htmlFor="disabled">Plan</Label>
        <Input id="disabled" defaultValue="Pro" disabled />
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/input. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Kbd

Keyboard keys and shortcuts.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/kbd
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Kbd, KbdGroup } from "@/components/ui/kbd"
```

## Dependencies

- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
function Kbd(props: React.ComponentProps<"kbd">)

function KbdGroup(props: React.ComponentProps<"span">)
```

## Example

```tsx
import { Command } from "lucide-react"

import { Kbd, KbdGroup } from "@/components/ui/kbd"

export default function KbdDemo() {
  return (
    <div className="grid gap-3 text-sm text-muted-foreground">
      <p className="flex items-center gap-2">
        Open the command palette
        <KbdGroup>
          <Kbd>
            <Command />
          </Kbd>
          <Kbd>K</Kbd>
        </KbdGroup>
      </p>
      <p className="flex items-center gap-2">
        Send without leaving the input
        <KbdGroup>
          <Kbd>Shift</Kbd>
          <Kbd>Enter</Kbd>
        </KbdGroup>
      </p>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/kbd. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Label

Accessible label for form controls.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/label
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Label } from "@/components/ui/label"
```

## Dependencies

- npm: `radix-ui`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
function Label(props: React.ComponentProps<typeof LabelPrimitive.Root>)
```

## Example

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

export default function LabelDemo() {
  return (
    <div className="flex items-center gap-3">
      <Checkbox id="terms" />
      <Label htmlFor="terms">Accept terms and conditions</Label>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/label. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Popover

Floating panel anchored to a trigger.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/popover
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Popover, PopoverTrigger, PopoverContent, PopoverAnchor } from "@/components/ui/popover"
```

## Dependencies

- npm: `radix-ui`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
function Popover(props: React.ComponentProps<typeof PopoverPrimitive.Root>)

function PopoverTrigger(props: React.ComponentProps<typeof PopoverPrimitive.Trigger>)

function PopoverContent(props: React.ComponentProps<typeof PopoverPrimitive.Content>)

function PopoverAnchor(props: React.ComponentProps<typeof PopoverPrimitive.Anchor>)
```

## Example

```tsx
import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"
import {
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@/components/ui/popover"

export default function PopoverDemo() {
  return (
    <Popover>
      <PopoverTrigger asChild>
        <Button variant="outline">Dimensions</Button>
      </PopoverTrigger>
      <PopoverContent className="grid gap-3">
        <p className="eyebrow text-muted-foreground">Dimensions</p>
        <div className="grid grid-cols-3 items-center gap-3">
          <Label htmlFor="width">Width</Label>
          <Input id="width" defaultValue="100%" className="col-span-2 h-8" />
          <Label htmlFor="height">Height</Label>
          <Input id="height" defaultValue="auto" className="col-span-2 h-8" />
        </div>
      </PopoverContent>
    </Popover>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/popover. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Radio Group

Single choice from a set, with a spring-in indicator.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/radio-group
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
```

## Dependencies

- npm: `radix-ui`, `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`

## Props and types

```ts
function RadioGroup(props: React.ComponentProps<typeof RadioGroupPrimitive.Root>)

function RadioGroupItem(props: React.ComponentProps<typeof RadioGroupPrimitive.Item>)
```

## Example

```tsx
import { Label } from "@/components/ui/label"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"

export default function RadioGroupDemo() {
  return (
    <RadioGroup defaultValue="balanced">
      {[
        ["fast", "Fast", "Quick answers for simple tasks"],
        ["balanced", "Balanced", "Good default for most work"],
        ["deep", "Deep thinking", "Slower, for hard problems"],
      ].map(([value, label, hint]) => (
        <div key={value} className="flex items-start gap-3">
          <RadioGroupItem value={value} id={value} className="mt-0.5" />
          <Label htmlFor={value} className="grid gap-1">
            {label}
            <span className="text-xs font-normal text-muted-foreground">
              {hint}
            </span>
          </Label>
        </div>
      ))}
    </RadioGroup>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/radio-group. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Select

Dropdown select with groups and labels.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/select
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue } from "@/components/ui/select"
```

## Dependencies

- npm: `radix-ui`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
function Select(props: React.ComponentProps<typeof SelectPrimitive.Root>)

function SelectContent(props: React.ComponentProps<typeof SelectPrimitive.Content>)

function SelectGroup(props: React.ComponentProps<typeof SelectPrimitive.Group>)

function SelectItem(props: React.ComponentProps<typeof SelectPrimitive.Item>)

function SelectLabel(props: React.ComponentProps<typeof SelectPrimitive.Label>)

function SelectScrollDownButton(props: React.ComponentProps<typeof SelectPrimitive.ScrollDownButton>)

function SelectScrollUpButton(props: React.ComponentProps<typeof SelectPrimitive.ScrollUpButton>)

function SelectSeparator(props: React.ComponentProps<typeof SelectPrimitive.Separator>)

function SelectTrigger(props: React.ComponentProps<typeof SelectPrimitive.Trigger> & {
  size?: "sm" | "default"
})

function SelectValue(props: React.ComponentProps<typeof SelectPrimitive.Value>)
```

## Example

```tsx
import { Label } from "@/components/ui/label"
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectLabel,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select"

export default function SelectDemo() {
  return (
    <div className="grid w-full max-w-xs gap-2">
      <Label>Plan</Label>
      <Select defaultValue="pro">
        <SelectTrigger className="w-full">
          <SelectValue placeholder="Choose a plan" />
        </SelectTrigger>
        <SelectContent>
          <SelectGroup>
            <SelectLabel>Plans</SelectLabel>
            <SelectItem value="free">Free</SelectItem>
            <SelectItem value="pro">Pro</SelectItem>
            <SelectItem value="team">Team</SelectItem>
          </SelectGroup>
        </SelectContent>
      </Select>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/select. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Separator

Horizontal or vertical hairline.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/separator
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Separator } from "@/components/ui/separator"
```

## Dependencies

- npm: `radix-ui`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
function Separator(props: React.ComponentProps<typeof SeparatorPrimitive.Root>)
```

## Example

```tsx
import { Separator } from "@/components/ui/separator"

export default function SeparatorDemo() {
  return (
    <div className="w-full max-w-sm">
      <p className="heading text-xl">opendraft</p>
      <p className="text-sm text-muted-foreground">
        A design system for agent interfaces.
      </p>
      <Separator className="my-4" />
      <div className="flex h-5 items-center gap-4 text-sm">
        <span>Docs</span>
        <Separator orientation="vertical" />
        <span>Components</span>
        <Separator orientation="vertical" />
        <span>Registry</span>
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/separator. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Skeleton

Shimmering placeholder while content loads.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/skeleton
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Skeleton } from "@/components/ui/skeleton"
```

## Dependencies

- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
function Skeleton(props: React.ComponentProps<"div">)
```

## Example

```tsx
import { Skeleton } from "@/components/ui/skeleton"

export default function SkeletonDemo() {
  return (
    <div className="grid w-full max-w-sm gap-4">
      {[0, 1, 2].map((row) => (
        <div key={row} className="flex items-center gap-3">
          <Skeleton className="size-10 rounded-full" />
          <div className="grid flex-1 gap-2">
            <Skeleton className="h-3.5 w-3/5" />
            <Skeleton className="h-3.5 w-2/5" />
          </div>
        </div>
      ))}
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/skeleton. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Switch

On / off toggle with a spring-driven thumb.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/switch
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Switch } from "@/components/ui/switch"
```

## Dependencies

- npm: `radix-ui`, `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`

## Props and types

```ts
function Switch(props: React.ComponentProps<typeof SwitchPrimitive.Root>)
```

## Example

```tsx
import { Label } from "@/components/ui/label"
import { Switch } from "@/components/ui/switch"

export default function SwitchDemo() {
  return (
    <div className="grid gap-4">
      <div className="flex items-center gap-3">
        <Switch id="notifications" defaultChecked />
        <Label htmlFor="notifications">Email notifications</Label>
      </div>
      <div className="flex items-center gap-3">
        <Switch id="digest" />
        <Label htmlFor="digest">Weekly digest</Label>
      </div>
      <div className="flex items-center gap-3">
        <Switch id="locked" disabled />
        <Label htmlFor="locked">Managed by your admin</Label>
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/switch. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Tabs

Tabs with a sliding indicator, in pill or underline style.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/tabs
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

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

## Dependencies

- npm: `radix-ui`, `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`

## Props and types

```ts
type TabsVariant = "pill" | "underline"

function Tabs(props: React.ComponentProps<typeof TabsPrimitive.Root> & {
  variant?: TabsVariant
})

function TabsList(props: React.ComponentProps<typeof TabsPrimitive.List>)

function TabsTrigger(props: React.ComponentProps<typeof TabsPrimitive.Trigger>)

function TabsContent(props: React.ComponentProps<typeof TabsPrimitive.Content>)
```

## Example

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

export default function TabsDemo() {
  return (
    <div className="grid w-full max-w-md gap-8">
      <Tabs defaultValue="overview">
        <TabsList>
          <TabsTrigger value="overview">Overview</TabsTrigger>
          <TabsTrigger value="activity">Activity</TabsTrigger>
          <TabsTrigger value="settings">Settings</TabsTrigger>
        </TabsList>
        <TabsContent value="overview" className="text-sm text-muted-foreground">
          The indicator slides between tabs with a spring from lib/motion.
        </TabsContent>
        <TabsContent value="activity" className="text-sm text-muted-foreground">
          12 events in the last 24 hours.
        </TabsContent>
        <TabsContent value="settings" className="text-sm text-muted-foreground">
          Workspace settings live here.
        </TabsContent>
      </Tabs>
      <Tabs defaultValue="all" variant="underline">
        <TabsList>
          <TabsTrigger value="all">All</TabsTrigger>
          <TabsTrigger value="open">Open</TabsTrigger>
          <TabsTrigger value="closed">Closed</TabsTrigger>
        </TabsList>
      </Tabs>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/tabs. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Textarea

Multi-line text field that grows with its content.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/textarea
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Textarea } from "@/components/ui/textarea"
```

## Dependencies

- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
function Textarea(props: React.ComponentProps<"textarea">)
```

## Example

```tsx
import { Label } from "@/components/ui/label"
import { Textarea } from "@/components/ui/textarea"

export default function TextareaDemo() {
  return (
    <div className="grid w-full max-w-sm gap-2">
      <Label htmlFor="message">Message</Label>
      <Textarea id="message" placeholder="Tell us a bit more…" />
      <p className="text-xs text-muted-foreground">
        Grows with its content up to the space available.
      </p>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/textarea. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Toast

Stacked notifications with actions, themed to the tokens.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/sonner
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Toaster } from "@/components/ui/sonner"
```

## Dependencies

- npm: `sonner`
- Registry (installed with it): `@opendraft/utils`

## Example

```tsx
"use client"

import { toast } from "sonner"

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

export default function ToastDemo() {
  return (
    <div className="flex flex-wrap gap-3">
      <Button
        variant="outline"
        onClick={() =>
          toast("Deployment queued", {
            description: "Building main@4f2c1a, about 40 seconds.",
            action: { label: "View", onClick: () => {} },
          })
        }
      >
        Default
      </Button>
      <Button variant="outline" onClick={() => toast.success("Settings saved")}>
        Success
      </Button>
      <Button variant="outline" onClick={() => toast.error("Payment failed")}>
        Error
      </Button>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/sonner. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Tooltip

Short hint on hover or focus, with optional shortcuts.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/tooltip
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from "@/components/ui/tooltip"
```

## Dependencies

- npm: `radix-ui`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
function Tooltip(props: React.ComponentProps<typeof TooltipPrimitive.Root>)

function TooltipTrigger(props: React.ComponentProps<typeof TooltipPrimitive.Trigger>)

function TooltipContent(props: React.ComponentProps<typeof TooltipPrimitive.Content>)

function TooltipProvider(props: React.ComponentProps<typeof TooltipPrimitive.Provider>)
```

## Example

```tsx
import { Search } from "lucide-react"

import { Button } from "@/components/ui/button"
import { Kbd, KbdGroup } from "@/components/ui/kbd"
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@/components/ui/tooltip"

export default function TooltipDemo() {
  return (
    <Tooltip>
      <TooltipTrigger asChild>
        <Button variant="outline" size="icon" aria-label="Search">
          <Search />
        </Button>
      </TooltipTrigger>
      <TooltipContent>
        Search
        <KbdGroup>
          <Kbd>⌘</Kbd>
          <Kbd>K</Kbd>
        </KbdGroup>
      </TooltipContent>
    </Tooltip>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/tooltip. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Search List

Command-style search with live filtering, a clear action, a gliding hover highlight and an empty state. Shows sample content (an ice cream shop) until you pass your own data through its props.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/search-list
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { SearchList } from "@/components/agents/search-list"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/glide-menu`

## Props and types

```ts
export type SearchItem = string

export type SearchListLabels = {
  placeholder: string
  ariaLabel: string
  emptyTitle: string
  emptyHint: string
}

export interface SearchListProps {
  items?: SearchItem[]
  labels?: Partial<SearchListLabels>
  /** Fired when a result is picked. */
  onSelect?: (item: SearchItem) => void
  className?: string
}
```

## Example

```tsx
"use client"

import { SearchList } from "@/components/agents/search-list"

export default function SearchListDemo() {
  return (
    <div className="flex w-full justify-center">
      <SearchList onSelect={(item) => console.log("picked:", item)} />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/search-list. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Sidebar Nav

Workspace switcher, primary nav and searchable chats that collapse to an aligned icon rail. Data shape: An AI-chat sidebar (chats, new chat, collapse rail). For general app navigation use `animated-sidebar`. Shows sample content (an ice cream shop) until you pass your own data through its props.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/sidebar-nav
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { SidebarNav } from "@/components/agents/sidebar-nav"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/glide-menu`, `@opendraft/motion`

## Props and types

```ts
export type SidebarRecent = {
  id: string
  label: string
  prompt?: string
}

export type SidebarWorkspaceMenuItem = {
  label: string
  icon?: React.ReactNode
  onSelect?: () => void
}

export type SidebarWorkspace = { key: string; name: string; monogram: string }

export type SidebarNavItem = {
  key: string
  label: string
  icon: React.ReactNode
  count?: string
}

export type SidebarNavProps = {
  /** Workspace shown in the switcher. Defaults to a neutral "Workspace". */
  workspace?: SidebarWorkspace
  /** Primary navigation items. Defaults to neutral Home / Invite users. */
  navItems?: SidebarNavItem[]
  /** Mark shown at the left of the workspace switcher. Defaults to a neutral icon. */
  logo?: React.ReactNode
  /** Items in the workspace menu (between the workspace row and sign out). */
  workspaceMenu?: SidebarWorkspaceMenuItem[]
  /** Called from the sign-out row of the workspace menu. */
  onSignOut?: () => void
  signOutLabel?: string
  newChatLabel?: string
  chatsLabel?: string
  searchLabel?: string
  searchPlaceholder?: string
  emptyLabel?: string
  /** aria-label of the aside. */
  ariaLabel?: string
  collapseLabel?: string
  expandLabel?: string
  activeTitle?: string | null
  className?: string
  /** Fill the parent's height instead of the fixed 600px demo height. */
  fill?: boolean
  onNewChat?: () => void
  onPick?: (id: string, label: string, prompt?: string) => void
  /** Controlled primary-nav selection (e.g. "home" | "invite"). */
  activeNav?: string
  onNavigate?: (key: string) => void
  /** Footer call-to-action — defaults to the demo "Upgrade" button. */
  footerLabel?: string
  footerIcon?: React.ReactNode
  onFooterClick?: () => void
  recents?: SidebarRecent[]
}
```

## Example

```tsx
import { SAMPLE_RECENTS, SidebarNav } from "@/components/agents/sidebar-nav"

export default function SidebarNavDemo() {
  return (
    <div className="flex h-[600px] overflow-hidden rounded-lg border bg-background">
      <SidebarNav fill recents={SAMPLE_RECENTS} />
      <div className="flex-1 bg-dots" />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/sidebar-nav. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Filter Bar

Search, select and multi-select filters from a config, with removable chips and clear-all.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/filter-bar
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { FilterBar } from "@/components/ui/filter-bar"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/badge`, `@opendraft/button`, `@opendraft/checkbox`, `@opendraft/input`, `@opendraft/popover`, `@opendraft/select`

## Props and types

```ts
export type FilterOption = {
  value: string
  label: string
  /** Optional count shown next to the option. */
  count?: number
}

type FilterBase = {
  /** Key of this filter in the values object. */
  key: string
  label: string
}

export type TextFilter = FilterBase & {
  type: "text"
  placeholder?: string
}

export type SelectFilter = FilterBase & {
  type: "select"
  options: FilterOption[]
}

export type MultiSelectFilter = FilterBase & {
  type: "multi-select"
  options: FilterOption[]
}

export type FilterConfig = TextFilter | SelectFilter | MultiSelectFilter

/** text and select store a string ("" = unset); multi-select stores string[]. */
export type FilterValues = Record<string, string | string[] | undefined>

export type FilterBarLabels = {
  clearAll: string
  /** Select placeholder suffix, e.g. "All" + label is built as `${all} ${label}`. */
  all: string
  /** Multi-select summary, receives the label and number selected. */
  selected: (label: string, count: number) => string
  /** aria-label for the group. */
  group: string
  /** aria-label for the remove button on an option chip. */
  remove: (label: string) => string
}

export type FilterBarProps = Omit<
  React.ComponentProps<"div">,
  "defaultValue" | "onChange"
> & {
  filters: FilterConfig[]
  value?: FilterValues
  defaultValue?: FilterValues
  onValueChange?: (value: FilterValues) => void
  labels?: Partial<FilterBarLabels>
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { FilterBar, type FilterValues } from "@/components/ui/filter-bar"

const hospital: { name: string; ward: string; priority: string }[] = [
  { name: "Patient 1", ward: "Cardiology", priority: "Urgent" },
  { name: "Patient 2", ward: "Oncology", priority: "Routine" },
  { name: "Patient 3", ward: "Cardiology", priority: "Routine" },
  { name: "Patient 4", ward: "Neurology", priority: "Urgent" },
]

export default function FilterBarDemo() {
  const [values, setValues] = React.useState<FilterValues>({})
  const q = String(values.q ?? "").toLowerCase()
  const wards = (values.ward as string[] | undefined) ?? []
  const shown = hospital.filter(
    (r) =>
      r.name.toLowerCase().includes(q) &&
      (wards.length === 0 || wards.includes(r.ward)) &&
      (!values.priority || r.priority === values.priority)
  )

  return (
    <div className="flex w-full max-w-[720px] flex-col gap-8">
      <div className="flex flex-col gap-3">
        <p className="eyebrow text-muted-foreground">
          Logistics (uncontrolled)
        </p>
        <FilterBar
          filters={[
            {
              key: "q",
              type: "text",
              label: "Search",
              placeholder: "Search shipments",
            },
            {
              key: "carrier",
              type: "select",
              label: "Carrier",
              options: [
                { value: "north", label: "Northline" },
                { value: "harbor", label: "Harbor Freight" },
              ],
            },
            {
              key: "mode",
              type: "multi-select",
              label: "Mode",
              options: [
                { value: "air", label: "Air", count: 4 },
                { value: "sea", label: "Sea", count: 9 },
                { value: "road", label: "Road", count: 21 },
              ],
            },
          ]}
          defaultValue={{ mode: ["air", "sea"] }}
        />
      </div>
      <div className="flex flex-col gap-3">
        <p className="eyebrow text-muted-foreground">Healthcare (controlled)</p>
        <FilterBar
          value={values}
          onValueChange={setValues}
          labels={{ clearAll: "Reset", all: "Any" }}
          filters={[
            {
              key: "q",
              type: "text",
              label: "Search",
              placeholder: "Search patients",
            },
            {
              key: "ward",
              type: "multi-select",
              label: "Ward",
              options: [
                { value: "Cardiology", label: "Cardiology" },
                { value: "Oncology", label: "Oncology" },
                { value: "Neurology", label: "Neurology" },
              ],
            },
            {
              key: "priority",
              type: "select",
              label: "Priority",
              options: [
                { value: "Urgent", label: "Urgent" },
                { value: "Routine", label: "Routine" },
              ],
            },
          ]}
        />
        <p className="font-mono text-xs text-muted-foreground">
          {shown.length} of {hospital.length} match
        </p>
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/filter-bar. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Bulk Action Bar

Toolbar that appears when items are selected: count, generic actions and a clear button.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/bulk-action-bar
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { BulkActionBar } from "@/components/ui/bulk-action-bar"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`

## Props and types

```ts
export type BulkAction = {
  id: string
  label: string
  icon?: React.ReactNode
  onSelect: () => void
  destructive?: boolean
  disabled?: boolean
}

export type BulkActionBarLabels = {
  /** Summary text for the current count. */
  selected: (count: number) => string
  clear: string
  /** aria-label for the toolbar. */
  toolbar: string
}

export type BulkActionBarProps = Omit<
  React.ComponentProps<"div">,
  "children"
> & {
  /** Number of selected items. The bar renders nothing visible at 0. */
  count: number
  actions: BulkAction[]
  onClear?: () => void
  labels?: Partial<BulkActionBarLabels>
}
```

## Example

```tsx
"use client"

import * as React from "react"
import { Archive, Download, Trash2, UserPlus } from "lucide-react"

import { Button } from "@/components/ui/button"
import { BulkActionBar } from "@/components/ui/bulk-action-bar"

export default function BulkActionBarDemo() {
  const [a, setA] = React.useState(3)
  const [b, setB] = React.useState(2)

  return (
    <div className="flex w-full max-w-[640px] flex-col gap-8">
      <div className="flex flex-col gap-3">
        <p className="eyebrow text-muted-foreground">Invoices</p>
        <div className="flex items-center gap-2">
          <Button size="xs" variant="outline" onClick={() => setA(a + 1)}>
            Select one more
          </Button>
        </div>
        <BulkActionBar
          count={a}
          onClear={() => setA(0)}
          actions={[
            {
              id: "export",
              label: "Export",
              icon: <Download />,
              onSelect: () => {},
            },
            {
              id: "archive",
              label: "Archive",
              icon: <Archive />,
              onSelect: () => {},
            },
            {
              id: "delete",
              label: "Delete",
              icon: <Trash2 />,
              destructive: true,
              onSelect: () => setA(0),
            },
          ]}
        />
      </div>
      <div className="flex flex-col gap-3">
        <p className="eyebrow text-muted-foreground">Staff, custom labels</p>
        <Button
          size="xs"
          variant="outline"
          className="w-fit"
          onClick={() => setB(b + 1)}
        >
          Select one more
        </Button>
        <BulkActionBar
          count={b}
          onClear={() => setB(0)}
          labels={{
            selected: (n) =>
              `${n} ${n === 1 ? "employee" : "employees"} chosen`,
            clear: "Deselect all",
          }}
          actions={[
            {
              id: "assign",
              label: "Assign manager",
              icon: <UserPlus />,
              onSelect: () => {},
            },
          ]}
        />
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/bulk-action-bar. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Checklist

Tickable checklist with progress, optional notes and a sign-off step for inspections, onboarding or compliance.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/checklist
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Checklist } from "@/components/ui/checklist"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/checkbox`, `@opendraft/progress`, `@opendraft/textarea`

## Props and types

```ts
type ChecklistItem = {
  id: string
  label: React.ReactNode
  description?: React.ReactNode
  /** Initial state when the list is uncontrolled and `defaultValue` is not set. */
  done?: boolean
  /** Initial note. */
  note?: string
}

type ChecklistLabels = {
  /** Progress caption. */
  progress: string
  /** Progress value. `{done}` and `{total}` are replaced. */
  count: string
  addNote: string
  editNote: string
  notePlaceholder: string
  noteLabel: string
  signOff: string
  signedOff: string
  /** Shown beside the disabled sign-off button. */
  incomplete: string
  /** Screen-reader announcement when progress changes. */
  announce: string
  empty: string
}

type ChecklistProps = Omit<
  React.ComponentProps<"div">,
  "onChange" | "defaultValue"
> & {
  items?: ChecklistItem[]
  /** Controlled list of completed item ids. */
  value?: string[]
  /** Uncontrolled initial completed ids. Falls back to each item's `done`. */
  defaultValue?: string[]
  onValueChange?: (value: string[]) => void
  title?: React.ReactNode
  description?: React.ReactNode
  /** Show a progress bar and count. */
  showProgress?: boolean
  /** Allow a note on each item. */
  notes?: boolean
  /** Controlled notes keyed by item id. */
  noteValues?: Record<string, string>
  onNoteChange?: (id: string, note: string) => void
  /** Show a sign-off footer. Enabled once every item is done. */
  onComplete?: (result: {
    done: string[]
    notes: Record<string, string>
  }) => void
  /** Extra content above the sign-off button, e.g. a name field. */
  signOff?: React.ReactNode
  /** Disables sign-off even when complete (e.g. a required field is empty). */
  signOffDisabled?: boolean
  disabled?: boolean
  /** Items stay visible and notes readable, but nothing can change. */
  readOnly?: boolean
  labels?: Partial<ChecklistLabels>
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { Checklist, type ChecklistItem } from "@/components/ui/checklist"
import { Input } from "@/components/ui/input"

const preflight: ChecklistItem[] = [
  {
    id: "fuel",
    label: "Fuel quantity",
    description: "Check against the flight plan.",
    done: true,
  },
  { id: "controls", label: "Flight controls free and correct" },
  {
    id: "lights",
    label: "Exterior lights",
    description: "Navigation, strobe and landing.",
  },
  { id: "docs", label: "Documents on board" },
]

const onboarding: ChecklistItem[] = [
  { id: "contract", label: "Signed contract received", done: true },
  {
    id: "laptop",
    label: "Laptop issued",
    note: "Serial recorded in the asset log.",
  },
  {
    id: "accounts",
    label: "Accounts created",
    description: "Email, chat and calendar.",
  },
  { id: "intro", label: "Intro meeting scheduled" },
]

export default function ChecklistDemo() {
  const [name, setName] = React.useState("")
  return (
    <div className="grid w-full max-w-4xl gap-8 md:grid-cols-2">
      <Checklist
        title="Pre-flight inspection"
        description="Walk-around before engine start."
        items={preflight}
        notes
        labels={{
          progress: "Inspection",
          signOff: "Release aircraft",
          signedOff: "Released",
        }}
        signOff={
          <Input
            aria-label="Inspector name"
            placeholder="Inspector name"
            value={name}
            onChange={(e) => setName(e.target.value)}
          />
        }
        signOffDisabled={!name.trim()}
        onComplete={() => {}}
      />
      <Checklist
        title="New hire onboarding"
        description="Read-only view for the hiring manager."
        items={onboarding}
        notes
        readOnly
        labels={{ progress: "Onboarding" }}
      />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/checklist. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Description List

Label and value grid for record details, with column spans, mono values and copy buttons.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/description-list
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { DescriptionList } from "@/components/ui/description-list"
```

## Dependencies

- Registry (installed with it): `@opendraft/utils`, `@opendraft/copy-button`

## Props and types

```ts
type DescriptionItem = {
  label: React.ReactNode
  value?: React.ReactNode
  /** Columns this entry spans (clamped to the available columns). */
  span?: number
  /** Show a copy button. Needs `copyValue` or a string/number `value`. */
  copyable?: boolean
  /** Text to copy when it differs from the displayed value. */
  copyValue?: string
  /** Render the value in mono, for IDs, codes and dates. */
  mono?: boolean
}

type DescriptionListLabels = {
  /** Shown when a value is empty. */
  empty: string
  copy: string
}

type DescriptionListProps = Omit<React.ComponentProps<"dl">, "children"> & {
  items?: DescriptionItem[]
  /** Maximum columns. The list steps down as its container narrows. */
  columns?: 1 | 2 | 3 | 4
  /** Wrap the list in a hairline-bordered card with dividers. */
  bordered?: boolean
  labels?: Partial<DescriptionListLabels>
}
```

## Example

```tsx
import {
  DescriptionList,
  type DescriptionItem,
} from "@/components/ui/description-list"

const shipment: DescriptionItem[] = [
  { label: "Tracking number", value: "SHP-204518", mono: true, copyable: true },
  { label: "Carrier", value: "Example Freight" },
  { label: "Status", value: "In transit" },
  { label: "Origin", value: "Rotterdam, NL" },
  { label: "Destination", value: "Chicago, US" },
  { label: "ETA", value: "2026-03-18", mono: true },
  { label: "Handling notes", value: "", span: 3 },
]

const employee: DescriptionItem[] = [
  { label: "Name", value: "Sam Example" },
  { label: "Employee ID", value: "E-10482", mono: true, copyable: true },
  { label: "Email", value: "sam@example.com", copyable: true },
  { label: "Department", value: "Operations" },
  { label: "Start date", value: "2025-09-01", mono: true },
  { label: "Manager", value: "Jo Example" },
]

export default function DescriptionListDemo() {
  return (
    <div className="flex w-full max-w-3xl flex-col gap-8">
      <section className="flex flex-col gap-3">
        <h3 className="heading text-xl">Shipment</h3>
        <DescriptionList
          items={shipment}
          bordered
          labels={{ empty: "None recorded" }}
        />
      </section>
      <section className="flex flex-col gap-3">
        <h3 className="heading text-xl">Employee record</h3>
        <DescriptionList items={employee} columns={2} bordered />
      </section>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/description-list. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Gauge

SVG gauge and risk-score ring with threshold bands and a text status, for posture, vitals, utilization and energy.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/gauge
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Gauge } from "@/components/ui/gauge"
```

## Dependencies

- npm: `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/badge`, `@opendraft/motion`

## Props and types

```ts
type GaugeTone = "neutral" | "brand" | "success" | "warning" | "destructive"

type GaugeThreshold = {
  /** The band starts at this value and runs to the next threshold's `at`. */
  at: number
  tone: GaugeTone
  /** Status word shown beside the number, so state never relies on color. */
  label: string
}

type GaugeLabels = {
  /** Screen-reader prefix for the status, e.g. "Status". */
  status: string
}

type GaugeProps = Omit<React.ComponentProps<"div">, "children"> & {
  value: number
  /** Scale start. Defaults to 0. */
  min?: number
  /** Scale end. Defaults to 100. */
  max?: number
  /**
   * Bands of the scale, in any order. The band whose `at` is the highest one
   * not above `value` is the current status. Defaults to low / medium / high
   * thirds-ish bands (0, 50%, 80% of the scale).
   */
  thresholds?: GaugeThreshold[]
  /** `ring` is a full circle, `arc` an open 240 degree dial. */
  variant?: "ring" | "arc"
  size?: keyof typeof sizeClass
  /** What the gauge measures. Also its accessible name. */
  label: string
  /** Small text under the status, e.g. a timestamp or a target. */
  hint?: React.ReactNode
  /** Unit shown next to the number, e.g. "%", "bpm", "kW". */
  unit?: React.ReactNode
  /** Format the number in the center and in the accessible value text. */
  formatValue?: (value: number) => string
  /** Replace the center content entirely. */
  center?: React.ReactNode
  /** Draw thin ticks where the bands change. Defaults to true. */
  showTicks?: boolean
  labels?: Partial<GaugeLabels>
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { Gauge, type GaugeThreshold } from "@/components/ui/gauge"
import { Slider } from "@/components/ui/slider"

const riskBands: GaugeThreshold[] = [
  { at: 0, tone: "success", label: "Low risk" },
  { at: 40, tone: "warning", label: "Elevated" },
  { at: 70, tone: "destructive", label: "Critical" },
]

const heartRateBands: GaugeThreshold[] = [
  { at: 30, tone: "warning", label: "Low" },
  { at: 60, tone: "success", label: "Normal" },
  { at: 100, tone: "warning", label: "Elevated" },
  { at: 140, tone: "destructive", label: "High" },
]

export default function GaugeDemo() {
  const [risk, setRisk] = React.useState(72)

  return (
    <div className="flex w-full flex-col gap-8">
      <section className="flex flex-col gap-3">
        <span className="eyebrow text-muted-foreground">
          Security posture: risk score ring
        </span>
        <div className="flex flex-wrap items-start gap-8">
          <Gauge
            label="Account risk"
            value={risk}
            thresholds={riskBands}
            hint="Scored from 128 signals"
          />
          <div className="w-56 pt-8">
            <Slider
              aria-label="Risk score"
              min={0}
              max={100}
              value={[risk]}
              onValueChange={(v) => setRisk(v[0])}
            />
          </div>
        </div>
      </section>
      <section className="flex flex-col gap-3">
        <span className="eyebrow text-muted-foreground">
          Vitals: arc with units
        </span>
        <div className="flex flex-wrap items-start gap-8">
          <Gauge
            variant="arc"
            label="Heart rate"
            value={88}
            min={30}
            max={180}
            unit="bpm"
            thresholds={heartRateBands}
            hint="Resting, last 5 min"
          />
          <Gauge
            variant="arc"
            size="sm"
            label="Grid load"
            value={0.64}
            min={0}
            max={1}
            unit="of capacity"
            formatValue={(v) =>
              new Intl.NumberFormat("en", { style: "percent" }).format(v)
            }
          />
        </div>
      </section>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/gauge. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# ETA Indicator

Estimated time with a range bar, confidence word and icon, and stale and past-window states.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/eta-indicator
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { EtaIndicator } from "@/components/ui/eta-indicator"
```

## Dependencies

- npm: `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/badge`, `@opendraft/motion`

## Props and types

```ts
type EtaConfidenceLevel = "high" | "medium" | "low"

type EtaLabels = {
  eta: string
  earliest: string
  latest: string
  confidence: string
  high: string
  medium: string
  low: string
  stale: string
  late: string
  unknown: string
  /** "Updated 12 min ago" */
  updated: (ago: string) => string
}

type DateInput = string | number | Date

type EtaIndicatorProps = Omit<React.ComponentProps<"div">, "children"> & {
  eta: DateInput
  /** Start of the plausible window. Pair with `latest` to show the range bar. */
  earliest?: DateInput
  latest?: DateInput
  /** 0 to 1. */
  confidence?: number
  /** `confidence` at or above these values reads as high / medium. */
  confidenceLevels?: { high: number; medium: number }
  /** When the estimate was last refreshed. */
  updatedAt?: DateInput
  /** Current time. Pass it for tests and stories; otherwise it ticks each minute. */
  now?: DateInput
  /** Estimates older than this are marked stale. Defaults to 15 minutes. */
  staleAfterMs?: number
  /** IANA zone, e.g. "Europe/Berlin". Defaults to the viewer's zone. */
  timeZone?: string
  locale?: string
  /** Show the zone abbreviation next to times. Defaults to true. */
  showTimeZone?: boolean
  /** What is being estimated, e.g. "Delivery", "Doctor arrives". */
  title?: React.ReactNode
  labels?: Partial<EtaLabels>
}
```

## Example

```tsx
"use client"

import { EtaIndicator } from "@/components/ui/eta-indicator"

const NOW = "2026-03-14T14:00:00Z"

export default function EtaIndicatorDemo() {
  return (
    <div className="grid w-full max-w-[720px] gap-4 min-[600px]:grid-cols-2">
      <EtaIndicator
        title="Parcel delivery"
        now={NOW}
        eta="2026-03-14T15:20:00Z"
        earliest="2026-03-14T14:50:00Z"
        latest="2026-03-14T16:30:00Z"
        confidence={0.82}
        updatedAt="2026-03-14T13:56:00Z"
        timeZone="Europe/Berlin"
      />
      <EtaIndicator
        title="Clinician arrival"
        now={NOW}
        eta="2026-03-14T14:35:00Z"
        earliest="2026-03-14T14:20:00Z"
        latest="2026-03-14T15:30:00Z"
        confidence={0.41}
        updatedAt="2026-03-14T13:20:00Z"
        timeZone="America/New_York"
        labels={{ eta: "Expected on site", stale: "Out of date" }}
      />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/eta-indicator. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Secret Input

Masked input with reveal, copy and optional auto-hide, for API keys, tokens and sensitive fields.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/secret-input
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { SecretInput } from "@/components/ui/secret-input"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/input`, `@opendraft/button`

## Props and types

```ts
type SecretInputLabels = {
  show: string
  hide: string
  copy: string
  copied: string
  /** Announced when the value is hidden again automatically. */
  autoHidden: string
}

type SecretInputProps = Omit<
  React.ComponentProps<"input">,
  "value" | "defaultValue" | "onChange" | "type"
> & {
  value?: string
  defaultValue?: string
  onChange?: (value: string) => void
  /** Character used to mask the value while hidden. A custom character makes the hidden field read-only. */
  mask?: string
  /** Show a copy button. */
  copyable?: boolean
  /** Hide the value again after this many milliseconds. 0 disables. */
  autoHideMs?: number
  /** Fixed accessible name for the field. Never include the secret itself. */
  "aria-label"?: string
  labels?: Partial<SecretInputLabels>
  /** Called after a successful copy. */
  onCopy?: () => void
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { Field } from "@/components/ui/field"
import { SecretInput } from "@/components/ui/secret-input"

export default function SecretInputDemo() {
  const [token, setToken] = React.useState("tok_live_8f3a91c2d7b04e65")
  return (
    <div className="flex w-full max-w-md flex-col gap-6">
      <Field label="Access token" hint="Hides itself after 10 seconds.">
        {(c) => (
          <SecretInput
            {...c}
            value={token}
            onChange={setToken}
            autoHideMs={10000}
          />
        )}
      </Field>
      <Field label="National ID number" hint="Masked with a custom character.">
        {(c) => (
          <SecretInput
            {...c}
            defaultValue="482-19-7730"
            mask="*"
            copyable={false}
            labels={{ show: "Reveal number", hide: "Hide number" }}
          />
        )}
      </Field>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/secret-input. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# MFA Step

Multi-factor step: code entry, method switcher, resend countdown, and verifying, error and locked states.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/mfa-step
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { MfaStep } from "@/components/ui/mfa-step"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/otp-input`, `@opendraft/button`

## Props and types

```ts
type MfaMethod = {
  id: string
  /** Short name shown in the switcher, e.g. "Authenticator app". */
  label: string
  /** Instruction under the title while this method is active. */
  description?: React.ReactNode
  /** Where a code was sent, e.g. a masked phone number. Shown with the description. */
  destination?: string
  /** Number of characters in the code. Defaults to 6. */
  codeLength?: number
  /** Accepted characters. Defaults to numeric. */
  pattern?: "numeric" | "alphanumeric"
  /** Whether a new code can be requested for this method. */
  resendable?: boolean
}

type MfaVerifyResult = boolean | void

type MfaStepLabels = {
  title: string
  codeLabel: string
  verify: string
  verifying: string
  switchMethod: string
  resend: string
  /** Template for the countdown; `{seconds}` is replaced. */
  resendIn: string
  resent: string
  invalidCode: string
  failed: string
  lockedTitle: string
  lockedDescription: string
}

type MfaStepProps = Omit<
  React.ComponentProps<"section">,
  "onSubmit" | "title"
> & {
  methods?: MfaMethod[]
  method?: string
  defaultMethod?: string
  onMethodChange?: (id: string) => void
  /**
   * Resolve to verify. Return false or throw to show an error. The code is
   * submitted automatically once every cell is filled.
   */
  onVerify: (code: string, method: string) => Promise<MfaVerifyResult>
  /** Request a new code. Restarts the countdown. */
  onResend?: (method: string) => void | Promise<void>
  /** Seconds before a code can be requested again. */
  resendIn?: number
  /** Locks the step, e.g. after too many failed attempts. */
  locked?: boolean
  /** Error from outside, shown instead of the local one. */
  error?: React.ReactNode
  labels?: Partial<MfaStepLabels>
}
```

## Example

```tsx
"use client"

import { MfaStep, type MfaMethod } from "@/components/ui/mfa-step"

const wait = (ms: number) => new Promise<void>((r) => setTimeout(r, ms))

const BANK_METHODS: MfaMethod[] = [
  {
    id: "app",
    label: "Authenticator",
    description: "Open your authenticator app and enter the current code.",
  },
  {
    id: "sms",
    label: "SMS",
    description: "We texted a code to",
    destination: "•••• 4417",
    resendable: true,
  },
]

const CLINIC_METHODS: MfaMethod[] = [
  {
    id: "email",
    label: "Email",
    description: "Enter the 8-character code sent to",
    destination: "j•••@example.com",
    codeLength: 8,
    pattern: "alphanumeric",
    resendable: true,
  },
  {
    id: "backup",
    label: "Recovery code",
    description: "Use one of the recovery codes you saved.",
    codeLength: 10,
    pattern: "alphanumeric",
  },
]

export default function MfaStepDemo() {
  return (
    <div className="grid w-full gap-10 md:grid-cols-2">
      <MfaStep
        methods={BANK_METHODS}
        resendIn={20}
        onVerify={async (code) => {
          await wait(700)
          return code === "123456"
        }}
        onResend={() => wait(300)}
        labels={{ title: "Confirm this payment" }}
      />
      <MfaStep
        methods={CLINIC_METHODS}
        resendIn={45}
        onVerify={async () => {
          await wait(700)
          throw new Error("This code has expired.")
        }}
        onResend={() => wait(300)}
        labels={{ title: "Open patient record", verify: "Continue" }}
      />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/mfa-step. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Permission Matrix

Roles by permissions grid with groups, select-all, indeterminate states, read-only roles and a change summary.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/permission-matrix
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { PermissionMatrix } from "@/components/ui/permission-matrix"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/checkbox`, `@opendraft/button`

## Props and types

```ts
type PermissionRole = {
  id: string
  label: string
  description?: string
  /** Column can be viewed but not changed. */
  readOnly?: boolean
}

type PermissionItem = {
  id: string
  label: string
  description?: string
}

type PermissionGroup = {
  label: string
  items: PermissionItem[]
}

/** Map of role id to the permission ids it holds. */
type PermissionValue = Record<string, string[]>

type PermissionMatrixLabels = {
  permission: string
  allRoles: string
  readOnly: string
  /** `{permission}` and `{role}` are replaced. */
  cell: string
  /** `{role}` is replaced. */
  selectRole: string
  /** `{permission}` is replaced. */
  selectRow: string
  /** `{group}` and `{role}` are replaced. */
  selectGroup: string
  noChanges: string
  /** `{added}` and `{removed}` are replaced. */
  summary: string
  /** `{more}` is replaced. */
  moreChanges: string
  granted: string
  revoked: string
  reset: string
  empty: string
}

type PermissionMatrixProps = Omit<
  React.ComponentProps<"div">,
  "defaultValue" | "onChange"
> & {
  roles?: PermissionRole[]
  groups?: PermissionGroup[]
  value?: PermissionValue
  defaultValue?: PermissionValue
  onValueChange?: (value: PermissionValue) => void
  /** Saved state to compare against. Defaults to the value on mount. */
  baseline?: PermissionValue
  /** Disable every cell. */
  readOnly?: boolean
  /** Show the change summary below the grid. */
  showSummary?: boolean
  /** Accessible name for the grid. */
  "aria-label"?: string
  labels?: Partial<PermissionMatrixLabels>
}
```

## Example

```tsx
"use client"

import {
  PermissionMatrix,
  type PermissionGroup,
  type PermissionRole,
  type PermissionValue,
} from "@/components/ui/permission-matrix"

const FLEET_ROLES: PermissionRole[] = [
  { id: "owner", label: "Owner", readOnly: true },
  { id: "dispatcher", label: "Dispatcher" },
  { id: "driver", label: "Driver" },
  { id: "auditor", label: "Auditor" },
]
const FLEET_GROUPS: PermissionGroup[] = [
  {
    label: "Shipments",
    items: [
      { id: "ship.view", label: "View shipments" },
      {
        id: "ship.assign",
        label: "Assign drivers",
        description: "Dispatch only",
      },
      { id: "ship.cancel", label: "Cancel shipments" },
    ],
  },
  {
    label: "Vehicles",
    items: [
      { id: "veh.view", label: "View vehicles" },
      { id: "veh.service", label: "Log service" },
    ],
  },
]
const FLEET_VALUE: PermissionValue = {
  owner: ["ship.view", "ship.assign", "ship.cancel", "veh.view", "veh.service"],
  dispatcher: ["ship.view", "ship.assign", "veh.view"],
  driver: ["ship.view", "veh.view", "veh.service"],
  auditor: ["ship.view", "veh.view"],
}

const HR_ROLES: PermissionRole[] = [
  { id: "hr", label: "HR partner" },
  { id: "manager", label: "Manager" },
  { id: "employee", label: "Employee" },
]
const HR_GROUPS: PermissionGroup[] = [
  {
    label: "Compensation",
    items: [
      { id: "pay.view", label: "View salary bands" },
      { id: "pay.edit", label: "Adjust salary" },
    ],
  },
  {
    label: "Time off",
    items: [
      { id: "leave.request", label: "Request leave" },
      { id: "leave.approve", label: "Approve leave" },
    ],
  },
]

export default function PermissionMatrixDemo() {
  return (
    <div className="flex w-full flex-col gap-10">
      <PermissionMatrix
        aria-label="Fleet permissions"
        roles={FLEET_ROLES}
        groups={FLEET_GROUPS}
        defaultValue={FLEET_VALUE}
      />
      <PermissionMatrix
        aria-label="HR permissions"
        roles={HR_ROLES}
        groups={HR_GROUPS}
        defaultValue={{
          hr: ["pay.view", "pay.edit", "leave.approve"],
          manager: ["leave.request", "leave.approve"],
          employee: ["leave.request"],
        }}
        labels={{
          permission: "Capability",
          summary: "{added} added, {removed} removed",
        }}
      />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/permission-matrix. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Signature Pad

Canvas signature capture with undo, clear and a typed-name alternative, for delivery, consent and sign-off.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/signature-pad
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { SignaturePad } from "@/components/ui/signature-pad"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/input`

## Props and types

```ts
type SignaturePadMode = "draw" | "type"

type SignaturePadLabels = {
  /** Visible label above the pad. */
  label: string
  /** Placeholder shown while the pad is empty. */
  empty: string
  clear: string
  undo: string
  /** Confirm button, shown when `onSign` is set. */
  sign: string
  draw: string
  type: string
  typedLabel: string
  typedPlaceholder: string
  /** Accessible name of the drawing surface. */
  canvas: string
  /** Live announcement once a signature exists. */
  captured: string
  /** Live announcement after clearing. */
  cleared: string
}

type SignaturePadResult = {
  dataUrl: string
  mode: SignaturePadMode
  /** The typed name, when mode is "type". */
  name?: string
}

type SignaturePadProps = Omit<
  React.ComponentProps<"div">,
  "onChange" | "children"
> & {
  /** Called with a PNG data URL after each stroke, undo or typed change, or null when empty. */
  onChange?: (dataUrl: string | null) => void
  /** Called when the person confirms with the sign button. The button is hidden when omitted. */
  onSign?: (result: SignaturePadResult) => void
  /** Offer a typed-name alternative for keyboard and assistive-tech users. */
  allowTyped?: boolean
  disabled?: boolean
  /** Stroke width in CSS pixels. */
  strokeWidth?: number
  /** Height of the drawing surface in CSS pixels. */
  height?: number
  labels?: Partial<SignaturePadLabels>
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { SignaturePad } from "@/components/ui/signature-pad"

export default function SignaturePadDemo() {
  const [delivery, setDelivery] = React.useState<string | null>(null)
  const [consent, setConsent] = React.useState<string | null>(null)

  return (
    <div className="grid w-full max-w-3xl gap-8 sm:grid-cols-2">
      <section className="flex flex-col gap-3">
        <h3 className="heading text-xl">Proof of delivery</h3>
        <SignaturePad
          labels={{
            label: "Recipient signature",
            empty: "Recipient signs here",
            sign: "Confirm delivery",
          }}
          onChange={setDelivery}
          onSign={() => {}}
        />
        <p className="font-mono text-xs text-muted-foreground">
          {delivery ? "Captured" : "Waiting for signature"}
        </p>
      </section>
      <section className="flex flex-col gap-3">
        <h3 className="heading text-xl">Patient consent</h3>
        <SignaturePad
          allowTyped
          labels={{
            label: "Patient or guardian",
            empty: "Sign to consent",
            typedLabel: "Type the patient's full name",
            sign: "Give consent",
          }}
          onChange={setConsent}
          onSign={() => {}}
        />
        <p className="font-mono text-xs text-muted-foreground">
          {consent ? "Captured" : "Waiting for consent"}
        </p>
      </section>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/signature-pad. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Photo Capture

Take or pick photos with thumbnails, remove, a max count and optional captions.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/photo-capture
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { PhotoCapture } from "@/components/ui/photo-capture"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/input`

## Props and types

```ts
type CapturedPhoto = {
  id: string
  file: File
  caption: string
}

type PhotoCaptureLabels = {
  /** Visible label above the control. */
  label: string
  /** Button that opens the device camera. */
  take: string
  /** Button that opens the file picker. */
  choose: string
  /** Shown while there are no photos. */
  empty: string
  captionLabel: string
  captionPlaceholder: string
  /** Prefix of the remove button's accessible name, followed by the file name. */
  remove: string
  /** Shown when `max` is reached. */
  limitReached: string
  /** Live announcement after adding photos. */
  added: string
  /** Live announcement after removing a photo. */
  removed: string
}

type PhotoCaptureProps = Omit<
  React.ComponentProps<"div">,
  "onChange" | "children"
> & {
  /** Maximum number of photos. Further picks are ignored and the buttons disable. */
  max?: number
  /** Show a caption field under each photo. */
  captions?: boolean
  /** Which camera to prefer on phones. */
  facing?: "environment" | "user"
  /** Same syntax as the input `accept` attribute. */
  accept?: string
  disabled?: boolean
  /** Fires on add, remove and caption edits. `files` is the plain list; `photos` carries captions. */
  onChange?: (files: File[], photos: CapturedPhoto[]) => void
  labels?: Partial<PhotoCaptureLabels>
}
```

## Example

```tsx
"use client"

import { PhotoCapture } from "@/components/ui/photo-capture"

export default function PhotoCaptureDemo() {
  return (
    <div className="grid w-full max-w-3xl gap-8 sm:grid-cols-2">
      <section className="flex flex-col gap-3">
        <h3 className="heading text-xl">Site inspection</h3>
        <PhotoCapture
          captions
          max={6}
          labels={{
            label: "Evidence photos",
            empty: "Add photos of the defect",
            captionPlaceholder: "What does this show?",
          }}
        />
      </section>
      <section className="flex flex-col gap-3">
        <h3 className="heading text-xl">Parcel condition</h3>
        <PhotoCapture
          max={3}
          labels={{
            label: "Delivery photos",
            take: "Photo of parcel",
            choose: "Pick from gallery",
            empty: "No delivery photos",
          }}
        />
      </section>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/photo-capture. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Step Navigation

Non-linear lesson and step navigation with complete, current, available and locked states.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/step-nav
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { StepNav } from "@/components/ui/step-nav"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/progress`

## Props and types

```ts
type StepNavStatus = "complete" | "current" | "locked" | "available"

type StepNavStep = {
  id: string
  label: string
  description?: string
  /** Defaults to "current" for the `current` id and "available" otherwise. */
  status?: StepNavStatus
  /** Why the step is locked. Shown as text and announced. */
  lockedReason?: string
}

type StepNavLabels = {
  navigation: string
  /** Template for the summary. `{done}` and `{total}` are replaced. */
  summary: string
  complete: string
  current: string
  available: string
  locked: string
  /** Fallback reason when a locked step has none. */
  lockedReason: string
}

type StepNavProps = Omit<
  React.ComponentProps<"nav">,
  "children" | "onSelect"
> & {
  steps: StepNavStep[]
  /** Id of the current step. Used for steps without an explicit status. */
  current?: string
  onSelect?: (step: StepNavStep, index: number) => void
  /** `auto` is vertical in narrow containers and horizontal from 42rem up. */
  orientation?: "auto" | "vertical" | "horizontal"
  /** Show the "n of m" summary and bar. */
  showProgress?: boolean
  labels?: Partial<StepNavLabels>
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { StepNav, type StepNavStep } from "@/components/ui/step-nav"

const lessons: StepNavStep[] = [
  {
    id: "l1",
    label: "Lesson 1",
    description: "Getting started",
    status: "complete",
  },
  {
    id: "l2",
    label: "Lesson 2",
    description: "Core ideas",
    status: "complete",
  },
  { id: "l3", label: "Lesson 3", description: "Worked examples" },
  {
    id: "l4",
    label: "Lesson 4",
    description: "Final quiz",
    status: "locked",
    lockedReason: "Pass lesson 3 to unlock",
  },
]

const onboarding: StepNavStep[] = [
  {
    id: "docs",
    label: "Identity check",
    description: "Upload documents",
    status: "complete",
  },
  { id: "policy", label: "Policy review", description: "Read and accept" },
  {
    id: "equipment",
    label: "Equipment",
    description: "Request devices",
    status: "locked",
    lockedReason: "Awaiting manager approval",
  },
]

export default function StepNavDemo() {
  const [lesson, setLesson] = React.useState("l3")
  const [task, setTask] = React.useState("policy")

  return (
    <div className="flex w-full max-w-3xl flex-col gap-10">
      <section className="flex flex-col gap-3">
        <h3 className="heading text-xl">Course lessons</h3>
        <StepNav
          steps={lessons}
          current={lesson}
          onSelect={(s) => setLesson(s.id)}
          labels={{ navigation: "Lessons" }}
        />
      </section>
      <section className="flex flex-col gap-3">
        <h3 className="heading text-xl">Employee onboarding</h3>
        <StepNav
          orientation="vertical"
          steps={onboarding}
          current={task}
          onSelect={(s) => setTask(s.id)}
          labels={{
            navigation: "Onboarding tasks",
            summary: "{done} of {total} tasks done",
          }}
        />
      </section>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/step-nav. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Time Series Chart

Multi-series time chart with time zones, brush zoom, thresholds, gaps, keyboard stepping and a data-table fallback.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/time-series-chart
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { TimeSeriesChart } from "@/components/ui/time-series-chart"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`

## Props and types

```ts
type TimeSeriesPoint = {
  /** Timestamp: epoch milliseconds, a Date, or an ISO string. */
  t: number | Date | string
  /** `null` (or NaN) is a gap: the line breaks, nothing is interpolated. */
  v: number | null
}

type TimeSeries = {
  id: string
  label: string
  points: TimeSeriesPoint[]
  /** Overrides the chart-level `unit` for this series. */
  unit?: string
  /** Any CSS color value or token, e.g. `var(--brand)`. Defaults by order. */
  color?: string
  /** SVG dash pattern, e.g. "6 3". Defaults by order so lines differ without color. */
  dash?: string
}

type ThresholdTone = "neutral" | "warning" | "destructive" | "success" | "brand"

type TimeSeriesThreshold = {
  id: string
  /** Visible text on the chart, e.g. "Limit 80%". Always shown. */
  label: string
  /** Line position, or the lower edge of a band. */
  value: number
  /** When set, draws a band between `value` and `to` instead of a line. */
  to?: number
  tone?: ThresholdTone
}

type TimeSeriesLabels = {
  legend: string
  resetZoom: string
  dataTable: string
  time: string
  noData: string
  /** Screen reader hint for the focusable plot. */
  instructions: string
  zoomed: string
  empty: string
  /** Builds the live readout text. */
  readout: (time: string, parts: { label: string; value: string }[]) => string
}

type TimeSeriesChartProps = Omit<
  React.ComponentProps<"div">,
  "children" | "onChange"
> & {
  series?: TimeSeries[]
  /** IANA time zone used for every axis, tooltip and table label. Defaults to UTC. */
  timeZone?: string
  /** BCP 47 locale for date and number formatting. */
  locale?: string
  /** Suffix for values, e.g. "%" or "MW". Ignored when `formatValue` is set. */
  unit?: string
  formatValue?: (value: number, series: TimeSeries) => string
  thresholds?: TimeSeriesThreshold[]
  /** Fixed y bounds; leave a side undefined to fit the data. */
  yDomain?: [number | undefined, number | undefined]
  /** Plot height in px. */
  height?: number
  /** Accessible name of the chart. */
  title?: string
  labels?: Partial<TimeSeriesLabels>
  onZoomChange?: (range: [number, number] | null) => void
}
```

## Example

```tsx
"use client"

import {
  TimeSeriesChart,
  type TimeSeries,
  type TimeSeriesThreshold,
} from "@/components/ui/time-series-chart"

const START = Date.UTC(2025, 2, 10, 0, 0, 0)
const MINUTE = 60_000

function build(
  id: string,
  label: string,
  count: number,
  step: number,
  fn: (i: number) => number,
  gap?: [number, number]
): TimeSeries {
  return {
    id,
    label,
    points: Array.from({ length: count }, (_, i) => ({
      t: START + i * step,
      v: gap && i >= gap[0] && i <= gap[1] ? null : Math.round(fn(i) * 10) / 10,
    })),
  }
}

const serverSeries: TimeSeries[] = [
  build(
    "cpu",
    "CPU",
    97,
    15 * MINUTE,
    (i) => 38 + 30 * Math.sin(i / 9) ** 2 + (i % 5)
  ),
  build(
    "mem",
    "Memory",
    97,
    15 * MINUTE,
    (i) => 55 + i / 8 + 4 * Math.sin(i / 4),
    [40, 47]
  ),
  build("disk", "Disk", 97, 15 * MINUTE, (i) => 24 + i / 20),
]
const serverThresholds: TimeSeriesThreshold[] = [
  { id: "warn", label: "Warning 70%", value: 70, tone: "warning" },
  { id: "crit", label: "Critical 90%", value: 90, tone: "destructive" },
]

const loadSeries: TimeSeries[] = [
  build(
    "grid",
    "Grid import",
    48,
    60 * MINUTE,
    (i) => 310 + 120 * Math.sin((i - 6) / 3.8)
  ),
  build("solar", "Solar", 48, 60 * MINUTE, (i) =>
    Math.max(0, 260 * Math.sin((((i % 24) - 6) / 12) * Math.PI))
  ),
]
const loadThresholds: TimeSeriesThreshold[] = [
  {
    id: "peak",
    label: "Peak tariff band",
    value: 380,
    to: 450,
    tone: "warning",
  },
  { id: "cap", label: "Contract cap 450 kW", value: 450, tone: "destructive" },
]

export default function TimeSeriesChartDemo() {
  return (
    <div className="grid w-full gap-10">
      <section className="grid gap-3">
        <h3 className="heading text-xl">Server metrics</h3>
        <TimeSeriesChart
          title="Server utilisation, 24 hours"
          series={serverSeries}
          thresholds={serverThresholds}
          unit="%"
          yDomain={[0, 100]}
          timeZone="Europe/Berlin"
        />
      </section>
      <section className="grid gap-3">
        <h3 className="heading text-xl">Energy load</h3>
        <TimeSeriesChart
          title="Site power, 48 hours"
          series={loadSeries}
          thresholds={loadThresholds}
          unit="kW"
          timeZone="America/New_York"
          formatValue={(v) => `${Math.round(v)} kW`}
          labels={{ legend: "Sources", resetZoom: "Show full range" }}
        />
      </section>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/time-series-chart. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Seat Map

Grid seat picker for aircraft, venues and transport with five seat states, a max selection and arrow-key navigation.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/seat-map
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { SeatMap } from "@/components/ui/seat-map"
```

## Dependencies

- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
type SeatState = "available" | "selected" | "occupied" | "blocked" | "premium"

type SeatInfo = {
  /** Defaults to "available". "selected" is derived from the selection. */
  state?: Exclude<SeatState, "selected">
  /** Price in the smallest display unit you pass to `formatValue`. */
  price?: number
  /** Free text tier name, e.g. "Exit row" or "Circle". Shown in the readout. */
  tier?: string
}

/**
 * Layout rows, one string per row. `s` is a seat, `.` an aisle (narrow gap),
 * `_` an empty cell the size of a seat (a missing seat, a pillar).
 */
type SeatLayoutObject = {
  rows: string[]
  /** One label per row; defaults to A, B, C... */
  rowLabels?: string[]
  /** One label per grid column (aisles included, ignored for them); defaults to 1, 2, 3... counted per row. */
  columnLabels?: string[]
}

type SeatLayout = string[] | SeatLayoutObject

type SeatMapLabels = {
  legend: string
  front: string
  available: string
  selected: string
  occupied: string
  blocked: string
  premium: string
  none: string
  total: string
  maxReached: (max: number) => string
  /** Row label shown to assistive tech. */
  row: (label: string) => string
  /** Accessible description of one seat. */
  seat: (p: {
    id: string
    stateLabel: string
    price?: string
    tier?: string
  }) => string
  map: string
}

type SeatMapChange = { id: string; row: number; col: number } & SeatInfo

type SeatMapProps = Omit<
  React.ComponentProps<"div">,
  "onChange" | "defaultValue" | "children"
> & {
  layout?: SeatLayout
  /** Per-seat info by seat id (row label + column label, e.g. "12A"). */
  seats?: Record<string, SeatInfo>
  /** Computed alternative to `seats`; takes precedence when it returns a value. */
  getSeat?: (id: string, row: number, col: number) => SeatInfo | undefined
  /** Controlled selection (seat ids). */
  value?: string[]
  defaultValue?: string[]
  /** Maximum selectable seats. With 1, picking another seat replaces the first. */
  max?: number
  onChange?: (ids: string[], seats: SeatMapChange[]) => void
  /** Formats prices. Defaults to `Intl` with `currency` if given, else plain number. */
  formatValue?: (value: number) => string
  currency?: string
  locale?: string
  /** Hide the legend or the selection summary. */
  showLegend?: boolean
  showSummary?: boolean
  readOnly?: boolean
  labels?: Partial<SeatMapLabels>
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { SeatMap, type SeatInfo } from "@/components/ui/seat-map"

const cabinRows = Array.from({ length: 10 }, (_, i) => String(i + 1))
const cabin = {
  rows: cabinRows.map(() => "sss.sss"),
  rowLabels: cabinRows,
  columnLabels: ["A", "B", "C", ".", "D", "E", "F"],
}
const cabinSeats: Record<string, SeatInfo> = {}
for (const r of ["1", "2"])
  for (const c of ["A", "B", "C", "D", "E", "F"])
    cabinSeats[`${r}${c}`] = {
      state: "premium",
      price: 45,
      tier: "Extra legroom",
    }
for (const id of ["3B", "3C", "4A", "6E", "6F", "7D", "9A"])
  cabinSeats[id] = { state: "occupied" }
for (const id of ["5A", "5F"]) cabinSeats[id] = { state: "blocked" }
for (const r of ["3", "4", "5", "6", "7", "8", "9", "10"])
  for (const c of ["A", "B", "C", "D", "E", "F"])
    cabinSeats[`${r}${c}`] ??= { price: 18 }

const theatre = {
  rows: [
    "__ssssssss__",
    "_ssssssssss_",
    "ssss.ss.ssss",
    "ssss.ss.ssss",
    "ssss.ss.ssss",
    "ssss.ss.ssss",
  ],
  rowLabels: ["A", "B", "C", "D", "E", "F"],
}
const theatreSeats: Record<string, SeatInfo> = {}
for (const r of ["C", "D"])
  for (let n = 1; n <= 10; n++)
    theatreSeats[`${r}${n}`] = { state: "premium", price: 60, tier: "Stalls" }
for (const id of ["D4", "D5", "E2", "F9", "F10", "B6"])
  theatreSeats[id] = { state: "occupied" }
theatreSeats.A1 = { state: "blocked" }

export default function SeatMapDemo() {
  const [cabinPick, setCabinPick] = React.useState<string[]>(["2C"])
  return (
    <div className="grid w-full gap-12">
      <section className="grid gap-3">
        <h3 className="heading text-xl">Aircraft cabin</h3>
        <SeatMap
          layout={cabin}
          seats={cabinSeats}
          value={cabinPick}
          onChange={setCabinPick}
          max={3}
          currency="EUR"
          locale="en-GB"
          labels={{ front: "Cockpit", premium: "Extra legroom" }}
        />
      </section>
      <section className="grid gap-3">
        <h3 className="heading text-xl">Theatre</h3>
        <SeatMap
          layout={theatre}
          seats={theatreSeats}
          max={4}
          formatValue={(n) => `$${n.toFixed(2)}`}
          labels={{
            front: "Stage",
            premium: "Best view",
            row: (l) => `Row ${l}`,
          }}
        />
      </section>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/seat-map. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Product Card

Product card and responsive grid with price, compare-at price, text badges, rating slot and an out-of-stock state.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/product-card
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { ProductCard, ProductGrid } from "@/components/ui/product-card"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/badge`, `@opendraft/button`, `@opendraft/empty-state`

## Props and types

```ts
export type ProductCardLabels = {
  /** Badge shown when `isNew` is set. */
  new: string
  /** Badge shown when `compareAtPrice` is higher than `price`. */
  sale: string
  soldOut: string
  /** Button text; the product title is appended to the accessible name. */
  add: string
  /** Screen-reader text before the original price. */
  was: string
  /** Screen-reader text before the current price. */
  now: string
  /** Shown in the image area when there is no image. */
  noImage: string
}

export type ProductBadge = {
  label: string
  variant?: "default" | "secondary" | "outline" | "brand" | "success"
}

export type ProductCardProps = Omit<
  React.ComponentProps<"article">,
  "title" | "onSelect"
> & {
  title: string
  subtitle?: React.ReactNode
  /** Plain `<img>`; works in any React app. Ignored when `renderImage` is set. */
  image?: { src: string; alt: string; srcSet?: string; sizes?: string }
  /** Replaces the `<img>`, e.g. to render your framework's image component. */
  renderImage?: (props: { className: string }) => React.ReactNode
  price: number
  compareAtPrice?: number
  /** ISO 4217 code used with Intl when `formatValue` is not given. */
  currency?: string
  locale?: string
  /** Full control of price text. Overrides `currency` and `locale`. */
  formatValue?: (value: number) => string
  isNew?: boolean
  /** Extra badges (e.g. "Low stock", "Refurbished"). Text, never color alone. */
  badges?: ProductBadge[]
  /** Slot under the subtitle: stars, review count, any rating UI. */
  rating?: React.ReactNode
  /** Extra content under the price (swatches, stock note, delivery). */
  meta?: React.ReactNode
  outOfStock?: boolean
  onAdd?: () => void
  /** Makes the whole card activatable through the title. */
  onSelect?: () => void
  /** Renders the title as a link instead of a button. Takes priority over `onSelect`. */
  href?: string
  labels?: Partial<ProductCardLabels>
}

export type ProductGridLabels = {
  emptyTitle: string
  emptyDescription: string
}

export type ProductGridProps = React.ComponentProps<"div"> & {
  /** Label for the list, read by screen readers. */
  "aria-label"?: string
  /** Shown instead of the grid when there are no children. */
  empty?: React.ReactNode
  labels?: Partial<ProductGridLabels>
}
```

## Example

```tsx
"use client"

import * as React from "react"
import { Star } from "lucide-react"

import { ProductCard, ProductGrid } from "@/components/ui/product-card"

function art(label: string, shade: number) {
  const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 500"><rect width="400" height="500" fill="hsl(220 8% ${shade}%)"/><text x="200" y="256" font-family="monospace" font-size="20" text-anchor="middle" fill="hsl(220 8% 40%)">${label}</text></svg>`
  return `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`
}

function Rating({ value, count }: { value: number; count: number }) {
  return (
    <p className="flex items-center gap-1 text-xs text-muted-foreground">
      <Star aria-hidden className="size-3 fill-current" />
      <span className="font-mono">
        <span className="sr-only">Rated </span>
        {value.toFixed(1)}
        <span className="sr-only"> out of 5, </span> ({count})
      </span>
    </p>
  )
}

const apparel = [
  {
    id: 1,
    title: "Linen overshirt",
    subtitle: "Sand, 6 sizes",
    price: 89,
    was: 120,
    isNew: false,
    rating: [4.6, 128] as const,
  },
  {
    id: 2,
    title: "Wool crew sweater",
    subtitle: "Charcoal",
    price: 110,
    isNew: true,
    rating: [4.8, 41] as const,
  },
  {
    id: 3,
    title: "Canvas tote",
    subtitle: "One size",
    price: 38,
    out: true,
    rating: [4.2, 9] as const,
  },
  {
    id: 4,
    title: "Selvedge jeans",
    subtitle: "Indigo, straight",
    price: 145,
    rating: [4.7, 76] as const,
  },
]

const electronics = [
  {
    id: 1,
    title: "Noise-cancelling headphones",
    subtitle: "40 h battery",
    price: 249.99,
    was: 299.99,
    rating: [4.5, 2310] as const,
  },
  {
    id: 2,
    title: "27-inch 4K monitor",
    subtitle: "USB-C, 60 W",
    price: 429,
    isNew: true,
    rating: [4.4, 318] as const,
  },
  {
    id: 3,
    title: "Mechanical keyboard",
    subtitle: "Hot-swap switches",
    price: 129,
    out: true,
    rating: [4.9, 87] as const,
  },
]

export default function ProductCardDemo() {
  const [added, setAdded] = React.useState<string | null>(null)

  return (
    <div className="flex w-full flex-col gap-10">
      <section className="flex flex-col gap-3">
        <h3 className="eyebrow">Apparel store</h3>
        <ProductGrid aria-label="Apparel">
          {apparel.map((p, i) => (
            <ProductCard
              key={p.id}
              title={p.title}
              subtitle={p.subtitle}
              image={{
                src: art(p.title, 90 - i * 4),
                alt: `${p.title}, product photo`,
              }}
              price={p.price}
              compareAtPrice={p.was}
              currency="GBP"
              locale="en-GB"
              isNew={p.isNew}
              outOfStock={p.out}
              rating={<Rating value={p.rating[0]} count={p.rating[1]} />}
              onAdd={() => setAdded(p.title)}
              onSelect={() => setAdded(`Opened ${p.title}`)}
            />
          ))}
        </ProductGrid>
      </section>

      <section className="flex flex-col gap-3">
        <h3 className="eyebrow">Electronics</h3>
        <ProductGrid aria-label="Electronics">
          {electronics.map((p, i) => (
            <ProductCard
              key={p.id}
              title={p.title}
              subtitle={p.subtitle}
              image={{ src: art(p.title, 86 - i * 4), alt: p.title }}
              price={p.price}
              compareAtPrice={p.was}
              currency="USD"
              locale="en-US"
              isNew={p.isNew}
              outOfStock={p.out}
              badges={i === 0 ? [{ label: "Free shipping" }] : undefined}
              rating={<Rating value={p.rating[0]} count={p.rating[1]} />}
              labels={{ add: "Add to cart", soldOut: "Sold out" }}
              onAdd={() => setAdded(p.title)}
            />
          ))}
        </ProductGrid>
      </section>

      <section className="flex flex-col gap-3">
        <h3 className="eyebrow">Empty</h3>
        <ProductGrid
          labels={{
            emptyTitle: "No results",
            emptyDescription: "Try fewer filters.",
          }}
        />
      </section>

      <p aria-live="polite" className="font-mono text-xs text-muted-foreground">
        {added ? `Last action: ${added}` : "Press Add or a title."}
      </p>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/product-card. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Image Gallery

Main image with thumbnails, keyboard and swipe navigation and a click-to-zoom lightbox.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/image-gallery
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { ImageGallery } from "@/components/ui/image-gallery"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/dialog`

## Props and types

```ts
export type GalleryImage = {
  src: string
  /** Required. Describe the image; use "" only for purely decorative ones. */
  alt: string
  /** Smaller source for the thumbnail strip. Defaults to `src`. */
  thumb?: string
}

export type ImageGalleryLabels = {
  previous: string
  next: string
  zoom: string
  /** Lightbox title (screen readers). */
  lightbox: string
  lightboxDescription: string
  /** Text for the counter, e.g. "2 / 5". */
  counter: (current: number, total: number) => string
  thumbnail: (current: number, total: number) => string
  empty: string
  toggleZoom: string
}

export type ImageGalleryProps = Omit<
  React.ComponentProps<"div">,
  "children" | "onChange"
> & {
  images: GalleryImage[]
  /** Controlled index. */
  index?: number
  defaultIndex?: number
  onIndexChange?: (index: number) => void
  /** Aspect ratio of the main frame as a CSS value. Default "4 / 3". */
  aspect?: string
  /** Disable the zoom lightbox. */
  zoomable?: boolean
  labels?: Partial<ImageGalleryLabels>
}
```

## Example

```tsx
import { ImageGallery, type GalleryImage } from "@/components/ui/image-gallery"

function art(label: string, shade: number): string {
  const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 600"><rect width="800" height="600" fill="hsl(220 8% ${shade}%)"/><text x="400" y="306" font-family="monospace" font-size="32" text-anchor="middle" fill="hsl(220 8% 40%)">${label}</text></svg>`
  return `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`
}

const apparel: GalleryImage[] = ["Front", "Back", "Detail", "Worn"].map(
  (v, i) => ({
    src: art(`Overshirt - ${v}`, 92 - i * 5),
    alt: `Linen overshirt, ${v.toLowerCase()} view`,
  })
)

const property: GalleryImage[] = ["Living room", "Kitchen", "Bedroom"].map(
  (v, i) => ({ src: art(v, 88 - i * 5), alt: `${v} of the apartment` })
)

export default function ImageGalleryDemo() {
  return (
    <div className="@container grid w-full grid-cols-1 gap-8 md:grid-cols-2">
      <div className="flex flex-col gap-3">
        <h3 className="eyebrow">Apparel product</h3>
        <ImageGallery images={apparel} aspect="4 / 5" className="max-w-sm" />
      </div>
      <div className="flex flex-col gap-3">
        <h3 className="eyebrow">Property listing</h3>
        <ImageGallery
          images={property}
          labels={{
            counter: (c, t) => `Photo ${c} of ${t}`,
            zoom: "Open photo viewer",
            next: "Next photo",
            previous: "Previous photo",
          }}
        />
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/image-gallery. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Address Form

Shipping or billing address form with per-country rules, validation and correct autocomplete tokens.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/address-form
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { AddressForm } from "@/components/ui/address-form"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/field`, `@opendraft/input`, `@opendraft/select`

## Props and types

```ts
export type AddressValue = {
  line1: string
  line2: string
  city: string
  region: string
  postal: string
  /** Country code, matching `countries[].code`. */
  country: string
}

export type AddressField = keyof AddressValue

export type AddressCountry = { code: string; name: string }

export type AddressRule = {
  postalLabel?: string
  regionLabel?: string
  /** Postal code must match this (tested on the trimmed value). */
  postalPattern?: RegExp
  /** Shown as placeholder and in the invalid message hint, e.g. "SW1A 1AA". */
  postalExample?: string
  /** Default true. Set false where regions are not part of addresses. */
  regionRequired?: boolean
  /** Renders region as a select instead of free text. */
  regionOptions?: { value: string; label: string }[]
  /** Default true. */
  postalRequired?: boolean
}

export type AddressFormLabels = {
  line1: string
  line2: string
  city: string
  region: string
  postal: string
  country: string
  optional: string
  selectCountry: string
  selectRegion: string
  submit: string
  required: (field: string) => string
  invalidPostal: (field: string, example?: string) => string
}

export type AddressErrors = Partial<Record<AddressField, string>>

export type AddressFormProps = Omit<
  React.ComponentProps<"form">,
  "onSubmit" | "onChange" | "defaultValue"
> & {
  /** Controlled value. */
  value?: AddressValue
  defaultValue?: Partial<AddressValue>
  onChange?: (value: AddressValue) => void
  /** Called with a valid address. May return a promise; the button shows loading until it settles. */
  onSubmit?: (value: AddressValue) => void | Promise<void>
  countries?: AddressCountry[]
  /** Per-country-code overrides merged over `DEFAULT_ADDRESS_RULE`. */
  rules?: Record<string, AddressRule>
  /** Prefixes autocomplete tokens: "shipping" gives "shipping address-line1". */
  section?: "shipping" | "billing"
  /** Replaces the default submit button. */
  footer?: React.ReactNode
  disabled?: boolean
  labels?: Partial<AddressFormLabels>
}
```

## Example

```tsx
"use client"

import * as React from "react"

import {
  AddressForm,
  SAMPLE_ADDRESS_COUNTRIES,
  SAMPLE_ADDRESS_RULES,
  type AddressValue,
} from "@/components/ui/address-form"

export default function AddressFormDemo() {
  const [saved, setSaved] = React.useState<AddressValue | null>(null)
  const [billing, setBilling] = React.useState<AddressValue>({
    line1: "",
    line2: "",
    city: "",
    region: "",
    postal: "",
    country: "US",
  })

  return (
    <div className="grid w-full grid-cols-1 gap-10 lg:grid-cols-2">
      <div className="flex flex-col gap-4">
        <h3 className="eyebrow">Shipping, United Kingdom</h3>
        <AddressForm
          section="shipping"
          defaultValue={{ country: "GB" }}
          countries={SAMPLE_ADDRESS_COUNTRIES}
          rules={SAMPLE_ADDRESS_RULES}
          labels={{ submit: "Deliver here" }}
          onSubmit={(v) => setSaved(v)}
        />
        <p
          aria-live="polite"
          className="font-mono text-xs text-muted-foreground"
        >
          {saved
            ? JSON.stringify(saved)
            : "Uncontrolled. Submit to see the value."}
        </p>
      </div>
      <div className="flex flex-col gap-4">
        <h3 className="eyebrow">Billing, United States (controlled)</h3>
        <AddressForm
          section="billing"
          value={billing}
          onChange={setBilling}
          countries={SAMPLE_ADDRESS_COUNTRIES}
          rules={{
            ...SAMPLE_ADDRESS_RULES,
            US: {
              ...SAMPLE_ADDRESS_RULES.US,
              regionOptions: [
                { value: "CA", label: "California" },
                { value: "NY", label: "New York" },
                { value: "TX", label: "Texas" },
              ],
            },
          }}
          labels={{ submit: "Save billing address", line1: "Street address" }}
        />
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/address-form. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Video Player

Accessible video player with seek, volume, speed, captions, chapters, keyboard shortcuts and an error state.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/video-player
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { VideoPlayer } from "@/components/ui/video-player"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/dropdown-menu`, `@opendraft/slider`, `@opendraft/kbd`, `@opendraft/scrub-bar`

## Props and types

```ts
type VideoChapter = {
  /** Start of the chapter, in seconds. */
  time: number
  label: string
}

type VideoCaptionTrack = {
  /** URL of a WebVTT file. */
  src: string
  /** Shown in the captions menu, e.g. "English". */
  label: string
  /** BCP 47 language tag, e.g. "en". */
  srcLang?: string
  kind?: "captions" | "subtitles"
  /** Show this track at first. */
  default?: boolean
}

type VideoPlayerLabels = {
  player: string
  play: string
  pause: string
  seek: string
  mute: string
  unmute: string
  volume: string
  speed: string
  normalSpeed: string
  captions: string
  captionsOff: string
  fullscreen: string
  exitFullscreen: string
  shortcuts: string
  shortcutsHint: string
  shortcutPlay: string
  shortcutSeek: string
  shortcutVolume: string
  shortcutMute: string
  shortcutFullscreen: string
  shortcutCaptions: string
  chapters: string
  error: string
  retry: string
  loading: string
  playing: string
  paused: string
}

type VideoPlayerProps = Omit<
  React.ComponentProps<"div">,
  "children" | "title" | "onProgress"
> & {
  /** URL of the video file or stream the browser can play. */
  src: string
  /** Image shown before playback starts. */
  poster?: string
  /** Heading above the video. Also names the player for assistive tech. */
  title?: React.ReactNode
  /** Short text under the title, e.g. a date or an owner. */
  description?: React.ReactNode
  /** WebVTT caption or subtitle tracks. Adds a captions control when given. */
  tracks?: VideoCaptionTrack[]
  /** Named positions in the video. Rendered as a list that seeks, and as ticks on the seek bar. */
  chapters?: VideoChapter[]
  /** Reports the position in seconds: every `progressInterval` seconds while playing, and on pause and end. Use it to save where the viewer stopped. */
  onProgress?: (seconds: number) => void
  /** Seconds between `onProgress` calls while playing. Defaults to 5. */
  progressInterval?: number
  /** Position in seconds to resume from once the video is ready. */
  startAt?: number
  /** Called when the video fails to load or decode. */
  onError?: () => void
  /** Selectable playback rates. */
  speeds?: readonly number[]
  /** Fixed copy. Merged over neutral English defaults. */
  labels?: Partial<VideoPlayerLabels>
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { formatTimestamp } from "@/components/agents/scrub-bar"
import { VideoPlayer } from "@/components/ui/video-player"

// The sources below are placeholders and may 404. The player then shows its
// error state with a retry button instead of a blank frame.
export default function VideoPlayerDemo() {
  const [trainingSeconds, setTrainingSeconds] = React.useState(0)
  const [briefingSeconds, setBriefingSeconds] = React.useState(0)

  return (
    <div className="flex w-full max-w-[960px] flex-col gap-10">
      <section className="flex flex-col gap-3">
        <p className="eyebrow">Training video</p>
        <VideoPlayer
          src="https://example.com/media/forklift-safety-training.mp4"
          poster="https://example.com/media/forklift-safety-training.jpg"
          title="Forklift safety, module 2"
          description="Warehouse operations onboarding"
          tracks={[
            { src: "/media/forklift-en.vtt", label: "English", srcLang: "en" },
            { src: "/media/forklift-es.vtt", label: "Español", srcLang: "es" },
          ]}
          chapters={[
            { time: 0, label: "Pre-shift inspection" },
            { time: 95, label: "Load limits and stability" },
            { time: 240, label: "Pedestrian zones" },
            { time: 410, label: "Parking and charging" },
          ]}
          onProgress={setTrainingSeconds}
        />
        <p className="font-mono text-xs text-muted-foreground">
          Saved position {formatTimestamp(trainingSeconds)}
        </p>
      </section>

      <section className="flex flex-col gap-3">
        <p className="eyebrow">Surgical briefing</p>
        <VideoPlayer
          src="https://example.com/media/procedure-briefing.mp4"
          title="Laparoscopic cholecystectomy briefing"
          description="Pre-operative team review"
          tracks={[
            {
              src: "/media/briefing-en.vtt",
              label: "English",
              srcLang: "en",
              default: true,
            },
          ]}
          chapters={[
            { time: 0, label: "Patient and consent" },
            { time: 60, label: "Equipment check" },
            { time: 150, label: "Approach and ports" },
            { time: 330, label: "Contingencies" },
          ]}
          speeds={[0.75, 1, 1.5]}
          onProgress={setBriefingSeconds}
          labels={{
            error:
              "The briefing recording is unavailable. Contact the surgical coordinator.",
          }}
        />
        <p className="font-mono text-xs text-muted-foreground">
          Reviewed up to {formatTimestamp(briefingSeconds)}
        </p>
      </section>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/video-player. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Document Viewer

Shell for paged documents: page nav, zoom, download, search and sidebar slots, plus thumbnails and outline.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/document-viewer
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { DocumentViewer, DocumentThumbnails, DocumentOutline } from "@/components/ui/document-viewer"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`

## Props and types

```ts
type DocumentViewerLabels = {
  document: string
  toolbar: string
  previousPage: string
  nextPage: string
  pageNumber: string
  /** Visible "of N" text and the spoken page status. */
  pageOf: (page: number, pageCount: number | undefined) => string
  zoomIn: string
  zoomOut: string
  resetZoom: string
  download: string
  thumbnails: string
  toggleThumbnails: string
  fallback: string
  fallbackLink: string
  emptyPage: string
}

type DocumentViewerProps = Omit<
  React.ComponentProps<"div">,
  "children" | "title"
> & {
  /** Name of the document, shown in the toolbar and used for the accessible name. */
  title?: React.ReactNode
  /**
   * URL of a PDF. Used by the default renderer (an `<object>` with a fallback
   * link) and as the default download link. Not needed when `renderPage` is given.
   */
  src?: string
  /**
   * Draws one page. Receives the 1-based page number and the current scale
   * (1 = 100%). Use it to plug in pdf.js, page images, or generated pages.
   *
   * pdf.js through react-pdf is the recommended renderer for real PDFs: it
   * gives text selection, search and per-page rendering, and keeps the viewer
   * free of a PDF dependency. See the docs example for the wiring.
   */
  renderPage?: (pageNumber: number, scale: number) => React.ReactNode
  /** Total pages. Required with `renderPage`; optional with `src`. */
  pageCount?: number
  /** Current page, 1-based. Controlled. */
  page?: number
  defaultPage?: number
  onPageChange?: (page: number) => void
  /** Current scale, 1 = 100%. Controlled. */
  zoom?: number
  defaultZoom?: number
  onZoomChange?: (zoom: number) => void
  minZoom?: number
  maxZoom?: number
  zoomStep?: number
  /** Download link. Defaults to `src`. Pass `false` to hide the button. */
  downloadHref?: string | false
  /** File name suggested for the download. */
  downloadName?: string
  /** Search UI, rendered in the toolbar. Bring your own input and results. */
  search?: React.ReactNode
  /** Extra toolbar actions, rendered after the download button. */
  actions?: React.ReactNode
  /**
   * Sidebar content, usually `DocumentThumbnails` or `DocumentOutline`. A
   * toggle appears in the toolbar when this is given.
   */
  thumbnails?: React.ReactNode
  /** Whether the sidebar starts open. Defaults to true. */
  defaultThumbnailsOpen?: boolean
  /** Fixed copy. Merged over neutral English defaults. */
  labels?: Partial<DocumentViewerLabels>
}

type DocumentThumbnailsProps = Omit<
  React.ComponentProps<"ol">,
  "children" | "onChange"
> & {
  pageCount: number
  page: number
  onPageChange: (page: number) => void
  /** Draws a small preview of one page. Defaults to an empty sheet with its number. */
  renderThumbnail?: (pageNumber: number) => React.ReactNode
  /** Builds the accessible name of each button. */
  pageLabel?: (pageNumber: number) => string
}

type OutlineItem = {
  id: string
  label: React.ReactNode
  /** Page this section starts on, shown on the right. */
  page?: number
  children?: OutlineItem[]
}

type DocumentOutlineProps = Omit<
  React.ComponentProps<"nav">,
  "children" | "onSelect"
> & {
  items: OutlineItem[]
  /** Id of the current section. Marked with `aria-current`. */
  activeId?: string
  onSelect?: (item: OutlineItem) => void
  /** Whether sections with children start open. Defaults to true. */
  defaultExpanded?: boolean
  /** Heading above the list. Pass `false` to hide. */
  heading?: React.ReactNode | false
  labels?: Partial<{ expand: string; collapse: string }>
}
```

## Example

```tsx
"use client"

import * as React from "react"
import { Search } from "lucide-react"

import {
  DocumentOutline,
  DocumentThumbnails,
  DocumentViewer,
  type OutlineItem,
} from "@/components/ui/document-viewer"

/*
 * Real PDFs: use pdf.js through react-pdf (recommended). Install it in your
 * app, then plug it into `renderPage`. DocumentViewer itself has no PDF
 * dependency.
 *
 *   import { Document, Page, pdfjs } from "react-pdf"
 *   pdfjs.GlobalWorkerOptions.workerSrc = new URL(
 *     "pdfjs-dist/build/pdf.worker.min.mjs",
 *     import.meta.url
 *   ).toString()
 *
 *   <Document file={url} onLoadSuccess={({ numPages }) => setCount(numPages)}>
 *     <DocumentViewer
 *       pageCount={count}
 *       page={page}
 *       onPageChange={setPage}
 *       src={url}
 *       renderPage={(n, scale) => <Page pageNumber={n} scale={scale} />}
 *     />
 *   </Document>
 *
 * Page images work the same way: renderPage={(n) => <img src={pages[n - 1]} alt="" />}
 */

const CONTRACT_PAGES = 6
const CONTRACT_OUTLINE: OutlineItem[] = [
  { id: "parties", label: "Parties", page: 1 },
  {
    id: "terms",
    label: "Terms",
    page: 2,
    children: [
      { id: "term", label: "Term and renewal", page: 2 },
      { id: "fees", label: "Fees", page: 3 },
    ],
  },
  { id: "liability", label: "Liability", page: 5 },
  { id: "signatures", label: "Signatures", page: 6 },
]

const HANDBOOK_OUTLINE: OutlineItem[] = [
  { id: "welcome", label: "Welcome", page: 1 },
  {
    id: "time-off",
    label: "Time off",
    page: 4,
    children: [
      { id: "leave", label: "Annual leave", page: 4 },
      { id: "sick", label: "Sick leave", page: 6 },
    ],
  },
  { id: "conduct", label: "Code of conduct", page: 9 },
]

// Plain generated pages: stand-ins for pdf.js output.
function GeneratedPage({
  n,
  scale,
  name,
}: {
  n: number
  scale: number
  name: string
}) {
  return (
    <div
      className="flex flex-col gap-3 bg-background p-8"
      style={{ width: 480 * scale, minHeight: 640 * scale }}
    >
      <p className="eyebrow">{name}</p>
      <p className="heading text-2xl">Page {n}</p>
      {Array.from({ length: 8 }, (_, i) => (
        <div
          key={i}
          className="h-2 bg-muted"
          style={{ width: `${95 - ((i * 7) % 30)}%` }}
        />
      ))}
    </div>
  )
}

export default function DocumentViewerDemo() {
  const [contractPage, setContractPage] = React.useState(1)
  const [handbookPage, setHandbookPage] = React.useState(1)

  return (
    <div className="flex w-full flex-col gap-10">
      <section className="flex flex-col gap-3">
        <p className="eyebrow">Contract review</p>
        <div className="h-[560px] w-full overflow-hidden">
          <DocumentViewer
            title="Services agreement"
            pageCount={CONTRACT_PAGES}
            page={contractPage}
            onPageChange={setContractPage}
            downloadHref="https://example.com/files/services-agreement.pdf"
            downloadName="services-agreement.pdf"
            renderPage={(n, scale) => (
              <GeneratedPage n={n} scale={scale} name="Services agreement" />
            )}
            search={
              <label className="flex h-8 items-center gap-1.5 border bg-background px-2">
                <Search
                  aria-hidden
                  className="size-3.5 text-muted-foreground"
                />
                <input
                  type="search"
                  aria-label="Search the document"
                  placeholder="Search"
                  className="w-28 bg-transparent text-sm outline-none"
                />
              </label>
            }
            thumbnails={
              <>
                <DocumentOutline
                  items={CONTRACT_OUTLINE}
                  onSelect={(item) => item.page && setContractPage(item.page)}
                />
                <DocumentThumbnails
                  pageCount={CONTRACT_PAGES}
                  page={contractPage}
                  onPageChange={setContractPage}
                />
              </>
            }
          />
        </div>
      </section>

      <section className="flex flex-col gap-3">
        <p className="eyebrow">HR handbook</p>
        <div className="h-[560px] w-full overflow-hidden">
          {/* No renderPage: the default renderer shows the PDF natively,
              or a fallback link when the file cannot load. */}
          <DocumentViewer
            title="Employee handbook"
            src="https://example.com/files/employee-handbook.pdf"
            pageCount={24}
            page={handbookPage}
            onPageChange={setHandbookPage}
            thumbnails={
              <DocumentOutline
                items={HANDBOOK_OUTLINE}
                onSelect={(item) => item.page && setHandbookPage(item.page)}
                activeId={
                  [
                    ...HANDBOOK_OUTLINE.flatMap((i) => [
                      i,
                      ...(i.children ?? []),
                    ]),
                  ]
                    .filter((i) => (i.page ?? 99) <= handbookPage)
                    .at(-1)?.id
                }
              />
            }
            labels={{
              fallback: "The handbook could not be displayed in this browser.",
            }}
          />
        </div>
      </section>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/document-viewer. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Date Time Picker

Pick a date and time in a named time zone, with DST gap and overlap handling and other-zone display.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/date-time-picker
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { DateTimePicker } from "@/components/ui/date-time-picker"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/input`, `@opendraft/popover`, `@opendraft/select`

## Props and types

```ts
type Wall = { y: number; mo: number; d: number; hh: number; mm: number }

type DateTimePickerLabels = {
  placeholder: string
  chooseDate: string
  time: string
  hours: string
  minutes: string
  am: string
  pm: string
  amPm: string
  timeZone: string
  previousMonth: string
  nextMonth: string
  alsoShowing: string
  /** Placeholders: {time} (requested), {adjusted} (used), {zone}. */
  gap: string
  /** Placeholders: {time} (the allowed time used). */
  clamped: string
  /** Placeholder: {zone}. */
  ambiguous: string
  earlier: string
  later: string
}

type ZoneOption = string | { value: string; label?: string }

type AlsoShowZone = string | { timeZone: string; label?: string }

type DateTimeChangeMeta = {
  /** IANA zone the person was working in. */
  timeZone: string
  /** Wall-clock time in that zone, `YYYY-MM-DDTHH:mm`. */
  local: string
  /** UTC offset at that instant, `+HH:mm`. */
  offset: string
  /** Short zone name as Intl renders it for the locale (EDT, GMT+1, ...). */
  abbreviation: string
  /** Set when the requested time was moved: skipped by DST, or out of range. */
  adjusted?: "gap" | "clamped"
}

type DateTimePickerProps = Omit<
  React.ComponentProps<"button">,
  "value" | "defaultValue" | "onChange" | "type"
> & {
  /** Instant as an ISO string with an offset (`2026-03-08T07:30:00Z`). A bare local ISO string is read in `timeZone`. */
  value?: string
  defaultValue?: string
  /** Called with the UTC instant (`toISOString()`) and the zone-local detail. */
  onChange?: (isoUtc: string, meta: DateTimeChangeMeta) => void
  /** IANA zone the date and time are written in. Controlled when set. */
  timeZone?: string
  /** Initial zone when `timeZone` is not controlled. */
  defaultTimeZone?: string
  onTimeZoneChange?: (timeZone: string) => void
  /** Zones offered in a selector. Omit to lock the picker to one zone. */
  timeZones?: ZoneOption[]
  /** Show the same instant in these other zones. */
  alsoShow?: AlsoShowZone[]
  /** BCP 47 locale. Also decides 12 or 24 hour unless `hourCycle` is set. */
  locale?: string
  hourCycle?: 12 | 24
  /** Minute increment for the time field and arrow keys. */
  minuteStep?: number
  /** Earliest allowed instant (ISO with offset). */
  min?: string
  /** Latest allowed instant (ISO with offset). */
  max?: string
  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6
  /** Wall time used when a day is picked and no time is set. `HH:MM`. */
  defaultTime?: string
  /** Which occurrence to use when a wall time happens twice (clocks go back). */
  overlap?: "earlier" | "later"
  labels?: Partial<DateTimePickerLabels>
  placeholder?: string
  disabled?: boolean
  invalid?: boolean
  align?: "start" | "center" | "end"
}
```

## Example

```tsx
"use client"

import * as React from "react"

import {
  DateTimePicker,
  SAMPLE_TIME_ZONES,
  type DateTimeChangeMeta,
} from "@/components/ui/date-time-picker"
import { Label } from "@/components/ui/label"

export default function DateTimePickerDemo() {
  // Domain 1: a departure time, written in the departure airport's zone.
  const [departure, setDeparture] = React.useState<string | undefined>(
    "2026-11-21T14:40:00Z"
  )
  // Domain 2: a clinic appointment, with a selectable zone and a DST-day value.
  const [visit, setVisit] = React.useState<string | undefined>(
    "2026-03-08T14:30:00Z"
  )
  const [meta, setMeta] = React.useState<DateTimeChangeMeta | null>(null)

  return (
    <div className="grid w-full max-w-3xl gap-8 sm:grid-cols-2">
      <div className="flex flex-col gap-2">
        <Label htmlFor="dtp-departure">Scheduled departure</Label>
        <DateTimePicker
          id="dtp-departure"
          value={departure}
          onChange={(iso) => setDeparture(iso)}
          timeZone="Europe/London"
          alsoShow={[
            { timeZone: "America/New_York", label: "Arrival city" },
            "UTC",
          ]}
          locale="en-GB"
          minuteStep={5}
          min="2026-11-01T00:00:00Z"
          max="2027-03-31T23:59:00Z"
        />
        <span className="font-mono text-xs text-muted-foreground tabular-nums">
          value = {departure ?? "undefined"}
        </span>
      </div>
      <div className="flex flex-col gap-2">
        <Label htmlFor="dtp-visit">Appointment</Label>
        <DateTimePicker
          id="dtp-visit"
          value={visit}
          onChange={(iso, m) => {
            setVisit(iso)
            setMeta(m)
          }}
          defaultTimeZone="America/New_York"
          timeZones={SAMPLE_TIME_ZONES}
          alsoShow={["Europe/Berlin"]}
          locale="en-US"
          minuteStep={15}
          defaultTime="10:00"
        />
        <span className="font-mono text-xs text-muted-foreground tabular-nums">
          local = {meta?.local ?? "-"} {meta?.offset ?? ""}
        </span>
        <span className="text-xs text-muted-foreground">
          Try 02:30 on 8 March (skipped by DST) or 01:30 on 1 November (happens
          twice).
        </span>
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/date-time-picker. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Rating

Star rating display and input with half steps, plus a distribution breakdown.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/rating
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Rating, RatingBreakdown, RatingInput } from "@/components/ui/rating"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
type RatingSize = "sm" | "default" | "lg"

type RatingLabels = {
  /** aria-label of a display rating. {value}, {max}. */
  summary: string
  /** Visible suffix after the number. {max}. Use "" to hide. */
  outOf: string
  /** Count text, plural. {count}. */
  count: string
  /** Count text when the count is 1. {count}. */
  countOne: string
  /** aria-label of one input option. {value}, {max}. */
  option: string
  /** aria-label of the input group. */
  group: string
  /** Shown by the input when nothing is chosen. */
  none: string
}

type RatingProps = Omit<React.ComponentProps<"div">, "children"> & {
  /** Average or score, 0 to `max`. Fractions are drawn by clipping. */
  value: number
  max?: number
  size?: RatingSize
  /** Show the number (and "out of max"). Default true. */
  showValue?: boolean
  /** Decimal places for the number. Default 1. */
  precision?: number
  /** Number of ratings behind the value. */
  count?: number
  locale?: string
  labels?: Partial<RatingLabels>
}

type RatingInputProps = Omit<
  React.ComponentProps<"div">,
  "defaultValue" | "onChange" | "children"
> & {
  value?: number
  defaultValue?: number
  onValueChange?: (value: number) => void
  max?: number
  size?: RatingSize
  /** Allow half steps (0.5, 1, 1.5 ...). */
  allowHalf?: boolean
  /** Clicking the chosen value again clears it to 0. */
  clearable?: boolean
  disabled?: boolean
  readOnly?: boolean
  required?: boolean
  /** Renders a hidden input so the value posts with a form. */
  name?: string
  /** Show the chosen value as text beside the stars. Default true. */
  showValue?: boolean
  labels?: Partial<RatingLabels>
}

type RatingBreakdownLabels = {
  /** aria-label of the list. */
  group: string
  /** Row summary for assistive tech. {stars}, {count}, {percent}. */
  row: string
}

type RatingBreakdownProps = Omit<React.ComponentProps<"ul">, "children"> & {
  /** Counts per rating, index 0 = 1 star ... index max-1 = max stars. */
  counts?: number[]
  /** Makes each row a button, e.g. to filter a list. */
  onSelectStars?: (stars: number) => void
  /** Highlights the active filter. */
  selectedStars?: number | null
  locale?: string
  labels?: Partial<RatingBreakdownLabels>
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { Rating, RatingBreakdown, RatingInput } from "@/components/ui/rating"

export default function RatingDemo() {
  // Domain 1: product reviews.
  const [filter, setFilter] = React.useState<number | null>(null)
  // Domain 2: course feedback.
  const [score, setScore] = React.useState(3.5)

  return (
    <div className="grid w-full max-w-3xl gap-10 sm:grid-cols-2">
      <section className="flex flex-col gap-4">
        <span className="eyebrow">Product reviews</span>
        <Rating value={4.3} count={1284} size="lg" />
        <RatingBreakdown
          counts={[38, 52, 120, 410, 664]}
          selectedStars={filter}
          onSelectStars={(s) => setFilter((f) => (f === s ? null : s))}
        />
        <p className="font-mono text-xs text-muted-foreground">
          filter = {filter ?? "all"}
        </p>
      </section>
      <section className="flex flex-col gap-4">
        <span className="eyebrow">Course feedback</span>
        <RatingInput
          aria-label="Rate this lesson"
          value={score}
          onValueChange={setScore}
          allowHalf
          clearable
          size="lg"
          name="lesson-rating"
        />
        <Rating
          value={3.8}
          max={5}
          count={1}
          size="sm"
          labels={{ count: "{count} responses", countOne: "{count} response" }}
        />
        <Rating
          value={7.4}
          max={10}
          precision={1}
          showValue
          labels={{ outOf: "of {max} clarity" }}
        />
      </section>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/rating. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Gantt

Task bars on a day, week or month axis with dependency arrows, groups, today marker and critical flags.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/gantt
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Gantt } from "@/components/ui/gantt"
```

## Dependencies

- Registry (installed with it): `@opendraft/utils`, `@opendraft/badge`, `@opendraft/button`

## Props and types

```ts
export type GanttDate = string | Date

export type GanttZoom = "day" | "week" | "month"

export type GanttTone = "default" | "brand" | "success" | "warning"

export type GanttTask = {
  id: string
  label: string
  start: GanttDate
  end: GanttDate
  /** 0-100. Leave out when progress is not tracked (then a task is never "overdue"). */
  progress?: number
  /** Ids of tasks that must finish before this one starts. */
  dependsOn?: string[]
  /** Tasks sharing a group value are listed under one collapsible header. */
  group?: string
  tone?: GanttTone
}

/** Fixed copy. Placeholders in braces: {value} {count} {label} {names}. */
export type GanttLabels = {
  chart: string
  task: string
  zoom: string
  day: string
  week: string
  month: string
  today: string
  critical: string
  overdue: string
  complete: string
  /** Uses {value}. */
  progress: string
  /** Uses {names}. */
  dependsOn: string
  /** Uses {label}. */
  collapse: string
  /** Uses {label}. */
  expand: string
  /** Uses {count}. */
  tasks: string
  noTasks: string
}

export type GanttProps = {
  tasks?: GanttTask[]
  zoom?: GanttZoom
  defaultZoom?: GanttZoom
  onZoomChange?: (zoom: GanttZoom) => void
  /** Group values that are collapsed. */
  collapsed?: string[]
  defaultCollapsed?: string[]
  onCollapsedChange?: (collapsed: string[]) => void
  /** Current time for the today marker and overdue checks. Passed in, never read from the clock. */
  now?: GanttDate
  /**
   * Task ids drawn as critical. Defaults to the chain of driving dependencies that
   * ends at the latest finishing task.
   */
  criticalIds?: string[]
  /** IANA zone for day boundaries and labels. Default "UTC". */
  timeZone?: string
  locale?: string
  onTaskClick?: (task: GanttTask) => void
  labels?: Partial<GanttLabels>
  className?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { Gantt, type GanttTask } from "@/components/ui/gantt"
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"

type Domain = "construction" | "launch"

const CONSTRUCTION: GanttTask[] = [
  {
    id: "c1",
    group: "Site",
    label: "Survey and permits",
    start: "2026-08-17",
    end: "2026-09-04",
    progress: 100,
  },
  {
    id: "c2",
    group: "Site",
    label: "Excavation",
    start: "2026-09-04",
    end: "2026-09-25",
    progress: 100,
    dependsOn: ["c1"],
  },
  {
    id: "c3",
    group: "Structure",
    label: "Foundations",
    start: "2026-09-21",
    end: "2026-10-09",
    progress: 70,
    dependsOn: ["c2"],
  },
  {
    id: "c4",
    group: "Structure",
    label: "Frame",
    start: "2026-10-09",
    end: "2026-11-13",
    progress: 20,
    dependsOn: ["c3"],
  },
  {
    id: "c5",
    group: "Structure",
    label: "Roof",
    start: "2026-11-09",
    end: "2026-11-27",
    progress: 0,
    dependsOn: ["c4"],
  },
  {
    id: "c6",
    group: "Services",
    label: "Plumbing rough-in",
    start: "2026-10-19",
    end: "2026-11-06",
    progress: 10,
    dependsOn: ["c3"],
    tone: "success",
  },
  {
    id: "c7",
    group: "Services",
    label: "Electrical rough-in",
    start: "2026-11-02",
    end: "2026-11-20",
    progress: 0,
    dependsOn: ["c4", "c6"],
    tone: "success",
  },
  {
    id: "c8",
    label: "Handover",
    start: "2026-12-07",
    end: "2026-12-11",
    dependsOn: ["c5", "c7"],
  },
]

const LAUNCH: GanttTask[] = [
  {
    id: "l1",
    group: "Plan",
    label: "Positioning brief",
    start: "2026-09-14",
    end: "2026-09-25",
    progress: 100,
  },
  {
    id: "l2",
    group: "Plan",
    label: "Pricing decision",
    start: "2026-09-21",
    end: "2026-10-02",
    progress: 80,
    dependsOn: ["l1"],
  },
  {
    id: "l3",
    group: "Build",
    label: "Core features",
    start: "2026-09-28",
    end: "2026-10-30",
    progress: 55,
    dependsOn: ["l1"],
  },
  {
    id: "l4",
    group: "Build",
    label: "Beta feedback fixes",
    start: "2026-10-30",
    end: "2026-11-13",
    progress: 0,
    dependsOn: ["l3"],
  },
  {
    id: "l5",
    group: "Market",
    label: "Landing page",
    start: "2026-10-05",
    end: "2026-10-23",
    progress: 40,
    dependsOn: ["l2"],
    tone: "success",
  },
  {
    id: "l6",
    group: "Market",
    label: "Launch campaign",
    start: "2026-11-02",
    end: "2026-11-20",
    progress: 0,
    dependsOn: ["l5", "l4"],
    tone: "success",
  },
  {
    id: "l7",
    label: "Public launch",
    start: "2026-11-20",
    end: "2026-11-23",
    dependsOn: ["l4", "l6"],
  },
]

export default function GanttDemo() {
  const [domain, setDomain] = React.useState<Domain>("construction")
  const [picked, setPicked] = React.useState("")

  return (
    <div className="flex w-full min-w-0 flex-col gap-3">
      <div className="flex flex-wrap items-center gap-3">
        <Tabs value={domain} onValueChange={(v) => setDomain(v as Domain)}>
          <TabsList>
            <TabsTrigger value="construction">Construction plan</TabsTrigger>
            <TabsTrigger value="launch">Product launch</TabsTrigger>
          </TabsList>
        </Tabs>
        <p
          className="font-mono text-xs text-muted-foreground"
          aria-live="polite"
        >
          {picked}
        </p>
      </div>
      <Gantt
        key={domain}
        className="h-[480px]"
        tasks={domain === "construction" ? CONSTRUCTION : LAUNCH}
        now="2026-10-13T12:00:00Z"
        defaultZoom="week"
        onTaskClick={(t) => setPicked(t.label)}
        labels={
          domain === "construction"
            ? { task: "Work package", tasks: "{count} packages" }
            : { task: "Deliverable", tasks: "{count} deliverables" }
        }
      />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/gantt. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Map View

Token-styled MapLibre GL map with focusable markers, routes and areas, and a synced keyboard list, for fleets, outages, assets and stores.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/map-view
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { MapView } from "@/components/ui/map-view"
```

## Dependencies

- npm: `maplibre-gl`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/utils`, `@opendraft/button`, `@opendraft/empty-state`

## Props and types

```ts
type LngLat = [lng: number, lat: number]

type MapStatus = "ok" | "warning" | "critical" | "info" | "offline"

type MapTone = "brand" | "success" | "warning" | "destructive" | "neutral"

type MapViewMarker<T = unknown> = {
  id: string
  lng: number
  lat: number
  /** Visible on hover/focus, used as the accessible name and in the list. */
  label: string
  /** Shown as an icon plus text (never by color alone). */
  status?: MapStatus
  /** Overrides the color implied by `status`. */
  tone?: MapTone
  /** Your own record, handed back to `renderListItem`. */
  data?: T
}

type MapViewRoute = {
  id: string
  coordinates: LngLat[]
  label?: string
  dashed?: boolean
  tone?: MapTone
}

type MapViewArea = {
  id: string
  /** One outer ring; it is closed automatically. */
  coordinates: LngLat[]
  label?: string
  tone?: MapTone
}

type MapViewport = {
  center: LngLat
  zoom: number
  bounds: [LngLat, LngLat]
}

type MapViewLabels = {
  map: string
  loading: string
  list: string
  showList: string
  hideList: string
  zoomIn: string
  zoomOut: string
  fit: string
  empty: string
  routes: string
  areas: string
  selected: string
  errorTitle: string
  errorDescription: string
  count: (n: number) => string
  status: Record<MapStatus, string>
}

type MapViewProps<T = unknown> = Omit<
  React.ComponentProps<"div">,
  "onSelect" | "children"
> & {
  markers?: MapViewMarker<T>[]
  routes?: MapViewRoute[]
  areas?: MapViewArea[]
  /**
   * A MapLibre style URL or object. The default is an inline blank style (one
   * background layer) so the component works offline. Real products pass a tile
   * style, e.g. an OpenFreeMap, Protomaps or MapTiler style URL. Check that
   * provider's terms: most require visible attribution (OpenStreetMap
   * contributors plus the provider), which MapLibre shows in its attribution
   * control. Add `attribution` for sources the style does not declare.
   */
  /**
   * URL of MapLibre's worker file (`maplibre-gl/dist/maplibre-gl-worker.mjs`).
   * Bundlers such as Next/Turbopack and Vite move the library out of
   * node_modules, so its default worker location (next to the bundled chunk)
   * no longer exists. Copy that file to a public path (for example
   * `/maplibre/maplibre-gl-worker.mjs`) and pass the URL here.
   */
  workerUrl?: string
  styleUrl?: string | StyleSpecification
  /** Extra attribution text for the corner control. */
  attribution?: string | string[]
  center?: LngLat
  zoom?: number
  /** Initial/explicit view: [[west, south], [east, north]]. */
  bounds?: [LngLat, LngLat]
  /** Fit the view to markers, routes and areas, and refit when they change. */
  fitToData?: boolean
  selectedId?: string | null
  defaultSelectedId?: string | null
  onSelect?: (id: string | null, marker?: MapViewMarker<T>) => void
  /** Fires when a pan/zoom ends (not on every frame). */
  onMove?: (view: MapViewport) => void
  /** Extra row content in the list (type-safe via `marker.data`). */
  renderListItem?: (marker: MapViewMarker<T>) => React.ReactNode
  /** Start with the list expanded. Default true. */
  defaultListOpen?: boolean
  labels?: Partial<Omit<MapViewLabels, "status">> & {
    status?: Partial<MapViewLabels["status"]>
  }
}

function MapView(props: MapViewProps<T>)
```

## Example

```tsx
"use client"

import * as React from "react"

import { MapView, type MapViewMarker } from "@/components/ui/map-view"
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"

const FLEET: MapViewMarker<{ load: string }>[] = [
  {
    id: "v1",
    lng: 4.9,
    lat: 52.37,
    label: "Unit 101",
    status: "ok",
    data: { load: "12 stops left" },
  },
  {
    id: "v2",
    lng: 4.48,
    lat: 51.92,
    label: "Unit 102",
    status: "warning",
    data: { load: "Delayed 18 min" },
  },
  {
    id: "v3",
    lng: 5.12,
    lat: 52.09,
    label: "Unit 103",
    status: "ok",
    data: { load: "4 stops left" },
  },
  {
    id: "v4",
    lng: 4.3,
    lat: 52.08,
    label: "Depot",
    status: "info",
    data: { load: "Hub" },
  },
]

const FLEET_ROUTES = [
  {
    id: "r1",
    label: "Route A: Depot to Unit 101",
    coordinates: [
      [4.3, 52.08],
      [4.55, 52.2],
      [4.75, 52.3],
      [4.9, 52.37],
    ] as [number, number][],
  },
  {
    id: "r2",
    label: "Route B (planned)",
    dashed: true,
    coordinates: [
      [4.3, 52.08],
      [4.7, 52.02],
      [5.12, 52.09],
    ] as [number, number][],
  },
]

const OUTAGES: MapViewMarker[] = [
  {
    id: "s1",
    lng: -122.43,
    lat: 37.77,
    label: "Substation 1",
    status: "critical",
  },
  { id: "s2", lng: -122.27, lat: 37.8, label: "Substation 2", status: "ok" },
  {
    id: "s3",
    lng: -122.4,
    lat: 37.74,
    label: "Substation 3",
    status: "warning",
  },
  {
    id: "s4",
    lng: -122.48,
    lat: 37.74,
    label: "Substation 4",
    status: "offline",
  },
]

const OUTAGE_AREAS = [
  {
    id: "a1",
    label: "Affected zone 1",
    tone: "destructive" as const,
    coordinates: [
      [-122.46, 37.79],
      [-122.39, 37.8],
      [-122.38, 37.74],
      [-122.45, 37.73],
    ] as [number, number][],
  },
]

export default function MapViewDemo() {
  const [tab, setTab] = React.useState("fleet")
  return (
    <Tabs value={tab} onValueChange={setTab} className="w-full gap-3">
      <TabsList>
        <TabsTrigger value="fleet">Fleet</TabsTrigger>
        <TabsTrigger value="outages">Outages</TabsTrigger>
      </TabsList>
      <TabsContent value="fleet">
        <div className="h-[560px] w-full overflow-hidden rounded-lg border bg-background">
          <MapView
            workerUrl="/maplibre/maplibre-gl-worker.mjs"
            markers={FLEET}
            routes={FLEET_ROUTES}
            fitToData
            defaultSelectedId="v2"
            labels={{ list: "Vehicles", count: (n) => `${n} units` }}
            renderListItem={(m) => (
              <span className="text-xs text-muted-foreground">
                {m.data?.load}
              </span>
            )}
          />
        </div>
      </TabsContent>
      <TabsContent value="outages">
        <div className="h-[560px] w-full overflow-hidden rounded-lg border bg-background">
          <MapView
            workerUrl="/maplibre/maplibre-gl-worker.mjs"
            markers={OUTAGES}
            areas={OUTAGE_AREAS}
            fitToData
            labels={{
              list: "Sites",
              count: (n) => `${n} sites`,
              status: { critical: "Outage", ok: "Online" },
            }}
          />
        </div>
      </TabsContent>
    </Tabs>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/map-view. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Rich Text Editor

Accessible Tiptap editor with a roving toolbar, validated links, character limit and a read-only renderer, for notes, case files and messages.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/rich-text-editor
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { RichTextEditor, RichTextContent } from "@/components/ui/rich-text-editor"
```

## Dependencies

- npm: `@tiptap/react`, `@tiptap/pm`, `@tiptap/starter-kit`, `@tiptap/extension-placeholder`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/input`, `@opendraft/popover`, `@opendraft/tooltip`

## Props and types

```ts
type ToolbarItem =
  | "heading2"
  | "heading3"
  | "bold"
  | "italic"
  | "underline"
  | "strike"
  | "code"
  | "link"
  | "bulletList"
  | "orderedList"
  | "blockquote"
  | "undo"
  | "redo"

type RichTextEditorLabels = {
  toolbar: string
  heading2: string
  heading3: string
  bold: string
  italic: string
  underline: string
  strike: string
  code: string
  link: string
  bulletList: string
  orderedList: string
  blockquote: string
  undo: string
  redo: string
  linkUrl: string
  linkPlaceholder: string
  linkApply: string
  linkRemove: string
  linkInvalid: string
  /** `{count}` is replaced. */
  count: string
  /** `{count}` and `{max}` are replaced. */
  countOfMax: string
  /** `{over}` is replaced. */
  overLimit: string
  submitHint: string
  placeholder: string
}

type RichTextContentProps = Omit<React.ComponentProps<"div">, "children"> & {
  /**
   * HTML to render. It is injected as markup, so it MUST be sanitized on the
   * server first (allow-list tags and http/https/mailto URLs). Never pass
   * unsanitized user input.
   */
  html: string
}

type RichTextEditorProps = Omit<
  React.ComponentProps<"div">,
  "onChange" | "onSubmit" | "defaultValue" | "children"
> & {
  /** Controlled content: an HTML string, or Tiptap JSON when `format="json"`. */
  value?: string | JSONContent
  defaultValue?: string | JSONContent
  /** How `value` / `defaultValue` are expressed. Default "html". */
  format?: "html" | "json"
  /** Called on every edit with both representations. HTML is "" when empty. */
  onChange?: (html: string, json: JSONContent) => void
  /** Called on Ctrl/Cmd + Enter. */
  onSubmit?: (html: string, json: JSONContent) => void
  placeholder?: string
  readOnly?: boolean
  disabled?: boolean
  invalid?: boolean
  /** Minimum height of the writing area, any CSS length. Default 8rem. */
  minHeight?: string | number
  /** Soft limit on characters: typing past it is blocked, pastes show over. */
  maxLength?: number
  /** Which toolbar buttons to show, in order. Default is all. */
  toolbar?: ToolbarItem[]
  /** Hide the character count. */
  hideCount?: boolean
  "aria-label"?: string
  "aria-labelledby"?: string
  "aria-describedby"?: string
  labels?: Partial<RichTextEditorLabels>
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { Button } from "@/components/ui/button"
import { Label } from "@/components/ui/label"
import {
  RichTextContent,
  RichTextEditor,
} from "@/components/ui/rich-text-editor"

const NOTE_SEED =
  "<h2>Site visit, unit 4B</h2><p>Tenant reports a <strong>recurring leak</strong> under the kitchen sink. Moisture reading was elevated near the wall.</p><ul><li>Photograph the pipe joint</li><li>Book plumber for Thursday</li></ul>"

const LESSON_SEED =
  "<p>In this lesson you will learn how to read a simple balance sheet and spot the three numbers that matter most.</p>"

export default function RichTextEditorDemo() {
  const [notes, setNotes] = React.useState<{ id: number; html: string }[]>([])
  const [draft, setDraft] = React.useState(NOTE_SEED)
  const [lesson, setLesson] = React.useState(LESSON_SEED)
  const nextId = React.useRef(1)

  function submit(html: string) {
    if (!html) return
    setNotes((n) => [{ id: nextId.current++, html }, ...n])
    setDraft("")
  }

  return (
    <div className="grid w-full max-w-5xl gap-10 @3xl:grid-cols-2">
      <section className="flex min-w-0 flex-col gap-3">
        <p className="eyebrow">Case file</p>
        <Label id="case-note-label">Add a note to this case</Label>
        <RichTextEditor
          aria-labelledby="case-note-label"
          value={draft}
          onChange={(html) => setDraft(html)}
          onSubmit={submit}
          placeholder="Record what happened, what was said, what comes next…"
          toolbar={[
            "bold",
            "italic",
            "link",
            "bulletList",
            "orderedList",
            "blockquote",
            "undo",
            "redo",
          ]}
        />
        <div className="flex justify-end">
          <Button size="sm" onClick={() => submit(draft)} disabled={!draft}>
            Add note
          </Button>
        </div>
        <ul className="flex flex-col gap-2">
          {notes.map((n) => (
            <li key={n.id} className="rounded-md border p-3">
              {/* Demo only: in a real app, sanitize on the server first. */}
              <RichTextContent html={n.html} />
            </li>
          ))}
        </ul>
      </section>

      <section className="flex min-w-0 flex-col gap-3">
        <p className="eyebrow">Course lesson</p>
        <Label id="lesson-label">Lesson description</Label>
        <RichTextEditor
          aria-labelledby="lesson-label"
          value={lesson}
          onChange={(html) => setLesson(html)}
          maxLength={280}
          minHeight="10rem"
          placeholder="Describe what learners will cover…"
          toolbar={[
            "heading2",
            "heading3",
            "bold",
            "italic",
            "underline",
            "link",
            "bulletList",
            "orderedList",
            "undo",
            "redo",
          ]}
          labels={{
            count: "{count} characters",
            countOfMax: "{count} of {max}",
          }}
        />
      </section>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/rich-text-editor. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Quantity Stepper

Minus, value and plus control with min, max and step, controlled or uncontrolled, with optional press-and-hold repeat.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/quantity-stepper
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { QuantityStepper } from "@/components/ui/quantity-stepper"
```

## Dependencies

- npm: `lucide-react`, `class-variance-authority`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`

## Props and types

```ts
type QuantityStepperProps = Omit<
  React.ComponentProps<"div">,
  "defaultValue" | "onChange"
> & {
  /** Controlled value. */
  value?: number
  /** Initial value when uncontrolled. */
  defaultValue?: number
  onValueChange?: (value: number) => void
  min?: number
  max?: number
  step?: number
  size?: "sm" | "default"
  disabled?: boolean
  /** Hold a button to keep stepping. */
  repeat?: boolean
  /** Accessible name of the group. */
  "aria-label"?: string
  /** Spoken names of the two buttons. */
  decrementLabel?: string
  incrementLabel?: string
}
```

## Variants

- `size`: `sm`, `default` (default)

## Example

```tsx
"use client"

import * as React from "react"

import { QuantityStepper } from "@/components/ui/quantity-stepper"

export default function QuantityStepperDemo() {
  const [qty, setQty] = React.useState(2)

  return (
    <div className="flex flex-wrap items-end gap-x-8 gap-y-5">
      <div className="flex flex-col gap-2">
        <span className="eyebrow">Controlled · 1–10</span>
        <QuantityStepper
          aria-label="Quantity"
          value={qty}
          onValueChange={setQty}
          min={1}
          max={10}
          repeat
        />
        <span className="font-mono text-xs text-muted-foreground tabular-nums">
          value = {qty}
        </span>
      </div>
      <div className="flex flex-col gap-2">
        <span className="eyebrow">Small · step 5</span>
        <QuantityStepper
          aria-label="Seats"
          size="sm"
          defaultValue={10}
          min={0}
          max={50}
          step={5}
        />
      </div>
      <div className="flex flex-col gap-2">
        <span className="eyebrow">Disabled</span>
        <QuantityStepper
          aria-label="Locked quantity"
          defaultValue={3}
          disabled
        />
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/quantity-stepper. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Progress

Horizontal progress bar with a label row and a tone that follows how full or empty it is, for quotas and stock.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/progress
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Progress } from "@/components/ui/progress"
```

## Dependencies

- npm: `motion`, `class-variance-authority`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`

## Props and types

```ts
type ProgressTone = "auto" | "brand" | "success" | "warning" | "destructive"

type ProgressProps = Omit<React.ComponentProps<"div">, "children"> & {
  /** Current value, clamped to 0..max. */
  value: number
  /** Value that represents a full bar. Defaults to 100. */
  max?: number
  /** Accessible name. Falls back to `label` when that is a string. */
  "aria-label"?: string
  /** Left text of the label row. */
  label?: React.ReactNode
  /**
   * Right text of the label row. Defaults to "n of max" when `label` is set.
   * Pass `false` to hide it.
   */
  valueLabel?: React.ReactNode | false
  size?: "sm" | "default" | "lg"
  /**
   * Fill color. `auto` picks by how much headroom is left: brand normally,
   * warning once the remaining fraction drops below `lowThreshold`, destructive
   * below `criticalThreshold`.
   */
  tone?: ProgressTone
  /**
   * For `tone="auto"`. By default the bar measures consumption (a full bar is
   * bad, like quota used). Set `invert` when the value is what remains
   * (stock, availability, battery) so a low value is bad.
   */
  invert?: boolean
  /** Remaining fraction (0..1) below which auto tone turns warning. */
  lowThreshold?: number
  /** Remaining fraction (0..1) at or below which auto tone turns destructive. */
  criticalThreshold?: number
}
```

## Variants

- `size`: `sm`, `default` (default), `lg`

## Example

```tsx
"use client"

import * as React from "react"

import { Progress } from "@/components/ui/progress"
import { Button } from "@/components/ui/button"

export default function ProgressDemo() {
  const [stock, setStock] = React.useState(18)

  return (
    <div className="flex max-w-xl flex-col gap-6">
      <Progress aria-label="Upload" value={64} />
      <Progress
        label="Storage used"
        value={6.2}
        max={10}
        valueLabel="6.2 / 10 GB"
      />
      <div className="flex flex-col gap-3">
        <Progress
          label="Remaining"
          value={stock}
          max={24}
          tone="auto"
          invert
          lowThreshold={0.25}
        />
        <div className="flex gap-2">
          <Button
            size="xs"
            variant="outline"
            onClick={() => setStock((s) => Math.max(0, s - 4))}
          >
            Use 4
          </Button>
          <Button size="xs" variant="outline" onClick={() => setStock(24)}>
            Reset
          </Button>
        </div>
      </div>
      <Progress
        label="Quota"
        value={92}
        tone="auto"
        size="lg"
        valueLabel="92%"
      />
      <div className="grid gap-4 sm:grid-cols-2">
        <Progress size="sm" tone="success" label="Done" value={100} />
        <Progress size="sm" tone="warning" label="Slow" value={40} />
        <Progress size="sm" tone="destructive" label="Failed" value={15} />
        <Progress size="sm" label="Brand" value={55} />
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/progress. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Stat

KPI tile with a label, a large value, a change chip and an optional toggle-button mode, plus a grouped grid.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/stat
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Stat, StatGroup } from "@/components/ui/stat"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/badge`

## Props and types

```ts
type StatDirection = "up" | "down" | "flat"

type StatDelta = {
  value: string
  direction: StatDirection
  /** Which direction is good news. Defaults to "up". */
  goodWhen?: "up" | "down"
}

type StatProps = Omit<React.ComponentProps<"div">, "onClick" | "children"> & {
  label: React.ReactNode
  value: React.ReactNode
  hint?: React.ReactNode
  delta?: StatDelta
  icon?: React.ReactNode
  /** Makes the tile an accessible toggle button. */
  onClick?: () => void
  selected?: boolean
  /** Drop the border and background, e.g. inside a StatGroup. */
  bare?: boolean
}

function StatGroup(props: React.ComponentProps<"div"> & { columns?: 2 | 3 | 4 })
```

## Example

```tsx
"use client"

import * as React from "react"
import { CreditCard, TrendingUp, Users } from "lucide-react"

import { Stat, StatGroup } from "@/components/ui/stat"

const items = [
  {
    id: "revenue",
    label: "Revenue",
    value: "$48,210",
    hint: "vs. previous 30 days",
    delta: { value: "12.4%", direction: "up" as const },
    icon: <CreditCard />,
  },
  {
    id: "users",
    label: "Active users",
    value: "3,982",
    hint: "vs. previous 30 days",
    delta: { value: "0.0%", direction: "flat" as const },
    icon: <Users />,
  },
  {
    id: "churn",
    label: "Churn",
    value: "2.1%",
    hint: "Lower is better",
    delta: {
      value: "0.6%",
      direction: "down" as const,
      goodWhen: "down" as const,
    },
    icon: <TrendingUp />,
  },
]

export default function StatDemo() {
  const [selected, setSelected] = React.useState("revenue")

  return (
    <div className="flex w-full max-w-[640px] flex-col gap-6">
      <div className="grid gap-3 min-[480px]:grid-cols-3">
        {items.map((s) => (
          <Stat
            key={s.id}
            label={s.label}
            value={s.value}
            delta={s.delta}
            icon={s.icon}
            selected={selected === s.id}
            onClick={() => setSelected(s.id)}
          />
        ))}
      </div>
      <StatGroup columns={3}>
        {items.map((s) => (
          <Stat
            key={s.id}
            label={s.label}
            value={s.value}
            hint={s.hint}
            delta={s.delta}
          />
        ))}
      </StatGroup>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/stat. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Empty State

Centered empty block with an optional icon, title, description and action slots, for tables, lists and cards.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/empty-state
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { EmptyState } from "@/components/ui/empty-state"
```

## Dependencies

- npm: `class-variance-authority`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
type EmptyStateProps = Omit<React.ComponentProps<"div">, "title"> &
  VariantProps<typeof emptyStateVariants> & {
    icon?: React.ReactNode
    title: React.ReactNode
    description?: React.ReactNode
    action?: React.ReactNode
    secondaryAction?: React.ReactNode
    /** Announce to assistive tech (role="status"), e.g. for empty search results. */
    live?: boolean
  }
```

## Variants

- `size`: `sm`, `default` (default), `lg`
- `bordered`: `true`, `false` (default)

## Example

```tsx
import { Inbox, Plus, Search } from "lucide-react"

import { Button } from "@/components/ui/button"
import { EmptyState } from "@/components/ui/empty-state"

export default function EmptyStateDemo() {
  return (
    <div className="flex w-full max-w-[640px] flex-col gap-6">
      <EmptyState
        bordered
        icon={<Inbox />}
        title="No items yet"
        description="Items you create will show up here. Start by adding your first one."
        action={
          <Button size="sm">
            <Plus /> New item
          </Button>
        }
        secondaryAction={
          <Button size="sm" variant="outline">
            Import
          </Button>
        }
      />
      <div className="rounded-lg border">
        <EmptyState
          live
          size="sm"
          icon={<Search />}
          title="No results"
          description="Try a different search term or clear your filters."
          action={
            <Button size="sm" variant="outline">
              Clear filters
            </Button>
          }
        />
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/empty-state. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Stepper

Numbered step indicator for multi-step flows like checkout, horizontal or vertical, that never overflows on mobile.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/stepper
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Stepper } from "@/components/ui/stepper"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
type StepperStep = {
  id: string
  label: string
  description?: string
}

type StepperProps = Omit<React.ComponentProps<"nav">, "children"> & {
  steps: StepperStep[]
  /** Index or id of the current step. */
  current: number | string
  /** Called when a completed step is clicked. Only completed steps are interactive. */
  onStepClick?: (step: StepperStep, index: number) => void
  orientation?: "horizontal" | "vertical"
  /**
   * Every step is done: all show a check and none is current. Also implied when
   * `current` is a number >= steps.length.
   */
  complete?: boolean
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { Button } from "@/components/ui/button"
import { Stepper } from "@/components/ui/stepper"

const steps = [
  { id: "cart", label: "Cart", description: "Review items" },
  { id: "shipping", label: "Shipping", description: "Address and method" },
  { id: "payment", label: "Payment", description: "Card details" },
  { id: "confirm", label: "Confirm", description: "Place order" },
]

export default function StepperDemo() {
  const [current, setCurrent] = React.useState(1)

  return (
    <div className="flex w-full max-w-[640px] flex-col gap-8">
      <Stepper
        steps={steps}
        current={current}
        onStepClick={(_, i) => setCurrent(i)}
      />
      <div className="flex gap-2">
        <Button
          variant="outline"
          size="sm"
          disabled={current === 0}
          onClick={() => setCurrent((c) => Math.max(0, c - 1))}
        >
          Back
        </Button>
        <Button
          size="sm"
          disabled={current >= steps.length}
          onClick={() => setCurrent((c) => Math.min(steps.length, c + 1))}
        >
          {current === steps.length - 1 ? "Finish" : "Continue"}
        </Button>
      </div>
      <div className="border-t pt-6">
        <p className="mb-4 eyebrow text-muted-foreground">Vertical</p>
        <Stepper steps={steps} current="payment" orientation="vertical" />
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/stepper. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Theme Toggle

Icon menu that switches between system, light and dark by toggling the dark class, and remembers the choice.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/theme-toggle
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { ThemeToggle } from "@/components/ui/theme-toggle"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/dropdown-menu`

## Props and types

```ts
type ThemePreference = "system" | "light" | "dark"

type ThemeToggleProps = Omit<
  React.ComponentProps<typeof Button>,
  "children" | "onClick"
>
```

## Example

```tsx
"use client"

import { ThemeToggle, useThemePreference } from "@/components/ui/theme-toggle"

export default function ThemeToggleDemo() {
  const [preference] = useThemePreference()

  return (
    <div className="flex w-full max-w-[640px] items-center justify-between gap-4 border p-4">
      <div className="min-w-0">
        <p className="eyebrow text-muted-foreground">Appearance</p>
        <p className="mt-1 text-sm">
          Preference: <span className="font-mono">{preference}</span>
        </p>
      </div>
      <ThemeToggle />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/theme-toggle. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Site Header

Sticky top bar with a brand slot, nav links, an actions slot and a mobile menu.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/site-header
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { SiteHeader } from "@/components/ui/site-header"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`

## Props and types

```ts
type SiteHeaderLink = {
  label: string
  href: string
  active?: boolean
}

type RenderLinkProps = {
  href: string
  className?: string
  children: React.ReactNode
  onClick?: () => void
  "aria-current"?: "page"
}

type SiteHeaderProps = Omit<React.ComponentProps<"header">, "children"> & {
  /** Logo / wordmark, usually wrapped in a link. */
  brand: React.ReactNode
  nav?: SiteHeaderLink[]
  /** Inject a router link (e.g. Next's `Link`). Defaults to a plain `<a>`. */
  renderLink?: (props: RenderLinkProps) => React.ReactNode
  /** Right-hand slot: theme toggle, buttons, avatar. */
  actions?: React.ReactNode
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { Button } from "@/components/ui/button"
import { SiteHeader } from "@/components/ui/site-header"
import { ThemeToggle } from "@/components/ui/theme-toggle"

const links = ["Product", "Pricing", "Docs", "Changelog"]

export default function SiteHeaderDemo() {
  const [active, setActive] = React.useState("Product")

  return (
    <div className="w-full max-w-[640px] overflow-hidden border">
      <SiteHeader
        className="static"
        brand={
          <a href="#" className="font-display text-lg">
            Acme
          </a>
        }
        nav={links.map((label) => ({
          label,
          href: `#${label.toLowerCase()}`,
          active: label === active,
        }))}
        renderLink={({ children, onClick, ...props }) => (
          <a
            {...props}
            onClick={(e) => {
              e.preventDefault()
              setActive(String(children))
              onClick?.()
            }}
          >
            {children}
          </a>
        )}
        actions={
          <>
            <ThemeToggle />
            <Button size="sm" className="hidden sm:inline-flex">
              Sign in
            </Button>
          </>
        }
      />
      <div className="h-32 bg-dots" />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/site-header. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# QR Code

A real, scannable QR code drawn as an inline SVG, readable in light and dark themes.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/qr-code
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { QrCode } from "@/components/ui/qr-code"
```

## Dependencies

- npm: `uqr`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
type QrCodeErrorCorrection = "L" | "M" | "Q" | "H"

type QrCodeProps = Omit<React.ComponentProps<"svg">, "children"> & {
  /** The text or URL to encode. */
  value: string
  /** Rendered width and height in px. */
  size?: number
  /** Error correction level: L 7%, M 15%, Q 25%, H 30%. */
  errorCorrection?: QrCodeErrorCorrection
  /** Accessible name for the code. */
  label?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { Input } from "@/components/ui/input"
import { QrCode, type QrCodeErrorCorrection } from "@/components/ui/qr-code"

const LEVELS: QrCodeErrorCorrection[] = ["L", "M", "Q", "H"]

export default function QrCodeDemo() {
  const [value, setValue] = React.useState("https://example.com/invite/4F7K")
  const [level, setLevel] = React.useState<QrCodeErrorCorrection>("M")

  return (
    <div className="flex w-full max-w-xl flex-col items-center gap-6 sm:flex-row sm:items-start">
      <QrCode
        value={value || " "}
        errorCorrection={level}
        size={176}
        className="border"
      />
      <div className="flex w-full min-w-0 flex-1 flex-col gap-4">
        <label className="flex flex-col gap-1.5">
          <span className="eyebrow text-muted-foreground">Value</span>
          <Input value={value} onChange={(e) => setValue(e.target.value)} />
        </label>
        <div
          role="radiogroup"
          aria-label="Error correction"
          className="flex flex-col gap-1.5"
        >
          <span className="eyebrow text-muted-foreground">
            Error correction
          </span>
          <div className="flex gap-1">
            {LEVELS.map((l) => (
              <button
                key={l}
                type="button"
                role="radio"
                aria-checked={level === l}
                onClick={() => setLevel(l)}
                className="h-8 w-10 rounded-md border font-mono text-xs transition-colors outline-none hover:bg-muted focus-visible:ring-[3px] focus-visible:ring-ring/50 aria-checked:border-transparent aria-checked:bg-ink aria-checked:text-ink-foreground"
              >
                {l}
              </button>
            ))}
          </div>
        </div>
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/qr-code. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Ticket Pass

Digital ticket card with a title band, details grid, tear line, QR stub and a status badge.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/ticket-pass
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { TicketPass } from "@/components/ui/ticket-pass"
```

## Dependencies

- npm: `class-variance-authority`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/qr-code`, `@opendraft/badge`

## Props and types

```ts
type TicketPassStatus = "valid" | "used" | "expired" | "void"

type TicketPassField = {
  label: string
  value: React.ReactNode
}

type TicketPassProps = Omit<React.ComponentProps<"div">, "title"> & {
  /** Event or trip title. */
  title: React.ReactNode
  /** Small label above the title, e.g. "Admit one". */
  eyebrow?: React.ReactNode
  /** Label/value pairs shown in the meta grid. */
  fields: TicketPassField[]
  /** The string encoded in the QR code and shown under it. */
  code: string
  status?: TicketPassStatus
  /** Render the header band dark in either theme. */
  dark?: boolean
  /** Header band colour: "brand" uses the primary colour. */
  tone?: "default" | "brand"
  /** Buttons or links rendered below the stub. */
  actions?: React.ReactNode
}
```

## Variants

- `dark`: `true`, `false` (default)
- `tone`: `default` (default), `brand`

## Example

```tsx
import { Button } from "@/components/ui/button"
import { TicketPass } from "@/components/ui/ticket-pass"

const fields = [
  { label: "Date", value: <span className="font-mono">12 Nov 2026</span> },
  { label: "Doors", value: <span className="font-mono">19:00</span> },
  { label: "Venue", value: "Harbour Hall" },
  { label: "Section", value: "Floor A" },
  { label: "Seat", value: <span className="font-mono">14 / 22</span> },
  { label: "Tier", value: "General" },
]

export default function TicketPassDemo() {
  return (
    <div className="flex w-full max-w-2xl flex-col gap-6">
      <TicketPass
        eyebrow="Admit one"
        title="Autumn Sessions: Live"
        fields={fields}
        code="TKT-8F2K-41Q9"
        actions={
          <>
            <Button size="sm">Add to wallet</Button>
            <Button size="sm" variant="outline">
              Share
            </Button>
          </>
        }
      />
      <TicketPass
        dark
        eyebrow="Boarding pass"
        title="Lisbon to Berlin"
        fields={fields.slice(0, 4)}
        code="BRD-20X7-93LM"
        status="used"
      />
      <div className="grid gap-6 sm:grid-cols-2">
        <TicketPass
          title="Workshop day"
          fields={fields.slice(0, 2)}
          code="WSD-1102"
          status="expired"
        />
        <TicketPass
          title="Workshop day"
          fields={fields.slice(0, 2)}
          code="WSD-1103"
          status="void"
        />
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/ticket-pass. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Page Header

Page title block with eyebrow, description, actions and breadcrumb slots, plus a container that gives every route the same width and gutters.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/page-header
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { PageHeader, PageContainer } from "@/components/ui/page-header"
```

## Dependencies

- npm: `class-variance-authority`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
type PageContainerProps = React.ComponentProps<"div"> &
  VariantProps<typeof pageContainerVariants>

type PageHeaderProps = Omit<React.ComponentProps<"header">, "title"> & {
  eyebrow?: React.ReactNode
  title: React.ReactNode
  description?: React.ReactNode
  /** Buttons or menus aligned to the right (stacked below on narrow screens). */
  actions?: React.ReactNode
  /** Breadcrumb or back link rendered above the eyebrow. */
  breadcrumb?: React.ReactNode
  /** Draw a hairline under the header. */
  bordered?: boolean
  /** Heading level for the title. Defaults to h1. */
  as?: "h1" | "h2" | "h3"
}
```

## Variants

- `size`: `sm`, `default` (default), `lg`, `full`

## Example

```tsx
"use client"

import * as React from "react"
import { ChevronRight, Plus } from "lucide-react"

import { Button } from "@/components/ui/button"
import { PageContainer, PageHeader } from "@/components/ui/page-header"

function Crumbs() {
  return (
    <nav aria-label="Breadcrumb">
      <ol className="flex items-center gap-1.5 text-muted-foreground">
        <li>
          <a href="#" className="hover:text-foreground">
            Workspace
          </a>
        </li>
        <ChevronRight aria-hidden className="size-3.5" />
        <li aria-current="page" className="text-foreground">
          Projects
        </li>
      </ol>
    </nav>
  )
}

export default function PageHeaderDemo() {
  return (
    <div className="w-full max-w-[640px] overflow-hidden rounded-lg border bg-background">
      <PageContainer size="full">
        <PageHeader
          bordered
          breadcrumb={<Crumbs />}
          eyebrow="Overview"
          title="Projects"
          description="Everything your team is building, in one place."
          actions={
            <>
              <Button variant="outline">Export</Button>
              <Button>
                <Plus /> New project
              </Button>
            </>
          }
        />
        <PageHeader
          as="h2"
          eyebrow="Settings"
          title="Notifications"
          description="Choose what you hear about and where."
        />
      </PageContainer>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/page-header. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Field

Form field wrapper that pairs a label, control, hint and error message and wires ids and ARIA attributes, with a responsive group and fieldset.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/field
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Field, FieldControl, FieldGroup, FieldSet } from "@/components/ui/field"
```

## Dependencies

- Registry (installed with it): `@opendraft/utils`, `@opendraft/label`

## Props and types

```ts
type FieldControlProps = {
  id: string
  "aria-describedby"?: string
  "aria-invalid"?: true
  "aria-required"?: true
}

type FieldProps = Omit<React.ComponentProps<"div">, "children"> & {
  label?: React.ReactNode
  hint?: React.ReactNode
  /** Error message. Marks the control invalid and replaces the hint. */
  error?: React.ReactNode
  required?: boolean
  /** Visually hide the label but keep it for screen readers. */
  hideLabel?: boolean
  /** Override the generated control id. */
  controlId?: string
  /**
   * A render function receiving the control props to spread, or plain nodes
   * containing a `FieldControl` / any component using `useFieldControl`.
   */
  children: React.ReactNode | ((props: FieldControlProps) => React.ReactNode)
}

type FieldGroupProps = React.ComponentProps<"div"> & {
  /** Max columns when the container is wide enough. */
  columns?: 1 | 2
}

type FieldSetProps = Omit<React.ComponentProps<"fieldset">, "title"> & {
  legend: React.ReactNode
  description?: React.ReactNode
}

function FieldControl(props: React.ComponentProps<typeof Slot.Root>)
```

## Example

```tsx
"use client"

import * as React from "react"

import {
  Field,
  FieldControl,
  FieldGroup,
  FieldSet,
} from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import { Textarea } from "@/components/ui/textarea"
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select"

export default function FieldDemo() {
  const [email, setEmail] = React.useState("name@")
  const emailError = /^\S+@\S+\.\S+$/.test(email)
    ? undefined
    : "Enter a valid email address."

  return (
    <form
      className="w-full max-w-[640px]"
      onSubmit={(e) => e.preventDefault()}
      noValidate
    >
      <FieldSet
        legend="Contact details"
        description="We only use these to send your receipt."
      >
        <FieldGroup>
          <Field label="First name" required>
            {(p) => <Input {...p} autoComplete="given-name" />}
          </Field>
          <Field label="Last name" required>
            {(p) => <Input {...p} autoComplete="family-name" />}
          </Field>
          <Field
            data-span="full"
            label="Email"
            required
            hint="Receipts are sent here."
            error={emailError}
          >
            {(p) => (
              <Input
                {...p}
                type="email"
                value={email}
                onChange={(e) => setEmail(e.target.value)}
              />
            )}
          </Field>
          <Field label="Country">
            <Select defaultValue="us">
              <FieldControl>
                <SelectTrigger className="w-full">
                  <SelectValue />
                </SelectTrigger>
              </FieldControl>
              <SelectContent>
                <SelectItem value="us">United States</SelectItem>
                <SelectItem value="gb">United Kingdom</SelectItem>
                <SelectItem value="de">Germany</SelectItem>
              </SelectContent>
            </Select>
          </Field>
          <Field label="Company" hint="Optional.">
            {(p) => <Input {...p} />}
          </Field>
          <Field data-span="full" label="Notes" hint="Anything we should know?">
            <FieldControl>
              <Textarea rows={3} />
            </FieldControl>
          </Field>
        </FieldGroup>
      </FieldSet>
    </form>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/field. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Date Picker

Single-date picker in a popover with an accessible month grid and an optional HH:MM time field (12h or 24h), using ISO string values. Data shape: A single date with an optional HH:MM field; no time zone.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/date-picker
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { DatePicker } from "@/components/ui/date-picker"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/input`, `@opendraft/popover`

## Props and types

```ts
type HourCycle = 12 | 24

type DatePickerProps = Omit<
  React.ComponentProps<"button">,
  "value" | "defaultValue" | "onChange" | "type"
> & {
  /** Controlled ISO value: `2026-11-21` or `2026-11-21T19:30`. */
  value?: string
  /** Initial ISO value when uncontrolled. */
  defaultValue?: string
  /** Called with an ISO string, or `undefined` when cleared. */
  onValueChange?: (value: string | undefined) => void
  /** Adds an HH:MM field; value becomes `YYYY-MM-DDTHH:MM`. */
  time?: boolean
  /** 12 or 24 hour display and entry for the time field. */
  hourCycle?: HourCycle
  placeholder?: string
  /** BCP 47 locale for formatting. Defaults to the runtime locale. */
  locale?: string
  /** Earliest selectable day (ISO). */
  min?: string
  /** Latest selectable day (ISO). */
  max?: string
  /** Extra per-day rule; receives `YYYY-MM-DD`. */
  isDateDisabled?: (day: string) => boolean
  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6
  disabled?: boolean
  invalid?: boolean
  /** Time used when a day is picked and no time is set yet. */
  defaultTime?: string
  align?: "start" | "center" | "end"
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { DatePicker } from "@/components/ui/date-picker"
import { Label } from "@/components/ui/label"

export default function DatePickerDemo() {
  const [date, setDate] = React.useState<string | undefined>("2026-11-21")
  const [start, setStart] = React.useState<string | undefined>(
    "2026-11-21T19:30"
  )

  return (
    <div className="grid w-full max-w-xl gap-6 sm:grid-cols-2">
      <div className="flex flex-col gap-2">
        <Label htmlFor="dp-date">Event date</Label>
        <DatePicker
          id="dp-date"
          value={date}
          onValueChange={setDate}
          min="2026-01-01"
          max="2027-12-31"
        />
        <span className="font-mono text-xs text-muted-foreground tabular-nums">
          value = {date ?? "undefined"}
        </span>
      </div>
      <div className="flex flex-col gap-2">
        <Label htmlFor="dp-start">Doors open</Label>
        <DatePicker
          id="dp-start"
          time
          hourCycle={12}
          value={start}
          onValueChange={setStart}
          placeholder="Pick date and time"
        />
        <span className="font-mono text-xs text-muted-foreground tabular-nums">
          value = {start ?? "undefined"}
        </span>
      </div>
      <div className="flex flex-col gap-2">
        <Label htmlFor="dp-weekdays">Weekdays only (24h)</Label>
        <DatePicker
          id="dp-weekdays"
          time
          weekStartsOn={1}
          isDateDisabled={(d) => {
            const [y, m, day] = d.split("-").map(Number)
            const dow = new Date(Date.UTC(y, m - 1, day)).getUTCDay()
            return dow === 0 || dow === 6
          }}
        />
      </div>
      <div className="flex flex-col gap-2">
        <Label htmlFor="dp-invalid">Invalid</Label>
        <DatePicker id="dp-invalid" invalid placeholder="Required" />
      </div>
      <div className="flex flex-col gap-2">
        <Label htmlFor="dp-disabled">Disabled</Label>
        <DatePicker id="dp-disabled" disabled defaultValue="2026-12-01" />
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/date-picker. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Repeater Field

Add and remove rows editor for repeatable groups, with min/max, optional move up/down, live announcements and animated rows.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/repeater-field
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { RepeaterField } from "@/components/ui/repeater-field"
```

## Dependencies

- npm: `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/button`, `@opendraft/motion`

## Props and types

```ts
type RepeaterRowContext<T> = {
  item: T
  index: number
  /** Merge a partial change into this row. */
  update: (patch: Partial<T>) => void
  remove: () => void
}

type RepeaterFieldProps<T extends object> = Omit<
  React.ComponentProps<"div">,
  "children" | "onChange" | "defaultValue"
> & {
  value: T[]
  onValueChange: (value: T[]) => void
  renderRow: (ctx: RepeaterRowContext<T>) => React.ReactNode
  createItem: () => T
  /** Group heading, also the accessible name. */
  label?: string
  addLabel?: string
  /** Rows that cannot be removed below. Defaults to 0. */
  min?: number
  /** Add is disabled at this many rows. */
  max?: number
  emptyLabel?: string
  /** Show move up / move down buttons. */
  reorderable?: boolean
  /** Stable key per row. Defaults to an internal id map. */
  getKey?: (item: T, index: number) => React.Key
  /** Noun used in screen reader announcements and button names. */
  itemLabel?: string
}

function RepeaterField(props: RepeaterFieldProps<T>)
```

## Example

```tsx
"use client"

import * as React from "react"

import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"
import { RepeaterField } from "@/components/ui/repeater-field"

type Tier = { id: string; name: string; price: string; capacity: string }

let seq = 0
const createTier = (): Tier => ({
  id: `tier-${++seq}`,
  name: "",
  price: "",
  capacity: "",
})

export default function RepeaterFieldDemo() {
  const [tiers, setTiers] = React.useState<Tier[]>(() => [
    { id: "tier-a", name: "General admission", price: "25", capacity: "200" },
    { id: "tier-b", name: "VIP", price: "80", capacity: "40" },
  ])

  return (
    <div className="w-full max-w-xl">
      <RepeaterField
        label="Ticket tiers"
        itemLabel="Tier"
        addLabel="Add tier"
        emptyLabel="No tiers yet. Add one to start selling."
        value={tiers}
        onValueChange={setTiers}
        createItem={createTier}
        getKey={(t) => t.id}
        min={1}
        max={5}
        reorderable
        renderRow={({ item, update }) => (
          <div className="grid gap-3 sm:grid-cols-[1fr_5.5rem_5.5rem]">
            <div className="flex flex-col gap-1.5">
              <Label htmlFor={`${item.id}-name`}>Name</Label>
              <Input
                id={`${item.id}-name`}
                value={item.name}
                placeholder="Tier name"
                onChange={(e) => update({ name: e.target.value })}
              />
            </div>
            <div className="flex flex-col gap-1.5">
              <Label htmlFor={`${item.id}-price`}>Price</Label>
              <Input
                id={`${item.id}-price`}
                inputMode="decimal"
                className="font-mono tabular-nums"
                value={item.price}
                placeholder="0"
                onChange={(e) => update({ price: e.target.value })}
              />
            </div>
            <div className="flex flex-col gap-1.5">
              <Label htmlFor={`${item.id}-cap`}>Capacity</Label>
              <Input
                id={`${item.id}-cap`}
                inputMode="numeric"
                className="font-mono tabular-nums"
                value={item.capacity}
                placeholder="0"
                onChange={(e) => update({ capacity: e.target.value })}
              />
            </div>
          </div>
        )}
      />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/repeater-field. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Timeline

Vertical event timeline with status markers that never rely on color alone, mono timestamps, a side time column on wide containers, expandable detail, collapsible long lists, and loading and empty states.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/timeline
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Timeline, TimelineItem } from "@/components/ui/timeline"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/skeleton`

## Props and types

```ts
type TimelineStatus =
  "default" | "success" | "warning" | "destructive" | "current" | "upcoming"

type TimelineAlign = "left" | "right-time"

type TimelineItemData = {
  /** Display time. Rendered in mono. */
  time?: React.ReactNode
  /** ISO 8601 value; renders the time inside a `<time dateTime>` element. */
  timestamp?: string
  title: React.ReactNode
  description?: React.ReactNode
  /** Secondary line, e.g. location or actor. */
  meta?: React.ReactNode
  /** Replaces the status glyph inside the marker. */
  icon?: React.ReactNode
  status?: TimelineStatus
  /** Screen-reader text for the status. Defaults to a built-in label. */
  statusLabel?: string
  /** Expandable detail or attachments, shown in a disclosure. */
  children?: React.ReactNode
  /** Label of the disclosure toggle. */
  detailLabel?: React.ReactNode
  /** Start with the detail open. */
  defaultOpen?: boolean
}

type TimelineItemProps = TimelineItemData &
  Omit<React.ComponentProps<"li">, "title" | "children">

type TimelineProps = Omit<React.ComponentProps<"ol">, "children"> & {
  /** Array form. Rendered before any `children`. */
  items?: TimelineItemData[]
  /** Composable form: `<TimelineItem />` elements. */
  children?: React.ReactNode
  /** `right-time` moves the time to a left column on wide containers. */
  align?: TimelineAlign
  /** Marks the list as newest-first in its label. Does not reorder. */
  newestFirst?: boolean
  loading?: boolean
  /** Shown when there are no items. */
  emptyLabel?: React.ReactNode
  /** Show only the first `max` items behind a toggle. */
  collapsible?: boolean
  max?: number
}
```

## Example

```tsx
"use client"

import { MapPin, Package, Truck } from "lucide-react"

import { Timeline, TimelineItem } from "@/components/ui/timeline"

const incident = [
  {
    time: "14:52",
    timestamp: "2026-03-12T14:52:00Z",
    title: "Incident resolved",
    description: "Error rate back under 0.1% for 30 minutes.",
    meta: "Dana R., on-call",
    status: "success" as const,
  },
  {
    time: "14:21",
    timestamp: "2026-03-12T14:21:00Z",
    title: "Rollback in progress",
    description: "Reverting release 4.12.0 on all regions.",
    meta: "Deploy pipeline",
    status: "current" as const,
  },
  {
    time: "14:05",
    timestamp: "2026-03-12T14:05:00Z",
    title: "Checkout latency degraded",
    description: "p95 above 4s, elevated 5xx from the payments service.",
    meta: "Monitoring",
    status: "warning" as const,
    children: "Alert: payments-api p95 > 2s for 5 minutes. Runbook: RB-204.",
  },
  {
    time: "13:58",
    timestamp: "2026-03-12T13:58:00Z",
    title: "Database failover failed",
    description: "Replica promotion timed out.",
    meta: "Primary cluster",
    status: "destructive" as const,
  },
  {
    time: "13:40",
    timestamp: "2026-03-12T13:40:00Z",
    title: "Release 4.12.0 deployed",
    meta: "Alex M.",
  },
]

export default function TimelineDemo() {
  return (
    <div className="flex w-full max-w-[640px] flex-col gap-10">
      <section className="flex flex-col gap-4">
        <h3 className="eyebrow text-muted-foreground">
          Incident, newest first, collapsible
        </h3>
        <Timeline
          aria-label="Incident timeline"
          items={incident}
          newestFirst
          collapsible
          max={3}
          align="right-time"
        />
      </section>

      <section className="flex flex-col gap-4">
        <h3 className="eyebrow text-muted-foreground">
          Shipment tracking, composable
        </h3>
        <Timeline aria-label="Shipment tracking">
          <TimelineItem
            time="Mar 10"
            timestamp="2026-03-10"
            title="Order placed"
            meta="Online"
            status="success"
            icon={<Package className="size-3.5" />}
          />
          <TimelineItem
            time="Mar 11"
            timestamp="2026-03-11"
            title="Departed facility"
            meta={
              <span className="inline-flex items-center gap-1">
                <MapPin className="size-3" /> Rotterdam, NL
              </span>
            }
            status="success"
          />
          <TimelineItem
            time="Mar 12"
            timestamp="2026-03-12"
            title="In transit"
            description="Arriving at the local depot."
            meta="Hamburg, DE"
            status="current"
            icon={<Truck className="size-3.5" />}
          />
          <TimelineItem
            time="Mar 13"
            title="Out for delivery"
            status="upcoming"
          />
          <TimelineItem time="Mar 14" title="Delivered" status="upcoming" />
        </Timeline>
      </section>

      <section className="grid gap-6 sm:grid-cols-2">
        <Timeline loading aria-label="Loading history" />
        <Timeline items={[]} emptyLabel="No history for this case" />
      </section>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/timeline. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Alert

Callout with a per-variant icon, optional dismiss, an actions slot and a full-bleed banner mode for system, weather and policy notices.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/alert
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Alert, AlertTitle, AlertDescription, AlertAction } from "@/components/ui/alert"
```

## Dependencies

- npm: `class-variance-authority`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
type AlertVariant = NonNullable<VariantProps<typeof alertVariants>["variant"]>

type AlertProps = Omit<React.ComponentProps<"div">, "title"> &
  VariantProps<typeof alertVariants> & {
    /** Replace the default per-variant icon. */
    icon?: React.ReactNode
    /** Show a close button. */
    dismissible?: boolean
    onDismiss?: () => void
    dismissLabel?: string
  }

function AlertTitle(props: React.ComponentProps<"div">)

function AlertDescription(props: React.ComponentProps<"div">)

function AlertAction(props: React.ComponentProps<"div">)
```

## Variants

- `variant`: `default` (default), `info`, `success`, `warning`, `destructive`
- `banner`: `false` (default), `true`

## Example

```tsx
"use client"

import * as React from "react"

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

export default function AlertDemo() {
  const [open, setOpen] = React.useState(true)

  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      <Alert>
        <AlertTitle>Shipment SH-20418 updated</AlertTitle>
        <AlertDescription>
          Departure rescheduled to 06:40 from the Rotterdam hub.
        </AlertDescription>
      </Alert>
      <Alert variant="info">
        <AlertTitle>Scheduled maintenance</AlertTitle>
        <AlertDescription>
          The tracking API is read-only on Sunday, 02:00 to 04:00 UTC.
        </AlertDescription>
      </Alert>
      <Alert variant="success">
        <AlertTitle>Customs cleared</AlertTitle>
        <AlertDescription>
          Container MSKU-7731905 is released for pickup.
        </AlertDescription>
      </Alert>
      <Alert variant="warning">
        <AlertTitle>Weather delay at LHR</AlertTitle>
        <AlertDescription>
          Crosswinds are causing 45 minute holds on departures.
        </AlertDescription>
        <AlertAction>
          <Button size="sm" variant="outline">
            View affected flights
          </Button>
        </AlertAction>
      </Alert>
      {open && (
        <Alert
          variant="destructive"
          dismissible
          onDismiss={() => setOpen(false)}
        >
          <AlertTitle>Webhook delivery failing</AlertTitle>
          <AlertDescription>
            Endpoint returned 503 for the last 12 attempts.
          </AlertDescription>
          <AlertAction>
            <Button size="sm" variant="outline">
              Retry now
            </Button>
          </AlertAction>
        </Alert>
      )}
      <Alert variant="warning" banner>
        <AlertTitle>Policy update</AlertTitle>
        <AlertDescription>
          New cargo declaration rules apply from 1 November.
        </AlertDescription>
      </Alert>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/alert. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Status Indicator

Shape plus word status (operational, degraded, down, maintenance) and an uptime bar of segments with an accessible summary.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/status-indicator
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { StatusIndicator, UptimeBar } from "@/components/ui/status-indicator"
```

## Dependencies

- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
type StatusKind =
  "operational" | "degraded" | "down" | "maintenance" | "unknown"

type StatusTone = "success" | "warning" | "destructive" | "brand" | "muted"

type StatusShape = "dot" | "half" | "ring" | "square" | "dash"

type StatusIndicatorProps = Omit<React.ComponentProps<"span">, "children"> & {
  status?: StatusKind
  /** Override the colour tone (for custom statuses). */
  tone?: StatusTone
  /** Override the label text. */
  label?: React.ReactNode
  /** Shape for custom statuses; defaults to the status shape. */
  shape?: StatusShape
  /** Visually hide the label (kept for screen readers). */
  hideLabel?: boolean
  /** Animate a soft halo for live states. Respects reduced motion. */
  pulse?: boolean
}

type UptimeSegment = { status: StatusKind; label?: string }

type UptimeBarProps = Omit<React.ComponentProps<"div">, "children"> & {
  segments: UptimeSegment[]
  /** Percent text, e.g. "99.98%". Shown in mono beside the bar. */
  uptime?: React.ReactNode
  /** Name used in the accessible summary, e.g. "API gateway". */
  name?: string
  /** Unit for the accessible summary. */
  unit?: string
}
```

## Example

```tsx
import { StatusIndicator, UptimeBar } from "@/components/ui/status-indicator"
import type {
  StatusKind,
  UptimeSegment,
} from "@/components/ui/status-indicator"

const pattern: StatusKind[] = ["degraded", "down", "maintenance", "unknown"]

function makeSegments(seed: number): UptimeSegment[] {
  return Array.from({ length: 90 }, (_, i) => {
    const day = 90 - i
    const hit = (i * 7 + seed) % 29 === 0
    return {
      status: hit ? pattern[(i + seed) % pattern.length] : "operational",
      label: `${day} days ago`,
    }
  })
}

const services = [
  { name: "Tracking API", status: "operational", uptime: "99.98%", seed: 3 },
  { name: "Booking portal", status: "degraded", uptime: "99.41%", seed: 5 },
  { name: "Customs gateway", status: "down", uptime: "98.72%", seed: 11 },
] as const

export default function StatusIndicatorDemo() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-8">
      <div className="flex flex-wrap gap-x-6 gap-y-3">
        <StatusIndicator status="operational" pulse />
        <StatusIndicator status="degraded" />
        <StatusIndicator status="down" />
        <StatusIndicator status="maintenance" />
        <StatusIndicator status="unknown" />
        <StatusIndicator tone="brand" label="In transit" />
        <StatusIndicator status="operational" hideLabel label="Online" />
      </div>
      <div className="flex flex-col gap-5">
        {services.map((s) => (
          <div key={s.name} className="flex flex-col gap-2">
            <div className="flex items-center justify-between gap-3">
              <span className="text-sm font-medium">{s.name}</span>
              <StatusIndicator status={s.status} />
            </div>
            <UptimeBar
              name={s.name}
              unit="days"
              segments={makeSegments(s.seed)}
              uptime={s.uptime}
            />
          </div>
        ))}
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/status-indicator. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Slider

Single or range slider on Radix with a label row, formatted value and marks.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/slider
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Slider } from "@/components/ui/slider"
```

## Dependencies

- npm: `radix-ui`
- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
type SliderMark = { value: number; label?: React.ReactNode }

type SliderProps = Omit<
  React.ComponentProps<typeof SliderPrimitive.Root>,
  "value" | "defaultValue" | "onValueChange" | "onValueCommit" | "children"
> & {
  /** Controlled value. Two entries make a range slider. */
  value?: number[]
  defaultValue?: number[]
  onValueChange?: (value: number[]) => void
  onValueCommit?: (value: number[]) => void
  /** Left text of the label row. */
  label?: React.ReactNode
  /** Right text of the label row. Defaults to the formatted value. Pass `false` to hide. */
  valueLabel?: React.ReactNode | false
  /** Formats each value for the value label. Range values are joined with an en dash. */
  formatValue?: (value: number) => React.ReactNode
  /** Show min and max labels under the track. Pass `marks` for custom ticks. */
  showRange?: boolean
  marks?: SliderMark[]
  "aria-label"?: string
  "aria-labelledby"?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { Slider } from "@/components/ui/slider"

export default function SliderDemo() {
  const [volume, setVolume] = React.useState([70])

  return (
    <div className="grid w-full max-w-md gap-8">
      <Slider
        label="Playback volume"
        value={volume}
        onValueChange={setVolume}
        formatValue={(v) => `${v}%`}
        showRange
      />
      <Slider
        label="Speaking rate"
        defaultValue={[1]}
        min={0.5}
        max={2}
        step={0.1}
        formatValue={(v) => `${v.toFixed(1)}x`}
        marks={[
          { value: 0.5, label: "Slow" },
          { value: 1.25, label: "Natural" },
          { value: 2, label: "Fast" },
        ]}
      />
      <Slider
        label="Pitch range"
        defaultValue={[20, 65]}
        formatValue={(v) => `${v}`}
        showRange
      />
      <Slider aria-label="Noise reduction" defaultValue={[40]} disabled />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/slider. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Dropzone

Drag-and-drop or click-to-browse file area with size, type and count validation, camera capture and a file list with progress. No upload logic.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/dropzone
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Dropzone, DropzoneFileList, FileListItem } from "@/components/ui/dropzone"
```

## Dependencies

- npm: `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/progress`

## Props and types

```ts
type DropzoneRejectionReason =
  "file-too-large" | "file-invalid-type" | "too-many-files"

type DropzoneRejection = { file: File; reason: DropzoneRejectionReason }

type DropzoneFile = {
  id: string
  name: string
  size: number
  /** Upload progress, 0-100. Omit to hide the bar. */
  progress?: number
  /** Per-file error text. */
  error?: string
}

type DropzoneProps = Omit<
  React.ComponentProps<"div">,
  "onDrop" | "children"
> & {
  /** Same syntax as the input `accept` attribute. */
  accept?: string
  multiple?: boolean
  /** Maximum size per file, in bytes. */
  maxSize?: number
  maxFiles?: number
  /** Passes through to the input for phone camera capture. */
  capture?: boolean | "user" | "environment"
  disabled?: boolean
  onFiles?: (files: File[]) => void
  onReject?: (rejections: DropzoneRejection[]) => void
  /** Controlled list of files to render under the area. */
  files?: DropzoneFile[]
  onRemove?: (file: DropzoneFile) => void
  /** Custom prompt. Defaults to a generic drag or browse message. */
  children?: React.ReactNode
  /** Accessible name for the file input. */
  "aria-label"?: string
}

function FileListItem(props: {
  file: DropzoneFile
  onRemove?: (file: DropzoneFile) => void
  className?: string
})
```

## Example

```tsx
"use client"

import * as React from "react"
import { CameraIcon } from "lucide-react"

import { Dropzone, type DropzoneFile } from "@/components/ui/dropzone"

export default function DropzoneDemo() {
  const [files, setFiles] = React.useState<DropzoneFile[]>([
    { id: "seed-1", name: "dock-door-4.jpg", size: 2_400_000, progress: 100 },
  ])
  const [counter, setCounter] = React.useState(0)

  return (
    <div className="grid w-full max-w-xl gap-8">
      <div className="grid gap-3">
        <p className="eyebrow">Shipment photos</p>
        <Dropzone
          multiple
          accept="image/png, image/jpeg"
          maxSize={5 * 1024 * 1024}
          maxFiles={4}
          aria-label="Upload shipment photos"
          files={files}
          onRemove={(f) => setFiles((p) => p.filter((x) => x.id !== f.id))}
          onFiles={(added) => {
            const next = added.map((f, i) => ({
              id: `file-${counter + i}`,
              name: f.name,
              size: f.size,
              progress: 100,
            }))
            setCounter((c) => c + added.length)
            setFiles((p) => [...p, ...next])
          }}
        />
      </div>
      <div className="grid gap-3">
        <p className="eyebrow">Proof of delivery</p>
        <Dropzone
          accept="image/*"
          capture="environment"
          aria-label="Take a delivery photo"
        >
          <CameraIcon aria-hidden className="size-5 text-muted-foreground" />
          <span className="text-sm font-medium">Take or choose a photo</span>
          <span className="text-xs text-muted-foreground">
            Opens the camera on phones.
          </span>
        </Dropzone>
      </div>
      <div className="grid gap-3">
        <p className="eyebrow">Disabled</p>
        <Dropzone disabled aria-label="Upload disabled" />
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/dropzone. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# OTP Input

One-time-code entry on a single real input, with paste, a separator and complete, invalid and disabled states.

Category: Components

## Install

```bash
npx shadcn@latest add @opendraft/otp-input
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { OtpInput } from "@/components/ui/otp-input"
```

## Dependencies

- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
type OtpInputProps = Omit<
  React.ComponentProps<"input">,
  "value" | "defaultValue" | "onChange" | "maxLength" | "pattern" | "type"
> & {
  /** Number of cells. Defaults to 6. */
  length?: number
  value?: string
  defaultValue?: string
  onValueChange?: (value: string) => void
  /** Called once when every cell is filled. */
  onComplete?: (value: string) => void
  /** Accepted characters. Digits only by default. */
  pattern?: "numeric" | "alphanumeric"
  invalid?: boolean
  /** Render a dash after the middle cell. */
  separator?: boolean
  /** Focus the field on mount. */
  autoFocus?: boolean
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { OtpInput } from "@/components/ui/otp-input"

export default function OtpInputDemo() {
  const [code, setCode] = React.useState("")
  const [status, setStatus] = React.useState<"idle" | "error" | "ok">("idle")

  return (
    <div className="grid w-full max-w-md gap-8">
      <div className="grid gap-3">
        <p className="eyebrow">Two-factor authentication</p>
        <p className="text-sm text-muted-foreground">
          Enter the 6-digit code from your authenticator app. Try 123456.
        </p>
        <OtpInput
          separator
          value={code}
          invalid={status === "error"}
          onValueChange={(v) => {
            setCode(v)
            setStatus("idle")
          }}
          onComplete={(v) => setStatus(v === "123456" ? "ok" : "error")}
          aria-label="Authentication code"
        />
        <p
          role={status === "error" ? "alert" : "status"}
          className="min-h-5 text-sm"
        >
          {status === "error" && (
            <span className="text-destructive">
              That code is not valid. Try again.
            </span>
          )}
          {status === "ok" && <span className="text-success">Verified.</span>}
        </p>
      </div>
      <div className="grid gap-3">
        <p className="eyebrow">Alphanumeric, 4 characters</p>
        <OtpInput length={4} pattern="alphanumeric" aria-label="Access code" />
      </div>
      <div className="grid gap-3">
        <p className="eyebrow">Disabled</p>
        <OtpInput defaultValue="1234" disabled aria-label="Locked code" />
      </div>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/otp-input. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Action Swap

Buttons whose label and icon roll, blur or cascade between states.

Category: Motion

## Install

```bash
npx shadcn@latest add @opendraft/action-swap
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { ActionSwapText, ActionSwapIcon, ActionSwapButton } from "@/components/motion/action-swap"
```

Files added to the project:

- `components/motion/action-swap.tsx`
- `components/motion/action-swap-roll.tsx`

## Dependencies

- npm: `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`

## Props and types

```ts
export type ActionSwapItem = {
  id: string
  label: ReactNode
  icon?: ReactNode
  ariaLabel?: string
}

export type ActionSwapButtonVariant =
  "primary" | "secondary" | "outline" | "ghost"

export type ActionSwapButtonSize = "sm" | "md" | "lg" | "icon"

export type ActionSwapAnimation = "blur" | "roll" | "cascade"

export interface ActionSwapButtonProps extends Omit<
  HTMLMotionProps<"button">,
  "children" | "onChange"
> {
  items: ActionSwapItem[]
  value?: string
  defaultValue?: string
  onValueChange?: (value: string, item: ActionSwapItem) => void
  variant?: ActionSwapButtonVariant
  size?: ActionSwapButtonSize
  animation?: ActionSwapAnimation
  iconOnly?: boolean
  cycle?: boolean
}

export interface ActionSwapTextProps {
  value: string
  children: ReactNode
  animation?: ActionSwapAnimation
  className?: string
}

export interface ActionSwapIconProps {
  value: string
  children: ReactNode
  animation?: ActionSwapAnimation
  className?: string
}
```

## Example

```tsx
import { Check, Copy, Pause, Play } from "lucide-react"

import { ActionSwapButton } from "@/components/motion/action-swap"

export default function ActionSwapDemo() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <ActionSwapButton
        animation="roll"
        cycle
        items={[
          { id: "play", label: "Play", icon: <Play className="size-4" /> },
          { id: "pause", label: "Pause", icon: <Pause className="size-4" /> },
        ]}
      />
      <ActionSwapButton
        variant="outline"
        animation="blur"
        cycle
        items={[
          { id: "copy", label: "Copy link", icon: <Copy className="size-4" /> },
          { id: "copied", label: "Copied", icon: <Check className="size-4" /> },
        ]}
      />
      <ActionSwapButton
        variant="ghost"
        animation="cascade"
        cycle
        items={[
          { id: "follow", label: "Follow" },
          { id: "following", label: "Following" },
        ]}
      />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/action-swap. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Animated Number

Spring-animated number with Intl formatting.

Category: Motion

## Install

```bash
npx shadcn@latest add @opendraft/animated-number
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { AnimatedNumber } from "@/components/motion/animated-number"
```

## Dependencies

- npm: `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`

## Props and types

```ts
type AnimatedNumberProps = {
  value: number
  /** Intl.NumberFormat options, e.g. { style: "currency", currency: "USD" }. */
  format?: Intl.NumberFormatOptions
  locale?: string
  spring?: SpringOptions
  /** Start counting from 0 the first time the number scrolls into view. */
  countOnView?: boolean
  className?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { AnimatedNumber } from "@/components/motion/animated-number"
import { Button } from "@/components/ui/button"

export default function AnimatedNumberDemo() {
  const [value, setValue] = React.useState(128_430.52)

  return (
    <div className="flex flex-wrap items-end gap-6">
      <AnimatedNumber
        value={value}
        format={{ style: "currency", currency: "USD" }}
        className="heading text-5xl"
      />
      <Button
        variant="outline"
        size="sm"
        onClick={() =>
          setValue((v) => Math.max(0, v + (Math.random() - 0.4) * 20_000))
        }
      >
        Randomize
      </Button>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/animated-number. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Blur Text

Text that arrives word by word or character by character.

Category: Motion

## Install

```bash
npx shadcn@latest add @opendraft/blur-text
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { BlurText } from "@/components/motion/blur-text"
```

## Dependencies

- npm: `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`

## Props and types

```ts
type BlurTextProps = {
  text: string
  /** Animate per word (default) or per character. */
  by?: "word" | "char"
  as?: "h1" | "h2" | "h3" | "p" | "span"
  stagger?: number
  delay?: number
  /** Wait until the text scrolls into view. */
  inView?: boolean
  className?: string
}
```

## Example

```tsx
import { BlurText } from "@/components/motion/blur-text"

export default function BlurTextDemo() {
  return (
    <div className="grid gap-4">
      <BlurText
        as="h2"
        text="Text that arrives, word by word."
        className="heading text-4xl"
      />
      <BlurText
        by="char"
        delay={0.6}
        text="Or one character at a time."
        className="text-muted-foreground"
      />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/blur-text. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Copy Button

Copies a value and morphs its icon into a check.

Category: Motion

## Install

```bash
npx shadcn@latest add @opendraft/copy-button
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { CopyButton } from "@/components/motion/copy-button"
```

## Dependencies

- npm: `motion`, `lucide-react`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`, `@opendraft/button`

## Props and types

```ts
function CopyButton(props: Omit<React.ComponentProps<typeof Button>, "onClick" | "children"> & {
  value: string
})
```

## Example

```tsx
import { CopyButton } from "@/components/motion/copy-button"

const COMMAND = "npx shadcn add @opendraft/button"

export default function CopyButtonDemo() {
  return (
    <div className="flex h-10 items-center gap-2 border bg-surface pr-1 pl-3 font-mono text-sm">
      <span className="text-brand">$</span> {COMMAND}
      <CopyButton value={COMMAND} />
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/copy-button. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Loader

Fifteen loading animations, from spinners to ASCII and metaballs.

Category: Motion

## Install

```bash
npx shadcn@latest add @opendraft/loader
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Loader } from "@/components/motion/loader"
```

## Dependencies

- npm: `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`

## Props and types

```ts
export type LoaderVariant =
  | "spinner"
  | "dots"
  | "bars"
  | "dot-matrix"
  | "dither"
  | "ascii"
  | "ascii-line"
  | "ascii-braille"
  | "ascii-blocks"
  | "ascii-bounce"
  | "morph"
  | "comet"
  | "scramble"
  | "metaballs"
  | "newton"
  | "helix"
  | "percent"

export interface LoaderProps {
  /** Which animation to render. */
  variant?: LoaderVariant
  /** Base square size in px. Everything scales from this. */
  size?: number
  /** Seconds per animation cycle. */
  speed?: number
  /** Accessible label announced to screen readers. */
  label?: string
  className?: string
}
```

## Example

```tsx
import { Loader, type LoaderVariant } from "@/components/motion/loader"

const VARIANTS: LoaderVariant[] = [
  "spinner",
  "dots",
  "bars",
  "dot-matrix",
  "dither",
  "morph",
  "comet",
  "metaballs",
  "newton",
  "helix",
  "ascii",
  "ascii-braille",
  "ascii-blocks",
  "scramble",
  "percent",
]

export default function LoaderDemo() {
  return (
    <div className="grid w-full grid-cols-3 gap-2 sm:grid-cols-5">
      {VARIANTS.map((variant) => (
        <div
          key={variant}
          className="flex h-24 min-w-0 flex-col items-center justify-center gap-3 bg-muted/50"
        >
          <Loader variant={variant} size={28} label={variant} />
          <span className="truncate font-mono text-[10px] text-muted-foreground">
            {variant}
          </span>
        </div>
      ))}
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/loader. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Magnetic

Pulls its child gently toward the cursor.

Category: Motion

## Install

```bash
npx shadcn@latest add @opendraft/magnetic
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Magnetic } from "@/components/motion/magnetic"
```

## Dependencies

- npm: `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`

## Props and types

```ts
function Magnetic(props: {
  children: React.ReactNode
  strength?: number
  className?: string
})
```

## Example

```tsx
import { Magnetic } from "@/components/motion/magnetic"
import { Button } from "@/components/ui/button"

export default function MagneticDemo() {
  return (
    <Magnetic strength={0.4}>
      <Button size="lg" caps>
        Hover near me
      </Button>
    </Magnetic>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/magnetic. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Marquee

Seamless scrolling row with faded edges.

Category: Motion

## Install

```bash
npx shadcn@latest add @opendraft/marquee
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Marquee } from "@/components/motion/marquee"
```

## Dependencies

- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
type MarqueeProps = React.ComponentProps<"div"> & {
  /** Seconds per loop. */
  duration?: number
  gap?: string
  reverse?: boolean
  pauseOnHover?: boolean
  /** Fade the edges out. */
  fade?: boolean
}
```

## Example

```tsx
import { Marquee } from "@/components/motion/marquee"

const STACK = [
  "shadcn/ui",
  "Radix",
  "Motion",
  "Tailwind CSS",
  "Shiki",
  "Next.js",
  "Geist",
]

export default function MarqueeDemo() {
  return (
    <Marquee duration={25} gap="3rem" className="w-full py-2">
      {STACK.map((name) => (
        <span
          key={name}
          className="font-display text-2xl text-muted-foreground"
        >
          {name}
        </span>
      ))}
    </Marquee>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/marquee. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Code Reveal

Code backdrop that appears under the pointer, with a slower glow trailing behind.

Category: Motion

## Install

```bash
npx shadcn@latest add @opendraft/code-reveal
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { CodeReveal } from "@/components/motion/code-reveal"
```

## Dependencies

- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
type CodeRevealProps = React.ComponentProps<"div"> & {
  /** The code to hide. Plain text with newlines. */
  code: string
  /** Radius in px of the bright spot under the cursor. */
  radius?: number
  /**
   * Where the code sits. "sides" keeps it out of the middle column so the
   * headline stays clear; "full" fills the whole area.
   */
  area?: "sides" | "full"
}
```

## Example

```tsx
import { CodeReveal } from "@/components/motion/code-reveal"

const CODE = `import { Button } from "@/components/ui/button"

:root {
  --primary: var(--blue-600);
  --control-radius: 2px;
}

// move the pointer over this panel
export function Save() {
  return <Button variant="ink">Save</Button>
}`

export default function CodeRevealDemo() {
  return (
    <div className="relative grid h-72 w-full place-items-center overflow-hidden border bg-card">
      <CodeReveal code={CODE} area="full" radius={120} />
      <p className="relative eyebrow text-muted-foreground">Move your cursor</p>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/code-reveal. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Pixel Field

Canvas pixel textures in the blue scale: mosaic, dot matrix and equalizer.

Category: Motion

## Install

```bash
npx shadcn@latest add @opendraft/pixel-field
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { PixelField } from "@/components/motion/pixel-field"
```

## Dependencies

- Registry (installed with it): `@opendraft/utils`, `@opendraft/theme`

## Props and types

```ts
type PixelFieldVariant = "mosaic" | "matrix" | "equalizer"

type PixelFieldProps = Omit<React.ComponentProps<"div">, "children"> & {
  /**
   * mosaic: drifting blue pixel gradient (hero panels).
   * matrix: faint dot grid with a few cells blinking on (section texture).
   * equalizer: dot columns rising and falling like a level meter (bands).
   */
  variant?: PixelFieldVariant
  /** Cell pitch in CSS px. Defaults per variant. */
  cell?: number
  /** Animation speed multiplier. 0 renders a still frame. */
  speed?: number
  children?: React.ReactNode
}
```

## Example

```tsx
import { PixelField } from "@/components/motion/pixel-field"

export default function PixelFieldDemo() {
  return (
    <div className="grid w-full gap-3 sm:grid-cols-3">
      {(["mosaic", "matrix", "equalizer"] as const).map((variant) => (
        <div key={variant} className="grid gap-2">
          <PixelField variant={variant} className="h-40 border" />
          <p className="eyebrow text-muted-foreground">{variant}</p>
        </div>
      ))}
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/pixel-field. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Preview Rail

Tick rail with hover previews for jumping between sections.

Category: Motion

## Install

```bash
npx shadcn@latest add @opendraft/preview-rail
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { PreviewRail } from "@/components/motion/preview-rail"
```

## Dependencies

- npm: `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`, `@opendraft/use-dismiss`, `@opendraft/use-hover-gesture`, `@opendraft/use-tap-gesture`

## Props and types

```ts
export interface PreviewRailItem {
  id: string
  label: string
  ariaLabel?: string
  description?: ReactNode
  href?: string
  target?: "_blank" | "_self" | "_parent" | "_top"
  rel?: string
}

export interface PreviewRailProps {
  items: PreviewRailItem[]
  label?: string
  orientation?: "vertical" | "horizontal"
  activeId?: string
  defaultActiveId?: string
  onActiveChange?: (id: string) => void
  onItemSelect?: (item: PreviewRailItem) => void
  renderPreview?: (item: PreviewRailItem) => ReactNode
  showPreview?: boolean
  previewSide?: "before" | "after"
  highlightActive?: boolean
  itemSize?: number
  children?: ReactNode
  className?: string
  railClassName?: string
  previewContainerClassName?: string
  previewClassName?: string
}
```

## Example

```tsx
"use client"

import * as React from "react"

import {
  PreviewRail,
  type PreviewRailItem,
} from "@/components/motion/preview-rail"

const SECTIONS: PreviewRailItem[] = [
  {
    id: "tokens",
    label: "Tokens",
    description: "Color, type, shape and motion in one file.",
  },
  {
    id: "components",
    label: "Components",
    description: "Radix behavior, token styling, Motion state.",
  },
  {
    id: "agents",
    label: "Agents",
    description: "Chat, tools, approvals and voice.",
  },
  {
    id: "registry",
    label: "Registry",
    description: "Install any piece with one command.",
  },
]

export default function PreviewRailDemo() {
  const [active, setActive] = React.useState("tokens")
  const current = SECTIONS.find((s) => s.id === active) ?? SECTIONS[0]

  return (
    <PreviewRail
      items={SECTIONS}
      activeId={active}
      onActiveChange={setActive}
      highlightActive
      className="min-h-64 w-full"
    >
      <div className="grid h-full content-center gap-2 pl-6">
        <p className="eyebrow text-muted-foreground">Hover the ticks</p>
        <p className="heading text-3xl">{current.label}</p>
      </div>
    </PreviewRail>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/preview-rail. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Reveal

Fades and lifts content into view as it scrolls in.

Category: Motion

## Install

```bash
npx shadcn@latest add @opendraft/reveal
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { Reveal } from "@/components/motion/reveal"
```

## Dependencies

- npm: `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`

## Props and types

```ts
type RevealProps = HTMLMotionProps<"div"> & {
  variant?: keyof typeof presets
  delay?: number
  /** Only animate the first time it scrolls into view. */
  once?: boolean
}
```

## Example

```tsx
import { Reveal } from "@/components/motion/reveal"

const STEPS = ["Tokens", "Components", "Motion"]

export default function RevealDemo() {
  return (
    <div className="grid w-full gap-3 sm:grid-cols-3">
      {STEPS.map((step, i) => (
        <Reveal key={step} delay={i * 0.12} className="border bg-card p-5">
          <p className="eyebrow text-muted-foreground">0{i + 1}</p>
          <p className="mt-3 heading text-2xl">{step}</p>
        </Reveal>
      ))}
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/reveal. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Shimmer Text

A light sweep across text, for thinking and loading labels.

Category: Motion

## Install

```bash
npx shadcn@latest add @opendraft/shimmer-text
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { ShimmerText } from "@/components/motion/shimmer-text"
```

## Dependencies

- Registry (installed with it): `@opendraft/utils`

## Props and types

```ts
function ShimmerText(props: React.ComponentProps<"span"> & { duration?: number })
```

## Example

```tsx
import { ShimmerText } from "@/components/motion/shimmer-text"

export default function ShimmerTextDemo() {
  return (
    <div className="grid gap-3">
      <ShimmerText className="text-lg font-medium">
        Thinking through your request…
      </ShimmerText>
      <ShimmerText duration={3.5} className="text-sm">
        Searching 14 sources
      </ShimmerText>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/shimmer-text. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Spotlight Card

Card whose border and surface light up under the cursor.

Category: Motion

## Install

```bash
npx shadcn@latest add @opendraft/spotlight-card
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { SpotlightCard } from "@/components/motion/spotlight-card"
```

## Dependencies

- npm: `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`

## Props and types

```ts
function SpotlightCard(props: React.ComponentProps<"div"> & { size?: number })
```

## Example

```tsx
import { SpotlightCard } from "@/components/motion/spotlight-card"

export default function SpotlightCardDemo() {
  return (
    <SpotlightCard className="w-full max-w-sm">
      <p className="mb-4 eyebrow text-muted-foreground">Spotlight</p>
      <h3 className="heading text-2xl">Move your cursor over me</h3>
      <p className="mt-2 text-sm text-muted-foreground">
        The border and surface follow the pointer with a blue glow.
      </p>
    </SpotlightCard>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/spotlight-card. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt

---

# Text Scramble

Characters scramble, then resolve to the new text.

Category: Motion

## Install

```bash
npx shadcn@latest add @opendraft/text-scramble
```

Install `@opendraft/theme` first (once per project) so the tokens exist, and add the `@opendraft` registry to `components.json`. See https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt.

## Import

```tsx
import { TextScramble } from "@/components/motion/text-scramble"
```

## Dependencies

- npm: `motion`
- Registry (installed with it): `@opendraft/utils`, `@opendraft/motion`

## Props and types

```ts
export interface TextScrambleProps {
  /** Final text revealed by the scramble animation. */
  text: string
  /** Maximum animation duration in milliseconds. */
  duration?: number
  /** Characters sampled while unresolved positions are scrambling. */
  glyphs?: string
  className?: string
  style?: CSSProperties
}
```

## Example

```tsx
"use client"

import * as React from "react"

import { TextScramble } from "@/components/motion/text-scramble"
import { Button } from "@/components/ui/button"

const WORDS = ["Thinking", "Searching", "Reasoning", "Composing"]

export default function TextScrambleDemo() {
  const [index, setIndex] = React.useState(0)

  return (
    <div className="flex flex-wrap items-center gap-6">
      <TextScramble
        text={WORDS[index]}
        className="w-48 font-mono text-2xl tracking-wide uppercase"
      />
      <Button
        variant="outline"
        size="sm"
        onClick={() => setIndex((i) => (i + 1) % WORDS.length)}
      >
        Next word
      </Button>
    </div>
  )
}
```

Live docs: https://ui-system-virid.vercel.app/docs/text-scramble. Rules for building with opendraft: https://raw.githubusercontent.com/nuelmdesign/UI-System/HEAD/public/llms.txt