# Dowel — full reference

Generated from @dowel-ui/react@0.8.0. Canonical source: https://dowel-eight.vercel.app

---

# Dowel — conventions

Rules for writing code in this project. Dowel is **source-first**: its
components are files in this repository, not a dependency you can reason about
from its README. They are yours to edit, and edits are preserved across updates.

## The rule that matters most

**Do not hand-write a component that Dowel already has.** Check the
catalogue in `components.md` first. Writing a second Button — with different
focus rings, different disabled semantics, different tokens — is the single
most common and most damaging thing to do here.

## Adding a component

```bash
npx @dowel-ui/cli add <name>
```

This writes the source into the project and installs whatever it depends on.
`add` is safe to re-run: an untouched file is left alone, an edited one is
never overwritten without `--overwrite`.

Do not `npm install` a component. Do not copy source out of the documentation
by hand — the CLI resolves the dependency graph and rewrites imports to this
project's path alias, and doing it manually gets both wrong.

## Importing

```tsx
import { Button, Card, CardContent } from "@dowel-ui/react";
```

## Styling

- Use semantic tokens (`bg-background`, `text-foreground`, `border-border`, `ring-ring`, `bg-primary`, `text-muted-foreground`). Never raw hex, and never Tailwind's own palette (`bg-slate-900`, `text-gray-500`) — those do not follow the theme and break every preset and dark mode.
- Spacing, radius and type come from the scale. `rounded-md` and `rounded-lg` re-proportion with `--radius-scale`; an arbitrary `rounded-[7px]` does not.
- Durations derive from `--motion-scale`. Do not hardcode transition timings.
- Compose class names with `cn()` from the project's utils, so consumer overrides win over defaults.

## Accessibility

Targeted at WCAG 2.2 AA, verified with axe per component. Where Dowel
differs from what you have seen in other libraries:

- A loading `Button` uses `aria-disabled` + `aria-busy` and guards its own click handler. Never add `disabled` to it — disabling a control mid-action strands keyboard focus.
- `Alert` is not a live region by default. One that exists on first paint announces for no reason. Opt in with `live="polite"` or `live="assertive"` only when the alert appears in response to something.
- `Separator`, `Skeleton` and `Spinner` are decorative and stay out of the accessibility tree unless given a label. Do not add `role` or `aria-label` to them by reflex.
- `PopoverContent` carries `role="dialog"` and warns in development without an accessible name. Always give it `aria-label` or `aria-labelledby`.
- Never use colour as the only signal. The `monochrome` preset exists as a standing check on exactly this — if a state is unreadable under it, the component is wrong.

## Before you build a page

Check `components.md` for a **block** that already covers it. A block is a
whole section — a login form, a settings page, a chat surface — and installing
one brings every component it is assembled from. Building a dashboard out of
individual primitives when `add dashboard` exists is wasted work.

## Reference

- Documentation: https://dowel-eight.vercel.app
- Full text for models: https://dowel-eight.vercel.app/llms-full.txt

---

# Dowel — catalogue

184 components and 51 blocks, generated from `@dowel-ui/react@0.8.0`. This is the complete list — anything not here does not exist.

## Foundation

- **button** — Triggers an action or event, with variants for every level of emphasis.
- **direction** — Tells the component primitives which way the writing runs, so menus and sliders mirror with the rest of the page.

## Forms

- **animated-checklist** — A task list whose boxes fill with a bounce and whose done tasks fade and strike through, with an add row. _(beta)_
- **app-stack** — A pile of app icons that fans out on hover and opens into a multi-select picker whose icons fly to their tiles. _(beta)_
- **assignee-picker** — A pill of overlapping faces that opens a multi-select list of people; new faces fly into the stack. _(beta)_
- **calendar** — A date grid for selecting a day, several days or a range.
- **checkbox** — A control for an on/off choice, with support for an indeterminate state.
- **combobox** — A searchable single-select built on the ARIA combobox pattern.
- **confirm-typed** — Type the name to confirm — and be told, not ignored, when it does not match.
- **copy-button** — Copies a value to the clipboard and morphs its icon and label into a confirmation that reverts on its own. _(beta)_
- **cron-editor** — A schedule as a cron expression, with a plain-language reading and the next runs.
- **date-picker** — A button that opens a calendar to pick a date or a date range.
- **dial** — A rotary dial input — a knob inside a filling arc with detent ticks — turned by drag, wheel or keys. _(beta)_
- **dot-morph-button** — A pill button led by a dot that stretches into a bar on hover and keyboard focus. _(beta)_
- **drag-stepper** — A pill number stepper: tap − or + to step, or hold either one to stretch into a sweep and drag to scrub. _(beta)_
- **effect-button** — A Button with a hover and focus micro-interaction — slide-arrow, pulse, rotate, shake, glare, text reveal, expanding ring or clip corners. _(beta)_
- **expanding-search** — A search button that opens into a field, clears, and collapses back with Escape — ready for a combobox. _(beta)_
- **exposure-slider** — A camera-style exposure dial: a draggable ruler of notches under a fixed centre mark, with a value ring. _(beta)_
- **file-upload** — A dropzone over a real file input, plus the upload queue nobody ships.
- **form** — Accessible field wiring that works with any form library, or none.
- **image-selector** — A photo grid with a Select mode: tick photos, see the count, share or delete them, and reset. _(beta)_
- **inline-confirm** — A destructive button that asks in place — it widens into Keep / Delete, then offers a timed Undo. _(beta)_
- **input** — A single-line text field with size variants and native validation styling.
- **label** — An accessible caption that associates text with a form control.
- **liquid-toggle** — A switch whose knob squashes like a droplet as it travels, and can be dragged across. _(beta)_
- **magnetic-button** — A button that drifts toward the pointer — optionally with its label leaning further — and springs back when it leaves. _(beta)_
- **magnetic-select** — A honeycomb of round chips: choosing one grows it and magnetically shoves the rest apart, tilted, with a springy settle. _(beta)_
- **morph-button** — A button whose icon and label morph to an active state — toggles, transient confirmations and hover affordances. _(beta)_
- **notify-button** — A “notify me” toggle: the bell rings and the label grows elastically into the confirmation. _(beta)_
- **otp-input** — A one-time-code field drawn as a row of animated slots — paste, SMS autofill, masking and grouping included. _(beta)_
- **radio-group** — A set of mutually exclusive options.
- **range-dial** — A 24-hour circular two-thumb range — drag or key the start and end round a ticked clock face, with the duration in the middle. _(beta)_
- **reorder-list** — A short list of people or things you put in order by dragging liquid pills, or with Space and the arrow keys. _(beta)_
- **scrubber** — A design-tool number field: drag across a labelled bar to scrub a value, step it from the keyboard, or type it. _(beta)_
- **secret-field** — An API key in its three states: shown once, hidden but revealable, and gone.
- **select** — Picks one value from a short list of options.
- **selection-list** — A multi-select list of people with a liquid tick and an action that springs out from under it once someone is picked. _(beta)_
- **shortcut-recorder** — Press the keys you want: records a chord, platform-aware, and says when it clashes.
- **slide-to-confirm** — A track whose grip you slide to the end to confirm — bencho's wash-and-morph pill or SmoothUI's power-off slide — with a press-and-hold path. _(beta)_
- **slider** — Selects a value, or a range, from a continuous span.
- **slosh-slider** — A slider whose fill behaves like liquid: the knob jumps to the value while the fill springs after it, leaning as it moves. _(beta)_
- **social-selector** — Pick a social platform from a row of icons — a pill slides behind the choice and the caption links to the profile. _(beta)_
- **switch** — An immediate on/off toggle for settings that apply straight away.
- **tags-input** — A list of short values, where invalid entries stay visible instead of vanishing.
- **textarea** — A multi-line text field, with optional auto-resize and a character count that knows when to stay quiet.
- **time-range-picker** — A time range whose value is an expression, so it stays relative across a reload.

## Overlays

- **account-menu** — An avatar that opens an account panel of collapsible sections — edit the profile, check recent orders. _(beta)_
- **context-menu** — A right-click menu that pops from the pointer with a spring and staggers its items in — same parts as Dropdown Menu. _(beta)_
- **dialog** — A modal window that interrupts the user to gather a response.
- **drawer** — A bottom sheet that can be dismissed by dragging it down.
- **dropdown-menu** — A menu of actions revealed from a trigger, with submenus and selectable items.
- **gooey-popover** — A round trigger whose popover pours out of it, melted together by an SVG goo filter. _(beta)_
- **morph-surface** — A dock that grows in place into a panel — a feedback form or a quick prompt — and shrinks back when done. _(beta)_
- **popover** — Rich floating content anchored to a trigger.
- **rich-popover** — A popover card for an inline reference — heading or link, description, a meta chip and one call to action. _(beta)_
- **sheet** — A panel that enters from an edge of the viewport for secondary content.
- **tooltip** — A short label revealed on hover or keyboard focus.

## Navigation

- **breadcrumb** — Where the current page sits in the hierarchy, and how to get back up it.
- **browser-tabs** — A miniature browser window whose tabs are a real tablist: a card-coloured leaf springs under the active tab, and tabs reorder by drag or keyboard. _(beta)_
- **canvas-toolbar** — A Figma-style tool rail: one active tool with a springy fill, a shape slot that swaps its tool from a flyout, and single-key shortcuts. _(beta)_
- **command** — A searchable command palette, with groups and a ⌘K dialog variant.
- **create-menu** — A DropdownMenu with a morph flourish: a "+ Create" pill that grows in place into its menu panel. _(beta)_
- **focus-blur-links** — A row of links where hovering or focusing one blurs and dims the rest, with an optional dashed bracket. _(beta)_
- **goo-tabs** — Dowel Tabs with a motion flourish: an icon bar whose pill stretches over the old and new tab, then snaps onto the new one, melted together by an SVG goo filter. _(beta)_
- **magnify-dock** — A macOS-style dock whose icons grow, lift and show a label as the pointer or keyboard focus passes over them. _(beta)_
- **pagination** — Navigation between pages of a list.
- **radial-menu** — A round button whose options fan out along an arc: press and drag onto one, click, or walk the ring with the keyboard. _(beta)_
- **sidebar** — The application's own navigation: a collapsible rail on a wide screen, an overlay on a narrow one.
- **stepper** — A multi-step wizard's progress — connectors fill, finished steps draw a check, and each step's content slides in from the side it comes from. _(beta)_
- **tabs** — Switches between panels of related content.

## Display

- **action-node** — A workflow node card whose round action buttons spring out in an arc around its top-end corner on hover or from a More actions trigger. _(beta)_
- **aspect-morph** — A picture that smoothly reshapes between aspect ratios, picked from a segmented control with a sliding thumb. _(beta)_
- **avatar** — An image representation of a user or entity with a graceful text fallback.
- **avatar-group** — Overlapping avatars that spread apart on hover or keyboard focus, collapsing the rest into a "+N" count. _(beta)_
- **badge** — A compact marker for status, counts and categories.
- **book** — A 3D book cover drawn in CSS that tilts, or swings open to reveal its first page, on hover and keyboard focus. _(beta)_
- **card** — A surface that groups related content and actions into a single block.
- **card-spread** — A stack of cards that fans into an arc, row, corner fan, stamp arc, cascade, dealt hand or wheel on hover, focus or click. _(beta)_
- **card-stack** — A pile of cards you step through as a receding deck, or that fans out into an arc on hover and focus. _(beta)_
- **carousel-3d** — A 3D carousel of cards — a fanned arc or a CoverFlow path — with buttons, dots, arrow keys and swipe. _(beta)_
- **comment-bubble** — A canvas comment pin — an avatar in a speech-bubble corner that grows into the thread and a reply composer. _(beta)_
- **expandable-cards** — Cards that open into a detail view — widening in place in a row, or growing out of a grid into a modal. _(beta)_
- **expandable-list** — A list of compact rows — jobs, releases, people — each growing into a detail dialog out of its place in the list. _(beta)_
- **glow-card** — Card surfaces with a soft glow that follows the pointer, alone or continuously across a group. _(beta)_
- **image-accordion** — Image panels in a row — the open one widens and shows its caption, the rest stand as narrow strips — opened by hover, focus or press. _(beta)_
- **image-metadata** — An image with a row of actions and a details button that opens a metadata panel, lifting the image to make room. _(beta)_
- **invite-carousel** — Event invitations fanned out as tilted cards — the current one upright in front, its neighbours leaning behind — advancing on a timer or by hand. _(beta)_
- **island** — A pill that morphs between views — idle, a call, a timer, a player — resizing around whatever it shows. _(beta)_
- **marquee** — Scrolls its children in a seamless, endless loop — horizontal or vertical, at a set speed, pausing on hover and focus. _(beta)_
- **now-playing** — A compact music mini-player that expands in place, with a morphing play button, a like and a seek slider. _(beta)_
- **number-flow** — A number whose digits roll to each new value — counters, prices, percentages and compact figures, formatted by Intl.NumberFormat. _(beta)_
- **photo-stack** — A pile of photos: flick the top one away and it springs to the back, or tap, key or button through them. _(beta)_
- **photo-tabs** — A photo with a floating bar of icon tabs; each tab swaps the photo. _(beta)_
- **pixel-avatar** — A deterministic pixel avatar generated from a seed — crisp SVG, coloured from theme tokens, with a gentle shimmer. _(beta)_
- **product-card** — A shop tile with image zoom, badge, half-star rating, discount pricing, a wishlist toggle and an add-to-cart confirmation. _(beta)_
- **reviews-carousel** — Testimonials stacked in depth — the active review in front, the next ones receding behind — stepped through with buttons, indicators or arrow keys. _(beta)_
- **star-count** — An animated star counter — plain or as a star button — with the stargazers' avatars beside it. The count is a prop; nothing is fetched. _(beta)_
- **swipe-carousel** — Cards on a ring seen from the front — swipe, tap or step and the ring turns, so nothing ever leaves the frame. _(beta)_
- **switchboard-card** — A feature card illustrated by a grid of tiny lights — a lit pattern such as a word, or random flicker. _(beta)_
- **tilt-card** — A card that tilts in 3D toward the pointer, with a glare that follows it and layers that float at their own depth, springing back flat on leave. _(beta)_
- **time-stack** — Cards receding in depth, stepped through with a timeline scrubber, the mouse wheel or the arrow keys. _(beta)_
- **todo-tower** — To-do cards stacked like bricks: tick one and it flicks away as the cards above drop; drag one and the stack sways. _(beta)_
- **tweet-card** — A social post drawn from props — author, text, photos, date and counts — with a link out to the original. No network, no embed script. _(beta)_

## Data

- **accordion** — Vertically stacked sections that expand to reveal their content.
- **activity-feed** — A chronological list of events, with a connecting timeline rail.
- **code-block** — A block of code with a copy control, ready for any highlighter.
- **contribution-graph** — A GitHub-style year heatmap of daily counts — a keyboard-navigable grid with a tooltip per day. _(beta)_
- **data-table** — Presentation for a TanStack Table instance: sorting, column visibility and pagination.
- **diff-viewer** — A diff you can style, and accept or reject hunk by hunk.
- **dither-area** — An area chart filled with dithered cells over a cell grid, with a date scrubber that swells the cells around it. _(beta)_
- **dither-bar** — Stacked bars drawn in dithered cells that grow on change, with series highlighting on hover and a per-column readout. _(beta)_
- **dither-canvas** — The engine behind the dither charts: a DPR-capped, self-pausing canvas loop, token colours, a deterministic cell hash, springs, geometry and a keyboard scrubber. _(beta)_
- **dither-donut** — A donut chart drawn in shimmering dithered cells, with wedges that pop out and sparkle on hover, focus or pin. _(beta)_
- **dither-funnel** — A conversion funnel of dithered stage bars that morph between periods, with overall and step conversion per stage. _(beta)_
- **dither-gauge** — A half-circle gauge drawn in dithered cells, one sweeping ring per metric, with a centre reading and metric switch. _(beta)_
- **dither-heatmap** — A rows × columns intensity grid drawn in dithered tiles that morph between periods, with a keyboard-navigable cell readout. _(beta)_
- **dither-line** — A smooth monotone line over a drifting dithered gradient fill, with a keyboard-operable point scrubber. _(beta)_
- **dither-meter** — A capacity bar drawn in dithered cells, split into categories that fill with a spring, with a category legend. _(beta)_
- **dither-scatter** — A bubble scatter drawn in dithered cells: floating bubbles sized by value that glide between data sets, with a per-point readout. _(beta)_
- **dns-record** — Add this record at your provider: parts copied separately, checked with what was found.
- **log-viewer** — A streaming console with filtering, level facets and follow mode.
- **metric-delta** — A headline number with a change indicator that knows which direction is good.
- **permission-matrix** — Roles across, permissions down, with inheritance, locked roles and one tab stop.
- **record-diff** — Field-level before and after, for audit entries, settings history and revisions.
- **table** — Semantic table primitives for tabular data.
- **tick-progress** — A percentage drawn as a row of waveform ticks under a big figure — a progress bar, or a slider with hover preview. _(beta)_
- **uptime-matrix** — A day-by-day status history drawn in dithered tiles — operational, degraded, outage — with a keyboard-navigable readout and legend. _(beta)_

## Feedback

- **alert** — A callout that draws attention to an important message.
- **bar-loader** — Indeterminate loading indicators made of bars — cascade, equalizer, wave physics, an indeterminate sweep and 17 more motions. _(beta)_
- **dots-loader** — Indeterminate loading indicators made of dots — pulse, bounce, ripple, orbit and 21 more motions. _(beta)_
- **empty-state** — Shown where content would be, explaining why it is empty and what to do next.
- **grid-loader** — Indeterminate loading indicators on a grid of cells — 48 patterns (and 17 SmoothUI alias names) that pulse or stagger, plus sequence, thinking and matrix. _(beta)_
- **meter** — A measurement against a capacity — quota, seats, spend — segmented by category.
- **notification-badge** — A dot, rolling count or presence badge pinned to the corner of an icon, button or avatar. _(beta)_
- **progress** — Shows how far along a task is, or that one is running at all.
- **pull-to-refresh** — A sheet you pull down to refresh, with rubber-band resistance, a dot ring that fills as you pull and springs that carry the pull's velocity. _(beta)_
- **ring-loader** — Indeterminate loading indicators made of rings and spinners — classic, sweep, radar, gears and 26 more motions. _(beta)_
- **session-expiry** — The idle-timeout warning WCAG 2.2.1 asks for: warned, extendable, and not dismissable by accident.
- **shape-loader** — Indeterminate loading indicators made of geometric shapes — flipping squares, hexagons, hourglasses, hearts and 31 more motions. _(beta)_
- **skeleton** — A shaped placeholder that holds layout while content loads.
- **spinner** — An indeterminate loading indicator for buttons, panels and inline content.
- **sync-status** — Offline, saving, saved or failed — with the count of changes being held.
- **text-loader** — Indeterminate loading indicators made of words and interface shapes — shimmer, typing, skeleton, terminal and 15 more motions. _(beta)_
- **toast** — Brief, non-blocking messages with an imperative API callable from anywhere.

