# Rime

> Rime is a React component kit with frosted-glass surfaces: Next.js App Router, TypeScript, CSS Modules and CSS custom properties, no Tailwind and no component library underneath. It installs like shadcn/ui (the shadcn CLI copies the source into your project) and names its items as shadcn does. Each project re-themes it with one theme.css made in Rime Studio (https://rime.mjsons.net/themes). Two presets, Rime Default (frosted glass in Frost blue) and Rime Flat, each in light and dark mode.

Read the rules before writing UI code with these components:

- Import primitives from "@/components/ui" (the barrel). Shells come from "@/components/shell/*".
- Never restyle a primitive from a screen. Theme it with CSS custom properties (tokens) instead: system tokens in app/styles/tokens.css, per-component tokens (--button-radius, --input-height-md, --table-head-fill) at :root or on a wrapper.
- CSS Modules only. No Tailwind, no inline colour values, no new component library.
- No heavy rounding beyond the theme's scale, no scale-up or lift on hover, no bento grids, no left accent bars, no decorative background effects that do not derive from the product.
- No eyebrow or small label stacked over a title. Text uses the full width of its column: no narrow measure caps.
- Summary stats are one card with hairline cells, never a grid of separate stat cards.
- Filters are dropdowns (Select chips) plus one full-width search, never a row of toggle chips. Sortable table headers are the whole cell; pagination is centred under the table.
- One primary button (the brand gradient) per view. One table look everywhere. Modal and sheet headers keep one left edge.
- Every list page is GlassPanel > FilterBar + Table + Pagination, with nothing above it.
- Every component needs its loading, empty, error and disabled states; an empty state always says what to do next.
- Text contrast 4.5:1 minimum (3:1 for focus rings and control edges). Fill colours like --brand-soft and --danger-base are never text.
- In Next.js, gate access inside page.tsx, never in layout.tsx (a layout gate leaks the page into the RSC payload).
- No em dashes in copy.

## Install

- Everything: `npx shadcn@latest add KezLahd/rime/kit`
- One component: `npx shadcn@latest add KezLahd/rime/<item>` (item names follow shadcn: button, dialog, dropdown-menu, select, sheet, sonner...)
- The agent docs and Claude skill for a project: `npx shadcn@latest add KezLahd/rime/agents`
- Registry: https://rime.mjsons.net/r/registry.json. Namespace @rime for components.json: "@rime": "https://rime.mjsons.net/r/{name}.json". The shadcn MCP server (npx shadcn@latest mcp) then lists, searches and installs Rime items.
- Styles, imported first in app/globals.css: app/styles/tokens.css, app/styles/base.css, app/styles/shadcn-bridge.css, then the project's theme.css.

## Coming from shadcn

| shadcn | Rime | Install item |
| --- | --- | --- |
| button | Button (variant default→primary, destructive→danger, outline→secondary; link and icon sizes as in shadcn) | button |
| button-group | ButtonGroup | button-group |
| card | Card (+ CardHeader, CardTitle, CardContent...) (props (title, description, actions, footer) or the shadcn parts) | card |
| dialog | Modal, ConfirmModal | dialog |
| alert-dialog | AlertDialog | alert-dialog |
| sheet, drawer | Sheet, Drawer | sheet |
| dropdown-menu | Menu | dropdown-menu |
| context-menu | ContextMenu | context-menu |
| menubar | Menubar | menubar |
| navigation-menu | NavigationMenu | navigation-menu |
| popover | Popover | popover |
| hover-card | HoverCard | hover-card |
| tooltip | Tooltip, Toggletip | tooltip |
| command | Command, CommandDialog | command |
| input | TextInput | input |
| input-group | InputGroup | input-group |
| input-otp | OtpInput | input-otp |
| textarea | Textarea | textarea |
| label | Label | label |
| field, form | Field, ErrorSummary | field |
| checkbox | Checkbox | checkbox |
| radio-group | RadioGroup | radio-group |
| switch | Switch | switch |
| slider | Slider | slider |
| select | Select (searchable option) | select |
| combobox | Combobox | combobox |
| calendar, date-picker | Calendar, DateField, DateRangeFilter | date-field |
| toggle, toggle-group | Toggle, ToggleGroup | toggle |
| tabs | FolderTabs, SegmentedControl | tabs |
| accordion | Accordion | accordion |
| collapsible | Collapsible | collapsible |
| breadcrumb | Breadcrumb | breadcrumb |
| pagination | Pagination (in Table) | table |
| table, data-table | Table + FilterBar + Pagination (the list page pattern) | table |
| badge | Badge, StatusPill, CountBadge | badge |
| avatar | Avatar | avatar |
| separator | Divider | separator |
| progress | Meter, ProgressBar | progress |
| skeleton | Skeleton | skeleton |
| spinner | Spinner | spinner |
| kbd | Kbd | kbd |
| alert | Alert | alert |
| sonner, toast | Toast + ToastProvider | sonner |
| empty | EmptyState | empty |
| scroll-area | ScrollArea | scroll-area |
| aspect-ratio | AspectRatio | aspect-ratio |
| carousel | Carousel | carousel |
| resizable | ResizablePanelGroup, ResizablePanel, ResizableHandle | resizable |
| chart | LineChart, AreaChart, BarChart, DonutChart, ChartContainer | chart |
| sidebar | SidebarShell (components/shell) | sidebar |

shadcn CSS variable names are aliases of Rime tokens (app/styles/shadcn-bridge.css), one way only:

| shadcn variable | Rime token |
| --- | --- |
| --background | --page-base |
| --foreground | --ink-body |
| --card / --card-foreground | --surface-solid / --ink-body |
| --popover / --popover-foreground | --popover-surface / --ink-body |
| --primary / --primary-foreground | --brand-action / --ink-inverse |
| --secondary / --secondary-foreground | --surface-sunken / --ink-heading |
| --muted / --muted-foreground | --surface-sunken / --ink-muted |
| --accent / --accent-foreground | --wash-hover / --ink-heading |
| --destructive | --danger-base-solid |
| --border | --line |
| --input | --line-input |
| --ring | --focus-color |
| --radius | --r-md |
| --chart-1..5 | --chart-1..5 |
| --sidebar* | --chrome-sidebar, --brand-action, --wash-active, --line-soft |
| --font-sans / --font-heading | --font-body / --font-display |

Dark mode is the .dark class or data-mode="dark" on <html>; Rime Flat is data-theme="flat".

## Docs

- [Everything in one file](https://rime.mjsons.net/llms-full.txt): every component, pattern and rule
- [Theming and tokens](https://rime.mjsons.net/md/theme.md): token layers, presets and modes, how to theme a project
- [Patterns](https://rime.mjsons.net/md/patterns.md): composed patterns (list page, shells, sign-in, terms gate)
- Any docs page as markdown: add .md to its URL (for example /components/button.md).

## Actions

- [Button](https://rime.mjsons.net/md/button.md): The action control: primary gradient, glass secondary, ghost, and two danger forms, in three sizes. Install: `npx shadcn@latest add KezLahd/rime/button`
- [ButtonGroup](https://rime.mjsons.net/md/button-group.md): Joins Buttons and IconButtons into one segmented row or column with shared outer corners. Install: `npx shadcn@latest add KezLahd/rime/button-group`
- [IconButton](https://rime.mjsons.net/md/icon-button.md): A square action with only an icon, a required accessible label and a tooltip-friendly hit area. Install: `npx shadcn@latest add KezLahd/rime/icon-button`

## Forms

- [Calendar](https://rime.mjsons.net/md/calendar.md): The month grid on its own: a single date or a range, one or two months, with month and year pickers. Install: `npx shadcn@latest add KezLahd/rime/date-field`
- [Checkbox](https://rime.mjsons.net/md/checkbox.md): A native checkbox drawn as a gradient tick, plain or as a selectable card, with indeterminate. Install: `npx shadcn@latest add KezLahd/rime/checkbox`
- [Combobox](https://rime.mjsons.net/md/combobox.md): A text field that filters a list of options as you type and picks one, with optional create. Install: `npx shadcn@latest add KezLahd/rime/combobox`
- [DateField](https://rime.mjsons.net/md/date-field.md): A typed DD/MM/YYYY field with a calendar popover, min/max and a date-of-birth preset. Install: `npx shadcn@latest add KezLahd/rime/date-field`
- [DateRangeFilter](https://rime.mjsons.net/md/date-range-filter.md): A date-range chip for filter rows: presets plus a two-month range calendar. Install: `npx shadcn@latest add KezLahd/rime/date-range-filter`
- [DateTimeField and DateTimeRangeField](https://rime.mjsons.net/md/date-time-field.md): A date and a time of day on one row, each with its own popup; the range variant pairs a start and end. Install: `npx shadcn@latest add KezLahd/rime/date-time-field`
- [ErrorSummary](https://rime.mjsons.net/md/error-summary.md): The list of form errors at the top of a form, focused on submit, each linking to its field. Install: `npx shadcn@latest add KezLahd/rime/error-summary`
- [Field](https://rime.mjsons.net/md/field.md): Label, hint, error and required marker for any control, wired through context. Install: `npx shadcn@latest add KezLahd/rime/field`
- [FileDrop](https://rime.mjsons.net/md/file-drop.md): A drop zone and file picker with type and size checks and per-file status chips. Install: `npx shadcn@latest add KezLahd/rime/file-drop`
- [InputGroup](https://rime.mjsons.net/md/input-group.md): A text field with addons joined to it: a fixed text segment, an icon, or a button such as Copy. Install: `npx shadcn@latest add KezLahd/rime/input-group`
- [Label](https://rime.mjsons.net/md/label.md): A standalone form label with required and optional markers, for controls outside a Field. Install: `npx shadcn@latest add KezLahd/rime/label`
- [OtpInput](https://rime.mjsons.net/md/otp-input.md): A six-cell one-time code entry with paste, auto-advance and onComplete. Install: `npx shadcn@latest add KezLahd/rime/otp-input`
- [PrefixedInput](https://rime.mjsons.net/md/prefixed-input.md): A fixed-format code with a set prefix: an invoice number, an account code, a membership number. Install: `npx shadcn@latest add KezLahd/rime/prefixed-input`
- [RadioGroup](https://rime.mjsons.net/md/radio-group.md): One choice from a few: a list, inline, or cards in 1 to 3 columns. Install: `npx shadcn@latest add KezLahd/rime/radio-group`
- [SearchField](https://rime.mjsons.net/md/search-field.md): Field-size search on the grey frosted recess: clear button, loading state and an optional key hint. Install: `npx shadcn@latest add KezLahd/rime/search-field`
- [Select](https://rime.mjsons.net/md/select.md): A custom listbox: a recessed field or filter chip that opens a frosted popover, optionally searchable. Install: `npx shadcn@latest add KezLahd/rime/select`
- [Slider](https://rime.mjsons.net/md/slider.md): Picks a number or a range by dragging along a track, with steps, marks and a value readout. Install: `npx shadcn@latest add KezLahd/rime/slider`
- [Switch](https://rime.mjsons.net/md/switch.md): An on/off setting that takes effect immediately, with a loading state while it saves. Install: `npx shadcn@latest add KezLahd/rime/switch`
- [Textarea](https://rime.mjsons.net/md/textarea.md): Multi-line text in the TextInput box, resizable vertically, with an optional character count. Install: `npx shadcn@latest add KezLahd/rime/textarea`
- [TextInput](https://rime.mjsons.net/md/text-input.md): The text field: a white box with a tinted edge, a brand halo on focus, adornments and a password reveal. Install: `npx shadcn@latest add KezLahd/rime/text-input`
- [TimeField and TimeRangeField](https://rime.mjsons.net/md/time-field.md): A time of day with typed input and a popup picker; the range variant pairs start and end on one row. Install: `npx shadcn@latest add KezLahd/rime/time-field`
- [Toggle](https://rime.mjsons.net/md/toggle.md): A two-state button, pressed or not, for toolbar formatting and view options. Install: `npx shadcn@latest add KezLahd/rime/toggle`
- [ToggleGroup](https://rime.mjsons.net/md/toggle-group.md): A set of toggles sharing one value: single (a clearable radio set) or multiple. Install: `npx shadcn@latest add KezLahd/rime/toggle`

## Data display

- [Avatar](https://rime.mjsons.net/md/avatar.md): Initials on the brand gradient or a neutral disc, in three sizes. Install: `npx shadcn@latest add KezLahd/rime/avatar`
- [Chart](https://rime.mjsons.net/md/chart.md): Themed charts on Recharts: line, area, bar and donut in one frame with a table view, plus sparklines and a stat strip. Install: `npx shadcn@latest add KezLahd/rime/charts`
- [Kbd and KbdGroup](https://rime.mjsons.net/md/kbd.md): Keyboard keys as small raised key caps, alone or as a combination. Install: `npx shadcn@latest add KezLahd/rime/kbd`
- [Meter and ProgressBar](https://rime.mjsons.net/md/meter.md): A segmented meter for small counts (seats used) and a bar for progress through a total. Install: `npx shadcn@latest add KezLahd/rime/meter`
- [ProgressSteps](https://rime.mjsons.net/md/progress-steps.md): A horizontal track of steps with detail and meta lines, or a compact dot track for table cells. Install: `npx shadcn@latest add KezLahd/rime/progress-steps`
- [StatusPill, Badge and CountBadge](https://rime.mjsons.net/md/status-pill.md): Status pills (tinted fill, tinted edge, deep ink), small uppercase tags, and count badges. Install: `npx shadcn@latest add KezLahd/rime/badge`
- [Table](https://rime.mjsons.net/md/table.md): The one table look: neutral header row, whole-cell sortable headers, skeleton, empty and error states, and Pagination. Install: `npx shadcn@latest add KezLahd/rime/table`

## Navigation

- [Breadcrumb](https://rime.mjsons.net/md/breadcrumb.md): Where this page sits: a trail of links ending on the current page, folding its middle into a menu when long. Install: `npx shadcn@latest add KezLahd/rime/breadcrumb`
- [FilterBar](https://rime.mjsons.net/md/filter-bar.md): The one filter row above every table: a growing search, dropdown chips at the end, clear, and the list's own action. Install: `npx shadcn@latest add KezLahd/rime/filter-bar`
- [FolderTabs and SegmentedControl](https://rime.mjsons.net/md/tabs.md): Folder tabs that sit on a glass panel with always-visible counts, and a segmented control for views. Install: `npx shadcn@latest add KezLahd/rime/tabs`
- [NavigationMenu](https://rime.mjsons.net/md/navigation-menu.md): Top-level site navigation with frosted dropdown panels of described links, built as disclosure navigation. Install: `npx shadcn@latest add KezLahd/rime/navigation-menu`
- [NavSearch and SmartSearch](https://rime.mjsons.net/md/nav-search.md): Top-bar search: NavSearch jumps to pages and actions; SmartSearch queries records with grouped results. Install: `npx shadcn@latest add KezLahd/rime/nav-search`
- [Pagination](https://rime.mjsons.net/md/pagination.md): Centred page buttons with previous and next, gaps for long ranges, and a summary line at the left. Install: `npx shadcn@latest add KezLahd/rime/table`
- [Stepper](https://rime.mjsons.net/md/stepper.md): The wizard's step list: lettered markers, states, and optional navigation back to finished steps. Install: `npx shadcn@latest add KezLahd/rime/stepper`

## Feedback

- [Alert](https://rime.mjsons.net/md/alert.md): An inline message in a tone (info, success, warning, danger) or a quiet legal box for fixed wording, with an action and dismiss. Install: `npx shadcn@latest add KezLahd/rime/alert`
- [EmptyState](https://rime.mjsons.net/md/empty-state.md): What an empty list means and what to do next: default, positive (all done) and filtered tones. Install: `npx shadcn@latest add KezLahd/rime/empty-state`
- [ImpactPreview](https://rime.mjsons.net/md/impact-preview.md): What a destructive action will change, row by row, before it is confirmed. Install: `npx shadcn@latest add KezLahd/rime/impact-preview`
- [Skeleton](https://rime.mjsons.net/md/skeleton.md): Loading placeholders shaped like the content they stand in for, with a soft shimmer. Install: `npx shadcn@latest add KezLahd/rime/skeleton`
- [Spinner](https://rime.mjsons.net/md/spinner.md): A small brand-tinted spinner for in-flight work inside buttons, fields and panels. Install: `npx shadcn@latest add KezLahd/rime/spinner`
- [Toast](https://rime.mjsons.net/md/toast.md): Frosted toasts for success, error, info and in-flight work, stacked as a deck that fans out on hover. Install: `npx shadcn@latest add KezLahd/rime/toast`

## Overlays

- [AlertDialog](https://rime.mjsons.net/md/alert-dialog.md): A short interrupting confirm with Cancel and one action; focus starts on Cancel and the scrim never dismisses it. Install: `npx shadcn@latest add KezLahd/rime/alert-dialog`
- [Command](https://rime.mjsons.net/md/command.md): A command palette: a search box over grouped actions with shortcuts, keyboard-first, inline or as a Ctrl+K dialog. Install: `npx shadcn@latest add KezLahd/rime/command`
- [ContextMenu](https://rime.mjsons.net/md/context-menu.md): A menu of actions for a region, opened at the pointer with a right-click, Shift+F10 or a long press. Install: `npx shadcn@latest add KezLahd/rime/context-menu`
- [HoverCard](https://rime.mjsons.net/md/hover-card.md): A rich preview on hover or keyboard focus of a link: a person, a project, a record. Install: `npx shadcn@latest add KezLahd/rime/hover-card`
- [Menu](https://rime.mjsons.net/md/menu.md): An action menu from a button: groups, headings, separators, icons, links and danger items, in a frosted popover. Install: `npx shadcn@latest add KezLahd/rime/menu`
- [Menubar](https://rime.mjsons.net/md/menubar.md): A desktop application menu bar (File, Edit, View) with keyboard navigation across and within its menus. Install: `npx shadcn@latest add KezLahd/rime/menubar`
- [Modal](https://rime.mjsons.net/md/modal.md): A frosted dialog with a focus trap, scroll lock, inert page, scroll-aware edges and a bottom sheet on phones. Install: `npx shadcn@latest add KezLahd/rime/modal`
- [Popover](https://rime.mjsons.net/md/popover.md): An anchored frosted panel for arbitrary content: a short form, a set of options, a details block. Install: `npx shadcn@latest add KezLahd/rime/popover`
- [Sheet and Drawer](https://rime.mjsons.net/md/sheet.md): A panel that slides in from an edge over a scrim, and a bottom Drawer with a drag handle. Install: `npx shadcn@latest add KezLahd/rime/sheet`
- [Tooltip and Toggletip](https://rime.mjsons.net/md/tooltip.md): Hover and focus tooltips (dark one-liners or light rich cards) and click-to-open toggletips for help. Install: `npx shadcn@latest add KezLahd/rime/tooltip`
- [TypeToConfirmModal and DangerZone](https://rime.mjsons.net/md/type-to-confirm.md): The heaviest confirm: an impact preview and a typed phrase; and the Danger zone section that leads to it. Install: `npx shadcn@latest add KezLahd/rime/type-to-confirm`

## Layout and surfaces

- [Accordion](https://rime.mjsons.net/md/accordion.md): Stacked sections that open and close in place: one at a time or several, on glass or plain hairlines. Install: `npx shadcn@latest add KezLahd/rime/accordion`
- [AspectRatio](https://rime.mjsons.net/md/aspect-ratio.md): A box held to a width-to-height ratio, so media keeps its shape and never shifts the layout while loading. Install: `npx shadcn@latest add KezLahd/rime/aspect-ratio`
- [Card](https://rime.mjsons.net/md/card.md): A solid card with a washed header, a lifted highlight tone, and a sunken muted tone. Install: `npx shadcn@latest add KezLahd/rime/card`
- [Carousel](https://rime.mjsons.net/md/carousel.md): A row of slides on a native scroll-snap track, with frosted prev and next buttons, dots and arrow keys. Install: `npx shadcn@latest add KezLahd/rime/carousel`
- [Collapsible](https://rime.mjsons.net/md/collapsible.md): One disclosure: a title row with a toggle, an always-visible summary and a region that opens beneath it. Install: `npx shadcn@latest add KezLahd/rime/collapsible`
- [Divider](https://rime.mjsons.net/md/divider.md): A hairline rule, horizontal or vertical, optionally labelled, with spacing steps. Install: `npx shadcn@latest add KezLahd/rime/divider`
- [GlassPanel](https://rime.mjsons.net/md/glass-panel.md): Frosted glass over the page field: page, light and nested variants, padding steps and an optional bloom. Install: `npx shadcn@latest add KezLahd/rime/glass-panel`
- [Resizable](https://rime.mjsons.net/md/resizable.md): Panels split by draggable hairline handles, side by side or stacked, with keyboard resizing and minimum sizes. Install: `npx shadcn@latest add KezLahd/rime/resizable`
- [ScrollArea, useScrollEdges and useScrollLock](https://rime.mjsons.net/md/scroll-area.md): The modal's scroll, made portable: thin tinted scrollbars, contained overscroll, edge shadows and a shared scroll lock. Install: `npx shadcn@latest add KezLahd/rime/scroll-area`

## Shell

- [AuthCard and AuthLayout](https://rime.mjsons.net/md/auth-card.md): The sign-in card: a solid card on a deep field, with a logo slot, icon tile, title, footer strip and back link. Install: `npx shadcn@latest add KezLahd/rime/auth-card`
- [PageHeader](https://rime.mjsons.net/md/page-header.md): A page's h1 with a back link, a meta line, a description and actions. Install: `npx shadcn@latest add KezLahd/rime/page-header`
- [SidebarShell](https://rime.mjsons.net/md/sidebar-shell.md): The signed-in frame in four layouts: an expanded frosted sidebar, a collapsible icon rail, a header-only top nav, and a drawer on narrow screens. Install: `npx shadcn@latest add KezLahd/rime/sidebar-shell`

## Patterns

- [List page](https://rime.mjsons.net/md/patterns.md#list-page): One glass panel holding the filter row, the table and the pagination. Nothing above it.
- [Frosted glass shell](https://rime.mjsons.net/md/patterns.md#glass-shell): The signed-in frame: the page field painted once, a frosted sidebar and top bar over it, and glass panels inside.
- [Shell: sidebar expanded](https://rime.mjsons.net/md/patterns.md#shell-sidebar): The default signed-in frame: a full-height frosted sidebar and top bar forming one glass L, the logo corner in the same glass.
- [Shell: collapsible icon rail](https://rime.mjsons.net/md/patterns.md#shell-rail): The same frame with a panel button that folds the sidebar to a 68px icon rail, remembered across visits.
- [Shell: header only](https://rime.mjsons.net/md/patterns.md#shell-header): No sidebar: the logo, a short horizontal nav and the profile in one frosted top bar, the page below at full width.
- [Shell: mobile drawer](https://rime.mjsons.net/md/patterns.md#shell-drawer): On narrow screens the sidebar becomes an off-canvas drawer from a menu button, with a scrim, a focus hold and Esc to close.
- [Summary card with cells](https://rime.mjsons.net/md/patterns.md#summary-card): One card of key figures: per cell a label, a big number and a muted line of context, separated by hairlines.
- [Modal with scroll edges](https://rime.mjsons.net/md/patterns.md#modal-scroll): A long modal whose header and footer cast shadows only when content passes under them.
- [Terms with scroll-gated accept](https://rime.mjsons.net/md/patterns.md#terms-gated): A terms dialog whose Accept stays disabled until the reader has scrolled to the end.
- [Sign-in with multi-factor authentication](https://rime.mjsons.net/md/patterns.md#sign-in): A corporate sign-in: brand mark in the header, the form centred, a shield treatment and a security note in the footer, across the password, MFA code and authenticator setup steps.

---

# Button

> The action control: primary gradient, glass secondary, ghost, and two danger forms, in three sizes.

Category: Actions. Docs page: https://rime.mjsons.net/components/button

## Installation

```bash
npx shadcn@latest add KezLahd/rime/button
```

Button is every pressable action that is not an icon on its own. Primary carries the brand gesture (the brand gradient with a soft glow) and appears at most once per view. Secondary is glass on the page and a white tile with a brand ring inside solid surfaces (a Card, a Modal, an auth card), switched automatically by the nearest data-surface="solid" ancestor. Ghost is for low-emphasis actions in rows and toolbars.

Danger is the irreversible action, in the danger gradient. dangerSecondary is its inverse (danger ink on the secondary's glass) for destructive steps that are not the last one, such as "Review deletion" before the final "Delete project".

Pass href to render a Next Link with the same look. A disabled or loading link drops its href and leaves the tab order, as a disabled button would. Loading shows a spinner, sets aria-busy, blocks presses and can swap the label (loadingLabel).

## Usage

```tsx
import { Button } from "@/components/ui";

<Button onClick={save}>Save changes</Button>
```

## Props: Button

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `ButtonVariant` | `"primary"` | primary = the one brand gradient per view. secondary = glass (white inside solid surfaces). |
| `size` | `ButtonSize` | `"md"` |  |
| `loading` | `boolean` |  | Shows a spinner, sets aria-busy and blocks further presses. |
| `loadingLabel` | `string` |  | Replaces the label while loading, e.g. "Submitting…". |
| `iconStart` | `ReactNode` |  |  |
| `iconEnd` | `ReactNode` |  |  |
| `fullWidth` | `boolean` |  |  |
| `className` | `string` |  |  |
| `children` | `ReactNode` |  |  |
| `href` | `undefined \| string` |  | Renders a Next <Link>. Internal routes only. |
| `asChild` | `boolean \| undefined` |  | Render the single child element (a Next <Link>, an <a>) with the button's look, as shadcn's asChild. The child supplies its own content. |
| `disabled` | `boolean` |  |  |
| `prefetch` | `boolean` |  |  |
| `replace` | `boolean` |  |  |
| `scroll` | `boolean` |  |  |

Also accepts the native attributes of: AnchorHTMLAttributes, AriaAttributes, ButtonHTMLAttributes, DOMAttributes, HTMLAttributes.

## Examples

### Variants

One primary per view. Secondary switches to a white tile inside solid surfaces.

```tsx
<Button>Create invoice</Button>
<Button variant="secondary">Save draft</Button>
<Button variant="ghost">Cancel</Button>
<Button variant="dangerSecondary">Review deletion</Button>
<Button variant="danger">Delete project</Button>
```

### Sizes

sm for table rows and toolbars, md everywhere else, lg for the one action on an auth card.

```tsx
<Button size="sm">Small</Button>
<Button>Medium</Button>
<Button size="lg">Large</Button>
```

### With icons

```tsx
<Button iconStart={<IconPlus size={15} />}>Add team member</Button>
<Button variant="secondary" iconEnd={<IconArrowRight size={15} />}>Continue</Button>
```

### Loading and disabled

Loading keeps the fill, dulls it and swaps the label. Disabled is a flat tint, not a faded gradient.

```tsx
<Button loading loadingLabel="Saving…">Save</Button>
<Button disabled>Submit</Button>
<Button href="/projects" variant="secondary">Link as button</Button>
```

### shadcn names

shadcn's variant and size names work as aliases: default is primary, destructive is danger, outline is secondary; link is an inline text link; icon, icon-sm and icon-lg are square. buttonVariants is buttonClassName.

```tsx
<Button variant="default">Save</Button>
<Button variant="outline">Cancel</Button>
<Button variant="destructive">Delete</Button>
<Button variant="link">Read the terms</Button>
<Button variant="outline" size="icon" aria-label="Settings"><Settings size={16} /></Button>
```

### asChild

asChild renders the single child (a Next Link, an <a>) with the button's look, as shadcn does. href remains the shorter way for internal links.

```tsx
import Link from "next/link";

<Button asChild>
  <Link href="/projects/new">New project</Link>
</Button>
<Button variant="destructive" size="icon" asChild>
  <Link href="/trash" aria-label="Open trash"><Trash2 size={16} /></Link>
</Button>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--button-case` | `none` |
| `--button-danger-bg` | `var(--danger-gradient)` |
| `--button-dur` | `var(--dur)` |
| `--button-ease` | `var(--ease)` |
| `--button-gap` | `8px` |
| `--button-ghost-ink` | `var(--ink-brand)` |
| `--button-height-lg` | `var(--control-h-lg)` |
| `--button-height-md` | `var(--control-h-md)` |
| `--button-height-sm` | `var(--control-h-sm)` |
| `--button-hover-glow` | `var(--glow-md-hover)` |
| `--button-hover-overlay` | `rgba(var(--rgb-white), 0.07)` |
| `--button-lift` | `0px` |
| `--button-link-ink` | `var(--ink-brand)` |
| `--button-outline` | `var(--shadow-control)` |
| `--button-outline-active` | `inset 0 0 0 1px rgba(var(--rgb-brand), 0.32)` |
| `--button-outline-hover` | `0 3px 8px rgba(var(--rgb-brand-deep), 0.1), inset 0 0 0 1px rgba(var(--rgb-brand), 0.32)` |
| `--button-pad-lg` | `calc(24px * var(--density))` |
| `--button-pad-md` | `calc(18px * var(--density))` |
| `--button-pad-sm` | `calc(12px * var(--density))` |
| `--button-press-overlay` | `rgba(var(--rgb-shade), 0.14)` |
| `--button-primary-bg` | `var(--brand-gradient)` |
| `--button-primary-ink` | `var(--ink-inverse)` |
| `--button-radius` | `var(--r-sm)` / `var(--r-md)` / `var(--r-lg)` |
| `--button-secondary-bg` | `rgba(var(--rgb-white), 0.45)` |
| `--button-secondary-hover-bg` | `rgba(var(--rgb-white), 0.68)` |
| `--button-secondary-hover-shadow` | `inset 0 0 0 1px rgba(var(--rgb-white), 0.9), var(--shadow-specular), 0 4px 12px rgba(var(--rgb-brand-deep), 0.1)` |
| `--button-secondary-ink` | `var(--ink-heading)` |
| `--button-size-lg` | `15px` |
| `--button-size-md` | `14px` |
| `--button-size-sm` | `12.5px` |
| `--button-tracking` | `-0.005em` |
| `--button-trim` | `0em` |
| `--button-weight` | `700` |

System tokens it reads: `--blur-callout`, `--brand-deep`, `--brand-gradient`, `--control-h-lg`, `--control-h-md`, `--control-h-sm`, `--danger-fill`, `--danger-gradient`, `--danger-ink`, `--danger-line`, `--density`, `--dur`, `--ease`, `--focus-gap`, `--focus-ring`, `--font-body`, `--glass-edge`, `--glass-edge-strong`, `--glow-danger`, `--glow-danger-hover`, `--glow-md`, `--glow-md-hover`, `--glow-sm`, `--ink-brand`, `--ink-disabled`, `--ink-heading`, `--ink-inverse`, `--ink-muted`, `--r-2xs`, `--r-lg`, `--r-md`, `--r-sm`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-contact`, `--rgb-danger`, `--rgb-shade`, `--rgb-white`, `--shadow-control`, `--shadow-specular`, `--shadow-specular-dark`, `--surface-solid`, `--wash-active`, `--wash-hover`, `--wash-subtle`.

## Accessibility

- Renders a real <button type="button"> (or a Next <Link>), so Enter and Space work and the role is right with no ARIA.
- Focus is a 2px ring with a white gap (--focus-ring), drawn with box-shadow so it follows the radius.
- Loading sets aria-busy and disables the button; keep the loadingLabel short and present tense ("Saving…").
- A link with disabled renders a non-focusable span with role="link" and aria-disabled, never a dead href.
- Square icon sizes have no text: give them aria-label (or use IconButton, which requires a label).
- Every button carries data-slot="button", data-variant and data-size, for styling from a CSS Module without new props.
- Primary text must hold 4.5:1 on the gradient's light stop; re-check it in the Studio's Contrast tab when a theme changes the gradient.

## Do

- Use one primary per view: the action the screen exists for.
- Write labels as verbs plus the object: "Add team member", "Send question".
- Use dangerSecondary for the step that leads to a destructive confirm, and danger only on the confirm itself.

## Don't

- Never scale a button on hover; hover deepens the glow (no lift: --button-lift is 0 in the default theme).
- Don't put two primary buttons side by side; demote one to secondary.
- Don't fade a disabled gradient; the flat tint is the disabled state.
- Don't use Button for navigation inside text; use a plain link.

Related: https://rime.mjsons.net/components/icon-button, https://rime.mjsons.net/components/modal

---

# IconButton

> A square action with only an icon, a required accessible label and a tooltip-friendly hit area.

Category: Actions. Docs page: https://rime.mjsons.net/components/icon-button

## Installation

```bash
npx shadcn@latest add KezLahd/rime/icon-button
```

IconButton is for compact, well-known actions (close, more, print, remove) where a label would crowd the layout. It takes the same variants as Button, minus the danger secondary, and a pressed state for toggles.

## Usage

```tsx
import { IconButton, IconX } from "@/components/ui";

<IconButton label="Close" icon={<IconX size={18} />} onClick={onClose} />
```

## Props: IconButton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` |  | Required: an icon-only control has no other accessible name. |
| `icon` (required) | `ReactNode` |  |  |
| `variant` | `"ghost" \| "secondary" \| "primary" \| "danger"` | `"ghost"` |  |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` |  |
| `loading` | `boolean` |  |  |
| `pressed` | `boolean` |  | Makes it a toggle button (aria-pressed). |
| `asChild` | `boolean` |  | Render the single child element (a Next <Link>, an <a>) with the icon button's look; pass the icon inside the child. |

Also accepts the native attributes of: AriaAttributes, ButtonHTMLAttributes, DOMAttributes, HTMLAttributes.

## Examples

### Variants and states

```tsx
<IconButton label="More actions" icon={<IconMoreHorizontal size={18} />} />
<IconButton label="Print invoice" icon={<IconPrinter size={17} />} variant="secondary" />
<IconButton label="Add project" icon={<IconPlus size={17} />} variant="primary" />
<IconButton label="Filter" icon={<IconFilter size={16} />} pressed />
<IconButton label="Loading" icon={<IconMail size={16} />} loading />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--button-height-lg` | `var(--control-h-lg)` |
| `--button-height-md` | `var(--control-h-md)` |
| `--button-height-sm` | `var(--control-h-sm)` |
| `--icon-button-radius` | `var(--r-xs)` / `var(--r-sm)` / `var(--r-md)` |

System tokens it reads: `--blur-callout`, `--brand-gradient`, `--control-h-lg`, `--control-h-md`, `--control-h-sm`, `--danger-fill`, `--danger-ink`, `--dur`, `--ease`, `--focus-ring`, `--glass-edge-strong`, `--glow-md`, `--glow-md-hover`, `--glow-sm`, `--ink-brand`, `--ink-disabled`, `--ink-heading`, `--ink-inverse`, `--ink-muted`, `--r-md`, `--r-sm`, `--r-xs`, `--rgb-brand-deep`, `--rgb-contact`, `--rgb-danger`, `--rgb-white`, `--shadow-control`, `--shadow-specular`, `--shadow-specular-dark`, `--surface-solid`, `--wash-active`, `--wash-subtle`.

## Accessibility

- label is required and becomes the accessible name (aria-label); the icon is hidden from assistive tech.
- pressed sets aria-pressed for toggle buttons.
- sm is 28px: only inside dense rows. Use md (36px) or lg (44px) where it is the main target on touch.

## Do

- Pair an unfamiliar icon with a Tooltip carrying the same label.

## Don't

- Don't use an IconButton for the primary action of a screen; it needs words.

Related: https://rime.mjsons.net/components/button, https://rime.mjsons.net/components/tooltip

---

# ButtonGroup

> Joins Buttons and IconButtons into one segmented row or column with shared outer corners.

Category: Actions. Docs page: https://rime.mjsons.net/components/button-group

## Installation

```bash
npx shadcn@latest add KezLahd/rime/button-group
```

ButtonGroup shapes related actions into one control: the outer corners keep the buttons' radius, the joins between them are square, and neighbouring edges share a single hairline. It only shapes; each button keeps its own variant, size, loading and disabled state.

Use it for a split button (a primary action plus a chevron for its options), a pair of previous and next buttons, or a short set of related secondary actions. For a choice that stays selected, use ToggleGroup or SegmentedControl instead.

## Usage

```tsx
import { Button, ButtonGroup } from "@/components/ui";

<ButtonGroup aria-label="Invoice actions">
  <Button variant="secondary">Archive</Button>
  <Button variant="secondary">Report</Button>
</ButtonGroup>
```

## Props: ButtonGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | horizontal (default) joins left to right; vertical stacks top to bottom. |

Also accepts the native attributes of: AriaAttributes, DOMAttributes, HTMLAttributes.

## Examples

### Groups and a split button

```tsx
<ButtonGroup aria-label="Invoice actions">
  <Button variant="secondary">Archive</Button>
  <Button variant="secondary">Report</Button>
  <Button variant="secondary">Snooze</Button>
</ButtonGroup>
<ButtonGroup aria-label="Send">
  <Button>Send invoice</Button>
  <IconButton variant="primary" label="More send options" icon={<IconChevronDown size={16} />} />
</ButtonGroup>
```

### Vertical

```tsx
<ButtonGroup orientation="vertical" aria-label="Order view">
  <Button variant="secondary">Details</Button>
  <Button variant="secondary">Line items</Button>
  <Button variant="secondary">History</Button>
</ButtonGroup>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--button-group-join` | `0` |

## Accessibility

- Renders role="group" with aria-orientation. Give it an aria-label that names the set ("Invoice actions").
- Every button stays a real, separately focusable button in reading order; hover and focus lift the button over its neighbours so its focus ring is drawn whole.

## Do

- Keep a group to one variant, except a split button's primary half.
- Group two to five actions that belong together.

## Don't

- Don't use a ButtonGroup for a selected state; that is ToggleGroup or SegmentedControl.
- Don't put two primary buttons in one group.

Related: https://rime.mjsons.net/components/button, https://rime.mjsons.net/components/toggle-group

---

# TextInput

> The text field: a white box with a tinted edge, a brand halo on focus, adornments and a password reveal.

Category: Forms. Docs page: https://rime.mjsons.net/components/text-input

## Installation

```bash
npx shadcn@latest add KezLahd/rime/text-input
```

TextInput is the one box every text-like field wears: Textarea, Select's field trigger, DateField, SearchField and PrefixedInput all share its --input-* tokens, so one theme change moves them together.

Focus is drawn on the whole box, adornments included (a leading icon, a trailing unit, the reveal button), never on the bare <input>. Invalid warms the fill and turns the edge to the danger hue; read-only is a dashed sunken box; disabled is flat and sunken.

It is a plain controlled or uncontrolled <input>: every native attribute passes through (type, autoComplete, inputMode, maxLength).

## Usage

```tsx
import { Field, TextInput } from "@/components/ui";

<Field label="Email" hint="We send the sign-in link here.">
  <TextInput type="email" autoComplete="email" value={email} onChange={(e) => setEmail(e.target.value)} />
</Field>
```

## Props: TextInput

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `leadingIcon` | `ReactNode` |  |  |
| `trailing` | `ReactNode` |  | Right-hand slot inside the box: a unit ("%"), a clear button. |
| `mono` | `boolean` |  | Monospace with slight tracking, for ID numbers, references, postcodes. |
| `invalid` | `boolean` |  | Overrides the Field's invalid state. |
| `revealable` | `boolean` |  | Adds a show/hide toggle. Only meaningful with type="password". |
| `defaultRevealed` | `boolean` | `false` | Starts with the password readable. For the styleguide and review screens. |
| `size` | `"sm" \| "md"` | `"md"` |  |
| `boxClassName` | `string` |  | Class for the outer box rather than the <input>. |

Also accepts the native attributes of: AriaAttributes, DOMAttributes, HTMLAttributes, InputHTMLAttributes.

## Props: Field

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `ReactNode` |  |  |
| `hint` | `ReactNode` |  |  |
| `error` | `ReactNode` |  | Presence marks the control invalid. Say what to do, not just what is wrong. |
| `required` | `boolean` | `false` |  |
| `optional` | `boolean` |  | Shows "(optional)". Use on forms where most fields are required. |
| `id` | `string` |  | Pass to link a field to an ErrorSummary entry. Generated otherwise. |
| `group` | `boolean` |  | fieldset + legend, for RadioGroup, a checkbox list, OtpInput, DateField. |
| `labelStyle` | `"sentence" \| "caps"` | `"sentence"` | sentence = 13px bold (default, reads well for long labels). caps = the reference 11.5px uppercase micro-label, for short auth/admin forms. |
| `labelAction` | `ReactNode` |  | Something on the label's right edge, e.g. a "Forgot password?" link. |
| `hideLabel` | `boolean` |  |  |
| `className` | `string` |  |  |
| `children` (required) | `ReactNode` |  |  |

## Examples

### In a Field

Label, hint and error come from Field; the input reads them from context.

```tsx
<Field label="Project name" hint="Shown to everyone on the team.">
  <TextInput placeholder="e.g. Atlas redesign" />
</Field>
```

### Adornments and reveal

```tsx
<TextInput leadingIcon={<IconSearch size={16} />} placeholder="Search" />
<TextInput trailing="kg" inputMode="decimal" />
<TextInput type="password" revealable autoComplete="current-password" />
```

### States

```tsx
<Field label="Postcode" error="Enter a 4-digit postcode.">
  <TextInput invalid defaultValue="20" />
</Field>
<TextInput readOnly defaultValue="INV-1042" mono />
<TextInput disabled placeholder="Disabled" />
<TextInput size="sm" placeholder="Small" />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--field-focus-border` | `rgba(var(--rgb-brand), 0.7)` / `var(--focus-color)` |
| `--field-focus-ring` | `var(--focus-halo)` |
| `--field-focus-ring-invalid` | `0 0 0 4px rgba(var(--rgb-danger), 0.14)` |
| `--field-hover-border` | `rgba(var(--rgb-brand-deep), 0.3)` |
| `--input-bg` | `var(--surface-solid)` |
| `--input-border` | `var(--line-input)` |
| `--input-border-width` | `var(--border-w-field)` |
| `--input-font-size` | `var(--text-input)` |
| `--input-height-md` | `var(--field-h-md)` |
| `--input-height-sm` | `var(--field-h-sm)` |
| `--input-pad-x` | `calc(14px * var(--density))` |
| `--input-radius` | `var(--r-md)` / `var(--r-sm)` |
| `--input-shadow` | `var(--shadow-input)` |

System tokens it reads: `--border-w-field`, `--danger-base`, `--danger-field-fill`, `--danger-ink`, `--density`, `--dur`, `--ease`, `--field-h-md`, `--field-h-sm`, `--focus-color`, `--focus-halo`, `--font-body`, `--font-mono`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-muted`, `--ink-placeholder`, `--ink-secondary`, `--line-input`, `--r-md`, `--r-sm`, `--r-xs`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-danger`, `--shadow-input`, `--surface-solid`, `--surface-sunken`, `--text-body`, `--text-caption`, `--text-input`, `--text-small`, `--wash-subtle`.

## Accessibility

- Wrap it in <Field label=…>: Field wires the label, hint and error to the control (id, aria-describedby, aria-invalid) through context, so the control needs no ids of its own.
- Placeholder ink holds 4.97:1 on the white box; never put instructions only in a placeholder.
- revealable adds a real button inside the box whose name switches between "Show password" and "Hide password" (no aria-pressed, which would read as "Hide password, pressed").
- Set autoComplete on every personal-data field (WCAG 1.3.5).

## Do

- Size the box to the content where the content is short (a postcode), with a className width.

## Don't

- Don't style the <input> itself; theme the box with --input-* tokens.
- Don't show an error before the user has left the field or submitted.

Related: https://rime.mjsons.net/components/select, https://rime.mjsons.net/components/textarea, https://rime.mjsons.net/components/search-field

---

# Textarea

> Multi-line text in the TextInput box, resizable vertically, with an optional character count.

Category: Forms. Docs page: https://rime.mjsons.net/components/textarea

## Installation

```bash
npx shadcn@latest add KezLahd/rime/textarea
```

Textarea wears the TextInput box and tokens. showCount with maxLength shows a live count that turns to warning ink near the limit.

## Usage

```tsx
import { Field, Textarea } from "@/components/ui";

<Field label="Note for the customer">
  <Textarea maxLength={1000} showCount rows={4} />
</Field>
```

## Props: Textarea

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `invalid` | `boolean` |  |  |
| `showCount` | `boolean` |  | Shows "n / max" under the box. Requires maxLength and a controlled value. |

Also accepts the native attributes of: AriaAttributes, DOMAttributes, HTMLAttributes, TextareaHTMLAttributes.

## Examples

### With a count

```tsx
<Textarea maxLength={280} showCount placeholder="Plain language." />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--input-font-size` | `var(--text-input)` |
| `--input-pad-x` | `calc(14px * var(--density))` |

System tokens it reads: `--density`, `--font-body`, `--ink-body`, `--ink-disabled`, `--ink-muted`, `--ink-placeholder`, `--text-caption`, `--text-input`, `--warning-ink`.

## Accessibility

- Wrap it in <Field label=…>: Field wires the label, hint and error to the control (id, aria-describedby, aria-invalid) through context, so the control needs no ids of its own.
- The count sits in a polite live region tied to the textarea by aria-describedby.

## Do

- Give a maxLength whenever the server has one.

## Don't

- Don't disable resize; vertical resize is the user's.

---

# Select

> A custom listbox: a recessed field or filter chip that opens a frosted popover, optionally searchable.

Category: Forms. Docs page: https://rime.mjsons.net/components/select

## Installation

```bash
npx shadcn@latest add KezLahd/rime/select
```

Select replaces the native <select> with a combobox and a listbox popover that keeps the design system's look while matching native keyboard behaviour. It has two appearances: field (a grey frosted recess, so a choice reads as something you press rather than type in) and chip (the compact filter dropdown used in a FilterBar).

Options can be grouped (consecutive options sharing group), described (a second line), disabled, and counted (filter dropdowns show how many rows each option would show). searchable adds a pinned search well with keyword matching for long lists.

The popover portals to document.body, flips above the trigger when there is no room below, and returns focus to the trigger on close.

## Usage

```tsx
import { Field, Select } from "@/components/ui";

<Field label="Topic">
  <Select
    value={topic}
    onChange={setTopic}
    placeholder="Choose a topic"
    options={[
      { value: "billing", label: "Billing and invoices" },
      { value: "access", label: "Account access" },
    ]}
  />
</Field>
```

## Props: Select

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` (required) | `ReadonlyArray<SelectOption<V>>` |  |  |
| `value` (required) | `V \| null` |  |  |
| `onChange` (required) | `(value: V) => void` |  |  |
| `placeholder` | `string` | `"Select…"` |  |
| `appearance` | `"field" \| "chip"` | `"field"` | field = bordered form control. chip = the reference recessed filter-bar chip. |
| `size` | `"sm" \| "md"` | `"md"` |  |
| `disabled` | `boolean` |  |  |
| `invalid` | `boolean` |  |  |
| `required` | `boolean` |  |  |
| `id` | `string` |  |  |
| `name` | `string` |  | Emits a hidden input so the value posts with a native form. |
| `active` | `boolean` |  | Chip only: shows the "filter applied" tint. Defaults to value !== null. |
| `leadingIcon` | `ReactNode` |  |  |
| `className` | `string` |  |  |
| `searchable` | `boolean` | `false` | A search box pinned at the top of the list. Typing filters by label, description, group and keywords, and highlights the match. For long lists (countries, cities, time zones); a short list reads faster without. |
| `searchPlaceholder` | `string` | `"Search"` | Placeholder, and accessible name, of the search box. |
| `aria-label` | `string` |  |  |
| `aria-labelledby` | `string` |  |  |
| `aria-describedby` | `string` |  |  |
| `onBlur` | `() => void` |  |  |
| `inline` | `boolean` | `false` | Render the list open, in place under the trigger: no portal, no focus move, no outside-click listener, no scrolling into view. For docs and thumbnails. |

## Examples

### Open

inline renders the list open under its trigger, in place: how it looks when someone opens it.

```tsx
<Select inline aria-label="Topic" value={topic} onChange={setTopic} options={TOPICS} />
```

### Field appearance

```tsx
<Select value={value} onChange={setValue} placeholder="Choose a topic" options={TOPICS} />
```

### Chip appearance (filters)

active marks a chip whose filter is applied; count shows the rows each option would leave.

```tsx
<Select
  appearance="chip"
  aria-label="Status"
  value={status}
  onChange={setStatus}
  active={status !== "all"}
  options={[
    { value: "all", label: "All statuses" },
    { value: "sent", label: "Sent", count: 2 },
    { value: "paid", label: "Paid", count: 5 },
  ]}
/>
```

### Searchable, grouped

```tsx
<Select searchable value={project} onChange={setProject} placeholder="Choose a project" options={PROJECTS} />
```

### Invalid and disabled

```tsx
<Select invalid … />
<Select disabled … />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--chip-height` | `var(--control-h-sm)` |
| `--chip-radius` | `var(--r-sm)` |
| `--field-focus-border` | `rgba(var(--rgb-brand), 0.7)` / `var(--focus-color)` |
| `--field-focus-ring` | `var(--focus-halo)` |
| `--field-focus-ring-invalid` | `0 0 0 4px rgba(var(--rgb-danger), 0.14)` |
| `--field-hover-border` | `rgba(var(--rgb-brand-deep), 0.3)` |
| `--input-bg` | `var(--surface-solid)` |
| `--input-border` | `var(--line-input)` |
| `--input-border-width` | `var(--border-w-field)` |
| `--input-font-size` | `var(--text-input)` |
| `--input-height-md` | `var(--field-h-md)` |
| `--input-height-sm` | `var(--field-h-sm)` |
| `--input-pad-x` | `calc(14px * var(--density))` |
| `--input-radius` | `var(--r-md)` / `var(--r-sm)` |
| `--input-shadow` | `var(--shadow-input)` |
| `--popover-item-active-bg` | `linear-gradient(to right, rgba(var(--rgb-brand), 0.14), rgba(var(--rgb-brand-deep), 0.07))` |
| `--popover-item-radius` | `var(--r-xs)` |
| `--popover-pad` | `calc(6px * var(--density))` |
| `--popover-radius` | `var(--r-lg)` |
| `--recess-fill-disabled` | `rgba(var(--rgb-white), 0.3)` |
| `--recess-line-disabled` | `rgba(var(--rgb-brand-deep), 0.1)` |

System tokens it reads: `--blur-recess`, `--border-w`, `--border-w-field`, `--brand`, `--brand-deep`, `--chip-active-fill`, `--chip-active-fill-hover`, `--chip-active-shadow`, `--control-h-sm`, `--danger-base`, `--danger-field-fill`, `--density`, `--dur`, `--dur-fast`, `--ease`, `--ease-out`, `--field-h-md`, `--field-h-sm`, `--focus-color`, `--focus-halo`, `--focus-ring`, `--font-body`, `--font-mono`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-muted`, `--ink-placeholder`, `--ink-secondary`, `--line-input`, `--line-soft`, `--popover-blur`, `--popover-border`, `--popover-shadow`, `--popover-surface`, `--r-2xs`, `--r-lg`, `--r-md`, `--r-sm`, `--r-xs`, `--recess-fill`, `--recess-fill-hover`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-contact`, `--rgb-danger`, `--rgb-white`, `--shadow-input`, `--shadow-recess`, `--surface-solid`, `--surface-sunken`, `--text-body`, `--text-caption`, `--text-input`, `--text-micro`, `--text-small`, `--tracking-label`, `--wash-active`, `--wash-strong`, `--wash-subtle`, `--z-popover`.

## Accessibility

- The trigger is role="combobox" with aria-expanded, aria-controls and aria-activedescendant; options are role="option" with aria-selected.
- Keyboard: Down, Up, Enter, Space, Home and End open it; Up/Down/Home/End/PageUp/PageDown move; typing jumps to the next label starting with those letters (closed, it selects); Enter or Space selects; Esc clears a search first, then closes, and stops there so an enclosing Modal stays open; Tab closes without selecting and moves on.
- Searchable lists announce the result count through a polite status region.
- A chip has no visible label, so aria-label is required on it.
- Wrap it in <Field label=…>: Field wires the label, hint and error to the control (id, aria-describedby, aria-invalid) through context, so the control needs no ids of its own.

## Do

- Use appearance="chip" inside FilterBar, and "field" in forms.
- Turn on searchable past roughly 12 options.
- Use RadioGroup instead when there are 2 to 4 options a user should compare at a glance.

## Don't

- Don't use a native <select>; it cannot take the theme.
- Don't put actions ("Add new…") inside the options; that is a Menu.

Related: https://rime.mjsons.net/components/text-input, https://rime.mjsons.net/components/filter-bar, https://rime.mjsons.net/components/radio-group, https://rime.mjsons.net/components/menu

---

# SearchField

> Field-size search on the grey frosted recess: clear button, loading state and an optional key hint.

Category: Forms. Docs page: https://rime.mjsons.net/components/search-field

## Installation

```bash
npx shadcn@latest add KezLahd/rime/search-field
```

SearchField is the search box on a page (not in a filter row, where FilterSearch lives). It lifts toward white while focused, shows a clear button once there is a query, and can show a shortcut hint ("/") that focuses it from anywhere.

## Usage

```tsx
import { SearchField } from "@/components/ui";

<SearchField aria-label="Search invoices" value={q} onValueChange={setQ} placeholder="Customer or invoice number" />
```

## Props: SearchField

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` |  |  |
| `onValueChange` (required) | `(value: string) => void` |  |  |
| `size` | `"sm" \| "md"` | `"md"` | md sits level with TextInput and Select; sm with the 36px controls. |
| `loading` | `boolean` | `false` | Results are being fetched. The magnifier turns into a spinner and the field reports busy. |
| `loadingLabel` | `string` | `"Searching…"` | Announced while loading. |
| `shortcut` | `string` |  | A letter that focuses the field with Ctrl/⌘. Shows as a key badge while the field is empty and unfocused. Use once per page. |
| `onSearch` | `(value: string) => void` |  | Enter runs this (and never submits an enclosing form). Omit for live filtering. |
| `invalid` | `boolean` |  |  |
| `boxClassName` | `string` |  | Class for the outer box rather than the <input>. |

Also accepts the native attributes of: AriaAttributes, DOMAttributes, HTMLAttributes, InputHTMLAttributes.

## Examples

### Default, loading

```tsx
<SearchField value={q} onValueChange={setQ} loading={pending} shortcut="/" aria-label="Search" />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--field-focus-border` | `rgba(var(--rgb-brand), 0.7)` |
| `--field-focus-ring` | `var(--focus-halo)` |
| `--field-focus-ring-invalid` | `0 0 0 4px rgba(var(--rgb-danger), 0.14)` |
| `--input-border-width` | `var(--border-w-field)` |
| `--input-font-size` | `var(--text-input)` |
| `--input-height-md` | `var(--field-h-md)` |
| `--input-height-sm` | `var(--field-h-sm)` |
| `--input-radius` | `var(--r-md)` / `var(--r-sm)` |

System tokens it reads: `--blur-recess`, `--border-w-field`, `--danger-base`, `--density`, `--dur`, `--ease`, `--field-h-md`, `--field-h-sm`, `--focus-halo`, `--focus-ring`, `--font-body`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-muted`, `--r-2xs`, `--r-md`, `--r-sm`, `--r-xs`, `--recess-fill`, `--recess-fill-hover`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-danger`, `--rgb-white`, `--shadow-recess`, `--text-body`, `--text-input`, `--text-micro`, `--wash-active`, `--wash-strong`.

## Accessibility

- Renders input type="search". Esc clears the query and stops there, so an enclosing modal stays open; a second Esc on an empty field bubbles. The clear button returns focus to the input.
- Give it an aria-label or a Field label.

## Do

- Debounce the query yourself; the field reports every keystroke.

## Don't

- Don't use it inside a FilterBar; use FilterSearch there so heights match.

---

# Checkbox

> A native checkbox drawn as a gradient tick, plain or as a selectable card, with indeterminate.

Category: Forms. Docs page: https://rime.mjsons.net/components/checkbox

## Installation

```bash
npx shadcn@latest add KezLahd/rime/checkbox
```

Checkbox keeps the real <input type="checkbox"> (visually hidden, focusable, form-posting) and draws the box beside it. variant="card" turns the whole option into a bordered target for statements a user agrees to (terms, declarations).

## Usage

```tsx
import { Checkbox } from "@/components/ui";

<Checkbox label="I accept the workspace terms" checked={ok} onChange={(e) => setOk(e.target.checked)} />
```

## Props: Checkbox

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `ReactNode` |  |  |
| `description` | `ReactNode` |  |  |
| `indeterminate` | `boolean` |  |  |
| `error` | `ReactNode` |  | Error text for a standalone checkbox (a declaration, accepting the terms). |
| `invalid` | `boolean` |  |  |
| `variant` | `"plain" \| "card"` | `"plain"` | plain = box and label. card = a bordered opt-in box that washes accent when ticked (declarations, an opt-in to email updates). |

Also accepts the native attributes of: AriaAttributes, DOMAttributes, HTMLAttributes, InputHTMLAttributes.

## Examples

### Plain, card, indeterminate

```tsx
<Checkbox label="Email me updates" />
<Checkbox variant="card" label="I accept the terms" description="Required to continue." />
<Checkbox indeterminate label="Select all" />
```

## Theme tokens

System tokens it reads: `--brand`, `--brand-gradient`, `--danger-base`, `--danger-field-fill`, `--danger-ink`, `--dur`, `--ease`, `--focus-ring`, `--glow-sm`, `--ink-body`, `--ink-disabled`, `--ink-heading`, `--ink-inverse`, `--ink-muted`, `--line`, `--neutral-border`, `--r-2xs`, `--r-lg`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-contact`, `--rgb-danger`, `--rgb-white`, `--surface-solid`, `--surface-sunken`, `--text-body`, `--text-caption`.

## Accessibility

- The label is the <label> of the real input, so the whole row toggles it.
- error renders under the option and is tied by aria-describedby.

## Do

- Use the card variant for statements a user signs up to.

## Don't

- Don't use a checkbox to trigger an immediate action; that is a Switch.

---

# RadioGroup

> One choice from a few: a list, inline, or cards in 1 to 3 columns.

Category: Forms. Docs page: https://rime.mjsons.net/components/radio-group

## Installation

```bash
npx shadcn@latest add KezLahd/rime/radio-group
```

RadioGroup renders real radio inputs in a fieldset. The cards variant suits two to four choices that need a sentence each (a billing period, a plan).

## Usage

```tsx
import { RadioGroup } from "@/components/ui";

<RadioGroup aria-label="Billing period" value={period} onChange={setPeriod} options={[{ value: "monthly", label: "Monthly" }, { value: "yearly", label: "Yearly" }]} />
```

## Props: RadioGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` (required) | `ReadonlyArray<RadioOption<V>>` |  |  |
| `value` (required) | `V \| null` |  |  |
| `onChange` (required) | `(value: V) => void` |  |  |
| `name` | `string` |  | Shared native name. Generated if omitted; arrow keys work across the group natively. |
| `variant` | `"list" \| "inline" \| "cards"` | `"list"` | list = stacked radios. inline = radios in a row (Yes / No). cards = choice cards: title + description tiles (withdrawal source, delivery destination). |
| `columns` | `1 \| 2 \| 3` | `2` | cards only. Collapses to one column under 640px. |
| `invalid` | `boolean` |  |  |
| `disabled` | `boolean` |  |  |
| `required` | `boolean` |  |  |
| `aria-label` | `string` |  |  |
| `aria-labelledby` | `string` |  |  |
| `className` | `string` |  |  |

## Examples

### Cards

```tsx
<RadioGroup variant="cards" columns={3} value={v} onChange={setV} options={PERIODS} aria-label="Billing period" />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--columns` | `2` |

System tokens it reads: `--brand`, `--brand-gradient`, `--danger-base`, `--danger-field-fill`, `--dur`, `--ease`, `--focus-ring`, `--glow-sm`, `--ink-body`, `--ink-disabled`, `--ink-heading`, `--ink-muted`, `--line`, `--neutral-border`, `--r-lg`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-contact`, `--rgb-danger`, `--rgb-white`, `--surface-solid`, `--surface-sunken`, `--text-body`, `--text-caption`, `--text-small`.

## Accessibility

- Arrow keys move the choice within the group, as native radios do.
- Radio dots stay round in every theme: a square radio reads as a checkbox.

## Do

- Prefer RadioGroup over Select for 2 to 4 options.

## Don't

- Don't preselect a choice the user must consciously make (accepting terms, a paid plan).

---

# Switch

> An on/off setting that takes effect immediately, with a loading state while it saves.

Category: Forms. Docs page: https://rime.mjsons.net/components/switch

## Installation

```bash
npx shadcn@latest add KezLahd/rime/switch
```

Switch is role="switch" on a button. Use it for settings that apply at once; use Checkbox inside forms that are submitted.

## Usage

```tsx
import { Switch } from "@/components/ui";

<Switch label="Email me when an invoice is paid" checked={on} onChange={setOn} />
```

## Props: Switch

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` (required) | `boolean` |  |  |
| `onChange` (required) | `(checked: boolean) => void` |  |  |
| `label` (required) | `ReactNode` |  |  |
| `description` | `ReactNode` |  |  |
| `disabled` | `boolean` |  |  |
| `loading` | `boolean` |  | The change is saving. Blocks input and shows a spinner in the thumb. |
| `id` | `string` |  |  |
| `labelPosition` | `"start" \| "end"` | `"end"` | Label on the left, switch pushed right: for settings rows. |
| `className` | `string` |  |  |

## Examples

### States

```tsx
<Switch label="Saving" checked loading onChange={…} />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--r-flat` | `5px` |

System tokens it reads: `--brand-gradient`, `--dur`, `--ease`, `--focus-ring`, `--glow-md`, `--glow-sm`, `--ink-body`, `--ink-disabled`, `--ink-muted`, `--r-sm`, `--rgb-brand-deep`, `--rgb-contact`, `--shadow-specular`, `--surface-solid`, `--text-body`, `--text-caption`.

## Accessibility

- aria-checked reflects state; loading sets aria-busy and blocks toggling.

## Do

- Say what is on, not what pressing does: "Email notifications".

## Don't

- Don't use a Switch inside a form that has a submit button.

---

# OtpInput

> A six-cell one-time code entry with paste, auto-advance and onComplete.

Category: Forms. Docs page: https://rime.mjsons.net/components/otp-input

## Installation

```bash
npx shadcn@latest add KezLahd/rime/otp-input
```

OtpInput is one real input per cell with roving focus. Pasting a full code fills every cell and fires onComplete.

## Usage

```tsx
import { OtpInput } from "@/components/ui";

<OtpInput aria-label="Authenticator code" value={code} onChange={setCode} onComplete={verify} />
```

## Props: OtpInput

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` |  |  |
| `onChange` (required) | `(value: string) => void` |  |  |
| `onComplete` | `(value: string) => void` |  | Fires once when every box holds a digit, e.g. to auto-submit. |
| `length` | `number` | `6` |  |
| `invalid` | `boolean` |  |  |
| `disabled` | `boolean` |  |  |
| `autoFocus` | `boolean` |  |  |
| `aria-label` | `string` |  | Required when not inside a <Field group>. |
| `className` | `string` |  |  |

## Examples

### Default

```tsx
<OtpInput value={code} onChange={setCode} aria-label="Authenticator code" />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--field-focus-border` | `rgba(var(--rgb-brand), 0.75)` |
| `--field-focus-ring` | `var(--focus-halo)` |
| `--field-focus-ring-invalid` | `0 0 0 4px rgba(var(--rgb-danger), 0.14)` |
| `--field-hover-border` | `rgba(var(--rgb-brand-deep), 0.3)` |

System tokens it reads: `--brand`, `--danger-base`, `--dur`, `--ease`, `--focus-halo`, `--font-mono`, `--ink-disabled`, `--ink-heading`, `--line-input`, `--r-md`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-danger`, `--shadow-input`, `--surface-solid`, `--surface-sunken`.

## Accessibility

- autocomplete="one-time-code" on the first cell lets phones offer the SMS code.

## Do

- Verify on onComplete; don't make users press a button too.

## Don't

- Don't clear the code on a wrong attempt without saying why.

---

# DateField

> A typed DD/MM/YYYY field with a calendar popover, min/max and a date-of-birth preset.

Category: Forms. Docs page: https://rime.mjsons.net/components/date-field

## Installation

```bash
npx shadcn@latest add KezLahd/rime/date-field
```

DateField accepts typing (DD/MM/YYYY, day first) or picking from Calendar. preset="dob" opens on a sensible year with a year dropdown, for dates decades back.

## Usage

```tsx
import { DateField } from "@/components/ui";

<Field label="Due date"><DateField value={due} onChange={setDue} /></Field>
```

## Props: DateField

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `IsoDate \| null` |  |  |
| `onChange` (required) | `(value: IsoDate \| null) => void` |  | null when cleared or when the typed text is not a usable date. |
| `isDateDisabled` | `(date: IsoDate) => boolean` |  |  |
| `min` | `IsoDate` |  |  |
| `max` | `IsoDate` |  |  |
| `defaultMonth` | `IsoDate` |  | Month the calendar opens on when empty. For a date of birth, pass ~40 years ago (or use preset="dob"). |
| `preset` | `"dob"` |  | dob: a date of birth, set up as a sign-up form does it. Month and Year dropdowns in the calendar, years 1920 to this year, no future dates, and an empty field opens 40 years back. Any prop passed explicitly wins over the preset. |
| `captionLayout` | `"label" \| "dropdown"` |  | The calendar's caption. dropdown gives Month ▾ and Year ▾ quick pickers; see Calendar. |
| `fromYear` | `number` |  | Year span of the Year picker (dropdown caption only). |
| `toYear` | `number` |  |  |
| `invalid` | `boolean` |  |  |
| `disabled` | `boolean` |  |  |
| `required` | `boolean` |  |  |
| `id` | `string` |  |  |
| `name` | `string` |  |  |
| `placeholder` | `string` | `"DD/MM/YYYY"` |  |
| `aria-label` | `string` |  |  |
| `className` | `string` |  |  |
| `inline` | `boolean` | `false` | Show the calendar open, in place under the field: no portal, no focus move, no outside-click listener. For docs and thumbnails. |

## Props: Calendar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isDateDisabled` | `(date: IsoDate) => boolean` |  | Days that cannot be picked. Still focusable, so keyboard users can pass over them. |
| `min` | `IsoDate` |  |  |
| `max` | `IsoDate` |  |  |
| `defaultMonth` | `IsoDate` |  | Month shown first when there is no value. Defaults to today's month. |
| `autoFocus` | `boolean` |  | Moves focus into the grid on mount (used by DateField's popup). |
| `numberOfMonths` | `1 \| 2 \| 1 \| 2` | `1` | Months side by side. Navigation moves them together. |
| `captionLayout` | `"label" \| "dropdown" \| "label" \| "dropdown"` | `"label"` | label: the month and year as a heading, with month and year arrows. dropdown: Month ▾ and Year ▾ buttons that open quick pickers, for dates years away such as a date of birth (a sign-up form). Month arrows stay. Two-month calendars always use labels. |
| `fromYear` | `number` |  | First and last years the Year picker lists (dropdown only). Default to min's and max's years, else 100 years back and 10 on. They also bound the arrows and keyboard paging, so the grid never shows a year the picker lacks. |
| `toYear` | `number` |  |  |
| `className` | `string` |  |  |
| `value` (required) | `IsoDate \| null \| never` |  |  |
| `onChange` (required) | `(value: IsoDate) => void \| never` |  |  |
| `range` | `never \| DateRange` |  | Range mode. After a start is picked, hovering or arrowing previews the range. |
| `onRangeChange` | `never \| (range: DateRange) => void` |  |  |

## Examples

### Open

inline shows the calendar open under the field, in place.

```tsx
<DateField inline aria-label="Due date" value={due} onChange={setDue} />
```

### Default

```tsx
<DateField value={date} onChange={setDate} min="2026-01-01" />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--field-focus-border` | `rgba(var(--rgb-brand), 0.7)` / `var(--focus-color)` |
| `--field-focus-ring` | `var(--focus-halo)` |

System tokens it reads: `--brand`, `--brand-gradient`, `--danger-ink`, `--dur`, `--dur-fast`, `--ease`, `--ease-out`, `--focus-color`, `--focus-halo`, `--focus-ring`, `--font-body`, `--glow-sm`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-heading`, `--ink-inverse`, `--ink-muted`, `--line`, `--line-brand`, `--line-brand-strong`, `--r-xl`, `--r-xs`, `--rgb-brand`, `--rgb-brand-deep`, `--shadow-float`, `--surface-solid`, `--text-micro`, `--wash-active`, `--wash-hover`, `--wash-strong`, `--wash-subtle`, `--z-popover`.

## Accessibility

- The calendar is a grid with arrow-key navigation; Esc returns focus to the field.

## Do

- Always let people type a date of birth; never force a calendar for it.

## Don't

- Don't mix date orders within one product.

---

# DateRangeFilter

> A date-range chip for filter rows: presets plus a two-month range calendar.

Category: Forms. Docs page: https://rime.mjsons.net/components/date-range-filter

## Installation

```bash
npx shadcn@latest add KezLahd/rime/date-range-filter
```

DateRangeFilter is the date filter in a FilterBar. It reads as a chip like Select's, with presets (last 7 days, this month) and a range calendar.

## Usage

```tsx
import { DateRangeFilter } from "@/components/ui";

<DateRangeFilter aria-label="Issued" value={range} onChange={setRange} />
```

## Props: DateRangeFilter

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `DateRange` |  | Both null = no filter. A half-picked range never reaches onChange. |
| `onChange` (required) | `(value: DateRange) => void` |  |  |
| `presets` | `ReadonlyArray<DateRangePreset>` | `DEFAULT_DATE_RANGE_PRESETS` |  |
| `min` | `IsoDate` |  |  |
| `max` | `IsoDate` |  |  |
| `isDateDisabled` | `(date: IsoDate) => boolean` |  |  |
| `placeholder` | `string` | `"All dates"` | Shown when no range is set. |
| `appearance` | `"chip" \| "field"` | `"chip"` | chip = 32px filter-bar chip. field = form-control height, beside Select. |
| `months` | `1 \| 2` |  | Calendars side by side. Defaults to 2, or 1 under 640px. |
| `disabled` | `boolean` |  |  |
| `invalid` | `boolean` |  |  |
| `id` | `string` |  |  |
| `aria-label` | `string` |  | Names the control. The current range is appended, so it is read too. |
| `className` | `string` |  |  |
| `inline` | `boolean` | `false` | Show the panel open, in place under the trigger: no portal, no focus move, no outside-click listener. For docs and thumbnails. |

## Examples

### Open

inline shows the presets and calendars open under the chip, in place.

```tsx
<DateRangeFilter inline aria-label="Issued" value={range} onChange={setRange} />
```

### Chip

```tsx
<DateRangeFilter value={range} onChange={setRange} aria-label="Date" />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--chip-height` | `var(--control-h-sm)` |
| `--chip-radius` | `var(--r-sm)` |
| `--field-focus-border` | `rgba(var(--rgb-brand), 0.7)` |
| `--field-focus-ring` | `var(--focus-halo)` |
| `--field-focus-ring-invalid` | `0 0 0 4px rgba(var(--rgb-danger), 0.14)` |

System tokens it reads: `--brand-deep`, `--chip-active-fill`, `--chip-active-fill-hover`, `--chip-active-shadow`, `--control-h-sm`, `--danger-base`, `--density`, `--dur`, `--dur-fast`, `--ease`, `--ease-out`, `--focus-color`, `--focus-gap`, `--focus-halo`, `--focus-ring`, `--font-body`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-muted`, `--line`, `--line-brand`, `--line-soft`, `--r-2xs`, `--r-lg`, `--r-md`, `--r-sm`, `--r-xs`, `--recess-fill`, `--recess-fill-hover`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-contact`, `--rgb-danger`, `--rgb-white`, `--shadow-menu`, `--shadow-recess`, `--surface-solid`, `--text-caption`, `--text-input`, `--text-small`, `--wash-active`, `--wash-row`, `--wash-strong`, `--wash-subtle`, `--z-popover`.

## Accessibility

- The clear button is a separate control, so the trigger never nests a button.

## Do

- Put it after the Select chips in a FilterBar.

## Don't

- Don't use it for a single date; that is DateField.

---

# FileDrop

> A drop zone and file picker with type and size checks and per-file status chips.

Category: Forms. Docs page: https://rime.mjsons.net/components/file-drop

## Installation

```bash
npx shadcn@latest add KezLahd/rime/file-drop
```

FileDrop validates type and size client-side, lists files as FileChips with uploading, done and error states, and keeps a real file input for keyboard users.

## Usage

```tsx
import { FileDrop } from "@/components/ui";

<FileDrop files={files} onFilesChange={setFiles} accept={[".pdf"]} multiple={false} />
```

## Props: FileDrop

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `files` (required) | `File[]` |  |  |
| `onFilesChange` (required) | `(files: File[]) => void` |  |  |
| `accept` | `string[]` | `[".pdf", ".jpg", ".jpeg", ".png"]` | Extensions including the dot. Checked by name and MIME type both. |
| `maxSizeBytes` | `number` | `10 * 1024 * 1024` |  |
| `multiple` | `boolean` | `true` |  |
| `disabled` | `boolean` |  |  |
| `invalid` | `boolean` |  |  |
| `title` | `ReactNode` | `"Drop the file here"` |  |
| `description` | `ReactNode` |  | Defaults to a sentence built from accept and maxSizeBytes. |
| `statusFor` | `(file: File) => Pick<FileChipProps, "status" \| "message"> \| undefined` |  | Per-file upload state, keyed by file name. |
| `id` | `string` |  |  |
| `className` | `string` |  |  |
| `forceDragOver` | `boolean` | `false` | Holds the drag-over state without a drag. For the styleguide only. |

## Props: FileChip

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` |  |  |
| `size` (required) | `number` |  |  |
| `status` | `"ready" \| "uploading" \| "done" \| "error"` | `"ready"` | ready = attached, not yet sent. |
| `message` | `ReactNode` |  | Shown under the name; required when status is "error". |
| `onRemove` | `() => void` |  |  |
| `className` | `string` |  |  |

## Examples

### Default

```tsx
<FileDrop files={files} onFilesChange={setFiles} />
```

## Theme tokens

System tokens it reads: `--brand`, `--brand-deep`, `--brand-fill`, `--brand-gradient`, `--brand-gradient-soft`, `--danger-field-fill`, `--danger-fill`, `--danger-ink`, `--danger-line`, `--dur`, `--ease`, `--focus-ring`, `--font-mono`, `--glow-sm`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-heading`, `--ink-inverse`, `--ink-muted`, `--line-brand`, `--line-soft`, `--r-lg`, `--r-md`, `--r-xs`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-contact`, `--rgb-danger`, `--rgb-white`, `--success-fill`, `--success-ink`, `--surface-solid`, `--surface-sunken`, `--text-body`, `--text-caption`, `--text-small`.

## Accessibility

- The "Choose files" button opens the native picker; drag and drop is an enhancement, never the only way.

## Do

- State the accepted types and size limit in description.

## Don't

- Don't trust the client check; validate on the server too.

---

# Field

> Label, hint, error and required marker for any control, wired through context.

Category: Forms. Docs page: https://rime.mjsons.net/components/field

## Installation

```bash
npx shadcn@latest add KezLahd/rime/field
```

Field renders the label and messages and hands ids to the control inside it (useField). group=true renders a fieldset and legend for RadioGroup and Checkbox lists.

## Usage

```tsx
import { Field } from "@/components/ui";

<Field label="Email" required error={errors.email}><TextInput type="email" /></Field>
```

## Props: Field

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `ReactNode` |  |  |
| `hint` | `ReactNode` |  |  |
| `error` | `ReactNode` |  | Presence marks the control invalid. Say what to do, not just what is wrong. |
| `required` | `boolean` | `false` |  |
| `optional` | `boolean` |  | Shows "(optional)". Use on forms where most fields are required. |
| `id` | `string` |  | Pass to link a field to an ErrorSummary entry. Generated otherwise. |
| `group` | `boolean` |  | fieldset + legend, for RadioGroup, a checkbox list, OtpInput, DateField. |
| `labelStyle` | `"sentence" \| "caps"` | `"sentence"` | sentence = 13px bold (default, reads well for long labels). caps = the reference 11.5px uppercase micro-label, for short auth/admin forms. |
| `labelAction` | `ReactNode` |  | Something on the label's right edge, e.g. a "Forgot password?" link. |
| `hideLabel` | `boolean` |  |  |
| `className` | `string` |  |  |
| `children` (required) | `ReactNode` |  |  |

## Examples

### Required, optional, error

```tsx
<Field label="Phone" optional><TextInput /></Field>
```

## Theme tokens

System tokens it reads: `--danger-ink`, `--ink-muted`, `--ink-secondary`, `--text-caption`, `--text-small`.

## Accessibility

- The error is linked by aria-describedby and the control gets aria-invalid.
- labelStyle="caps" is the compact auth-card label; sentence case everywhere else.

## Do

- Mark the rare field instead: if most are required, mark the optional ones.

## Don't

- Don't hide the label; use hideLabel only when a visible heading already names the control.

---

# ErrorSummary

> The list of form errors at the top of a form, focused on submit, each linking to its field.

Category: Forms. Docs page: https://rime.mjsons.net/components/error-summary

## Installation

```bash
npx shadcn@latest add KezLahd/rime/error-summary
```

ErrorSummary follows the GOV.UK pattern: after a failed submit it takes focus, lists every error as a link, and each link moves focus to the field.

## Usage

```tsx
import { ErrorSummary } from "@/components/ui";

<ErrorSummary errors={[{ id: "email", message: "Enter an email address" }]} focusKey={submitCount} />
```

## Props: ErrorSummary

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `errors` (required) | `ReadonlyArray<FormError>` |  |  |
| `title` | `string` |  |  |
| `focusKey` | `number \| string` |  | Change this (e.g. a submit counter) to move focus to the summary again. Focus moves on mount and whenever it changes. |
| `className` | `string` |  |  |

## Examples

### Default

```tsx
<ErrorSummary errors={errors} focusKey={attempt} />
```

## Theme tokens

System tokens it reads: `--danger-fill`, `--danger-gradient`, `--danger-ink`, `--danger-line`, `--dur`, `--ease`, `--focus-color`, `--focus-ring`, `--glow-danger`, `--ink-inverse`, `--ink-muted`, `--ink-secondary`, `--line-soft`, `--r-2xs`, `--r-md`, `--r-sm`, `--rgb-danger`, `--shadow-lift`, `--shadow-specular-dark`, `--surface-solid`, `--text-caption`, `--text-card-title`, `--text-micro`, `--text-small`.

## Accessibility

- role="alert" and focus moves to the summary when focusKey changes, so it is announced once per submit.

## Do

- Use the same message text here and under the field.

## Don't

- Don't show it before the first submit.

---

# PrefixedInput

> A fixed-format code with a set prefix: an invoice number, an account code, a membership number.

Category: Forms. Docs page: https://rime.mjsons.net/components/prefixed-input

## Installation

```bash
npx shadcn@latest add KezLahd/rime/prefixed-input
```

PrefixedInput is the TextInput box with a fixed prefix segment set into its left end ("INV", "ACC-") and a counter at the right. The prefix is part of the box, never typed. charset is digits (the default) or alphanumeric, upper-cased as typed.

It normalises whatever is pasted or autofilled (with or without the prefix, spaces or dashes) and reports both the full code and the body after the prefix. Leaving it part-filled marks it invalid; an empty field is left to the form's required check.

## Usage

```tsx
import { Field, PrefixedInput } from "@/components/ui";

<Field label="Invoice number">
  <PrefixedInput prefix="INV" length={6} value={code} onValueChange={(full) => setCode(full)} />
</Field>
```

## Props: PrefixedInput

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `prefix` | `string` |  | The fixed segment set into the box and never typed: "INV", "ACC", "#". Omit when passing prefixOptions; the selected option's value takes over. |
| `length` | `number` |  | How many characters follow the prefix. Omit when passing prefixOptions; each option carries its own length. |
| `charset` | `PrefixedFormat["charset"]` | `"digits"` | digits = 0-9 only (the default). alphanumeric = A-Z and 0-9, upper-cased as typed. |
| `prefixOptions` | `ReadonlyArray<PrefixedOption>` |  | A list of switchable prefix choices, each with its own length (and charset). The prefix slot becomes a dropdown button; pasting a full code picks the matching option automatically. The first option is the default. For a single hardcoded prefix, use prefix + length instead. |
| `prefixValue` | `string` |  | Controlled: which option is active. onPrefixChange fires when it changes. |
| `onPrefixChange` | `(value: string, option: PrefixedOption) => void` |  |  |
| `value` (required) | `string` |  | The full code ("INV004213") or the body alone; either is read. |
| `onValueChange` (required) | `(code: string, body: string) => void` |  | Every edit. `code` is the full form ("" while nothing is entered, never a bare prefix); `body` is what follows the prefix. |
| `invalid` | `boolean` |  | Overrides the Field's invalid state and the built-in check on blur. |
| `showCounter` | `boolean` | `true` | The "4/6" count at the right of the box. On by default. |
| `boxClassName` | `string` |  | Class for the outer box rather than the <input>. |

Also accepts the native attributes of: AriaAttributes, DOMAttributes, HTMLAttributes, InputHTMLAttributes.

## Examples

### Digits

```tsx
<PrefixedInput prefix="INV" length={6} value={v} onValueChange={(code) => setV(code)} />
```

### Letters and numbers

```tsx
<PrefixedInput prefix="ACC-" length={8} charset="alphanumeric" value={v} onValueChange={(code) => setV(code)} />
```

### Switchable prefix (phone)

prefixOptions turns the prefix into a dropdown. Each option carries its own length so a +61 mobile, a +61 landline, a 1300, a 13 and a 1800 all fit the same field. Pasting a full number picks the matching option automatically. Add validate(body) to catch invalid formats (AU numbers after +61 start with 2, 3, 4, 7, or 8) and detail(body) to show a plain-English hint under the field as the user types.

```tsx
const AU_AREAS = {
  "2": "NSW / ACT landline",
  "3": "VIC / TAS landline",
  "4": "Mobile",
  "7": "QLD landline",
  "8": "WA / SA / NT landline",
};

<PrefixedInput
  prefixOptions={[
    {
      value: "+61",
      label: "Mobile or landline",
      length: 9,
      validate: (b) =>
        AU_AREAS[b[0]]
          ? null
          : "Australian numbers after +61 start with 2 (NSW/ACT), 3 (VIC/TAS), 4 (mobile), 7 (QLD), or 8 (WA/SA/NT).",
      detail: (b) => AU_AREAS[b[0]] ?? null,
    },
    { value: "1300", label: "Business", length: 6, detail: () => "Local-rate business number" },
    { value: "13", label: "Short code", length: 4, detail: () => "National short code (max 4 digits)" },
    { value: "1800", label: "Toll-free", length: 6, detail: () => "Free for the caller" },
  ]}
  value={p}
  onValueChange={(code) => setP(code)}
/>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--field-focus-border` | `rgba(var(--rgb-brand), 0.7)` / `var(--focus-color)` |
| `--field-focus-ring` | `var(--focus-halo)` |
| `--field-focus-ring-invalid` | `0 0 0 4px rgba(var(--rgb-danger), 0.14)` |
| `--field-hover-border` | `rgba(var(--rgb-brand-deep), 0.3)` |
| `--input-bg` | `var(--surface-solid)` |
| `--input-border` | `var(--line-input)` |
| `--input-border-width` | `var(--border-w-field)` |
| `--input-font-size` | `var(--text-input)` |
| `--input-height-md` | `var(--field-h-md)` |
| `--input-height-sm` | `var(--field-h-sm)` |
| `--input-pad-x` | `calc(14px * var(--density))` |
| `--input-radius` | `var(--r-md)` / `var(--r-sm)` |
| `--input-shadow` | `var(--shadow-input)` |

System tokens it reads: `--border-w-field`, `--danger-base`, `--danger-field-fill`, `--danger-ink`, `--danger-line`, `--density`, `--dur`, `--ease`, `--ease-out`, `--field-h-md`, `--field-h-sm`, `--focus-color`, `--focus-halo`, `--font-body`, `--font-mono`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-heading`, `--ink-muted`, `--ink-placeholder`, `--ink-secondary`, `--line`, `--line-input`, `--r-md`, `--r-sm`, `--r-xs`, `--recess-fill`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-danger`, `--rgb-white`, `--shadow-float`, `--shadow-input`, `--success-ink`, `--surface-solid`, `--surface-sunken`, `--text-body`, `--text-caption`, `--text-input`, `--text-small`, `--wash-active`, `--wash-hover`, `--wash-subtle`, `--z-popover`.

## Accessibility

- Wrap it in <Field label=…>: Field wires the label, hint and error to the control (id, aria-describedby, aria-invalid) through context, so the control needs no ids of its own.
- The prefix and the expected length are read out through a visually hidden description tied to the input.
- A refused key shows a short note in the counter and announces it politely, so a refusal is never silent.
- In switchable-prefix mode the dropdown is a listbox: arrow keys move between options, Enter picks, Escape closes and returns focus to the trigger.

## Do

- Validate the full code on the server too.
- Use it only where the format is truly fixed.
- Reach for prefixOptions when the user must pick from a small set of fixed-length formats (phone type, country code, SKU family).

## Don't

- Don't use it for free text that merely starts with a word; use TextInput with a leading adornment.
- Don't put >5 options in the prefix dropdown; use a Combobox or a dedicated phone-country picker instead.

Related: https://rime.mjsons.net/components/text-input

---

# Label

> A standalone form label with required and optional markers, for controls outside a Field.

Category: Forms. Docs page: https://rime.mjsons.net/components/label

## Installation

```bash
npx shadcn@latest add KezLahd/rime/label
```

Field renders its own label and wires it to the control, so most forms never need Label. Use Label when a control sits outside a Field: a custom group, a Slider row, a label beside a Switch in a dense settings list.

required adds a red asterisk; optional adds a muted "(optional)". Mark whichever is rarer on the form. labelStyle="caps" matches Field's compact uppercase label.

## Usage

```tsx
import { Label } from "@/components/ui";

<Label htmlFor="project-name" required>Project name</Label>
<TextInput id="project-name" required />
```

## Props: Label

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `required` | `boolean` |  | Adds a red asterisk after the text. Pair it with required on the control. |
| `optional` | `boolean` |  | Adds a muted "(optional)" after the text. Use it when most fields are required. |
| `disabled` | `boolean` |  | Dims the label to match a disabled control. |
| `labelStyle` | `"sentence" \| "caps"` | `"sentence"` | sentence = 13px bold (default). caps = the compact uppercase micro-label. |

Also accepts the native attributes of: AriaAttributes, DOMAttributes, HTMLAttributes, LabelHTMLAttributes.

## Examples

### Required and optional

```tsx
<Label htmlFor="name" required>Project name</Label>
<TextInput id="name" required />
<Label htmlFor="po" optional>Purchase order</Label>
<TextInput id="po" />
```

### Styles

```tsx
<Label>Sentence label</Label>
<Label labelStyle="caps">Caps label</Label>
<Label disabled>Disabled label</Label>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--label-ink` | `var(--ink-secondary)` |
| `--label-size` | `var(--text-small)` |

System tokens it reads: `--danger-ink`, `--ink-disabled`, `--ink-muted`, `--ink-secondary`, `--text-caption`, `--text-small`.

## Accessibility

- Renders a real <label>. Point htmlFor at the control's id so clicking the label focuses it and the control gets its accessible name.
- The asterisk is hidden from assistive tech; set required on the control itself so it is announced.

## Do

- Prefer Field, which wires label, hint and error for you.
- Write labels as nouns in sentence case.

## Don't

- Don't use a Label without htmlFor (or wrapping the control).
- Don't put instructions in a label; use a hint.

Related: https://rime.mjsons.net/components/field, https://rime.mjsons.net/components/text-input

---

# InputGroup

> A text field with addons joined to it: a fixed text segment, an icon, or a button such as Copy.

Category: Forms. Docs page: https://rime.mjsons.net/components/input-group

## Installation

```bash
npx shadcn@latest add KezLahd/rime/input-group
```

InputGroup wears the TextInput box and its --input-* tokens, with addons set into either end. A string addon ("https://", "$", "kg") is drawn as a sunken text segment divided by a hairline; an element addon (an icon or an IconButton) sits inline.

Focus, invalid, read-only and disabled all draw on the whole group, addons included. The <input> takes every native attribute, and reads its id, required and error state from a surrounding Field.

## Usage

```tsx
import { InputGroup } from "@/components/ui";

<Field label="Website">
  <InputGroup start="https://" placeholder="example.com" />
</Field>
```

## Props: InputGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `start` | `ReactNode` |  | Before the input. A string ("https://", "$") is set off as a sunken text segment with a hairline; an element (an icon, an IconButton) sits inline. |
| `end` | `ReactNode` |  | After the input, the same way: a unit ("kg", ".com") or a button. |
| `size` | `"sm" \| "md"` | `"md"` |  |
| `invalid` | `boolean` |  | Overrides the Field's invalid state. |
| `mono` | `boolean` |  |  |
| `boxClassName` | `string` |  | Class for the outer box rather than the <input>. |

Also accepts the native attributes of: AriaAttributes, DOMAttributes, HTMLAttributes, InputHTMLAttributes.

## Examples

### Text, icon and button addons

```tsx
<InputGroup start="https://" placeholder="example.com" aria-label="Website" />
<InputGroup start={<IconSearch size={16} />} placeholder="Search invoices" aria-label="Search invoices" />
<InputGroup start="$" end="USD" inputMode="decimal" aria-label="Amount" />
<InputGroup readOnly mono defaultValue="sk_live_4f9a2c" aria-label="API key"
  end={<IconButton size="sm" label="Copy key" icon={<Copy size={14} />} />} />
```

### In a Field

```tsx
<Field label="Workspace address" hint="Letters, numbers and dashes.">
  <InputGroup end=".example.app" placeholder="acme" />
</Field>
<Field label="Weight" error="Enter a weight under 30 kg.">
  <InputGroup end="kg" inputMode="decimal" />
</Field>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--field-focus-border` | `rgba(var(--rgb-brand), 0.7)` / `var(--focus-color)` |
| `--field-focus-ring` | `var(--focus-halo)` |
| `--field-focus-ring-invalid` | `0 0 0 4px rgba(var(--rgb-danger), 0.14)` |
| `--field-hover-border` | `rgba(var(--rgb-brand-deep), 0.3)` |
| `--input-addon-bg` | `var(--recess-fill)` |
| `--input-bg` | `var(--surface-solid)` |
| `--input-border` | `var(--line-input)` |
| `--input-border-width` | `var(--border-w-field)` |
| `--input-font-size` | `var(--text-input)` |
| `--input-height-md` | `var(--field-h-md)` |
| `--input-height-sm` | `var(--field-h-sm)` |
| `--input-pad-x` | `calc(14px * var(--density))` |
| `--input-radius` | `var(--r-md)` / `var(--r-sm)` |
| `--input-shadow` | `var(--shadow-input)` |

System tokens it reads: `--border-w`, `--border-w-field`, `--danger-base`, `--danger-field-fill`, `--danger-line`, `--density`, `--dur`, `--ease`, `--field-h-md`, `--field-h-sm`, `--focus-color`, `--focus-halo`, `--font-body`, `--font-mono`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-muted`, `--ink-placeholder`, `--ink-secondary`, `--line`, `--line-input`, `--r-md`, `--r-sm`, `--r-xs`, `--recess-fill`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-danger`, `--shadow-input`, `--surface-solid`, `--surface-sunken`, `--text-body`, `--text-input`, `--text-small`, `--wash-active`, `--wash-subtle`.

## Accessibility

- Text addons are visual only (aria-hidden). If the unit matters to understanding, say it in the label or hint as well ("Weight in kg").
- Button addons are real buttons with their own accessible names, after the input in tab order.
- Wrap it in <Field label=…> so the label, hint and error are wired through context.

## Do

- Use a text addon for a fixed part the user should not type.
- Use PrefixedInput when the whole value has a fixed format.

## Don't

- Don't put more than one button in an addon.
- Don't style the <input> directly; theme the box with --input-* tokens.

Related: https://rime.mjsons.net/components/text-input, https://rime.mjsons.net/components/prefixed-input, https://rime.mjsons.net/components/field

---

# Combobox

> A text field that filters a list of options as you type and picks one, with optional create.

Category: Forms. Docs page: https://rime.mjsons.net/components/combobox

## Installation

```bash
npx shadcn@latest add KezLahd/rime/combobox
```

Combobox is the editable combobox: typing opens a frosted list and narrows it by label, description and keywords. It suits long lists people know the name of (a project, a country, a customer). For a short fixed list a person compares, use Select; Select's searchable mode is the same idea with a button trigger.

Leaving the field restores the chosen option's label, so the text never disagrees with the value. creatable offers "Create …" when the text matches nothing, and hands the text to onCreate.

inline renders the list open in normal flow under the field instead of a portalled popover: for docs, previews and pickers that live inside a panel.

## Usage

```tsx
import { Combobox } from "@/components/ui";

<Field label="Project">
  <Combobox options={PROJECTS} value={project} onChange={setProject} placeholder="Type to search projects" />
</Field>
```

## Props: Combobox

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` (required) | `ReadonlyArray<ComboboxOption>` |  |  |
| `value` (required) | `string \| null` |  |  |
| `onChange` (required) | `(value: string \| null) => void` |  | The chosen option's value, or null when the text is cleared. |
| `placeholder` | `string` |  |  |
| `creatable` | `boolean` |  | Offer "Create …" when the typed text matches no option. onCreate receives the text; add the option and select it there. |
| `onCreate` | `(label: string) => void` |  |  |
| `emptyText` | `string` | `"No matches"` | Shown when nothing matches and creatable is off. |
| `size` | `"sm" \| "md"` | `"md"` |  |
| `disabled` | `boolean` |  |  |
| `invalid` | `boolean` |  |  |
| `id` | `string` |  |  |
| `name` | `string` |  |  |
| `aria-label` | `string` |  |  |
| `defaultOpen` | `boolean` | `false` | Open on mount. |
| `inline` | `boolean` | `false` | Render the list in normal flow under the field instead of portalling a popover, and keep it open. For docs, previews and pickers inside a panel. |
| `className` | `string` |  |  |

## Examples

### Open list

Shown inline so the list is visible; in a form it is a popover.

```tsx
<Combobox inline aria-label="Project" options={PROJECTS} value={project} onChange={setProject} />
```

### In a Field

```tsx
<Field label="Project">
  <Combobox options={PROJECTS} value={project} onChange={setProject} placeholder="Type to search projects" />
</Field>
```

### Creatable

```tsx
<Combobox
  creatable
  options={tags}
  value={tag}
  onChange={setTag}
  onCreate={(label) => {
    const value = slugify(label);
    setTags((t) => [...t, { value, label }]);
    setTag(value);
  }}
/>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--field-focus-border` | `rgba(var(--rgb-brand), 0.7)` / `var(--focus-color)` |
| `--field-focus-ring` | `var(--focus-halo)` |
| `--field-focus-ring-invalid` | `0 0 0 4px rgba(var(--rgb-danger), 0.14)` |
| `--field-hover-border` | `rgba(var(--rgb-brand-deep), 0.3)` |
| `--input-bg` | `var(--surface-solid)` |
| `--input-border` | `var(--line-input)` |
| `--input-border-width` | `var(--border-w-field)` |
| `--input-font-size` | `var(--text-input)` |
| `--input-height-md` | `var(--field-h-md)` |
| `--input-height-sm` | `var(--field-h-sm)` |
| `--input-pad-x` | `calc(14px * var(--density))` |
| `--input-radius` | `var(--r-md)` / `var(--r-sm)` |
| `--input-shadow` | `var(--shadow-input)` |
| `--popover-item-active-bg` | `linear-gradient(to right, rgba(var(--rgb-brand), 0.14), rgba(var(--rgb-brand-deep), 0.07))` |
| `--popover-item-radius` | `var(--r-xs)` |
| `--popover-pad` | `calc(6px * var(--density))` |
| `--popover-radius` | `var(--r-lg)` |

System tokens it reads: `--border-w`, `--border-w-field`, `--brand`, `--danger-base`, `--danger-field-fill`, `--density`, `--dur`, `--dur-fast`, `--ease`, `--ease-out`, `--field-h-md`, `--field-h-sm`, `--focus-color`, `--focus-halo`, `--font-body`, `--font-mono`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-muted`, `--ink-placeholder`, `--ink-secondary`, `--line-input`, `--line-soft`, `--popover-blur`, `--popover-border`, `--popover-shadow`, `--popover-surface`, `--r-lg`, `--r-md`, `--r-sm`, `--r-xs`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-danger`, `--scrollbar-thumb`, `--scrollbar-track`, `--scrollbar-width`, `--shadow-input`, `--surface-solid`, `--surface-sunken`, `--text-body`, `--text-caption`, `--text-input`, `--text-small`, `--wash-subtle`, `--z-popover`.

## Accessibility

- The input is role="combobox" with aria-expanded, aria-controls, aria-autocomplete="list" and aria-activedescendant, so focus stays in the field while Up and Down move the highlight.
- Keyboard: typing filters, Up and Down move (and open), Home and End jump, Enter picks, Esc closes and then clears, Tab closes and moves on.
- The number of results is announced through a polite status region as you type.
- Give it a Field label, or aria-label when it stands alone.

## Do

- Search descriptions and keywords, not only labels.
- Use creatable only where adding a value is safe and expected (tags).

## Don't

- Don't use Combobox for fewer than about eight options; use Select or RadioGroup.
- Don't allow free text that is not saved as an option; that is a TextInput.

Related: https://rime.mjsons.net/components/select, https://rime.mjsons.net/components/command, https://rime.mjsons.net/components/field

---

# Slider

> Picks a number or a range by dragging along a track, with steps, marks and a value readout.

Category: Forms. Docs page: https://rime.mjsons.net/components/slider

## Installation

```bash
npx shadcn@latest add KezLahd/rime/slider
```

Slider takes one value or a [low, high] range (two thumbs that never cross). The chosen span is drawn in the accent gradient over a recessed track. step snaps every value, marks draw labelled ticks, and showValue prints the formatted value beside the label.

Use it where the exact number matters less than its position in a range (volume, a price filter, a threshold). When the exact number matters, pair it with a TextInput or use the input alone.

## Usage

```tsx
import { Slider } from "@/components/ui";

<Slider label="Volume" value={volume} onValueChange={setVolume} showValue formatValue={(n) => `${n}%`} />
```

## Props: Slider

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `min` | `number` | `0` |  |
| `max` | `number` | `100` |  |
| `step` | `number` | `1` |  |
| `largeStep` | `number` |  | PageUp and PageDown move by this much. Defaults to a tenth of the range, rounded to the step. |
| `marks` | `ReadonlyArray<{ value: number; label?: string }>` |  | Ticks under the track, optionally labelled: [{ value: 0, label: "0" }, { value: 50 }]. |
| `formatValue` | `(value: number) => string` | `(v: number) => String(v)` | Formats the value for aria-valuetext and the value readout: (v) => `${v}%`. |
| `showValue` | `boolean` |  | Shows the formatted value (or range) to the right of the label row. |
| `label` | `string` |  | Visible label above the track. Without it, pass aria-label. |
| `aria-label` | `string` |  |  |
| `disabled` | `boolean` |  |  |
| `name` | `string` |  | Posts the value (a range posts two inputs, name[0] and name[1]). |
| `className` | `string` |  |  |
| `value` (required) | `number \| readonly [number, number]` |  | One thumb. |
| `onValueChange` (required) | `(value: number) => void \| (value: [number, number]) => void` |  |  |

## Examples

### Single value

```tsx
<Slider label="Volume" value={v} onValueChange={setV} showValue formatValue={(n) => `${n}%`} />
```

### Range with marks

```tsx
<Slider
  label="Order value"
  value={range}
  onValueChange={setRange}
  min={0}
  max={1000}
  step={50}
  showValue
  formatValue={(n) => `$${n}`}
  marks={[{ value: 0, label: "$0" }, { value: 500, label: "$500" }, { value: 1000, label: "$1,000" }]}
/>
```

### Step and disabled

```tsx
<Slider label="Step 5" value={35} onValueChange={set} step={5} showValue />
<Slider label="Disabled" value={40} onValueChange={set} disabled />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--slider-fill` | `var(--brand-gradient)` |
| `--slider-thumb-bg` | `var(--surface-solid)` |
| `--slider-thumb-size` | `18px` |
| `--slider-track-bg` | `var(--recess-fill-hover)` |
| `--slider-track-h` | `6px` |

System tokens it reads: `--brand`, `--brand-gradient`, `--dur`, `--ease`, `--focus-ring`, `--ink-disabled`, `--ink-heading`, `--ink-muted`, `--ink-secondary`, `--line-input`, `--r-full`, `--recess-fill-hover`, `--rgb-contact`, `--surface-solid`, `--text-caption`, `--text-small`.

## Accessibility

- Each thumb is role="slider" with aria-valuemin, aria-valuemax, aria-valuenow and aria-valuetext (from formatValue), named by the label; range thumbs are named "minimum" and "maximum".
- Keyboard: arrows step, PageUp and PageDown take a large step (a tenth of the range by default), Home and End jump to the ends.
- Pressing anywhere on the track moves the nearest thumb there and focuses it.

## Do

- Format values in the unit people think in ("$500", "60%").
- Use marks for meaningful stops only.

## Don't

- Don't use a slider for a value that must be exact; offer a text field too.
- Don't hide the current value when it matters; turn on showValue.

Related: https://rime.mjsons.net/components/meter, https://rime.mjsons.net/components/text-input

---

# Toggle

> A two-state button, pressed or not, for toolbar formatting and view options.

Category: Forms. Docs page: https://rime.mjsons.net/components/toggle

## Installation

```bash
npx shadcn@latest add KezLahd/rime/toggle
```

Toggle is a real <button> with aria-pressed: quiet at rest, washed in the accent with a hairline when pressed. ghost (the default) has no edge at rest, for toolbars; outline keeps a hairline box, for a lone option such as "Show archived".

Use Switch for a setting that applies at once and reads as on or off; use Checkbox inside a form that is submitted.

## Usage

```tsx
import { Toggle } from "@/components/ui";

<Toggle aria-label="Bold" icon={<Bold size={16} />} pressed={bold} onPressedChange={setBold} />
```

## Props: Toggle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pressed` | `boolean` |  | Controlled pressed state. Leave unset (with defaultPressed) for uncontrolled. |
| `defaultPressed` | `boolean` | `false` |  |
| `onPressedChange` | `(pressed: boolean) => void` |  |  |
| `variant` | `"ghost" \| "outline"` | `"ghost"` | ghost (default) shows no edge at rest; outline keeps a hairline box. |
| `size` | `"sm" \| "md"` | `"md"` |  |
| `icon` | `ReactNode` |  | An icon before the label. An icon-only toggle needs aria-label. |

Also accepts the native attributes of: AriaAttributes, ButtonHTMLAttributes, DOMAttributes, HTMLAttributes.

## Examples

### Icon, text and disabled

```tsx
<Toggle aria-label="Bold" icon={<Bold size={16} />} pressed={bold} onPressedChange={setBold} />
<Toggle variant="outline" pressed={archived} onPressedChange={setArchived}>Show archived</Toggle>
<Toggle disabled>Disabled</Toggle>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--toggle-height-md` | `var(--control-h-md)` |
| `--toggle-height-sm` | `var(--control-h-sm)` |
| `--toggle-ink` | `var(--ink-muted)` |
| `--toggle-on-bg` | `var(--wash-active)` / `var(--surface-solid)` |
| `--toggle-on-ink` | `var(--ink-brand)` |
| `--toggle-on-line` | `var(--line-brand-strong)` |
| `--toggle-radius` | `var(--r-md)` / `var(--r-sm)` |

System tokens it reads: `--border-w`, `--control-h-md`, `--control-h-sm`, `--density`, `--dur`, `--ease`, `--focus-ring`, `--font-body`, `--ink-brand`, `--ink-disabled`, `--ink-heading`, `--ink-muted`, `--line`, `--line-brand-strong`, `--line-input`, `--r-md`, `--r-sm`, `--recess-fill`, `--rgb-white`, `--shadow-hairline-card`, `--shadow-recess`, `--surface-solid`, `--text-small`, `--wash-active`, `--wash-hover`.

## Accessibility

- aria-pressed carries the state, so the label must not change with it: "Bold", pressed or not pressed.
- An icon-only toggle needs aria-label.

## Do

- Keep the label constant; the pressed state says the rest.

## Don't

- Don't use a Toggle to trigger a one-off action; that is a Button.

Related: https://rime.mjsons.net/components/toggle-group, https://rime.mjsons.net/components/switch

---

# ToggleGroup

> A set of toggles sharing one value: single (a clearable radio set) or multiple.

Category: Forms. Docs page: https://rime.mjsons.net/components/toggle-group

## Installation

```bash
npx shadcn@latest add KezLahd/rime/toggle
```

ToggleGroup sits its items on one recessed track and lifts the pressed ones out as solid keys. type="single" allows at most one pressed item, and pressing it again clears the value; type="multiple" allows any number.

It has one tab stop: arrow keys move between items and Space or Enter presses. For a view switch where one option is always chosen, SegmentedControl reads better.

## Usage

```tsx
import { ToggleGroup } from "@/components/ui";

<ToggleGroup
  type="single"
  aria-label="Text alignment"
  value={align}
  onValueChange={setAlign}
  items={[
    { value: "left", icon: <AlignLeft size={16} />, "aria-label": "Align left" },
    { value: "center", icon: <AlignCenter size={16} />, "aria-label": "Align centre" },
  ]}
/>
```

## Props: ToggleGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `ReadonlyArray<ToggleGroupItem>` |  |  |
| `aria-label` (required) | `string` |  | Names the group: "Text formatting", "Days". |
| `variant` | `"ghost" \| "outline" \| "ghost" \| "outline"` | `"outline"` |  |
| `size` | `"sm" \| "md" \| "sm" \| "md"` | `"md"` |  |
| `orientation` | `"horizontal" \| "vertical" \| "horizontal" \| "vertical"` | `"horizontal"` |  |
| `disabled` | `boolean` |  |  |
| `className` | `string` |  |  |
| `type` (required) | `"single" \| "multiple"` |  | single: at most one item pressed, like a radio group that can be cleared. |
| `value` (required) | `string \| null \| ReadonlyArray<string>` |  |  |
| `onValueChange` (required) | `(value: string \| null) => void \| (value: string[]) => void` |  |  |

## Examples

### Single and multiple

```tsx
<ToggleGroup type="single" aria-label="Text alignment" value={align} onValueChange={setAlign} items={ALIGN} />
<ToggleGroup type="multiple" aria-label="Text formatting" value={marks} onValueChange={setMarks} items={MARKS} />
```

### Text items

```tsx
<ToggleGroup type="multiple" size="sm" aria-label="Days" value={days} onValueChange={setDays}
  items={["Mon", "Tue", "Wed"].map((d) => ({ value: d.toLowerCase(), label: d }))} />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--toggle-height-md` | `var(--control-h-md)` |
| `--toggle-height-sm` | `var(--control-h-sm)` |
| `--toggle-ink` | `var(--ink-muted)` |
| `--toggle-on-bg` | `var(--wash-active)` / `var(--surface-solid)` |
| `--toggle-on-ink` | `var(--ink-brand)` |
| `--toggle-on-line` | `var(--line-brand-strong)` |
| `--toggle-radius` | `var(--r-md)` / `var(--r-sm)` |

System tokens it reads: `--border-w`, `--control-h-md`, `--control-h-sm`, `--density`, `--dur`, `--ease`, `--focus-ring`, `--font-body`, `--ink-brand`, `--ink-disabled`, `--ink-heading`, `--ink-muted`, `--line`, `--line-brand-strong`, `--line-input`, `--r-md`, `--r-sm`, `--recess-fill`, `--rgb-white`, `--shadow-hairline-card`, `--shadow-recess`, `--surface-solid`, `--text-small`, `--wash-active`, `--wash-hover`.

## Accessibility

- single renders role="radiogroup" with role="radio" items and aria-checked; multiple renders role="group" with aria-pressed buttons.
- Roving tabindex: one tab stop, arrows move (Up and Down when vertical), Home and End jump to the ends.
- aria-label on the group is required; icon-only items each need their own aria-label.

## Do

- Use multiple for independent options (bold, italic).
- Keep items to one short word or a familiar icon.

## Don't

- Don't use single where a value is always required; use SegmentedControl.

Related: https://rime.mjsons.net/components/toggle, https://rime.mjsons.net/components/tabs, https://rime.mjsons.net/components/button-group

---

# Calendar

> The month grid on its own: a single date or a range, one or two months, with month and year pickers.

Category: Forms. Docs page: https://rime.mjsons.net/components/calendar

## Installation

```bash
npx shadcn@latest add KezLahd/rime/date-field
```

Calendar is the grid DateField and DateRangeFilter open in their popovers, usable on its own when a date picker should stay on the page (a booking panel, a report range). It takes a single value with onChange, or a range with onRangeChange, where the first pick starts the range, the second ends it and hovering previews it.

min, max and isDateDisabled bound what can be picked; disabled days stay focusable so keyboard users can pass over them. numberOfMonths={2} shows two months side by side; captionLayout="dropdown" adds Month and Year pickers for dates years away. Dates are ISO strings (2026-10-14), never Date objects, so time zones never shift a day.

## Usage

```tsx
import { Calendar, type DateRange, type IsoDate } from "@/components/ui";

<Calendar value={date} onChange={setDate} />
```

## Props: Calendar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isDateDisabled` | `(date: IsoDate) => boolean` |  | Days that cannot be picked. Still focusable, so keyboard users can pass over them. |
| `min` | `IsoDate` |  |  |
| `max` | `IsoDate` |  |  |
| `defaultMonth` | `IsoDate` |  | Month shown first when there is no value. Defaults to today's month. |
| `autoFocus` | `boolean` |  | Moves focus into the grid on mount (used by DateField's popup). |
| `numberOfMonths` | `1 \| 2 \| 1 \| 2` | `1` | Months side by side. Navigation moves them together. |
| `captionLayout` | `"label" \| "dropdown" \| "label" \| "dropdown"` | `"label"` | label: the month and year as a heading, with month and year arrows. dropdown: Month ▾ and Year ▾ buttons that open quick pickers, for dates years away such as a date of birth (a sign-up form). Month arrows stay. Two-month calendars always use labels. |
| `fromYear` | `number` |  | First and last years the Year picker lists (dropdown only). Default to min's and max's years, else 100 years back and 10 on. They also bound the arrows and keyboard paging, so the grid never shows a year the picker lacks. |
| `toYear` | `number` |  |  |
| `className` | `string` |  |  |
| `value` (required) | `IsoDate \| null \| never` |  |  |
| `onChange` (required) | `(value: IsoDate) => void \| never` |  |  |
| `range` | `never \| DateRange` |  | Range mode. After a start is picked, hovering or arrowing previews the range. |
| `onRangeChange` | `never \| (range: DateRange) => void` |  |  |

## Examples

### Single date

```tsx
<Calendar value={date} onChange={setDate} />
```

### Range, two months

```tsx
<Calendar range={range} onRangeChange={setRange} numberOfMonths={2} />
```

### Month and year pickers

```tsx
<Calendar value={date} onChange={setDate} captionLayout="dropdown" fromYear={1940} toYear={2026} />
```

## Theme tokens

System tokens it reads: `--brand`, `--brand-gradient`, `--dur`, `--dur-fast`, `--ease`, `--focus-ring`, `--font-body`, `--glow-sm`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-heading`, `--ink-inverse`, `--ink-muted`, `--line`, `--line-brand`, `--line-brand-strong`, `--r-xs`, `--rgb-brand-deep`, `--text-micro`, `--wash-active`, `--wash-hover`, `--wash-strong`, `--wash-subtle`.

## Accessibility

- The days are a grid: arrows move by day and week, PageUp and PageDown by month (Shift for a year), Home and End to the week's ends, Enter or Space picks.
- Each day is named by its full date, and the picked day carries aria-selected, so the choice is never shown by colour alone.

## Do

- Use DateField when people may know the date and want to type it.
- Bound the grid with min and max.

## Don't

- Don't force a calendar for a date of birth; let people type it.

Related: https://rime.mjsons.net/components/date-field, https://rime.mjsons.net/components/date-range-filter

---

# TimeField and TimeRangeField

> A time of day with typed input and a popup picker; the range variant pairs start and end on one row.

Category: Forms. Docs page: https://rime.mjsons.net/components/time-field

## Installation

```bash
npx shadcn@latest add KezLahd/rime/time-field
```

TimeField lets people type a time the way they say it ("3pm", "0930", "14:30") and offers a popup picker as a second path: scrollable hour, minute and AM/PM columns that auto-center on the current value. The value is "HH:MM" 24h regardless of display format, so it sorts, compares and serialises predictably.

format="12h" shows "9:30 AM" and parses am/pm; the default is 24h. step sets the minute granularity for the popup list (default 15; set to 1 for a free picker). min and max bound both the parse and the picker — a chosen time outside the bounds is kept on screen with a reason, not silently wiped. TimeRangeField pairs two TimeFields with an en dash between them and flags end at or before start as invalid so the row disagrees with itself until the parent fixes it.

## Usage

```tsx
import { TimeField, TimeRangeField, type Time, type TimeRange } from "@/components/ui";

<TimeField value={at} onChange={setAt} />
```

## Props: TimeField

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `Time \| null` |  |  |
| `onChange` (required) | `(value: Time \| null) => void` |  | null when cleared or when the typed text can't be read as a time. |
| `format` | `"12h" \| "24h"` | `"24h"` | 24h is the default. 12h shows "9:30 AM" and parses am/pm. |
| `step` | `number` | `15` | Minute granularity for the popup list (default 15). Set to 1 for a free picker. |
| `min` | `Time` |  |  |
| `max` | `Time` |  |  |
| `invalid` | `boolean` |  |  |
| `disabled` | `boolean` |  |  |
| `required` | `boolean` |  |  |
| `id` | `string` |  |  |
| `name` | `string` |  |  |
| `placeholder` | `string` |  |  |
| `aria-label` | `string` |  |  |
| `className` | `string` |  |  |
| `inline` | `boolean` | `false` | Keep the popup rendered open under the field (for docs). |

## Props: TimeRangeField

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `TimeRange` |  |  |
| `onChange` (required) | `(value: TimeRange) => void` |  |  |
| `format` | `"12h" \| "24h"` | `"24h"` |  |
| `step` | `number` | `15` |  |
| `requireEndAfterStart` | `boolean` | `true` | When true, flag an end at or before start as invalid. Default true. |
| `min` | `Time` |  |  |
| `max` | `Time` |  |  |
| `disabled` | `boolean` |  |  |
| `className` | `string` |  |  |
| `aria-label-start` | `string` |  |  |
| `aria-label-end` | `string` |  |  |

## Examples

### Open

inline shows the picker open under the field, in place.

```tsx
<TimeField inline aria-label="Opens at" value={at} onChange={setAt} format="12h" step={15} />
```

### Single time and range

```tsx
<TimeField value={at} onChange={setAt} format="12h" step={15} />
<TimeRangeField value={range} onChange={setRange} format="12h" step={30} />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--field-focus-border` | `rgba(var(--rgb-brand), 0.7)` / `var(--focus-color)` |
| `--field-focus-ring` | `var(--focus-halo)` |

System tokens it reads: `--danger-ink`, `--dur`, `--ease`, `--ease-out`, `--focus-color`, `--focus-halo`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-heading`, `--ink-muted`, `--line`, `--r-lg`, `--r-sm`, `--r-xs`, `--rgb-brand`, `--shadow-float`, `--surface-solid`, `--surface-sunken`, `--text-small`, `--wash-active`, `--wash-hover`, `--wash-subtle`, `--z-popover`.

## Accessibility

- The field accepts spoken-style input ("3pm", "9:30 am") and reports a reason when the text can't be read as a time, named by aria-describedby.
- The popup is a role="dialog" with hour, minute and (12h only) AM/PM listboxes; arrow keys move focus between cells and Enter picks.
- Alt+Down from the field opens the popup. Escape closes it and returns focus to the toggle, so a Modal containing the field doesn't close with it.

## Do

- Use step={15} or step={30} for scheduling flows; most times a human picks are on the quarter or half hour.
- Pass min and max for opening hours or an event window so the picker only lists times that work.

## Don't

- Don't use a free-text input for a time; the picker catches typos and ambiguous formats cheaply.

Related: https://rime.mjsons.net/components/date-field, https://rime.mjsons.net/components/date-range-filter, https://rime.mjsons.net/components/date-time-field

---

# DateTimeField and DateTimeRangeField

> A date and a time of day on one row, each with its own popup; the range variant pairs a start and end.

Category: Forms. Docs page: https://rime.mjsons.net/components/date-time-field

## Installation

```bash
npx shadcn@latest add KezLahd/rime/date-time-field
```

DateTimeField composes DateField and TimeField into one control. The parts join as "YYYY-MM-DDTHH:MM" (local, no time zone) — pair with a stored zone when the moment matters across zones; keep it naive when the user types the time in their own time ("show starts 7 pm on Saturday" is the same string whether they're in Sydney or Perth).

min and max are also DateTime strings, so a bound on "2026-10-14T17:00" rules out both a later date and a later time on that same date. The TimeField's own bound widens on dates strictly inside the range and only narrows on the bound dates themselves.

DateTimeRangeField pairs two DateTimeFields with an arrow between them. The start caps the end's min (and vice-versa), so an impossible pick is simply not offered — and if the parent passes an inverted pair, the end sub-group gets a soft danger wash so the row disagrees with itself until it's fixed.

## Usage

```tsx
import { DateTimeField, DateTimeRangeField, type DateTime, type DateTimeRange } from "@/components/ui";

<DateTimeField value={at} onChange={setAt} format="12h" step={15} />
```

## Props: DateTimeField

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `DateTime \| null` |  |  |
| `onChange` (required) | `(value: DateTime \| null) => void` |  |  |
| `format` | `"12h" \| "24h"` | `"24h"` | 24h is the default. 12h shows "9:30 AM" and parses am/pm. |
| `step` | `number` | `15` | Minute granularity for the time popup (default 15). |
| `min` | `DateTime` |  |  |
| `max` | `DateTime` |  |  |
| `disabled` | `boolean` |  |  |
| `className` | `string` |  |  |
| `aria-label-date` | `string` |  | aria-label for the date field (default "Date"). |
| `aria-label-time` | `string` |  | aria-label for the time field (default "Time"). |

## Props: DateTimeRangeField

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `DateTimeRange` |  |  |
| `onChange` (required) | `(value: DateTimeRange) => void` |  |  |
| `format` | `"12h" \| "24h"` | `"24h"` |  |
| `step` | `number` | `15` |  |
| `disabled` | `boolean` |  |  |
| `className` | `string` |  |  |

## Examples

### Date-time and range

```tsx
<DateTimeField value={at} onChange={setAt} format="12h" step={15} />
<DateTimeRangeField value={range} onChange={setRange} format="12h" step={30} />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--wash-danger-subtle` | `rgba(var(--rgb-danger), 0.06)` |

System tokens it reads: `--ink-muted`, `--r-md`, `--rgb-danger`.

## Accessibility

- Each piece keeps its own field semantics: the DateField accepts DD/MM/YYYY typing, the TimeField accepts spoken-style times, and both expose their own aria-describedby reason when parsing fails.
- The TimeField is disabled until a date is set — a time without a day is ambiguous — so keyboard users aren't trapped typing a time that can't be stored.

## Do

- Use this when both pieces matter and the user types them in their own time (events, bookings, deadlines).
- Pass min and max as full DateTime strings so the TimeField narrows automatically on the boundary dates.

## Don't

- Don't use it for a cross-zone instant; store the time zone alongside the value, or pass a UTC string your layer above knows to translate.

Related: https://rime.mjsons.net/components/date-field, https://rime.mjsons.net/components/time-field, https://rime.mjsons.net/components/date-range-filter

---

# Table

> The one table look: neutral header row, whole-cell sortable headers, skeleton, empty and error states, and Pagination.

Category: Data display. Docs page: https://rime.mjsons.net/components/table

## Installation

```bash
npx shadcn@latest add KezLahd/rime/table
```

Table is presentational: you own the rows, the sort state and the page, and it draws them. Columns declare a header, a cell renderer, alignment, width, a monospace flag for references, a skeleton width for loading, and hideBelow to drop a column on narrow screens.

A sortable header is the whole cell, edge to edge: the button fills the th, so hover, press and focus light the full cell over the neutral sweep, never a pill inside it. The sort chevron always holds its slot, so labels never shift when sorting.

Every state is built in: loading draws skeleton rows matching the columns; empty renders whatever you pass (an EmptyState compact that says what to do next); error replaces the body (an Alert with a retry). Pagination sits centred under the table with a summary line.

Two appearances: glass (rows fall through to the frosted panel, the default inside a GlassPanel) and white (an inset solid table for dense lists). Both share one header look, set by --table-* tokens.

## Usage

```tsx
import { Pagination, Table, type Column, type SortState } from "@/components/ui";

const columns: Column<Invoice>[] = [
  { key: "ref", header: "Invoice", cell: (i) => i.reference, mono: true },
  { key: "customer", header: "Customer", sortable: true, cell: (i) => i.customer },
];

<Table caption="Invoices" columns={columns} rows={rows} rowKey={(i) => i.id} sort={sort} onSortChange={setSort} />
<Pagination page={page} pageCount={pageCount} onPageChange={setPage} totalItems={total} pageSize={20} itemLabel="invoices" />
```

## Props: Table

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` (required) | `ReadonlyArray<Column<T>>` |  |  |
| `rows` (required) | `ReadonlyArray<T>` |  |  |
| `rowKey` (required) | `(row: T) => string` |  |  |
| `caption` (required) | `string` |  | Screen-reader caption. Required: a table needs a name. |
| `sort` | `SortState` | `null` |  |
| `onSortChange` | `(sort: SortState) => void` |  | Header click: asc first, then toggles. Sort the rows yourself. |
| `loading` | `boolean` |  |  |
| `skeletonRows` | `number` | `5` |  |
| `empty` | `ReactNode` |  | Shown when not loading and rows is empty. Pass an <EmptyState compact />. |
| `error` | `ReactNode` |  | Replaces the body when the load failed. Pass an <Alert> with a retry. |
| `appearance` | `"glass" \| "white"` | `"glass"` | glass = rows fall through to the frosted panel (no wrapper background). white = the reference white inset table, for dense lists. |
| `isRowHighlighted` | `(row: T) => boolean` |  | Marks a row, e.g. the one just edited. |
| `className` | `string` |  |  |

## Props: Pagination

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `page` (required) | `number` |  |  |
| `pageCount` (required) | `number` |  |  |
| `onPageChange` (required) | `(page: number) => void` |  |  |
| `totalItems` | `number` |  |  |
| `pageSize` | `number` |  |  |
| `itemLabel` | `string` | `"results"` | Plural noun for the summary: "customers", "requests". |
| `className` | `string` |  |  |

## Examples

### Sortable, with pagination

```tsx
<Table caption="Invoices" columns={columns} rows={pageRows} rowKey={(i) => i.id} sort={sort} onSortChange={setSort} />
<Pagination page={page} pageCount={3} onPageChange={setPage} totalItems={11} pageSize={4} itemLabel="invoices" />
```

### Loading, empty and error

Switch the state to see each. Empty tells the user what to do next.

```tsx
<Table … loading />
<Table … rows={[]} empty={<EmptyState compact tone="filtered" title="No invoices match" description="Clear a filter to see more." />} />
<Table … error={<Alert tone="danger" title="Couldn't load invoices" action={<Button size="sm" variant="secondary" onClick={retry}>Try again</Button>} />} />
```

### White appearance

```tsx
<Table appearance="white" caption="Invoices" columns={columns} rows={rows} rowKey={(r) => r.id} />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--button-primary-bg` | `var(--brand-gradient)` |
| `--button-radius` | `var(--r-sm)` |
| `--inner-radius` | `var(--r-lg)` |
| `--r-flat` | `var(--table-radius, var(--r-md))` / `var(--table-radius, var(--inner-radius, var(--r-lg)))` |
| `--table-radius` | `var(--r-md)` / `var(--inner-radius, var(--r-lg))` |
| `--table-row-height` | `46px` |

System tokens it reads: `--brand-deep`, `--brand-gradient`, `--control-h-sm`, `--dur`, `--ease`, `--focus-color`, `--focus-ring`, `--font-mono`, `--glass-fill-nested`, `--glow-sm`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-inverse`, `--ink-muted`, `--line-glass`, `--line-soft`, `--r-lg`, `--r-md`, `--r-sm`, `--rgb-contact`, `--surface-solid`, `--table-cell-pad`, `--table-head-fill`, `--table-head-hover`, `--table-head-ink`, `--table-head-pad`, `--table-head-press`, `--table-head-rule`, `--table-row-hover`, `--table-row-line`, `--text-caption`, `--text-small`, `--wash-subtle`.

## Accessibility

- caption is required and rendered as a visually hidden <caption>: a table needs a name.
- Sortable headers are buttons inside the th with aria-sort on the th; the first press sorts ascending, then toggles.
- Rows are not clickable. Put a link (or a ghost Button with href) in the identifying cell, so keyboard and screen-reader users reach it.
- Pagination is a nav labelled "Pagination", the current page is aria-current="page", and prev/next disable at the ends.

## Do

- Put the table, its FilterBar and its Pagination in one GlassPanel: that is the list page pattern.
- Right-align numbers and actions (align="right").
- Give every empty state a next step.

## Don't

- Never invent another table look; theme --table-* tokens instead.
- Don't uppercase column headers; sentence case only.
- Don't put a title or an "n of m shown" line above the table.

Related: https://rime.mjsons.net/components/filter-bar, https://rime.mjsons.net/components/empty-state, https://rime.mjsons.net/components/glass-panel

---

# StatusPill, Badge and CountBadge

> Status pills (tinted fill, tinted edge, deep ink), small uppercase tags, and count badges.

Category: Data display. Docs page: https://rime.mjsons.net/components/status-pill

## Installation

```bash
npx shadcn@latest add KezLahd/rime/badge
```

StatusPill names a record's state in a list or header. Badge is a small uppercase tag (soft or solid) for categories and flags. CountBadge is a number of things waiting, capped at max (99+).

Tones: neutral, info, success, warning, danger and deep (the brand). Every tone's ink clears 4.5:1 on its own fill over worst-case glass.

## Usage

```tsx
import { Badge, CountBadge, StatusPill } from "@/components/ui";

<StatusPill tone="success">Paid</StatusPill>
```

## Props: StatusPill

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` (required) | `Tone` |  |  |
| `children` (required) | `ReactNode` |  |  |
| `dot` | `boolean` |  | Leading dot in the tone colour, for dense tables where the pill needs a second cue. |
| `size` | `"sm" \| "md"` | `"md"` |  |
| `className` | `string` |  |  |
| `asChild` | `boolean` |  | Render the single child element (a link) with the pill's look. |

## Props: Badge

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `Tone` | `"neutral"` |  |
| `variant` | `"soft" \| "solid" \| "default" \| "secondary" \| "destructive" \| "outline"` | `"soft"` | soft = tinted tag. solid = white text on the tone (counts needing attention). shadcn's names are accepted too: default (solid brand), secondary (soft neutral), destructive (solid danger), outline (a hairline tag with no fill). |
| `children` (required) | `ReactNode` |  |  |
| `className` | `string` |  |  |
| `asChild` | `boolean` |  | Render the single child element (a link) with the badge's look. |

## Props: CountBadge

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` (required) | `number` |  |  |
| `tone` | `"brand" \| "danger" \| "warning" \| "neutral"` | `"brand"` |  |
| `label` | `string` |  | Accessible text, e.g. "3 pending requests". The number alone is ambiguous. |
| `max` | `number` | `99` |  |
| `className` | `string` |  |  |

## Examples

### Tones

```tsx
<StatusPill tone="neutral">Draft</StatusPill>
<StatusPill tone="info">Sent</StatusPill>
<StatusPill tone="warning" dot>Overdue</StatusPill>
<StatusPill tone="success">Paid</StatusPill>
<StatusPill tone="danger">Void</StatusPill>
<Badge tone="brand" variant="solid">New</Badge>
<CountBadge count={4} label="4 waiting" />
```

### shadcn badge variants

Badge accepts shadcn's variant names: default (solid accent), secondary (soft neutral), destructive (solid danger) and outline (a hairline, no fill). asChild renders a link with the badge's look.

```tsx
<Badge variant="default">New</Badge>
<Badge variant="secondary">Draft</Badge>
<Badge variant="destructive">Overdue</Badge>
<Badge variant="outline">Beta</Badge>
<Badge variant="outline" asChild><a href="#changelog">Changelog</a></Badge>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--pill-font-size` | `12px` |
| `--pill-pad-x` | `calc(10px * var(--density))` |
| `--pill-radius` | `var(--r-full)` |
| `--r-circle` | `50%` |
| `--tag-brand-bg` | `var(--brand-gradient)` |
| `--tag-radius` | `var(--r-2xs)` |

System tokens it reads: `--border-w`, `--brand-fill`, `--brand-gradient`, `--brand-ink`, `--brand-line`, `--danger-fill`, `--danger-ink`, `--danger-line`, `--density`, `--info-fill`, `--info-ink`, `--info-line`, `--ink-brand`, `--ink-inverse`, `--ink-secondary`, `--neutral-fill`, `--neutral-ink`, `--neutral-line`, `--r-2xs`, `--r-full`, `--success-fill`, `--success-ink`, `--success-line`, `--success-solid`, `--warning-fill`, `--warning-ink`, `--warning-line`, `--warning-solid`, `--wash-strong`.

## Accessibility

- Colour is never the only signal: the label always says the state.
- CountBadge takes a label for screen readers ("4 waiting").

## Do

- Map each status to one tone in one place and reuse it.

## Don't

- Don't make a pill clickable; it is a label.

---

# Avatar

> Initials on the brand gradient or a neutral disc, in three sizes.

Category: Data display. Docs page: https://rime.mjsons.net/components/avatar

## Installation

```bash
npx shadcn@latest add KezLahd/rime/avatar
```

Avatar shows initials, from name or given, on the brand gradient (the signed-in person) or a neutral disc (a record).

## Usage

```tsx
import { Avatar } from "@/components/ui";

<Avatar name="Jane Cooper" />
```

## Props: Avatar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  | Full name; initials are derived (titles like "Dr" are skipped). |
| `initials` | `string` |  | Explicit initials, e.g. a customer's "R.T." (dots are dropped). |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` |  |
| `tone` | `"brand" \| "neutral"` | `"brand"` | brand = the gradient (the signed-in user). neutral = a record (a customer). |
| `label` | `string` |  | Decorative when a name sits next to it (the default). |
| `className` | `string` |  |  |

## Examples

### Sizes and tones

```tsx
<Avatar name="Jane Cooper" size="sm" />
<Avatar name="Wade Warren" />
<Avatar name="Esther Howard" size="lg" tone="neutral" />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--r-circle` | `50%` |

System tokens it reads: `--brand-deep`, `--brand-fill`, `--brand-gradient`, `--brand-line`, `--ink-inverse`, `--rgb-brand`, `--shadow-specular-dark`.

## Accessibility

- Decorative by default; pass label when it is the only name on screen.

## Do

- Pair it with the person's name in text.

## Don't

- Don't use it as a button on its own.

---

# Meter and ProgressBar

> A segmented meter for small counts (seats used) and a bar for progress through a total.

Category: Data display. Docs page: https://rime.mjsons.net/components/meter

## Installation

```bash
npx shadcn@latest add KezLahd/rime/meter
```

Meter draws one segment per unit up to max (default 5). ProgressBar is a continuous bar for larger totals. Both announce value text.

## Usage

```tsx
import { Meter, ProgressBar } from "@/components/ui";

<Meter label="Seats" value={3} max={5} valueText="3 of 5 used" />
```

## Props: Meter

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` |  |  |
| `max` | `number` | `5` | Discrete slots. The team member cap is 5. |
| `label` (required) | `string` |  | Visible caption and the basis of the accessible name, e.g. "Slots in use". |
| `valueText` | `string` |  | Spoken value; defaults to "3 of 5". |
| `note` | `ReactNode` |  | Line under the segments, e.g. "At capacity: withdraw a customer to free a slot". |
| `size` | `"sm" \| "md"` | `"md"` | md = dashboard header block. sm = inline in a table cell. |
| `className` | `string` |  |  |

## Props: ProgressBar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` |  |  |
| `max` (required) | `number` |  |  |
| `label` (required) | `string` |  |  |
| `valueText` | `string` |  |  |
| `className` | `string` |  |  |

## Examples

### Default

```tsx
<Meter label="Seats" value={3} max={5} />
<ProgressBar label="Quarterly target" value={240} max={400} />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--r-flat` | `3px` / `2px` |

System tokens it reads: `--brand-deep`, `--brand-gradient`, `--brand-soft`, `--danger-base`, `--danger-base-solid`, `--danger-ink`, `--dur-slow`, `--ease`, `--ink-heading`, `--ink-muted`, `--ink-secondary`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-contact`, `--rgb-danger`, `--shadow-specular-dark`, `--text-caption`, `--text-micro`, `--tracking-eyebrow`.

## Accessibility

- role="meter" / role="progressbar" with aria-valuenow, -min, -max and aria-valuetext.

## Do

- Write valueText in words people use: "3 of 5 seats used".

## Don't

- Don't use a meter for a task that is in progress over time; that is a Spinner or a toast.

---

# ProgressSteps

> A horizontal track of steps with detail and meta lines, or a compact dot track for table cells.

Category: Data display. Docs page: https://rime.mjsons.net/components/progress-steps

## Installation

```bash
npx shadcn@latest add KezLahd/rime/progress-steps
```

ProgressSteps shows where something is in a fixed sequence (a shipment: packed, shipped, delivered). compact fits a table cell.

## Usage

```tsx
import { ProgressSteps } from "@/components/ui";

<ProgressSteps aria-label="Shipment" steps={[{ label: "Packed", state: "done" }, { label: "Shipped", state: "current" }]} />
```

## Props: ProgressSteps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` (required) | `ReadonlyArray<ProgressStep>` |  |  |
| `aria-label` | `string` |  |  |
| `compact` | `boolean` |  | compact = segments plus a one-line caption, for customer cards. |
| `caption` | `ReactNode` |  | Compact caption, e.g. "Delivery 2 of 3 dispatched". Required in compact mode for meaning. |
| `className` | `string` |  |  |

## Examples

### Full and compact

```tsx
<ProgressSteps steps={steps} aria-label="Shipment" />
<ProgressSteps compact steps={steps} aria-label="Shipment" />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--r-flat` | `3px` |

System tokens it reads: `--brand-gradient`, `--danger-base`, `--danger-ink`, `--ink-brand`, `--ink-muted`, `--ink-secondary`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-contact`, `--rgb-danger`, `--text-caption`, `--text-micro`.

## Accessibility

- An ordered list; each step's state is in its accessible text, not colour alone.

## Do

- Keep labels to one or two words.

## Don't

- Don't make it interactive; that is Stepper.

---

# Kbd and KbdGroup

> Keyboard keys as small raised key caps, alone or as a combination.

Category: Data display. Docs page: https://rime.mjsons.net/components/kbd

## Installation

```bash
npx shadcn@latest add KezLahd/rime/kbd
```

Kbd renders one key as a real <kbd>: a light fill, a hairline edge and a darker bottom lip so it reads as a key, not a badge. KbdGroup renders a chord (Ctrl + K) as a <kbd> wrapping one <kbd> per key, which is how HTML marks up a combination.

Use them in help text, menus, tooltips and command palettes. size="sm" fits inside a menu row or running text.

## Usage

```tsx
import { Kbd, KbdGroup } from "@/components/ui";

<KbdGroup keys={["Ctrl", "K"]} />
```

## Props: Kbd

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "md"` | `"md"` | sm sits inside menus and tooltips; md in running text. |

Also accepts the native attributes of: AriaAttributes, DOMAttributes, HTMLAttributes.

## Props: KbdGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `keys` (required) | `ReadonlyArray<string>` |  | The keys pressed together, in order: ["Ctrl", "K"]. |
| `separator` | `ReactNode` | `"+"` | Between the keys. Defaults to a muted "+". |
| `size` | `"sm" \| "md"` | `"md"` |  |
| `className` | `string` |  |  |

## Examples

### Keys and combinations

```tsx
<KbdGroup keys={["Ctrl", "K"]} />
<KbdGroup keys={["Shift", "Alt", "N"]} />
<Kbd>Esc</Kbd>
<p>Press <KbdGroup keys={["Ctrl", "S"]} size="sm" /> to save the invoice.</p>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--kbd-bg` | `rgba(var(--rgb-white), 0.8)` |
| `--kbd-ink` | `var(--ink-secondary)` |
| `--kbd-radius` | `var(--r-2xs)` |

System tokens it reads: `--border-w`, `--font-body`, `--ink-muted`, `--ink-secondary`, `--line`, `--r-2xs`, `--rgb-brand-deep`, `--rgb-contact`, `--rgb-white`, `--text-caption`, `--text-micro`.

## Accessibility

- Real <kbd> elements, so the keys are read as text; the separator is hidden from assistive tech.

## Do

- Name keys as they are printed: Ctrl, Shift, Enter, Esc.

## Don't

- Don't use Kbd for anything that is not a key; that is a Badge.

Related: https://rime.mjsons.net/components/tooltip, https://rime.mjsons.net/components/command

---

# Chart

> Themed charts on Recharts: line, area, bar and donut in one frame with a table view, plus sparklines and a stat strip.

Category: Data display. Docs page: https://rime.mjsons.net/components/chart

## Installation

```bash
npx shadcn@latest add KezLahd/rime/charts
```

The chart layer lives in components/charts. Every chart mounts in ChartFrame: a caption, a legend, the plot and a Chart or Table toggle whose table is the same data for anyone who cannot read the picture. Loading, refreshing, empty and error states are built in (status).

Charts carry no hex. Every mark reads a custom property (--chart-1 to --chart-6, --chart-seq-*, --chart-good and friends) declared in tokens.css, and chart chrome (grid, axes, ticks) derives from the global tokens, so a preset, dark mode or a Rime Studio theme re-themes them with no client code. Tooltips glide between points (TOOLTIP_MOTION: Recharts' 400ms ease, off under reduced motion) and use the compact shadcn layout on the popover glass, with dot, line or dashed indicators.

The high-level charts take series (Rime's list) or config (a shadcn ChartConfig), and expose --color-<key> per series on the root. For anything custom, the shadcn-compatible primitives are here too: ChartContainer, ChartTooltip, ChartTooltipContent, ChartLegend, ChartLegendContent and type ChartConfig. A shadcn chart example works with its Tailwind classes removed and ChartContainer given a height. The full gallery, with every tooltip variant, is at /charts.

Series take their colour in a fixed order (the colour-blind safety mechanism): never re-rank on filter, and past six series fold the rest into "Other" (foldSeries). summary is required: one or two sentences a screen reader hears in place of the plot.

StatStrip is the summary-card pattern for figures: one surface, hairline cells, each with a value, a delta in words and an optional Sparkline.

## Usage

```tsx
import { AreaChart, BarChart, ChartContainer, ChartTooltip, ChartTooltipContent, DonutChart, LineChart, Sparkline, StatStrip, type ChartConfig } from "@/components/charts";

<LineChart
  title="Orders per month"
  summary="Online orders rose from 182 in January to 344 in August."
  data={rows}
  x="month"
  series={[{ key: "online", label: "Online" }]}
/>
```

## Props: TrendChart

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `ReactNode` |  |  |
| `subtitle` | `ReactNode` |  |  |
| `summary` (required) | `string` |  | One or two sentences a screen reader hears in place of the picture: what is plotted and the headline ("Weekly orders rose from 8 to 32"). Also set as the SVG's <desc>. |
| `hideTitle` | `boolean` |  | Keeps the title for assistive tech but hides it, when a Group heading already says it. |
| `status` | `ChartStatus` |  |  |
| `emptyTitle` | `ReactNode` |  |  |
| `emptyDescription` | `ReactNode` |  | What to do next, or what will fill this. A bare "No data" is not an empty state. |
| `emptyAction` | `ReactNode` |  |  |
| `errorTitle` | `ReactNode` |  |  |
| `errorDescription` | `ReactNode` |  |  |
| `onRetry` | `() => void` |  |  |
| `actions` | `ReactNode` |  | Controls placed beside the table toggle (a segmented control, a menu). |
| `height` | `number` | `248` | Plot height in px, x-axis band included. |
| `className` | `string` |  |  |
| `data` (required) | `ReadonlyArray<ChartRow>` |  |  |
| `x` (required) | `string` |  | Field holding the x value (an ISO date for time series). |
| `formatX` | `(value: string) => string` | `String` | Axis tick: short ("23 Nov"). |
| `formatXLong` | `(value: string) => string` |  | Tooltip header and table rows: in full ("Week of 23 Nov 2026"). |
| `formatValue` | `(value: number) => string` | `formatNumber` |  |
| `xLabel` | `string` | `"Week"` | Table header for the x column. |
| `endLabels` | `boolean` | `true` | Value and name at each line's end. On by default for up to four series; switched off automatically where the ends would collide. |
| `reference` | `{ value: number; label: string }` |  | One horizontal limit on the same axis (program places). Never a second axis. |
| `tooltipTag` | `string` |  | Tooltip header tag, e.g. "Cumulative". |
| `series` (required) | `ReadonlyArray<ChartSeries> \| never` |  |  |
| `config` | `never \| ChartConfig` |  |  |

## Props: AreaChart

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `ReactNode` |  |  |
| `subtitle` | `ReactNode` |  |  |
| `summary` (required) | `string` |  | One or two sentences a screen reader hears in place of the picture: what is plotted and the headline ("Weekly orders rose from 8 to 32"). Also set as the SVG's <desc>. |
| `hideTitle` | `boolean` |  | Keeps the title for assistive tech but hides it, when a Group heading already says it. |
| `status` | `ChartStatus` |  |  |
| `emptyTitle` | `ReactNode` |  |  |
| `emptyDescription` | `ReactNode` |  | What to do next, or what will fill this. A bare "No data" is not an empty state. |
| `emptyAction` | `ReactNode` |  |  |
| `errorTitle` | `ReactNode` |  |  |
| `errorDescription` | `ReactNode` |  |  |
| `onRetry` | `() => void` |  |  |
| `actions` | `ReactNode` |  | Controls placed beside the table toggle (a segmented control, a menu). |
| `height` | `number` |  | Plot height in px, x-axis band included. |
| `className` | `string` |  |  |
| `data` (required) | `ReadonlyArray<ChartRow>` |  |  |
| `x` (required) | `string` |  | Field holding the x value (an ISO date for time series). |
| `formatX` | `(value: string) => string` |  | Axis tick: short ("23 Nov"). |
| `formatXLong` | `(value: string) => string` |  | Tooltip header and table rows: in full ("Week of 23 Nov 2026"). |
| `formatValue` | `(value: number) => string` |  |  |
| `xLabel` | `string` |  | Table header for the x column. |
| `endLabels` | `boolean` |  | Value and name at each line's end. On by default for up to four series; switched off automatically where the ends would collide. |
| `reference` | `{ value: number; label: string }` |  | One horizontal limit on the same axis (program places). Never a second axis. |
| `tooltipTag` | `string` |  | Tooltip header tag, e.g. "Cumulative". |
| `series` (required) | `ReadonlyArray<ChartSeries> \| never` |  |  |
| `config` | `never \| ChartConfig` |  |  |
| `stacked` | `boolean` |  | Parts of a whole over time. Off for a single running total. |

## Props: BarChart

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `ReactNode` |  |  |
| `subtitle` | `ReactNode` |  |  |
| `summary` (required) | `string` |  | One or two sentences a screen reader hears in place of the picture: what is plotted and the headline ("Weekly orders rose from 8 to 32"). Also set as the SVG's <desc>. |
| `hideTitle` | `boolean` |  | Keeps the title for assistive tech but hides it, when a Group heading already says it. |
| `status` | `ChartStatus` |  |  |
| `emptyTitle` | `ReactNode` |  |  |
| `emptyDescription` | `ReactNode` |  | What to do next, or what will fill this. A bare "No data" is not an empty state. |
| `emptyAction` | `ReactNode` |  |  |
| `errorTitle` | `ReactNode` |  |  |
| `errorDescription` | `ReactNode` |  |  |
| `onRetry` | `() => void` |  |  |
| `actions` | `ReactNode` |  | Controls placed beside the table toggle (a segmented control, a menu). |
| `height` | `number` |  | Plot height in px, x-axis band included. |
| `className` | `string` |  |  |
| `data` (required) | `ReadonlyArray<ChartRow>` |  |  |
| `category` (required) | `string` |  | Field holding the category (region, team member, week, stage). |
| `orientation` | `"columns" \| "bars" \| "columns" \| "bars"` | `"columns"` | columns = vertical bars, for time and short labels. bars = horizontal, for many or long-named categories (regions, team members). |
| `stacked` | `boolean` | `false` | Parts of a whole per category. |
| `categoryColors` | `ReadonlyArray<string>` |  | One colour per category, for ordered categories on a single series (a funnel's stages, from ordinalColors). Nominal categories never get this: one series is one colour. |
| `formatCategory` | `(value: string) => string` | `String` |  |
| `formatCategoryLong` | `(value: string) => string` |  |  |
| `formatValue` | `(value: number) => string` | `formatNumber` |  |
| `categoryLabel` | `string` | `"Category"` |  |
| `valueLabels` | `boolean` |  | Value at each bar's end. Default: on for a single unstacked series. |
| `max` | `number` |  | Fixed value-axis top, e.g. 5 for places per team member. |
| `categoryWidth` | `number` | `150` | Width reserved for horizontal-bar category labels. |
| `tooltipTag` | `string` |  |  |
| `series` (required) | `ReadonlyArray<ChartSeries> \| never` |  |  |
| `config` | `never \| ChartConfig` |  |  |

## Props: DonutChart

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `summary` (required) | `string` |  | One or two sentences a screen reader hears in place of the picture: what is plotted and the headline ("Weekly orders rose from 8 to 32"). Also set as the SVG's <desc>. |
| `title` (required) | `ReactNode` |  |  |
| `className` | `string` |  |  |
| `subtitle` | `ReactNode` |  |  |
| `hideTitle` | `boolean` |  | Keeps the title for assistive tech but hides it, when a Group heading already says it. |
| `status` | `ChartStatus` |  |  |
| `emptyTitle` | `ReactNode` |  |  |
| `emptyDescription` | `ReactNode` |  | What to do next, or what will fill this. A bare "No data" is not an empty state. |
| `emptyAction` | `ReactNode` |  |  |
| `errorTitle` | `ReactNode` |  |  |
| `errorDescription` | `ReactNode` |  |  |
| `onRetry` | `() => void` |  |  |
| `actions` | `ReactNode` |  | Controls placed beside the table toggle (a segmented control, a menu). |
| `data` (required) | `ReadonlyArray<DonutDatum>` |  |  |
| `centreLabel` (required) | `string` |  | Centre figure label, e.g. "Customers". The figure is the total. |
| `centreValue` | `string` |  | Override the centre figure (defaults to the sum). |
| `formatValue` | `(value: number) => string` | `formatNumber` |  |
| `size` | `number` | `168` | Ring diameter in px. |
| `categoryLabel` | `string` | `"Group"` |  |

## Props: StatStrip

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stats` (required) | `ReadonlyArray<Stat>` |  |  |
| `loading` | `boolean` |  |  |
| `className` | `string` |  |  |
| `aria-label` | `string` |  |  |

## Props: Sparkline

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `values` (required) | `ReadonlyArray<number>` |  |  |
| `width` | `number` | `96` |  |
| `height` | `number` | `28` |  |
| `emphasiseLast` | `boolean` | `true` | The history in the de-emphasis hue, the current period (last segment and end dot) in the accent. Set false for an all-accent line. |
| `color` | `string` | `"var(--chart-1)"` | Accent colour, a var() from palette.ts. |
| `zeroBased` | `boolean` | `true` | Include zero in the scale. On for counts, off for rates that never near it. |
| `className` | `string` |  |  |

## Props: ChartContainer

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `config` (required) | `ChartConfig` |  |  |
| `children` (required) | `ComponentProps<typeof ResponsiveContainer>["children"]` |  | One Recharts chart (AreaChart, BarChart...). |
| `initialDimension` | `{ width: number; height: number }` | `{ width: 320, height: 200 }` | Size used before the first measure, so SSR and first paint are not 0 by 0. |

Also accepts the native attributes of: AriaAttributes, DOMAttributes, HTMLAttributes.

## Props: ChartTooltipContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  |  |
| `indicator` | `Indicator` | `"dot"` | dot (default), line or dashed key beside each row. |
| `hideLabel` | `boolean` | `false` |  |
| `hideIndicator` | `boolean` | `false` |  |
| `labelKey` | `string` |  | Config key to read the label from, when the label is not the x value. |
| `nameKey` | `string` |  | Row name from this field of the datum (pies: "browser"). |
| `color` | `string` |  | Forces every indicator to one colour. |
| `labelFormatter` | `(label: ReactNode, payload: ReadonlyArray<TooltipPayloadEntry>) => ReactNode` |  | Header text. Receives the resolved label and the payload. |
| `formatter` | `( value: TooltipPayloadEntry["value"], name: TooltipPayloadEntry["name"], item: TooltipPayloadEntry, index: number, datum: unknown, ) => ReactNode` |  | Replaces a row's whole body. |
| `valueFormatter` | `(value: number) => string` | `formatNumber` | Formats each numeric value (kit default: formatNumber). |
| `tag` | `string` |  | Small uppercase tag beside the label ("Cumulative"). Kit extra. |
| `total` | `boolean \| string` |  | Adds a total row: stacked charts. Kit extra. |

Also accepts the native attributes of: DOM attributes, Props.

## Props: ChartLegendContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  |  |
| `hideIcon` | `boolean` | `false` |  |
| `nameKey` | `string` |  |  |
| `payload` | `ReadonlyArray<LegendPayload>` |  |  |
| `verticalAlign` | `"top" \| "middle" \| "bottom"` | `"bottom"` |  |

## Examples

### Area, two series

```tsx
<AreaChart
  title="Orders per month"
  summary="Online orders rose every month, from 182 to 344."
  data={ORDERS}
  x="month"
  series={[{ key: "online", label: "Online" }, { key: "retail", label: "Retail" }]}
  formatX={formatMonthTick}
  formatXLong={formatMonth}
/>
```

### Line with a reference

```tsx
<LineChart title="Online orders" summary="…" data={ORDERS} x="month" series={[{ key: "online", label: "Online" }]} reference={{ value: 300, label: "Target" }} />
```

### Bars, labelled

```tsx
<BarChart title="Revenue by region" summary="North leads with 48,200." data={REVENUE} category="region" series={[{ key: "revenue", label: "Revenue" }]} orientation="bars" valueLabels />
```

### Donut

```tsx
<DonutChart title="Projects by status" summary="Of 40 projects, 22 are on track." centreLabel="Projects" data={STATUS_SPLIT} />
```

### Stat strip with sparklines

```tsx
<StatStrip aria-label="This month" stats={[{ label: "Orders", value: 505, delta: { value: 32, period: "vs last month" }, trend: [302, 323, 362, 375, 416, 453, 471, 505] }]} />
```

### The shadcn primitives

ChartContainer with a ChartConfig, Recharts marks reading var(--color-<key>), and ChartTooltipContent. See /charts for every tooltip variant.

```tsx
const chartConfig = {
  online: { label: "Online", color: "var(--chart-1)" },
  retail: { label: "Retail", color: "var(--chart-3)" },
} satisfies ChartConfig;

<ChartContainer config={chartConfig} style={{ aspectRatio: "auto", height: 220 }}>
  <BarChart accessibilityLayer data={rows}>
    <CartesianGrid vertical={false} />
    <XAxis dataKey="month" tickLine={false} axisLine={false} />
    <ChartTooltip {...TOOLTIP_MOTION} content={<ChartTooltipContent indicator="dot" />} />
    <Bar dataKey="online" fill="var(--color-online)" radius={4} />
    <Bar dataKey="retail" fill="var(--color-retail)" radius={4} />
  </BarChart>
</ChartContainer>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--chart-axis` | `var(--line)` |
| `--chart-band` | `var(--wash-hover)` |
| `--chart-cursor` | `var(--line)` |
| `--chart-grid` | `var(--line-soft)` |
| `--chart-tick` | `var(--ink-muted)` |
| `--popover-blur` | `none` |
| `--popover-border` | `transparent` |
| `--popover-shadow` | `var(--shadow-float)` |
| `--popover-surface` | `var(--surface-solid)` |
| `--r-circle` | `50%` |
| `--r-flat` | `2px` |
| `--stat-count` | `4` |

System tokens it reads: `--brand`, `--danger-fill`, `--danger-ink`, `--dur`, `--dur-slow`, `--ease`, `--focus-ring`, `--font-body`, `--glass-fill-nested`, `--indicator`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-heading`, `--ink-muted`, `--ink-secondary`, `--line`, `--line-glass`, `--line-soft`, `--r-2xs`, `--r-md`, `--r-sm`, `--r-xs`, `--rgb-brand`, `--rgb-brand-deep`, `--shadow-float`, `--success-ink`, `--surface-solid`, `--surface-sunken`, `--table-cell-pad`, `--table-head-fill`, `--table-head-ink`, `--table-head-pad`, `--table-head-rule`, `--table-row-hover`, `--table-row-line`, `--text-caption`, `--text-micro`, `--text-small`, `--tracking-label`, `--wash-active`, `--wash-hover`, `--wash-subtle`.

## Accessibility

- Every chart is a <figure> labelled by its title and described by summary, which is also the SVG's <desc>.
- The Chart or Table toggle shows the same data as a real table with a caption, for screen readers and for anyone comparing values.
- Colour is never the only key: legends name each series, end labels sit on lines, status hues always come with a label.
- The categorical order is the colour-blind safety mechanism; keep it.

## Do

- Write summary as the headline: what changed and by how much.
- Use StatStrip for headline figures: one surface, hairline cells, never a grid of separate cards.
- Pass status="loading" while data loads so the skeleton matches the chart's shape.

## Don't

- Don't hard-code a hex on a mark; set --chart-* tokens instead.
- Don't use more than six series; fold the rest into Other.
- Don't use status colours (good, warning, danger) as series identity.

Related: https://rime.mjsons.net/components/meter, https://rime.mjsons.net/components/table

---

# Stepper

> The wizard's step list: lettered markers, states, and optional navigation back to finished steps.

Category: Navigation. Docs page: https://rime.mjsons.net/components/stepper

## Installation

```bash
npx shadcn@latest add KezLahd/rime/stepper
```

Stepper heads a multi-step form. Steps are complete, current, upcoming or error; onStepClick lets people return to a finished step.

## Usage

```tsx
import { Stepper } from "@/components/ui";

<Stepper aria-label="Checkout" steps={steps} onStepClick={goTo} />
```

## Props: Stepper

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` (required) | `ReadonlyArray<StepperStep>` |  |  |
| `onStepClick` | `(id: string) => void` |  | Makes complete, error and current steps clickable. Upcoming steps never are. |
| `aria-label` | `string` |  |  |
| `className` | `string` |  |  |

## Examples

### Default

```tsx
<Stepper steps={steps} aria-label="Checkout" />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--r-flat` | `1px` |

System tokens it reads: `--brand`, `--brand-deep`, `--brand-gradient`, `--danger-base`, `--danger-ink`, `--dur`, `--ease`, `--focus-ring`, `--glow-sm`, `--ink-brand`, `--ink-heading`, `--ink-inverse`, `--ink-muted`, `--ink-secondary`, `--r-sm`, `--recess-fill`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-danger`, `--shadow-recess`, `--surface-solid`, `--text-caption`, `--text-micro`.

## Accessibility

- The current step carries aria-current="step".

## Do

- Let people go back to any finished step.

## Don't

- Don't let people jump ahead past an unfinished step.

---

# FilterBar

> The one filter row above every table: a growing search, dropdown chips at the end, clear, and the list's own action.

Category: Navigation. Docs page: https://rime.mjsons.net/components/filter-bar

## Installation

```bash
npx shadcn@latest add KezLahd/rime/filter-bar
```

FilterBar lays out a list's filters in a fixed order: a FilterSearch that grows to fill the row, then Select chips (and a DateRangeFilter), then a ghost "Clear filters" while anything is applied, then the list's own action after a hairline ("New invoice").

It is presentational. Filter state lives with the screen, which also decides when to pass onClear (only while a filter is applied). No title, no "n of m shown" line and never a row of toggle chips.

## Usage

```tsx
import { FilterBar, FilterSearch, Select } from "@/components/ui";

<FilterBar aria-label="Filter invoices" onClear={filtering ? clear : undefined} actions={<Button size="sm" iconStart={<IconPlus size={14} />}>New invoice</Button>}>
  <FilterSearch grow aria-label="Search invoices" value={query} onChange={setQuery} placeholder="Customer or invoice number" />
  <Select appearance="chip" aria-label="Status" value={status} onChange={setStatus} active={status !== "all"} options={STATUSES} />
</FilterBar>
```

## Props: FilterBar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | The filters, in order: a <FilterSearch grow /> first, then <Select appearance="chip" /> dropdowns. The search fills whatever the dropdowns leave, so the row always spans the table's full width. |
| `aria-label` (required) | `string` |  | Names the filter group for screen readers: "Filter seats". |
| `onClear` | `() => void` |  | Shown as a ghost "Clear filters" after the dropdowns. Pass it only while a filter is applied. |
| `clearLabel` | `string` | `"Clear filters"` |  |
| `actions` | `ReactNode` |  | The list's own action, at the far end after a hairline: "Add team member". |
| `className` | `string` |  |  |

## Props: FilterSearch

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` |  |  |
| `onChange` (required) | `(value: string) => void` |  |  |
| `placeholder` | `string` | `"Search"` |  |
| `aria-label` (required) | `string` |  |  |
| `className` | `string` |  |  |
| `width` | `number \| string` | `220` | Width of the chip. Defaults to 220px. Ignored when grow is set. |
| `grow` | `boolean` |  | Fill the row: the search takes every pixel the other filters leave (FilterBar's pattern, where dropdowns sit at the end). |

## Props: FilterChip

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` | `false` | Filter applied. Shown by tint and ink only, never a ring. |
| `icon` | `ReactNode` |  |  |
| `count` | `number` |  |  |
| `children` (required) | `ReactNode` |  |  |

Also accepts the native attributes of: AriaAttributes, ButtonHTMLAttributes, DOMAttributes, HTMLAttributes.

## Examples

### Search, dropdowns, clear and action

Type or pick a status to see Clear filters appear.

```tsx
<FilterBar aria-label="Filter invoices" onClear={filtering ? clear : undefined} actions={<Button size="sm">New invoice</Button>}>
  <FilterSearch grow aria-label="Search" value={q} onChange={setQ} />
  <Select appearance="chip" aria-label="Status" … />
  <DateRangeFilter aria-label="Issued" … />
</FilterBar>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--chip-height` | `var(--control-h-sm)` |
| `--chip-radius` | `var(--r-sm)` |
| `--filter-bar-gap` | `14px` |

System tokens it reads: `--brand-deep`, `--chip-active-fill`, `--chip-active-fill-hover`, `--chip-active-shadow`, `--control-h-sm`, `--density`, `--dur`, `--ease`, `--focus-color`, `--focus-ring`, `--font-body`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-muted`, `--line-glass`, `--r-2xs`, `--r-full`, `--r-sm`, `--recess-fill`, `--recess-fill-hover`, `--rgb-brand`, `--rgb-contact`, `--rgb-white`, `--shadow-recess`, `--text-caption`, `--wash-active`.

## Accessibility

- The filters sit in role="group" named by the required aria-label ("Filter invoices").
- Every chip needs its own aria-label: chips show a value, not a label.
- Announce result counts from the table region (a polite status line), not from the bar.

## Do

- Order: search, dropdowns, date, clear, then the action.
- Pass onClear only while a filter is applied.
- Use FilterSearch here, not SearchField, so the row's heights match.

## Don't

- Never a row of toggle chips for a single-choice filter; use a Select chip.
- Don't put a heading or result count above the bar.

Related: https://rime.mjsons.net/components/table, https://rime.mjsons.net/components/select, https://rime.mjsons.net/components/date-range-filter

---

# FolderTabs and SegmentedControl

> Folder tabs that sit on a glass panel with always-visible counts, and a segmented control for views.

Category: Navigation. Docs page: https://rime.mjsons.net/components/tabs

## Installation

```bash
npx shadcn@latest add KezLahd/rime/tabs
```

FolderTabs switch between queues of the same list (Open, In review, Cancelled). Each tab shows its count so the workload reads without opening each; the panel's top-left corner squares off so the tabs sit on it.

SegmentedControl switches the view of the same content (Chart or Table, List or Board). The active segment is a white key lifted out of a recess.

## Usage

```tsx
import { FolderTabs, SegmentedControl } from "@/components/ui";

<SegmentedControl aria-label="View" value={view} onChange={setView} options={[{ value: "chart", label: "Chart" }, { value: "table", label: "Table" }]} />
```

## Props: FolderTabs

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tabs` (required) | `ReadonlyArray<FolderTab>` |  |  |
| `value` (required) | `string` |  |  |
| `onChange` (required) | `(id: string) => void` |  |  |
| `aria-label` (required) | `string` |  |  |
| `children` (required) | `ReactNode` |  | Content of the active tab's panel. |
| `panelPadding` | `GlassPanelProps["padding"]` | `"md"` |  |
| `panelVariant` | `GlassPanelProps["variant"]` | `"page"` |  |
| `className` | `string` |  |  |

## Props: SegmentedControl

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` (required) | `ReadonlyArray<SegmentedOption<V>>` |  |  |
| `value` (required) | `V` |  |  |
| `onChange` (required) | `(value: V) => void` |  |  |
| `aria-label` (required) | `string` |  |  |
| `size` | `"sm" \| "md"` | `"md"` |  |
| `className` | `string` |  |  |

## Examples

### Folder tabs

```tsx
<FolderTabs aria-label="Orders" tabs={[{ id: "open", label: "Open", count: 12 }, { id: "review", label: "In review", count: 4, colour: "amber" }]} value={tab} onChange={setTab}>…</FolderTabs>
```

### Segmented control

```tsx
<SegmentedControl aria-label="View" value={view} onChange={setView} options={VIEWS} />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--r-flat` | `max(0px, calc(var(--segmented-radius, var(--r-sm)) - 3px))` |
| `--segmented-radius` | `var(--r-sm)` |
| `--tab-brand-active-from` | `#fdfcff` |
| `--tab-brand-active-to` | `#f3eefb` |
| `--tab-brand-from` | `#f7f4fc` |
| `--tab-brand-ink` | `#4e3470` |
| `--tab-brand-rgb` | `78, 52, 112` |
| `--tab-brand-to` | `#efe9f8` |
| `--tab-pad-x` | `calc(20px * var(--density))` |
| `--tab-radius` | `var(--r-md)` |

System tokens it reads: `--danger-ink`, `--density`, `--dur`, `--dur-fast`, `--ease`, `--focus-color`, `--focus-ring`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-muted`, `--ink-secondary`, `--r-md`, `--r-sm`, `--recess-fill`, `--rgb-brand`, `--rgb-contact`, `--rgb-white`, `--shadow-panel`, `--shadow-recess`, `--shadow-specular`, `--success-ink`, `--surface-solid`, `--text-caption`, `--text-small`, `--warning-ink`.

## Accessibility

- FolderTabs implement the ARIA tabs pattern: role="tablist", arrow keys move between tabs, the panel is role="tabpanel".
- SegmentedControl is a radiogroup: arrow keys change the value.

## Do

- Always show counts on folder tabs.

## Don't

- Don't use folder tabs for page navigation; that is the sidebar.

---

# NavSearch and SmartSearch

> Top-bar search: NavSearch jumps to pages and actions; SmartSearch queries records with grouped results.

Category: Navigation. Docs page: https://rime.mjsons.net/components/nav-search

## Installation

```bash
npx shadcn@latest add KezLahd/rime/nav-search
```

NavSearch filters a fixed list of destinations with a keyboard shortcut (Ctrl or Cmd K). SmartSearch takes an async search function with abort signals and renders grouped record results with highlighting.

## Usage

```tsx
import { NavSearch, SmartSearch } from "@/components/ui";

<NavSearch aria-label="Search pages" items={DESTINATIONS} />
```

## Props: NavSearch

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `ReadonlyArray<NavSearchItem>` |  |  |
| `recent` | `ReadonlyArray<string>` |  | Ids of recently opened items, newest first. Listed under "Recent" above everything else while the search is empty. The host keeps the list (from onSelect), so it can live wherever the rest of the session does. |
| `onSelect` | `(item: NavSearchItem) => boolean \| void` |  | Runs before navigating. Return false to stay put (the styleguide does, and a host can to open a dialog instead). |
| `placeholder` | `string` | `"Search pages and actions"` |  |
| `shortcut` | `string \| null` | `"k"` | Ctrl/⌘ + this letter opens the search from anywhere. Pass null to turn it off. |
| `width` | `number \| string` | `340` | Width of the bar, and the least width of its results. |
| `aria-label` | `string` |  | Names the search for assistive tech. |
| `className` | `string` |  |  |
| `inline` | `boolean` | `false` | Show the results panel open, in place under the bar: no portal, no outside-click listener, no scrolling into view. For docs and thumbnails. |

## Props: SmartSearch

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `search` (required) | `(query: string, signal: AbortSignal) => Promise<SmartSearchGroup[]>` |  | Runs the search. Called once typing pauses, with a signal that aborts when the query changes, so a slow answer to "ha" never lands on top of "cooper". Reject (anything but an AbortError) to show the error state. |
| `onSelect` (required) | `(result: SmartSearchResult, context: SmartSearchSelectContext) => boolean \| void` |  | A result was chosen (Enter or click). The host records it in recent searches. Return false to stay put; otherwise a result with an href is navigated to. |
| `onViewAll` | `(query: string) => void` |  | "View all results": the footer row, and Enter with no row highlighted. Omit to leave both out. |
| `recent` | `ReadonlyArray<string>` |  | Earlier queries, newest first. Offered while the field is focused and empty. |
| `placeholder` | `string` | `"Search"` |  |
| `minChars` | `number` | `2` | Characters before a search runs. Defaults to 2: one letter matches most of a database. |
| `debounceMs` | `number` | `180` | Pause after the last keystroke before searching. |
| `renderResult` | `(result: SmartSearchResult, state: SmartSearchResultState) => ReactNode` |  | Replaces the default row body (tile, text, meta, hint are all yours). |
| `emptyHint` | `ReactNode` |  | Shown when focused and empty with no recent searches: say what can be searched for. |
| `noResultsHint` | `(query: string) => ReactNode` |  | Suggestion under "No results for …". |
| `size` | `"sm" \| "md"` | `"md"` |  |
| `shortcut` | `string` |  | Ctrl/⌘ + this letter focuses the field. Use once per page. |
| `disabled` | `boolean` |  |  |
| `id` | `string` |  |  |
| `aria-label` | `string` |  | Needed unless a <Field> labels it. |
| `className` | `string` |  |  |

## Examples

### Open

inline shows the results panel open under the bar, in place.

```tsx
<NavSearch inline aria-label="Search pages and actions" items={DESTINATIONS} />
```

### NavSearch

```tsx
<NavSearch items={DESTINATIONS} aria-label="Search pages and actions" />
```

## Theme tokens

System tokens it reads: `--blur-chrome`, `--brand-gradient`, `--brand-gradient-soft`, `--danger-ink`, `--dur`, `--dur-fast`, `--ease`, `--ease-out`, `--focus-halo`, `--focus-ring`, `--font-body`, `--glass-edge`, `--glass-fill-chrome`, `--glow-sm`, `--ink-body`, `--ink-brand`, `--ink-heading`, `--ink-inverse`, `--ink-muted`, `--ink-secondary`, `--line`, `--line-brand`, `--line-brand-strong`, `--line-soft`, `--r-2xs`, `--r-full`, `--r-lg`, `--r-md`, `--r-sm`, `--rgb-brand-deep`, `--rgb-white`, `--shadow-chrome`, `--shadow-chrome-open`, `--shadow-float`, `--surface-solid`, `--text-caption`, `--text-micro`, `--text-small`, `--tracking-label`, `--wash-active`, `--wash-hover`, `--wash-row`, `--wash-strong`, `--wash-subtle`, `--z-popover`.

## Accessibility

- Combobox with a listbox of results; the shortcut is announced in the hint.

## Do

- Keep NavSearch items to real destinations.

## Don't

- Don't use SmartSearch without debouncing on the server side too.

---

# Breadcrumb

> Where this page sits: a trail of links ending on the current page, folding its middle into a menu when long.

Category: Navigation. Docs page: https://rime.mjsons.net/components/breadcrumb

## Installation

```bash
npx shadcn@latest add KezLahd/rime/breadcrumb
```

Breadcrumb is a nav landmark holding an ordered list of links. The last item is the current page: not a link, marked aria-current="page", in heading ink. Items may carry an icon (a home glyph on the first).

Past maxItems (default 4) the middle folds into an ellipsis Menu: the first item, the menu, then the last items, so the trail stays on one line. separator swaps the chevron for any node, "/" being the common alternative.

## Usage

```tsx
import { Breadcrumb } from "@/components/ui";

<Breadcrumb
  items={[
    { label: "Home", href: "/" },
    { label: "Projects", href: "/projects" },
    { label: "Website relaunch" },
  ]}
/>
```

## Props: Breadcrumb

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `ReadonlyArray<BreadcrumbItem>` |  |  |
| `maxItems` | `number` | `4` | Past this many items the middle folds into an ellipsis menu: the first item, the menu, then the last (maxItems - 2). Default 4. |
| `separator` | `ReactNode` |  | Between items. Defaults to a small chevron; "/" is the other common choice. |
| `aria-label` | `string` |  |  |
| `className` | `string` |  |  |

## Examples

### Default

```tsx
<Breadcrumb items={[{ label: "Home", href: "/", icon: <IconHome size={14} /> }, { label: "Projects", href: "/projects" }, { label: "Website relaunch" }]} />
```

### Long trail, folded

Six items with maxItems={4}: the middle three sit in the ellipsis menu.

```tsx
<Breadcrumb maxItems={4} items={TRAIL} />
```

### Slash separator

```tsx
<Breadcrumb separator="/" items={[{ label: "Settings", href: "/settings" }, { label: "Team", href: "/settings/team" }, { label: "Members" }]} />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--breadcrumb-gap` | `6px` |
| `--breadcrumb-size` | `var(--text-small)` |

System tokens it reads: `--dur`, `--ease`, `--focus-ring`, `--ink-brand`, `--ink-disabled`, `--ink-heading`, `--ink-muted`, `--r-xs`, `--text-small`, `--wash-subtle`.

## Accessibility

- A <nav aria-label="Breadcrumb"> wrapping an <ol>, so the count and order are announced.
- The current page is aria-current="page" and not a link; separators are hidden from assistive tech.
- The ellipsis is a Menu button named "Show n more" with keyboard support of its own.

## Do

- Start from the section root, not from the site name, when the shell already shows the site.

## Don't

- Don't use a breadcrumb as the only navigation.
- Don't link the current page to itself.

Related: https://rime.mjsons.net/components/navigation-menu, https://rime.mjsons.net/components/page-header

---

# NavigationMenu

> Top-level site navigation with frosted dropdown panels of described links, built as disclosure navigation.

Category: Navigation. Docs page: https://rime.mjsons.net/components/navigation-menu

## Installation

```bash
npx shadcn@latest add KezLahd/rime/navigation-menu
```

NavigationMenu is the marketing-site or docs header: a row of top-level items, each either a plain link or a button that opens a panel of links with a title, a description and an optional icon. A panel can lead with a feature block (a highlighted card) and lays its links in one to three columns.

It follows the WAI-ARIA disclosure navigation pattern, not role="menu": these are links, read as links. Clicking outside, tabbing out or pressing Esc closes the open panel.

inline renders the panel in normal flow beneath the bar instead of floating over the page, for docs and previews where it has to show open. defaultValue opens a panel on first render.

## Usage

```tsx
import { NavigationMenu } from "@/components/ui";

<NavigationMenu
  aria-label="Main"
  items={[
    { id: "product", label: "Product", links: [{ href: "/projects", title: "Projects", description: "Plan work and track every order." }] },
    { id: "pricing", label: "Pricing", href: "/pricing" },
  ]}
/>
```

## Props: NavigationMenu

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `ReadonlyArray<NavigationMenuItem>` |  |  |
| `aria-label` | `string` |  |  |
| `defaultValue` | `string \| null` | `null` | The panel open on first render, by item id. |
| `inline` | `boolean` |  | Renders the open panel in normal flow under the bar instead of floating over the page: for docs and previews, where the menu must show open. |
| `activeHref` | `string` |  | The current page, for aria-current on the matching link. |
| `className` | `string` |  |  |

## Examples

### Open panel with a feature block

Rendered inline and open, so the panel shows in place.

```tsx
<NavigationMenu aria-label="Main" items={NAV} inline defaultValue="product" />
```

### Floating panels

The default: panels float over the page under their item.

```tsx
<NavigationMenu aria-label="Site" items={NAV} />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--navmenu-item-radius` | `var(--r-sm)` |
| `--navmenu-link-width` | `230px` |
| `--navmenu-panel-max` | `600px` |
| `--navmenu-radius` | `var(--r-lg)` |

System tokens it reads: `--border-w`, `--brand-gradient-soft`, `--control-h-sm`, `--density`, `--dur`, `--dur-fast`, `--dur-slow`, `--ease`, `--ease-out`, `--focus-ring`, `--ink-body`, `--ink-brand`, `--ink-heading`, `--ink-muted`, `--ink-secondary`, `--line-brand`, `--popover-blur`, `--popover-border`, `--popover-shadow`, `--popover-surface`, `--r-lg`, `--r-sm`, `--text-caption`, `--text-small`, `--wash-active`, `--wash-hover`, `--wash-subtle`, `--z-popover`.

## Accessibility

- Each dropdown trigger is a button with aria-expanded and aria-controls; panels hold ordinary links.
- Left and Right move between top-level items; Down opens a panel and focuses its first link; Up and Down move through links; Esc closes and returns focus to the trigger.
- activeHref marks the current page's link with aria-current="page".

## Do

- Keep to five or six top-level items.
- Give every link a one-line description in panels with more than three links.

## Don't

- Don't use it inside an app shell; that is SidebarShell's nav.
- Don't put actions (sign out, delete) in its panels; those belong in a Menu.

Related: https://rime.mjsons.net/components/breadcrumb, https://rime.mjsons.net/components/menu, https://rime.mjsons.net/components/sidebar-shell

---

# Pagination

> Centred page buttons with previous and next, gaps for long ranges, and a summary line at the left.

Category: Navigation. Docs page: https://rime.mjsons.net/components/pagination

## Installation

```bash
npx shadcn@latest add KezLahd/rime/table
```

Pagination is the pager that sits under every Table, documented on its own because it works under any list: cards, search results, an activity feed. The page buttons stay on the centre line whatever the summary's length (a 1fr auto 1fr grid), and long ranges collapse into gaps around the current page.

With totalItems and pageSize it says "Showing 41 to 60 of 236 orders"; without, "Page 3 of 12". It is presentational: the screen owns the page number.

## Usage

```tsx
import { Pagination } from "@/components/ui";

<Pagination page={page} pageCount={12} onPageChange={setPage} totalItems={236} pageSize={20} itemLabel="orders" />
```

## Props: Pagination

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `page` (required) | `number` |  |  |
| `pageCount` (required) | `number` |  |  |
| `onPageChange` (required) | `(page: number) => void` |  |  |
| `totalItems` | `number` |  |  |
| `pageSize` | `number` |  |  |
| `itemLabel` | `string` | `"results"` | Plural noun for the summary: "customers", "requests". |
| `className` | `string` |  |  |

## Examples

### With a summary

```tsx
<Pagination page={page} pageCount={12} onPageChange={setPage} totalItems={236} pageSize={20} itemLabel="orders" />
```

### Pages only

```tsx
<Pagination page={page} pageCount={5} onPageChange={setPage} />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--button-primary-bg` | `var(--brand-gradient)` |
| `--button-radius` | `var(--r-sm)` |
| `--inner-radius` | `var(--r-lg)` |
| `--r-flat` | `var(--table-radius, var(--r-md))` / `var(--table-radius, var(--inner-radius, var(--r-lg)))` |
| `--table-radius` | `var(--r-md)` / `var(--inner-radius, var(--r-lg))` |
| `--table-row-height` | `46px` |

System tokens it reads: `--brand-deep`, `--brand-gradient`, `--control-h-sm`, `--dur`, `--ease`, `--focus-color`, `--focus-ring`, `--font-mono`, `--glass-fill-nested`, `--glow-sm`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-inverse`, `--ink-muted`, `--line-glass`, `--line-soft`, `--r-lg`, `--r-md`, `--r-sm`, `--rgb-contact`, `--surface-solid`, `--table-cell-pad`, `--table-head-fill`, `--table-head-hover`, `--table-head-ink`, `--table-head-pad`, `--table-head-press`, `--table-head-rule`, `--table-row-hover`, `--table-row-line`, `--text-caption`, `--text-small`, `--wash-subtle`.

## Accessibility

- A nav labelled "Pagination"; the current page button has aria-current="page"; every button is named "Page n".
- Previous and next disable at the ends rather than disappearing, so the layout never jumps.
- The summary is a polite live region, so a page change is announced.

## Do

- Reset to page one when a filter or sort changes.
- Keep it centred under the list it pages.

## Don't

- Don't left-align the page buttons.
- Don't use infinite scroll for records people need to find again.

Related: https://rime.mjsons.net/components/table, https://rime.mjsons.net/components/filter-bar

---

# Skeleton

> Loading placeholders shaped like the content they stand in for, with a soft shimmer.

Category: Feedback. Docs page: https://rime.mjsons.net/components/skeleton

## Installation

```bash
npx shadcn@latest add KezLahd/rime/skeleton
```

Skeleton draws a block, a text line or a circle. Size each one to the real content (the Table does this per column) so nothing jumps when data arrives.

## Usage

```tsx
import { Skeleton, SkeletonText } from "@/components/ui";

<Skeleton width={180} height={20} />
<SkeletonText lines={3} />
```

## Props: Skeleton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `width` | `number \| string` | `"100%"` | Size to the real content it stands in for, not a generic block. |
| `height` | `number \| string` |  |  |
| `variant` | `"text" \| "block" \| "circle"` | `"block"` | text = a line of text at the given font size's height; circle = avatar. |
| `radius` | `number \| string` |  |  |
| `className` | `string` |  |  |
| `style` | `CSSProperties` |  |  |

## Props: SkeletonText

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `lines` | `number` | `3` |  |
| `lastLineWidth` | `string` | `"62%"` | Last line is shorter, as real paragraphs are. |
| `lineHeight` | `number` | `14` |  |
| `className` | `string` |  |  |

## Examples

### Shapes

```tsx
<Skeleton variant="circle" width={36} height={36} />
<SkeletonText lines={2} />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--r-circle` | `50%` |
| `--r-flat` | `var(--skeleton-radius)` |

System tokens it reads: `--ease`, `--r-2xs`, `--r-xs`, `--rgb-brand-deep`, `--rgb-white`, `--skeleton-radius`.

## Accessibility

- Hidden from assistive tech; mark the loading region aria-busy instead.

## Do

- Match the real layout's dimensions.

## Don't

- Don't show grey blocks with no relation to the content.

---

# Alert

> An inline message in a tone (info, success, warning, danger) or a quiet legal box for fixed wording, with an action and dismiss.

Category: Feedback. Docs page: https://rime.mjsons.net/components/alert

## Installation

```bash
npx shadcn@latest add KezLahd/rime/alert
```

Alert sits in the flow of a page or form. It carries a title, body, an action (a retry), a badge and an optional reference code for approved wording. live makes it announce when it appears.

## Usage

```tsx
import { Alert } from "@/components/ui";

<Alert tone="warning" title="Payment is processing">We will email you when the bank confirms it.</Alert>
```

## Props: Alert

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` (required) | `AlertTone` |  |  |
| `title` | `ReactNode` |  |  |
| `children` | `ReactNode` |  |  |
| `action` | `ReactNode` |  | A button or link on the right (desktop) or below (mobile). |
| `icon` | `ReactNode \| false` |  |  |
| `badge` | `ReactNode` |  | Small uppercase tag before the title: "Cold chain", "Awaiting MLR". |
| `jobCode` | `string` |  | legal only: the approval job code, set in mono under the copy. |
| `live` | `boolean` |  | Announce on appearance. Use for banners that appear in response to an action (a failed save), not for ones present on page load. |
| `onDismiss` | `() => void` |  |  |
| `className` | `string` |  |  |

## Examples

### Tones

```tsx
<Alert tone="info" title="Heads up">…</Alert>
<Alert tone="danger" title="Couldn't save" action={<Button size="sm" variant="secondary">Try again</Button>} />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--alert-radius` | `var(--r-md)` |

System tokens it reads: `--blur-callout`, `--border-w`, `--danger-fill`, `--danger-ink`, `--danger-line`, `--density`, `--focus-ring`, `--font-mono`, `--info-ink`, `--ink-body`, `--ink-heading`, `--ink-muted`, `--line-brand`, `--r-2xs`, `--r-md`, `--r-xs`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-support`, `--rgb-support-deep`, `--rgb-white`, `--success-fill`, `--success-ink`, `--success-line`, `--text-body`, `--text-micro`, `--text-small`, `--warning-fill`, `--warning-ink`, `--warning-line`.

## Accessibility

- live renders role="alert" (danger and warning) or role="status" (the rest); without live it is plain content, so it is not re-announced on every render.

## Do

- Say what happened and what to do next.

## Don't

- Don't use an Alert for transient confirmation; that is a toast.

---

# Toast

> Frosted toasts for success, error, info and in-flight work, stacked as a deck that fans out on hover.

Category: Feedback. Docs page: https://rime.mjsons.net/components/toast

## Installation

```bash
npx shadcn@latest add KezLahd/rime/toast
```

Mount ToastProvider once in the root layout and call useToast(). success and info leave after 5 seconds with a timer rule; error and loading stay until dismissed or settled. toast.promise shows loading, then success or error when the promise settles.

## Usage

```tsx
import { useToast } from "@/components/ui";

const toast = useToast();
await toast.promise(save(), { loading: "Saving…", success: "Saved", error: "Couldn't save" });
```

## Examples

### The stack

ToastStackPreview draws the real stack in place, with no timers and no live region: loading, an error with an action, and a success.

```tsx
<ToastStackPreview
  expanded
  items={[
    { id: 1, tone: "loading", title: "Saving changes…" },
    { id: 2, tone: "error", title: "Couldn't send", description: "Check your connection.", action: { label: "Retry", onClick: retry } },
    { id: 3, tone: "success", title: "Invoice sent", description: "INV-1042 is on its way to Jane Cooper." },
  ]}
/>
```

### Tones

```tsx
toast.success("Invoice sent", { description: "INV-1042 is on its way to Jane Cooper." });
toast.error("Couldn't send", { action: { label: "Retry", onClick: retry } });
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--button-case` | `none` |
| `--button-size-sm` | `12.5px` |
| `--button-tracking` | `0` |
| `--toast-blur` | `blur(28px) saturate(180%)` |
| `--toast-icon-radius` | `var(--r-sm)` |
| `--toast-radius` | `var(--r-lg)` |
| `--toast-rgb-error` | `237, 93, 87` |
| `--toast-rgb-info` | `110, 84, 153` |
| `--toast-rgb-success` | `52, 168, 112` |
| `--toast-surface` | `rgba(var(--rgb-white), 0.82)` |

System tokens it reads: `--brand-gradient`, `--danger-ink`, `--density`, `--dur`, `--ease`, `--ease-out`, `--focus-ring`, `--font-body`, `--front-height`, `--index`, `--ink-brand`, `--ink-heading`, `--ink-muted`, `--ink-secondary`, `--line-brand`, `--line-brand-strong`, `--offset`, `--own-height`, `--r-lg`, `--r-sm`, `--r-xs`, `--rgb-brand-deep`, `--rgb-contact`, `--rgb-white`, `--success-gradient`, `--success-ink`, `--text-body`, `--text-small`, `--toast-duration`, `--wash-active`, `--wash-strong`, `--wash-subtle`, `--z-toast`.

## Accessibility

- The stack sits in a region labelled "Notifications" with a polite live list, and stays live while a Modal makes the rest of the page inert.
- Hover or focus inside fans the stack out and pauses every timer; toasts never take focus.

## Do

- Confirm what was done, with the record's name or reference.

## Don't

- Don't put the only copy of important information in a toast.

---

# Spinner

> A small brand-tinted spinner for in-flight work inside buttons, fields and panels.

Category: Feedback. Docs page: https://rime.mjsons.net/components/spinner

## Installation

```bash
npx shadcn@latest add KezLahd/rime/spinner
```

Spinner is decorative unless given a label. Buttons and IconButtons show it themselves when loading.

## Usage

```tsx
import { Spinner } from "@/components/ui";

<Spinner label="Loading invoices" />
```

## Props: Spinner

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `number` | `16` | Pixel size. 14 inside buttons, 16–20 inline, 24 for a panel. |
| `tone` | `"brand" \| "current"` | `"brand"` | brand = accent on light surfaces; current = inherits text colour (buttons). |
| `label` | `string` |  | Announced to screen readers. Omit when the parent already says it is busy. |
| `className` | `string` |  |  |

## Examples

### Sizes

```tsx
<Spinner size={14} />
<Spinner size={20} label="Loading" />
```

## Theme tokens

System tokens it reads: `--brand`.

## Accessibility

- With label it is wrapped in role="status" with the label as text; without, it is decorative.

## Do

- Prefer skeletons for content that is loading.

## Don't

- Don't spin a whole page; show its shape.

---

# EmptyState

> What an empty list means and what to do next: default, positive (all done) and filtered tones.

Category: Feedback. Docs page: https://rime.mjsons.net/components/empty-state

## Installation

```bash
npx shadcn@latest add KezLahd/rime/empty-state
```

EmptyState never says just "No data". It names why the space is empty and offers the next step as an action. compact fits inside a Table.

## Usage

```tsx
import { EmptyState } from "@/components/ui";

<EmptyState title="No projects yet" description="Create a project to start tracking work." action={<Button href="/projects/new">New project</Button>} />
```

## Props: EmptyState

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `ReactNode` |  |  |
| `description` (required) | `ReactNode` |  | What to do next. Required: a bare "No data" is not an empty state. |
| `action` | `ReactNode` |  |  |
| `secondaryAction` | `ReactNode` |  |  |
| `icon` | `ReactNode` |  |  |
| `tone` | `"default" \| "positive" \| "filtered"` | `"default"` | default = nothing here yet. positive = nothing needs you ("All caught up"), a green tile. filtered = the filters exclude everything; offer to clear them. |
| `compact` | `boolean` |  | Tighter spacing for inside tables and dropdowns. |
| `className` | `string` |  |  |

## Examples

### Tones

```tsx
<EmptyState tone="positive" title="All caught up" description="Nothing is waiting for review." />
```

## Theme tokens

System tokens it reads: `--brand-gradient-soft`, `--ink-brand`, `--ink-heading`, `--ink-muted`, `--line-brand`, `--neutral-fill`, `--neutral-line`, `--r-md`, `--success-fill`, `--success-ink`, `--success-line`, `--text-body`, `--text-caption`, `--text-small`.

## Accessibility

- The icon is decorative; the title and description are plain text, so put the empty state under the heading of the list it belongs to.

## Do

- Use tone="filtered" with a clear-filters action when filters emptied the list.

## Don't

- Never ship a bare "No data".

---

# ImpactPreview

> What a destructive action will change, row by row, before it is confirmed.

Category: Feedback. Docs page: https://rime.mjsons.net/components/impact-preview

## Installation

```bash
npx shadcn@latest add KezLahd/rime/impact-preview
```

ImpactPreview lists the consequences of an action (projects reassigned, sign-ins revoked) with severities, named affected records, and loading, error and nothing-affected states. TypeToConfirmModal embeds it.

## Usage

```tsx
import { ImpactPreview } from "@/components/ui";

<ImpactPreview items={[{ id: "a", severity: "destructive", title: "Signed out everywhere" }]} />
```

## Props: ImpactPreview

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` | `"Impact preview"` | Default "Impact preview". |
| `headingLevel` | `2 \| 3 \| 4` | `3` | Level of the small-caps heading. 3 inside a modal (the dialog title is the h2). |
| `statement` | `ReactNode` |  | A compact danger line under the heading, e.g. "This action cannot be undone". TypeToConfirmModal passes its consequencesTitle here. |
| `items` | `ImpactItem[]` |  | One row per consequence. Omit for a panel of prose only (children); an empty array renders the empty row ("Nothing else is affected"). |
| `children` | `ReactNode` |  | Plain text under the heading and above the rows: context the rows don't carry. |
| `loading` | `boolean` | `false` | The consequences are still being worked out on the server. |
| `loadingRows` | `number` | `3` | How many skeleton rows stand in while loading. Match the usual count. |
| `error` | `ReactNode \| boolean` |  | true for the default message, or the reason. Shown instead of the rows. |
| `onRetry` | `() => void` |  | Shows a Retry button in the error row. |
| `emptyTitle` | `ReactNode` | `"Nothing else is affected"` | Title of the row an empty items array renders. |
| `affectedLimit` | `number` | `5` | Affected lists longer than this collapse behind "Show N more". Default 5. |
| `className` | `string` |  |  |

## Examples

### Default

```tsx
<ImpactPreview statement="This action cannot be undone" items={ITEMS} />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--r-circle` | `50%` |

System tokens it reads: `--danger-fill`, `--danger-ink`, `--danger-solid`, `--ease`, `--focus-ring`, `--font-body`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-heading`, `--ink-muted`, `--ink-secondary`, `--line`, `--line-soft`, `--r-2xs`, `--r-lg`, `--r-sm`, `--r-xs`, `--shadow-input`, `--shadow-specular`, `--success-ink`, `--success-solid`, `--surface-solid`, `--surface-sunken`, `--text-caption`, `--text-small`, `--warning-fill`, `--warning-ink`, `--warning-solid`, `--wash-active`.

## Accessibility

- A list with a heading; severities are written out, not only coloured.

## Do

- State each row as an outcome: "3 projects are reassigned".

## Don't

- Don't hide consequences behind a disclosure.

---

# Menu

> An action menu from a button: groups, headings, separators, icons, links and danger items, in a frosted popover.

Category: Overlays. Docs page: https://rime.mjsons.net/components/menu

## Installation

```bash
npx shadcn@latest add KezLahd/rime/menu
```

Menu lists actions (not choices; that is Select). Items can be links (rendered as Next Links) or callbacks, carry an icon and a description, and be marked danger or disabled. It shares Select's popover family.

## Usage

```tsx
import { Menu } from "@/components/ui";

<Menu label="Actions" items={[{ id: "edit", label: "Edit", onSelect: edit }, { id: "sep", separator: true }, { id: "void", label: "Void invoice", tone: "danger", onSelect: confirm }]} />
```

## Props: Menu

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `ReactNode` |  | Trigger content. A chevron is appended unless iconOnly or hideChevron. |
| `aria-label` | `string` |  | Accessible name when the trigger content is not descriptive (an avatar, an icon). |
| `items` (required) | `ReadonlyArray<MenuEntry>` |  |  |
| `header` | `ReactNode` |  | Tinted block at the top of the menu: name and ID number, say. |
| `align` | `"start" \| "end"` | `"end"` |  |
| `iconOnly` | `boolean` |  | Icon-only trigger (a "more" ellipsis): a square ghost button, no chevron. Give it an aria-label. |
| `hideChevron` | `boolean` |  | Drops the chevron from a custom trigger that signals the menu another way. |
| `disabled` | `boolean` |  |  |
| `triggerClassName` | `string` |  |  |
| `className` | `string` |  |  |
| `inline` | `boolean` | `false` | Render the menu open, in place, under its trigger: no portal, no focus move, no outside-click listener. For docs and thumbnails. |

## Examples

### Open

inline renders the menu open under its trigger, in place.

```tsx
<Menu inline label="Actions" items={ITEMS} />
```

### Default

```tsx
<Menu label="Actions" items={ITEMS} />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--chip-radius` | `var(--r-sm)` |
| `--popover-item-active-bg` | `linear-gradient(to right, rgba(var(--rgb-brand), 0.14), rgba(var(--rgb-brand-deep), 0.07))` |
| `--popover-item-press-bg` | `linear-gradient(to right, rgba(var(--rgb-brand), 0.2), rgba(var(--rgb-brand-deep), 0.1))` |
| `--popover-item-radius` | `var(--r-xs)` |
| `--popover-pad` | `calc(6px * var(--density))` |
| `--popover-radius` | `var(--r-lg)` |
| `--recess-fill-disabled` | `rgba(var(--rgb-white), 0.3)` |

System tokens it reads: `--blur-recess`, `--border-w`, `--brand-gradient-wash`, `--danger-ink`, `--density`, `--dur`, `--dur-fast`, `--ease`, `--ease-out`, `--focus-halo`, `--focus-ring`, `--font-body`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-heading`, `--ink-muted`, `--ink-secondary`, `--line-soft`, `--popover-blur`, `--popover-border`, `--popover-shadow`, `--popover-surface`, `--r-lg`, `--r-sm`, `--r-xs`, `--recess-fill`, `--recess-fill-hover`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-contact`, `--rgb-danger`, `--rgb-white`, `--shadow-recess`, `--text-caption`, `--text-micro`, `--text-small`, `--tracking-label`, `--wash-active`, `--wash-subtle`, `--z-popover`.

## Accessibility

- role="menu" with roving focus: arrows, Home, End, typeahead; Esc and Tab close and return focus to the trigger.

## Do

- Put destructive items last, after a separator.

## Don't

- Don't hide the only way to do something important in a menu.

---

# Tooltip and Toggletip

> Hover and focus tooltips (dark one-liners or light rich cards) and click-to-open toggletips for help.

Category: Overlays. Docs page: https://rime.mjsons.net/components/tooltip

## Installation

```bash
npx shadcn@latest add KezLahd/rime/tooltip
```

Tooltip labels a control on hover and focus after a short delay; it can show a keyboard shortcut and only appear when text is truncated. Toggletip is an info button that opens a small panel on click, for help text people need to read.

## Usage

```tsx
import { Toggletip, Tooltip } from "@/components/ui";

<Tooltip content="Print invoice"><IconButton label="Print" icon={<IconPrinter size={17} />} /></Tooltip>
```

## Props: Tooltip

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `content` (required) | `ReactNode` |  | Supplementary text only. Never the sole label of a control, never the only place essential information lives. |
| `title` | `ReactNode` |  | Makes it a rich tooltip: a bold first line above the content. |
| `footer` | `ReactNode` |  | Rich tooltip: a quiet line under a hairline (a source, a caveat). Not interactive: use Toggletip for a link. |
| `shortcut` | `ReadonlyArray<string>` |  | Keys shown as badges after the content, e.g. ["Ctrl", "K"]. Also sets aria-keyshortcuts on the trigger. |
| `children` (required) | `ReactElement<TriggerProps>` |  | One focusable element (a button, a link). Its handlers are preserved. A disabled button fires no pointer or focus events: wrap it in TooltipTarget. |
| `side` | `TooltipSide` | `"top"` | Preferred side. Flips to the opposite side when there is no room. |
| `delay` | `number` | `400` | Hover delay in ms. Focus shows at once; so does hover within 400 ms of another tooltip closing. |
| `tone` | `"dark" \| "light"` |  | dark (default for plain) or light (default for rich). |
| `maxWidth` | `number` |  | Default 240 plain, 300 rich. |
| `onlyWhenTruncated` | `boolean` | `false` | Only open when the trigger's text is clipped (an ellipsised cell). The text is already in the DOM, so no aria-describedby is added. |
| `disabled` | `boolean` | `false` | Switch the tooltip off without unwrapping the trigger. |
| `inline` | `boolean` | `false` | Show the bubble open, in place beside its trigger: no portal, no listeners. For docs and thumbnails. |

## Props: Toggletip

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` |  | The (i) button's accessible name: "Why we ask for a billing address". |
| `title` | `ReactNode` |  |  |
| `children` (required) | `ReactNode` |  |  |
| `footer` | `ReactNode` |  | May hold a link: a toggletip is interactive, a tooltip is not. |
| `side` | `TooltipSide` | `"top"` |  |
| `maxWidth` | `number` | `300` |  |
| `icon` | `ReactNode` |  |  |
| `className` | `string` |  |  |
| `inline` | `boolean` | `false` | Show the panel open, in place beside the button: no portal, no listeners. For docs and thumbnails. |

## Examples

### Open

inline shows the bubble and the toggletip panel open beside their triggers, in place.

```tsx
<Tooltip inline content="Print invoice" shortcut={["Ctrl", "P"]}>…</Tooltip>
<Toggletip inline label="About seats" title="Seats">Each plan includes five seats.</Toggletip>
```

### Tooltip and toggletip

```tsx
<Tooltip content="Copy reference" shortcut={["Ctrl", "C"]}>…</Tooltip>
<Toggletip label="About seats">Each plan includes five seats.</Toggletip>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--arrow` | `50%` |
| `--r-flat` | `2px` |
| `--tooltip-bg` | `var(--brand-deep)` |
| `--tooltip-radius` | `var(--r-sm)` |

System tokens it reads: `--border-w`, `--brand-deep`, `--density`, `--dur`, `--dur-fast`, `--ease`, `--ease-out`, `--focus-color`, `--focus-ring`, `--font-body`, `--font-mono`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-heading`, `--ink-inverse`, `--ink-muted`, `--ink-secondary`, `--line`, `--line-brand`, `--line-input`, `--r-2xs`, `--r-full`, `--r-md`, `--r-sm`, `--r-xs`, `--rgb-contact`, `--rgb-white`, `--shadow-float`, `--shadow-menu`, `--shadow-specular-dark`, `--surface-solid`, `--surface-sunken`, `--text-caption`, `--text-micro`, `--wash-active`, `--wash-hover`, `--wash-strong`, `--z-tooltip`.

## Accessibility

- Tooltip content is the trigger's description (aria-describedby), shown on focus too, dismissed with Esc.
- Toggletip content is announced through a live region when opened.

## Do

- Keep tooltips to a few words.

## Don't

- Don't put interactive content in a Tooltip; use a Toggletip.

---

# Modal

> A frosted dialog with a focus trap, scroll lock, inert page, scroll-aware edges and a bottom sheet on phones.

Category: Overlays. Docs page: https://rime.mjsons.net/components/modal

## Installation

```bash
npx shadcn@latest add KezLahd/rime/modal
```

Modal portals a dialog over a deep scrim: focus moves in (to initialFocus, the first field, or the first button), Tab is trapped, Esc and a scrim click close it unless dismissible is false or busy is set, the page behind goes inert, and focus returns to whatever opened it.

Everything in the header sits on one left edge: the tone's icon tile and the close button on one row, then the title and description full width beneath; nothing is stacked over the title. tone tints the header wash and the tile (danger, success, info); progress draws a segmented step rule for multi-step flows.

The body scrolls on its own. Its scroll edges are the portable pattern from components/ui/Scroll: a hairline and soft shade under the header once content has scrolled (data-scrolled) and over the footer while there is more below (data-more), written straight to the DOM by useScrollEdges with a passive listener, plus thin tinted scrollbars and contained overscroll. Under 640px every size becomes a bottom sheet (or the full screen with mobile="fullscreen").

Widths are tokens: --modal-width-sm 480px, -md 640px, -lg 880px. meta puts a quiet line under the title (a reference, "Step 1 of 2"); nothing is stacked over the title. inline renders the open panel in place, with no portal, scrim, focus trap or scroll lock, for docs and design reviews.

## Usage

```tsx
import { Button, Modal } from "@/components/ui";

<Modal
  open={open}
  onClose={() => setOpen(false)}
  title="Contact support"
  description="Ask a question about invoice INV-1042."
  footer={
    <>
      <Button variant="secondary" onClick={() => setOpen(false)}>Cancel</Button>
      <Button onClick={send}>Send question</Button>
    </>
  }
>
  …form fields…
</Modal>
```

## Props: Modal

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` (required) | `boolean` |  |  |
| `onClose` (required) | `() => void` |  | Called on Esc, scrim click and the close button, unless dismissible is false. |
| `title` (required) | `ReactNode` |  |  |
| `meta` | `ReactNode` |  | A quiet line under the title: a reference, "Step 1 of 2". Never stacked over the title. |
| `description` | `ReactNode` |  |  |
| `children` | `ReactNode` |  |  |
| `inline` | `boolean` |  | Render the open panel in place, in normal flow: no portal, no scrim, no inert page, no scroll lock, no focus trap and no exit animation. For docs, thumbnails and design reviews, where many can render at once. |
| `footer` | `ReactNode` |  | Buttons, right-aligned. Primary last, and one gradient primary at most. |
| `footerStart` | `ReactNode` |  | Left side of the footer: a line of secondary text, a link, a Back button. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | sm 480, md 640, lg 880 (--modal-width-*). Under 640px every size becomes a bottom sheet. |
| `mobile` | `"sheet" \| "fullscreen"` | `"sheet"` | Under 640px: a bottom sheet (default) or the full screen, for long forms. |
| `tone` | `ModalTone` | `"default"` | Tints the header wash and the icon tile. danger, success and info bring their own icon; pass icon={false} to drop it. |
| `icon` | `ReactNode` |  |  |
| `progress` | `{ step: number; of: number }` |  | A multi-step flow: draws the segmented step rule under the heading. |
| `onScrollEnd` | `() => void` |  | Called when the body has been scrolled to its end (and at once if it does not overflow). Gate a terms "Accept" on it: see the scroll-gated accept example. |
| `dismissible` | `boolean` | `true` | false while a request is in flight: Esc, scrim and close are ignored. |
| `busy` | `boolean` | `false` | A request is in flight: sets aria-busy and locks dismissal. |
| `initialFocus` | `RefObject<HTMLElement \| null>` |  | Focused on open. Defaults to the first field or button in the body. |
| `closeLabel` | `string` | `"Close"` |  |
| `className` | `string` |  |  |

## Props: ConfirmModal

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` (required) | `boolean` |  |  |
| `onClose` (required) | `() => void` |  |  |
| `title` (required) | `ReactNode` |  |  |
| `meta` | `string` |  | A quiet line under the title; two-step flows prefix it with "Step 1 of 2". |
| `description` | `ReactNode` |  |  |
| `inline` | `boolean` |  | Render the open dialog in place (see Modal's inline). |
| `children` | `ReactNode` |  | Step one: the details or form (e.g. withdrawal reason). |
| `review` | `ReactNode` |  | Step two: what will happen, stated plainly. When given, the first button reads proceedLabel and leads here; the destructive button is only on this step. Omit for a single-step confirm. |
| `reviewTitle` | `ReactNode` |  |  |
| `reviewDescription` | `ReactNode` |  | Replaces description on step two. Omitted: step two has none. |
| `proceedLabel` | `string` | `"Continue"` |  |
| `confirmLabel` (required) | `string` |  |  |
| `cancelLabel` | `string` | `"Cancel"` |  |
| `tone` | `ModalTone` | `"default"` |  |
| `icon` | `ReactNode` |  | Overrides the tone's icon tile; false drops it. |
| `onProceed` | `() => boolean` |  | Return false to stay on step one (failed validation). |
| `onConfirm` (required) | `() => void` |  |  |
| `busy` | `boolean` |  | The confirm request is in flight. Locks the dialog. |
| `busyLabel` | `string` |  |  |
| `size` | `ModalProps["size"]` | `"md"` |  |
| `mobile` | `ModalProps["mobile"]` |  |  |

## Examples

### Open

inline renders the panel in place: no portal, scrim, focus trap or scroll lock. For docs and reviews.

```tsx
<Modal inline open onClose={close} title="Contact support" meta="Invoice INV-1042" description="Ask a question about this invoice." footer={…}>
  <Field label="Your question"><TextInput /></Field>
</Modal>
```

### Form in a modal

```tsx
<Modal open={open} onClose={close} title="Contact support" footerStart="Recorded on the activity log." footer={…}>
  <Field label="What is it about?" required><Select … /></Field>
</Modal>
```

### Long content: scroll edges

Scroll the body: the header shade appears once content passes under it, and the footer shade shows while there is more.

```tsx
<Modal open={open} onClose={close} size="lg" title="Workspace terms" footer={<Button onClick={close}>I agree</Button>}>
  {terms}
</Modal>
```

### Terms with a scroll-gated accept

Accept stays disabled until the body has been scrolled to the end. onScrollEnd comes from useScrollEdges, the same listener that clears data-more when nothing is left below. Open it and scroll.

```tsx
const [read, setRead] = useState(false);
const onEnd = useCallback(() => setRead(true), []);

<Modal
  open={open}
  onClose={close}
  size="lg"
  title="Workspace terms"
  onScrollEnd={onEnd}
  footerStart={read ? <span role="status">You have reached the end</span> : <span role="status" id="terms-hint">Scroll to the end to accept</span>}
  footer={<Button disabled={!read} aria-describedby={read ? undefined : "terms-hint"} onClick={accept}>Accept terms</Button>}
>
  {terms}
</Modal>
```

### ConfirmModal, danger, two steps

The irreversible button only appears on the review step, so a stray Enter cannot confirm.

```tsx
<ConfirmModal
  open={open}
  onClose={close}
  tone="danger"
  title="Delete Atlas redesign"
  review={<p>Files are removed from the shared drive immediately.</p>}
  proceedLabel="Review deletion"
  confirmLabel="Delete project"
  onConfirm={remove}
  busy={pending}
>
  …reason fields…
</ConfirmModal>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--modal-inline-width` | `520px` |
| `--modal-inline-width-lg` | `640px` |
| `--modal-pad-x` | `calc(24px * var(--density))` |
| `--modal-radius` | `var(--r-xl)` |
| `--modal-radius-lg` | `var(--r-2xl)` |
| `--modal-width-lg` | `880px` |
| `--modal-width-md` | `640px` |
| `--modal-width-sm` | `480px` |

System tokens it reads: `--brand-gradient`, `--danger-gradient`, `--danger-ink`, `--density`, `--dur-slow`, `--ease`, `--ease-out`, `--focus-color`, `--font-display`, `--info-ink`, `--ink-body`, `--ink-brand`, `--ink-heading`, `--ink-muted`, `--ink-secondary`, `--modal-blur`, `--modal-scrim`, `--modal-scrim-blur`, `--modal-shadow`, `--modal-surface`, `--modal-wash-opacity`, `--r-2xl`, `--r-full`, `--r-md`, `--r-xl`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-brand-soft`, `--rgb-danger`, `--scroll-edge-bottom`, `--scroll-edge-left`, `--scroll-edge-right`, `--scroll-edge-top`, `--scrollbar-thumb`, `--scrollbar-track`, `--scrollbar-width`, `--shadow-specular`, `--success-gradient`, `--success-ink`, `--success-solid`, `--text-body`, `--text-caption`, `--text-small`, `--tracking-display`, `--z-modal`.

## Accessibility

- role="dialog" ("alertdialog" for tone="danger") with aria-modal, aria-labelledby on the title and aria-describedby on the description.
- Focus trap with Tab and Shift+Tab, Esc to close, focus returned to the opener; the background is inert, except live regions (toasts) so failures are still announced.
- busy locks dismissal and sets aria-busy while a request is in flight.
- Reduced motion: everything fades in place; nothing travels or scales.

## Do

- Keep one primary action, last in the footer.
- Use ConfirmModal for any irreversible action; TypeToConfirmModal when the blast radius is large.
- Use footerStart for a line of context or a Back button.

## Don't

- Don't stack modals unless the second is a confirm of the first.
- Don't put a coloured side bar or a filled header on a modal; tone is a soft wash only.
- Don't open a modal on page load.

Related: https://rime.mjsons.net/components/button, https://rime.mjsons.net/components/scroll-area, https://rime.mjsons.net/components/type-to-confirm

---

# TypeToConfirmModal and DangerZone

> The heaviest confirm: an impact preview and a typed phrase; and the Danger zone section that leads to it.

Category: Overlays. Docs page: https://rime.mjsons.net/components/type-to-confirm

## Installation

```bash
npx shadcn@latest add KezLahd/rime/type-to-confirm
```

TypeToConfirmModal shows what will change (ImpactPreview), asks for a typed phrase (copyable, case-insensitive by default) and runs an async onConfirm, showing an error in place if it fails.

DangerZone is the section at the foot of a settings or record page that holds destructive actions, one DangerZoneRow each, each opening its confirm.

## Usage

```tsx
import { DangerZone, DangerZoneRow, TypeToConfirmModal } from "@/components/ui";

<DangerZone>
  <DangerZoneRow title="Remove team member" actionLabel="Remove team member" confirm={{ title: "Remove Jane Cooper?", phrase: "remove jane cooper", confirmLabel: "Remove team member", onConfirm: remove, impact: ITEMS }} />
</DangerZone>
```

## Props: TypeToConfirmModal

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` (required) | `boolean` |  |  |
| `onClose` (required) | `() => void` |  | Cancel, Esc, scrim, the close button, and a confirm that went through. |
| `title` (required) | `ReactNode` |  |  |
| `meta` | `ReactNode` |  | A quiet line under the title: the record's name or reference. |
| `description` | `ReactNode` |  |  |
| `inline` | `boolean` |  | Render the open dialog in place (see Modal's inline). |
| `impact` | `ImpactItem[] \| ImpactPreviewProps` |  | What the action does, one row per consequence, in the impact panel above the phrase. Pass the rows, or the full ImpactPreview props for a preview that loads from the server (loading, error, onRetry). |
| `consequences` | `ReactNode` |  | Prose consequences. Still supported: shown as plain text inside the impact panel, above any rows. Prefer `impact` for new dialogs. |
| `consequencesTitle` | `ReactNode` | `"This action cannot be undone"` | The compact danger line heading the impact panel. |
| `phrase` (required) | `string` |  | What the user types to arm the button. Keep it specific to the thing being destroyed ("delete atlas redesign"), so muscle memory can't confirm the wrong record. Shown verbatim; lower-case reads best. |
| `caseSensitive` | `boolean` | `false` | Default false: "Jane Cooper" matches "jane cooper". |
| `children` | `ReactNode` |  | Extra required fields (a training date). Rendered between the impact panel and the phrase. |
| `canConfirm` | `boolean` | `true` | Validity of the children. The button arms only when this and the phrase both hold. |
| `confirmLabel` (required) | `string` |  |  |
| `cancelLabel` | `string` | `"Cancel"` |  |
| `busyLabel` | `string` |  | Replaces the confirm label while onConfirm is in flight, e.g. "Deleting…". |
| `onConfirm` (required) | `() => void \| Promise<unknown>` |  | The irreversible request. While a returned promise is pending the dialog is locked (no Esc, scrim, close or Cancel). When it resolves the dialog closes through onClose; when it rejects the dialog stays open and unlocked, the typed phrase kept, and an error toast says so. |
| `errorTitle` | `ReactNode` | `"That didn't go through"` | Title of the failure toast. The description always says nothing changed. |
| `size` | `ModalProps["size"]` | `"md"` |  |
| `mobile` | `ModalProps["mobile"]` |  |  |

## Props: DangerZone

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` | `"Danger zone"` | Default "Danger zone". |
| `description` | `ReactNode` |  | One line under the title: whose data this is, who can see it. |
| `headingLevel` | `2 \| 3 \| 4` | `2` | 2 on a settings page, 3 inside a titled section. |
| `children` | `ReactNode` |  | DangerZoneRow elements. The zone renders nothing without any. |
| `className` | `string` |  |  |

## Props: DangerZoneRow

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `ReactNode` |  |  |
| `description` | `ReactNode` |  | What it does and what it takes with it. The button names the action; this explains it. |
| `actionLabel` (required) | `string` |  | A full verb phrase: "Deactivate team member", not "Deactivate". |
| `confirm` | `Omit<TypeToConfirmModalProps, "open" \| "onClose">` |  | The row owns a TypeToConfirmModal with these props and opens it from the button. It closes when onConfirm resolves. For a confirm whose extra fields the page holds in state, use onAction and render the modal there. |
| `onAction` | `() => void` |  | Called instead of opening the built-in confirm. |
| `disabled` | `boolean` |  |  |
| `disabledReason` | `ReactNode` |  | Shown in the row while disabled: why, and what would enable it. |

## Examples

### Open

The confirm itself, rendered in place with inline.

```tsx
<TypeToConfirmModal inline open onClose={close} title="Remove Jane Cooper?" meta="Team member · Design" phrase="remove jane cooper" confirmLabel="Remove team member" impact={ITEMS} onConfirm={remove} />
```

### Danger zone

```tsx
<DangerZone>…</DangerZone>
```

## Theme tokens

System tokens it reads: `--danger-fill`, `--danger-ink`, `--danger-line`, `--ease-out`, `--font-body`, `--font-mono`, `--ink-body`, `--ink-heading`, `--ink-muted`, `--ink-secondary`, `--line`, `--line-soft`, `--r-xl`, `--shadow-input`, `--success-fill`, `--success-ink`, `--success-solid`, `--surface-solid`, `--text-body`, `--text-caption`, `--text-card-title`, `--text-small`, `--wash-active`.

## Accessibility

- The confirm button stays disabled until the phrase matches; progress toward the phrase is announced through a polite status region.

## Do

- Make the phrase name the thing being destroyed.

## Don't

- Don't use it for everyday deletes; ConfirmModal is enough.

---

# Popover

> An anchored frosted panel for arbitrary content: a short form, a set of options, a details block.

Category: Overlays. Docs page: https://rime.mjsons.net/components/popover

## Installation

```bash
npx shadcn@latest add KezLahd/rime/popover
```

Popover opens a panel against its trigger, in the same frosted glass as Select and Menu. The trigger is any button you pass; Popover adds aria-expanded, aria-controls and the click handler. It flips above when there is no room below and follows scroll and resize.

Focus moves to the first focusable element inside (or the panel) but is not trapped. Esc closes it and returns focus to the trigger; a press outside closes it too. Open state is uncontrolled by default, or controlled with open and onOpenChange.

inline renders the open panel in the page flow: no portal, scrim, focus trap, scroll lock or outside-click listener. It exists for docs, previews and static mock-ups; never ship it as the live overlay.

## Usage

```tsx
import { Button, Popover } from "@/components/ui";

<Popover label="Canvas dimensions" trigger={<Button variant="secondary">Dimensions</Button>}>
  …fields…
</Popover>
```

## Props: Popover

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `trigger` (required) | `ReactElement<TriggerProps>` |  | The button that opens it. Gets aria-expanded, aria-controls and the click handler. |
| `children` (required) | `ReactNode` |  | The panel's content: a short form, a set of filters, a details block. |
| `label` | `string` |  | The panel's accessible name ("Edit dimensions"). Use it when the content has no heading. |
| `open` | `boolean` |  | Controlled open state. Leave unset for uncontrolled. |
| `defaultOpen` | `boolean` |  |  |
| `onOpenChange` | `(open: boolean) => void` |  |  |
| `side` | `FloatSide` | `"bottom"` | Preferred side; flips when there is no room. |
| `align` | `FloatAlign` | `"start"` |  |
| `width` | `number` |  | Panel width in px. Defaults to the content's width (min 220px). |
| `inline` | `boolean` |  | Render the open panel in the page flow under the trigger: not portalled, no outside-click or Esc handling. For docs, previews and static mock-ups. |
| `className` | `string` |  |  |

## Examples

### Open

The panel under its trigger, drawn inline.

```tsx
<Popover inline label="Canvas dimensions" width={260} trigger={<Button variant="secondary">Dimensions</Button>}>
  <Field label="Width"><TextInput size="sm" defaultValue="1280" trailing="px" /></Field>
  <Field label="Height"><TextInput size="sm" defaultValue="720" trailing="px" /></Field>
</Popover>
```

### From its trigger

Press the button. Esc or a press outside closes it.

```tsx
<Popover label="Canvas dimensions" width={260} trigger={<Button variant="secondary">Dimensions</Button>}>
  …
</Popover>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--popover-content-pad` | `calc(16px * var(--density))` |
| `--popover-max-width` | `380px` |
| `--popover-min-width` | `220px` |
| `--popover-radius` | `var(--r-lg)` |

System tokens it reads: `--border-w`, `--density`, `--dur`, `--dur-slow`, `--ease-out`, `--focus-ring`, `--ink-body`, `--popover-blur`, `--popover-border`, `--popover-shadow`, `--popover-surface`, `--r-lg`, `--text-small`, `--z-popover`.

## Accessibility

- The panel is role="dialog" named by label (or by a heading you give it); the trigger carries aria-expanded and aria-controls.
- Focus moves into the panel on open and back to the trigger on Esc. It is non-modal: Tab can leave it.
- Do not put the only route to an action in a popover that opens on hover; Popover opens on press only.

## Do

- Keep it to one small task: a few fields, a choice, a summary.
- Give it a label when the content has no heading.

## Don't

- Don't use it for a list of actions; that is Menu.
- Don't put a long form in it; use Sheet or Modal.

Related: https://rime.mjsons.net/components/hover-card, https://rime.mjsons.net/components/menu, https://rime.mjsons.net/components/tooltip

---

# HoverCard

> A rich preview on hover or keyboard focus of a link: a person, a project, a record.

Category: Overlays. Docs page: https://rime.mjsons.net/components/hover-card

## Installation

```bash
npx shadcn@latest add KezLahd/rime/hover-card
```

HoverCard opens after a short delay (openDelay, 500ms) when the pointer rests on its trigger or the trigger takes keyboard focus, and closes a little after the pointer leaves (closeDelay, 200ms), so the pointer can travel onto the card. Touch never opens it: the trigger must work on its own.

The card is supplementary. It is tied to the trigger with aria-describedby while open and Esc dismisses it.

inline renders the open panel in the page flow: no portal, scrim, focus trap, scroll lock or outside-click listener. It exists for docs, previews and static mock-ups; never ship it as the live overlay.

## Usage

```tsx
import { HoverCard } from "@/components/ui";

<HoverCard trigger={<a href="/team/jane-cooper">@janecooper</a>}>
  …profile…
</HoverCard>
```

## Props: HoverCard

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `trigger` (required) | `ReactElement<TriggerProps>` |  | A link or button the card previews: a person's name, a project, a reference. |
| `children` (required) | `ReactNode` |  | The preview: a few lines of supporting detail. Never the only route to an action. |
| `openDelay` | `number` | `500` | ms of hover or focus before it opens. |
| `closeDelay` | `number` | `200` | ms after the pointer leaves before it closes, so it can travel onto the card. |
| `side` | `FloatSide` | `"bottom"` |  |
| `align` | `FloatAlign` | `"start"` |  |
| `width` | `number` | `300` | Panel width in px. |
| `inline` | `boolean` |  | Render the card open in the page flow under the trigger (docs, previews). |
| `className` | `string` |  |  |

## Examples

### Open

```tsx
<HoverCard inline trigger={<a href="/team/jane-cooper">@janecooper</a>}>
  <Avatar name="Jane Cooper" />
  <strong>Jane Cooper</strong>
  <span>Design lead on Project Atlas.</span>
</HoverCard>
```

### On hover and focus

Hover the name, or Tab to it.

```tsx
<p>Assigned to <HoverCard trigger={<a href="/team/jane-cooper">@janecooper</a>}>…</HoverCard> for review.</p>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--hover-card-pad` | `calc(16px * var(--density))` |
| `--hover-card-radius` | `var(--r-lg)` |

System tokens it reads: `--border-w`, `--density`, `--dur`, `--dur-slow`, `--ease-out`, `--ink-body`, `--popover-blur`, `--popover-border`, `--popover-shadow`, `--popover-surface`, `--r-lg`, `--text-small`, `--z-popover`.

## Accessibility

- Opens on keyboard focus as well as hover, and the card describes its trigger (aria-describedby).
- Esc closes it. Nothing inside it should be the only way to reach an action.
- Respects reduced motion: it fades in place.

## Do

- Use it on links whose target needs a glance before a click: people, projects, references.

## Don't

- Don't put buttons or forms in a hover card; use Popover.
- Don't use it on touch-first screens as the only way to see the detail.

Related: https://rime.mjsons.net/components/popover, https://rime.mjsons.net/components/tooltip, https://rime.mjsons.net/components/avatar

---

# ContextMenu

> A menu of actions for a region, opened at the pointer with a right-click, Shift+F10 or a long press.

Category: Overlays. Docs page: https://rime.mjsons.net/components/context-menu

## Installation

```bash
npx shadcn@latest add KezLahd/rime/context-menu
```

ContextMenu wraps a region (a row, a card, a file) and opens the shared menu list where the pointer is. The region is focusable, so keyboard users open it with Shift+F10 or the Menu key; on touch a long press (longPressMs, 500ms) opens it.

Items take an icon, a shortcut hint (display only), a danger tone and a disabled state; separators and headings group them. It is the same popover glass and item rhythm as Menu.

inline renders the open panel in the page flow: no portal, scrim, focus trap, scroll lock or outside-click listener. It exists for docs, previews and static mock-ups; never ship it as the live overlay.

## Usage

```tsx
import { ContextMenu } from "@/components/ui";

<ContextMenu label="Actions for Invoice INV-0042" items={[
  { id: "open", label: "Open", onSelect: open },
  { id: "rename", label: "Rename", shortcut: "F2", onSelect: rename },
  { id: "sep", separator: true },
  { id: "delete", label: "Move to bin", tone: "danger", onSelect: remove },
]}>
  Invoice INV-0042.pdf
</ContextMenu>
```

## Props: ContextMenu

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | The region that answers a right-click: a row, a card, a canvas. |
| `items` (required) | `ReadonlyArray<MenuListEntry>` |  | The menu: actions, separators ({ id, separator: true }) and headings ({ id, heading }). |
| `label` (required) | `string` |  | The menu's accessible name, e.g. "Actions for Invoice INV-0042". |
| `longPressMs` | `number` | `500` | ms a touch must be held to open it on phones and tablets. |
| `inline` | `boolean` |  | Render the menu open in the page flow, over the region (docs, previews). Nothing is interactive and no listeners are attached. |
| `highlightId` | `string` |  | Inline only: the item drawn in its hover state. |
| `className` | `string` |  |  |

## Examples

### Open

The menu over its region, drawn inline with one item highlighted.

```tsx
<ContextMenu inline label="Actions for Invoice INV-0042" items={ITEMS} highlightId="rename">
  Invoice INV-0042.pdf
</ContextMenu>
```

### On a region

Right-click it, or focus it and press Shift F10.

```tsx
<ContextMenu label="Actions for Invoice INV-0042" items={ITEMS}>…</ContextMenu>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--context-region-height` | `150px` |
| `--context-region-radius` | `var(--r-lg)` |
| `--context-region-width` | `300px` |
| `--menu-list-min-width` | `220px` |
| `--popover-item-active-bg` | `linear-gradient(to right, rgba(var(--rgb-brand), 0.14), rgba(var(--rgb-brand-deep), 0.07))` |
| `--popover-item-press-bg` | `linear-gradient(to right, rgba(var(--rgb-brand), 0.2), rgba(var(--rgb-brand-deep), 0.1))` |
| `--popover-item-radius` | `var(--r-xs)` |
| `--popover-pad` | `calc(6px * var(--density))` |
| `--popover-radius` | `var(--r-lg)` |

System tokens it reads: `--border-w`, `--danger-ink`, `--density`, `--dur`, `--dur-fast`, `--dur-slow`, `--ease`, `--ease-out`, `--focus-ring`, `--font-body`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-muted`, `--line-input`, `--line-soft`, `--popover-blur`, `--popover-border`, `--popover-shadow`, `--popover-surface`, `--r-lg`, `--r-xs`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-danger`, `--rgb-white`, `--text-caption`, `--text-micro`, `--text-small`, `--tracking-label`, `--wash-subtle`, `--z-popover`.

## Accessibility

- The menu is role="menu" with role="menuitem" items: arrows, Home, End and typeahead move; Enter or Space runs; Esc closes and returns focus to the region; Tab closes.
- The region is focusable and opens on Shift+F10 and the Menu key, so a mouse is never required.
- Every action in a context menu must also be reachable some other way (a row Menu, a toolbar).

## Do

- Put destructive items last, after a separator.
- Keep it to the actions for that one thing.

## Don't

- Don't make it the only route to an action.
- Don't override the browser's menu on text people need to copy.

Related: https://rime.mjsons.net/components/menu, https://rime.mjsons.net/components/menubar

---

# Sheet and Drawer

> A panel that slides in from an edge over a scrim, and a bottom Drawer with a drag handle.

Category: Overlays. Docs page: https://rime.mjsons.net/components/sheet

## Installation

```bash
npx shadcn@latest add KezLahd/rime/sheet
```

Sheet is a dialog flush to one edge (side: right, left, top or bottom) for secondary tasks that keep the page in view: a record's details, filters, settings. It traps focus, locks page scroll, closes on Esc, the scrim and the close button, and returns focus to whatever opened it.

Drawer is the bottom sheet, centred to a readable width on wide screens, with a grab handle. With dragToClose (on by default) a downward drag on the handle past about a third of its height dismisses it.

The header keeps one left edge: title and description stacked flush left, the close button at the right. The body scrolls on its own with the themed scrollbar; footer buttons sit along the bottom edge, primary last. Size is size (any CSS length) or --sheet-size.

inline renders the open panel in the page flow: no portal, scrim, focus trap, scroll lock or outside-click listener. It exists for docs, previews and static mock-ups; never ship it as the live overlay.

## Usage

```tsx
import { Button, Drawer, Sheet } from "@/components/ui";

<Sheet
  open={open}
  onClose={() => setOpen(false)}
  title="Edit team member"
  footer={<Button onClick={save}>Save changes</Button>}
>
  …fields…
</Sheet>
```

## Props: Sheet

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` (required) | `boolean` |  |  |
| `onClose` (required) | `() => void` |  | Esc, the scrim and the close button. |
| `title` (required) | `ReactNode` |  |  |
| `description` | `ReactNode` |  |  |
| `children` | `ReactNode` |  |  |
| `footer` | `ReactNode` |  | Buttons along the bottom edge, primary last. |
| `side` | `SheetSide` | `"right"` | The edge it slides in from. |
| `size` | `string` |  | Width (left, right) or height (top, bottom), any CSS length. Defaults to --sheet-size, 420px. |
| `closeLabel` | `string` | `"Close"` |  |
| `inline` | `boolean` |  | Render the open panel in the page flow: no portal, scrim, focus trap or scroll lock (docs, previews). |
| `className` | `string` |  |  |

## Props: Drawer

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `footer` | `ReactNode` |  | Buttons along the bottom edge, primary last. |
| `title` (required) | `ReactNode` |  |  |
| `className` | `string` |  |  |
| `children` | `ReactNode` |  |  |
| `open` (required) | `boolean` |  |  |
| `onClose` (required) | `() => void` |  | Esc, the scrim and the close button. |
| `description` | `ReactNode` |  |  |
| `closeLabel` | `string` |  |  |
| `inline` | `boolean` |  | Render the open panel in the page flow: no portal, scrim, focus trap or scroll lock (docs, previews). |
| `dragToClose` | `boolean` | `true` | Let a downward drag on the handle dismiss it. On by default. |

## Examples

### Open

The panel itself, drawn inline.

```tsx
<Sheet inline open onClose={close} title="Edit team member" description="Changes apply as soon as you save." footer={…}>
  …fields…
</Sheet>
```

### From each edge

```tsx
<Sheet open={open} side="left" onClose={close} title="Filters">…</Sheet>
```

### Drawer, open

```tsx
<Drawer inline open onClose={close} title="Order ORD-2041" footer={<Button>Mark as shipped</Button>}>…</Drawer>
```

### Drawer with drag to close

Drag the handle down to dismiss.

```tsx
<Drawer open={open} onClose={() => setOpen(false)} title="Order ORD-2041">…</Drawer>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--drawer-width` | `640px` |
| `--sheet-radius` | `var(--r-xl)` |
| `--sheet-size` | `420px` / `85dvh` / `380px` |
| `--sheet-title-size` | `18px` |

System tokens it reads: `--border-w`, `--density`, `--dur`, `--ease`, `--ease-out`, `--font-display`, `--ink-body`, `--ink-heading`, `--ink-secondary`, `--line-glass`, `--modal-blur`, `--modal-scrim`, `--modal-scrim-blur`, `--modal-shadow`, `--modal-surface`, `--r-full`, `--r-xl`, `--rgb-brand-deep`, `--text-small`, `--tracking-display`, `--z-modal`.

## Accessibility

- role="dialog" with aria-modal, labelled by the title and described by the description.
- Focus moves in on open, Tab is trapped, Esc closes, and focus returns to the opener. The drag handle is pointer-only; Esc and the close button are always there.
- Reduced motion: it fades in place instead of sliding.

## Do

- Use a right sheet for detail and edit panels, a bottom drawer on phones.
- Keep one primary action in the footer.

## Don't

- Don't stack a sheet on a modal.
- Don't hide navigation in a sheet on desktop; that is the sidebar.

Related: https://rime.mjsons.net/components/modal, https://rime.mjsons.net/components/alert-dialog

---

# AlertDialog

> A short interrupting confirm with Cancel and one action; focus starts on Cancel and the scrim never dismisses it.

Category: Overlays. Docs page: https://rime.mjsons.net/components/alert-dialog

## Installation

```bash
npx shadcn@latest add KezLahd/rime/alert-dialog
```

AlertDialog asks one question with two answers. It is role="alertdialog": focus starts on Cancel, so a stray Enter never confirms; Esc cancels; Tab is trapped; a click on the scrim does nothing, because the choice must be made.

tone="danger" draws a warning tile and the danger button. busy locks both buttons and shows a spinner on the action while it runs. The header keeps one left edge. It wears the --modal-* glass, so it matches Modal in every preset.

inline renders the open panel in the page flow: no portal, scrim, focus trap, scroll lock or outside-click listener. It exists for docs, previews and static mock-ups; never ship it as the live overlay.

## Usage

```tsx
import { AlertDialog } from "@/components/ui";

<AlertDialog
  open={open}
  tone="danger"
  title="Delete Project Atlas?"
  description="Its 12 tasks and 48 files are deleted with it."
  actionLabel="Delete project"
  onCancel={() => setOpen(false)}
  onAction={remove}
  busy={pending}
/>
```

## Props: AlertDialog

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` (required) | `boolean` |  |  |
| `onCancel` (required) | `() => void` |  | Cancel, Esc. There is no scrim click: the choice must be made. |
| `onAction` (required) | `() => void` |  | The action button. Close the dialog yourself once it has run. |
| `title` (required) | `ReactNode` |  |  |
| `description` | `ReactNode` |  |  |
| `actionLabel` (required) | `string` |  | A verb plus the object: "Delete project", never "OK". |
| `cancelLabel` | `string` |  |  |
| `tone` | `"default" \| "danger"` |  | danger draws the action in the danger fill and a warning tile. |
| `busy` | `boolean` |  | The action is in flight: both buttons lock and the action shows a spinner. |
| `busyLabel` | `string` |  |  |
| `children` | `ReactNode` |  | Extra content under the description: a short list of what changes. |
| `inline` | `boolean` |  | Render the open panel in the page flow: no portal, scrim, focus trap or scroll lock (docs, previews). |
| `className` | `string` |  |  |

## Examples

### Open

```tsx
<AlertDialog inline open tone="danger" title="Delete Project Atlas?" description="…" actionLabel="Delete project" onCancel={…} onAction={…} />
```

### Danger, with a busy state

```tsx
<AlertDialog open={open} tone="danger" … busy={pending} busyLabel="Deleting…" />
```

### Default tone

```tsx
<AlertDialog open={open} title="Discard this draft?" actionLabel="Discard draft" cancelLabel="Keep editing" … />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--alert-dialog-radius` | `var(--r-xl)` |
| `--alert-dialog-title-size` | `18px` |
| `--alert-dialog-width` | `440px` |

System tokens it reads: `--danger-fill`, `--danger-ink`, `--danger-line`, `--density`, `--dur`, `--dur-slow`, `--ease`, `--ease-out`, `--font-display`, `--ink-body`, `--ink-heading`, `--ink-secondary`, `--modal-blur`, `--modal-scrim`, `--modal-scrim-blur`, `--modal-shadow`, `--modal-surface`, `--r-md`, `--r-xl`, `--text-body`, `--text-small`, `--tracking-display`, `--z-modal`.

## Accessibility

- role="alertdialog" with aria-modal, labelled by the title and described by the description, so both are read on open.
- Initial focus is Cancel. Esc cancels; the scrim does not.
- busy sets aria-busy and disables both buttons until the action settles.

## Do

- Name the action with a verb and the object: "Delete project".
- Say in the description what is lost.

## Don't

- Don't use it for forms; that is Modal.
- Don't use it for very large irreversible changes; that is TypeToConfirmModal.
- Never label the action "OK" or "Yes".

Related: https://rime.mjsons.net/components/modal, https://rime.mjsons.net/components/type-to-confirm

---

# Command

> A command palette: a search box over grouped actions with shortcuts, keyboard-first, inline or as a Ctrl+K dialog.

Category: Overlays. Docs page: https://rime.mjsons.net/components/command

## Installation

```bash
npx shadcn@latest add KezLahd/rime/command
```

Command is a combobox over a grouped listbox. Typing filters every group (every word must appear in the label or the item's keywords), Up and Down move the highlight, Enter runs it, and an empty state says when nothing matches. Focus stays in the input throughout; the highlighted option is announced through aria-activedescendant.

CommandDialog lifts it over the page in the modal glass and toggles it with Ctrl+K or Cmd+K (shortcut, on by default). Running a command closes it; Esc and the scrim close it too, and focus returns to where it was.

inline renders the open panel in the page flow: no portal, scrim, focus trap, scroll lock or outside-click listener. It exists for docs, previews and static mock-ups; never ship it as the live overlay.

## Usage

```tsx
import { Command, CommandDialog } from "@/components/ui";

<CommandDialog
  open={open}
  onOpenChange={setOpen}
  groups={[
    { heading: "Suggestions", items: [{ id: "invoice", label: "Create invoice", shortcut: "Ctrl N", onSelect: create }] },
    { heading: "Go to", items: [{ id: "orders", label: "Orders", onSelect: () => router.push("/orders") }] },
  ]}
/>
```

## Props: Command

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `groups` (required) | `ReadonlyArray<CommandGroup>` |  |  |
| `label` | `string` | `"Search commands"` | The input's accessible name. |
| `placeholder` | `string` | `"Type a command or search…"` |  |
| `emptyText` | `ReactNode` | `"No results found."` | Shown when nothing matches. |
| `onSelect` | `(item: CommandItem) => void` |  | Called with the item after its own onSelect runs. |
| `query` | `string` |  | Controlled query. Leave unset for uncontrolled. |
| `onQueryChange` | `(q: string) => void` |  |  |
| `autoFocus` | `boolean` |  | Focus the input on mount. |
| `className` | `string` |  |  |

## Props: CommandDialog

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` |  | The input's accessible name. |
| `className` | `string` |  |  |
| `onSelect` | `(item: CommandItem) => void` |  | Called with the item after its own onSelect runs. |
| `placeholder` | `string` |  |  |
| `groups` (required) | `ReadonlyArray<CommandGroup>` |  |  |
| `emptyText` | `ReactNode` |  | Shown when nothing matches. |
| `query` | `string` |  | Controlled query. Leave unset for uncontrolled. |
| `onQueryChange` | `(q: string) => void` |  |  |
| `open` (required) | `boolean` |  |  |
| `onOpenChange` (required) | `(open: boolean) => void` |  |  |
| `shortcut` | `boolean` | `true` | Toggle with Ctrl+K or Cmd+K from anywhere on the page. On by default. |
| `inline` | `boolean` |  | Render the open palette in the page flow: no portal, scrim, focus trap or shortcut (docs, previews). |

## Examples

### Palette

Type to filter; arrows and Enter run a command.

```tsx
<Command groups={GROUPS} label="Search commands" />
```

### As a dialog with Ctrl+K

Press the button, or Ctrl K anywhere on this page.

```tsx
<CommandDialog open={open} onOpenChange={setOpen} groups={GROUPS} />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--command-dialog-width` | `560px` |
| `--command-input-h` | `48px` |
| `--command-list-max` | `320px` |
| `--command-radius` | `var(--r-lg)` |
| `--command-width` | `440px` |
| `--popover-item-active-bg` | `linear-gradient(to right, rgba(var(--rgb-brand), 0.14), rgba(var(--rgb-brand-deep), 0.07))` |
| `--popover-item-radius` | `var(--r-xs)` |
| `--popover-pad` | `calc(6px * var(--density))` |

System tokens it reads: `--border-w`, `--density`, `--dur`, `--dur-slow`, `--ease`, `--ease-out`, `--font-body`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-heading`, `--ink-muted`, `--ink-placeholder`, `--line`, `--line-glass`, `--line-soft`, `--modal-blur`, `--modal-scrim`, `--modal-scrim-blur`, `--modal-shadow`, `--modal-surface`, `--popover-blur`, `--popover-border`, `--popover-shadow`, `--popover-surface`, `--r-2xs`, `--r-lg`, `--r-xs`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-white`, `--text-caption`, `--text-input`, `--text-micro`, `--text-small`, `--tracking-label`, `--z-modal`.

## Accessibility

- The input is role="combobox" with aria-controls and aria-activedescendant; results are role="listbox" with role="group" sections labelled by their headings and role="option" rows.
- The result count is announced through a polite status region as you type.
- CommandDialog is a modal dialog: focus moves to the input, Tab is trapped, Esc closes, focus returns.

## Do

- Add keywords for the words people actually type ("new", "add").
- Show the real shortcut beside each command that has one.

## Don't

- Don't make the palette the only way to reach a page.
- Don't fill it with every possible action; keep the top group to what is likely now.

Related: https://rime.mjsons.net/components/nav-search, https://rime.mjsons.net/components/menu

---

# Menubar

> A desktop application menu bar (File, Edit, View) with keyboard navigation across and within its menus.

Category: Overlays. Docs page: https://rime.mjsons.net/components/menubar

## Installation

```bash
npx shadcn@latest add KezLahd/rime/menubar
```

Menubar is the WAI-ARIA menubar pattern on the recessed control fill. It is one tab stop: Left and Right move across the titles, Down, Enter or Space open a menu at its first item and Up at its last. While a menu is open, Left and Right move to the neighbouring menu and hovering another title switches to it.

Each menu is the shared menu list: icons, shortcut hints, separators, headings and danger items in the popover glass.

inline renders the open panel in the page flow: no portal, scrim, focus trap, scroll lock or outside-click listener. It exists for docs, previews and static mock-ups; never ship it as the live overlay.

## Usage

```tsx
import { Menubar } from "@/components/ui";

<Menubar
  aria-label="Editor"
  menus={[
    { id: "file", label: "File", items: [{ id: "new", label: "New project", shortcut: "Ctrl N", onSelect: create }] },
    { id: "edit", label: "Edit", items: [{ id: "undo", label: "Undo", shortcut: "Ctrl Z", onSelect: undo }] },
  ]}
/>
```

## Props: Menubar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `menus` (required) | `ReadonlyArray<MenubarMenu>` |  |  |
| `aria-label` (required) | `string` |  | The bar's accessible name, e.g. "Editor". |
| `inline` | `boolean` |  | Render one menu open in the page flow under its trigger (docs, previews). Nothing is interactive and no listeners are attached. |
| `inlineOpenId` | `string` |  | Inline only: which menu is drawn open (default the first) and which item is highlighted. |
| `inlineHighlightId` | `string` |  |  |
| `className` | `string` |  |  |

## Examples

### Open

The File menu drawn open under its title.

```tsx
<Menubar inline aria-label="Editor" menus={MENUS} inlineOpenId="file" inlineHighlightId="open" />
```

### Interactive

Click a title, then use the arrow keys.

```tsx
<Menubar aria-label="Editor" menus={MENUS} />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--menu-list-min-width` | `220px` |
| `--menubar-bg` | `rgba(var(--rgb-white), 0.5)` |
| `--menubar-item-radius` | `var(--r-sm)` |
| `--menubar-radius` | `var(--r-md)` |
| `--popover-item-active-bg` | `linear-gradient(to right, rgba(var(--rgb-brand), 0.14), rgba(var(--rgb-brand-deep), 0.07))` |
| `--popover-item-press-bg` | `linear-gradient(to right, rgba(var(--rgb-brand), 0.2), rgba(var(--rgb-brand-deep), 0.1))` |
| `--popover-item-radius` | `var(--r-xs)` |
| `--popover-pad` | `calc(6px * var(--density))` |
| `--popover-radius` | `var(--r-lg)` |

System tokens it reads: `--blur-recess`, `--border-w`, `--control-h-sm`, `--danger-ink`, `--density`, `--dur`, `--dur-fast`, `--dur-slow`, `--ease`, `--ease-out`, `--focus-ring`, `--font-body`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-heading`, `--ink-muted`, `--ink-secondary`, `--line-soft`, `--popover-blur`, `--popover-border`, `--popover-shadow`, `--popover-surface`, `--r-lg`, `--r-md`, `--r-sm`, `--r-xs`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-danger`, `--rgb-white`, `--shadow-recess`, `--text-caption`, `--text-micro`, `--text-small`, `--tracking-label`, `--wash-active`, `--wash-hover`, `--z-popover`.

## Accessibility

- role="menubar" holding role="menuitem" titles with aria-haspopup and aria-expanded; each menu is role="menu" labelled by its title.
- Roving tab index: the bar is a single tab stop. Esc closes a menu and returns focus to its title; Tab closes it and moves on.

## Do

- Use it for desktop tools and editors with many commands.
- Mirror the real keyboard shortcuts in the hints.

## Don't

- Don't use it for site navigation; that is NavigationMenu or the sidebar.
- Don't nest submenus; keep each menu flat.

Related: https://rime.mjsons.net/components/context-menu, https://rime.mjsons.net/components/menu, https://rime.mjsons.net/components/command

---

# GlassPanel

> Frosted glass over the page field: page, light and nested variants, padding steps and an optional bloom.

Category: Layout and surfaces. Docs page: https://rime.mjsons.net/components/glass-panel

## Installation

```bash
npx shadcn@latest add KezLahd/rime/glass-panel
```

GlassPanel is the signature surface: a translucent white fill, a lit edge, a specular top line and a two-layer shadow over the coloured page field. page holds a screen's main content (one or two per screen), light is for screens that are mostly panel, nested is a glass block inside a panel.

It publishes --inner-radius (its radius minus its padding, floored at --r-2xs) so anything flush inside it is concentric. bloom adds a soft corner light for the one place to act; the flat preset turns it off.

## Usage

```tsx
import { GlassPanel } from "@/components/ui";

<GlassPanel padding="lg">…</GlassPanel>
```

## Props: GlassPanel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"page" \| "light" \| "nested"` | `"page"` | page = the signature panel, radius 20, two-layer shadow (one or two per screen). light = for screens that are mostly panel, so the page does not go milky. nested = a glass row or block inside a page panel, radius 16, no heavy shadow. |
| `padding` | `"none" \| "sm" \| "md" \| "lg"` | `"md"` |  |
| `as` | `"div" \| "section" \| "article" \| "aside" \| "header"` | `"div"` |  |
| `bloom` | `boolean` |  | Soft corner light, the reference "something to act on here" signal. Use sparingly. Off in the public system (--bloom-opacity: 0). |
| `tabbed` | `boolean` |  | Squares the top-left corner so FolderTabs can sit on it. Set by FolderTabs. |

Also accepts the native attributes of: AriaAttributes, DOMAttributes, HTMLAttributes.

## Examples

### Variants

```tsx
<GlassPanel>Page</GlassPanel>
<GlassPanel variant="light">Light</GlassPanel>
<GlassPanel variant="nested" padding="sm">Nested</GlassPanel>
<GlassPanel bloom>With bloom</GlassPanel>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--bloom-opacity` | `1` |
| `--panel-pad-lg` | `calc(24px * var(--density))` |
| `--panel-pad-md` | `calc(20px * var(--density))` |
| `--panel-pad-sm` | `calc(12px * var(--density))` |
| `--panel-radius-nested` | `var(--r-xl)` |
| `--panel-radius-page` | `var(--r-2xl)` |
| `--r-flat` | `var(--panel-radius)` |

System tokens it reads: `--blur-panel`, `--blur-panel-light`, `--blur-row`, `--density`, `--glass-edge`, `--glass-fill`, `--glass-fill-light`, `--glass-fill-nested`, `--r-2xl`, `--r-2xs`, `--r-xl`, `--rgb-bloom-a`, `--rgb-brand`, `--rgb-contact`, `--rgb-white`, `--shadow-panel`, `--shadow-panel-light`, `--shadow-specular`.

## Accessibility

- Glass needs contrast checks on its worst-case background: check every ink in the Studio's Contrast tab, which measures against the glass over the field.

## Do

- Use one page panel per job on a screen.

## Don't

- No bento grids of panels; no left accent bars.

---

# Card

> A solid card with a washed header, a lifted highlight tone, and a sunken muted tone.

Category: Layout and surfaces. Docs page: https://rime.mjsons.net/components/card

## Installation

```bash
npx shadcn@latest add KezLahd/rime/card
```

Card is a solid surface for content that should not show the field through it: summaries, forms, record details. default is a solid card with a washed header; highlight lifts the one block that needs action (white, a crisp brand hairline, a soft lift and a faint top rule); muted is a sunken box for secondary information.

It sets data-surface="solid", so secondary buttons inside become white tiles, and publishes --card-pad and --inner-radius to its content.

Two ways to fill it, rendering identically: props (title, description, actions, footer) or shadcn's parts (CardHeader, CardTitle, CardDescription, CardAction, CardContent, CardFooter). With parts, the children render bare and the parts give the structure.

## Usage

```tsx
import { Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "@/components/ui";

<Card title="This month" description="Updated hourly" actions={<Button size="sm" variant="secondary">Export</Button>}>…</Card>
```

## Composition

```tsx
Card
├── CardHeader
│   ├── CardTitle
│   ├── CardDescription
│   └── CardAction
├── CardContent
└── CardFooter
```

## Props: Card

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` |  |  |
| `description` | `ReactNode` |  |  |
| `actions` | `ReactNode` |  | Right side of the header: buttons, a status pill. |
| `footer` | `ReactNode` |  |  |
| `tone` | `"default" \| "highlight" \| "muted"` | `"default"` | default = solid card with a washed header. highlight = lifted white panel with a soft brand top edge, for the one block on a screen that needs the user's action. muted = sunken neutral box for secondary information. |
| `padding` | `"sm" \| "md" \| "lg"` | `"md"` |  |
| `as` | `"div" \| "section" \| "article" \| "aside"` | `"section"` |  |
| `headingLevel` | `2 \| 3 \| 4` | `3` |  |

Also accepts the native attributes of: AriaAttributes, DOMAttributes, HTMLAttributes.

## Props: CardHeader

Also accepts the native attributes of: AriaAttributes, DOMAttributes, HTMLAttributes.

## Props: CardContent

Also accepts the native attributes of: AriaAttributes, DOMAttributes, HTMLAttributes.

## Props: CardFooter

Also accepts the native attributes of: AriaAttributes, DOMAttributes, HTMLAttributes.

## Examples

### Tones

```tsx
<Card title="Default">…</Card>
<Card tone="highlight" title="Two invoices are overdue">…</Card>
<Card tone="muted">Secondary info</Card>
```

### Composed from parts

The same card written with shadcn's parts; it renders identically to the props form below it.

```tsx
<Card>
  <CardHeader>
    <CardTitle>This month</CardTitle>
    <CardDescription>Updated hourly</CardDescription>
    <CardAction><Button size="sm" variant="secondary">Export</Button></CardAction>
  </CardHeader>
  <CardContent>32 invoices paid</CardContent>
  <CardFooter><Button size="sm">View all</Button></CardFooter>
</Card>

// identical to:
<Card title="This month" description="Updated hourly" actions={…} footer={…}>32 invoices paid</Card>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--card-bg` | `var(--surface-solid)` |
| `--card-border` | `var(--line)` |
| `--card-header-bg` | `linear-gradient(to right, var(--surface-sunken), var(--surface-sunken-2))` |
| `--card-pad-lg` | `calc(24px * var(--density))` |
| `--card-pad-md` | `calc(20px * var(--density))` |
| `--card-pad-sm` | `calc(14px * var(--density))` |
| `--card-radius` | `var(--r-xl)` |
| `--card-shadow` | `var(--shadow-hairline-card)` |

System tokens it reads: `--border-w`, `--density`, `--font-body`, `--highlight-edge`, `--highlight-glow`, `--highlight-line`, `--ink-heading`, `--ink-muted`, `--line`, `--line-glass`, `--line-soft`, `--r-2xs`, `--r-xl`, `--shadow-hairline-card`, `--shadow-lift`, `--surface-solid`, `--surface-sunken`, `--surface-sunken-2`, `--text-card-title`, `--text-small`.

## Accessibility

- The title renders as h3 by default; set headingLevel to fit the page outline.

## Do

- Use highlight once per screen at most.

## Don't

- Don't tint a card to make it stand out; lift it (tone="highlight").

---

# ScrollArea, useScrollEdges and useScrollLock

> The modal's scroll, made portable: thin tinted scrollbars, contained overscroll, edge shadows and a shared scroll lock.

Category: Layout and surfaces. Docs page: https://rime.mjsons.net/components/scroll-area

## Installation

```bash
npx shadcn@latest add KezLahd/rime/scroll-area
```

ScrollArea wraps any scrolling region (a long list in a panel, long terms, a wide table with axis="x") and gives it the modal's scroll: thin native scrollbars in a brand tint (--scrollbar-thumb, --scrollbar-track, --scrollbar-width), overscroll-behavior: contain, and edge shadows that appear only when content has scrolled under the start edge or continues past the end (--scroll-edge-top, --scroll-edge-bottom, and -left/-right for x).

useScrollEdges(ref, { target, axis }) is the engine on its own: a passive scroll listener plus a ResizeObserver that toggle data-scrolled and data-more on the scroller (or a target such as a modal panel) without re-rendering React. Use it when your header and footer are siblings of the scroller and should cast the shadows themselves, as Modal does.

themedScrollClass is just the scrollbar and overscroll half, for a scroller you already have. useScrollLock() locks page scroll with a shared counter (nested overlays nest) and pays the scrollbar's width back as padding so nothing shifts.

## Usage

```tsx
import { ScrollArea, themedScrollClass, useScrollEdges, useScrollLock } from "@/components/ui";

<ScrollArea maxHeight={320} label="Workspace terms">
  {terms}
</ScrollArea>
```

## Props: ScrollArea

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `maxHeight` | `CSSProperties["maxHeight"]` |  | Caps the viewport; the content scrolls past it. Any CSS length. |
| `axis` | `"y" \| "x"` | `"y"` | "y" (default) for lists and long copy, "x" for wide tables. |
| `label` | `string` |  | A name for the scrolling region. When set, the viewport joins the tab order (a keyboard user can scroll it) and is announced as a region. |
| `children` | `ReactNode` |  |  |

Also accepts the native attributes of: AriaAttributes, DOMAttributes, HTMLAttributes.

## Examples

### Vertical

Scroll it: the top shade arrives once you leave the start; the bottom shade leaves at the end.

```tsx
<ScrollArea maxHeight={240} label="Activity">…</ScrollArea>
```

### Horizontal (a wide table)

```tsx
<ScrollArea axis="x" label="Sprints">
  <Table … />
</ScrollArea>
```

### The hook on your own scroller

```tsx
const bodyRef = useRef<HTMLDivElement>(null);
const panelRef = useRef<HTMLDivElement>(null);
useScrollEdges(bodyRef, { target: panelRef });

// CSS: .panel[data-scrolled] .header { box-shadow: var(--scroll-edge-top); }
//      .panel[data-more] .footer { box-shadow: var(--scroll-edge-bottom); }
```

## Theme tokens

System tokens it reads: `--dur-slow`, `--ease`, `--focus-color`, `--scroll-edge-bottom`, `--scroll-edge-left`, `--scroll-edge-right`, `--scroll-edge-top`, `--scrollbar-thumb`, `--scrollbar-track`, `--scrollbar-width`.

## Accessibility

- Pass label to make the region focusable (tabIndex 0) and named, so keyboard users can scroll it; skip it when the content already holds focusable items.
- Native scrollbars stay: they keep platform behaviour (overlay scrollbars on macOS, high contrast in forced-colors).

## Do

- Use it for any region that scrolls inside the page.

## Don't

- Don't build a JavaScript scrollbar.
- Don't nest two vertical scrollers.

Related: https://rime.mjsons.net/components/modal

---

# Divider

> A hairline rule, horizontal or vertical, optionally labelled, with spacing steps.

Category: Layout and surfaces. Docs page: https://rime.mjsons.net/components/divider

## Installation

```bash
npx shadcn@latest add KezLahd/rime/divider
```

Divider separates groups inside a panel. label puts a short word in the rule ("or").

## Usage

```tsx
import { Divider } from "@/components/ui";

<Divider spacing="sm" />
```

## Props: Divider

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |  |
| `label` | `ReactNode` |  | Centred text in the rule: "or", a section name. |
| `spacing` | `"none" \| "sm" \| "md" \| "lg"` | `"md"` | Vertical margin for horizontal dividers. |
| `className` | `string` |  |  |

## Examples

### Default and labelled

```tsx
<Divider />
<Divider label="or" />
```

## Theme tokens

System tokens it reads: `--ink-muted`, `--line-glass`, `--line-soft`, `--text-micro`, `--tracking-eyebrow`.

## Accessibility

- role="separator" with aria-orientation; decorative rules inside lists are hidden.

## Do

- Prefer space over rules where space does the job.

## Don't

- Don't stack dividers and borders on the same edge.

---

# Accordion

> Stacked sections that open and close in place: one at a time or several, on glass or plain hairlines.

Category: Layout and surfaces. Docs page: https://rime.mjsons.net/components/accordion

## Installation

```bash
npx shadcn@latest add KezLahd/rime/accordion
```

Accordion holds a list of questions, settings groups or details where people read one section at a time. type="single" keeps one section open (collapsible lets the open one close again); type="multiple" lets any number stay open.

Each header is a real heading (headingLevel, default h3) holding a button, so the page outline stays right. The panel animates its height with a grid-row transition, with no measuring, and reduced motion makes it instant. Closed panels are inert, so their links leave the tab order.

appearance="glass" is a frosted panel with hairlines between sections; "plain" is hairlines only, for use inside a Card or GlassPanel that already provides the surface.

## Usage

```tsx
import { Accordion } from "@/components/ui";

<Accordion
  defaultValue={["billing"]}
  items={[
    { id: "billing", title: "When is an invoice issued?", content: "On the first working day of each month." },
    { id: "seats", title: "Can I add a team member mid-cycle?", content: "Yes, from the day it is added." },
  ]}
/>
```

## Props: Accordion

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `ReadonlyArray<AccordionItem>` |  |  |
| `type` | `"single" \| "multiple"` | `"single"` | single = one section open at a time. multiple = any number. |
| `value` | `ReadonlyArray<string>` |  | Open ids, controlled. Pair with onValueChange. |
| `defaultValue` | `ReadonlyArray<string>` |  | Open ids on first render, uncontrolled. |
| `onValueChange` | `(value: string[]) => void` |  |  |
| `collapsible` | `boolean` | `true` | single only: false keeps one section open at all times. |
| `headingLevel` | `2 \| 3 \| 4 \| 5` | `3` | Heading level the triggers sit in, to fit the page outline. |
| `appearance` | `"glass" \| "plain"` | `"glass"` | glass = a frosted panel with hairlines between sections. plain = hairlines only. |
| `className` | `string` |  |  |

## Examples

### Single, one open

```tsx
<Accordion items={FAQ} defaultValue={["billing"]} />
```

### Multiple open

type="multiple": opening one section leaves the others as they are.

```tsx
<Accordion type="multiple" items={FAQ} defaultValue={["billing", "seats"]} />
```

### Plain, inside a surface

```tsx
<Card title="Help">
  <Accordion appearance="plain" items={FAQ} />
</Card>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--accordion-pad-x` | `calc(16px * var(--density))` |
| `--accordion-pad-y` | `calc(14px * var(--density))` |
| `--accordion-radius` | `var(--r-lg)` |
| `--accordion-width` | `min(560px, 100%)` |

System tokens it reads: `--blur-panel-light`, `--border-w`, `--density`, `--dur`, `--dur-slow`, `--ease`, `--ease-out`, `--focus-color`, `--glass-edge`, `--glass-fill-nested`, `--ink-body`, `--ink-brand`, `--ink-disabled`, `--ink-heading`, `--ink-muted`, `--line`, `--line-glass`, `--r-lg`, `--shadow-hairline-card`, `--shadow-specular`, `--text-body`, `--text-small`, `--wash-hover`.

## Accessibility

- WAI-ARIA accordion: each trigger is a <button> inside a heading, with aria-expanded and aria-controls; each panel is a region labelled by its trigger.
- Up and Down move focus between headers, Home and End jump to the first and last; Enter and Space toggle.
- Closed panels are inert, so nothing hidden can take focus.
- Focus shows as a 2px accent outline inset in the row.

## Do

- Write titles as the question or the name of the group, so a closed list scans.
- Open the most useful section by default with defaultValue.

## Don't

- Don't hide required form fields in a closed section.
- Don't nest accordions; use headings and a longer page instead.

Related: https://rime.mjsons.net/components/collapsible, https://rime.mjsons.net/components/card

---

# Collapsible

> One disclosure: a title row with a toggle, an always-visible summary and a region that opens beneath it.

Category: Layout and surfaces. Docs page: https://rime.mjsons.net/components/collapsible

## Installation

```bash
npx shadcn@latest add KezLahd/rime/collapsible
```

Collapsible shows the first part of something and keeps the rest a click away: the first of several items, advanced options, a long note. The summary stays visible whether open or closed; children open beneath it.

The region animates its height on a grid-row transition and is inert while closed. Control it with open and onOpenChange, or leave it uncontrolled with defaultOpen.

## Usage

```tsx
import { Collapsible } from "@/components/ui";

<Collapsible title="Jane Cooper starred 3 projects" summary={<Row>north-office/website</Row>}>
  <Row>north-office/brand-refresh</Row>
  <Row>north-office/quarterly-report</Row>
</Collapsible>
```

## Props: Collapsible

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `ReactNode` |  | The trigger's text. A chevron button sits at its right. |
| `summary` | `ReactNode` |  | Shown whether open or closed, under the trigger row (the first item of a list, say). |
| `children` (required) | `ReactNode` |  |  |
| `open` | `boolean` |  |  |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `(open: boolean) => void` |  |  |
| `toggleLabel` | `string` |  | Accessible name for the icon trigger. Defaults to "Show more" / "Show less". |
| `className` | `string` |  |  |

## Examples

### Open, with a summary

```tsx
<Collapsible title="Jane Cooper starred 3 projects" summary={<Row>north-office/website</Row>} defaultOpen>
  …
</Collapsible>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--collapsible-width` | `min(380px, 100%)` |

System tokens it reads: `--dur`, `--dur-slow`, `--ease`, `--ease-out`, `--focus-ring`, `--ink-brand`, `--ink-heading`, `--ink-muted`, `--r-sm`, `--text-small`, `--wash-active`, `--wash-subtle`.

## Accessibility

- The toggle is a button with aria-expanded and aria-controls pointing at the region; its name switches between "Show more" and "Show less" unless toggleLabel is given.
- The closed region is inert, so its content is out of the tab order and the accessibility tree.

## Do

- Use it for one disclosure; use Accordion for a list of them.

## Don't

- Don't put the only copy of an error or a required field inside a closed Collapsible.

Related: https://rime.mjsons.net/components/accordion

---

# Carousel

> A row of slides on a native scroll-snap track, with frosted prev and next buttons, dots and arrow keys.

Category: Layout and surfaces. Docs page: https://rime.mjsons.net/components/carousel

## Installation

```bash
npx shadcn@latest add KezLahd/rime/carousel
```

Carousel lays its children out as slides on a scroll-snap track, so swipe, trackpad and the keyboard all scroll the same native element with no dependency. perView shows several at once on wide screens (one on phones); the buttons fade out at the ends unless loop is on.

autoplay (off by default) advances on a timer, stops while the pointer or focus is inside and has its own pause button, as WCAG 2.2.2 requires. Reduced motion scrolls instantly.

## Usage

```tsx
import { Carousel } from "@/components/ui";

<Carousel aria-label="Featured projects" perView={3}>
  {projects.map((p) => <ProjectCard key={p.id} project={p} />)}
</Carousel>
```

## Props: Carousel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | One child per slide. |
| `aria-label` (required) | `string` |  | Names the carousel region: "Featured projects". |
| `perView` | `1 \| 2 \| 3 \| 4` | `1` | Slides visible at once on wide screens. Narrow screens show one. Default 1. |
| `gap` | `number` | `12` | Gap between slides in px. Default 12. |
| `controls` | `boolean` | `true` | Prev and next buttons. On by default. |
| `dots` | `boolean` | `true` | The dot row under the track. On by default. |
| `autoplay` | `number` |  | Advance every n ms. Off by default; pauses on hover and focus, and has a pause button. |
| `loop` | `boolean` | `false` | Start again from the first slide after the last. Default false. |
| `onIndexChange` | `(index: number) => void` |  |  |
| `className` | `string` |  |  |

## Examples

### One per view

```tsx
<Carousel aria-label="Projects">{slides}</Carousel>
```

### Three per view

```tsx
<Carousel aria-label="Projects" perView={3}>{slides}</Carousel>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--carousel-gap` | `12px` |
| `--carousel-nav-radius` | `var(--r-full)` |
| `--carousel-per-view` | `1` |
| `--carousel-radius` | `var(--r-lg)` |
| `--r-circle` | `50%` |

System tokens it reads: `--brand`, `--dur`, `--ease`, `--focus-ring`, `--ink-brand`, `--ink-heading`, `--ink-secondary`, `--line-input`, `--neutral-border`, `--popover-blur`, `--popover-surface`, `--r-full`, `--r-lg`, `--r-sm`, `--recess-fill`, `--recess-fill-hover`, `--shadow-float`, `--surface-solid`, `--text-caption`.

## Accessibility

- A section with aria-roledescription="carousel" and a required aria-label; each slide is a group with aria-roledescription="slide" labelled "2 of 5".
- Left and Right arrows move a slide; the track is focusable; off-screen slides are inert so Tab never lands on a hidden card.
- The track is a polite live region while not autoplaying, so a change of slide is announced.

## Do

- Use it for browsable, optional content: featured items, screenshots.
- Show a partial next slide (perView 3 at narrower widths) so people see there is more.

## Don't

- Don't put the only copy of important information on slide two or later.
- Don't turn autoplay on for content people need to read.

Related: https://rime.mjsons.net/components/aspect-ratio, https://rime.mjsons.net/components/card

---

# AspectRatio

> A box held to a width-to-height ratio, so media keeps its shape and never shifts the layout while loading.

Category: Layout and surfaces. Docs page: https://rime.mjsons.net/components/aspect-ratio

## Installation

```bash
npx shadcn@latest add KezLahd/rime/aspect-ratio
```

AspectRatio sizes itself from its width and a ratio (16 / 9 by default) with the CSS aspect-ratio property. A direct <img>, <video>, <iframe> or <picture> child fills it with object-fit: cover. framed (on by default) clips it to the inner radius on a sunken fill with a hairline, so an empty or loading box still reads as a frame.

## Usage

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

<AspectRatio ratio={16 / 9}>
  <img src="/cover.jpg" alt="The new office, from the street" />
</AspectRatio>
```

## Props: AspectRatio

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ratio` | `number` | `16 / 9` | Width over height: 16 / 9, 4 / 3, 1. Default 16 / 9. |
| `framed` | `boolean` | `true` | Rounded, clipped frame with a hairline, for media on a panel. Default true. |

Also accepts the native attributes of: AriaAttributes, DOMAttributes, HTMLAttributes.

## Examples

### 16 / 9

```tsx
<AspectRatio ratio={16 / 9}>…</AspectRatio>
```

### Square and 4 / 3

```tsx
<AspectRatio ratio={1}>…</AspectRatio>
<AspectRatio ratio={4 / 3}>…</AspectRatio>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--aspect-radius` | `var(--inner-radius, var(--r-lg))` |
| `--aspect-ratio` | `1.7778` |
| `--aspect-width` | `100%` |
| `--inner-radius` | `var(--r-lg)` |

System tokens it reads: `--border-w`, `--line`, `--r-lg`, `--surface-sunken`.

## Accessibility

- A plain box with no role; give the media inside it its own alt text or captions.

## Do

- Use it for every image whose size is not known ahead, so nothing jumps when it loads.

## Don't

- Don't crop faces or text with cover; pick a ratio that suits the media.

Related: https://rime.mjsons.net/components/carousel

---

# Resizable

> Panels split by draggable hairline handles, side by side or stacked, with keyboard resizing and minimum sizes.

Category: Layout and surfaces. Docs page: https://rime.mjsons.net/components/resizable

## Installation

```bash
npx shadcn@latest add KezLahd/rime/resizable
```

ResizablePanelGroup holds ResizablePanel and ResizableHandle children, alternating. Sizes are percentages applied as flex-grow proportions, so handles keep their pixel width and nothing overflows. Each panel can set defaultSize and minSize; onLayout reports every size after a change, for saving the split.

Drag a handle with the pointer, or focus it and use the arrow keys (5%, Shift for 10%) and Home or End. withGrip draws a small grip on the rule. framed (default) puts the group on a glass panel.

## Usage

```tsx
import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from "@/components/ui";

<ResizablePanelGroup height={320}>
  <ResizablePanel defaultSize={30} minSize={20}>Projects</ResizablePanel>
  <ResizableHandle withGrip />
  <ResizablePanel>Details</ResizablePanel>
</ResizablePanelGroup>
```

## Props: ResizablePanelGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `direction` | `"horizontal" \| "vertical"` | `"horizontal"` | horizontal = panels side by side (drag left and right). Default horizontal. |
| `children` (required) | `ReactNode` |  | ResizablePanel and ResizableHandle children, alternating. |
| `onLayout` | `(sizes: number[]) => void` |  | Called with every panel's size, in percent, after each change. |
| `height` | `number \| string` |  | Group height for vertical groups (or any fixed frame), e.g. 320. |
| `framed` | `boolean` | `true` | Glass frame around the group with hairline handles. Default true. |
| `className` | `string` |  |  |

## Props: ResizablePanel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultSize` | `number` |  | Starting size in percent of the group. Unset panels share what is left. |
| `minSize` | `number` |  | Smallest size in percent. Default 10. |
| `children` | `ReactNode` |  |  |
| `className` | `string` |  |  |

## Props: ResizableHandle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` |  | Accessible name. Defaults to "Resize". |
| `withGrip` | `boolean` |  | Shows a small grip on the rule. |
| `className` | `string` |  |  |

## Examples

### Three panels

Drag a handle, or focus it and use the arrow keys.

```tsx
<ResizablePanelGroup height={240}>
  <ResizablePanel defaultSize={25} minSize={15}>Projects</ResizablePanel>
  <ResizableHandle withGrip />
  <ResizablePanel defaultSize={50}>Invoice INV-004213</ResizablePanel>
  <ResizableHandle withGrip />
  <ResizablePanel defaultSize={25} minSize={15}>Details</ResizablePanel>
</ResizablePanelGroup>
```

### Vertical

```tsx
<ResizablePanelGroup direction="vertical" height={280}>…</ResizablePanelGroup>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--resizable-min-height` | `200px` |
| `--resizable-radius` | `var(--r-lg)` |

System tokens it reads: `--blur-panel-light`, `--border-w`, `--brand`, `--dur`, `--ease`, `--glass-edge`, `--glass-fill-nested`, `--line`, `--line-input`, `--r-2xs`, `--r-lg`, `--rgb-brand`, `--shadow-hairline-card`, `--shadow-input`, `--shadow-specular`, `--surface-solid`.

## Accessibility

- Each handle is a focusable role="separator" with aria-valuenow (the size of the panel before it), aria-valuemin, aria-valuemax and aria-controls; aria-orientation is perpendicular to the group.
- Arrow keys resize in 5% steps (10% with Shift); Home and End jump to the limits.
- Give each handle an aria-label that says what it resizes when there is more than one.

## Do

- Set minSize so no panel can be dragged shut by accident.
- Save the split from onLayout so it survives a reload.

## Don't

- Don't use it for layouts people never need to change; fixed columns are simpler.

---

# SidebarShell

> The signed-in frame in four layouts: an expanded frosted sidebar, a collapsible icon rail, a header-only top nav, and a drawer on narrow screens.

Category: Shell. Docs page: https://rime.mjsons.net/components/sidebar-shell

## Installation

```bash
npx shadcn@latest add KezLahd/rime/sidebar-shell
```

SidebarShell is the dashboard frame. The page field is painted once on the whole frame; the sidebar and top bar are frosted glass over it, so the chrome carries a whitened version of the field and the screen reads as one surface. Only <main> scrolls, so the chrome never moves and its blur always has content passing beneath it.

layout picks the frame. sidebar (the default) is the expanded glass L. rail is the sidebar collapsed to icons: labels are visually hidden (each item keeps its title as a tooltip), counts sit on the icon and the logo corner shows the compact mark (logoCompact). header drops the sidebar: the logo, the nav as horizontal links and topbarRight share one frosted top bar, and the page sits below. collapsible adds a panel button to the top bar that folds the sidebar to the rail and back; storageKey remembers the choice in localStorage, read after mount so the server and client render the same.

Below 900px of the frame's own width (600px when contained; set mobileBelow to change it) the sidebar becomes an off-canvas drawer: a menu button in the top bar opens it, focus moves in and is held there, and Esc, the scrim or picking a link closes it and returns focus to the button. mobileDrawer={false} keeps the icon rail on narrow screens instead. forceMobile and defaultDrawerOpen exist for previews like the one here.

The logo corner is flush, square and exactly the top bar's height. By default (logoCorner="glass") it is the same frosted glass as the sidebar and top bar, so the chrome reads as one continuous L. logoCorner="fill" opts in to a set colour or gradient behind the logo (--logo-corner-bg, with --logo-corner-ink for the default wordmark), for brands whose guidelines require one. Pass your logo as an element (logo) or an image URL (logoSrc); without either it shows a sample glyph and "Acme", the placeholder brand. strip adds a full-width band across the top (an admin session, a staging site), on --admin-strip-bg. The active nav item is the solid brand-gradient pill, the one gradient on the chrome.

Every chrome colour reads a token: --chrome-sidebar, --chrome-topbar, --chrome-shadow, --sidebar-bg, --topbar-bg, --sidebar-ink, --sidebar-hover-bg, --sidebar-active-bg and -ink, --sidebar-rule, --shell-sidebar-width, --shell-rail-width, --shell-drawer-width, plus --shell-logo (a url()). It is presentation only: no auth in here.

## Usage

```tsx
import { SidebarShell } from "@/components/shell/SidebarShell";

<SidebarShell
  navLabel="Main"
  logo={<img src="/logo.svg" alt="Acme" width={140} height={32} />}
  nav={[
    { href: "/dashboard", label: "Dashboard", icon: <IconHome size={16} />, exact: true },
    { href: "/projects", label: "Projects", icon: <IconClipboard size={16} />, count: 2 },
  ]}
  title="Projects"
  topbarRight={<Avatar name="Jane Cooper" size="sm" />}
  collapsible
  storageKey="app-sidebar-collapsed"
>
  {children}
</SidebarShell>
```

## Props: SidebarShell

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  |  |
| `nav` (required) | `ReadonlyArray<SidebarNavItem>` |  |  |
| `bottomNav` | `ReadonlyArray<SidebarNavItem>` |  | Pinned to the bottom of the sidebar (settings, sign out). Not shown in the header layout. |
| `navLabel` (required) | `string` |  |  |
| `title` | `ReactNode` |  | Page title shown in the top bar (sidebar and rail layouts). |
| `topbarRight` | `ReactNode` |  | Right side of the top bar: search, workspace switcher, profile. |
| `strip` | `ReactNode` |  | Full-width strip across the top of the frame, logo corner included (the admin context). |
| `footer` | `ReactNode` |  |  |
| `layout` | `SidebarShellLayout` | `"sidebar"` | sidebar (the default) = the expanded frosted sidebar and top bar, one glass L. rail = the sidebar collapsed to an icon rail. header = no sidebar: the logo, the nav as horizontal links and topbarRight in one frosted top bar, with the page below. |
| `collapsible` | `boolean` |  | Shows a toggle in the top bar that collapses the sidebar to the rail and back. The starting state is the layout prop (rail = collapsed) unless defaultCollapsed says otherwise. Ignored in the header layout. |
| `defaultCollapsed` | `boolean` |  | Start collapsed (as the rail). Defaults to layout === "rail". |
| `storageKey` | `string` |  | Persists the collapsed state in localStorage under this key. Read after mount. |
| `onCollapsedChange` | `(collapsed: boolean) => void` |  |  |
| `mobileDrawer` | `boolean` | `true` | Below the mobile breakpoint, the sidebar becomes an off-canvas drawer opened from a menu button in the top bar. On by default; false keeps the icon rail on narrow screens instead. |
| `mobileBelow` | `number` |  | The frame width (px) below which the drawer (or rail if mobileDrawer is false) applies. Defaults to 600, or 420 when contained. |
| `tabletBelow` | `number` |  | The frame width (px) below which the sidebar auto-collapses to the icon rail (tablet mode). A chevron at the bottom of the rail toggles back to the full width. Defaults to 1024, or 760 when contained. Set below mobileBelow to disable tablet mode. |
| `forceMobile` | `boolean` |  | Treat the frame as narrow whatever its width: the docs use it to show the drawer at desktop width. |
| `defaultDrawerOpen` | `boolean` |  | Open the drawer on first render, without moving focus (a static docs preview). |
| `logo` | `ReactNode` |  | The logo corner's content: your logo as an element (an <img>, an inline SVG, a wordmark). Defaults to a sample glyph and "Acme", the placeholder brand. |
| `logoCompact` | `ReactNode` |  | The logo for the rail's narrow corner: a mark without the wordmark. Defaults to the glyph. |
| `logoCorner` | `"glass" \| "fill"` | `"glass"` | The logo corner's ground. glass (the default) = the same frosted glass as the sidebar and top bar, one continuous L. fill = a set colour behind the logo, from --logo-corner-bg (ink --logo-corner-ink), for brands whose guidelines require one. |
| `logoSrc` | `string` |  | A logo image URL (or data URL) for the corner, in place of `logo`. Up to 176px wide. |
| `logoAlt` | `string` |  | Alt text for logoSrc. Required in practice whenever logoSrc is set. |
| `activeHref` | `string` |  | Overrides the pathname match; used by the docs previews. |
| `contained` | `boolean` |  | Fill the parent instead of the viewport. The docs render the shell inside a fixed-height frame so the sticky chrome can be seen working. |

## Examples

### Sidebar expanded (logo corner: match glass)

```tsx
<SidebarShell contained navLabel="Main" nav={NAV} activeHref="/projects" title="Projects">
  …
</SidebarShell>
```

### Collapsible, remembered

The panel button folds the sidebar to the icon rail and back. storageKey keeps the choice across reloads.

```tsx
<SidebarShell
  contained
  collapsible
  storageKey="app-sidebar-collapsed"
  onCollapsedChange={(collapsed) => console.log("collapsed", collapsed)}
  navLabel="Main"
  nav={NAV}
  title="Projects"
>
  …
</SidebarShell>
```

### Collapsed to an icon rail

layout="rail" starts collapsed. With collapsible it can still be expanded.

```tsx
<SidebarShell contained layout="rail" collapsible navLabel="Main" nav={NAV} title="Projects" logoCompact={<Mark />}>
  …
</SidebarShell>
```

### Header only (top nav)

No sidebar: the logo, the nav and topbarRight share one frosted bar.

```tsx
<SidebarShell contained layout="header" navLabel="Main" nav={NAV} topbarRight={<Avatar name="Jane Cooper" size="sm" />}>
  …
</SidebarShell>
```

### Mobile drawer

Below 900px the sidebar is a drawer from the menu button. Shown open here with forceMobile and defaultDrawerOpen.

```tsx
// Automatic below 900px of the frame's width. For a preview at desktop width:
<SidebarShell contained forceMobile defaultDrawerOpen navLabel="Main" nav={NAV} title="Projects">
  …
</SidebarShell>

// Keep the icon rail on narrow screens instead of a drawer:
<SidebarShell mobileDrawer={false} navLabel="Main" nav={NAV}>…</SidebarShell>
```

### Logo corner: brand fill

Opt in for brands that require a set colour behind the logo. Set the colour with --logo-corner-bg (a colour or a gradient).

```tsx
<SidebarShell contained logoCorner="fill" navLabel="Main" nav={NAV} activeHref="/projects" title="Projects">…</SidebarShell>

/* theme.css */
:root { --logo-corner-bg: linear-gradient(135deg, #0f766e, #0b5c56); --logo-corner-ink: #ffffff; }
```

### With a context strip

```tsx
<SidebarShell contained strip="Admin session" navLabel="Admin" nav={ADMIN_NAV} activeHref="/admin" title="Overview">…</SidebarShell>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--brand-height` | `var(--topbar-height)` |
| `--chrome-backdrop` | `var(--blur-chrome) saturate(160%)` |
| `--logo-corner-art` | `none` |
| `--logo-corner-art-opacity` | `0` |
| `--logo-corner-ink` | `var(--ink-inverse)` |
| `--page-art` | `none` |
| `--page-art-opacity` | `0` |
| `--shell-drawer-width` | `264px` |
| `--shell-logo` | `normal` |
| `--shell-logo-width` | `176px` |
| `--shell-rail-width` | `68px` |
| `--shell-sidebar-width` | `212px` |
| `--shell-title-size` | `26px` |
| `--sidebar-active-badge-bg` | `rgba(var(--rgb-white), 0.25)` |
| `--sidebar-active-bg` | `var(--brand-gradient)` |
| `--sidebar-active-ink` | `var(--ink-inverse)` |
| `--sidebar-active-shadow` | `var(--glow-md), inset 0 1px 0 rgba(var(--rgb-white), 0.18)` |
| `--sidebar-art` | `none` |
| `--sidebar-art-opacity` | `0` |
| `--sidebar-bg` | `var(--chrome-sidebar)` |
| `--sidebar-drawer-bg` | `var(--modal-surface)` |
| `--sidebar-hover-bg` | `rgba(var(--rgb-white), 0.65)` |
| `--sidebar-ink` | `var(--ink-muted)` |
| `--sidebar-ink-hover` | `var(--ink-heading)` |
| `--sidebar-item-radius` | `var(--r-lg)` |
| `--sidebar-rule` | `rgba(var(--rgb-brand-deep), 0.08)` |
| `--sidebar-shadow` | `8px 0 28px rgba(var(--rgb-brand-deep), 0.12), 1px 0 3px rgba(var(--rgb-contact), 0.06)` |
| `--topbar-bg` | `var(--chrome-topbar)` |
| `--topbar-shadow` | `var(--chrome-shadow)` |

System tokens it reads: `--admin-strip-bg`, `--blur-chrome`, `--blur-scrim`, `--brand-gradient`, `--chrome-shadow`, `--chrome-sidebar`, `--chrome-topbar`, `--danger-base-solid`, `--density`, `--dur`, `--dur-slow`, `--ease`, `--ease-out`, `--focus-ring`, `--font-display`, `--glow-md`, `--glow-sm`, `--ink-brand`, `--ink-heading`, `--ink-inverse`, `--ink-muted`, `--line`, `--logo-corner-bg`, `--modal-blur`, `--modal-surface`, `--page-background`, `--page-base`, `--r-full`, `--r-lg`, `--r-md`, `--r-sm`, `--r-xl`, `--rgb-brand-deep`, `--rgb-contact`, `--rgb-white`, `--scrim`, `--shadow-float`, `--shadow-modal`, `--surface-solid`, `--text-micro`, `--text-small`, `--topbar-height`, `--tracking-display`.

## Accessibility

- A skip link ("Skip to content") is the first focusable element and targets <main id="main">.
- The nav is a labelled <nav> (navLabel) in every layout; the current item has aria-current="page". In the rail the labels stay in the accessibility tree (visually hidden) and each item has a title tooltip.
- The collapse toggle is a real button with aria-expanded and a label that says what it will do ("Collapse sidebar", "Expand sidebar").
- The drawer's menu button has aria-expanded and aria-controls. While open, focus is held in the drawer, the page behind is inert, and Esc or the scrim closes it and returns focus to the button. A closed drawer is inert, so it is out of the tab order.
- The top bar title is not a heading: each page owns its h1.
- contained renders a <div> instead of <main>, so a preview never adds a second main landmark.

## Do

- Gate access inside each page.tsx, never in the layout that renders the shell (a layout gate leaks the page into the RSC payload).
- Give the rail a compact mark (logoCompact) when your logo is a wide wordmark.
- Use the header layout for products with five or fewer top-level sections and no deep navigation.
- Keep account links in a profile menu in the top bar, not at the sidebar's foot.

## Don't

- Don't give the sidebar a hue of its own; it is whitened glass over the same field.
- Don't add a second gradient to the chrome; the active pill is the one.
- Don't hide navigation behind the drawer on wide screens; it is for narrow frames only.

Related: https://rime.mjsons.net/components/page-header, https://rime.mjsons.net/components/glass-panel

---

# PageHeader

> A page's h1 with a back link, a meta line, a description and actions.

Category: Shell. Docs page: https://rime.mjsons.net/components/page-header

## Installation

```bash
npx shadcn@latest add KezLahd/rime/page-header
```

PageHeader opens every signed-in page: the h1, an optional back link above it, meta beside the title (a status pill, a reference) and actions on the right. Nothing is stacked over the title, and the description uses the full width of its column.

## Usage

```tsx
import { PageHeader } from "@/components/shell/PageHeader";

<PageHeader title="Atlas redesign" back={{ href: "/projects", label: "Projects" }} actions={<Button variant="secondary">Share</Button>} />
```

## Props: PageHeader

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `ReactNode` |  |  |
| `description` | `ReactNode` |  |  |
| `actions` | `ReactNode` |  | Right-aligned: the view's one primary button, plus any secondaries. |
| `back` | `{ href: string; label: string }` |  | Back link above the title, e.g. { href: "/projects", label: "Projects" }. |
| `meta` | `ReactNode` |  | Sits beside the title: a status pill, a reference. |
| `className` | `string` |  |  |

## Examples

### Back link, meta and actions

```tsx
<PageHeader
  title="Atlas redesign"
  description="Started 12 Oct 2026 · 4 members"
  back={{ href: "/projects", label: "Projects" }}
  meta={<StatusPill tone="success">Active</StatusPill>}
  actions={<Button variant="secondary">Share</Button>}
/>
```

## Theme tokens

System tokens it reads: `--brand-deep`, `--dur`, `--ease`, `--focus-ring`, `--font-display`, `--ink-brand`, `--ink-heading`, `--ink-secondary`, `--r-xs`, `--text-body`, `--text-caption`, `--text-page-title`, `--tracking-display`, `--wash-subtle`.

## Accessibility

- Renders the page's only h1.

## Do

- One PageHeader per page.

## Don't

- Don't repeat the top bar title as a second heading.
- Don't stack a small label over the title.

---

# AuthCard and AuthLayout

> The sign-in card: a solid card on a deep field, with a logo slot, icon tile, title, footer strip and back link.

Category: Shell. Docs page: https://rime.mjsons.net/components/auth-card

## Installation

```bash
npx shadcn@latest add KezLahd/rime/auth-card
```

AuthLayout paints the auth field (--auth-background, --auth-floor, --auth-sky), centres its child, and takes an optional header (your brand mark, a help link) and footer (a security note). AuthCard frames sign-in, sign-up, MFA, reset and onboarding steps: a logo slot, an optional icon tile, the title (the page's h1) with an optional inline badge, the form, an optional back link and a footer strip.

## Usage

```tsx
import { AuthCard, AuthLayout } from "@/components/shell/AuthCard";

<AuthLayout>
  <AuthCard logo={<Logo />} title="Sign in" subtitle="Use the email you signed up with.">
    …form…
  </AuthCard>
</AuthLayout>
```

## Props: AuthCard

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `ReactNode` |  |  |
| `subtitle` | `ReactNode` |  |  |
| `logo` | `ReactNode` |  | Your logo or wordmark, centred above the title. |
| `icon` | `ReactNode` |  | Icon tile above the title (MFA screens). |
| `badge` | `ReactNode` |  | A small tag beside nothing else: "Admin", "Staging". Sits above the title on one line with it. |
| `children` (required) | `ReactNode` |  |  |
| `footer` | `ReactNode` |  | A strip under the card body: a trust line, a terms link. |
| `width` | `"sm" \| "md" \| "lg"` | `"sm"` | sm 440 (sign-in, MFA), md 520 (set password), lg 720 (onboarding). |
| `back` | `{ href: string; label: string }` |  | A way out, under the form: "Back to sign in". |

## Props: AuthLayout

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  |  |
| `header` | `ReactNode` |  | A bar across the top of the page: your brand mark at the left, a help link at the right. |
| `footer` | `ReactNode` |  | A strip at the foot of the page: a security note, legal links. |
| `contained` | `boolean` |  | Fill a fixed-height parent instead of the viewport (docs previews). |

## Examples

### Sign in with multi-factor authentication

A brand bar in the header, the card centred, the security note in the footer. Switch between the password, MFA code and authenticator setup steps.

```tsx
<AuthLayout
  header={<Logo />}
  footer={<><IconShield size={14} /> Protected by multi-factor authentication.</>}
>
  <AuthCard icon={<IconLock size={22} />} title="Sign in" subtitle="Use your work email.">
    <Field label="Work email"><TextInput type="email" autoComplete="username" /></Field>
    <Field label="Password"><TextInput type="password" revealable autoComplete="current-password" /></Field>
    <Button size="lg" fullWidth>Continue</Button>
  </AuthCard>
</AuthLayout>
```

### MFA code step

```tsx
<AuthCard icon={<IconShield size={22} />} title="Enter your code" subtitle="Open your authenticator app and enter the 6-digit code.">
  <OtpInput aria-label="Authentication code" value={code} onChange={setCode} onComplete={verify} />
  <Button size="lg" fullWidth disabled={code.length < 6}>Verify</Button>
</AuthCard>
```

### Authenticator setup step

```tsx
<AuthCard width="md" icon={<IconShield size={22} />} title="Set up your authenticator">
  <QrCode value={otpauthUrl} />
  <code>{secret}</code>
  <OtpInput aria-label="Code from your authenticator app" value={code} onChange={setCode} />
  <Button size="lg" fullWidth>Turn on two-step sign-in</Button>
</AuthCard>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--auth-ink` | `var(--ink-inverse)` |
| `--auth-ink-muted` | `rgba(255, 255, 255, 0.78)` |
| `--heading-case` | `none` |
| `--heading-tracking` | `var(--tracking-display)` |

System tokens it reads: `--auth-background`, `--auth-floor`, `--auth-sky`, `--brand-deep`, `--brand-fill`, `--brand-gradient-soft`, `--brand-ink`, `--brand-line`, `--font-body`, `--font-display`, `--ink-brand`, `--ink-heading`, `--ink-inverse`, `--ink-muted`, `--line-brand`, `--line-soft`, `--r-full`, `--r-lg`, `--r-xl`, `--shadow-auth-card`, `--surface-solid`, `--surface-sunken`, `--text-auth-title`, `--text-caption`, `--text-micro`, `--tracking-display`.

## Accessibility

- The title is the page's h1; the layout renders the main landmark.

## Do

- One primary action, full width, size lg.

## Don't

- Don't put navigation inside the card beyond the back link.

---

# Patterns

## Pattern: List page

> One glass panel holding the filter row, the table and the pagination. Nothing above it.

Every list page is this, and only this. The FilterBar's search grows to fill the row, dropdown chips sit at the end, "Clear filters" appears while anything is applied, and the list's own action goes last after a hairline. The table follows, then Pagination centred beneath.

Sort, filter and page state live with the screen. Reset to page one when a filter changes. The empty state says whether filters caused it and offers to clear them.

Uses: GlassPanel, FilterBar, FilterSearch, Select, Table, Pagination, EmptyState.

```tsx
<GlassPanel padding="lg">
  <FilterBar aria-label="Filter invoices" onClear={filtering ? clear : undefined} actions={<Button size="sm" iconStart={<IconPlus size={14} />}>New invoice</Button>}>
    <FilterSearch grow aria-label="Search invoices" value={query} onChange={setQuery} />
    <Select appearance="chip" aria-label="Status" value={status} onChange={setStatus} active={status !== "all"} options={STATUSES} />
  </FilterBar>
  <Table
    caption="Invoices"
    columns={columns}
    rows={pageRows}
    rowKey={(i) => i.id}
    sort={sort}
    onSortChange={setSort}
    empty={<EmptyState compact tone={filtering ? "filtered" : "default"} title="No invoices match" description="Clear a filter to see more." action={filtering ? <Button size="sm" variant="secondary" onClick={clear}>Clear filters</Button> : undefined} />}
  />
  <Pagination page={page} pageCount={pageCount} onPageChange={setPage} totalItems={filtered.length} pageSize={20} itemLabel="invoices" />
</GlassPanel>
```

- No heading or "n of m shown" line above the panel.
- Never a row of toggle chips for a single choice: use a Select chip.
- One table look everywhere: theme --table-* tokens, never restyle a table.

## Pattern: Frosted glass shell

> The signed-in frame: the page field painted once, a frosted sidebar and top bar over it, and glass panels inside.

The field (--page-background) is never white: a coloured base with soft blooms, so white glass reads as panels floating on colour. The sidebar and top bar are whitened glass over the same field, so the chrome shares its colour, and the logo corner is that same glass by default: one continuous frosted L. A brand that requires a set colour behind its logo opts in with logoCorner="fill" and --logo-corner-bg. Content sits in GlassPanels; the one block that needs the user's action can be a Card tone="highlight".

A motif must derive from the product. The blooms here are light, not a picture; another site should choose its own field and justify any device it adds.

Uses: SidebarShell, PageHeader, GlassPanel, Card.

```tsx
<SidebarShell navLabel="Main" nav={NAV} title="Dashboard" topbarRight={<Avatar name="Jane Cooper" size="sm" />}>
  <PageHeader title="Good morning, Jane" description="Two invoices need your review." />
  <GlassPanel padding="lg">…</GlassPanel>
</SidebarShell>
```

- Gate inside page.tsx, never the layout.
- No bento grids; no left accent bars; no hover scale.

## Pattern: Shell: sidebar expanded

> The default signed-in frame: a full-height frosted sidebar and top bar forming one glass L, the logo corner in the same glass.

Use it for products with more than five sections, or sections people move between all day. The sidebar holds the primary nav with counts; the top bar names the area and holds search and the profile menu. Only the page scrolls.

Uses: SidebarShell, GlassPanel, PageHeader.

```tsx
<SidebarShell navLabel="Main" nav={NAV} title="Projects" topbarRight={<Avatar name="Jane Cooper" size="sm" />}>
  <PageHeader title="Projects" />
  <GlassPanel padding="lg">…</GlassPanel>
</SidebarShell>
```

- One gradient on the chrome: the active nav pill.
- The logo corner is glass unless the brand requires a fill (logoCorner="fill").

## Pattern: Shell: collapsible icon rail

> The same frame with a panel button that folds the sidebar to a 68px icon rail, remembered across visits.

For dense work screens (tables, boards) where width matters more than labels. The toggle sits at the start of the top bar; storageKey keeps the choice in localStorage, read after mount so the first render matches the server. In the rail each item keeps its title as a tooltip and its count on the icon.

Uses: SidebarShell.

```tsx
<SidebarShell
  collapsible
  storageKey="app-sidebar-collapsed"
  logoCompact={<Mark />}
  navLabel="Main"
  nav={NAV}
  title="Projects"
>
  …
</SidebarShell>
```

- Every nav item needs an icon in a collapsible shell.
- Give the rail a compact mark when the logo is a wide wordmark.

## Pattern: Shell: header only

> No sidebar: the logo, a short horizontal nav and the profile in one frosted top bar, the page below at full width.

For products with five or fewer top-level sections and no deep navigation: settings sites, portals, single-purpose tools. The bar is the same chrome glass and shadow as the sidebar frame, so a product can move between the two without a visual seam.

Uses: SidebarShell.

```tsx
<SidebarShell layout="header" navLabel="Main" nav={NAV} topbarRight={<Avatar name="Jane Cooper" size="sm" />}>
  <PageHeader title="Projects" />
  …
</SidebarShell>
```

- Five sections at most in the bar; past that, use the sidebar.
- No title in the bar: the page's own h1 names it.

## Pattern: Shell: mobile drawer

> On narrow screens the sidebar becomes an off-canvas drawer from a menu button, with a scrim, a focus hold and Esc to close.

Automatic below 900px of the frame's own width (mobileBelow changes it), for the sidebar and rail layouts. The menu button replaces the collapse toggle; opening moves focus into the drawer, the page behind goes inert, and Esc, the scrim or choosing a link closes it and returns focus to the button. mobileDrawer={false} keeps the icon rail instead.

Uses: SidebarShell.

```tsx
// Nothing to add: narrow frames get the drawer.
<SidebarShell navLabel="Main" nav={NAV} title="Projects">…</SidebarShell>

// Preview it open at desktop width:
<SidebarShell contained forceMobile defaultDrawerOpen navLabel="Main" nav={NAV} title="Projects">…</SidebarShell>
```

- The drawer is for narrow frames only, never a desktop pattern.
- Picking a link closes the drawer.

## Pattern: Summary card with cells

> One card of key figures: per cell a label, a big number and a muted line of context, separated by hairlines.

This month at a glance: four or five cells in one row, each a figure and a sentence of context, not a grid of separate cards. The whole set is one surface; hairlines separate the cells. The label sits beside nothing and above only its own figure, never as a stacked title.

Uses: Card, Meter.

```tsx
<Card title="This month" description="Updated hourly">
  <dl className={styles.cells}>
    <div><dt>Invoices paid</dt><dd>32</dd><p>+4 on last month</p></div>
    <div><dt>Active projects</dt><dd>14</dd><p>3 due this week</p></div>
  </dl>
</Card>
```

- One surface with cells, never a bento of cards.
- Every figure has a line that says what it means.

## Pattern: Modal with scroll edges

> A long modal whose header and footer cast shadows only when content passes under them.

The body scrolls; the header and footer do not. useScrollEdges writes data-scrolled and data-more on the panel from a passive listener, and the header and footer draw --scroll-edge-top and --scroll-edge-bottom. Thin tinted scrollbars and contained overscroll come from themedScrollClass. The page behind is locked with useScrollLock.

The same three pieces work for any scroller: ScrollArea bundles them for a region inside a page.

Uses: Modal, ScrollArea, useScrollEdges, useScrollLock.

```tsx
const bodyRef = useRef<HTMLDivElement>(null);
const panelRef = useRef<HTMLDivElement>(null);
useScrollLock(open);
useScrollEdges(bodyRef, { target: panelRef, enabled: open });

<div ref={panelRef} className={styles.panel}>
  <header className={styles.header}>…</header>
  <div ref={bodyRef} className={cx(styles.body, themedScrollClass)}>…</div>
  <footer className={styles.footer}>…</footer>
</div>

/* .panel[data-scrolled] .header { box-shadow: var(--scroll-edge-top); }
   .panel[data-more] .footer { box-shadow: var(--scroll-edge-bottom); } */
```

- Never a JavaScript scrollbar.
- No shadow when there is nothing under the edge.

## Pattern: Terms with scroll-gated accept

> A terms dialog whose Accept stays disabled until the reader has scrolled to the end.

The body scrolls; the footer says "Scroll to the end to accept" and the Accept button is disabled. When the scroll listener sees the far edge (useScrollEdges clears data-more and calls onEnd, surfaced on Modal as onScrollEnd), the hint turns into "You have reached the end" and Accept unlocks. If the terms are short enough not to scroll, it unlocks at once.

The hint is a status region and the disabled button is described by it, so screen reader users hear why it is locked and when it unlocks. Reopening the dialog locks it again.

Uses: Modal, useScrollEdges, Button.

```tsx
const [read, setRead] = useState(false);
const onEnd = useCallback(() => setRead(true), []);

<Modal
  open={open}
  onClose={close}
  size="lg"
  title="Workspace terms"
  onScrollEnd={onEnd} // useScrollEdges: fires when data-more clears
  footerStart={read
    ? <span role="status">You have reached the end</span>
    : <span role="status" id="terms-hint">Scroll to the end to accept</span>}
  footer={
    <>
      <Button variant="secondary" onClick={close}>Not now</Button>
      <Button disabled={!read} aria-describedby={read ? undefined : "terms-hint"} onClick={accept}>Accept terms</Button>
    </>
  }
>
  {terms}
</Modal>
```

- Say why the button is disabled, next to it, and announce the change.
- Gate on reaching the end, never on a timer.
- Keep a way out (Not now) that is always enabled.

## Pattern: Sign-in with multi-factor authentication

> A corporate sign-in: brand mark in the header, the form centred, a shield treatment and a security note in the footer, across the password, MFA code and authenticator setup steps.

AuthLayout paints the deep field and carries the header (the brand mark, a help link) and the footer ("Protected by multi-factor authentication"). One AuthCard sits in the middle per step: the password step with a lock tile, the code step with a shield tile and OtpInput, and the authenticator setup step with a QR code, the text key and a confirming code.

Each step has one full-width primary. The code step auto-verifies on onComplete; the setup step is reached from "Lost your device?" or after a reset. Use the switcher above the preview to see each step.

Uses: AuthLayout, AuthCard, Field, TextInput, OtpInput, Button, Checkbox.

```tsx
<AuthLayout
  header={<><Logo /><a href="/help">Need help?</a></>}
  footer={<><IconShield size={14} /> Protected by multi-factor authentication.</>}
>
  {step === "password" ? (
    <AuthCard icon={<IconLock size={22} />} title="Sign in" subtitle="Use your work email.">
      <Field label="Work email"><TextInput type="email" autoComplete="username" /></Field>
      <Field label="Password"><TextInput type="password" revealable autoComplete="current-password" /></Field>
      <Button size="lg" fullWidth onClick={next}>Continue</Button>
    </AuthCard>
  ) : step === "code" ? (
    <AuthCard icon={<IconShield size={22} />} title="Enter your code" subtitle="Open your authenticator app.">
      <OtpInput aria-label="Authentication code" value={code} onChange={setCode} onComplete={verify} />
      <Button size="lg" fullWidth disabled={code.length < 6}>Verify</Button>
    </AuthCard>
  ) : (
    <AuthCard width="md" icon={<IconShield size={22} />} title="Set up your authenticator">
      <QrCode value={otpauthUrl} />
      <code>{secret}</code>
      <OtpInput aria-label="Code from your authenticator app" value={code} onChange={setCode} />
      <Button size="lg" fullWidth>Turn on two-step sign-in</Button>
    </AuthCard>
  )}
</AuthLayout>
```

- One primary per step, full width, size lg.
- Errors in an ErrorSummary above the form on submit.
- Keep an admin sign-in on its own route, never a toggle on the public one.
- Never ask for the code anywhere but this screen; say so in the footer.