## Layout

- **collapsible** — A single section that opens and closes, without an accordion's set semantics.
- **separator** — A horizontal or vertical rule that divides content.

## AI

- **ai-action-ledger** — What an agent actually did, classified by what can be undone.
- **ai-agent-plan** — What an agent intends to do — including when it changes its mind mid-run.
- **ai-agent-status** — A pill showing what an agent is doing, in words as well as colour.
- **ai-approval-request** — Approve a tool call — after correcting the arguments the model got wrong.
- **ai-artifact** — A titled frame for something the model produced, with preview and code panes that slide along one axis and a copy action. _(beta)_
- **ai-branch** — Alternative versions of a conversation turn — regenerated answers, edited prompts — with a wrapping pager between them. _(beta)_
- **ai-conversation** — The scrolling transcript container, with follow-on-new-content and a status region.
- **ai-disclosure** — Tells a reader they are looking at AI, and what is actually known about it.
- **ai-extraction-review** — Check extracted fields against the document they came from, and decide each one.
- **ai-inline-completion** — Ghost-text suggestion inside a real textarea, accepted with Tab. _(beta)_
- **ai-loader** — A labelled AI waiting indicator — thinking dots, an indeterminate bar or a thinking grid — with an optional elapsed-seconds counter. _(beta)_
- **ai-message** — One turn in a conversation, with role, avatar, actions and footer slots.
- **ai-model-selector** — Picks the model a conversation runs on, with descriptions and availability.
- **ai-prompt-input** — The composer: auto-growing textarea, send-on-Enter, and a send/stop control.
- **ai-reasoning** — A collapsible disclosure for the model's reasoning.
- **ai-response** — Assistant response text, with a streaming caret and a thinking indicator.
- **ai-sources** — Inline citation markers and the source list they refer to.
- **ai-structured-output** — An object arriving field by field from the model, without the layout jumping.
- **ai-suggested-value** — An AI-proposed value for any form control, pending until accepted and marked afterwards.
- **ai-suggestions** — Prompt suggestion chips for a chat's empty state or follow-ups, arriving from the centre of the row outwards. _(beta)_
- **ai-token-usage** — A gauge showing how much of the context window a conversation has used.
- **ai-tool** — A collapsible record of a tool the model called, its arguments and its result.
- **command-bar** — A compact one-row prompt bar — auto-growing field, dictate toggle and send — composed from AI Prompt Input. _(beta)_
- **orb-face** — A cartoon assistant orb whose gaze follows the pointer, who blinks, and whose expression tells its state — listening, thinking, speaking, done or broken. _(beta)_

## Effects

- **cursor-follow** — A dot that trails the pointer on a spring inside a container and swells into a label over marked elements. _(beta)_
- **escape-button** — A novelty button that scoots away from an approaching mouse, then gives up after a few escapes. _(beta)_
- **folding-frame** — A photo folded shut like a book in 3D — drag across it (or use the keys) to open the cover until it lies flat. _(beta)_
- **glass-bubble** — A draggable glass lens that refracts the content under it, with a specular highlight and chromatic fringing. _(beta)_
- **goo-ball** — A decorative jelly ball you drag around a well: it stretches along its velocity and squashes against the walls. _(beta)_
- **gradient-orb** — An animated gradient orb — a rotating conic mesh with a dot screen, sheen and bloom — that can follow an AI state and a live audio level. _(beta)_
- **palette-generator** — A row of swatches that melt together through a goo filter and pop back out in a new palette. _(beta)_
- **scramble-text** — Text whose characters churn through random glyphs and resolve from the inline start, on hover, focus, mount or view. _(beta)_
- **scroll-reveal-text** — A paragraph whose words brighten from dim to full as it scrolls through the viewport. _(beta)_
- **shader-transition** — Transitions a frame between two states under a full-frame WebGL reveal — one raw-WebGL engine and sixteen presets (aperture, chroma, prism, SDF blobs and circles, noise, wipe, stripes, spiral…). _(beta)_
- **shimmer-text** — Text with a light band sweeping across it on a loop, or a blur-and-glide entrance as it arrives. _(beta)_
- **text-effect** — Text that animates in by character, word or line — blur, rise, mask, spring, centre-out, phrase builds and a wave, as 19 presets. _(beta)_
- **text-swap** — Text that animates from the old string to the new one when its value changes — fade through, shared axis X/Y/Z and per-word crossfade — with a TextRotate for cycling phrases. _(beta)_
- **typewriter-text** — Types text a character at a time behind a blinking caret — once, on a loop, or cycling through a list. _(beta)_

## Blocks

Whole sections. Installing one installs every component it is built from.

- **admin-dashboard** — An administration console: the shell every admin page shares — navigation, breadcrumb, account menu — and the overview that is its front page, with what needs attention first. _(resolves 11 components)_
- **admin-users** — A team administration table with filtering, sorting and per-row actions. _(resolves 8 components)_
- **agent-console** — One agent run, watched: the plan it is working from, the approval it is blocked on, and the ledger of what it has already done. _(resolves 8 components)_
- **ai-chat** — A complete chat surface: transcript, reasoning, tool calls, sources and composer. _(resolves 11 components)_
- **ai-dashboard** — What the AI features cost and whether they worked: tokens, spend, failure rate, a breakdown by model, and the runs still going. _(resolves 6 components)_
- **ai-workspace** — A whole AI application surface: conversations down one side, the active transcript with reasoning, tool calls and sources in the middle, and the context — window usage, attachments and a structured result — on the other. _(resolves 13 components)_
- **analytics** — An analytics page: headline metrics against the previous period, a series over time, and the breakdown that made it up. _(resolves 5 components)_
- **billing** — A billing page: the current plan, metered usage against its limits, the payment method and the invoice history. _(resolves 6 components)_
- **command-center** — Operations at a glance: service health worst-first, open incidents by severity, capacity meters, a filterable log stream, and a command palette for every action an operator reaches for. _(resolves 8 components)_
- **crm** — A sales pipeline: open value by stage, the deals in it with filtering and sorting, the win rate and cycle length, and the last few touches. _(resolves 12 components)_
- **cta-banner** — A compact banner call to action: headline, one line of copy and a single action. _(resolves 2 components)_
- **cta-centered** — A centred call to action with two actions on a muted band with a soft glow. _(resolves 1 components)_
- **cta-split-image** — A two-column call to action whose copy and image slide in from either side. _(resolves 1 components)_
- **dashboard** — An overview page with headline metrics and a recent activity feed. _(resolves 4 components)_
- **faq-accordion** — Frequently asked questions as bordered cards, one answer open at a time. _(resolves 1 components)_
- **faq-categorized** — Frequently asked questions in topic tabs, each topic an accordion of answers. _(resolves 2 components)_
- **faq-searchable** — Frequently asked questions filtered by a search field as you type. _(resolves 3 components)_
- **faq-tabbed-grid** — Frequently asked questions in category tabs, each category a grid of always-visible answers. _(resolves 1 components)_
- **features-alternating** — Feature rows that alternate copy and media from side to side, each sliding in from its own side as it scrolls into view.
- **features-bento** — A bento grid of features: a two-by-two lead cell carrying a visual — by default a small analytics panel whose bars grow in — among smaller cells. _(resolves 2 components)_
- **features-icon-grid** — A features section: a grid of cards, each an icon, a title and a sentence, rising into view as the page scrolls. _(resolves 1 components)_
- **footer-mega** — A mega footer: logo, four link columns and a newsletter sign-up, over a copyright and social bar. _(resolves 3 components)_
- **footer-minimal** — A one-row footer: logo and copyright, a few links, and social links.
- **footer-newsletter** — A site footer with a newsletter sign-up and social links beside four columns of links. _(resolves 3 components)_
- **footer-simple** — A site footer with the brand and social links beside three columns of links.
- **forgot-password** — A password reset request, with a confirmation that does not leak account existence. _(resolves 5 components)_
- **hero-grid** — A centred hero over a grid of squares that light up under the pointer. _(resolves 2 components)_
- **hero-minimal** — A quiet hero: a headline whose letters draw together, one line of copy and a text link. _(resolves 1 components)_
- **hero-perspective-grid** — A centred hero over a tilted 3D plane of tiles that light up under the pointer. _(resolves 2 components)_
- **hero-product** — A centred hero with an announcement, headline and two calls to action over a large product screenshot. _(resolves 3 components)_
- **hero-split-image** — A two-column hero with a headline, reviewer avatars, a star rating and calls to action beside an image. _(resolves 3 components)_
- **hero-spotlight** — A dark hero lit by a spotlight beam that opens as it scrolls into view. _(resolves 1 components)_
- **login** — A sign-in form with validation, social providers and a busy state. _(resolves 7 components)_
- **logo-cloud-simple** — A heading, a line of copy and a still grid of customer logos, dimmed until hovered or focused.
- **logo-grid-tooltips** — A panel of grayscale logos that lift into colour and name themselves in a tooltip on hover or focus, in three to six columns. _(resolves 1 components)_
- **logo-links-marquee** — A heading over an endless row of large, linked logos that pop in one after another and tilt on hover, with a pause control. _(resolves 2 components)_
- **logo-marquee** — A heading over a quiet, dimmed marquee of logos with a named speed, a direction and a pause control. _(resolves 2 components)_
- **onboarding** — A setup checklist: what is done, which step is current, and what is blocked and why. _(resolves 4 components)_
- **pricing** — A pricing section with plan cards and a monthly/yearly toggle. _(resolves 5 components)_
- **pricing-single-plan** — One plan with every feature, under a monthly/annual switch with a price that rolls. _(resolves 6 components)_
- **pricing-three-tier** — Three plans side by side, the middle one featured, under a monthly/annual switch with prices that roll. _(resolves 6 components)_
- **pricing-two-tier** — A free plan beside a featured paid one, under a monthly/annual switch with prices that roll. _(resolves 6 components)_
- **settings** — A settings page with a profile form, immediate toggles and a danger zone. _(resolves 10 components)_
- **signup** — An account creation form with a password strength hint and terms acceptance. _(resolves 6 components)_
- **stats-grid** — A heading over a row of big figures, each with a label and a line of context, whose digits roll up from zero as the row scrolls into view. _(resolves 2 components)_
- **stats-trend-cards** — Metric cards with an icon, a figure that rolls up from zero, a label, a line of context and a trend stated in words. _(resolves 3 components)_
- **team-carousel** — A large two-tone heading over a swipeable carousel of team member cards — avatar, name, role and a line under a divider — with previous and next buttons. _(resolves 3 components)_
- **team-grid** — A heading over a grid of team members — a large portrait, name, role, location and bio — rising in one after another. _(resolves 1 components)_
- **testimonial-rotator** — One large quotation at a time, rotating on a timer shown by a filling indicator, with a stop/start control. _(resolves 2 components)_
- **testimonial-spotlight** — A heading beside one testimonial at a time, stepped through with previous and next. _(resolves 3 components)_
- **testimonial-star-grid** — Reviews in a grid, each with a star rating, the quotation and its author. _(resolves 1 components)_

---

# Dowel — AI components

24 surfaces for AI features. Reach for these before building
anything custom for a model-facing interface.

Most component sets ship a chat transcript and stop. Real AI features are
extraction, enrichment, autofill and agents that *change things* — so the parts
that matter are the ones around the transcript, not the transcript itself.

- **ai-action-ledger** — What an agent actually did, classified by what can be undone.
- **ai-agent-plan** — What an agent intends to do — including when it changes its mind mid-run.
- **ai-agent-status** — A pill showing what an agent is doing, in words as well as colour.
- **ai-approval-request** — Approve a tool call — after correcting the arguments the model got wrong.
- **ai-artifact** — A titled frame for something the model produced, with preview and code panes that slide along one axis and a copy action.
- **ai-branch** — Alternative versions of a conversation turn — regenerated answers, edited prompts — with a wrapping pager between them.
- **ai-conversation** — The scrolling transcript container, with follow-on-new-content and a status region.
- **ai-disclosure** — Tells a reader they are looking at AI, and what is actually known about it.
- **ai-extraction-review** — Check extracted fields against the document they came from, and decide each one.
- **ai-inline-completion** — Ghost-text suggestion inside a real textarea, accepted with Tab.
- **ai-loader** — A labelled AI waiting indicator — thinking dots, an indeterminate bar or a thinking grid — with an optional elapsed-seconds counter.
- **ai-message** — One turn in a conversation, with role, avatar, actions and footer slots.
- **ai-model-selector** — Picks the model a conversation runs on, with descriptions and availability.
- **ai-prompt-input** — The composer: auto-growing textarea, send-on-Enter, and a send/stop control.
- **ai-reasoning** — A collapsible disclosure for the model's reasoning.
- **ai-response** — Assistant response text, with a streaming caret and a thinking indicator.
- **ai-sources** — Inline citation markers and the source list they refer to.
- **ai-structured-output** — An object arriving field by field from the model, without the layout jumping.
- **ai-suggested-value** — An AI-proposed value for any form control, pending until accepted and marked afterwards.
- **ai-suggestions** — Prompt suggestion chips for a chat's empty state or follow-ups, arriving from the centre of the row outwards.
- **ai-token-usage** — A gauge showing how much of the context window a conversation has used.
- **ai-tool** — A collapsible record of a tool the model called, its arguments and its result.
- **command-bar** — A compact one-row prompt bar — auto-growing field, dictate toggle and send — composed from AI Prompt Input.
- **orb-face** — A cartoon assistant orb whose gaze follows the pointer, who blinks, and whose expression tells its state — listening, thinking, speaking, done or broken.

## Choosing between them

- Rendering a conversation → `ai-conversation` with `ai-message` and `ai-response`.
- The composer → `ai-prompt-input`, with `ai-model-selector` if the model is switchable.
- A tool the model called → `ai-tool`. Its arguments and result belong there, not in prose.
- Asking permission *before* a tool runs → `ai-approval-request`.
- Reporting what it did *after* → `ai-action-ledger`, which is also where reversibility belongs. A deletion can be undone, a refund can only be offset, a sent email cannot be taken back — the ledger is where that distinction is shown.
- An object streaming in field by field → `ai-structured-output`, which reserves layout up front so nothing jumps.
- Ghost text in a real textarea → `ai-inline-completion`. Escape always returns Tab to focus management, so a keyboard user is never trapped.
- A value the model proposes for a form field → `ai-suggested-value`.
- Reviewing what was pulled out of a document → `ai-extraction-review`.
- Long-running work → `ai-agent-status` and `ai-agent-plan`.
- Where an answer came from → `ai-sources`. Cost → `ai-token-usage`. Chain of thought → `ai-reasoning`.

## Whole surface at once

```bash
npx @dowel-ui/cli add ai-chat
```

---

# Dowel — theming

Tokens are two-tier. **Tier 1** is raw scales: an OKLCH neutral ramp, a radius
ladder, a 15px-base type scale, elevation, motion. **Tier 2** is semantic
aliases — `--primary`, `--background`, `--border`, `--ring` — and components
consume Tier 2 *exclusively*.

Re-skinning the system means reassigning Tier 2. It never means editing a
component file. If you find yourself changing a colour inside a component, the
change belongs in the token layer instead.

## Presets

`default`, `ocean`, `emerald`, `violet`, `rose`, `amber`, `monochrome`,
`candy`, `indigo`, `blue`, `red`, `orange`, `green`.

```html
<html data-theme="ocean" class="dark">
```

`data-theme` selects the preset; the `dark` class selects the mode. They are
independent — every preset works in both.

`monochrome` is not only a style. It is a standing check that no component uses
colour as its only signal, so verify new work under it.

## Two properties that re-proportion everything

- `--radius-scale` — one multiplier behind every corner in the system. `1` is the designed default, `0` is fully square.
- `--motion-scale` — one multiplier every duration derives from. Under `prefers-reduced-motion` it collapses, but indicators that report ongoing state are *slowed* rather than stopped via `--motion-scale-indicator`, because a frozen spinner reads as a hung application.

## Contrast

All semantic pairs are verified against WCAG 2.2 AA across both modes and every
preset, in CI. A new token pair has to pass the same check — do not introduce
one without running `audit:contrast`.

---

# Per-component detail

## Accordion `accordion`

Vertically stacked sections that expand to reveal their content.

- Category: Data · Status: stable
- Install: `add accordion`
- npm: radix-ui
- Accessibility: Each trigger is a button inside a heading, so screen reader users can navigate the sections by heading. aria-expanded and aria-controls tie the trigger to its panel, and arrow keys move between triggers.

## Account Menu `account-menu`

An avatar that opens an account panel of collapsible sections — edit the profile, check recent orders.

- Category: Overlays · Status: beta
- Install: `add account-menu`
- Also installs: avatar, button, input, label, popover, progress
- Accessibility: The avatar trigger is named "Account menu for <name>" and opens Dowel's Popover: a role="dialog" labelled by the user's name, with focus moved inside, Escape and outside-press dismissal and focus returned to the trigger. It is deliberately not role="menu": sections contain form fields. Each section is a disclosure button (aria-expanded, aria-controls) revealing a named region that is inert while collapsed. Form fields are labelled; order progress bars and view buttons name their order. Transitions stop under reduced motion.

## Action Node `action-node`

A workflow node card whose round action buttons spring out in an arc around its top-end corner on hover or from a More actions trigger.

- Category: Display · Status: beta
- Install: `add action-node`
- Also installs: avatar, tooltip
- npm: class-variance-authority
- Accessibility: Hover opens the fan, and so does the "More actions" trigger (aria-expanded, aria-controls), which is revealed on hover and keyboard focus and always shown on devices without hover. Enter, Space or ArrowDown on it open the fan and focus the first action. The fan is role="toolbar" (named by toolbarLabel) with a roving tab stop: the arrow keys move along the arc (Left/Right mirrored in right-to-left layouts) with wrap-around, Home/End jump to the ends, and Escape closes it and returns focus to the trigger. Closed, the fan is inert and aria-hidden, so tucked buttons are neither focusable nor announced. Every action is an icon button named by aria-label and repeated in a tooltip. The hover bridge is aria-hidden; the springs are CSS transitions that settle at once under reduced motion.

## Activity Feed `activity-feed`

A chronological list of events, with a connecting timeline rail.

- Category: Data · Status: stable
- Install: `add activity-feed`
- npm: radix-ui
- Accessibility: An ordered list, so position and count are announced — the order is the meaning here. The rail and the indicators are decorative; the item text has to say what happened. ActivityTime requires a machine-readable dateTime, because a relative label like "2 hours ago" is ambiguous outside the moment it was rendered.

## AI Action Ledger `ai-action-ledger`

What an agent actually did, classified by what can be undone.

- Category: AI · Status: stable
- Install: `add ai-action-ledger`
- npm: class-variance-authority, radix-ui
- Accessibility: Reversibility is stated in words on every entry, never by colour or icon alone — it decides whether the undo control means anything, so it cannot be decoration. Selection uses native checkboxes with real labels, and the revert button carries the count in its accessible name so it says what pressing it will do. The selection summary is an aria-live region because the wording changes as the choice changes, and warns before the click when something can only be offset rather than undone.

## AI Agent Plan `ai-agent-plan`

What an agent intends to do — including when it changes its mind mid-run.

- Category: AI · Status: stable
- Install: `add ai-agent-plan`
- Accessibility: An ordered list, because a plan is a sequence and the order carries meaning an unordered list would discard. The running step carries aria-current="step", which marks the reader's place without moving focus and fighting anyone reading ahead. Every status is stated in text as well as drawn, and the markers are aria-hidden so the status is not heard twice per step. The live region reports structural revisions only — announcing every status transition would talk over the reader continuously on a plan of any length. Drawn checks and crosses live inside the hidden markers; quietCompleted dims finished steps with a contrast-audited token, and the optional sweep is decoration that stops under reduced motion.

## AI Agent Status `ai-agent-status`

A pill showing what an agent is doing, in words as well as colour.

- Category: AI · Status: stable
- Install: `add ai-agent-status`
- npm: class-variance-authority
- Accessibility: The state is always text. Agent states matter most when something has failed, which is exactly when a colour-only signal fails the people who most need to see it. Live announcements are off by default — several agents each announcing their transitions turns a dashboard into noise; enable it for the one agent being watched.

## AI Approval Request `ai-approval-request`

Approve a tool call — after correcting the arguments the model got wrong.

- Category: AI · Status: stable
- Install: `add ai-approval-request`
- Accessibility: The proposed arguments are a description list of real labelled form controls, so each value is associated with its name and editable ones are reachable by keyboard. A corrected argument is marked in text rather than by border colour alone, because an audit trail has to distinguish the model's proposal from the human's edit. The request is aria-busy while arguments are still arriving and the decision controls stay disabled until it is whole — rendering nothing until then, as the common implementation does, means nothing is on screen at the moment approval becomes relevant. Irreversibility is stated as a sentence, never as a severity colour. Focus never falls to the page as controls swap: deciding moves it to the outcome (tabindex -1, never a Tab stop), Deny… moves it into the reason field and Back returns it — but only when focus was already inside, so a replayed or remote decision never steals it (manageFocus={false} opts out).

## Artifact `ai-artifact`

A titled frame for something the model produced, with preview and code panes that slide along one axis and a copy action.

- Category: AI · Status: beta
- Install: `add ai-artifact`
- Also installs: copy-button, tabs
- Accessibility: A group named by its title. With both panes it is a real tablist (arrow keys move between Preview and Code, each panel focusable and named by its tab); with one code pane, the scrolling source is a focusable region named by the title. Copying announces success and failure through Copy Button. The pane slide mirrors in right-to-left layouts, never plays on mount, and stops under reduced motion.

## Branch `ai-branch`

Alternative versions of a conversation turn — regenerated answers, edited prompts — with a wrapping pager between them.

- Category: AI · Status: beta
- Install: `add ai-branch`
- Also installs: button
- npm: class-variance-authority
- Accessibility: The pager is a group named "Versions" with real Previous/Next buttons (their chevrons mirror in right-to-left layouts) and a polite, atomic "2 of 3" indicator, so paging says where it went. Inactive versions are hidden rather than unmounted, keeping their state. The pager disappears when there is only one version. The entrance is decoration and stops under reduced motion.

## AI Conversation `ai-conversation`

The scrolling transcript container, with follow-on-new-content and a status region.

- Category: AI · Status: stable
- Install: `add ai-conversation`
- Accessibility: The transcript is an ordered list, NOT a live region. A live region that updates on every streamed token is unusable with a screen reader, and is the most common accessibility failure in chat interfaces. Announce state — "generating", "response complete" — through ConversationStatus instead, and let the reader navigate the transcript at their own pace. Auto-scroll stops the moment the reader scrolls up, and ConversationScrollButton is the explicit way back.

## AI Disclosure `ai-disclosure`

Tells a reader they are looking at AI, and what is actually known about it.

- Category: AI · Status: stable
- Install: `add ai-disclosure`
- Also installs: popover
- npm: class-variance-authority
- Accessibility: The text is the disclosure and the icon is decoration, marked aria-hidden — a sparkle alone is a mark a sighted reader may not decode and a screen reader passes over in silence, which is the exact failure this component exists to prevent. Each of the four kinds carries wording of its own, so the distinction between generated, manipulated and human-reviewed survives for anyone who cannot see the styling. The provenance panel states in words whether anyone checked the claims and who, rather than implying it with a tick, and its three states are told apart by their sentences rather than by colour. Scope: this renders the human-visible disclosures of EU AI Act Article 50(1) and 50(4). It cannot satisfy 50(2), which requires machine-readable marking inside the artifact by whoever generated it, and no React component can. Not legal advice.

## AI Extraction Review `ai-extraction-review`

Check extracted fields against the document they came from, and decide each one.

- Category: AI · Status: stable
- Install: `add ai-extraction-review`
- Accessibility: Every field quotes its evidence in text under the value, so a reviewer who cannot see the highlight in the source still has what the model read. A value with no evidence is said in words — never left to look like a good one. The source is a focusable named region because it scrolls, and its highlights are mark elements with nothing spliced into the text, since a document read aloud with field names inserted is no longer the document. Focus anywhere in a field brings its evidence into view without moving focus, so a keyboard user is shown the source rather than sent into it. Each control's name carries the field it belongs to, so ten Accept buttons are ten different buttons. Status is a word, outside the label so editing never renames the control, and the running count is a polite live region present from the start. Enter accepts, except while an IME is composing.

## AI Inline Completion `ai-inline-completion`

Ghost-text suggestion inside a real textarea, accepted with Tab.

- Category: AI · Status: beta
- Install: `add ai-inline-completion`
- Accessibility: No WAI-ARIA pattern covers generative ghost text — combobox is the nearest and does not fit, because the suggestion is not one of a known set of options and a listbox would misdescribe it. So the suggestion is announced through a polite live description that names the keys, since a gesture nobody knows about is not an affordance, and the grey text itself is aria-hidden. Escape always dismisses and restores plain Tab, so the keyboard is never trapped in the field. The ghost hides during IME composition and whenever the caret is not at the end, rather than rendering somewhere it does not belong.

## AI Loader `ai-loader`

A labelled AI waiting indicator — thinking dots, an indeterminate bar or a thinking grid — with an optional elapsed-seconds counter.

- Category: AI · Status: beta
- Install: `add ai-loader`
- Also installs: bar-loader, dots-loader, grid-loader
- npm: class-variance-authority
- Accessibility: The root is a single role="status" region announcing the label (or `srLabel`, "Loading" by default). The loader inside it and the elapsed counter are aria-hidden — a counter ticking ten times a second inside a live region would announce continuously. The loaders are indicators: under reduced motion they slow rather than stop. None fakes determinate progress.

## AI Message `ai-message`

One turn in a conversation, with role, avatar, actions and footer slots.

- Category: AI · Status: stable
- Install: `add ai-message`
- npm: class-variance-authority, radix-ui
- Accessibility: Every message carries a visually hidden label naming the speaker. Alignment and colour tell a sighted reader who is talking and tell a screen reader user nothing, so the role is always in text. Message actions fade in on hover but stay in the DOM and in the tab order — a control that only exists on hover is unreachable by keyboard and invisible on touch — and on devices that cannot hover they are always shown. MessageTimestamp is a real <time>.

## AI Model Selector `ai-model-selector`

Picks the model a conversation runs on, with descriptions and availability.

- Category: AI · Status: stable
- Install: `add ai-model-selector`
- Also installs: select
- Accessibility: Inherits Select's listbox keyboard model. Each option sets textValue to the model name so typeahead matches the name rather than the description. A disabled model shows and announces why it is unavailable — a disabled option with no reason reads as a broken interface.

## AI Prompt Input `ai-prompt-input`

The composer: auto-growing textarea, send-on-Enter, and a send/stop control.

- Category: AI · Status: stable
- Install: `add ai-prompt-input`
- Accessibility: Enter sends and Shift+Enter inserts a newline, but never while an IME composition is active — for Japanese, Chinese and Korean input Enter confirms a candidate, and sending there truncates the sentence mid-word. The submit control renames itself to "Stop generating" while busy, so its accessible name always matches what it does. The character counter stays silent until it nears the limit; announcing every keystroke would be unusable.

## AI Reasoning `ai-reasoning`

A collapsible disclosure for the model's reasoning.

- Category: AI · Status: stable
- Install: `add ai-reasoning`
- Also installs: shimmer-text
- npm: radix-ui
- Accessibility: A standard disclosure with aria-expanded on the trigger. Collapsed by default because reasoning is supporting material — giving it the same weight as the answer buries the answer. The trigger's label changes while reasoning streams, so its accessible name matches what is happening — and to "Thought for 4.2s" when given a duration. autoOpen and autoCollapse are opt-in; auto-collapse never closes the trace while focus or the pointer is inside it. The optional shimmer is decoration and stops under reduced motion.

## AI Response `ai-response`

Assistant response text, with a streaming caret and a thinking indicator.

- Category: AI · Status: stable
- Install: `add ai-response`
- Also installs: ai-sources
- Accessibility: Deliberately not a live region: announcing streamed text as it arrives interrupts a screen reader user on every token. Announce state through ConversationStatus and let them read the response when it settles. The caret is decorative; ThinkingIndicator carries a label because it is the only thing on screen while waiting for the first token, and it slows rather than stops under reduced motion because a frozen one says the app has hung. ResponseText blurs in only newly arrived words, adds no live region, and leaves the text content unchanged; its [n] markers are InlineCitations named by their source title.

## AI Sources `ai-sources`

Inline citation markers and the source list they refer to.

- Category: AI · Status: stable
- Install: `add ai-sources`
- Also installs: tooltip
- npm: radix-ui
- Accessibility: An inline marker shows a bare number, which conveys nothing on its own, so the source title is carried in its accessible name. A marker with no href renders as text rather than as a link that goes nowhere. The source list is ordered, because the marker numbers refer to positions in it. The optional citation preview is a Radix Tooltip: it opens on hover and on keyboard focus, Escape closes it, and it describes the link (host and excerpt) only while open. Favicon stacks and marks are decorative and hidden; give an <img> favicon alt="".

## AI Structured Output `ai-structured-output`

An object arriving field by field from the model, without the layout jumping.

- Category: AI · Status: stable
- Install: `add ai-structured-output`
- Accessibility: A description list, so each value is associated with its label rather than floating beside it. The region is aria-live="polite" with aria-busy while streaming, so fields are announced as they settle instead of re-reading the whole object on every token. Height is reserved from the declared field list, which keeps focus and reading position stable as values arrive. Confidence is stated as a number in words, never as a colour alone.

## AI Suggested Value `ai-suggested-value`

An AI-proposed value for any form control, pending until accepted and marked afterwards.

- Category: AI · Status: stable
- Install: `add ai-suggested-value`
- Accessibility: The suggestion is the control's description, so a reader who lands on the field hears it without any announcement — and announcing is opt-in, because a form filling twenty fields at once would narrate all twenty. The row that holds it is rendered from the start and never display:none, so when announcing is on, a suggestion arriving after mount is actually heard. Each button's name carries the field it belongs to, so a page of Accepts is a page of different buttons. Provenance and confidence are words with a number, never a colour. Acceptance is reported, not performed: the control is the consumer's, so its value, its label and its own keyboard behaviour are untouched — there is no shortcut hijacked from a select or a date field. The id and ARIA a FormControl passes down are forwarded to the control, and an existing aria-describedby is merged rather than replaced.

## Suggestions `ai-suggestions`

Prompt suggestion chips for a chat's empty state or follow-ups, arriving from the centre of the row outwards.

- Category: AI · Status: beta
- Install: `add ai-suggestions`
- Also installs: button
- npm: class-variance-authority
- Accessibility: A list of real buttons, named by the visible heading (aria-labelledby) or "Suggestions". Every chip is in the tab order with the shared focus ring. The entrance stagger is decoration and does not run under reduced motion. Selecting hands the suggestion back; filling the composer rather than sending keeps it editable.

## AI Token Usage `ai-token-usage`

A gauge showing how much of the context window a conversation has used.

- Category: AI · Status: stable
- Install: `add ai-token-usage`
- Also installs: popover
- Accessibility: The numbers are the content and the bar only summarises them, so the bar is aria-hidden rather than a second progressbar to read past. Counts are formatted for the locale. Warning and over-limit states change the wording's colour but never remove the figures. The ring variant abbreviates its visible figures, so it carries a visually hidden sentence with the full numbers and percent. Its breakdown trigger is a real, never-disabled button: click, Enter or Space open it and Escape closes it; a mouse hover also opens it without moving focus, and focus alone never does.

## AI Tool Call `ai-tool`

A collapsible record of a tool the model called, its arguments and its result.

- Category: AI · Status: stable
- Install: `add ai-tool`
- npm: class-variance-authority, radix-ui
- Accessibility: A disclosure: the trigger exposes aria-expanded and controls the panel. Status is stated in words, not by a coloured dot — colour alone is unavailable to a screen reader and to anyone who cannot distinguish it. Payload blocks are focusable named regions, since JSON scrolls and an unfocusable scroll box is unreachable by keyboard. The optional ring indicator is decorative and hidden; the status word stays visible, and the ring stops moving under reduced motion. A summary note is part of the trigger's name, so keep it short.

## Alert `alert`

A callout that draws attention to an important message.

- Category: Feedback · Status: stable
- Install: `add alert`
- npm: class-variance-authority
- Accessibility: Not a live region by default. Pass live="polite" for alerts that appear in response to a user action, or live="assertive" for errors that must interrupt. Variant colour is never the only signal — the title carries the meaning.

## Animated Checklist `animated-checklist`

A task list whose boxes fill with a bounce and whose done tasks fade and strike through, with an add row.

- Category: Forms · Status: beta
- Install: `add animated-checklist`
- Also installs: checkbox
- npm: class-variance-authority
- Accessibility: A labelled group holding a real list. Each row is Dowel's Checkbox inside a <label>, so the whole row toggles with a click and the box with Space. The add row is a button that becomes a text field: Enter adds, Escape cancels and returns focus to "Add new task". Optional remove buttons are named per task and move focus to a neighbour. Additions and removals are announced politely. Name the group with aria-label.

## App Stack `app-stack`

A pile of app icons that fans out on hover and opens into a multi-select picker whose icons fly to their tiles.

- Category: Forms · Status: beta
- Install: `add app-stack`
- Also installs: button
- npm: class-variance-authority, motion
- Accessibility: The collapsed stack is a button (aria-expanded="false", named "Choose from {title}" or triggerLabel); opening moves focus to the picker's header button (aria-expanded="true"), which closes it and returns focus. Each app is a toggle button (aria-pressed) named by the app; icons and check marks are decorative. The download button is disabled until something is selected. Progress, completion and failure are announced through a polite status region, and the stack is aria-disabled while busy. Under reduced motion the icons move without animating (MotionConfig) and the fan, float and shine stop.

## Aspect Morph `aspect-morph`

A picture that smoothly reshapes between aspect ratios, picked from a segmented control with a sliding thumb.

- Category: Display · Status: beta
- Install: `add aspect-morph`
- npm: class-variance-authority
- Accessibility: The picker is a role="radiogroup" (named "Aspect ratio" unless `label` is given) of buttons with role="radio", aria-checked and a spoken name per shape; the outline icons and sliding thumb are aria-hidden. Roving tabindex: Tab reaches the checked option, arrow keys move focus and select with wrap-around (Left/Right follow the reading direction in RTL), Home/End jump to the ends. A `src` picture is role="img" named by `alt`, or hidden when no `alt` is given. The reshape and thumb are CSS transitions and snap to the final state under reduced motion.

## Assignee Picker `assignee-picker`

A pill of overlapping faces that opens a multi-select list of people; new faces fly into the stack.

- Category: Forms · Status: beta
- Install: `add assignee-picker`
- Also installs: avatar, popover
- npm: class-variance-authority
- Accessibility: The trigger exposes aria-haspopup="listbox" and aria-expanded, and is named by `label` plus who is assigned ("Assignees: Adam Marsh, Priya Raman", or the placeholder when nobody is). The popup is a role="listbox" aria-multiselectable="true" named by `label`, with role="option" rows carrying aria-selected. Opening moves focus onto the first assigned person (or the first row); ArrowUp/ArrowDown rove with wrap-around, Home/End jump, Space/Enter toggle, and Escape or Tab close it and return focus to the trigger. Faces, avatars and the check marks are aria-hidden: the option text and aria-selected carry the meaning. Under reduced motion the card, rows and faces appear in place.

## Avatar `avatar`

An image representation of a user or entity with a graceful text fallback.

- Category: Display · Status: stable
- Install: `add avatar`
- npm: class-variance-authority, radix-ui
- Accessibility: Give AvatarImage a meaningful alt, or alt="" when the adjacent text already names the person. Fallback initials are decorative and are not announced separately.

## Avatar Group `avatar-group`

Overlapping avatars that spread apart on hover or keyboard focus, collapsing the rest into a "+N" count.

- Category: Display · Status: beta
- Install: `add avatar-group`
- Also installs: avatar
- npm: class-variance-authority
- Accessibility: A list of people: each avatar's image carries the person's name as alt text, and the initials fallback is aria-hidden with the name beside it as screen-reader text. The "+N" overflow reads as "and N more" (overflowLabel). Linked avatars are real links with a focus ring, and keyboard focus spreads the group just as hover does. Name the group with aria-label when the context does not. The spread stops under reduced motion.

## Badge `badge`

A compact marker for status, counts and categories.

- Category: Display · Status: stable
- Install: `add badge`
- npm: class-variance-authority, radix-ui
- Accessibility: The badge label must convey the meaning on its own; variant colour is decoration. Use asChild to render an interactive badge as a link or button rather than adding handlers.

## Bar Loader `bar-loader`

Indeterminate loading indicators made of bars — cascade, equalizer, wave physics, an indeterminate sweep and 17 more motions.

- Category: Feedback · Status: beta
- Install: `add bar-loader`
- npm: class-variance-authority
- Accessibility: Renders aria-hidden by default so it does not announce inside controls that already expose a busy state. Pass `label` to announce it standalone via role="status". Under reduced motion it slows rather than stopping, because a frozen loader reads as a hang. The indeterminate sweep never reports a value, so it cannot be mistaken for real progress.

## Book `book`

A 3D book cover drawn in CSS that tilts, or swings open to reveal its first page, on hover and keyboard focus.

- Category: Display · Status: beta
- Install: `add book`
- npm: class-variance-authority, radix-ui
- Accessibility: The title is real text; the spine shading, page edges, back cover and inside of the cover are aria-hidden. Keyboard focus anywhere in the book (or on the book itself, when it is rendered as a link with asChild) does what hover does, and the link gets the shared focus ring. The tilt is decoration and does not happen under prefers-reduced-motion; the open effect still reveals its content there, instantly.

## Breadcrumb `breadcrumb`

Where the current page sits in the hierarchy, and how to get back up it.

- Category: Navigation · Status: stable
- Install: `add breadcrumb`
- npm: radix-ui
- Accessibility: The current page is a span carrying aria-current="page", not a link: a link to the page you are already on does nothing, and in a list of links it is indistinguishable from the ones that go somewhere. Separators are hidden from assistive technology, because the list already conveys the sequence and reading "slash" between every item is the design's punctuation leaking into the content. The ellipsis is the exception and is named, because it is content: it says levels have been left out. The optional entrance stagger stops under reduced motion.

## Browser Tabs `browser-tabs`

A miniature browser window whose tabs are a real tablist: a card-coloured leaf springs under the active tab, and tabs reorder by drag or keyboard.

- Category: Navigation · Status: beta
- Install: `add browser-tabs`
- npm: class-variance-authority
- Accessibility: The strip is role="tablist" (named by labels.tabList) of role="tab" buttons with aria-selected, aria-controls and aria-posinset/aria-setsize reporting each tab's visual position; one role="tabpanel" is labelled by the active tab. Left/Right (mirrored in right-to-left layouts) move focus and select with wrap-around, Home/End jump to the ends. Alt+Left/Right and Ctrl+Shift+PageUp/PageDown move the focused tab one slot, and every move — keyboard or drag — is announced through a polite live region ("Moved Finds to position 1 of 2"), so dragging is never the only way to reorder. Back, forward and reload are decorative (aria-hidden) unless onBack/onForward/onReload are given, when they become named buttons. The leaf and its ears are aria-hidden; the springs are CSS transitions that settle at once under reduced motion.

## Button `button`

Triggers an action or event, with variants for every level of emphasis.

- Category: Foundation · Status: stable
- Install: `add button`
- Also installs: spinner
- npm: class-variance-authority, radix-ui
- Accessibility: Keyboard activatable via Enter and Space. The loading state uses aria-disabled and aria-busy rather than the disabled attribute, so focus is never stranded mid-action. Use `size="icon"` only with an accessible name from aria-label or visually hidden text.

## Calendar `calendar`

A date grid for selecting a day, several days or a range.

- Category: Forms · Status: stable
- Install: `add calendar`
- Also installs: button
- npm: react-day-picker
- Accessibility: A real grid with roving focus: arrows move by day, Page Up/Down by month, Home/End to the ends of a week. Selection is announced through aria-selected, and the month caption is a live region so moving between months is announced. Give the calendar an accessible name when more than one is on the page.

## Canvas Toolbar `canvas-toolbar`

A Figma-style tool rail: one active tool with a springy fill, a shape slot that swaps its tool from a flyout, and single-key shortcuts.

- Category: Navigation · Status: beta
- Install: `add canvas-toolbar`
- Also installs: dropdown-menu, tooltip
- npm: class-variance-authority, radix-ui
- Accessibility: Built on Radix Toolbar: role="toolbar" (name it with aria-label; it warns in development when unnamed) with one tab stop, arrow keys that follow the reading direction, Home/End and wrap-around. Tools are toggle buttons named by their label, with aria-pressed on the single active tool and aria-keyshortcuts when a shortcut is set; a tooltip repeats the name and key. The slot is a named group; its notch is a menu button (aria-haspopup="menu", aria-expanded) opening Dowel's DropdownMenu, where shapes are menuitemradio items reachable with Left/Right as well as Up/Down. Escape closes the flyout and returns focus to the notch; picking a shape returns focus to the slot's tool. Shortcuts work while focus is in the toolbar, or on the whole document with globalShortcuts, and are ignored in inputs, textareas, contenteditable and open menus. The fill pop and the flyout entrance are decoration and stop under reduced motion.

## Card `card`

A surface that groups related content and actions into a single block.

- Category: Display · Status: stable
- Install: `add card`
- npm: radix-ui
- Accessibility: Card renders a plain div with no implicit landmark. CardTitle is an h3 by default — use asChild to set the level the page actually needs, since heading levels must increase by one, or to render something that is not a heading at all.

## Card Spread `card-spread`

A stack of cards that fans into an arc, row, corner fan, stamp arc, cascade, dealt hand or wheel on hover, focus or click.

- Category: Display · Status: beta
- Install: `add card-spread`
- npm: class-variance-authority, radix-ui
- Accessibility: The deck is a role="group"; name it with aria-label or aria-labelledby. A deck of non-interactive cards gets a real toggle button (aria-pressed, named by `toggleLabel`, default "Spread cards") laid over the stack: it is the tab stop, Enter/Space/click/tap pin the spread open, and Escape closes it. It is a sibling of the cards, so every card's own content stays in the accessibility tree. A deck whose cards are links or buttons (via `asChild`) has no toggle and is reached through them. Keyboard focus anywhere inside opens the spread. Under reduced motion the layout still applies, instantly. In RTL the spread mirrors toward the inline start.

## Card Stack `card-stack`

A pile of cards you step through as a receding deck, or that fans out into an arc on hover and focus.

- Category: Display · Status: beta
- Install: `add card-stack`
- npm: class-variance-authority
- Accessibility: The deck is a carousel region (aria-roledescription="carousel") of labelled slides; only the top card is exposed — the others are aria-hidden and inert. Indicator dots are buttons with a roving tabindex and aria-current; arrow keys (mirrored in right-to-left layouts), Home and End step the deck and move focus with it, and a polite status region announces the new card. Wheel and swipe are conveniences on top of that, and the wheel releases the page at either end. The fan is a labelled list that opens on focus as well as hover; its motion is decoration and settles instantly under reduced motion.

## 3D Carousel `carousel-3d`

A 3D carousel of cards — a fanned arc or a CoverFlow path — with buttons, dots, arrow keys and swipe.

- Category: Display · Status: beta
- Install: `add carousel-3d`
- npm: class-variance-authority
- Accessibility: Follows the APG tabbed carousel: a region with aria-roledescription="carousel", slides that are tabpanels with aria-roledescription="slide" and a position label, named previous/next buttons, and a tablist of dots with a roving tab stop. Arrow keys (mirrored in right-to-left layouts), Home and End move between slides anywhere in the carousel; changes are announced through a polite status. Only the current slide is in the accessibility tree and tab order — the neighbours are inert, and clicking one selects it. Swipe is a pointer convenience with button, dot and key equivalents. It never rotates on its own. Motion stops under reduced motion.

## Checkbox `checkbox`

A control for an on/off choice, with support for an indeterminate state.

- Category: Forms · Status: stable
- Install: `add checkbox`
- npm: radix-ui
- Accessibility: Toggles with Space, matching the native control. Always pair with a Label via htmlFor/id — the box alone has no accessible name. Indeterminate is announced as "mixed" and is a state the application sets, not one the user can reach by clicking.

## Code Block `code-block`

A block of code with a copy control, ready for any highlighter.

- Category: Data · Status: stable
- Install: `add code-block`
- Also installs: copy-button
- Accessibility: The pre is a focusable named region, since code overflows horizontally and an unfocusable scroll box is unreachable by keyboard. Copying is announced through a polite live region as well as shown, and a refused clipboard write reports failure rather than looking like success.

## Collapsible `collapsible`

A single section that opens and closes, without an accordion's set semantics.

- Category: Layout · Status: stable
- Install: `add collapsible`
- npm: radix-ui
- Accessibility: The trigger carries aria-expanded and points at the region it controls, both from the primitive. Reach for this rather than an Accordion of one item: a single-item Accordion gives its trigger a heading role and a position in a list of one, neither of which is true.

## Combobox `combobox`

A searchable single-select built on the ARIA combobox pattern.

- Category: Forms · Status: stable
- Install: `add combobox`
- npm: radix-ui
- Accessibility: The input owns role="combobox" with aria-expanded, aria-controls and aria-autocomplete; the list owns role="listbox" and each option role="option" with aria-selected. Focus stays in the input while arrow keys move aria-activedescendant, so typing is never interrupted. Arrow navigation wraps, Home/End jump, Enter selects the active option and Escape closes. With loading set, the listbox is aria-busy, ComboboxLoading is a status and the empty state waits for the answer. The optional clear button is a named button that returns focus to the input.

## Command `command`

A searchable command palette, with groups and a ⌘K dialog variant.

- Category: Navigation · Status: stable
- Install: `add command`
- Also installs: dialog
- Accessibility: The input owns role="combobox" and the list role="listbox"; focus stays in the input while arrow keys move aria-activedescendant, so typing is never interrupted. Enter runs the active item through the same path as a click. A group whose items are all filtered out hides its heading rather than labelling nothing. CommandDialog always renders a title and description, visually hidden, so the dialog is never unnamed.

## Command Bar `command-bar`

A compact one-row prompt bar — auto-growing field, dictate toggle and send — composed from AI Prompt Input.

- Category: AI · Status: beta
- Install: `add command-bar`
- Also installs: ai-prompt-input
- npm: class-variance-authority
- Accessibility: Inherits AI Prompt Input's behaviour: Enter sends, Shift+Enter adds a newline, never mid-IME-composition, and the submit control renames itself to "Stop" while sending. The field is named by `label`. Send is disabled while the field is empty. Dictate is a toggle button (aria-pressed); the consumer owns the microphone.

## Comment Bubble `comment-bubble`

A canvas comment pin — an avatar in a speech-bubble corner that grows into the thread and a reply composer.

- Category: Display · Status: beta
- Install: `add comment-bubble`
- Also installs: avatar
- Accessibility: The avatar is a disclosure button ("Comment by <name>, N replies") with aria-expanded and aria-controls. The thread is a labelled group and an ordered list; while collapsed it is invisible and inert. Opening moves focus to the reply field when there is one; Escape collapses the thread and returns focus to the avatar; a press outside collapses it. The reply field and send button are named. The grow and blur stop under reduced motion.

## Confirm Typed `confirm-typed`

Type the name to confirm — and be told, not ignored, when it does not match.

- Category: Forms · Status: stable
- Install: `add confirm-typed`
- Also installs: button, input
- Accessibility: The button stays reachable while the text does not match, dimmed rather than disabled, and pressing it or Enter announces what was expected, marks the field invalid and returns focus to it — the common version disables the button and says nothing, so a keyboard user cannot tell whether anything happened. The match is announced once, on the transition, naming the action that became available, so nobody has to watch the button change colour. Typing itself stays silent, because a verdict on every keystroke is noise. The hint is the field's description and the button's, and the status region exists from the first render so the first announcement is heard. Pasting is allowed: blocking it punishes people who cannot type a long name easily and stops nobody who can select-all and copy.

## Context Menu `context-menu`

A right-click menu that pops from the pointer with a spring and staggers its items in — same parts as Dropdown Menu.

- Category: Overlays · Status: beta
- Install: `add context-menu`
- npm: radix-ui
- Accessibility: Opens on right-click, long press, Shift+F10 or the Menu key — the keyboard paths need a focusable trigger. Full menu keyboard model: arrows move, Home/End jump, typeahead searches, Escape closes and returns focus, Right/Left open and close submenus (mirrored in RTL). Checkbox and radio items expose aria-checked; shortcuts are aria-hidden hints. A context menu is invisible until summoned, so its actions should also be reachable elsewhere. The pop and stagger stop under reduced motion.

## Contribution Graph `contribution-graph`

A GitHub-style year heatmap of daily counts — a keyboard-navigable grid with a tooltip per day.

- Category: Data · Status: beta
- Install: `add contribution-graph`
- Also installs: tooltip
- npm: class-variance-authority
- Accessibility: A table with role="grid", named by its caption ("1,234 contributions in 2025" or `label`). Weekdays are row headers and months column headers; every day is a gridcell whose screen-reader text states the count and the full date, so colour never carries the value. One day is tabbable (roving tabindex): arrows move by day and week (mirrored in RTL), Home/End to the ends of the weekday row, Ctrl+Home/End to the ends of the year, PageUp/PageDown by four weeks. The tooltip follows keyboard focus as well as hover and Escape dismisses it.

## Copy Button `copy-button`

Copies a value to the clipboard and morphs its icon and label into a confirmation that reverts on its own.

- Category: Forms · Status: beta
- Install: `add copy-button`
- Also installs: button
- npm: class-variance-authority
- Accessibility: The confirmation is announced through a polite role="status" region rendered beside the button, so it never becomes part of the button's name. Only the visible label is exposed; the hidden one is aria-hidden. Icon-only buttons are named "Copy" unless given an aria-label. A refused clipboard write is announced as a failure and never shows the check. The button is never disabled while confirming, so keyboard focus stays put.

## Create Menu `create-menu`

A DropdownMenu with a morph flourish: a "+ Create" pill that grows in place into its menu panel.

- Category: Navigation · Status: beta
- Install: `add create-menu`
- npm: class-variance-authority, radix-ui
- Accessibility: Built directly on the Radix DropdownMenu primitive (not portalled, so the panel can grow over the pill): the trigger exposes aria-haspopup="menu" and aria-expanded, the panel is a role="menu" named by the trigger, and items are role="menuitem". Opening from the keyboard moves focus to the first item; Up/Down move, Home/End jump, typeahead searches, Enter/Space select, Escape and an outside press close and return focus to the trigger. The morphing surface and the highlight pill are aria-hidden; the pill follows data-highlighted, so pointer and keyboard never disagree. The grow, stagger and pill slide are decoration and settle instantly under reduced motion.

## Cron Editor `cron-editor`

A schedule as a cron expression, with a plain-language reading and the next runs.

- Category: Forms · Status: stable
- Install: `add cron-editor`
- Also installs: input, select
- Accessibility: The expression field is described by one element that holds either the plain-language reading or the reason the expression is invalid, so a reader hears the error replace the reading rather than both at once; an invalid expression is never applied. The builder's day buttons are a named group of aria-pressed toggles with the full day name as the accessible name, and the last selected day cannot be removed silently — the group says why. Days 29 to 31 say in text that shorter months skip them. Next runs are a list of time elements with machine-readable datetimes, headed by the zone they are in, because a time with no zone is the classic scheduling mistake. Nothing clock-dependent renders until the clock is known, so server and client cannot disagree.

## Cursor Follow `cursor-follow`

A dot that trails the pointer on a spring inside a container and swells into a label over marked elements.

- Category: Effects · Status: beta
- Install: `add cursor-follow`
- npm: class-variance-authority, motion
- Accessibility: Purely decorative: the follower is aria-hidden and ignores the pointer, and the container adds no role or tab stop (the source's role="application" and tabIndex are dropped). A `data-cursor-text` label is shown only by the follower, so the same words must also be in the element's alt text or visible text. Nothing renders for touch input or under reduced motion. Hiding the system cursor is opt-in (`hideCursor`). The spring is `motion`, wrapped in MotionConfig reducedMotion="user".

## Data Table `data-table`

Presentation for a TanStack Table instance: sorting, column visibility and pagination.

- Category: Data · Status: stable
- Install: `add data-table`
- Also installs: button, dropdown-menu, select, table
- npm: @tanstack/react-table
- Accessibility: Sortable headers carry aria-sort, so the current sort is announced rather than being conveyed by an arrow icon alone, and each sort button has visually hidden text stating the column and its direction. The pagination status is a polite live region, because paging swaps the rows in place with no other signal. A column that cannot be sorted renders as text, not as a button that does nothing.

## Date Picker `date-picker`

A button that opens a calendar to pick a date or a date range.

- Category: Forms · Status: stable
- Install: `add date-picker`
- Also installs: button, calendar, popover
- npm: react-day-picker
- Accessibility: The trigger states the selected date, formatted for the locale, so its accessible name changes with the value. The popover is named because it carries role="dialog". Selecting a single date closes the popover and returns focus to the trigger; a range stays open, since one click is only half an answer. Offer a typed input alongside it for dates the user already knows.

## Dial `dial`

A rotary dial input — a knob inside a filling arc with detent ticks — turned by drag, wheel or keys.

- Category: Forms · Status: beta
- Install: `add dial`
- npm: class-variance-authority
- Accessibility: The dial is the role="slider" element (name it with aria-label or aria-labelledby), with aria-valuetext from `format`. Arrow keys step, PageUp/PageDown move a page, Home/End go to the ends. Dragging points the notch at the pointer; the wheel turns it only while it has focus, so it never steals page scroll. Clockwise means more in every language, so neither the dial nor its arrow keys mirror in right-to-left layouts. The knob's rotation settles instantly under reduced motion.

## Dialog `dialog`

A modal window that interrupts the user to gather a response.

- Category: Overlays · Status: stable
- Install: `add dialog`
- npm: radix-ui
- Accessibility: Focus is trapped while open and restored to the trigger on close; Escape and an overlay click dismiss. Always render a DialogTitle — it names the dialog for screen readers. Use DialogDescription, or aria-describedby, to explain consequential actions. The optional spring entrance and section stagger stop under reduced motion.

## Diff Viewer `diff-viewer`

A diff you can style, and accept or reject hunk by hunk.

- Category: Data · Status: stable
- Install: `add diff-viewer`
- npm: diff
- Accessibility: A semantic table, not a grid. role="grid" would promise cell-by-cell arrow navigation that does not exist here and makes no sense for reading code. Every row states added, removed or unchanged in text, because a plus sign and a green tint are not information — a diff read aloud without it is just the same file twice. Line numbers are aria-hidden: they orient a sighted reader, and announcing two numbers before every line makes the diff unlistenable. Changed words are marked with mark elements so they survive as structure, and the empty half of a split pair is hidden rather than read as a blank line of code. The optional wipe entrance is visual only — every row is in the DOM and its kind text is never clipped from assistive technology. With collapseRejected, a rejected hunk's lines are inert and hidden, its header says so in words, and Accept stays available so the decision can be reversed.

## Direction Provider `direction`

Tells the component primitives which way the writing runs, so menus and sliders mirror with the rest of the page.

- Category: Foundation · Status: stable
- Install: `add direction`
- npm: radix-ui
- Accessibility: Needed only for right-to-left languages, and needed in addition to `dir` on the document rather than instead of it. The styling here is written with logical properties and follows `dir` by itself; the primitives underneath read direction from React context and assume left-to-right without a provider, which mirrors a page correctly except for its menus, selects and sliders — worse than not mirroring at all, because it looks deliberate.

## Dither Area `dither-area`

An area chart filled with dithered cells over a cell grid, with a date scrubber that swells the cells around it.

- Category: Data · Status: beta
- Install: `add dither-area`
- Also installs: dither-canvas
- npm: class-variance-authority
- Accessibility: The plot is role="img" with an aria-label giving the range, start, end and peak. The scrubber over it is a slider: arrow keys step a point, Page keys jump a tenth, Home/End go to the ends, Escape hides the cursor, and aria-valuetext announces the date and value shown in the readout. Axis ticks are aria-hidden; the data is always in a table, visually hidden unless showTable is set.

## Dither Bar `dither-bar`

Stacked bars drawn in dithered cells that grow on change, with series highlighting on hover and a per-column readout.

- Category: Data · Status: beta
- Install: `add dither-bar`
- Also installs: dither-canvas
- npm: class-variance-authority
- Accessibility: The plot is role="img" with an aria-label summarising every stack. Each column is a button named with its full breakdown and total; focus shows the readout and pressing pins it (aria-pressed). Legend entries are buttons that preview a series on hover or focus and pin it when pressed. The data is always in a table, visually hidden unless showTable is set. Series are named in the legend and readout, never by colour alone.

## Dither Canvas `dither-canvas`

The engine behind the dither charts: a DPR-capped, self-pausing canvas loop, token colours, a deterministic cell hash, springs, geometry and a keyboard scrubber.

- Category: Data · Status: beta
- Install: `add dither-canvas`
- Accessibility: The canvas is aria-hidden by default: a chart built on it names itself with role="img" and an aria-label summary, and renders its values in DitherTable, which stays in the accessibility tree when visually hidden. useDitherScrubber gives a chart cursor APG slider semantics (arrows, Page keys, Home/End). The loop pauses off-screen and in hidden tabs, and under reduced motion (or --motion-scale near zero) draws a single static frame with springs settled.

## Dither Donut `dither-donut`

A donut chart drawn in shimmering dithered cells, with wedges that pop out and sparkle on hover, focus or pin.

- Category: Data · Status: beta
- Install: `add dither-donut`
- Also installs: dither-canvas
- npm: class-variance-authority
- Accessibility: The plot is role="img" with an aria-label summarising every entry, its share and the total. Legend entries are buttons named with their value and share: focus or hover previews a wedge, and pressing pins it (aria-pressed). The data is always in a table, visually hidden unless showTable is set. The readout is real text. Under reduced motion the shimmer stops and data changes settle in one frame.

## Dither Funnel `dither-funnel`

A conversion funnel of dithered stage bars that morph between periods, with overall and step conversion per stage.

- Category: Data · Status: beta
- Install: `add dither-funnel`
- Also installs: dither-canvas
- npm: class-variance-authority
- Accessibility: The bars are role="img" with an aria-label giving every stage's value and conversion. Each stage is a button over its bar, showing its name and overall conversion and named with the full breakdown (share of the first stage, step conversion, drop-off); hover or focus fills the text readout and pressing pins it (aria-pressed). The data is always in a table, visually hidden unless showTable is set.

## Dither Gauge `dither-gauge`

A half-circle gauge drawn in dithered cells, one sweeping ring per metric, with a centre reading and metric switch.

- Category: Data · Status: beta
- Install: `add dither-gauge`
- Also installs: dither-canvas
- npm: class-variance-authority
- Accessibility: The rings are role="img" with an aria-label listing every metric's reading. The centre reading is a role="meter" with aria-valuemin, aria-valuemax, aria-valuenow and a formatted aria-valuetext. With several metrics, legend buttons (named with label and reading) preview a ring on hover or focus and choose the centre's metric when pressed (aria-pressed). The data is always in a table, visually hidden unless showTable is set.

## Dither Heatmap `dither-heatmap`

A rows × columns intensity grid drawn in dithered tiles that morph between periods, with a keyboard-navigable cell readout.

- Category: Data · Status: beta
- Install: `add dither-heatmap`
- Also installs: dither-canvas
- npm: class-variance-authority
- Accessibility: The plot is role="img" with an aria-label giving its size, total and peak. Over it sits a role="grid" of real gridcells with one roving tab stop: arrow keys move a cell, Home/End go to the row's ends, Ctrl+Home/End to the corners, Escape hides the readout. Each cell's text is its readout, so focus announces what the pointer tooltip shows. Axis labels and the scale legend are aria-hidden; the data is always in a table, visually hidden unless showTable is set.

## Dither Line `dither-line`

A smooth monotone line over a drifting dithered gradient fill, with a keyboard-operable point scrubber.

- Category: Data · Status: beta
- Install: `add dither-line`
- Also installs: dither-canvas
- npm: class-variance-authority
- Accessibility: The plot is role="img" with an aria-label giving the range, high and low. The scrubber over it is a slider: arrow keys step a point, Page keys jump, Home/End go to the ends, Escape hides the cursor, and aria-valuetext announces the point and value shown in the readout. The data is always in a table, visually hidden unless showTable is set.

## Dither Meter `dither-meter`

A capacity bar drawn in dithered cells, split into categories that fill with a spring, with a category legend.

- Category: Data · Status: beta
- Install: `add dither-meter`
- Also installs: dither-canvas
- npm: class-variance-authority
- Accessibility: The bar is a role="meter" named by label, with used over capacity as aria-valuenow / aria-valuemax and the per-category breakdown as aria-valuetext (or `description`). Legend entries are buttons, named with category and value, that preview a segment on hover or focus and pin it when pressed (aria-pressed). The visible used-of-capacity line is aria-hidden as it repeats the meter. The data is always in a table, visually hidden unless showTable is set.

## Dither Scatter `dither-scatter`

A bubble scatter drawn in dithered cells: floating bubbles sized by value that glide between data sets, with a per-point readout.

- Category: Data · Status: beta
- Install: `add dither-scatter`
- Also installs: dither-canvas
- npm: class-variance-authority
- Accessibility: The plot is role="img" with an aria-label listing every point's x, y and size. Each bubble is a button over the plot, its visible short label first in a name that carries all three values; hover or focus shows the readout and pressing pins it (aria-pressed). The float stops under reduced motion. The data is always in a table, visually hidden unless showTable is set.

## DNS Record `dns-record`

Add this record at your provider: parts copied separately, checked with what was found.

- Category: Data · Status: stable
- Install: `add dns-record`
- Also installs: button, spinner
- Accessibility: The card is a region named by the record's type and purpose. Each part is a definition with its own copy button, named by the part it copies, so five Copy buttons are five different buttons. Verification status is a word in a polite live region, so the answer to a check arrives where it was asked for, and the card is aria-busy while checking. Copy results are announced in a separate region, present from the start, so a copy never replaces a check result mid-sentence; failure is announced with what to do instead. What the check found is a list, not a colour.

## Dot Morph Button `dot-morph-button`

A pill button led by a dot that stretches into a bar on hover and keyboard focus.

- Category: Forms · Status: beta
- Install: `add dot-morph-button`
- Also installs: button
- npm: class-variance-authority
- Accessibility: The dot is aria-hidden decoration; the button is named by its label. The morph runs on keyboard focus as well as hover, and hover only applies on devices that can hover, so a tap never leaves it stuck. Under reduced motion the change is instant.

## Dots Loader `dots-loader`

Indeterminate loading indicators made of dots — pulse, bounce, ripple, orbit and 21 more motions.

- Category: Feedback · Status: beta
- Install: `add dots-loader`
- npm: class-variance-authority
- Accessibility: Renders aria-hidden by default so it does not announce inside controls that already expose a busy state. Pass `label` to announce it standalone via role="status". Under reduced motion it slows rather than stopping, because a frozen loader reads as a hang.

## Drag Stepper `drag-stepper`

A pill number stepper: tap − or + to step, or hold either one to stretch into a sweep and drag to scrub.

- Category: Forms · Status: beta
- Install: `add drag-stepper`
- npm: class-variance-authority, radix-ui
- Accessibility: The value is a text input with role="spinbutton", aria-valuenow, -valuemin, -valuemax and an optional aria-valuetext from formatValue. Up/Right step up and Down/Left step down (Left/Right mirror in right-to-left layouts, and leave the caret alone while a number is being typed), Page Up/Down take large steps, Home/End jump to the bounds. Typing commits on Enter or blur, clamped to the range; Escape discards the draft. The − and + side buttons are real, named buttons ("Decrease", "Increase") that step on click, so Enter and Space work; they report aria-disabled at the bounds but stay focusable. Holding one to sweep is a pointer convenience with no keyboard-only behaviour behind it. The fill is aria-hidden, and the sweep's stretch and swell are CSS transitions that stop under reduced motion. A development warning fires when the value is unnamed.

## Drawer `drawer`

A bottom sheet that can be dismissed by dragging it down.

- Category: Overlays · Status: stable
- Install: `add drawer`
- npm: radix-ui
- Accessibility: Drag is pointer-only and never the sole way out: Escape, the overlay and DrawerCancel all dismiss. The grab handle is aria-hidden because it duplicates those affordances. Always render a DrawerTitle. The optional section stagger stops under reduced motion.

## Dropdown Menu `dropdown-menu`

A menu of actions revealed from a trigger, with submenus and selectable items.

- Category: Overlays · Status: stable
- Install: `add dropdown-menu`
- npm: radix-ui
- Accessibility: Full menu keyboard model: arrows move, Home/End jump, typeahead searches, Escape closes and restores focus, Right/Left open and close submenus. Highlight is driven by data-highlighted so pointer and keyboard focus never diverge. Use it for actions — links belong in a nav, and value selection belongs in Select. The opening pop and item stagger are decoration and stop under reduced motion.

## Effect Button `effect-button`

A Button with a hover and focus micro-interaction — slide-arrow, pulse, rotate, shake, glare, text reveal, expanding ring or clip corners.

- Category: Forms · Status: beta
- Install: `add effect-button`
- Also installs: button
- npm: class-variance-authority
- Accessibility: Every effect plays on keyboard focus-visible as well as hover. Icons and decorative layers are aria-hidden, and text-reveal's duplicate label is hidden so the name is read once. Colour (tone) never carries meaning on its own: the label does. Effects stop under reduced motion. Inherits Button's loading and disabled behaviour.

## Empty State `empty-state`

Shown where content would be, explaining why it is empty and what to do next.

- Category: Feedback · Status: stable
- Install: `add empty-state`
- npm: class-variance-authority
- Accessibility: A plain container with no implicit landmark or live region. When it replaces content after a search, put aria-live on the results region so the change is announced. The icon is decorative — the title has to carry the message on its own.

## Escape Button `escape-button`

A novelty button that scoots away from an approaching mouse, then gives up after a few escapes.

- Category: Effects · Status: beta
- Install: `add escape-button`
- Also installs: button
- npm: class-variance-authority
- Accessibility: The dodging is a mouse-and-pen game only: it never moves for touch, a coarse pointer, reduced motion, or while the button has focus, so keyboard users can Tab to it and press it at once. It gives up after `patience` escapes (4 by default) and stays put, and a press always goes through in every state — the movement is visual, never a lock. It is a real button with its visible label as its name.

## Expandable Cards `expandable-cards`

Cards that open into a detail view — widening in place in a row, or growing out of a grid into a modal.

- Category: Display · Status: beta
- Install: `add expandable-cards`
- npm: motion, radix-ui
- Accessibility: Every card is a real button. Inline, it is a disclosure (aria-expanded, aria-controls) whose detail is a labelled region: opening moves focus into it, Escape closes it from anywhere inside the card and returns focus to the card, and a closed detail is aria-hidden and inert. As a dialog it is a Radix modal — focus trap, aria-modal, title and description, Escape and a named Close button — and focus returns to the card that opened it. Motion follows MotionConfig reducedMotion="user": under reduced motion the card still opens, without growing out of its place.

## Expandable List `expandable-list`

A list of compact rows — jobs, releases, people — each growing into a detail dialog out of its place in the list.

- Category: Display · Status: beta
- Install: `add expandable-list`
- npm: class-variance-authority, motion, radix-ui
- Accessibility: Each row is a button with aria-haspopup="dialog" and aria-expanded. The detail is a Radix modal dialog: focus moves in and is trapped, the page behind is inert, it is named by the item's title and described by its content, and Escape, the backdrop or the named Close button dismiss it — after which focus returns to the row that opened it. Row media is aria-hidden. The grow-from-row animation uses motion's layoutId inside MotionConfig reducedMotion="user", so under reduced motion the dialog appears in place.

## Expanding Search `expanding-search`

A search button that opens into a field, clears, and collapses back with Escape — ready for a combobox.

- Category: Forms · Status: beta
- Install: `add expanding-search`
- npm: class-variance-authority
- Accessibility: A labelled search landmark. The trigger is a button with aria-expanded and aria-controls; opening moves focus into the field. Escape clears the text first, then collapses and returns focus to the trigger; leaving an empty field collapses it without moving focus. The collapsed field is visibility-hidden, so it is out of the tab order. `inputProps` reaches the input for combobox wiring, and its onKeyDown can preventDefault to keep Escape for its own listbox.

## Exposure Slider `exposure-slider`

A camera-style exposure dial: a draggable ruler of notches under a fixed centre mark, with a value ring.

- Category: Forms · Status: beta
- Install: `add exposure-slider`
- npm: class-variance-authority, radix-ui
- Accessibility: The ruler is a focusable role="slider" with aria-valuenow, -valuemin, -valuemax and an aria-valuetext taken from formatValue. Arrow keys move one step (Left/Right follow the reading direction), Page Up/Down move largeStep, Home/End jump to the ends — so the drag is never the only way to set it. aria-label and aria-labelledby passed to the component land on the slider, and a development warning fires when it has no name. The ring and notches are aria-hidden: the slider already reports the value. The settle animation is a CSS transition and stops under reduced motion.

## File Upload `file-upload`

A dropzone over a real file input, plus the upload queue nobody ships.

- Category: Forms · Status: stable
- Install: `add file-upload`
- Accessibility: The APG has no dropzone pattern, and inventing one is the usual failure — a div with role="button", a keydown handler, and a picker keyboard users never reach. The control here is a real input[type=file] with a real label, which is already operable, already announced, and opens the picker on Enter and Space with nothing added. Drag and drop is a pointer convenience layered on top; every drop can also be done from the input. Each uploading file gets a progressbar named after it, status is always stated in words as well as drawn, and one polite live region summarises the whole queue rather than six per-file regions talking over each other. The optional dropzone icon is aria-hidden. With animateExit, a removed row lingers only as an aria-hidden, inert copy with no buttons while it animates out.

## Focus Blur Links `focus-blur-links`

A row of links where hovering or focusing one blurs and dims the rest, with an optional dashed bracket.

- Category: Navigation · Status: beta
- Install: `add focus-blur-links`
- npm: class-variance-authority, radix-ui
- Accessibility: Every item is a real link (or your router's link via asChild). Keyboard focus triggers the same emphasis as hover and holds it after the pointer leaves; focus from a click does not. The blur is visual only — dimmed links stay in the accessibility tree and remain focusable. Wrap the row in a <nav aria-label> when it is site navigation.

## Folding Frame `folding-frame`

A photo folded shut like a book in 3D — drag across it (or use the keys) to open the cover until it lies flat.

- Category: Effects · Status: beta
- Install: `add folding-frame`
- npm: class-variance-authority, radix-ui
- Accessibility: The photo is exposed once, as role="img" named by `alt`; halves, spine, shading and the hinge band are presentational inside it. A focusable role="slider" overlay (default name "Unfold", 0–100) carries the openness with aria-valuetext "Closed", "40% open" or "Open". Arrows step by 5 (left/right follow the reading direction), Page Up/Down by 25, Home shuts and End opens. The drag follows pointer position rather than momentum and mirrors in right-to-left layouts. Key steps and the optional release snap ease with a CSS transition that is instant under reduced motion. The liquid refraction is Chromium-only; other engines get the blur alone (data-liquid="fallback").

## Form `form`

Accessible field wiring that works with any form library, or none.

- Category: Forms · Status: stable
- Install: `add form`
- npm: radix-ui
- Accessibility: FormField generates the id, points the Label at the control, and assembles aria-describedby from whichever of the description and error are actually present — a dangling reference announces nothing and is flagged by axe. aria-invalid follows the error. FormMessage is a polite live region, so a late validation message is announced without interrupting. With animateExit, a cleared message lingers only as an aria-hidden copy with no id, which the control no longer references.

## Glass Bubble `glass-bubble`

A draggable glass lens that refracts the content under it, with a specular highlight and chromatic fringing.

- Category: Effects · Status: beta
- Install: `add glass-bubble`
- npm: radix-ui
- Accessibility: The bubble is a 2D slider (role="slider", default name "Glass bubble") with aria-valuetext "<x> across, <y> down" in percent of travel. Arrow keys move it 2% (Shift: 6%), mirrored in right-to-left layouts; Home centres it; it has the shared focus ring. Highlight and rim layers are aria-hidden. The refracting lens is an SVG backdrop-filter that only Chromium supports; other engines get a blur-and-saturate bubble instead, and data-lens="svg" | "fallback" on the root reports which. Nothing moves on its own; the shadow transition while held runs on the duration tokens, so reduced motion stops it.

## Glow Card `glow-card`

Card surfaces with a soft glow that follows the pointer, alone or continuously across a group.

- Category: Display · Status: beta
- Install: `add glow-card`
- npm: class-variance-authority, radix-ui
- Accessibility: The glow is a decorative, aria-hidden, pointer-events-none layer, so the card's own content and semantics are untouched; use asChild to make the whole card a link or button. The pointer handler writes custom properties directly and never re-renders. The glow is off for touch input and under prefers-reduced-motion, where the layer is not displayed at all.

## Goo Ball `goo-ball`

A decorative jelly ball you drag around a well: it stretches along its velocity and squashes against the walls.

- Category: Effects · Status: beta
- Install: `add goo-ball`
- npm: class-variance-authority, motion, radix-ui
- Accessibility: The handle is a 2D slider (role="slider", aria-roledescription "draggable ball") labelled as decorative by default ("Goo ball (decorative)"), with aria-valuetext "<x>% across, <y>% down". Arrow keys nudge it 2% (Shift: 10%), mirrored in right-to-left layouts; Home centres it; it has the shared focus ring. The gooey blob is an aria-hidden SVG drawn behind the handle. Under reduced motion the spring is skipped: the ball sits exactly at the handle with no stretch or wobble.

## Goo Tabs `goo-tabs`

Dowel Tabs with a motion flourish: an icon bar whose pill stretches over the old and new tab, then snaps onto the new one, melted together by an SVG goo filter.

- Category: Navigation · Status: beta
- Install: `add goo-tabs`
- Also installs: tabs
- npm: class-variance-authority
- Accessibility: A thin composition on Dowel's Tabs (Radix): role="tablist" (name it with aria-label) with one tab stop, arrow keys along the orientation that follow the reading direction, Home/End, wrap-around and automatic activation; tabs carry aria-selected and aria-controls, and panels are focusable. Icon-only tabs must be named with aria-label and warn in development when they are not; icons are decoration. The pill, trailing blob and goo filter are one aria-hidden layer that ignores the pointer, and the filter never applies to the icons. Under reduced motion (or without SVG filter support, or with goo={false}) the goo is dropped and the pill moves straight to the new tab.

## Gooey Popover `gooey-popover`

A round trigger whose popover pours out of it, melted together by an SVG goo filter.

- Category: Overlays · Status: beta
- Install: `add gooey-popover`
- Also installs: popover
- npm: class-variance-authority
- Accessibility: Built on Dowel's Popover (Radix): the icon-only trigger is named by `triggerLabel` and exposes aria-expanded; the content is a role="dialog" named by `triggerLabel` unless given aria-label or aria-labelledby. Opens from pointer or keyboard, moves focus into the content, closes on Escape or an outside press, and returns focus to the trigger. The blob, goo layer and the copy of the trigger icon drawn over it are aria-hidden and ignore the pointer. Under reduced motion the goo layer is dropped and the panel appears in place.

## Gradient Orb `gradient-orb`

An animated gradient orb — a rotating conic mesh with a dot screen, sheen and bloom — that can follow an AI state and a live audio level.

- Category: Effects · Status: beta
- Install: `add gradient-orb`
- Accessibility: Decorative: aria-hidden unless given aria-label or aria-labelledby, when it becomes role="img". It never reports state on its own — pair it with a text status. Pure CSS; under reduced motion every loop stops and the orb shows its settled first frame.

## Grid Loader `grid-loader`

Indeterminate loading indicators on a grid of cells — 48 patterns (and 17 SmoothUI alias names) that pulse or stagger, plus sequence, thinking and matrix.

- Category: Feedback · Status: beta
- Install: `add grid-loader`
- npm: class-variance-authority
- Accessibility: Renders aria-hidden by default so it does not announce inside controls that already expose a busy state. Pass `label` to announce it standalone via role="status". Under reduced motion it slows rather than stopping, because a frozen loader reads as a hang.

## Image Accordion `image-accordion`

Image panels in a row — the open one widens and shows its caption, the rest stand as narrow strips — opened by hover, focus or press.

- Category: Display · Status: beta
- Install: `add image-accordion`
- npm: class-variance-authority
- Accessibility: An APG accordion: each panel's header is a button with aria-expanded inside a heading (`headingLevel`), controlling its caption, which is aria-hidden and inert while closed. Exactly one panel is open. Arrow keys move between headers (Left/Right mirrored under dir="rtl", Up/Down when vertical), Home and End jump to the ends. With `activateOn="hover"` a header opens on keyboard focus as well as mouse hover, so nothing is pointer-only; touch opens on tap. Images are decorative unless `imageAlt` is given. The widening stops animating under reduced motion.

## Image Metadata `image-metadata`

An image with a row of actions and a details button that opens a metadata panel, lifting the image to make room.

- Category: Display · Status: beta
- Install: `add image-metadata`
- Also installs: button
- npm: class-variance-authority
- Accessibility: A disclosure: the details toggle has aria-expanded and aria-controls, and the panel is a region named by the file name. Opening moves focus to the panel's Close button (the toggle it replaces is hidden); closing, with that button or Escape, returns focus to the toggle. Whichever of the action row and the panel is not shown is inert and aria-hidden. Metadata is a description list. The image needs real alt text. The lift and blur transitions stop under reduced motion.

## Image Selector `image-selector`

A photo grid with a Select mode: tick photos, see the count, share or delete them, and reset.

- Category: Forms · Status: beta
- Install: `add image-selector`
- Also installs: button
- npm: class-variance-authority, motion
- Accessibility: The grid is a list named by `label`. In Select mode each photo is a native checkbox named by the image's alt text — Tab reaches each, Space ticks it — with a visible focus ring on the photo. The Select toggle exposes aria-pressed; the selection count is a polite live region. Share and Delete are named icon buttons that become aria-disabled (not disabled) with nothing selected, so focus stays put after a delete. Tick marks are aria-hidden. The reflow after a delete uses motion inside MotionConfig reducedMotion="user"; the rest is CSS and stops under reduced motion.

## Inline Confirm `inline-confirm`

A destructive button that asks in place — it widens into Keep / Delete, then offers a timed Undo.

- Category: Forms · Status: beta
- Install: `add inline-confirm`
- Also installs: button
- npm: class-variance-authority
- Accessibility: A labelled group of real buttons. Asking moves focus to "Keep", the safe answer; Escape cancels and returns focus to the trigger. Confirming moves focus to "Undo" and announces the done label through a polite live region. The undo window pauses while keyboard focus is inside it, and its fuse stays still under reduced motion. When the window closes, focus returns to the trigger if it was inside.

## Input `input`

A single-line text field with size variants and native validation styling.

- Category: Forms · Status: stable
- Install: `add input`
- npm: class-variance-authority
- Accessibility: Always pair with a Label via htmlFor/id. Error state is driven by aria-invalid so assistive technology and styling stay in sync; describe the error with aria-describedby. FloatingLabelInput keeps a real <label for> as the accessible name whether resting or floated, and floats it with CSS alone.

## Invite Carousel `invite-carousel`

Event invitations fanned out as tilted cards — the current one upright in front, its neighbours leaning behind — advancing on a timer or by hand.

- Category: Display · Status: beta
- Install: `add invite-carousel`
- Also installs: button
- npm: class-variance-authority
- Accessibility: Follows the APG carousel pattern: a section with aria-roledescription="carousel", each card a labelled group with aria-roledescription="slide", and only the current card exposed (the neighbours are aria-hidden and inert). Automatic rotation — on by default, as in the source — has a stop/start control first in the tab order, pauses on hover and focus, turns the live region off while rotating, and does not start by itself under reduced motion. Previous/next buttons are named, arrow keys (mirrored in RTL), Home and End work inside it, and the fan mirrors under dir="rtl". Background images are decorative unless `imageAlt` is given; participant avatars take their name as alt text.

## Island `island`

A pill that morphs between views — idle, a call, a timer, a player — resizing around whatever it shows.

- Category: Display · Status: beta
- Install: `add island`
- npm: class-variance-authority
- Accessibility: The island is a container: the controls inside a view (play, skip, answer) are ordinary buttons and must be named by the consumer. Pass `live="polite"` to announce each new view — it is off by default, since an island that announces every change is noise. The resize and the incoming view's blur stop under reduced motion; the pill takes its new size immediately.

## Label `label`

An accessible caption that associates text with a form control.

- Category: Forms · Status: stable
- Install: `add label`
- npm: radix-ui
- Accessibility: Set htmlFor to the id of the control it labels. Clicking the label moves focus to that control, including composite widgets that are not native inputs.

## Liquid Toggle `liquid-toggle`

A switch whose knob squashes like a droplet as it travels, and can be dragged across.

- Category: Forms · Status: beta
- Install: `add liquid-toggle`
- npm: class-variance-authority, motion, radix-ui
- Accessibility: Built on the Radix switch primitive: role="switch" with aria-checked, toggled by click, Space or Enter, with a visible focus ring (missing in the source) and a hidden input inside forms. It has no visible label, so name it with aria-label or a <label>. Dragging the knob is a pointer convenience; releasing a drag never also counts as a click. Under reduced motion the knob jumps and never deforms.

## Log Viewer `log-viewer`

A streaming console with filtering, level facets and follow mode.

- Category: Data · Status: stable
- Install: `add log-viewer`
- npm: @tanstack/react-virtual
- Accessibility: role="log" implies aria-live="polite", which is right for a few events and unusable for a console — a screen reader would read every line of a build and nothing else would be audible. Announcing is off by default and opt-in. Virtualization is the harder trade: most rows are not in the DOM, so assistive technology cannot reach them, which is why the component takes an onDownload escape rather than pretending the virtual window is the whole log. Levels are written in text as well as coloured, matches use mark elements rather than a background colour, and an invalid pattern is announced instead of silently showing an empty log that reads as "nothing matched".

## Magnetic Button `magnetic-button`

A button that drifts toward the pointer — optionally with its label leaning further — and springs back when it leaves.

- Category: Forms · Status: beta
- Install: `add magnetic-button`
- Also installs: button
- Accessibility: The drift is decoration on an ordinary Button: name, role and keyboard behaviour are unchanged. It never runs for touch or coarse pointers, or under prefers-reduced-motion, and a disabled or loading button stays put. The `radius` option listens on the window rather than widening the hit area, so it never steals clicks from neighbouring controls.

## Magnetic Select `magnetic-select`

A honeycomb of round chips: choosing one grows it and magnetically shoves the rest apart, tilted, with a springy settle.

- Category: Forms · Status: beta
- Install: `add magnetic-select`
- npm: class-variance-authority
- Accessibility: A role="radiogroup" of native buttons with role="radio" and aria-checked, named by each option's `label`; the group needs aria-label or aria-labelledby and warns in development without one. Roving tabindex: Tab reaches the selected chip (or the first), arrow keys move focus and select with wrap-around (Left/Right follow the reading direction in RTL), Home/End jump to the ends. Images and skins are decorative. The spring is a CSS transition, so under reduced motion every chip settles at its final pose immediately; cursor parallax is mouse-only.

## Magnify Dock `magnify-dock`

A macOS-style dock whose icons grow, lift and show a label as the pointer or keyboard focus passes over them.

- Category: Navigation · Status: beta
- Install: `add magnify-dock`
- npm: class-variance-authority, radix-ui
- Accessibility: A toolbar (role="toolbar", named "Dock" by default, aria-orientation horizontal) with one roving tab stop: ArrowLeft/ArrowRight move between items (mirrored in right-to-left layouts, wrapping), Home/End jump to the ends, and disabled items are skipped. Items are real buttons, or links when given an href, named by their label; icons and the tooltip pill are aria-hidden. The active item carries aria-current="page" rather than aria-pressed: the dock marks where you are, like a nav bar, and only one item is ever current, so it is not a set of toggles. Magnification and the tooltip follow keyboard focus as well as hover, so keyboard users get the same feedback. Under reduced motion items still magnify, without animating.

## Marquee `marquee`

Scrolls its children in a seamless, endless loop — horizontal or vertical, at a set speed, pausing on hover and focus.

- Category: Display · Status: beta
- Install: `add marquee`
- npm: class-variance-authority
- Accessibility: The content is rendered once for assistive technology: the copy that closes the loop, and any `repeat` copies, are aria-hidden and inert, so nothing is announced or focused twice. It pauses while hovered or while focus is inside it, and `paused` stops it outright for a visible pause control (WCAG 2.2.2). Under prefers-reduced-motion it stops and becomes an ordinary, keyboard-focusable scroller. The loop runs toward the inline start, so it mirrors under dir="rtl".

## Meter `meter`

A measurement against a capacity — quota, seats, spend — segmented by category.

- Category: Feedback · Status: stable
- Install: `add meter`
- Accessibility: Uses role="meter", not role="progressbar": a meter reports a level with no expectation of reaching the end, and screen readers phrase the two differently. The bar is one meter and the segments inside it are decoration — making each its own widget would put several unlabelled meters in the tab order to describe one quantity. aria-valuetext carries the unit and the capacity, because a bare "4" says nothing about 4 of what. Per-segment detail lives in MeterLegend as text, where it can be read.

## Metric Delta `metric-delta`

A headline number with a change indicator that knows which direction is good.

- Category: Data · Status: stable
- Install: `add metric-delta`
- npm: class-variance-authority
- Accessibility: The meaning is never carried by colour and an arrow alone, which fails WCAG 1.4.1 — the direction and the comparison are always stated in text. The tile reads as one sentence rather than three fragments: the visible number and delta are aria-hidden and a single screen-reader description carries value, direction, comparison and, where given, sample size. A zero baseline is announced as having no percentage rather than as an infinite one.

## Morph Button `morph-button`

A button whose icon and label morph to an active state — toggles, transient confirmations and hover affordances.

- Category: Forms · Status: beta
- Install: `add morph-button`
- Also installs: button
- npm: class-variance-authority
- Accessibility: In `toggle` mode the state is exposed with aria-pressed and the accessible name stays the resting label, so "Mute" never becomes "Unmute, pressed". `transient` confirmations (Copied, Submitted) are announced through a polite live region and revert on a timer. `trigger="hover"` activates on keyboard focus as well as hover. Icons are aria-hidden: an icon-only button must be named with aria-label or aria-labelledby, and warns in development when it is not. Motion stops under reduced motion.

## Morph Surface `morph-surface`

A dock that grows in place into a panel — a feedback form or a quick prompt — and shrinks back when done.

- Category: Overlays · Status: beta
- Install: `add morph-surface`
- Accessibility: Behaves as a non-modal popover. The trigger is a disclosure button (aria-expanded, aria-controls) and the panel a named role="dialog". Opening moves focus into the panel (the message box in MorphSurfaceForm); Escape collapses it and returns focus to the trigger; pressing or tabbing outside collapses it without moving focus. A collapsed panel is inert and invisible; an expanded surface's dock is inert. MorphSurfaceForm's message box is labelled by the panel label, submits with ⌘/Ctrl + Enter (aria-keyshortcuts) or a named submit button, and a successful send is announced through a polite status region. The resize and fades stop under reduced motion.

## Notification Badge `notification-badge`

A dot, rolling count or presence badge pinned to the corner of an icon, button or avatar.

- Category: Feedback · Status: beta
- Install: `add notification-badge`
- Also installs: badge, number-flow
- npm: class-variance-authority
- Accessibility: Colour never carries the meaning alone: every badge has screen-reader text ("3 notifications", "More than 99 notifications", "New", "Online"…), overridable with `label`, while the visible digits are aria-hidden. A hidden count badge (zero, without showZero) is aria-hidden and empty. Changes are only announced when `live` is set. The text follows the wrapped element in reading order, so a wrapped icon button should still have its own name. The ping ring is not rendered under reduced motion, and the pop-in snaps.

## Notify Button `notify-button`

A “notify me” toggle: the bell rings and the label grows elastically into the confirmation.

- Category: Forms · Status: beta
- Install: `add notify-button`
- Also installs: button
- npm: class-variance-authority
- Accessibility: A toggle button exposed with aria-pressed. Its accessible name stays the resting label — the confirmation label is aria-hidden — and the confirmation is announced once through a polite live region when it turns on. The bell is decorative; its ring and the width spring stop under reduced motion.

## Now Playing `now-playing`

A compact music mini-player that expands in place, with a morphing play button, a like and a seek slider.

- Category: Display · Status: beta
- Install: `add now-playing`
- npm: class-variance-authority
- Accessibility: The track itself is the expand control: a button named by track and artist with aria-expanded. Restart, Play/Pause (its name follows the state), Next and a Like toggle (aria-pressed) are real buttons. Progress is a role="slider" with "0:52 of 3:34" value text: arrows seek 5 seconds (mirrored in right-to-left layouts), PageUp/PageDown 30, Home/End the ends, and Space plays or pauses while it has focus. Controls that are hidden while collapsed leave the tab order. Album art is decorative unless artworkAlt is given. Motion stops under reduced motion.

## Number Flow `number-flow`

A number whose digits roll to each new value — counters, prices, percentages and compact figures, formatted by Intl.NumberFormat.

- Category: Display · Status: beta
- Install: `add number-flow`
- npm: class-variance-authority
- Accessibility: The formatted value is rendered once as screen-reader text; the rolling reels are aria-hidden, so a reader hears "$1,234.56" rather than thirty digits per place. Nothing is announced when the value changes unless the consumer passes aria-live, and then only the settled value is announced (aria-atomic is set with it), never each digit. Under reduced motion every change snaps.

## Orb Face `orb-face`

A cartoon assistant orb whose gaze follows the pointer, who blinks, and whose expression tells its state — listening, thinking, speaking, done or broken.

- Category: AI · Status: beta
- Install: `add orb-face`
- npm: motion
- Accessibility: Decorative: aria-hidden unless given aria-label or aria-labelledby, when it becomes role="img" — keep that label in step with `state`, and keep a text status nearby, because an expression is not a word. It is never a live region. Under reduced motion the gaze, blinking and thinking glances are switched off and every keyframe stops, leaving each state's settled face; the gaze spring is the only use of `motion`.

## OTP Input `otp-input`

A one-time-code field drawn as a row of animated slots — paste, SMS autofill, masking and grouping included.

- Category: Forms · Status: beta
- Install: `add otp-input`
- npm: class-variance-authority
- Accessibility: One real text input with autocomplete="one-time-code" and a numeric inputmode sits over the slots, so paste, SMS autofill, password managers and screen readers all meet a single labelled field holding the code; the painted slots are aria-hidden. Every prop except className lands on that input, so FormField's id, aria-describedby and aria-invalid wire up through FormControl. It is named "One-time code" only when given no aria-label, aria-labelledby or id. Arrow keys, Home and End move between slots; typing over a filled slot replaces it. The slots stay left-to-right in RTL, as codes are read. Slot, digit and caret motion is decoration and stops under reduced motion, leaving the caret visible.

## Pagination `pagination`

Navigation between pages of a list.

- Category: Navigation · Status: stable
- Install: `add pagination`
- Also installs: button
- npm: radix-ui
- Accessibility: A named nav landmark. The current page carries aria-current="page" — styling it differently conveys nothing on its own. Links by default, since a page of results is a place worth sharing; use asChild for your router's link, or render buttons when paging only changes client state. The optional sliding pill (indicator="slide") is an aria-hidden list item, so the list's item count stays the number of pages, and it stops sliding under reduced motion.

## Palette Generator `palette-generator`

A row of swatches that melt together through a goo filter and pop back out in a new palette.

- Category: Effects · Status: beta
- Install: `add palette-generator`
- Also installs: button
- npm: class-variance-authority
- Accessibility: The refresh control is a named button ("Generate a new palette") with a focus ring. The swatches are a labelled list of images named by colour, and each new palette is announced through a polite live region (missing in the source). The melt is decoration: under reduced motion the colours swap at once.

## Permission Matrix `permission-matrix`

Roles across, permissions down, with inheritance, locked roles and one tab stop.

- Category: Data · Status: stable
- Install: `add permission-matrix`
- Also installs: checkbox
- Accessibility: A grid in the WAI-ARIA sense: role="grid" with one tab stop, arrow keys between cells, Home and End along a row and Ctrl with them across the whole matrix — the right call for a matrix that is operated, where it was the wrong one for a diff that is read. Every checkbox is named by both coordinates, "Delete projects for Editor", so a reader arriving by arrow key knows where they are without re-reading the headers. An inherited grant is a checked box that cannot be changed here, marked aria-disabled rather than disabled so it stays in the keyboard path, with the role it came from as its description. A locked role says in each cell's description that nothing can be changed. Group toggles are tri-state, and the column header counts each role's grants in text.

## Photo Stack `photo-stack`

A pile of photos: flick the top one away and it springs to the back, or tap, key or button through them.

- Category: Display · Status: beta
- Install: `add photo-stack`
- Also installs: button
- npm: motion, radix-ui
- Accessibility: A carousel region (aria-roledescription="carousel") of labelled slides; only the top photo is exposed, the rest are aria-hidden and inert. The top photo carries a real button ("Show next photo") so Enter and Space cycle it; arrow keys move either way (mirrored in right-to-left layouts); optional previous/next buttons give a visible pointer-free path; a polite status region announces the new photo. Dragging is a convenience on top of these and is switched off under reduced motion, where cards also move without animating.

## Photo Tabs `photo-tabs`

A photo with a floating bar of icon tabs; each tab swaps the photo.

- Category: Display · Status: beta
- Install: `add photo-tabs`
- Also installs: tabs
- npm: class-variance-authority
- Accessibility: Built on Dowel's Tabs: the ARIA tabs pattern with roving focus, arrow keys, Home/End and focusable panels. The tab list is named by `listLabel`; each icon-only tab carries its label as visually hidden text and the icon is aria-hidden. Each panel's image has alt text (defaulting to the label). With a fine pointer the bar hides until the photo is hovered or anything inside it has focus, so keyboard users always see it; on touch it is always visible. The hover pill is aria-hidden and its movement stops under reduced motion.

## Pixel Avatar `pixel-avatar`

A deterministic pixel avatar generated from a seed — crisp SVG, coloured from theme tokens, with a gentle shimmer.

- Category: Display · Status: beta
- Install: `add pixel-avatar`
- npm: class-variance-authority
- Accessibility: Decorative by default (aria-hidden), for the usual case of an avatar beside a visible name. Pass aria-label — the agent's name, not the seed — to make it role="img". The shimmer is decoration and stops under reduced motion, leaving the resting grid.

## Popover `popover`

Rich floating content anchored to a trigger.

- Category: Overlays · Status: stable
- Install: `add popover`
- npm: radix-ui
- Accessibility: The content has role="dialog" and therefore REQUIRES an accessible name — pass aria-label, or aria-labelledby pointing at a heading inside it. A development-only warning fires if neither is present. The trigger exposes aria-expanded and aria-controls; Escape closes and returns focus to it. Non-modal by default, so the rest of the page stays reachable; pass `modal` only when the content is a task the user must finish or abandon.

## Product Card `product-card`

A shop tile with image zoom, badge, half-star rating, discount pricing, a wishlist toggle and an add-to-cart confirmation.

- Category: Display · Status: beta
- Install: `add product-card`
- Also installs: badge, morph-button
- Accessibility: The card is an article named by its title; with href the title becomes a link stretched over the card while the buttons stay above it. The rating is one image labelled "Rated 4.5 out of 5". Prices read in order ("Now $129.00, was $179.00, 28% off") rather than relying on strikethrough and colour. The wishlist heart is a toggle with aria-pressed and a stable name, always visible rather than revealed on hover. Add to cart morphs to "Added", announces it through a polite status region and reverts, without ever disabling the button. The entrance animation is skipped under reduced motion.

## Progress `progress`

Shows how far along a task is, or that one is running at all.

- Category: Feedback · Status: stable
- Install: `add progress`
- npm: class-variance-authority, radix-ui
- Accessibility: Exposed as role="progressbar" with aria-valuenow, and give it a name with aria-label or aria-labelledby. Omitting `value` marks it indeterminate, which is announced differently from zero. Show the percentage in text as well — the bar alone is not readable at a glance for everyone. The optional stripe and shine effects are decoration: they stop under reduced motion and never apply to an indeterminate bar.

## Pull to Refresh `pull-to-refresh`

A sheet you pull down to refresh, with rubber-band resistance, a dot ring that fills as you pull and springs that carry the pull's velocity.

- Category: Feedback · Status: beta
- Install: `add pull-to-refresh`
- Also installs: button
- npm: class-variance-authority, motion
- Accessibility: The sheet is a named, focusable group described by a hint; Enter on it refreshes, and a visible Refresh button (showRefreshButton, on by default) gives a pointer-free path for touch and screen reader users, so pulling is never the only way. While refreshing the sheet is aria-busy and a polite status region announces "Refreshing…" then "Refreshed". The dot ring is aria-hidden decoration and stops under reduced motion, where the springs are also instant; the refresh itself still works. A pull only starts when the sheet is scrolled to the top, and the click a pull leaves behind is swallowed.

## Radial Menu `radial-menu`

A round button whose options fan out along an arc: press and drag onto one, click, or walk the ring with the keyboard.

- Category: Navigation · Status: beta
- Install: `add radial-menu`
- npm: class-variance-authority
- Accessibility: The core is a menu button (aria-haspopup="menu", aria-expanded, aria-controls) named by `label`; the options are role="menuitem" buttons named by their labels, in a role="menu" that is inert and aria-hidden while closed. Enter/Space opens and focuses the first option (Down/Up open onto the first or last); Left/Right and Up/Down walk around the ring with wrap-around (Left/Right follow the visual order in RTL), Home/End jump, Enter/Space select and return focus to the core, Escape closes and refocuses the core, Tab and an outside press close. The press-and-drag marking gesture is a pointer shortcut only; clicking and the keyboard reach every option. Captions are aria-hidden duplicates of the names. The fly-out settles instantly under reduced motion.

## Radio Group `radio-group`

A set of mutually exclusive options.

- Category: Forms · Status: stable
- Install: `add radio-group`
- npm: radix-ui
- Accessibility: Arrow keys move between options and select as they go, and the group is a single tab stop — the standard radio model. Give the group an accessible name with aria-labelledby, and each item a Label tied by htmlFor/id.

## Range Dial `range-dial`

A 24-hour circular two-thumb range — drag or key the start and end round a ticked clock face, with the duration in the middle.

- Category: Forms · Status: beta
- Install: `add range-dial`
- Accessibility: A labelled role="group" (default "Time range") holding two focusable role="slider" thumbs ("Start time", "End time"), each with aria-valuemin 0, aria-valuemax 1439, aria-valuenow in minutes and an aria-valuetext time such as "10:30 PM" (locale-aware, overridable). Arrow keys step by the snap, Page Up/Down by an hour, Home/End jump to midnight and the last step of the day, all wrapping round midnight; up/right always add time because a clock face does not mirror. The centre readout has a spoken equivalent, and a polite live region announces the new duration only after a change. Ticks and knobs are aria-hidden; the pointer grabs the nearest thumb and moves focus to it. Tick draw-in runs through --motion-scale and is instant under reduced motion.

## Record Diff `record-diff`

Field-level before and after, for audit entries, settings history and revisions.

- Category: Data · Status: stable
- Install: `add record-diff`
- Accessibility: A real table, not a grid of divs. Each field name is a th with scope="row", so a value is announced with the field it belongs to rather than as a loose cell. The kind of change is never carried by row colour alone — every row states added, removed or changed in text for screen readers, satisfying WCAG 1.4.1. The unchanged-field toggle is a real button with aria-expanded. Redacted values never reach the DOM at all.

## Reorder List `reorder-list`

A short list of people or things you put in order by dragging liquid pills, or with Space and the arrow keys.

- Category: Forms · Status: beta
- Install: `add reorder-list`
- Also installs: avatar
- npm: class-variance-authority, motion
- Accessibility: A real list (ol, role=list, named by aria-label) whose rows are buttons named by their label and described by the keyboard instructions. Space or Enter picks a row up (aria-pressed), ArrowUp/ArrowDown or Home/End move it, Space or Enter drops it and Escape (or leaving the row) cancels and restores the original order; without a grab the arrows move focus between rows. Focus stays on the moved row. A polite, visually hidden status region announces each grab, move, drop and cancel (messages overridable for i18n), including drops made by pointer. The goo layer of pill backgrounds is aria-hidden and separate from the text, and avatars are decorative. Under reduced motion nothing deforms and rows jump to their slots.

## Reviews Carousel `reviews-carousel`

Testimonials stacked in depth — the active review in front, the next ones receding behind — stepped through with buttons, indicators or arrow keys.

- Category: Display · Status: beta
- Install: `add reviews-carousel`
- Also installs: button
- npm: class-variance-authority
- Accessibility: Follows the APG carousel pattern: a section with aria-roledescription="carousel", each review a labelled group with aria-roledescription="slide", and only the active one exposed (the rest are aria-hidden and inert). Previous/next buttons and indicator buttons are named, the current indicator carries aria-current, and the end buttons use aria-disabled so focus is never dropped. Arrow keys (mirrored in RTL), Home and End work while focus is inside. `autoPlay` adds a stop/start control, pauses on hover and focus, turns the live region off while rotating, and does not start by itself under reduced motion.

## Rich Popover `rich-popover`

A popover card for an inline reference — heading or link, description, a meta chip and one call to action.

- Category: Overlays · Status: beta
- Install: `add rich-popover`
- Also installs: popover
- npm: class-variance-authority
- Accessibility: Built on Dowel's Popover: the content is a role="dialog" labelled by its heading, opens from pointer or keyboard, closes on Escape or an outside press and returns focus to the trigger. The trigger must be a focusable element with an accessible name (an icon-only trigger needs aria-label). Links open in a new tab with rel=noopener; the leading icon, chip icon and arrow are decorative. The blur-in stops under reduced motion.

## Ring Loader `ring-loader`

Indeterminate loading indicators made of rings and spinners — classic, sweep, radar, gears and 26 more motions.

- Category: Feedback · Status: beta
- Install: `add ring-loader`
- npm: class-variance-authority
- Accessibility: Renders aria-hidden by default so it does not announce inside controls that already expose a busy state. Pass `label` to announce it standalone via role="status". Under reduced motion it slows rather than stopping, because a frozen loader reads as a hang.

## Scramble Text `scramble-text`

Text whose characters churn through random glyphs and resolve from the inline start, on hover, focus, mount or view.

- Category: Effects · Status: beta
- Install: `add scramble-text`
- npm: class-variance-authority
- Accessibility: The scrambling glyphs are aria-hidden; an sr-only copy of the real text is what assistive technology reads, so nothing is announced per frame. The server renders the real text. It is not itself interactive: hover and keyboard focus on the nearest link or button that wraps it trigger the effect. No scramble under reduced motion.

## Scroll Reveal Text `scroll-reveal-text`

A paragraph whose words brighten from dim to full as it scrolls through the viewport.

- Category: Effects · Status: beta
- Install: `add scroll-reveal-text`
- npm: class-variance-authority
- Accessibility: The words are aria-hidden and the paragraph is read once from an sr-only copy. Driven by CSS scroll-driven animation where supported, with a frame-throttled scroll fallback; without either, and under reduced motion, every word is fully legible. Dimmed words are below contrast by design until revealed, so keep essential content out of it.

## Scrubber `scrubber`

A design-tool number field: drag across a labelled bar to scrub a value, step it from the keyboard, or type it.

- Category: Forms · Status: beta
- Install: `add scrubber`
- npm: class-variance-authority, radix-ui
- Accessibility: The bar is a focusable role="slider" named by its visible label, with aria-valuenow, -valuemin, -valuemax and an aria-valuetext matching the number on screen. Arrow keys step (Left/Right follow the reading direction), Shift + arrow and Page Up/Down take large steps, Home/End jump to the ends. Enter or a double-click opens a text field for an exact value (advertised with aria-keyshortcuts); Enter or blur commits, Escape cancels, and focus returns to the slider. Ticks, fill and thumb are aria-hidden. The thumb's transitions stop under reduced motion.

## Secret Field `secret-field`

An API key in its three states: shown once, hidden but revealable, and gone.

- Category: Forms · Status: stable
- Install: `add secret-field`
- Also installs: button, input
- Accessibility: The value sits in a read-only input rather than a disabled one, so it can be focused, selected and read, and focusing a shown value selects all of it for copying by hand. The field's state — shown once, hidden, revealed, gone — is a sentence attached as its description, never a colour or an icon. Copying is announced through a status region that exists before the first copy, and failure is announced too, with what to do instead, because the clipboard can be refused. Every button carries the field's label in its name, so a settings page with several keys has several distinct Copy buttons. Regenerating is confirmed inline in a named group that states the consequence, since it revokes the current key.

## Select `select`

Picks one value from a short list of options.

- Category: Forms · Status: stable
- Install: `add select`
- npm: class-variance-authority, radix-ui
- Accessibility: Full listbox keyboard model: arrows move, typeahead jumps, Enter selects, Escape closes and restores focus. Give the trigger a name with aria-labelledby or a Label. Past about a dozen options prefer Combobox — scrolling a long listbox by keyboard is slow. The opening pop, option stagger and tick pop are decoration and stop under reduced motion.

## Selection List `selection-list`

A multi-select list of people with a liquid tick and an action that springs out from under it once someone is picked.

- Category: Forms · Status: beta
- Install: `add selection-list`
- Also installs: avatar, button
- npm: class-variance-authority
- Accessibility: The list is a role="listbox" aria-multiselectable="true" with a single tab stop; name it with aria-label (default "Select people") or aria-labelledby. Rows are role="option" with aria-selected. ArrowUp/ArrowDown rove with wrap-around, Home/End jump, Space/Enter toggle and Ctrl/Cmd+A selects or clears everything. The hover highlight follows keyboard focus as well as the pointer. The action button is disabled, inert and aria-hidden while tucked away (nothing selected); a pending action shows aria-busy, and the done label is announced through a polite live region. When the action tucks away again focus returns to the list. The tick, avatars and highlight are aria-hidden; under reduced motion the goo fill becomes a plain fill.

## Separator `separator`

A horizontal or vertical rule that divides content.

- Category: Layout · Status: stable
- Install: `add separator`
- npm: radix-ui
- Accessibility: Decorative by default and hidden from assistive technology. Set decorative={false} to expose it as a semantic separator when it divides meaningfully distinct groups.

## Session Expiry `session-expiry`

The idle-timeout warning WCAG 2.2.1 asks for: warned, extendable, and not dismissable by accident.

- Category: Feedback · Status: stable
- Install: `add session-expiry`
- Also installs: button, dialog
- Accessibility: An alert dialog, named by its heading and described by the sentence that says how long is left. Escape and the backdrop do nothing, because dismissing a session warning without choosing is choosing nothing; the two buttons are the way out, and focus opens on the safe one. The visible countdown is not live — a number every second for two minutes drowns the question — and a separate status region speaks four times: when the warning opens, at one minute, thirty seconds and ten, still saying a threshold a slow tick skipped over. The clock is read in an effect, so the server renders nothing rather than a countdown from the wrong instant. This satisfies the warn-and-extend half of WCAG 2.2.1 Timing Adjustable; the twenty-second minimum is the default window's business and the application's.

## Shader Transition `shader-transition`

Transitions a frame between two states under a full-frame WebGL reveal — one raw-WebGL engine and sixteen presets (aperture, chroma, prism, SDF blobs and circles, noise, wipe, stripes, spiral…).

- Category: Effects · Status: beta
- Install: `add shader-transition`
- Accessibility: Both states are real DOM; the shader only paints a decorative, aria-hidden cover over the frame. While a run is in progress the outgoing state is aria-hidden and inert, the incoming state is in the accessibility tree from the first frame, and focus inside the outgoing state moves to the incoming one. The root is aria-busy while running. Reduced motion (OS setting or --motion-scale 0) swaps instantly; without WebGL, or if the context is lost mid-run, the states cross-fade instead.

## Shape Loader `shape-loader`

Indeterminate loading indicators made of geometric shapes — flipping squares, hexagons, hourglasses, hearts and 31 more motions.

- Category: Feedback · Status: beta
- Install: `add shape-loader`
- npm: class-variance-authority
- Accessibility: Renders aria-hidden by default so it does not announce inside controls that already expose a busy state. Pass `label` to announce it standalone via role="status". Under reduced motion it slows rather than stopping, because a frozen loader reads as a hang.

## Sheet `sheet`

A panel that enters from an edge of the viewport for secondary content.

- Category: Overlays · Status: stable
- Install: `add sheet`
- npm: class-variance-authority, radix-ui
- Accessibility: Modal, with the same focus trapping and restoration as Dialog. Always render a SheetTitle. For a side navigation sheet, put a nav landmark inside rather than relying on placement to convey the role. The optional section stagger stops under reduced motion.

## Shimmer Text `shimmer-text`

Text with a light band sweeping across it on a loop, or a blur-and-glide entrance as it arrives.

- Category: Effects · Status: beta
- Install: `add shimmer-text`
- npm: class-variance-authority
- Accessibility: The text is never split, so it reads as one run and copies cleanly. The effect is decoration: under reduced motion the shine becomes plain text in the base colour and the entrance settles at once to its visible end state. In forced-colours mode the clipped gradient is dropped so the text takes the system colour. Pick base and shine colours that both meet contrast against the background.

## Shortcut Recorder `shortcut-recorder`

Press the keys you want: records a chord, platform-aware, and says when it clashes.

- Category: Forms · Status: stable
- Install: `add shortcut-recorder`
- Accessibility: The recorder is a button named by what the shortcut does and described by its value in words — Command Shift K — while the key caps on it are hidden from assistive technology, since ⌘⇧K read aloud is noise. While recording it is aria-pressed and its description says what to do; Tab always leaves and Escape always cancels, so it is never a keyboard trap. Every outcome is announced through a status region present from the start: recorded, refused with the reason, clashing with which command, cancelled, cleared. Symbols are shown on a Mac and words elsewhere, and the description uses the platform's own names for its keys.

## Sidebar `sidebar`

The application's own navigation: a collapsible rail on a wide screen, an overlay on a narrow one.

- Category: Navigation · Status: stable
- Install: `add sidebar`
- Also installs: sheet
- npm: radix-ui
- Accessibility: The navigation landmark must be named — a page has several, and three regions all called "navigation" is a list nobody can choose from. The active entry carries aria-current="page" rather than only a background colour. On a narrow screen it is a Sheet, not a styled div: an overlay needs a focus trap and an Escape key, and without them the page behind stays reachable by Tab while the menu covers it. When the rail collapses, labels are visually hidden rather than removed — removing them leaves controls whose only content is an icon, which is how a collapsed sidebar becomes a column of links all announced as "link". The trigger says what pressing it will do, not what the state currently is. The overlay is mounted only on a narrow screen and has its own open state: a modal dialog that CSS hides is still modal, and mounting it always made every wide screen aria-hidden and unclickable whenever the rail was open.

## Skeleton `skeleton`

A shaped placeholder that holds layout while content loads.

- Category: Feedback · Status: stable
- Install: `add skeleton`
- Accessibility: Hidden from assistive technology. Put aria-busy on the container that owns the loading data so the state is announced once instead of once per placeholder. Pulse and shimmer are decoration and stop under reduced motion.

## Slide to Confirm `slide-to-confirm`

A track whose grip you slide to the end to confirm — bencho's wash-and-morph pill or SmoothUI's power-off slide — with a press-and-hold path.

- Category: Forms · Status: beta
- Install: `add slide-to-confirm`
- npm: class-variance-authority, motion, radix-ui
- Accessibility: The grip is a real button named by the label and described by a hint. Pressing and holding Enter or Space (or holding the pointer still on it) carries the grip across over holdDuration and confirms; letting go early sends it back, so dragging is never the only way through. The result ("Confirmed" / "Shutting down…") is announced through a polite status region. The grip travels toward the inline end and its arrow mirrors in right-to-left layouts. Under reduced motion the springs are instant, the shimmer stops and the hold still works.

## Slider `slider`

Selects a value, or a range, from a continuous span.

- Category: Forms · Status: stable
- Install: `add slider`
- npm: radix-ui
- Accessibility: Each thumb is a role="slider" with arrow keys, Home/End and Page Up/Down. The name is forwarded onto the thumbs, since the root has no role — a range slider should name each thumb separately with thumbLabels. A development-only warning fires if a thumb would be unnamed. Pass aria-valuetext when the raw number is not meaningful on its own (a price, a duration). Show the current value on screen too — a slider is imprecise, so pair it with a numeric input when exactness matters.

## Slosh Slider `slosh-slider`

A slider whose fill behaves like liquid: the knob jumps to the value while the fill springs after it, leaning as it moves.

- Category: Forms · Status: beta
- Install: `add slosh-slider`
- npm: class-variance-authority, motion, radix-ui
- Accessibility: Built on the Radix slider: the knob is a focusable role="slider" with aria-valuenow, -valuemin and -valuemax, pointer jump-to-value, arrow keys (mirrored in right-to-left layouts), Home/End, and Page Up/Down moving by largeStep. aria-label, aria-labelledby and aria-valuetext (or formatValue) are forwarded onto the thumb, and a development warning fires when it is unnamed — no default name is baked in. The focus ring is drawn around the whole bar. The liquid fill is aria-hidden decoration; under reduced motion it jumps with the knob and never leans.

## Social Selector `social-selector`

Pick a social platform from a row of icons — a pill slides behind the choice and the caption links to the profile.

- Category: Forms · Status: beta
- Install: `add social-selector`
- npm: class-variance-authority, radix-ui
- Accessibility: A Radix radio group named by `label`: one tab stop, arrow keys move and select (following the reading direction), and the value submits with a form under `name`. Each icon-only radio is named by the platform's `name`; icons and the sliding pill are aria-hidden. Caption links say when they open in a new tab. The pill's slide and the caption's blur-in stop under reduced motion.

## Spinner `spinner`

An indeterminate loading indicator for buttons, panels and inline content.

- Category: Feedback · Status: stable
- Install: `add spinner`
- npm: class-variance-authority
- Accessibility: Renders aria-hidden by default so it does not announce inside controls that already expose a busy state. Pass `label` to announce it standalone via role="status".

## Star Count `star-count`

An animated star counter — plain or as a star button — with the stargazers' avatars beside it. The count is a prop; nothing is fetched.

- Category: Display · Status: beta
- Install: `add star-count`
- Also installs: avatar-group, number-flow
- npm: class-variance-authority
- Accessibility: The settled count is screen-reader text ("1,234 stars") while the rolling digits and the star icon are aria-hidden, so a reader never hears the count-up. With href the counter is a real link with a focus ring. Stargazers are an AvatarGroup list named by stargazersLabel. Under reduced motion the count appears settled and the star does not pop.

## Stepper `stepper`

A multi-step wizard's progress — connectors fill, finished steps draw a check, and each step's content slides in from the side it comes from.

- Category: Navigation · Status: beta
- Install: `add stepper`
- npm: class-variance-authority
- Accessibility: An ordered list named "Progress", with aria-current="step" on the current step and finished steps named with a visually hidden "completed". Steps are plain list items unless `navigation` makes them choosable; then they are buttons sharing one tab stop, moved between with the arrow keys (mirrored in RTL, Up/Down when vertical), Home and End, and chosen with Enter or Space. The content area is a group labelled by the current step. Horizontal labels collapse to screen-reader-only text on narrow screens. All motion is CSS decoration and stops under reduced motion.

## Swipe Carousel `swipe-carousel`

Cards on a ring seen from the front — swipe, tap or step and the ring turns, so nothing ever leaves the frame.

- Category: Display · Status: beta
- Install: `add swipe-carousel`
- Also installs: button
- npm: class-variance-authority, motion
- Accessibility: Follows the APG carousel pattern: a section with aria-roledescription="carousel", each card a labelled group with aria-roledescription="slide", and only the front card exposed (the others are aria-hidden and inert). The swipe is never the only way through: named previous/next buttons, arrow keys (mirrored in RTL), Home and End, and a tap on a card peeking out at either side all turn the ring. A drag that ends over a link in the front card does not follow it. Under reduced motion the ring jumps instead of springing and the idle float stops; the spring is `motion`, wrapped in MotionConfig reducedMotion="user".

## Switch `switch`

An immediate on/off toggle for settings that apply straight away.

- Category: Forms · Status: stable
- Install: `add switch`
- npm: radix-ui
- Accessibility: Exposed as role="switch" and toggled with Space or Enter. Needs a visible label tied with htmlFor/id. Do not rely on colour alone to show state — position and the label carry it too. Icons passed to `icons` are aria-hidden decoration; the press squash only runs without a reduced-motion preference.

## Switchboard Card `switchboard-card`

A feature card illustrated by a grid of tiny lights — a lit pattern such as a word, or random flicker.

- Category: Display · Status: beta
- Install: `add switchboard-card`
- npm: class-variance-authority, radix-ui
- Accessibility: The lights are decorative and aria-hidden unless illustrationLabel describes them (a pattern spelling a word), in which case the grid is a single role="img". The heading level is set with headingAs. With href the whole card is one link, or use asChild to render a router link or a button; the focus ring is shared. The flicker pauses off-screen and in hidden tabs, and under reduced motion it never starts: a still frame is shown instead.

## Sync Status `sync-status`

Offline, saving, saved or failed — with the count of changes being held.

- Category: Feedback · Status: stable
- Install: `add sync-status`
- Also installs: button
- Accessibility: The word is the status and the coloured dot is decoration, hidden from assistive technology. The visible text is not a live region: every save flips it and a region on it would narrate the whole session. A separate region, present from the first render, announces transitions only — went offline with what will happen to the changes, came back with what is being saved, could not save, saved after a failure — and never the churn of saving itself. Announcing is on by default because going offline is the one thing a reader who is typing has to be told, and it can be turned off. The server render assumes online, since a page with no interface to report has no business saying offline.

## Table `table`

Semantic table primitives for tabular data.

- Category: Data · Status: stable
- Install: `add table`
- Accessibility: A native table, so row and column position, header association and dimensions are all announced without ARIA. Give it a name with TableCaption or aria-label. The scrolling wrapper is focusable so an overflowing table can be scrolled by keyboard — without that, columns past the edge are unreachable. Use scope="row" on th elements inside tbody.

## Tabs `tabs`

Switches between panels of related content.

- Category: Navigation · Status: stable
- Install: `add tabs`
- npm: class-variance-authority, radix-ui
- Accessibility: Implements the ARIA tabs pattern: arrows move between tabs, Home/End jump to the ends, and only the active tab is in the tab sequence. Panels are focusable so keyboard users reach their content directly. Use activationMode="manual" when showing a panel is expensive, so arrowing past it does not load it. The optional sliding indicator (indicator="slide") is aria-hidden decoration; selection is still conveyed by aria-selected, and the slide stops under reduced motion.

## Tags Input `tags-input`

A list of short values, where invalid entries stay visible instead of vanishing.

- Category: Forms · Status: stable
- Install: `add tags-input`
- Accessibility: No WAI-ARIA pattern covers a token field, and the near misses misdescribe it — these are committed values, not options being chosen, so calling the container a listbox would promise navigation that does not exist. It is a labelled group holding a list, with a remove button per token carrying the tag in its accessible name. An invalid token's reason is inside the token, so it is announced with it rather than as a detached error. Additions, removals and refusals all reach a polite live region, because a refusal that looks like nothing happening is the failure this component exists to prevent. Remove buttons sit in the natural tab order rather than behind a roving tabindex: it costs a tab stop per token, and buys a pattern every assistive technology already understands. With animateExit, a removed token lingers only as an aria-hidden, inert copy while it animates out.

## Text Effect `text-effect`

Text that animates in by character, word or line — blur, rise, mask, spring, centre-out, phrase builds and a wave, as 19 presets.

- Category: Effects · Status: beta
- Install: `add text-effect`
- npm: class-variance-authority
- Accessibility: The split pieces are aria-hidden and an sr-only copy carries the whole string, so screen readers read the sentence once, not letter by letter; `as` keeps heading semantics. Nothing is announced on its own: pass aria-live to announce the settled text when `children` changes, never per piece. The motion is decoration — under reduced motion every entrance lands at rest in one frame and the wave stops after one pass, back at rest.

## Text Loader `text-loader`

Indeterminate loading indicators made of words and interface shapes — shimmer, typing, skeleton, terminal and 15 more motions.

- Category: Feedback · Status: beta
- Install: `add text-loader`
- npm: class-variance-authority
- Accessibility: Renders aria-hidden by default so it does not announce inside controls that already expose a busy state; the words it shows are decoration. Pass `label` to announce it standalone via role="status". Under reduced motion it slows rather than stopping, because a frozen loader reads as a hang.

## Text Swap `text-swap`

Text that animates from the old string to the new one when its value changes — fade through, shared axis X/Y/Z and per-word crossfade — with a TextRotate for cycling phrases.

- Category: Effects · Status: beta
- Install: `add text-swap`
- npm: class-variance-authority
- Accessibility: The incoming text is the accessible text from the moment it changes; the outgoing copy is aria-hidden while it animates out and is then removed, and a change mid-transition replaces the pending text rather than stacking copies. Per-word transitions keep the whole string in a visually hidden copy with the word spans aria-hidden. Nothing is a live region unless you pass aria-live, and then only the settled value is added, never per word. Under reduced motion the swap is instant and TextRotate stops rotating; `paused` stops it on demand. shared-axis-x mirrors in RTL so forward always arrives from the inline end.

## Textarea `textarea`

A multi-line text field, with optional auto-resize and a character count that knows when to stay quiet.

- Category: Forms · Status: stable
- Install: `add textarea`
- npm: class-variance-authority
- Accessibility: Pair with a Label via htmlFor/id. The error state is driven by aria-invalid, so assistive technology and styling stay in sync. The character count is described by the field rather than announced on every keystroke — a permanently live counter reads the remaining number between every letter typed, which is unusable — so it goes live only once the limit is close, and states the remainder in words rather than as a bare ratio that is read aloud as two unlabelled numbers. Horizontal resizing is off by default, because a field dragged wider than its container is a broken layout.

## Tick Progress `tick-progress`

A percentage drawn as a row of waveform ticks under a big figure — a progress bar, or a slider with hover preview.

- Category: Data · Status: beta
- Install: `add tick-progress`
- npm: class-variance-authority
- Accessibility: Display mode is a role="progressbar" with aria-valuenow and a "%" value text. `interactive` makes it a role="slider": focusable, with a focus ring; arrows step one tick (mirrored in right-to-left layouts), PageUp/PageDown five, Home/End the ends, and keys commit immediately as the APG slider pattern requires. Hover preview and click-to-commit are pointer conveniences over that. The ticks and the figure are aria-hidden because the role already carries the value; name it with aria-label or aria-labelledby.

## Tilt Card `tilt-card`

A card that tilts in 3D toward the pointer, with a glare that follows it and layers that float at their own depth, springing back flat on leave.

- Category: Display · Status: beta
- Install: `add tilt-card`
- Also installs: card
- Accessibility: The tilt is decoration on an ordinary Card: it adds no role, name or tab stop, so a card that acts as a link should contain a real link (the stories stretch one over the card). The glare layer is aria-hidden and ignores the pointer. The card stays flat for touch and coarse pointers and under prefers-reduced-motion. Keyboard focus on the card or anything inside it shows a small static lift instead of a tilt, and a focusable card gets the standard focus ring.

## Time Range Picker `time-range-picker`

A time range whose value is an expression, so it stays relative across a reload.

- Category: Forms · Status: stable
- Install: `add time-range-picker`
- Also installs: button, calendar, input, popover
- npm: react-day-picker
- Accessibility: The trigger is named by the range it holds — "Last 6 hours" — and the window that resolves to is read after it, so the relative choice is not replaced by two timestamps. The popover carries role="dialog" and is named. Presets are buttons rather than radios because choosing one both selects and dismisses, with aria-pressed carrying which matches the current expression. The expression field reports why an unparseable entry is invalid through one aria-describedby element that the preview and the error share, so a reader hears the error replace the preview rather than both at once; an invalid expression is never applied, because a chart silently re-scoping itself is worse than one that refuses.

## Time Stack `time-stack`

Cards receding in depth, stepped through with a timeline scrubber, the mouse wheel or the arrow keys.

- Category: Display · Status: beta
- Install: `add time-stack`
- npm: class-variance-authority
- Accessibility: The scrubber is a vertical role="slider" whose aria-valuetext names the moment ("1w ago: Forest Trail"). Newest is at the bottom, so ArrowUp/ArrowRight go back in time as a vertical slider requires; ArrowDown/Left, Page Up/Down, Home and End work too. Only the current card is exposed (a labelled group); the cards behind and before it are inert. Wheel steps are announced through a polite status, and the wheel only captures scrolling while there is a card to step to. Motion stops under reduced motion.

## Toast `toast`

Brief, non-blocking messages with an imperative API callable from anywhere.

- Category: Feedback · Status: stable
- Install: `add toast`
- npm: class-variance-authority, radix-ui
- Accessibility: Toasts are announced through a live region: destructive and warning variants interrupt (foreground), the rest wait for a pause (background). Auto-dismiss timers pause on hover, focus and window blur, and F8 moves focus into the toast list from anywhere. An action must carry altText describing how to do the same thing without the toast, since it may be gone before a screen reader user reaches it. The optional spring entrance stops under reduced motion.

## Todo Tower `todo-tower`

To-do cards stacked like bricks: tick one and it flicks away as the cards above drop; drag one and the stack sways.

- Category: Display · Status: beta
- Install: `add todo-tower`
- npm: class-variance-authority, motion
- Accessibility: A labelled list. Each card's check is a real button named "Done: <task>", so Tab and Enter/Space complete tasks; completion is announced politely and focus moves to the card that drops into the gap. Dragging and swaying the stack is decoration with no keyboard equivalent because it does nothing. Under reduced motion there is no sway, flick or drop.

## Tooltip `tooltip`

A short label revealed on hover or keyboard focus.

- Category: Overlays · Status: stable
- Install: `add tooltip`
- npm: radix-ui
- Accessibility: Opens on focus as well as hover, and Escape dismisses it. Never put essential or interactive content in a tooltip: it is unreachable on touch and vanishes on blur. For an icon-only button, prefer aria-label for the name and use the tooltip only to repeat it visually. The opening pop is decoration and stops under reduced motion.

## Tweet Card `tweet-card`

A social post drawn from props — author, text, photos, date and counts — with a link out to the original. No network, no embed script.

- Category: Display · Status: beta
- Install: `add tweet-card`
- Also installs: avatar, skeleton
- npm: class-variance-authority
- Accessibility: An article named by its author, with the post in a blockquote citing its URL. URLs, @mentions and #hashtags in string text become real links. The link to the post is a real, named link revealed on hover and on keyboard focus, and always shown on devices that cannot hover. The avatar is decorative (the name beside it is the link); verification is announced as text, counts are read in full ("1200 likes", not "1.2K"), and the date is a <time> element. Photos need alt text.

## Typewriter Text `typewriter-text`

Types text a character at a time behind a blinking caret — once, on a loop, or cycling through a list.

- Category: Effects · Status: beta
- Install: `add typewriter-text`
- npm: class-variance-authority
- Accessibility: The typed characters are aria-hidden and an sr-only copy holds the full text (every item, for a list), so a screen reader reads it once and never per character. The server renders the finished text, and the untyped remainder reserves its space so nothing reflows. Under reduced motion the full text shows immediately.

## Uptime Matrix `uptime-matrix`

A day-by-day status history drawn in dithered tiles — operational, degraded, outage — with a keyboard-navigable readout and legend.

- Category: Data · Status: beta
- Install: `add uptime-matrix`
- Also installs: dither-canvas
- npm: class-variance-authority
- Accessibility: The tiles are role="img" with an aria-label counting each state and the average uptime. Over them sits a role="grid" of gridcells with one roving tab stop: arrow keys move a day, Home/End go to the row's ends, Ctrl+Home/End to the first and last day, Escape hides the readout; each cell's text is its readout. State is never colour alone: degraded tiles are striped, outages solid, and the legend, readout and table name every state. Axis labels are aria-hidden; the data is always in a table, visually hidden unless showTable is set.