# Folio

> A monochrome design system for software, writing and photography:
> portable CSS tokens and accessible React primitives. Paper ground,
> near-black mark, and status is the only chroma in the file.

Install: `npm install @misoto22/design`. Styles: `import '@misoto22/design/styles.css'`.
Every component is a client-safe React 19 component; the token layer is
plain CSS and works without React at all.

## The laws

1. **The ground is paper.** White, not off-white, and the same white on every surface. There is no card colour, no elevated panel tint, and no "subtle background" that quietly becomes a second ground.
   Rules out: A card that separates itself from the page by being a different shade of white.
2. **A shadow is never blurred.** The system has no light source, so it has no elevation ramp. Depth is a hairline, a change of ground, or a hard ink offset with no blur radius.
   Rules out: box-shadow: 0 2px 8px rgba(0,0,0,.08) — and the whole scale it belongs to.
3. **The rule does the work colour would.** Three weights, and each is chosen by what it separates: hairline between rows, edge between blocks, hard under a masthead. A monochrome page has nothing else to divide with.
   Rules out: Five hand-tuned greys, picked per component, that nobody can tell apart.
4. **There are two text steps and nothing lighter.** The floor clears AA on white at 6.7:1. Every step above it is darker. A third, lighter grey is not a design decision available here.
   Rules out: #999 on white, for "secondary" text that half the readers cannot see.
5. **Chroma is bound to state.** Green, amber and red mean succeeded, needs attention, and failed. They are never decorative, and the meaning is always doubled — by an icon, by the words, or by both.
   Rules out: A blue badge because the row needed some colour.
6. **One ladder, and the page owns the top of it.** Five heading steps, fluid between a phone and the full page, and nothing sits above the page title. Two headings that nest must skip a step, or the hierarchy is not readable as one.
   Rules out: A card title on one page that is larger than another page’s own h1.
7. **The accent is ink.** In a monochrome system the single editorial pointer collapses onto the mark. What used to be carried by hue is carried by weight, by an underline, by a filled pill, or by reversal.
   Rules out: A brand hue reintroduced through a link colour or a hover state.
8. **Dark mode is a value swap, not a second palette.** The same token names, different values. That is why a component reads a semantic alias and never a primitive: the alias re-resolves on its own when the mode flips. The two exceptions — type over a photograph, and a foreign brand mark — are documented where they are defined, because their ground is not the theme.
   Rules out: A .dark block in a component’s own stylesheet, freezing one side of the swap.

## Theming

Attributes that re-point tokens the package already defines. No component
reads any of them, and none of them introduces a token.

- `data-accent`: clay | cobalt | forest | ink | moss | plum (unset = ink)
- `data-chart-palette`: accent | chroma (unset = the neutral series ramp)
- `data-density`: comfortable | compact (unset = comfortable)
- `data-mode`: dark | light (unset = follows the app)
- `data-motion`: snappy | still (unset = calm)
- `data-radius`: round | sharp (unset = the default radius ladder)
- `data-rules`: firm | hairline | quiet (unset = hairline)
- `data-surface`: cool | glass | paper | warm (unset = paper)
- `data-table-density`: compact (unset = comfortable — whatever `data-density` is doing around it)
- `data-type`: bookish | editorial | grotesk (unset = editorial)

An unset attribute is the default; nothing is anchored to `:root`, so an
axis set on any element applies to the subtree below it. `data-accent`
re-points one token, `--clay`, which every component reads through
`--accent`; a brand that is none of the shipped values re-points that token
in a stylesheet instead of setting the attribute.

## When you get it wrong

Some misuse fails silently — a `Field` whose child is a wrapper puts the
label on the box; an icon-only `Button` with no accessible name renders
perfectly and is invisible to a screen reader. The component says so in
development, with the field that caused it and an imperative fix. Each code
is stable, so it is safe to branch on:

- `ARTICLE_HTML_AND_CHILDREN`
- `BREADCRUMB_CRUMB_NOT_LINKED`
- `BUTTON_ICON_ONLY_UNNAMED`
- `CLIPBOARD_WRITE_REJECTED`
- `DIAGRAM_ACCENT_ON_CONTAINER`
- `DIAGRAM_CELL_COLLISION`
- `DIAGRAM_DIRECTION_ON_LEAF`
- `DIAGRAM_DUPLICATE_ID`
- `DIAGRAM_EDGE_DANGLING`
- `DIAGRAM_LANE_UNKNOWN`
- `DIAGRAM_REF_UNKNOWN`
- `DIAGRAM_SPEC_MUTATED`
- `DIAGRAM_STAGE_OUT_OF_RANGE`
- `DIALOG_TITLE_MISSING`
- `FIELD_CONTROL_NOT_LABELLABLE`
- `FIELD_CONTROL_NOT_WIRED`
- `REQUIRED_NAME_BLANK`
- `SEARCHABLE_MENU_LABEL_UNREADABLE`

## Components

- [Button](https://ui.misoto22.com/components/button/llms.txt): The system’s action, on the same corner as the field beside it.
- [FloatingIconButton](https://ui.misoto22.com/components/floating-icon-button/llms.txt): A round action pinned to a screen corner.
- [Field](https://ui.misoto22.com/components/field/llms.txt): A labelled form row: label, control, and the one message below it — and, in row layout, the settings row.
- [Input](https://ui.misoto22.com/components/input/llms.txt): A single line of text entry.
- [NumberField](https://ui.misoto22.com/components/number-field/llms.txt): A number, typed or swept to.
- [Textarea](https://ui.misoto22.com/components/textarea/llms.txt): Multi-line text entry, resizable vertically only.
- [Select](https://ui.misoto22.com/components/select/llms.txt): A choice from a list, styled the whole way down.
- [NativeSelect](https://ui.misoto22.com/components/native-select/llms.txt): The platform’s own picker, restyled where it can be.
- [Checkbox](https://ui.misoto22.com/components/checkbox/llms.txt): A choice that takes effect when the form is submitted.
- [RadioGroup](https://ui.misoto22.com/components/radio-group/llms.txt): A set of mutually exclusive choices.
- [Switch](https://ui.misoto22.com/components/switch/llms.txt): A setting that takes effect immediately.
- [Combobox](https://ui.misoto22.com/components/combobox/llms.txt): A select you can type into.
- [DatePicker](https://ui.misoto22.com/components/date-picker/llms.txt): A date — or a span of them — chosen from a calendar.
- [ColorPicker](https://ui.misoto22.com/components/color-picker/llms.txt): A colour, chosen or typed.
- [Slider](https://ui.misoto22.com/components/slider/llms.txt): A value chosen along a range.
- [ToggleGroup](https://ui.misoto22.com/components/toggle-group/llms.txt): A segmented control: several options, one strip.
- [Tabs](https://ui.misoto22.com/components/tabs/llms.txt): One strip, several panels.
- [Accordion](https://ui.misoto22.com/components/accordion/llms.txt): Disclosure rows that open in place.
- [Breadcrumb](https://ui.misoto22.com/components/breadcrumb/llms.txt): Where you are, as a path.
- [Pagination](https://ui.misoto22.com/components/pagination/llms.txt): Numbered pages, with the middle elided.
- [Sidebar](https://ui.misoto22.com/components/sidebar/llms.txt): A navigation rail down the side of an application.
- [NavItem](https://ui.misoto22.com/components/nav-item/llms.txt): A row in a sidebar.
- [Collapsible](https://ui.misoto22.com/components/collapsible/llms.txt): One thing that opens, on its own.
- [Dialog](https://ui.misoto22.com/components/dialog/llms.txt): A modal surface: portal, scrim, centred panel.
- [DropdownMenu](https://ui.misoto22.com/components/dropdown-menu/llms.txt): A menu of actions.
- [Tooltip](https://ui.misoto22.com/components/tooltip/llms.txt): A short label on hover and on focus.
- [Popover](https://ui.misoto22.com/components/popover/llms.txt): A panel anchored to a control, holding content you can interact with.
- [Sheet](https://ui.misoto22.com/components/sheet/llms.txt): A panel docked to an edge of the viewport.
- [ContextMenu](https://ui.misoto22.com/components/context-menu/llms.txt): The menu a right-click opens.
- [SearchableMenu](https://ui.misoto22.com/components/searchable-menu/llms.txt): A menu of actions you can type into.
- [Command](https://ui.misoto22.com/components/command/llms.txt): A filterable list of actions — the ⌘K surface.
- [Spinner](https://ui.misoto22.com/components/spinner/llms.txt): The one “working” indicator — a ring, never a shimmer.
- [Skeleton](https://ui.misoto22.com/components/skeleton/llms.txt): The shape of the page, before the page.
- [Progress](https://ui.misoto22.com/components/progress/llms.txt): A bar that fills, or sweeps when the end is unknown.
- [Alert](https://ui.misoto22.com/components/alert/llms.txt): A message about the page, in place.
- [EmptyState](https://ui.misoto22.com/components/empty-state/llms.txt): A collection with nothing in it — yet.
- [ErrorState](https://ui.misoto22.com/components/error-state/llms.txt): A page that could not be shown.
- [Toast](https://ui.misoto22.com/components/toast/llms.txt): A transient confirmation, mounted once near the app root.
- [Badge](https://ui.misoto22.com/components/badge/llms.txt): A count or a state, set in mono so it reads as metadata.
- [Tag](https://ui.misoto22.com/components/tag/llms.txt): A subject label — a topic, a technology, a filter facet — that filters with onClick and is dismissed with onRemove.
- [Kbd](https://ui.misoto22.com/components/kbd/llms.txt): A key on a keyboard, set as one.
- [Avatar](https://ui.misoto22.com/components/avatar/llms.txt): A person, as a circle, with initials until the image lands.
- [StatusDot](https://ui.misoto22.com/components/status-dot/llms.txt): The dot beside a status word.
- [Steps](https://ui.misoto22.com/components/steps/llms.txt): A numbered sequence, as a rail — one thing after another, with a rule through them.
- [StatusPill](https://ui.misoto22.com/components/status-pill/llms.txt): A live state, named: a dot plus an uppercase mono label.
- [LinkArrow](https://ui.misoto22.com/components/link-arrow/llms.txt): The mark on a link that leaves the page.
- [Separator](https://ui.misoto22.com/components/separator/llms.txt): A rule, in the three weights a monochrome page needs — with words in it when the break has something to say.
- [Diagram](https://ui.misoto22.com/components/diagram/llms.txt): A flow or architecture figure, drawn out of the system’s own parts.
- [FigureBand](https://ui.misoto22.com/components/figure-band/llms.txt): A row of counted facts, divided by hairlines and nothing else.
- [Text](https://ui.misoto22.com/components/text/llms.txt): The system’s paragraph, on the second rung of the ink ladder.
- [Heading](https://ui.misoto22.com/components/heading/llms.txt): A heading whose element and whose size are two decisions.
- [Code](https://ui.misoto22.com/components/code/llms.txt): A function name or a flag, inside a sentence.
- [CodeBlock](https://ui.misoto22.com/components/code-block/llms.txt): A multi-line snippet, on a plate, with a way to take it away.
- [Markdown](https://ui.misoto22.com/components/markdown/llms.txt): A Markdown string, rendered as this system’s components.
- [Timestamp](https://ui.misoto22.com/components/timestamp/llms.txt): A date or a time, rendered the one way the system renders them.
- [Article](https://ui.misoto22.com/components/article/llms.txt): The long-form reading surface — everything a Markdown pipeline emits, in this system’s type.
- [Card](https://ui.misoto22.com/components/card/llms.txt): A bounded surface, with no shadow under it.
- [AppShell](https://ui.misoto22.com/components/app-shell/llms.txt): Two columns on a desktop, a drawer on a phone.
- [PageHeader](https://ui.misoto22.com/components/page-header/llms.txt): A page opening: what this page is, and what qualifies it.
- [Calendar](https://ui.misoto22.com/components/calendar/llms.txt): A month, as a grid of days.
- [ScrollArea](https://ui.misoto22.com/components/scroll-area/llms.txt): A box that scrolls, with a scrollbar that looks the same everywhere.
- [DescriptionList](https://ui.misoto22.com/components/description-list/llms.txt): One record’s fields, as a real <dl> rather than a grid of divs.
- [Toolbar](https://ui.misoto22.com/components/toolbar/llms.txt): The bar of actions at the edge of a working surface.
- [AspectRatio](https://ui.misoto22.com/components/aspect-ratio/llms.txt): A box that keeps its shape whatever is inside it.
- [Table](https://ui.misoto22.com/components/table/llms.txt): A ruled data table — alignment, sorting and rules all per column.
- [Heatmap](https://ui.misoto22.com/components/heatmap/llms.txt): A grid of values read by weight.
- [CalendarHeatmap](https://ui.misoto22.com/components/calendar-heatmap/llms.txt): A year of daily readings, as a week-by-week grid.
- [Sparkline](https://ui.misoto22.com/components/sparkline/llms.txt): A run of numbers at the size of a word.
- [BarList](https://ui.misoto22.com/components/bar-list/llms.txt): A ranked list, with the bar behind the name rather than beside it.
- [Metric](https://ui.misoto22.com/components/metric/llms.txt): One reading, on a plate: a label, a figure, and what qualifies it.
- [BigNumber](https://ui.misoto22.com/components/big-number/llms.txt): One number, at the size of a headline.
- [BulletChart](https://ui.misoto22.com/components/bullet-chart/llms.txt): A measure, its target, and the bands that say whether it is any good.
- [AreaChart](https://ui.misoto22.com/components/area-chart/llms.txt): A filled series over a continuous axis, where the area means something.
- [BarChart](https://ui.misoto22.com/components/bar-chart/llms.txt): Discrete categories compared by length.
- [LineChart](https://ui.misoto22.com/components/line-chart/llms.txt): Several series compared over a continuous axis.
- [ComposedChart](https://ui.misoto22.com/components/composed-chart/llms.txt): Bars and lines over one axis — the volume, and the rate it moved at.
- [PieChart](https://ui.misoto22.com/components/pie-chart/llms.txt): Parts of one whole.
- [RadarChart](https://ui.misoto22.com/components/radar-chart/llms.txt): A profile across several named dimensions.
- [RadialChart](https://ui.misoto22.com/components/radial-chart/llms.txt): Values on an arc — a gauge, or a few totals against one scale.
- [SankeyChart](https://ui.misoto22.com/components/sankey-chart/llms.txt): Where a quantity goes as it moves through stages.
- [ScatterChart](https://ui.misoto22.com/components/scatter-chart/llms.txt): Two measures against each other, one mark per observation.
- [FunnelChart](https://ui.misoto22.com/components/funnel-chart/llms.txt): Stages that only ever narrow.
- [TreemapChart](https://ui.misoto22.com/components/treemap-chart/llms.txt): Part of a whole, when the whole has too many parts for a pie — and the parts nest.
- [BoxPlot](https://ui.misoto22.com/components/box-plot/llms.txt): The spread of a measurement, per category.
- [Histogram](https://ui.misoto22.com/components/histogram/llms.txt): The shape of one distribution.
- [WaterfallChart](https://ui.misoto22.com/components/waterfall-chart/llms.txt): How a total got from one figure to another.
- [Facet](https://ui.misoto22.com/components/facet/llms.txt): The same chart once per group, on one shared scale.
- [ArchitectureFigure](https://ui.misoto22.com/components/architecture-figure/llms.txt): A component map: services, datastores, trust boundaries, and what talks to what.
- [WorkflowFigure](https://ui.misoto22.com/components/workflow-figure/llms.txt): A process in lanes and phases, with the main path drawn heavier than its branches.
- [SequenceFigure](https://ui.misoto22.com/components/sequence-figure/llms.txt): A call chain over time: who asks whom, in what order, and what comes back.
- [DataflowFigure](https://ui.misoto22.com/components/dataflow-figure/llms.txt): A pipeline: where data comes from, what happens to it, and who ends up with it.
- [LifecycleFigure](https://ui.misoto22.com/components/lifecycle-figure/llms.txt): A state machine: what something can be, and what moves it between states.
- [DiagramCanvas](https://ui.misoto22.com/components/diagram-canvas/llms.txt): A frame that a picture larger than it can be panned and zoomed inside.
- [DiagramToolbar](https://ui.misoto22.com/components/diagram-toolbar/llms.txt): A bar of actions belonging to the surface underneath them.
- [DiagramExportMenu](https://ui.misoto22.com/components/diagram-export-menu/llms.txt): Taking the figure off the page: PNG, JPEG, WebP, SVG and a 1200×630 share card.
- [DiagramInspector](https://ui.misoto22.com/components/diagram-inspector/llms.txt): What the reader just picked, written out beside the picture.
- [DiagramMinimap](https://ui.misoto22.com/components/diagram-minimap/llms.txt): Where you are in something bigger than the window.
- [DiagramLegend](https://ui.misoto22.com/components/diagram-legend/llms.txt): The key: which drawn form means which kind of thing.

## Website

Page-shaped compositions of the components above, imported from `@misoto22/design/website`.
The host supplies content, routes and service state.

- [SiteShell](https://ui.misoto22.com/components/site-shell/llms.txt): Page landmarks, footer groups and shared section headings.
- [SiteNavigation](https://ui.misoto22.com/components/site-navigation/llms.txt): Responsive navigation and explicit language or appearance choices.
- [Portfolio](https://ui.misoto22.com/components/portfolio/llms.txt): An editorial introduction, featured images, records and a question card.
- [PortfolioIndex](https://ui.misoto22.com/components/portfolio-index/llms.txt): Tabbed collections with a supporting editorial column.
- [Collection](https://ui.misoto22.com/components/collection/llms.txt): Collection headings, search controls, featured records and empty states.
- [Reading](https://ui.misoto22.com/components/reading/llms.txt): Article and project layouts, outlines, media and installation instructions.
- [Contact](https://ui.misoto22.com/components/contact/llms.txt): A correspondence form, contact facts, questions and location imagery.
- [Music](https://ui.misoto22.com/components/music/llms.txt): Featured recordings, track rows and playlist collections.
- [Timeline](https://ui.misoto22.com/components/timeline/llms.txt): Career records, profile narratives and chronological lists.
- [Recovery](https://ui.misoto22.com/components/recovery/llms.txt): Loading, unavailable and missing-page states with recovery actions.
- [Media](https://ui.misoto22.com/components/media/llms.txt): Photograph collections, lightboxes, image details and map controls.
- [Metrics](https://ui.misoto22.com/components/metrics/llms.txt): Metric panels, accessible data tables and chart arrangements.
- [SearchPalette](https://ui.misoto22.com/components/search-palette/llms.txt): Search results, actions and a detail view in one accessible modal.
- [Content](https://ui.misoto22.com/components/content/llms.txt): Formatted code, clipboard actions, step sequences and rich-content elements.
- [Actions](https://ui.misoto22.com/components/actions/llms.txt): Share action menus and a scroll-to-top control.
- [Conversation](https://ui.misoto22.com/components/conversation/llms.txt): Conversation threads, answers, citations, composers and floating chat surfaces.
- [Evidence](https://ui.misoto22.com/components/evidence/llms.txt): Expandable traces, source stages, scores and timing summaries.

## Foundations

- [Getting started](https://ui.misoto22.com/foundations/getting-started/): Install it, pick a stylesheet, and render the first control.
- [Colour](https://ui.misoto22.com/foundations/colour/): A white ground, a near-black mark, three rule weights, and status.
- [Typography](https://ui.misoto22.com/foundations/typography/): Three faces, one heading ladder, and nothing above the page title.
- [Space & shape](https://ui.misoto22.com/foundations/space/): The page gutter, the measures, and the five radii.
- [Shape](https://ui.misoto22.com/foundations/shape/): Five steps from one number, and the arithmetic that keeps two of them concentric.
- [Elevation](https://ui.misoto22.com/foundations/elevation/): Nothing rises. Four shadow tokens exist to make sure of it.
- [Icons](https://ui.misoto22.com/foundations/icons/): Filled paths rather than strokes, three size tokens over six sizes in the source, and a set that ships brand marks again.
- [Motion](https://ui.misoto22.com/foundations/motion/): One curve, three durations, and a reduced-motion rule that is not optional.
- [Working with AI](https://ui.misoto22.com/foundations/agents/): The package documents itself twice. This is the half a browser cannot open.

## Templates

- [Dashboard](https://ui.misoto22.com/templates/dashboard/): A console: a sidebar, a figure band, tabs, a filterable table and two job cards.
- [Activity board](https://ui.misoto22.com/templates/activity-board/): One screen of a working week: four figures, two lanes over time, a ranked attention column, a grouped table and two bar charts.
- [Landing page](https://ui.misoto22.com/templates/landing/): A marketing page: a hero, a figure band, three pillars, a reversed pricing plate and an FAQ.
- [Blog index](https://ui.misoto22.com/templates/blog/): A publication index: a filter strip, a lead story, and a ruled list of records.
- [Architecture explorer](https://ui.misoto22.com/templates/architecture/): One diagram given the screen: a floating toolbar, a pannable canvas, an inspector, a minimap, a key and the conclusions under it.
- [Article](https://ui.misoto22.com/templates/post/): One post, rendered from a real Markdown file through the site’s own pipeline.
- [Settings](https://ui.misoto22.com/templates/settings/): A workspace settings screen: a section rail, four groups of real controls, and a save bar that only exists once something changed.
- [Sign in](https://ui.misoto22.com/templates/login-card/): A centred authentication card: email and password, a rejected attempt still on screen, and a divider into two SSO buttons.
- [Data table](https://ui.misoto22.com/templates/table-filter/): A table with everything a real one has: a filter strip, a sorted column, row selection with a bulk bar, and pagination.
- [Multi-step form](https://ui.misoto22.com/templates/form-wizard/): Four steps to create a deploy environment: the rail on one side, the current step’s fields beside it, and a review that reads back what was entered.
- [Record detail](https://ui.misoto22.com/templates/detail-page/): One incident: a title block carrying its status, the write-up, a metadata rail, and the activity that happened to it.
- [Loading, empty, error](https://ui.misoto22.com/templates/states/): The three states every real screen has, drawn side by side: a skeleton, an empty collection, and a page that failed.
- [Documentation](https://ui.misoto22.com/templates/docs-shell/): A reference page: a sidebar of sections, an article column with a props table and a keyboard note, and a contents rail beside it.
- [Pricing](https://ui.misoto22.com/templates/pricing/): Three plans behind a monthly/annual switch, a feature comparison table, and the questions people ask before paying.

## Optional

- [Everything, inline](https://ui.misoto22.com/llms-full.txt) — every component in one file.
- [Themes](https://ui.misoto22.com/themes/) — the five presets, rendered.
- [Changelog](https://ui.misoto22.com/changelog/)

---

# Button

The system’s action, on the same corner as the field beside it.

- Group: Actions
- Import: `import { Button } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/button/
- Related: floating-icon-button, spinner

## When to reach for it

Anything that DOES something. If it navigates and looks like text, it is a link, not a ghost button.

## Anatomy

- **Control box** (required) — The <button>, the <a> it becomes when given href, or whatever asChild slots in. It carries the variant, the size, and the same --radius corner as the field beside it.
- **Label** — children, and the accessible name of a text button. It stays put while loading, so the width does not move under the pointer.
- **Icon** — The same children slot on an iconOnly button: the box goes square, the padding to zero, and nothing text-shaped is left behind for a screen reader.
- **Keycap** — keycap, after the label — a mono glyph in a bordered box at reduced opacity. Real text, not decoration hidden from assistive tech.
- **Spinner** — loading, before the label — a Spinner toned to the ground it sits on and passed label={null}, so it is aria-hidden and aria-busy on the control carries the state instead.

## Best practices

### Do

- Spell out type="submit" on a form’s submit control: the default here is type="button", so the button at the foot of a form looks right and submits nothing.
- Keep one primary to a view. variant defaults to primary, so a row written without the prop is a row in which every button claims to be the one thing the screen wants.
- Reach for loading rather than swapping the label by hand: it holds the label, sets aria-busy and disables the control in one move, so the box does not collapse under the pointer that just clicked it.
- Use href when it navigates and asChild when a router owns the navigation — a <button> whose onClick calls router.push cannot be opened in a new tab, and is announced as a button that goes nowhere.

### Don’t

- asChild passes the styling to the child and nothing else: keycap and loading never reach it, so a loading state written that way shows no spinner and blocks no clicks.
- sm is 36px at the default density, under the 44px md clears on its own — a toolbar built out of sm is a row of targets a thumb misses (WCAG 2.5.5).
- danger is a state, not emphasis. Spent on the merely important action, nothing is left that reads as destructive when one actually is.
- The keycap is not hidden from assistive tech, so the glyph joins the accessible name — the control is read out as “Save S”, and a keycap for a shortcut nothing binds announces a promise the page never keeps.

## Accessibility

- A native <button> by default, so Enter and Space both fire it.
- loading sets aria-busy and disables the control; the label stays, so the box does not collapse under the pointer that just clicked it.
- A link cannot be disabled, so href + loading sets aria-disabled and blocks pointer events instead.
- iconOnly has no text, so it requires aria-label — the single most common way a design system ships an unusable control.

## Keyboard

- Enter — Activates the button.
- Space — Activates the button. A native <button> answers to both; a styled <div> answers to neither.

## Button

The system's action. Renders a `<button>`, or an `<a>` when given `href`, or whatever you hand it via `asChild`. No router is imported, so the package stays framework-agnostic and a Next or React Router app wires its own `Link` at the call site. Server-component friendly: there is no client boundary here, so it renders in a static page as well as an interactive one.

### Props

- `children` — `ReactNode`.
- `variant` — `ButtonVariant` default `'primary'`. Which action this is. `primary` is the one thing the screen wants you to do, so there is at most one per view; `danger` is reserved for destructive actions and is the only place chroma is allowed on a control.
- `size` — `ButtonSize` default `'md'`. 36 / 44 / 48px tall. `md` meets the pointer-target floor on its own.
- `keycap` — `string`. Optional mono keycap glyph rendered after the label (e.g. "P").
- `loading` — `boolean` default `false`. Swaps the leading content for a spinner and blocks interaction. The label stays put — a button that empties out while it works loses its width, and the page reflows under the pointer that just clicked it.
- `iconOnly` — `boolean` default `false`. Square control with no label. REQUIRES `aria-label`: an icon-only button with no accessible name is invisible to a screen reader, and this is the single most common way a design system ships an unusable control.
- `asChild` — `boolean` default `false`. Render the child element instead of a `<button>`, keeping these styles. Use it to hand the styling to a router's `Link` — `asChild` is what keeps this package free of any one router. The decoration slots (`keycap`, `loading`) are not injected into a slotted child; compose them inside it yourself.
- `className` — `string`.
- `href` — `string`.

Also accepts: `AnchorHTMLAttributes<HTMLAnchorElement>`, `ButtonHTMLAttributes<HTMLButtonElement>`.

## Example — variants

```tsx
import { Button } from '@misoto22/design'

<div className="flex flex-wrap items-center gap-3">
  <Button>Primary</Button>
  <Button variant="secondary">Secondary</Button>
  <Button variant="ghost">Ghost</Button>
  <Button variant="danger">Delete</Button>
</div>
```

## Example — sizes

```tsx
import { Button } from '@misoto22/design'

<div className="flex flex-wrap items-center gap-3">
  <Button size="sm" variant="secondary">Small</Button>
  <Button size="md" variant="secondary">Medium</Button>
  <Button size="lg" variant="secondary">Large</Button>
</div>
```

## Example — states

```tsx
import { Button } from '@misoto22/design'

<div className="flex flex-wrap items-center gap-3">
  <Button loading>Saving…</Button>
  <Button disabled>Disabled</Button>
  <Button variant="secondary" keycap="P">View projects</Button>
</div>
```

## Example — icon only

```tsx
import { Button } from '@misoto22/design'

<div className="flex flex-wrap items-center gap-3">
  <Button iconOnly aria-label="Copy to clipboard" variant="secondary">
    <RiFileCopyLine size={16} aria-hidden />
  </Button>
  <Button iconOnly aria-label="Share" variant="ghost">
    <RiShareLine size={16} aria-hidden />
  </Button>
  <Button iconOnly aria-label="Open in a new tab">
    <RiArrowRightUpLine size={16} aria-hidden />
  </Button>
</div>
```

# FloatingIconButton

A round action pinned to a screen corner.

- Group: Actions
- Import: `import { FloatingIconButton } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/floating-icon-button/
- Related: button

## When to reach for it

A page-level affordance that must stay reachable while the reader scrolls — back to top, a mobile table of contents.

## Anatomy

- **Control box** (required) — A real <button type="button">, --control-h-md square with a pill radius, position: fixed to a bottom corner at --z-drawer. There is no asChild and no href here: it cannot become a link.
- **Icon** (required) — children, and the only thing in the box. Nothing text-shaped renders, so the control is as wide as the square and no wider.
- **Ground** (required) — A 90% --paper fill over a backdrop blur, with a --rule-2 hairline. The White Reset has no elevation ramp, so the blur and the hairline are what lift it off the page — not a shadow.
- **Name** (required) — label, set as aria-label. It never renders, so a screen reader has the name and a sighted reader has the glyph alone.

## Best practices

### Do

- Spell out position — it is required and has no default, and the values are start and end in reading order. The component’s own doc example says position="right", which is not one of them and does not type-check.
- Wrap it in a Tooltip when the glyph is not universal: label is aria-label only, so it names the control for a screen reader and for nobody else — and a tooltip does not open on touch, which is where a floating control is most often the only affordance on screen.
- Keep it to two. start is deliberately raised to 5rem while end sits at 1.5rem, which is exactly enough clearance for a pair; a third has nowhere left to go, and the corners already compete with a cookie bar and a chat launcher.
- Move it with className when the page has a fixed footer — the classes go through tailwind-merge, so className="bottom-24" REPLACES the corner offset rather than losing to it.

### Don’t

- --control-h-md is 44px at the default density and 36px under data-density="compact", so a compact page ships the one control a thumb reaches for without looking at eight pixels under the WCAG 2.5.5 floor.
- It is position: fixed, so any ancestor with a transform, filter or backdrop-filter becomes its containing block — put one inside a DialogContent, which centres itself with a translate, and it pins to the panel’s corner instead of the screen’s.
- It sits at --z-drawer, 100, and every rank that can appear over it is higher: a scrim is 200, a modal 210, an anchored panel 220 — --z-dropdown now resolves to --z-anchored, not to this rank. So a menu opening into the same corner covers the button outright rather than tying with it, and a dialog covers it too. Nothing here is settled by document order; move the button with className if it must stay reachable beside something else.

## Accessibility

- label is the only name the control has; it is required rather than optional.
- 44px square, which is the pointer-target floor (WCAG 2.5.8).

## FloatingIconButton

A round action pinned to a screen corner. A translucent paper ground with a backdrop blur rather than a drop shadow — the White Reset has no elevation ramp, so what separates the control from the page under it is the blur and the hairline, not a glow.

### Props

- `position` (required) — `'start' | 'end'`. Which bottom corner the control is pinned to, in READING order — `end` is the right in English and the left in Arabic. Naming the sides `left`/`right` would have hard-coded one script's layout into the API.
- `label` (required) — `string`. Accessible name — the button has no visible text, so this is its only name.
- `children` (required) — `ReactNode`.

Also accepts: `Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'>`.

## Example — back to top

```tsx
import { FloatingIconButton } from '@misoto22/design'

<div className="relative h-32 w-full overflow-hidden rounded-(--radius) border border-(--rule) [&>button]:absolute">
  <FloatingIconButton position="end" label="Back to top">
    <RiArrowUpLine size={16} aria-hidden />
  </FloatingIconButton>
</div>
```

## Example — a tooltip name

```tsx
import { FloatingIconButton, Tooltip, TooltipProvider } from '@misoto22/design'

<TooltipProvider>
  <div className="relative h-32 w-full overflow-hidden rounded-(--radius) border border-(--rule) [&>button]:absolute">
    <Tooltip content={name} side="top">
      <FloatingIconButton position="end" label={name}>
        <RiNodeTree size={16} aria-hidden />
      </FloatingIconButton>
    </Tooltip>
  </div>
</TooltipProvider>
```

## Example — two corners

```tsx
import { FloatingIconButton } from '@misoto22/design'

<div className="relative h-40 w-full overflow-hidden rounded-(--radius) border border-(--rule) [&>button]:absolute">
  <FloatingIconButton position="start" label="Open the chat">
    <RiChat3Line size={16} aria-hidden />
  </FloatingIconButton>
  <FloatingIconButton position="end" label="Back to top">
    <RiArrowUpLine size={16} aria-hidden />
  </FloatingIconButton>
</div>
```

# Field

A labelled form row: label, control, and the one message below it — and, in row layout, the settings row.

- Group: Forms
- Import: `import { Field } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/field/
- Related: input, select, switch

## When to reach for it

Any labelled control. layout="row" is the settings row — label and description at the inline start, control at the inline end — which is a layout here rather than a second component, because the label wiring, the required marker and the message slot are the same three things either way.

## Anatomy

- **Label** — label, rendered as a Radix <Label> carrying htmlFor and an id. The id is what a trigger names itself from, alongside its own value, and what a group points back at — neither of which htmlFor can do.
- **Required mark** — The --danger asterisk after the label when required. aria-hidden, but still inside the label’s text, so the accessible name ends “Email *”.
- **Control slot** (required) — children — ONE element, which the field clones to add id, aria-describedby, aria-required and aria-invalid, and which each control forwards to whatever element carries its role: the trigger for Select, Combobox and DatePicker, the root for a group, the thumb for a Slider. This is the whole contract; everything else is layout.
- **Description** — description, a second line under the LABEL explaining what the setting does — as distinct from hint, which sits under the control and belongs to the input. It has its own id and joins aria-describedby ahead of the message, so a row with both announces both.
- **Message** — A single <p> below the control: error if there is one, hint otherwise, never both. It owns the id that aria-describedby points at, and it is --danger or --ink-3-aa accordingly.
- **Row layout** — layout="row": the label and description in a column at the inline start, the control at the inline end, the message underneath both. The two columns are TOP-aligned — items-start on the block axis, not items-center — so a two-line description does not drag the switch down to the middle of the paragraph, and a column of settings rows keeps every control on the same line as the words that name it.

## Best practices

### Do

- Make children the control itself, not a layout wrapper around it: the wiring is a cloneElement on the single child, so a <div> in between takes the id and the aria-describedby and the label ends up naming a box.
- Let error carry the invalid state. The field sets aria-invalid on the control, and Input, Textarea, NativeSelect, Select and Combobox all read either spelling through isInvalid, so passing invalid as well states the same fact twice from two places that can disagree.
- Pass htmlFor, and the same id on the control, whenever something outside the row has to address it — a form library, a scroll-to-first-error, a test. The generated id is a useId value nothing else can predict.
- Build a settings screen out of layout="row" with description, not out of three hand-rolled divs. The label still reaches the control through the same wiring, so the switch on the far side of the row is named by the words on the near side.

### Don’t

- required here is aria-required and an asterisk, and nothing else: it never reaches the control’s own required attribute, so the browser will not block the submit and the row stays unmarked until you pass error yourself.
- The words above a RadioGroup or a ToggleGroup name it but do not click through. Both roots are <div role="radiogroup">, which htmlFor does not bind to, so the label is pointed AT by the group instead — a reader who clicks it the way they click "Email" gets nothing, exactly as with a <legend>.
- Do not reach for description as a second hint. It explains the SETTING and sits under the label; hint explains the INPUT and sits under the control. A row that uses one for the other reads correctly and lands in the wrong place.
- required is announced on every control here except DatePicker, whose trigger is a plain <button> — a role with nowhere to put aria-required. There the asterisk is the whole of the marking, and a screen reader meets an ordinary optional field.

## Accessibility

- Generates an id when none is given, so the label always points at something.
- Wires aria-describedby, aria-required and aria-invalid onto the control, so validation is announced and not merely drawn.
- hint and error are one slot: when a field is wrong, the thing to read is what is wrong with it.
- description joins aria-describedby ahead of the message, so a settings row announces what the setting does and then what is wrong with it.
- Every control forwards the wiring to the element that carries its role, so the hint under a Select or a Slider is announced and not merely drawn.
- The row layout moves the label to the other side of the row and changes nothing about the association, so a settings row with a Switch or a Select in it is named by the words on the near side. Slider is the exception, and the layout cannot fix it: role="slider" is on the THUMB while the field’s label points at the roleless root, so there the label prop on the Slider is still the only name a reader hears.

## Field

A labelled form row: label, control, and the one message below it. The visible message is only half of accessible validation — it must also reach the control. This wires `aria-describedby`, `aria-required` and `aria-invalid` onto the single control child so the requirement and the error are announced, not merely drawn (WCAG 1.3.1 / 3.3.1 / 4.1.2). An earlier version derived the message id from `htmlFor`, which meant a caller who left `htmlFor` off got a hint that was rendered and never announced — the failure was invisible in the browser and total for a screen reader. The id is now generated when it is not supplied. `hint` and `error` are one slot, not two stacked messages: when a field is wrong, the thing to read is what is wrong with it. `description` is a different slot again — it explains the SETTING, not the input, and it is what `layout="row"` puts under the label to make a settings row. **How the wiring reaches the control.** `cloneElement` puts the four attributes on the single child, and each control forwards them to whatever element carries the role — which is the child itself for `Input`, `Textarea`, `NativeSelect`, `Checkbox`, `Switch` and any host element written by hand, and a trigger, a group or a thumb further down for `Select`, `Combobox`, `DatePicker`, `Slider`, `RadioGroup` and `ToggleGroup`. The composites used to drop them on the floor, which drew a hint under a control that never announced it; a wrapper that appears to wire things up and does not is worse than one that never claimed to. The label's own id travels separately, through context, because a name is the one thing a prop cannot carry: a trigger whose text is its VALUE is named by the label AND by itself, so `<Field label="Region"><Select/></Field>` announces "Region, Australia" rather than either half. Three things stay out of reach, and each of them is the control's own markup rather than a gap in this wiring. A `<label for>` binds only to a labellable element, so the words do not click through to a `RadioGroup`, a `ToggleGroup` or a `Slider`: the first two are a `role="radiogroup"` named by pointing back at the label instead, exactly as a `<legend>` is, and the third carries `role="slider"` on a thumb below a roleless root. `required` reaches a control as `aria-required`, which `DatePicker`'s plain `<button>` trigger and a multiple-value `ToggleGroup`'s `role="toolbar"` have nowhere to put; there the asterisk is the only marker. And `aria-invalid` reaches `Slider`'s root rather than its thumb, so an errored slider is drawn wrong without being announced wrong. Each composite still takes its own `label` prop — that is what names it standing outside a field, and `Select`, `Combobox` and `DatePicker` warn when it is blank. It is no longer used INSTEAD of this one's. What no wiring can reach, the field says out loud in development rather than failing silently: `FIELD_CONTROL_NOT_LABELLABLE` when the child is a host element a label cannot bind to — the `<div>` wrapper that takes the id and leaves the control inside it with nothing — and `FIELD_CONTROL_NOT_WIRED` when there is no single element to wire at all.

### Props

- `label` — `ReactNode`. Visible label text; renders a `--danger` asterisk when `required`.
- `htmlFor` — `string`. The control's `id`. Optional: when omitted, the field generates one and puts it on the control child itself, so the label still points at something. Pass it explicitly when the id has to be stable across renders — a form library referencing it by name, say.
- `description` — `ReactNode`. A second line under the LABEL, explaining what the setting does. Distinct from `hint`, which sits under the control and belongs to the input — "We never share it". This belongs to the thing being switched on, and it is what makes a settings row a settings row. Both reach the control through `aria-describedby`, so a row that has a description and an error announces both.
- `hint` — `ReactNode`. Helper copy shown below the control when there is no `error`.
- `error` — `ReactNode`. Validation message; takes precedence over `hint` when present.
- `required` — `boolean`.
- `layout` — `FieldLayout` default `'stacked'`. Where the control sits relative to its label. See FieldLayout.
- `children` (required) — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## Example — states

```tsx
import { Field, Input, Select, SelectItem, Textarea } from '@misoto22/design'

<div className="flex w-full max-w-md flex-col gap-5">
  <Field label="Email" required hint="We never share it.">
    <Input type="email" placeholder="you@example.com" />
  </Field>
  <Field label="Full name" error="Name is required.">
    <Input />
  </Field>
  <Field label="Region">
    <Select label="Region" defaultValue="au">
      <SelectItem value="au">Australia</SelectItem>
      <SelectItem value="nz">New Zealand</SelectItem>
      <SelectItem value="jp">Japan</SelectItem>
    </Select>
  </Field>
  <Field label="Notes" hint="Markdown is fine.">
    <Textarea rows={3} placeholder="Anything else?" />
  </Field>
</div>
```

## Example — one message slot

```tsx
import { Field, Input } from '@misoto22/design'

<Field
  label="Work email"
  required
  hint="The receipt goes here — use the address on the invoice."
  error={wrong ? 'Enter a full address, like maya.chen@studio.example.' : undefined}
  className="w-full max-w-sm"
>
  <Input
    type="email"
    autoComplete="email"
    value={email}
    onChange={(event) => setEmail(event.target.value)}
  />
</Field>
```

## Example — naming a group

```tsx
import { Field, RadioGroup, RadioGroupItem } from '@misoto22/design'

<Field
  label="Delivery speed"
  hint="Weekend delivery is metro only."
  className="w-full max-w-sm"
>
  <RadioGroup defaultValue="standard" aria-label="Delivery speed">
    <RadioGroupItem value="standard">Standard — 3 to 5 business days</RadioGroupItem>
    <RadioGroupItem value="express">Express — next business day</RadioGroupItem>
    <RadioGroupItem value="pickup">Collect from the Newtown store</RadioGroupItem>
  </RadioGroup>
</Field>
```

## Example — a stable id

```tsx
import { Button, Field, Input } from '@misoto22/design'

<div className="flex w-full max-w-sm flex-col gap-4">
  <Field label="Email" htmlFor="checkout-email" hint="The receipt goes here.">
    <Input
      id="checkout-email"
      type="email"
      autoComplete="email"
      defaultValue="maya.chen@studio.example"
    />
  </Field>
  <Field label="Postcode" htmlFor="checkout-postcode" error="Enter a four-digit postcode.">
    <Input
      id="checkout-postcode"
      inputMode="numeric"
      autoComplete="postal-code"
      defaultValue="20o0"
    />
  </Field>
  <Button
    variant="secondary"
    className="self-start"
    onClick={() => document.getElementById('checkout-postcode')?.focus()}
  >
    Jump to the first error
  </Button>
</div>
```

# Input

A single line of text entry.

- Group: Forms
- Import: `import { Input } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/input/
- Related: field, textarea

## Anatomy

- **Control box** (required) — The <input>, on the CONTROL_BASE it shares with Textarea and the Select trigger. Its padding is --field-px / --field-py, so a subtree marked data-density="compact" tightens the fields along with the buttons.
- **Placeholder** — placeholder, in --ink-3-aa inside the box — the same slot the value occupies, which is why it cannot also be the name.
- **Focus border** — focus:border-(--ink) on the border already there, not an added ring. The box does not gain a pixel on focus, so nothing in the row shifts.
- **Danger border** — What invalid — or an aria-invalid set by a Field with an error — swaps in. It changes the border colour and nothing else, so the reason has to come from the message below.

## Best practices

### Do

- Spell out type and inputMode. An <Input> with no type is type="text", so an email field that never says so gets a phone keyboard with no @ on it and no browser validation at all.
- Name the field to the browser with autoComplete: a password field without current-password or new-password is one a manager fills with the wrong value and one no browser offers to save.
- Reach for readOnly rather than disabled when the value is real but not editable — a disabled input is skipped by Tab AND left out of the submitted form data, so the server hears nothing about a field the reader can plainly see.

### Don’t

- readOnly is styled by nothing here: CONTROL_BASE dims on :disabled only, so a read-only input is pixel-identical to an editable one and the first thing a reader learns about it is that typing does nothing.
- type="number" is for quantities, not for digits. A phone number, a card number or a postcode loses its leading zeros, and a scroll wheel over the focused control changes the value without a keystroke.
- A Tooltip on a disabled input never opens — disabled:pointer-events-none means the control receives no hover — so the explanation for why it is disabled has to live in the Field’s hint instead.

## Accessibility

- A placeholder is not a label — it disappears the moment anyone types. Pair with Field.

## Input

A single line of text entry. Shares `CONTROL_BASE` with Textarea and Select, so the three cannot drift apart. Pair with `Field` for the label, hint and error — an input with a placeholder and no label is not labelled, because the placeholder disappears the moment anyone types.

### Props

- `invalid` — `boolean`. Paints the resting border with `--danger` and reflects `aria-invalid`.
- `ref` — `Ref<HTMLInputElement>`.

Also accepts: `InputHTMLAttributes<HTMLInputElement>`.

## Example — default

```tsx
import { Input } from '@misoto22/design'

<div className="flex w-full max-w-md flex-col gap-3">
  <Input placeholder="Resting" aria-label="Resting" />
  <Input invalid defaultValue="not-an-email" aria-label="Invalid" />
  <Input disabled placeholder="Disabled" aria-label="Disabled" />
</div>
```

## Example — types and autofill

```tsx
import { Field, Input } from '@misoto22/design'

<div className="flex w-full max-w-sm flex-col gap-4">
  <Field label="Email" htmlFor="signin-email">
    <Input
      id="signin-email"
      type="email"
      inputMode="email"
      autoComplete="email"
      placeholder="maya.chen@studio.example"
    />
  </Field>
  <Field label="Password" htmlFor="signin-password">
    <Input id="signin-password" type="password" autoComplete="current-password" />
  </Field>
  <Field label="Mobile" htmlFor="signin-mobile" hint="Australian numbers keep their leading zero.">
    <Input
      id="signin-mobile"
      type="tel"
      inputMode="tel"
      autoComplete="tel-national"
      placeholder="0412 345 678"
    />
  </Field>
</div>
```

## Example — read only

```tsx
import { Field, Input } from '@misoto22/design'

<div className="flex w-full max-w-sm flex-col gap-4">
  <Field
    label="Workspace address"
    htmlFor="workspace-host"
    hint="Fixed at sign-up. Copy it, but it cannot be edited here."
  >
    <Input id="workspace-host" name="workspace" readOnly defaultValue="studio-nine.example.com" />
  </Field>
  <Field
    label="Seats"
    htmlFor="workspace-seats"
    hint="Locked while an invoice is outstanding — this one sends nothing on submit."
  >
    <Input id="workspace-seats" disabled defaultValue="24" />
  </Field>
</div>
```

# NumberField

A number, typed or swept to.

- Group: Forms
- Import: `import { NumberField } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/number-field/
- Related: input, slider, field

## When to reach for it

The number has a range and a sensible increment. A bare quantity is an Input with type="number"; a value judged by WHERE it sits on a track is a Slider.

## Anatomy

- **Field** (required) — A native number input wearing CONTROL_BASE, so it is the same box as Input, Textarea and Select — same padding, same focus, same disabled opacity. The native spinner buttons are hidden: they are three different controls in three browsers and none of them is this system’s.
- **Scrub grip** — A horizontal-arrows glyph at the inline start, on unless scrub is false. Dragging it changes the value by one step every 4px, ten steps with Shift held, and it follows the reading direction — in an RTL page, more is to the left. Pointer only and aria-hidden, because the keyboard already has the arrow keys.
- **Unit** — unit, drawn inside the end of the box and announced through aria-describedby. The slot is a fixed 3rem, so a unit longer than about four characters runs under a long number.

## Best practices

### Do

- Reach for it when a value is TUNED rather than entered — a duration, a line height, an offset. The grip is the whole argument for this over an Input: a reader finds those by sweeping past the neighbouring values, not by typing candidates one at a time.
- Wrap it in a Field. The root is a div and the id lands on the input inside it, so the label binds and clicks through exactly as it does for an Input — but only if there is a Field to do it.
- Pass min, max and step. They are what the arrows step by, what one notch of a scrub is worth, and what the value is reconciled with when the field is left; without them the control is an Input with a grip on it.

### Don’t

- Do not expect the range to hold mid-keystroke. Clamping happens on blur, not on every character, because a minimum of 10 otherwise makes 50 unreachable — the 5 is clamped up before the 0 arrives. onValueChange can report a number outside the range; the value that SETTLES is always inside it.
- Do not turn the grip off and expect a pointer to have another way through. There are no spinner buttons behind it — hiding those is the point — so scrub={false} leaves a mouse with typing and nothing else. Turn it off for a quantity that is chosen rather than swept to, and accept that trade knowingly.
- Do not put the unit in the box and nowhere else past about four characters. The slot is fixed, so “requests” runs under the number; a long unit belongs in the Field’s label, where it is read rather than clipped.

## Accessibility

- It is a real <input type="number">, so the platform supplies the spinbutton role, the value, and the range it is announced against.
- unit reaches assistive tech through aria-describedby, so “300” is not announced as a number with no dimension.
- The grip is aria-hidden and not focusable: it commits nothing a keyboard cannot already reach, and announcing it would offer a reader a control that does nothing when they press it.
- invalid and aria-invalid are read together, so a form library setting either one paints the same border.

## Keyboard

- ↑ / ↓ — Steps by one step, honouring min and max.
- Enter — Reconciles what has been typed with the range and the step.
- Escape — Abandons the edit and restores the last settled value.

## NumberField

A number, typed or swept to. `Input` with `type="number"` is a box that happens to reject letters. This is the control for a number that has a RANGE and a sensible increment: the arrows step it, the grip sweeps it, and `min`, `max` and `step` are honoured on the way out rather than merely announced. Reach for `Slider` instead when the position along the range is the information — a volume, a confidence, anything a reader judges by where the thumb sits. Reach for this when the digits are. A slider that also has to be exact is a `Slider` with `editable`, not one of these beside it. **Clamping happens when the field is left, not while it is being typed.** A minimum of 10 would otherwise make 50 unreachable: the `5` is clamped up to 10 before the `0` arrives. So `onValueChange` can report a number outside the range mid-keystroke, and the value that settles is always inside it. The native spinner buttons are hidden — they are three different controls in three browsers, and none of them is this system's. The grip replaces them for a pointer; the arrow keys were always the keyboard's answer.

### Props

- `value` — `number`.
- `defaultValue` — `number`.
- `onValueChange` — `(value: number) => void`. Fires with the parsed number. Raw `onChange` still fires with the event.
- `min` — `number` default `Number.NEGATIVE_INFINITY`.
- `max` — `number` default `Number.POSITIVE_INFINITY`.
- `step` — `number` default `1`. The increment for the arrows and for one notch of a scrub.
- `unit` — `string`. A unit drawn inside the end of the field — `%`, `px`, `ms`. The field reserves a fixed slot for it, so keep it to about four characters; a longer one runs under a long number. It is announced through `aria-describedby` as well as drawn, because a unit nobody hears turns "300" into a number with no dimension.
- `scrub` — `boolean` default `true`. A grip at the start of the field that changes the value as it is dragged. On by default, and the reason to reach for this over `<Input type="number">`: a value that is being TUNED — a duration, a weight, an offset — is found by sweeping through neighbouring values, not by typing candidates one at a time. Shift multiplies the travel by ten. Pointer only, and `aria-hidden` for that reason: the same journey on a keyboard is the arrow keys on the field itself, which the platform already provides. Turn it off where the number is a quantity rather than a setting — a line item's quantity is chosen, not swept to.
- `invalid` — `boolean`. Paints the resting border with `--danger` and reflects `aria-invalid`.
- `ref` — `Ref<HTMLInputElement>`.

Also accepts: `Omit<InputHTMLAttributes<HTMLInputElement>, 'value' | 'defaultValue' | 'min' | 'max' | 'step' | 'type'>`.

## Example — default

```tsx
import { Field, NumberField } from '@misoto22/design'

<div className="flex w-full max-w-xs flex-col gap-5">
  <Field label="Line height" hint="Between 1 and 3.">
    <NumberField defaultValue={1.5} min={1} max={3} step={0.1} />
  </Field>
  <Field label="Corner radius">
    <NumberField defaultValue={12} min={0} max={64} unit="px" />
  </Field>
</div>
```

## Example — clamping on the way out

```tsx
import { Field, NumberField, Text } from '@misoto22/design'

<div className="flex w-full max-w-xs flex-col gap-3">
  <Field label="Retries" hint="Between 10 and 100.">
    <NumberField value={retries} onValueChange={setRetries} min={10} max={100} step={5} />
  </Field>
  <Text size="sm" tone="muted">
    Reported: {retries}
  </Text>
</div>
```

# Textarea

Multi-line text entry, resizable vertically only.

- Group: Forms
- Import: `import { Textarea } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/textarea/
- Related: input, field

## Anatomy

- **Control box** (required) — The <textarea>, on the same CONTROL_BASE as Input plus a min-h-24 floor. That floor is under rows, not over it: rows={2} still renders six rems tall.
- **Resize grip** — The browser’s own corner handle, constrained to resize-y — a reader can lengthen the box but cannot drag it past the measure or out of the page’s gutter.
- **Danger border** — The same pair isInvalid reads on Input: the invalid prop or an aria-invalid, including the one a Field sets when it has an error.

## Best practices

### Do

- Set rows to the answer you expect. It is the only thing that raises the resting height above the six-rem floor, and the size of the box is the clearest thing on the page about how long an answer should be.
- If there is a length limit, set maxLength AND say so in the hint: maxLength swallows the keystroke without explaining, and a paste one character too long is silently truncated.
- Keep Enter meaning newline. A textarea that submits on Enter has taken the one key the control exists to accept, and the reader loses the paragraph they were halfway through.

### Don’t

- There is no auto-grow. The height is whatever rows and min-h-24 settled on and it never follows the content, so a long answer is reviewed through a six-rem window unless the call site says otherwise.
- Do not put a required format in the Field’s hint and nothing else: hint and error share one slot, so the format vanishes the instant the field is wrong — which is the only moment anyone needed it.

## Textarea

Multi-line text entry. Resizes vertically only: horizontal resize lets a reader drag the control past the measure and past the page's own gutter.

### Props

- `invalid` — `boolean`. Paints the resting border with `--danger` and reflects `aria-invalid`.
- `ref` — `Ref<HTMLTextAreaElement>`.

Also accepts: `TextareaHTMLAttributes<HTMLTextAreaElement>`.

## Example — default

```tsx
import { Textarea } from '@misoto22/design'

<Textarea className="max-w-md" rows={4} aria-label="Notes" placeholder="Tell us more…" />
```

## Example — rows and limits

```tsx
import { Field, Textarea } from '@misoto22/design'

<Field
  label="Condition notes"
  hint={`${LIMIT - notes.length} characters left of ${LIMIT}.`}
  className="w-full max-w-sm"
>
  <Textarea
    rows={4}
    maxLength={LIMIT}
    value={notes}
    onChange={(event) => setNotes(event.target.value)}
  />
</Field>
```

## Example — invalid

```tsx
import { Field, Textarea } from '@misoto22/design'

<Field
  label="Release notes"
  required
  error="Open with a line starting Added, Fixed or Changed — that first word groups the entry in the changelog."
  className="w-full max-w-sm"
>
  <Textarea rows={4} defaultValue="tidied up the release script a bit" />
</Field>
```

# Select

A choice from a list, styled the whole way down.

- Group: Forms
- Import: `import { Select } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/select/
- Related: combobox, native-select, field

## When to reach for it

Up to roughly a dozen options. Past that a Combobox wins, because a list nobody can filter is slower to scan than one you can type into.

## Anatomy

- **Trigger** (required) — A <button role="combobox"> on CONTROL_BASE, so it matches the Input beside it exactly. It is named by the label and by its own value together, and carries the chevron that turns over while the panel is open.
- **Value** — The chosen item’s text, or placeholder in --ink-3-aa when nothing is chosen. It truncates, and it is the half of the accessible name that says what was picked.
- **Panel** — Portalled, at least as wide as the trigger and at most 18rem tall, with a scroll chevron appearing at each end once the list is longer than that.
- **Item** — One option. The 3.5 tick box is always drawn and only the tick inside it appears, so choosing does not shunt every label sideways; data-highlighted is the fill, the tick is the chosen one.
- **Group heading** — SelectLabel — a mono eyebrow inside a SelectGroup. It is a heading, not an option, which is the difference between it and a disabled item used as a divider.

## Best practices

### Do

- Pass name when the value has to survive a submit. The trigger is a <button>; Radix renders the hidden native <select> that carries the value only when the control is inside a <form>, and only a named one sends anything.
- Pick one spelling of invalid. The trigger reads the invalid prop and aria-invalid alike, including the one a Field sets from error, so setting both is two sources of truth for one border.
- Divide long lists with SelectGroup and SelectLabel rather than a disabled item used as a heading: a disabled item is still an option, so a screen reader counts it and announces the list as one longer than it is.

### Don’t

- Inside a Field with a label, the label prop here is not announced — the field’s words name the trigger — so a label that disagrees with the one above it is dead text nobody will ever hear.
- Do not lean on the closed trigger to show a long option: it truncates to keep the field’s height, so the end of the value is only readable with the panel open.
- Do not point contentClassName at the trigger. className is the trigger; contentClassName is the panel, and confusing them is how a select gets a 18rem-wide dropdown over the thing it is choosing for.

## Accessibility

- Inside a bounded frame — a device preview, an embedded console — wrap the subtree in `<OverlayContainer container={el}>`. The panel then renders into that element and collides with its edges instead of the viewport’s, and inherits the `dir` and `data-density` set there.
- The option list is ours, so it does not change typeface, spacing and selection colour the moment it opens — which is what a native select does.
- The keyboard contract is the platform's: typeahead, arrows, Home and End, Escape to close without choosing.
- label is required, and it is announced WITH the value: the trigger reads "Region, Australia", because a value is not a name and a name without the value is not the answer. Inside a Field the FIELD’s label supplies the name half — the trigger’s aria-labelledby points at that label and at the value — and the label prop here is neither rendered nor announced, so one that disagrees with the words above it is text nobody will hear.

## Keyboard

- Enter / Space / ↓ — Opens the list.
- ↑ / ↓ — Moves between options.
- a–z — Typeahead — jumps to the next option starting with that letter.
- Home / End — Jumps to the first or last option.
- Escape — Closes without choosing.

## SelectRoot

Re-export of `SelectPrimitive.Root`.

Radix Select root, group and label, as typed passthroughs.

## SelectGroup

Re-export of `SelectPrimitive.Group`.

## Select

A choice from a list, styled the whole way down. The option list is ours — drawn from the same tokens as everything else, so it does not change typeface, spacing and selection colour the moment it opens. That is the whole reason this replaced the native control as the default: a design system whose most common form control stops being part of the system on click is not a design system, it is a stylesheet for closed states. The keyboard contract is Radix's, which means it is the platform's: typeahead works, the arrows move, Home and End reach the ends, and Escape closes without choosing. That was the one genuine argument for staying native, and it is answered. Past roughly a dozen options, reach for `Combobox` — a list nobody can filter is worse than one they can type into. Where the platform picker is genuinely better — a phone, or a form that must survive without JavaScript — reach for `NativeSelect`.

### Props

- `contentClassName` — `string`. Classes for the option PANEL, not the trigger. `className` styles the trigger, which is the common case. This exists for the uncommon one: a select inside a bounded surface, where the default 18rem of list would cover the thing the reader is choosing for — a year picker over its own calendar, say.
- `label` (required) — `string`. Names the control. Required — the trigger shows a value, and a value is not a name. It is announced together with the value, not instead of it: the trigger is named by the label and by its own text, so a reader hears "Region, Australia". Inside a `Field` with a label, that label is used and this one is not repeated.
- `placeholder` — `string` default `'Select…'`.
- `invalid` — `boolean`. Paints the resting border with `--danger` and reflects `aria-invalid`.
- `disabled` — `boolean`.
- `className` — `string`.
- `id` — `string`. The TRIGGER's id — the element a label points at. A `Field` sets it.
- `aria-describedby` — `string`. Ids of the copy describing the control. A `Field` sets it from hint, error and description.
- `aria-invalid` — `boolean | 'true' | 'false'`. The spelling a form library sets; read together with `invalid`.
- `aria-required` — `boolean`. Announced on the trigger. A `Field` sets it from `required`.
- `children` (required) — `ReactNode`. `SelectItem`s, optionally wrapped in `SelectGroup` with a `SelectLabel`.

Also accepts: `ComponentProps<typeof SelectPrimitive.Root>`.

## SelectItem

One option. The tick marks the chosen one; the fill marks the highlighted one.

Also accepts: `ComponentProps<typeof SelectPrimitive.Item>`.

## SelectLabel

Mono eyebrow heading for a group of options. Must sit inside a `SelectGroup` — Radix throws otherwise, because a heading with no group is a heading for nothing, and assistive tech would announce it as an option.

## SelectSeparator

Hairline divider between groups.

## Example — default

```tsx
import { Field, Select, SelectGroup, SelectItem, SelectLabel, SelectSeparator } from '@misoto22/design'

<Field label="Region" hint="The list is ours, not the platform’s — open it." className="w-full max-w-xs">
  <Select label="Region" defaultValue="au">
    <SelectGroup>
      <SelectLabel>Oceania</SelectLabel>
      <SelectItem value="au">Australia</SelectItem>
      <SelectItem value="nz">New Zealand</SelectItem>
    </SelectGroup>
    <SelectSeparator />
    <SelectGroup>
      <SelectLabel>Asia</SelectLabel>
      <SelectItem value="jp">Japan</SelectItem>
      <SelectItem value="sg">Singapore</SelectItem>
      <SelectItem value="cn">China</SelectItem>
    </SelectGroup>
  </Select>
</Field>
```

## Example — invalid

```tsx
import { Field, Select, SelectItem } from '@misoto22/design'

<Field label="Plan" required error="Choose a plan before inviting your team." className="w-full max-w-xs">
  <Select label="Plan" invalid placeholder="Select a plan">
    <SelectItem value="solo">Solo — one seat</SelectItem>
    <SelectItem value="studio">Studio — ten seats</SelectItem>
    <SelectItem value="agency">Agency — unlimited seats</SelectItem>
  </Select>
</Field>
```

## Example — inside a form

```tsx
import { Button, Field, Select, SelectItem, Text } from '@misoto22/design'

<form
  className="flex w-full max-w-xs flex-col gap-4"
  onSubmit={(event) => {
    event.preventDefault()
    setSent(String(new FormData(event.currentTarget).get('currency') ?? 'nothing'))
  }}
>
  <Field label="Currency" className="w-full">
    <Select label="Currency" name="currency" defaultValue="aud">
      <SelectItem value="aud">Australian dollar</SelectItem>
      <SelectItem value="jpy">Japanese yen</SelectItem>
      <SelectItem value="usd">United States dollar</SelectItem>
    </Select>
  </Field>
  <Button type="submit" variant="secondary" className="self-start">
    Save
  </Button>
  {sent !== undefined && (
    <Text size="sm" tone="muted">
      The form sent currency = {sent}
    </Text>
  )}
</form>
```

# NativeSelect

The platform’s own picker, restyled where it can be.

- Group: Forms
- Import: `import { NativeSelect } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/native-select/
- Related: select, field

## When to reach for it

The escape hatch, not the default. Reach for it where the platform genuinely wins: a very long list on a phone, a form that must work without JavaScript, a page counting its last kilobyte.

## Anatomy

- **Wrapper** (required) — A relative <div> around the pair, and the element className lands on. It is the only control in this group where className does not go to the field itself, because the chevron is pinned to this box: a width set anywhere else strands the arrow at the far edge of the row.
- **Control box** (required) — The <select> on CONTROL_BASE, appearance-none so the platform’s own arrow is gone, with pe-9 of end padding so the longest option clears the drawn one. It fills the wrapper, so the wrapper’s width is the field’s width.
- **Chevron** (required) — A pointer-events-none icon pinned to the wrapper’s end edge. It is ours, not the platform’s, so it does not flip or move when the picker opens.
- **Option list** — children, drawn by the operating system on open. <option> and <optgroup> are the only things in it, and neither takes these tokens.

## Best practices

### Do

- Give it an explicit empty first option, or a defaultValue. A <select> nobody touches has its first option selected, so an untouched form submits the top of the list as though someone chose it.
- Group with <optgroup>: it is the one piece of structure the OS picker actually renders, and there is no styled equivalent to fall back on the way SelectLabel gives Select one.
- Set the width with className. It lands on the wrapper the chevron is pinned to and the select fills it, so the arrow travels with the edge of the field rather than staying where the row ends.

### Don’t

- multiple and size do not survive the styling: appearance-none plus a chevron pinned to the middle of the wrapper turns a list box into a scrolling column with an arrow drawn across it. Use checkboxes, or a multiple Combobox.
- Do not use the first option as the label. “Select a country” is announced as a choosable value and it is the value an untouched form submits — put the name in a Field and give that option value="" and disabled.
- Do not send the control’s own ink or border through className: it dresses the wrapper, and the <select> inside keeps CONTROL_BASE whatever the box around it says.

## Accessibility

- Typeahead and the mobile wheel come free, from the browser.
- What it cannot do is look like the rest of the system once open — the option list is drawn by the operating system and carries none of these tokens.

## Keyboard

- Space / ↓ — Opens the platform picker.
- a–z — Typeahead, from the browser’s own implementation.

## NativeSelect

A native `<select>`, restyled. The escape hatch, not the default — `Select` is the styled one. Reach for this where the platform's own picker is genuinely better: a very long list on a phone, a form that must work without JavaScript, a page where the last kilobyte matters. The browser gives typeahead and the mobile wheel for free, and those are real. What it cannot do is look like the rest of the system once open. The option list is drawn by the operating system, so it carries none of these tokens — which is exactly why it stopped being the default. `className` sizes the WRAPPER, not the `<select>` inside it. This is the one control here that renders two elements, and the chevron is pinned to the wrapper's end edge: a width on the select alone narrowed the box and left the arrow floating at the far side of the row. The select fills whatever the wrapper is.

### Props

- `invalid` — `boolean`. Paints the resting border with `--danger` and reflects `aria-invalid`.
- `ref` — `Ref<HTMLSelectElement>`.

Also accepts: `SelectHTMLAttributes<HTMLSelectElement>`.

## Example — default

```tsx
import { Field, NativeSelect } from '@misoto22/design'

<Field
  label="Density"
  hint="The platform's own picker — better on a phone, and it works without JavaScript."
  className="w-full max-w-xs"
>
  <NativeSelect defaultValue="mid">
    <option value="tight">Tight</option>
    <option value="mid">Comfortable</option>
    <option value="loose">Loose</option>
  </NativeSelect>
</Field>
```

## Example — a placeholder option

```tsx
import { Field, NativeSelect } from '@misoto22/design'

<Field
  label="Country"
  required
  hint="Where the invoice is issued from."
  className="w-full max-w-xs"
>
  <NativeSelect defaultValue="" required>
    <option value="" disabled>
      Select a country
    </option>
    <option value="au">Australia</option>
    <option value="jp">Japan</option>
    <option value="nz">New Zealand</option>
    <option value="sg">Singapore</option>
  </NativeSelect>
</Field>
```

## Example — option groups

```tsx
import { Field, NativeSelect } from '@misoto22/design'

<Field label="Time zone" className="w-full max-w-xs">
  <NativeSelect defaultValue="Australia/Sydney">
    <optgroup label="Australia">
      <option value="Australia/Perth">Perth</option>
      <option value="Australia/Adelaide">Adelaide</option>
      <option value="Australia/Sydney">Sydney</option>
    </optgroup>
    <optgroup label="Asia">
      <option value="Asia/Singapore">Singapore</option>
      <option value="Asia/Tokyo">Tokyo</option>
    </optgroup>
  </NativeSelect>
</Field>
```

# Checkbox

A choice that takes effect when the form is submitted.

- Group: Forms
- Import: `import { Checkbox } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/checkbox/
- Related: switch, radio-group

## When to reach for it

A setting that applies immediately is a Switch.

## Anatomy

- **Box** (required) — An 18px <button role="checkbox"> on --radius-xs. It fills with --accent for BOTH checked and indeterminate, so the fill says “not off” rather than “on”.
- **Tick** — The check glyph, aria-hidden — Radix shows the indicator, the state is carried by the role.
- **Dash** — The minus that replaces the tick, chosen from the state the box is actually in — controlled or not, so defaultChecked="indeterminate" draws the dash it promised rather than a tick.
- **Label** — Not rendered here. Unlike RadioGroupItem, nothing wraps the box in a <label>, so the words beside it and the click target they give it are the call site’s job.

## Best practices

### Do

- Wrap it and its words in a <label>, or put it in a Field: the control renders no label of its own, so a bare Checkbox has no accessible name and an 18px box is the entire click target.
- Hold an indeterminate box on controlled state. It is a report about OTHER rows, and clicking it hands you true — a “select all” header that keeps its own answer stops describing the list underneath it on the first click.
- Default the value on the server. An unticked box sends no entry at all in a form submission, so the field a reader deliberately cleared and a field that was never rendered arrive identically as undefined.

### Don’t

- checked without onCheckedChange gives a box that never moves: Radix treats the prop as the source of truth, so the reader clicks a control that is neither broken nor working and gets no feedback either way.
- There is no readOnly on a Radix checkbox. disabled is the only lock and it drops the box out of the tab order and out of the form, so a value that must be shown but not changed is better drawn as text.
- Do not put the indeterminate state on a leaf. It means “some of the things under this one”, so a box with nothing under it that draws a dash is reporting a state its own value cannot hold.

## Accessibility

- Supports the indeterminate state, which is what a “select all” header needs when only some rows are selected.

## Keyboard

- Space — Toggles it.

## Checkbox

A choice that takes effect when the form is submitted. Supports the indeterminate state (`checked="indeterminate"`), which is what a "select all" header needs when only some rows are selected — a plain unchecked box there tells the reader the opposite of the truth. Controlled or not: the glyph follows the state the box is actually in, so an uncontrolled `defaultChecked="indeterminate"` draws the dash rather than the tick that says the opposite. Pair with `Field`, or wrap it in a `<label>` at the call site so the words beside it are part of the click target.

Also accepts: `ComponentProps<typeof CheckboxPrimitive.Root>`.

## Example — default

```tsx
import { Checkbox } from '@misoto22/design'

<div className="flex flex-col gap-3 text-sm text-(--ink-2)">
  <label className="flex cursor-pointer items-center gap-2.5">
    <Checkbox
      checked={some ? 'indeterminate' : all}
      onCheckedChange={(next) => setChecked(next === true ? JOBS : [])}
    />
    Select all
  </label>

  <div className="ms-6 flex flex-col gap-3 border-s border-(--rule) ps-4">
    {JOBS.map((job) => (
      <label key={job} className="flex cursor-pointer items-center gap-2.5">
        <Checkbox
          checked={checked.includes(job)}
          onCheckedChange={(next) =>
            setChecked((previous) =>
              next === true ? [...previous, job] : previous.filter((item) => item !== job),
            )
          }
        />
        {job}
      </label>
    ))}
  </div>

  <label className="flex items-center gap-2.5 text-(--ink-3-aa)">
    <Checkbox disabled /> Requires admin
  </label>
</div>
```

## Example — with descriptions

```tsx
import { Checkbox, Text } from '@misoto22/design'

<div className="flex max-w-sm flex-col gap-4">
  {OPTIONS.map((option) => (
    <label key={option.id} className="flex cursor-pointer items-start gap-3">
      <Checkbox defaultChecked={option.on} className="mt-0.5" />
      <span className="flex flex-col gap-0.5">
        <Text as="span" size="sm" tone="strong">
          {option.label}
        </Text>
        <Text as="span" size="xs" tone="muted">
          {option.detail}
        </Text>
      </span>
    </label>
  ))}
</div>
```

## Example — inside a form

```tsx
import { Button, Checkbox, Text } from '@misoto22/design'

<form
  className="flex max-w-sm flex-col gap-3"
  onSubmit={(event) => {
    event.preventDefault()
    const keys = [...new FormData(event.currentTarget).keys()]
    setSent(keys.length > 0 ? keys.join(', ') : 'nothing at all')
  }}
>
  <label className="flex cursor-pointer items-center gap-2.5 text-sm text-(--ink-2)">
    <Checkbox name="backups" value="nightly" defaultChecked /> Nightly backups
  </label>
  <label className="flex cursor-pointer items-center gap-2.5 text-sm text-(--ink-2)">
    <Checkbox name="telemetry" value="anonymous" /> Share anonymous usage data
  </label>
  <Button type="submit" variant="secondary" className="self-start">
    Save
  </Button>
  {sent !== undefined && (
    <Text size="sm" tone="muted">
      The form sent: {sent}
    </Text>
  )}
</form>
```

# RadioGroup

A set of mutually exclusive choices.

- Group: Forms
- Import: `import { RadioGroup } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/radio-group/
- Related: checkbox, select

## Anatomy

- **Group** (required) — A <div role="radiogroup"> stacking its options. Being a div is why the label above it names the group by being pointed AT — aria-labelledby, not htmlFor — and why the words do not click through.
- **Row** (required) — The <label> RadioGroupItem wraps around control and words. It is the click target — a bare 18px circle is below every pointer-target guideline — and it is the only source of the option’s accessible name.
- **Circle** (required) — The 18px control itself, its border turning --accent when chosen.
- **Dot** — The 10px --accent fill inside the circle, present only on the chosen option.

## Best practices

### Do

- Name the group. Inside a Field its label does it, through aria-labelledby; standing alone it needs its own aria-label, and without either the group is announced as three unlabelled radios.
- Set defaultValue or value. Selection follows focus here, so a group that starts empty commits an answer the moment anybody arrows into it — including a reader who was only passing through on the way to the next field.
- Add an explicit “None” or “Any” option when the answer is genuinely optional: there is no way back to nothing once a radio is chosen, neither by clicking it again nor from the keyboard.

### Don’t

- Do not hang an expensive effect on onValueChange. Every arrow press commits, so a group whose options fetch or navigate fires once per key on the way past the ones nobody wanted.
- Do not reach past RadioGroupItem to the Radix primitive or hand-roll the row: selection-follows-focus is implemented in this item’s own focus handler, not upstream, so a hand-rolled one moves the outline and selects nothing.
- Do not disable one option to mean “not available here”: the roving focus skips it entirely, so a keyboard reader never learns the option exists. Say why in the Field’s hint and leave the option out.

## Accessibility

- One tab stop for the whole group; the arrow keys move between options, per the ARIA radiogroup pattern.
- The label is inside the <label>, so the whole row is the click target.

## Keyboard

- Tab — Moves into the group, and out of it — the whole group is one stop.
- ↑ / ↓ / ← / → — Moves between options AND selects as it goes.

## RadioGroup

A set of mutually exclusive choices. Radix owns the roving tabindex, so the whole group is ONE tab stop and the arrow keys move between options — which is what the ARIA radiogroup pattern requires and what a stack of hand-rolled `<input type="radio">` wrappers usually gets wrong. Inside a `Field` the group takes its name from that label, by pointing back at it: the root is a `<div role="radiogroup">` and `<label for>` does not bind to one, so the words above it click through no more than a `<legend>` does. Standing alone, it still needs an `aria-label` of its own — an unnamed group is three unlabelled radios.

Also accepts: `ComponentProps<typeof RadioGroupPrimitive.Root>`.

## RadioGroupItem

One option, and its label, as a single click target. The `<label>` wraps both, so the whole row is clickable — a bare 18px circle is below every pointer-target guideline and is miserable on a phone. It is also what gives the control its accessible name: remove the wrapper and the radio has no name at all. Selection follows focus, which is the half of the pattern that makes a radiogroup usable from the keyboard: moving to an option chooses it, so nobody has to press an extra key to commit. That is implemented here rather than inherited, because the upstream primitive gates it on a flag cleared by `keyup` and loses the race against its own focus move — see ARROW_GRACE_MS. Re-selecting an already-selected option is a no-op, so this stays correct even where the upstream path does fire.

### Props

- `children` (required) — `ReactNode`. The visible label. Rendered inside the `<label>` that wraps the control.

Also accepts: `Omit<ComponentProps<typeof RadioGroupPrimitive.Item>, 'children'>`.

## Example — default

```tsx
import { RadioGroup, RadioGroupItem } from '@misoto22/design'

<RadioGroup defaultValue="system" aria-label="Appearance">
  <RadioGroupItem value="light">Light</RadioGroupItem>
  <RadioGroupItem value="dark">Dark</RadioGroupItem>
  <RadioGroupItem value="system">Match the system</RadioGroupItem>
</RadioGroup>
```

## Example — options with detail

```tsx
import { RadioGroup, RadioGroupItem, Text } from '@misoto22/design'

<RadioGroup defaultValue="studio" aria-label="Plan" className="max-w-sm">
  {PLANS.map((plan) => (
    <RadioGroupItem key={plan.value} value={plan.value} className="items-start">
      <span className="flex flex-col gap-0.5">
        <Text as="span" size="sm" tone="strong">
          {plan.name}
        </Text>
        <Text as="span" size="xs" tone="muted">
          {plan.detail}
        </Text>
      </span>
    </RadioGroupItem>
  ))}
</RadioGroup>
```

## Example — a way back

```tsx
import { RadioGroup, RadioGroupItem } from '@misoto22/design'

<RadioGroup defaultValue="any" aria-label="Delivery window">
  <RadioGroupItem value="any">Any time</RadioGroupItem>
  <RadioGroupItem value="morning">Morning — 8am to 12pm</RadioGroupItem>
  <RadioGroupItem value="afternoon">Afternoon — 12pm to 5pm</RadioGroupItem>
  <RadioGroupItem value="evening">Evening — 5pm to 8pm</RadioGroupItem>
</RadioGroup>
```

# Switch

A setting that takes effect immediately.

- Group: Forms
- Import: `import { Switch } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/switch/
- Related: checkbox

## When to reach for it

Inside a form with a Save button, a switch is a lie about when the change happened. Use a Checkbox.

## Anatomy

- **Track** (required) — A 36×20 <button role="switch"> on a pill radius, filled --stone when off and --accent when on. Filled rather than outlined, so it still reads as a control on a white page.
- **Thumb** (required) — A 14px paper circle with a hairline, not a white disc on a shadow — this system has no shadows. It stretches to 20px while pressed and rounds out as it lands; motion-reduce drops that entirely.
- **Label** — Not rendered here either. The Radix root IS a <button>, though, which a <label for> does bind to — so unlike Select or RadioGroup, a Field’s label above a Switch really does click through to it.

## Best practices

### Do

- Handle the failure at the control. The flip has already claimed the change happened, so an onCheckedChange whose request fails must put the thumb back and say why, or the page is showing a setting the server does not have.
- Name it for the state, not the action: the accessible name is read together with “on” or “off”, so “Email notifications, on” is a sentence and “Turn on email notifications, on” is two contradictory ones.
- Keep the flip instant to the eye even when the write is not — an optimistic thumb with a quiet undo beats a spinner on a control whose whole claim is that it already took effect.

### Don’t

- A switch has two states and no third. “Inherit from the workspace” cannot be a switch, because the only way to draw it is unchecked, which announces “off” — that is a RadioGroup or a Select.
- There is no readOnly: disabled is the only lock, and it takes the control out of the tab order, so a keyboard reader tabbing the form passes the setting without ever hearing its value.
- Do not add transition-all from a call site. It replaces transition-[transform,width] wholesale, which puts the track’s colour on the thumb’s longer duration and turns a flip into a fade.

## Keyboard

- Space / Enter — Toggles it, and the change applies immediately.

## Switch

A setting that takes effect immediately. Distinct from `Checkbox`, and the distinction is not cosmetic: a switch applies on flip, a checkbox applies on submit. A switch inside a form with a Save button is a lie about when the change happened. The track fills with ink when on and the thumb is paper with a hairline — rather than a white thumb floating on a drop shadow, which this system does not have. The off state is a filled rule-coloured track, so the control still reads as a control on a white page.

Also accepts: `ComponentProps<typeof SwitchPrimitive.Root>`.

## Example — default

```tsx
import { Switch } from '@misoto22/design'

<div className="flex flex-col gap-3">
  {SETTINGS.map((setting) => (
    <label key={setting.id} className="flex cursor-pointer items-center gap-3 text-sm">
      <Switch
        checked={state[setting.id]}
        onCheckedChange={(next) => setState((previous) => ({ ...previous, [setting.id]: next }))}
      />
      {/* The label follows the state. A switch that is off beside a label
          at full strength reads as "on" at a glance, and the control is
          the smaller of the two things on the row. */}
      <span
        className={
          state[setting.id]
            ? 'text-(--ink) transition-colors duration-(--duration-fast)'
            : 'text-(--ink-3-aa) transition-colors duration-(--duration-fast)'
        }
      >
        {setting.label}
      </span>
      <span className="ms-auto mono-meta text-(--ink-3-aa)">
        {state[setting.id] ? 'On' : 'Off'}
      </span>
    </label>
  ))}
</div>
```

## Example — a failed write

```tsx
import { Alert, Switch } from '@misoto22/design'

<div className="flex max-w-sm flex-col gap-3">
  <label className="flex cursor-pointer items-center gap-3 text-sm text-(--ink-2)">
    <Switch checked={on} onCheckedChange={save} />
    Two-factor authentication
  </label>
  {failed && (
    <Alert tone="danger" title="Could not reach the authentication service.">
      Two-factor authentication is still off. Try again in a moment.
    </Alert>
  )}
</div>
```

## Example — a third state

```tsx
import { RadioGroup, RadioGroupItem, Switch, Text } from '@misoto22/design'

<div className="flex flex-col gap-8 sm:flex-row sm:gap-12">
  <div className="flex flex-col gap-2">
    <Text size="xs" tone="muted">
      Two states
    </Text>
    <label className="flex cursor-pointer items-center gap-3 text-sm text-(--ink-2)">
      <Switch defaultChecked /> Require review before merge
    </label>
  </div>
  <div className="flex flex-col gap-2">
    <Text size="xs" tone="muted">
      Three
    </Text>
    <RadioGroup defaultValue="inherit" aria-label="Require review before merge">
      <RadioGroupItem value="on">Always require review</RadioGroupItem>
      <RadioGroupItem value="off">Never require review</RadioGroupItem>
      <RadioGroupItem value="inherit">Inherit from the workspace</RadioGroupItem>
    </RadioGroup>
  </div>
</div>
```

# Combobox

A select you can type into.

- Group: Forms
- Import: `import { Combobox } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/combobox/
- Related: select, command

## When to reach for it

Past roughly a dozen options. Below that a native Select is better: the platform picker on a phone, typeahead for free, no JavaScript.

## Anatomy

- **Trigger** (required) — A <button role="combobox"> named by the label and its own summary together, carrying aria-expanded. Its text truncates rather than wrapping, so the field keeps its height whatever is chosen.
- **Summary** — The trigger’s text: the placeholder, or up to two chosen labels joined by commas, then “n selected”. Counting past two is what stops a multiple picker reflowing the form on every choice.
- **Clear** — A <span role="button"> beside the chevron, on multiple with something chosen. A span rather than a nested <button>, which is invalid inside the trigger and which browsers reparent out of the field.
- **Filter field** — cmdk’s input inside the panel. It is named through the Command wrapper as “label: searchPlaceholder”, because aria-labelledby beats aria-label and naming the input directly did nothing.
- **Option row** — A tick for single, a fillable box for multiple, then the label. emptyMessage takes the list’s place when the filter matches nothing.

## Best practices

### Do

- Spell “nothing chosen” as an empty string when the value is controlled. value={undefined} is precisely how this component decides it is UNCONTROLLED, so clearing that way hands it back its own state and it stops following the parent.
- Put readable text in label and anything else worth matching in keywords: cmdk scores against the option’s value too, so a list keyed by UUID is being ranked on a string no reader will ever type.
- Say what WOULD match in emptyMessage. The default tells a reader the filter ran and nothing about which of the four hundred options they should have typed instead.

### Don’t

- Past two choices the trigger stops naming them — it announces “Tags, 3 selected”, and WHICH three is only in the panel. Print them beside the field when the choice has to be checkable without opening it.
- Do not hand it thousands of options. Nothing here virtualises: every option in the array renders into the panel on open and stays there behind the filter, so the list length is a DOM cost, not a search cost.
- A disabled option is not a hidden one — it still renders and still matches the filter, so a reader can type its exact name, watch it come up, and be unable to pick it with no reason offered.

## Accessibility

- The highlight moves through aria-activedescendant while focus stays in the input — the ARIA combobox pattern. Hand-rolled comboboxes move focus into the list, and the typed text stops being editable.
- label is required, and it is announced with the summary rather than instead of it: the trigger reads “Tags, 3 selected”. Inside a Field the FIELD’s label supplies the name half and the label prop is neither rendered nor announced on the trigger — it still names the clear control, as “Clear Tags”, so it has to stay truthful even where the trigger no longer says it.

## Keyboard

- Enter / Space / ↓ — Opens the list.
- ↑ / ↓ — Moves the highlight while focus stays in the filter.
- Enter — Chooses the highlighted option; choosing the current one clears it.
- Escape — Closes without choosing.

## Combobox

A select you can type into, choosing one or several. The line against `Select` is length, and it is not a matter of taste: a styled select is better up to roughly a dozen options, because a list nobody can filter is faster to scan than one they have to think about. Past that, this is the right answer. Filtering, the highlighted row and the arrow keys come from cmdk, which implements the ARIA combobox pattern properly: the highlight moves through `aria-activedescendant` while focus stays in the input. Hand-rolled comboboxes move focus into the list instead, and the typed text stops being editable. Controlled or uncontrolled, like every other form control here.

### Props

- `multiple` — `false`.
- `value` — `string`.
- `defaultValue` — `string`.
- `onValueChange` — `(value: string) => void`.
- `options` (required) — `ComboboxOption[]`.
- `label` (required) — `string`. Names the control. Required — the trigger's text is a value, not a label. Announced together with the summary rather than instead of it, so a reader hears "Tags, 3 selected". Inside a `Field` with a label, that label names the trigger and this one is not repeated.
- `placeholder` — `string` default `'Select…'`. Shown on the trigger when nothing is chosen.
- `searchPlaceholder` — `string` default `'Search…'`. Placeholder inside the filter field.
- `emptyMessage` — `string` default `'Nothing matches.'`. Shown when the filter matches nothing. Say what WOULD match.
- `disabled` — `boolean` default `false`.
- `className` — `string`.
- `id` — `string`. The TRIGGER's id — the element a label points at. A `Field` sets it.
- `aria-describedby` — `string`. Ids of the copy describing the control. A `Field` sets it from hint, error and description.
- `aria-invalid` — `boolean | 'true' | 'false'`. Paints the resting border with `--danger` and is announced. A `Field` sets it from `error`.
- `aria-required` — `boolean`. Announced on the trigger. A `Field` sets it from `required`.

## Example — default

```tsx
import { Combobox, Field } from '@misoto22/design'

<Field label="Camera" hint="Type to filter — “compact” matches two of them." className="w-full max-w-xs">
  <Combobox label="Camera" options={CAMERAS} placeholder="Pick a body" />
</Field>
```

## Example — multiple

```tsx
import { Combobox, Field } from '@misoto22/design'

<Field
  label="Tags"
  hint="The panel stays open while you pick; past two it counts instead of listing."
  className="w-full max-w-xs"
>
  <Combobox multiple label="Tags" options={TAGS} defaultValue={['film']} placeholder="Add tags" />
</Field>
```

## Example — controlled and cleared

```tsx
import { Button, Combobox, Field, Text } from '@misoto22/design'

<div className="flex w-full max-w-xs flex-col gap-3">
  <Field label="Reviewer" className="w-full">
    <Combobox
      label="Reviewer"
      options={REVIEWERS}
      value={reviewer}
      onValueChange={setReviewer}
      placeholder="Unassigned"
      searchPlaceholder="Search by name or team"
      emptyMessage="Nobody by that name — try a team, like platform."
    />
  </Field>
  <div className="flex items-center gap-3">
    <Button
      variant="secondary"
      size="sm"
      disabled={reviewer === ''}
      onClick={() => setReviewer('')}
    >
      Unassign
    </Button>
    <Text size="xs" tone="muted">
      value is {reviewer === '' ? 'an empty string' : reviewer}
    </Text>
  </div>
</div>
```

# DatePicker

A date — or a span of them — chosen from a calendar.

- Group: Forms
- Import: `import { DatePicker } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/date-picker/
- Related: calendar, field

## When to reach for it

Deliberately not a text input with a calendar attached: parsing a typed date needs a format, and 03/04 is March the fourth in one country and the third of April in the next. When the date is a long way back, the calendar’s month and year are dropdowns.

## Anatomy

- **Trigger** (required) — A <button> printing format(value) or the placeholder, with a calendar glyph pinned at the end. It is named by the label and the printed date together, so the format is heard as well as seen.
- **Panel** — A Popover holding the rail and the grid — side by side from sm up, stacked below it, where two months would not fit anyway.
- **Preset rail** — A role="group" of plain buttons, present only when presets is set: on by default for DateRangePicker, off by default for DatePicker. A shortcut that lands on a disabledDates day is drawn unavailable and refuses the click.
- **Calendar grid** — The shared Calendar, autoFocus on open so the keyboard lands in the month rather than back at the trigger. Two months at once on the range picker, from months.
- **Half-range text** — The range trigger prints “from – …” while only one end is chosen, so a half-answered range says so on the closed control instead of looking finished.

## Best practices

### Do

- Put the restriction in disabledDates rather than in your own handler. The rail asks it too, so a shortcut on a blocked day is disabled instead of committing a date the grid beside it refuses — a range preset is tested at its ENDS, so one straddling a blocked day is still offered, exactly as the grid still allows it.
- Pick controlled or uncontrolled and stay there. The current value is value ?? uncontrolled, so a controlled picker that clears by setting value to undefined falls through to whatever defaultValue seeded and the old date reappears.
- Validate a range before you use it: half a range is a legal state here — from set, to undefined — so a submit handler that reads value.to without checking gets undefined from a reader who simply closed the panel early.

### Don’t

- A Field’s required does not reach the trigger. It is a plain <button>, a role with nowhere to put aria-required, so the asterisk above is the whole of the marking and a screen reader meets an ordinary optional field.
- Do not reach for it for a birth date. There is no defaultMonth to pass: the panel always opens on the current month, so a date decades back begins with every reader in the month-and-year picker.
- Do not disable it to show a fixed date. disabled takes the trigger out of the tab order and blocks its pointer events, and the trigger is the only place the chosen date is printed at all.

## Accessibility

- The trigger prints the date in the visitor’s own locale, not a fixed dd/mm/yyyy, and announces it as part of its own name — so format reaches a screen reader too.
- DateRangePicker keeps the panel open until both ends are chosen — a range is not a value until it has a second date.
- The shortcut rail is plain buttons, not a menu: they set the same value the grid beside them sets, so they belong to one control and Tab in the same pass.
- Presets are computed on click, so “today” means today even on a tab left open overnight.

## Keyboard

- Enter / Space — Opens the calendar.
- Escape — Closes it without choosing.

## RANGE_PRESETS

Re-export of `[
  { label: 'Last 7 days', value: () => daysAgo(7) },
  { label: 'Last 30 days', value: () => daysAgo(30) },
  { label: 'Last 90 days', value: () => daysAgo(90) },
  { label: 'Last 12 months', value: () => daysAgo(365) },
  {
    label: 'Month to date',
    value: () => {
      const to = new Date()
      return { from: new Date(to.getFullYear(), to.getMonth(), 1), to }
    },
  },
  {
    label: 'Year to date',
    value: () => {
      const to = new Date()
      return { from: new Date(to.getFullYear(), 0, 1), to }
    },
  },
]`.

The shortcuts a range picker is asked for on nearly every screen it appears on, so they ship rather than being rebuilt per dashboard. Computed on click: a preset list built at render time freezes "today" at whenever the page loaded, which is wrong for anything left open overnight.

## DATE_PRESETS

Re-export of `[
  { label: 'Today', value: () => new Date() },
  {
    label: 'Tomorrow',
    value: () => {
      const date = new Date()
      date.setDate(date.getDate() + 1)
      return date
    },
  },
  {
    label: 'In a week',
    value: () => {
      const date = new Date()
      date.setDate(date.getDate() + 7)
      return date
    },
  },
  {
    label: 'In a month',
    value: () => {
      const date = new Date()
      date.setMonth(date.getMonth() + 1)
      return date
    },
  },
]`.

The single-date equivalent.

## DatePicker

A date, chosen from a calendar. A trigger and a `Calendar` in a `Popover` — not a new component so much as the composition people otherwise assemble slightly differently on every screen. It is deliberately NOT a text input with a calendar attached. A typed date needs parsing, and parsing needs a format, and a format is a locale argument nobody wins. When typing genuinely matters — a birth date, a long way back — the calendar's month and year are dropdowns, which is the same journey without the ambiguity.

### Props

- `value` — `Date`.
- `defaultValue` — `Date`.
- `onValueChange` — `(value: Date | undefined) => void`.
- `label` (required) — `string`. Names the control. Required — the trigger's text is a value, not a label. Announced together with the printed date rather than instead of it, so `format` reaches a screen reader as well as the screen. Inside a `Field` with a label, that label names the trigger and this one is not repeated.
- `placeholder` — `string` default `'Pick a date'`.
- `disabled` — `boolean` default `false`.
- `disabledDates` — `ComponentProps<typeof Calendar>['disabled']`. Days the reader may not choose. Reaches the calendar AND the shortcut rail: a preset landing on a blocked day is drawn unavailable and refuses the click, rather than committing a value the grid beside it would not accept.
- `format` — `(date: Date) => string` default `formatDate`. How the chosen date is printed on the trigger.
- `presets` — `boolean | DatePreset<Date>[]`. Shortcuts shown beside the grid. Pass `true` for the built-in set, an array for your own, or leave it off for none.
- `className` — `string`.
- `id` — `string`. The TRIGGER's id — the element a label points at. A `Field` sets it.
- `aria-describedby` — `string`. Ids of the copy describing the control. A `Field` sets it from hint, error and description.
- `aria-invalid` — `boolean | 'true' | 'false'`. Announced on the trigger. A `Field` sets it from `error`.

## DateRangePicker

A span of dates — a stay, a reporting period, a filter. Two months side by side, because a range that crosses a month boundary is the common case, and paging back and forth to see both ends is what makes a range picker tiring. They stack under `sm`, where two would not fit — the calendar's own `months` class already carries that, so there is nothing to override. The panel stays open until both ends are chosen: a range is not a value until it has a second date, and closing on the first one would mean re-opening to finish.

### Props

- `value` — `DateRange`.
- `defaultValue` — `DateRange`.
- `onValueChange` — `(value: DateRange | undefined) => void`.
- `label` (required) — `string`. Names the control. Announced together with the printed range, not instead of it.
- `placeholder` — `string` default `'Pick a range'`.
- `disabled` — `boolean` default `false`.
- `disabledDates` — `ComponentProps<typeof Calendar>['disabled']`. Days the reader may not choose. Reaches the shortcut rail as well as the grid, at the ENDS of each preset range — a shortcut whose interior straddles a blocked day is still offered, the way the grid still lets a reader drag a range across one.
- `months` — `number` default `2`. How many months are shown side by side. Falls back to one under `sm`.
- `format` — `(date: Date) => string` default `formatDate`.
- `presets` — `boolean | DatePreset<DateRange>[]` default `true`. Shortcuts shown beside the grid — Last 30 days and its neighbours. `true` for the built-in set, an array for your own. On by default here and off on the single picker, because "last 30 days" is most of what a range picker is ever asked for, while a single date is usually a specific one.
- `className` — `string`.
- `id` — `string`. The TRIGGER's id — the element a label points at. A `Field` sets it.
- `aria-describedby` — `string`. Ids of the copy describing the control. A `Field` sets it from hint, error and description.
- `aria-invalid` — `boolean | 'true' | 'false'`. Announced on the trigger. A `Field` sets it from `error`.

## Example — default

```tsx
import { DatePicker, Field } from '@misoto22/design'

<Field
  label="Publish on"
  hint="Month and year are dropdowns — reaching two years back is one click, not twenty-four."
  className="w-full max-w-xs"
>
  <DatePicker label="Publish on" />
</Field>
```

## Example — range

```tsx
import { DateRangePicker, Field } from '@misoto22/design'

<Field
  label="Reporting period"
  hint="Last 30 days and its neighbours are one click; the grid is for everything else."
  className="w-full max-w-sm"
>
  <DateRangePicker label="Reporting period" />
</Field>
```

## Example — presets

```tsx
import { DatePicker, Field } from '@misoto22/design'

<Field
  label="Remind me on"
  hint="Shortcuts are computed when clicked, so “today” means today even on a tab left open overnight."
  className="w-full max-w-xs"
>
  <DatePicker label="Remind me on" presets />
</Field>
```

## Example — blocked dates

```tsx
import { DatePicker, Field } from '@misoto22/design'

<Field
  label="Site visit"
  hint="Weekdays only, and not in the past."
  className="w-full max-w-xs"
>
  <DatePicker label="Site visit" disabledDates={[{ before: TODAY }, { dayOfWeek: [0, 6] }]} />
</Field>
```

# ColorPicker

A colour, chosen or typed.

- Group: Forms
- Import: `import { ColorPicker } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/color-picker/
- Related: field, input, popover

## When to reach for it

A person is choosing the colour. A colour that is merely being SHOWN is a swatch, and a set of fixed brand colours is a RadioGroup — a picker offers sixteen million answers to a question with six.

## Anatomy

- **Trigger** (required) — The closed control: a swatch, then the value as text, in the same box as Input and Select. Named by its label AND by its own value, so a reader hears “Brand colour, #a78bfa” rather than either half.
- **Swatch** — The colour over a checkerboard, so a half-transparent value reads as transparent rather than as a paler colour.
- **Notation strip** — Hex, OKLCH and Display P3, as a single-value ToggleGroup. It changes what onValueChange emits, not what the colour is — and hex and P3 are bounded, so switching to one of them fits the colour to that gamut on the way out.
- **Field** (required) — The plane: chroma across, lightness up. Each ROW is normalised to the most chroma that exists at that lightness and hue, so the whole surface is reachable instead of a lens of colour inside bands of clipped duplicates. Underneath it are two real sliders rather than key handlers on a canvas, which is what gives it arrows, Home, End and an announced position.
- **Hue track** — A ramp taken at the lightness and chroma already chosen, not a generic rainbow — so the strip shows the hues of THIS colour rather than of some other one.
- **Opacity track** — Transparent to the current colour, over the same checkerboard as the swatch.
- **CSS box** — The value as text. Accepts hex, rgb(), hsl(), oklch() and color(display-p3 …) in both syntaxes, and paints itself invalid on anything else.

## Best practices

### Do

- Wrap it in a Field. The trigger is a button, which a label binds to and clicks through — one of the few composites where that works without help.
- Pass the notation you want back. The panel emits in whatever notation the value arrived in until somebody changes it in the strip, so a defaultValue of "#a78bfa" keeps a consumer in hex.
- Reach for this over <input type="color"> when the colours are being TUNED. The native picker works in HSV, where a row of constant lightness visibly darkens as it saturates — so a reader building a palette is fighting the instrument. OKLCH is the space where two colours at the same height genuinely match.

### Don’t

- Do not pass a named colour. Hex, rgb(), hsl(), oklch() and color(display-p3 …) parse; "rebeccapurple" does not, and the box will show it as invalid. Resolving names needs a table of every CSS keyword or a live DOM, and a picker that takes some names and not others is worse than one that takes none.
- Do not read the emitted string as a fixed notation. It is whatever the strip is set to, so a consumer that slices a "#" off the front breaks the first time a reader picks OKLCH.
- Do not use it to pick text or background colour and call the result accessible. Nothing here measures contrast; a picker that lets a reader choose #eeeeee for body copy is doing exactly what it was asked.

## Accessibility

- label is required. The trigger shows a value, and a value is not a name.
- The plane is a group of two real sliders — Chroma and Lightness — each announced with a percentage, so the 2D surface is operable and reported rather than merely clickable.
- The focus ring is drawn on the plane, because the sliders that take the focus are visually hidden and the browser’s own ring is clipped away with them.
- Alpha is doubled by a checkerboard everywhere it is shown, so transparency is not carried by lightness alone.

## Keyboard

- Enter / Space — Opens the panel.
- ← / → — Moves the focused axis or track by one step.
- Home / End — Jumps that axis or track to its ends.
- Escape — Closes the panel; focus returns to the trigger.

## ColorPicker

A colour, chosen or typed. The panel works in OKLCH, and that is the reason to reach for this rather than `<input type="color">`. In HSV — which is what the native picker and most libraries use — dragging along a row of constant "lightness" walks through colours the eye reads as getting darker, so a reader tuning a palette is fighting the instrument. OKLCH's lightness is the one a person sees, so two colours at the same height on the plane genuinely match, and the hue strip stays at the lightness already chosen instead of showing a rainbow that belongs to some other colour. The plane is normalised to the gamut ROW BY ROW: its right edge is the most chroma that exists at that lightness and hue, so the whole surface is reachable rather than a lens of colour inside a field of clipped duplicates. **What it accepts.** Hex, `rgb()`, `hsl()`, `oklch()` and `color(display-p3 …)`, in both syntaxes. Named colours are not accepted: resolving them needs a table of every CSS name or a live DOM, and a box that takes "rebeccapurple" but not "papayawhip" is worse than one that takes neither. **Keyboard.** The plane is a group of two real sliders — chroma across, lightness up — so the arrows move it and a screen reader announces where it is. That is the part a 2D canvas usually leaves out, and leaving it out makes the control unusable rather than merely awkward.

### Props

- `label` (required) — `string`. Names the control. Required — the trigger shows a colour, and a colour is not a name. Announced together with the value, the way `Select`'s is: a reader hears "Brand colour, #a78bfa". Inside a `Field` with a label, that label is used and this one is not repeated.
- `value` — `string`. The colour, as any absolute CSS colour string.
- `defaultValue` — `string` default `'#000000'`.
- `onValueChange` — `(value: string) => void`. Fires with a CSS colour string in whichever notation the panel is set to — so the notation a caller passes in is the notation they get back until somebody changes it in the panel.
- `disabled` — `boolean`.
- `invalid` — `boolean`. Paints the resting border with `--danger` and reflects `aria-invalid`.
- `className` — `string`.
- `id` — `string`. The TRIGGER's id — the element a label points at. A `Field` sets it.
- `aria-describedby` — `string`. Ids of the copy describing the control. A `Field` sets it from hint, error and description.
- `aria-invalid` — `boolean | 'true' | 'false'`. The spelling a form library sets; read together with `invalid`.
- `aria-required` — `boolean`. Announced on the trigger. A `Field` sets it from `required`.

## Example — default

```tsx
import { ColorPicker, Field } from '@misoto22/design'

<div className="flex w-full max-w-xs flex-col gap-5">
  <Field label="Brand colour">
    <ColorPicker label="Brand colour" defaultValue="#a78bfa" />
  </Field>
  <Field label="Accent" hint="Passed in as OKLCH, so it comes back as OKLCH.">
    <ColorPicker label="Accent" defaultValue="oklch(0.72 0.16 145)" />
  </Field>
</div>
```

# Slider

A value chosen along a range.

- Group: Forms
- Import: `import { Slider } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/slider/
- Related: progress

## Anatomy

- **Track** (required) — A 1px rule in --stone that thickens to 1.5 when the pointer is anywhere over the control, not only over the thumb.
- **Range** — The --accent fill from the minimum to the thumb, or between the two thumbs of a range.
- **Thumb** — One per entry in the value array — so the number of thumbs comes from the value, not from a prop, and a slider given neither value nor defaultValue falls back to the primitive’s own default of one thumb at the minimum. Each is a 16px circle with an invisible 44px hit area from a before pseudo-element.
- **Value readout** — Only with showValue: a mono row above the track, the names on the start edge and the formatted values on the end, each joined by an en dash and in the thumbs’ own order — so a two-ended range reads “Minimum – Maximum” over “10 – 90”.
- **Editable readout** — What editable turns those figures into: one box per thumb, showing format’s output at rest and the bare number while it has focus, so a reader still sees “$1,200” and a typist is never asked to type a currency symbol back. Each is named separately from its thumb — two controls announcing “Quality” is one control announced twice.

## Best practices

### Do

- Pass defaultValue or value whenever there is more than one end to it. The thumb count comes from that array, so a price filter left to the default is a single thumb sitting at the minimum.
- Pass an array of two names for a two-thumb range: every thumb after the first falls back to names[0], so both ends of a price filter otherwise announce themselves as “Minimum”.
- Turn on editable when the exact number matters. A slider on its own cannot be typed into, and someone who needs 37 rather than roughly 40 is dragging a 16px thumb across a hundred steps to get it — the box in the readout is the way out, and it replaces the second Input this used to ask for.

### Don’t

- format becomes each thumb’s aria-valuetext, which REPLACES the number rather than decorating it — so a formatter that rounds hard or drops the unit is what a screen reader gets instead of the value.
- editable typing is bounded by the NEIGHBOURING thumb as well as by min and max, and it has to be: 90 typed into the lower end of a range sitting at 70 would otherwise cross the two thumbs over. So a number can be accepted and then land somewhere else, and the box shows where it landed.
- Do not disable a slider to make it read-only: the whole control dims and stops taking the pointer, and Radix drops the thumb out of the tab order, so the value becomes unreachable rather than uneditable.
- Do not pass two names to a one-thumb slider: the heading prints one name per THUMB, so the second is drawn nowhere and announced nowhere.
- A Field’s label above it does not name it and does not click through: the role is on the THUMB and the root is a <span>, so the label prop here is the only name a reader hears. The hint and the error do reach the thumb.

## Accessibility

- label is required. A thumb that announces "42" and nothing else leaves a screen reader user with a number and no idea what it measures.
- A 44px hit area sits invisibly around the 16px thumb.
- format is announced as aria-valuetext, so a thumb showing “$1,200” says that rather than 1200.
- Arrows step, Page keys jump, Home and End reach the ends.

## Keyboard

- ← / → — Moves by one step.
- Page Up / Page Down — Moves by a larger step.
- Home / End — Jumps to the minimum or maximum.

## Slider

A value chosen along a range. Radix owns the keyboard contract — arrows step, Page keys jump, Home and End reach the ends — and the ARIA that reports the value. What is here is the look, and the labelling, which is the part a slider most often gets wrong: a thumb that announces "42" and nothing else leaves a screen reader user with a number and no idea what it measures. A 44px hit area sits invisibly around the 16px thumb, because a thumb sized for the design is well under any pointer-target guideline. `editable` is the answer to the thing a slider cannot do. Reach for it whenever the exact figure is the point — a budget, a timeout, a price — and leave it off when the value is genuinely approximate, because a box invites precision the setting may not have. Inside a `Field`, the hint, the error and the requirement land on the THUMB, which is the element carrying `role="slider"` — on the root they would sit on a `<span>` with no role and announce nothing. The NAME still comes from `label` here: a field's label above a slider points at that same roleless root, so it neither names the control nor clicks through to it.

### Props

- `label` (required) — `string | [string, string]`. Names the control. Required: a slider with no name announces only a number, and a number with no noun is not information. A range slider (two thumbs) needs one name per thumb — pass an array.
- `showValue` — `boolean` default `false`. Prints the current value beside the label. A two-thumb range prints both names and both values, in the same order — the heading used to print the first name over a pair of numbers, which read as "Minimum" over "10 – 90".
- `editable` — `boolean` default `false`. Turns that readout into a box the number can be typed into, and implies `showValue`. A slider is a control for a NEIGHBOURHOOD; someone who needs 1,150 rather than roughly 1,200 is dragging a 16px thumb across a hundred steps to get it. This is the way out, in the place the value already is, rather than a second field beside the track that has to be kept in step by hand. The box shows `format`'s output at rest and the bare number while it has focus, so a reader still sees "$1,200" and a typist is never asked to type a currency symbol back.
- `format` — `(value: number) => string`. Renders the value with a unit or a currency, e.g. `(n) => n + '%'`. Reaches assistive tech as well as the readout: it becomes each thumb's `aria-valuetext`, so a thumb showing "$1,200" announces that rather than the bare number. Left off, the platform announces the value itself.

Also accepts: `ComponentProps<typeof SliderPrimitive.Root>`.

## Example — default

```tsx
import { Slider } from '@misoto22/design'

<div className="flex w-full max-w-sm flex-col gap-8">
  <Slider label="Quality" defaultValue={[80]} max={100} step={5} showValue format={(n) => `${n}%`} />
  <Slider
    label={['Minimum price', 'Maximum price']}
    defaultValue={[20, 70]}
    max={100}
    step={5}
    showValue
    format={(n) => `$${n}`}
  />
</div>
```

## Example — typing the exact value

```tsx
import { Slider } from '@misoto22/design'

<div className="flex w-full max-w-sm flex-col gap-8">
  <Slider
    label="Monthly budget"
    defaultValue={[1200]}
    max={5000}
    step={50}
    editable
    format={(n) => `$${n}`}
  />
  <Slider
    label={['Minimum price', 'Maximum price']}
    defaultValue={[20, 70]}
    max={100}
    step={5}
    editable
    format={(n) => `$${n}`}
  />
</div>
```

## Example — naming the unit

```tsx
import { Slider } from '@misoto22/design'

<div className="flex w-full max-w-sm flex-col gap-8">
  <Slider
    label="Request timeout in seconds"
    defaultValue={[12]}
    min={1}
    max={60}
    showValue
    format={(n) => `${n}s`}
  />
  <Slider label="Retries before giving up" defaultValue={[3]} max={10} showValue />
</div>
```

# ToggleGroup

A segmented control: several options, one strip.

- Group: Forms
- Import: `import { ToggleGroup } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/toggle-group/
- Related: tabs, radio-group

## When to reach for it

It changes a VALUE. Something that switches panels is Tabs.

## Anatomy

- **Strip** (required) — The bordered pill holding the segments, w-fit as well as inline-flex — without it a flex or grid parent stretches the strip to the widest sibling and leaves dead space after the last segment.
- **Travelling pill** — The --accent block behind the selection, on single-value groups only and only once it has measured a selected segment. It moves rather than cross-fading, so the eye follows one thing.
- **Segment** (required) — A button at --control-h-sm. In a single group it changes ink only and lets the pill behind it do the filling; in a multiple group it fills itself, because there is nothing travelling.
- **Segment content** — children, in a gap-2 row. There is no iconOnly path here the way Button has one, so an icon with no words is a segment with no name.

## Best practices

### Do

- Give a single-value group a defaultValue or a value. The pill appears only after it has measured a selected segment, so a group that starts empty is a bare strip with nothing marked in it.
- Name the strip. Inside a Field its label does it, through aria-labelledby — the root is a div, so there is nothing for htmlFor to bind to — and standing alone it needs its own aria-label, which with type="single" is what a radiogroup is announced by.
- Give an icon-only segment its own aria-label: nothing strips the text or supplies a name for you here, so a strip of three glyphs announces three unnamed buttons.

### Don’t

- type="single" has radio semantics but not radio behaviour: pressing the selected segment deselects it and commits an empty string, so a view switcher built on it can be switched off into no view at all.
- Segments are --control-h-sm — 36px comfortable, 30px under data-density="compact" — which is below the 44px pointer floor (WCAG 2.5.5). A strip meant for a thumb needs its own height.
- Do not put six options in it. The strip neither wraps nor scrolls, so past about five segments it simply runs out past its container, and that is a Select or a Combobox anyway.
- A Field’s required marks a single-value strip and leaves a multiple-value one unmarked: that one is a role="toolbar", which takes no aria-required at all, so on type="multiple" the asterisk is the whole of the marking.

## Accessibility

- type="single" gets radio semantics; type="multiple" gets independent toggles. Choosing wrong tells a screen reader that picking one option unpicks the others.

## Keyboard

- Tab — Moves into the strip — one stop for the group.
- ← / → — Moves between segments.
- Enter / Space — Toggles the focused segment.

## ToggleGroup

A segmented control: several options, one strip. `type="single"` is a choice — Radix gives it radio semantics, and it is the right shape for a view switcher or a density setting. `type="multiple"` is a set of independent toggles, which is a different thing announced differently; choosing the wrong one is how a "filter by tag" control ends up telling a screen reader that picking one tag unpicks the others. The two look different on purpose. A single-value strip moves ONE filled pill between its options, so the eye follows a thing travelling; a multiple-value strip fills each pressed option separately, because there is no single selection to travel. Two people looking at a screenshot should be able to tell which kind they are looking at, and before this they could not. Distinct from `Tabs`, which switches PANELS and owns a tabpanel relationship. A toggle group changes a value. Inside a `Field` the strip takes its name from that label, by pointing back at it — the root is a div, and `<label for>` does not bind to one, so the words above it do not click through. Standing alone it still needs its own `aria-label`.

Also accepts: `ComponentProps<typeof ToggleGroupPrimitive.Root>`.

## ToggleGroupItem

One segment. In a single-value group the item draws no background of its own — the travelling pill behind it does — so it only changes ink. In a multiple-value group it fills, because there is nothing travelling.

Also accepts: `ComponentProps<typeof ToggleGroupPrimitive.Item>`.

## Example — default

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'

<div className="flex flex-col gap-8">
  <div className="flex flex-col gap-2">
    <p className="m-0 eyebrow text-(--ink-3-aa)">single — one of these</p>
    <ToggleGroup type="single" defaultValue="grid" aria-label="Layout">
      <ToggleGroupItem value="grid">Grid</ToggleGroupItem>
      <ToggleGroupItem value="list">List</ToggleGroupItem>
      <ToggleGroupItem value="map">Map</ToggleGroupItem>
    </ToggleGroup>
  </div>

  <div className="flex flex-col gap-2">
    <p className="m-0 eyebrow text-(--ink-3-aa)">multiple — any of these</p>
    <ToggleGroup type="multiple" defaultValue={['film']} aria-label="Formats">
      <ToggleGroupItem value="film">Film</ToggleGroupItem>
      <ToggleGroupItem value="digital">Digital</ToggleGroupItem>
      <ToggleGroupItem value="scan">Scan</ToggleGroupItem>
    </ToggleGroup>
  </div>
</div>
```

## Example — icon only

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'

<ToggleGroup type="single" defaultValue="start" aria-label="Text alignment">
  {ALIGNMENTS.map(({ value, label, icon: Icon }) => (
    <ToggleGroupItem key={value} value={value} aria-label={label} className="px-2.5">
      <Icon size={16} aria-hidden />
    </ToggleGroupItem>
  ))}
</ToggleGroup>
```

## Example — never switched off

```tsx
import { Text, ToggleGroup, ToggleGroupItem } from '@misoto22/design'

<div className="flex flex-col gap-3">
  <ToggleGroup
    type="single"
    value={view}
    onValueChange={(next) => {
      if (next) setView(next)
    }}
    aria-label="Layout"
  >
    <ToggleGroupItem value="grid">Grid</ToggleGroupItem>
    <ToggleGroupItem value="list">List</ToggleGroupItem>
    <ToggleGroupItem value="map">Map</ToggleGroupItem>
  </ToggleGroup>
  <Text size="sm" tone="muted">
    Showing the {view} view.
  </Text>
</div>
```

# Tabs

One strip, several panels.

- Group: Navigation
- Import: `import { Tabs } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/tabs/
- Related: accordion

## Anatomy

- **Root** (required) — Tabs — Radix’s root, re-exported. It draws nothing and owns everything: value or defaultValue, and activationMode. With neither value nor defaultValue no tab is selected and no panel is mounted.
- **Tab strip** (required) — TabsList — the role="tablist" row, sitting on one hairline rule and scrolling on its own axis with scroll-slim. It has no accessible name unless you give it one.
- **Tab** (required) — TabsTrigger, at the md control height with its label on one line. Every tab carries the 2px active marker, transparent until it is the selected one; the marker is pulled onto the strip’s own border with -mb-px so the two share a line rather than stacking into a 3px edge.
- **Panel** — TabsContent, paired to its tab by matching value. Mounted only while it is the selected one, and marked data-m22-animated so its entrance is dropped for a reader who asked for less motion.

## Best practices

### Do

- Give the root a defaultValue or a value: with neither, nothing matches, every panel stays unmounted, and the page renders a strip above an empty space with nothing to say what is missing.
- Match each trigger’s value to a panel’s value exactly — the pairing is string equality, and a typo is not an error but a tab that opens onto nothing.
- Pass activationMode="manual" when a panel fetches or renders something expensive: the default is automatic, so ← and → select as they move and arrowing across four tabs starts four loads before the reader has stopped.
- Give TabsList an aria-label on a page with more than one set: Radix names the tablist after nothing, and two unnamed tablists are two “tab list”s a reader cannot tell apart.

### Don’t

- An unselected panel is unmounted, not hidden — find-in-page cannot reach its text, a print takes only the panel that was open, and a half-filled form in another tab has lost what was typed into it by the time the reader comes back.
- The selected tab lives in React state, not in the URL: a reader who reloads or shares the page lands on the first panel, so anything worth linking to needs value lifted into a query parameter.
- Tabs are not a way to fit more in: the strip scrolls silently, and a sixth tab past the fold looks exactly like a page that only has five.

## Accessibility

- The strip scrolls rather than wrapping: a wrapped second row moves every tab below it and the reader loses the one they were about to click.
- 44px tall, because a tab is a pointer target like any other.

## Keyboard

- Tab — Moves into the strip, and out of it — the whole strip is one stop.
- ← / → — Moves between tabs and switches the panel with them.
- Home / End — Jumps to the first or last tab.

## Tabs

Accessible tabs with a moving marker and optional horizontal drag gestures.

## TabsList

The tab strip. Scrolls horizontally rather than wrapping. A wrapped second row of tabs moves every tab below it when the strip grows, and the reader loses the one they were about to click.

## TabsTrigger

One tab. The active marker is a 2px ink rule pulled onto the strip's own border with `-mb-px`, so the two occupy the same line instead of stacking into a 3px edge. 44px tall, because a tab is a pointer target like any other.

## TabsContent

The panel paired to a TabsTrigger by matching `value`.

## Example — default

```tsx
import { Tabs, TabsContent, TabsList, TabsTrigger } from '@misoto22/design'

<Tabs defaultValue="preview" className="w-full">
  <TabsList>
    <TabsTrigger value="preview">Preview</TabsTrigger>
    <TabsTrigger value="code">Code</TabsTrigger>
    <TabsTrigger value="props">Props</TabsTrigger>
  </TabsList>
  <TabsContent value="preview" className="text-sm text-(--ink-2)">The rendered component.</TabsContent>
  <TabsContent value="code" className="text-sm text-(--ink-2)">The source that produced it.</TabsContent>
  <TabsContent value="props" className="text-sm text-(--ink-2)">Its parsed prop table.</TabsContent>
</Tabs>
```

## Example — manual activation

```tsx
import { Tabs, TabsContent, TabsList, TabsTrigger, Text } from '@misoto22/design'

<Tabs defaultValue="traffic" activationMode="manual" className="w-full">
  <TabsList aria-label="Site metrics">
    <TabsTrigger value="traffic">Traffic</TabsTrigger>
    <TabsTrigger value="referrers">Referrers</TabsTrigger>
    <TabsTrigger value="errors">Errors</TabsTrigger>
  </TabsList>
  <TabsContent value="traffic">
    <Text size="sm">18,402 visits over the last 30 days, up 6% on the month before.</Text>
  </TabsContent>
  <TabsContent value="referrers">
    <Text size="sm">news.ycombinator.com sent 4,110 of them; nothing else broke 500.</Text>
  </TabsContent>
  <TabsContent value="errors">
    <Text size="sm">Eleven 500s, all from the same deploy, all before 09:14.</Text>
  </TabsContent>
</Tabs>
```

## Example — what gets hidden

```tsx
<div className="grid w-full gap-8 lg:grid-cols-3">
  <div className="flex flex-col gap-3">
    <Text size="xs" tone="muted">
      Tabs — one of several views
    </Text>
    <Tabs defaultValue="usd">
      <TabsList aria-label="Currency">
        <TabsTrigger value="usd">USD</TabsTrigger>
        <TabsTrigger value="aud">AUD</TabsTrigger>
      </TabsList>
      <TabsContent value="usd">
        <Text size="sm">Billed at $18 a seat each month.</Text>
      </TabsContent>
      <TabsContent value="aud">
        <Text size="sm">Billed at A$28 a seat each month.</Text>
      </TabsContent>
    </Tabs>
  </div>
  <div className="flex flex-col gap-3">
    <Text size="xs" tone="muted">
      Accordion — a set of answers
    </Text>
    <Accordion type="single" collapsible>
      <AccordionItem value="usd" title="What does a seat cost?">
        Billed at $18 a seat each month.
      </AccordionItem>
      <AccordionItem value="cancel" title="Can I cancel mid-month?">
        Yes, and the remainder is refunded.
      </AccordionItem>
    </Accordion>
  </div>
  <div className="flex flex-col gap-3">
    <Text size="xs" tone="muted">
      Collapsible — detail on one thing
    </Text>
    <div className="border-y border-(--rule)">
      <CollapsibleSection title="Billing detail">
        Billed at $18 a seat each month, on the day you first subscribed.
      </CollapsibleSection>
    </div>
  </div>
</div>
```

# Accordion

Disclosure rows that open in place.

- Group: Navigation
- Import: `import { Accordion } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/accordion/
- Related: tabs

## When to reach for it

The marker is a plus, not a chevron: a plus says “this opens”, a chevron says “there is more below”.

## Anatomy

- **Row** (required) — AccordionItem — one hairline-ruled record, keyed by the value Radix opens and closes it by. The set is the root above it: type="single" with collapsible for an FAQ, type="multiple" for a stack of settings.
- **Heading** (required) — Radix’s Accordion.Header, which is an <h3> and takes no level prop. Every row therefore adds an h3 to the document outline, wherever the accordion happens to sit.
- **Trigger** (required) — The full-width button inside that heading: title against the start edge, marker against the end, py-4. It is also what names the open panel.
- **Marker** (required) — A 16px plus, aria-hidden, rotating 45° into a minus when the row opens. The state it draws is carried for everyone else by aria-expanded on the trigger.
- **Panel** — Radix’s Content — a role="region" labelled by its trigger, mounted only while open, overflow-hidden so its measured height can animate, with pb-4 pe-8 inside so the text stops short of the marker’s column. It carries data-m22-animated, so the open and close are dropped outright for a reader who asked for less motion.

## Best practices

### Do

- Pass collapsible alongside type="single": without it there is no empty value to return to, so the first row the reader opens is a row they can never close again.
- Key each item by something stable rather than by its position — Radix tracks the open row by value, so re-ordering or filtering the list leaves whatever now sits in that slot standing open.
- Write the title as the whole question: it is the accessible name of the panel as well as of the trigger, so a row titled “More” opens a region called “More”.
- Reach for type="multiple" when two rows have to be read against each other — single closes the one the reader was holding in order to open the one they wanted to compare it with.

### Don’t

- A closed row’s content is not in the DOM, so an FAQ built out of these is invisible to find-in-page and prints as a list of questions — anything that has to be searchable or printable belongs in the page.
- The trigger is fixed at h3 by Radix’s header, so an accordion under an <h3> lists its rows as that heading’s siblings and the outline goes flat exactly where it should have nested.
- The panel is overflow-hidden — that is what lets the open height animate — so anything inside that must escape the row’s box has to portal out of it; a menu that renders in place is cut off at the row’s edge.

## Keyboard

- Tab — Moves between rows.
- Enter / Space — Opens or closes the focused row.

## Accordion

Re-export of `AccordionPrimitive.Root`.

Radix root, re-exported. Pass `type="single" collapsible` for an FAQ and `type="multiple"` for a settings stack; Radix's own discriminated union then types `value` correctly for each.

## AccordionItem

One disclosure row: a hairline-ruled trigger and its panel. The marker is a plus that rotates into a minus, not a chevron. A chevron says "there is more below"; a plus says "this opens" — and in a stack of rows the difference decides whether the reader expects navigation or expansion. The panel animates on Radix's own `--radix-accordion-content-height`, so it opens to its real height without measuring anything at the call site.

### Props

- `title` (required) — `ReactNode`. The row's summary — what the reader clicks. Named `title` rather than inherited from the DOM attribute of the same name, which is a tooltip.
- `children` (required) — `ReactNode`.

Also accepts: `Omit<ComponentProps<typeof AccordionPrimitive.Item>, 'children' | 'title'>`.

## Example — default

```tsx
import { Accordion, AccordionItem } from '@misoto22/design'

<Accordion type="single" collapsible className="w-full">
  <AccordionItem value="install" title="How do I install it?">
    <code className="font-mono text-xs">pnpm add @misoto22/design</code>, then import the stylesheet once
    at your app root.
  </AccordionItem>
  <AccordionItem value="tailwind" title="Do I need Tailwind?">
    No. The compiled stylesheet is self-contained. If you already compile Tailwind, import the token
    layers instead and skip the second copy of the utilities.
  </AccordionItem>
  <AccordionItem value="router" title="Which router does it assume?">
    None. Components that navigate take <code className="font-mono text-xs">asChild</code>, so you hand
    them your own Link.
  </AccordionItem>
</Accordion>
```

## Example — a settings stack

```tsx
import { Accordion, AccordionItem, Field, Input, Switch } from '@misoto22/design'

<Accordion type="multiple" defaultValue={['retries']} className="w-full max-w-md">
  <AccordionItem value="retries" title="Retries">
    <Field label="Attempts" hint="How many times a failed job is tried again.">
      <Input type="number" defaultValue={3} />
    </Field>
  </AccordionItem>
  <AccordionItem value="notifications" title="Notifications">
    <Field
      layout="row"
      label="Email me when a job fails"
      description="One message per failure, not per attempt."
    >
      <Switch defaultChecked />
    </Field>
  </AccordionItem>
</Accordion>
```

## Example — the whole question

```tsx
import { Accordion, AccordionItem, Text } from '@misoto22/design'

<div className="grid w-full gap-8 sm:grid-cols-2">
  <div className="flex flex-col gap-3">
    <Text size="xs" tone="muted">
      Opens a region called More
    </Text>
    <Accordion type="single" collapsible>
      <AccordionItem value="a" title="More">
        Invoices are issued on the first working day of the month.
      </AccordionItem>
      <AccordionItem value="b" title="Details">
        Payment is due 30 days after the issue date.
      </AccordionItem>
    </Accordion>
  </div>
  <div className="flex flex-col gap-3">
    <Text size="xs" tone="muted">
      Opens a region called by its question
    </Text>
    <Accordion type="single" collapsible>
      <AccordionItem value="a" title="When are invoices issued?">
        Invoices are issued on the first working day of the month.
      </AccordionItem>
      <AccordionItem value="b" title="When is payment due?">
        Payment is due 30 days after the issue date.
      </AccordionItem>
    </Accordion>
  </div>
</div>
```

# Breadcrumb

Where you are, as a path.

- Group: Navigation
- Import: `import { Breadcrumb } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/breadcrumb/
- Related: pagination

## Anatomy

- **Trail** (required) — A <nav> named by label, which defaults to “Breadcrumb”. It is a landmark whether or not the page wanted another one, set in mono-meta at --ink-3-aa.
- **List** (required) — An <ol> — the order is the hierarchy, not the reader’s history. It wraps rather than truncating, so a deep path takes a second line instead of losing a level.
- **Crumb link** — An <a> for every item that has an href and is not the last. The label is a ReactNode, so whatever you put in it becomes part of the link’s accessible name.
- **Current crumb** (required) — The last item, always: plain text at full --ink with aria-current="page", whether or not it was given an href.
- **Separator** — A slash by default, in its own <li aria-hidden> between crumbs. Decorative by construction — it is never part of what is read out.

## Best practices

### Do

- Pass label when a page can hold two trails: both nav landmarks are named “Breadcrumb” otherwise, and two landmarks with one name are two entries a reader cannot choose between.
- Give every crumb but the last an href — one without renders as plain text in the same colour as the links beside it, with no destination and no aria-current, so it reads as the page the reader is on when it is not. Development names the crumb rather than leaving an omission that is invisible in the browser and in review.
- Start the trail above the current page: a one-item Breadcrumb renders that item as the current crumb with no path at all, which is a landmark announcing a journey of length one.

### Don’t

- Leave the href off the last item rather than passing one it ignores: the last crumb is text whatever you hand it, so an href there reads as a link in review and is not one at run time.
- Do not hide it on a phone to save a line. That is the layout where the sidebar is behind a drawer, which makes the trail the only way up a level that is on the screen.

## Accessibility

- The last crumb is text with aria-current="page", never a link to itself.
- Separators are aria-hidden, so the trail is not read as “home slash work slash”.
- A middle crumb with no href takes no aria-current and no colour of its own, which is why the omission is reported in development instead of shipped as a crumb that impersonates the current page.

## Breadcrumb

Where you are, as a path. The last crumb is plain text with `aria-current="page"` rather than a link to itself — a self-link is the most common breadcrumb bug, and it makes a screen reader offer a navigation that goes nowhere. Separators live in `<li aria-hidden>` so the trail is read as its items and not as "home slash work slash". A middle crumb with no `href` is a defect that is invisible twice over: it renders as plain text in the same `--ink-3-aa` as the links beside it, and it carries no `aria-current` either — so it reads as the page the reader is on when it is not, and neither the browser nor a review says a word. The console does, in development.

### Props

- `items` (required) — `Crumb[]`.
- `label` — `string` default `'Breadcrumb'`. Names this trail when a page has more than one.
- `separator` — `ReactNode` default `'/'`. Rendered between crumbs. A slash by default; it is decorative either way.

Also accepts: `HTMLAttributes<HTMLElement>`.

## Example — default

```tsx
import { Breadcrumb } from '@misoto22/design'

// Named, because the page that documents this component has a breadcrumb
// of its own and two landmarks with one name cannot be told apart.
<Breadcrumb
  label="Example trail"
  items={[
    { label: 'Home', href: '/' },
    { label: 'Components', href: '/components' },
    { label: 'Breadcrumb' },
  ]}
/>
```

## Example — a deep path

```tsx
import { Breadcrumb } from '@misoto22/design'

<Breadcrumb
  label="Deep trail"
  separator="›"
  className="max-w-xs"
  items={[
    { label: 'Workspace', href: '/' },
    { label: 'Clients', href: '/clients' },
    { label: 'Northwind', href: '/clients/northwind' },
    { label: 'Invoices', href: '/clients/northwind/invoices' },
    { label: '2024-118' },
  ]}
/>
```

## Example — page header

```tsx
import { Breadcrumb, Heading, Text } from '@misoto22/design'

<div className="flex w-full flex-col gap-4">
  <Breadcrumb
    label="Invoice trail"
    items={[
      { label: 'Clients', href: '/clients' },
      { label: 'Northwind', href: '/clients/northwind' },
      { label: 'Invoice 2024-118' },
    ]}
  />
  <Heading level={2}>Invoice 2024-118</Heading>
  <Text size="sm" tone="muted">
    Issued 4 March, due 3 April. Unpaid.
  </Text>
</div>
```

# Pagination

Numbered pages, with the middle elided.

- Group: Navigation
- Import: `import { Pagination } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/pagination/
- Related: breadcrumb

## Anatomy

- **Nav** (required) — A <nav> named by label, “Pagination” by default. Nothing else here is a landmark, so this is how a reader jumps to the pager rather than scrolling to it.
- **Step buttons** (required) — Previous and Next, pill-cornered at --control-h-sm, named by previousLabel and nextLabel — “Previous page” and “Next page” until a call site says otherwise. Each is disabled at its end of the range, which takes it out of the tab order rather than leaving a control that does nothing.
- **Page list** (required) — An <ol> of numbers, each a <button> named by pageLabel — “Page N” by default — and carrying aria-current on the one you are on.
- **Travelling pill** — One aria-hidden fill, measured from the selected button and moved with a transform rather than two grounds cross-fading. It is absent until the first measurement lands, and holds still under prefers-reduced-motion.
- **Ellipsis** — An aria-hidden <li> wherever the sequence skips more than one page. A single skipped page is printed instead — “1 … 3” is longer than “1 2 3” and says less.

## Best practices

### Do

- Move page in the same state update that fetches: it is fully controlled, so a handler that loads the next page without setting page leaves the pager marking the page the reader just left.
- Raise siblings rather than lowering it — below 2 × siblings + 5 pages every page is printed anyway, so the prop does nothing on a short list and is the only lever you have on a long one.
- Import paginationRange when something else has to agree with the pager: it is exported and pure, which is how a server-rendered summary and this component end up describing one window instead of two.
- Let the surrounding row collapse: the component returns null at one page or fewer, so a footer built to a fixed height shows an empty strip on the day the list gets short.

### Don’t

- Do not put it in a compact region and call it a touch target: the pills are --control-h-sm, 36px comfortable and 30px under data-density="compact", set 4px apart — well under the 44px WCAG 2.5.5 asks of a pointer target.
- Do not expect pageLabel to change what is printed. It names the control for a screen reader and nothing else; the button still shows the Western digit it was handed, so a locale that writes its numerals differently has to format them at the call site as well.

## Accessibility

- The current page is a button with aria-current, not a styled span — a reader jumping by control needs to find it.
- Renders nothing at one page. A pager for a single page is furniture.
- Every string a reader hears is a prop: the two chevrons by name, each numbered page through pageLabel — a function rather than a template, because “Page 3” is a phrase whose parts move around between languages.

## Keyboard

- Tab — Reaches every control, including the current page.
- Enter / Space — Goes to that page.

## paginationRange

Builds the visible page list: always the first and last page, a window around the current one, and an ellipsis wherever the sequence skips. Returned as numbers and a literal ellipsis rather than as pre-rendered nodes, so the shape is testable without a DOM — the off-by-one at the window edges is the whole difficulty of this component.

## Pagination

Numbered pagination. The current page is marked by one filled pill that TRAVELS between the numbers rather than by a background switching off on one and on on another. Two backgrounds cross-fading reads as two things changing; a shape moving reads as the one thing that actually did. A `<nav>` wrapping a list, and the current page is a `<button aria-current>` rather than a styled `<span>` — a reader jumping by landmark needs to find the control, and a reader on the current page needs to be told they are already there. Renders nothing at one page or fewer. A pager for a single page is furniture. Every string a reader hears is a prop. The chevrons carry no text, so `previousLabel` and `nextLabel` are the whole of those two controls' names, and `pageLabel` is a function because "Page 3" is a phrase whose parts move around between languages.

### Props

- `page` (required) — `number`. 1-based.
- `pageCount` (required) — `number`. Total pages. A value of 1 or less renders nothing.
- `onPageChange` (required) — `(page: number) => void`.
- `siblings` — `number` default `1`. How many numbered pages sit either side of the current one.
- `label` — `string` default `'Pagination'`.
- `previousLabel` — `string` default `'Previous page'`. Names the two step controls. Each is a chevron and nothing else, so these strings are its entire accessible name — the same reason `AppShell` exposes `openLabel` and `closeLabel` rather than baking them in.
- `nextLabel` — `string` default `'Next page'`.
- `pageLabel` — `(page: number) => string` default `(page) => `Page ${page}``. Names one numbered page. A function rather than a template, because the number does not sit in the same place in every language and neither does the noun around it — `"Page 3"`, `"第 3 页"`, `"Seite 3"`. The visible digit is the same either way; this is what a screen reader hears instead of a bare number.

Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'onChange'>`.

## Example — default

```tsx
import { Pagination } from '@misoto22/design'

<div className="flex flex-col items-center gap-5">
  <Pagination page={page} pageCount={20} onPageChange={setPage} />
  <p className="m-0 mono-meta text-(--ink-3-aa)">page {page} of 20</p>
</div>
```

## Example — the edges

```tsx
import { Pagination, Text } from '@misoto22/design'

<div className="flex flex-col gap-6">
  <div className="flex flex-col gap-2">
    <Text size="xs" tone="muted">
      At the first page
    </Text>
    <Pagination label="First page" page={first} pageCount={24} onPageChange={setFirst} />
  </div>
  <div className="flex flex-col gap-2">
    <Text size="xs" tone="muted">
      In the middle, elided on both sides
    </Text>
    <Pagination label="Middle pages" page={middle} pageCount={24} onPageChange={setMiddle} />
  </div>
  <div className="flex flex-col gap-2">
    <Text size="xs" tone="muted">
      At the last page
    </Text>
    <Pagination label="Last page" page={last} pageCount={24} onPageChange={setLast} />
  </div>
</div>
```

## Example — a wider window

```tsx
import { Pagination, Text } from '@misoto22/design'

<div className="flex flex-col gap-6">
  <div className="flex flex-col gap-2">
    <Text size="xs" tone="muted">
      One sibling, the default
    </Text>
    <Pagination label="Default window" page={page} pageCount={24} onPageChange={setPage} />
  </div>
  <div className="flex flex-col gap-2">
    <Text size="xs" tone="muted">
      Two siblings
    </Text>
    <Pagination
      label="Wider window"
      siblings={2}
      page={page}
      pageCount={24}
      onPageChange={setPage}
    />
  </div>
</div>
```

# Sidebar

A navigation rail down the side of an application.

- Group: Navigation
- Import: `import { Sidebar } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/sidebar/
- Related: nav-item, collapsible, app-shell

## When to reach for it

A whole application’s navigation, in a column that stays. A list of links inside a page is NavItem on its own; a strip of panels is Tabs.

## Anatomy

- **Provider** (required) — SidebarProvider. It holds whether the rail is open and binds the shortcut that changes it, and it sits ABOVE both the rail and the content beside it — the page has to reserve the rail’s width, and a state that lived inside the rail could only ever be read downwards. It also supplies the tooltip provider a collapsed rail needs, so the icon state works without the app being told to wrap itself in one.
- **Rail** (required) — Sidebar. A <nav>, not an <aside>: the element decides the landmark, and a rail of links announced as “complementary” is not the one a reader jumps to when they go looking for the navigation. Its width animates between --sidebar-w and --sidebar-w-icon while the column inside stays full width, so the rows do not reflow under the wipe.
- **Header** — SidebarHeader. The brand, the workspace, the switcher — and where SidebarTrigger belongs. A control that hides a thing lives on the thing; out in an application’s masthead it is one more anonymous icon with nothing connecting it to the column it operates.
- **Content** — SidebarContent. The scrolling middle, and the only part that scrolls.
- **Group** — SidebarGroup: a heading, an optional count, an optional action, and rows behind a hairline. The heading is the same size as its rows and outranks them by weight and one step of ink — smaller than what it contains, it reads as a footnote over a list rather than as a title over its own contents.
- **Row** — SidebarItem, which is NavItem plus the two things a rail adds: a trailing slot, and an answer for the state with no room for words. Collapsed, the label leaves the layout and becomes the row’s tooltip.
- **Branch** — SidebarBranch: a row that opens onto more rows, behind the same hairline a group draws and one indent further in. It is the line between a place and a heading — a workspace that contains projects is a place containing places, and it carries an icon and a state the way its children do, which a Group has neither of. Two levels is what the indent has room for; a third in a 16rem column is a horizontal scrollbar with an outline in it.
- **Footer** — SidebarFooter. The utilities a rail ends on, kept out of the index above it.
- **Page** — SidebarInset, the column beside the rail. It is `min-w-0` — the half every hand-written version forgets, and the reason one wide table inside pushes the page past the viewport and takes the rail’s width with it. Under variant="inset" it is also the panel: the rail becomes the ground, and this draws the bordered --paper surface sitting on it.
- **Drawer** — What the rail becomes under the provider’s breakpoint (768px by default): fixed against its own edge, over a scrim, and inert while closed. Nothing to render — the same <Sidebar> is both — but it is a different component to a reader, and the collapsible setting does not apply there.

## Best practices

### Do

- Give every row an icon if the rail collapses to icons. The icon is the whole of what a collapsed row shows, and SidebarItem keeps the label drawn on a row without one rather than leaving a blank line — which is a rail that is half collapsed.
- Choose collapsible by what the rows ARE. icon suits a fixed set a reader learns the shape of; offcanvas suits a long index nobody memorises, where a column of unrecognisable glyphs is worse than no column.
- Reach for SidebarBranch when the thing is a PLACE that contains places, and for SidebarGroup when it is a heading over a set. A group has no icon and no state because it is not somewhere you can be; a branch has both because it is.
- Put SidebarTrigger in the header. It is where the component expects it and where a reader looks for it, and it is the difference between a control that belongs to the rail and one that has wandered into the masthead.
- Wrap the page in SidebarInset rather than a hand-written flex column. It carries min-w-0, which is what stops one wide table inside the page from pushing the whole layout past the viewport, and it is the other half of variant="inset".
- Pass persist with a key when the rail is an application’s own. A reader who put the rail away did not mean “until the next page”. Only the docked state is kept: restoring an open drawer is a page that loads with its navigation over the top of itself.
- Give the provider a ground for variant="floating" and variant="inset" — bg-(--stone) on the element holding it. Both draw a --paper panel, and a panel on the same colour as the thing behind it is a border with nothing on either side of it.

### Don’t

- Do not reach for it for navigation inside a page. This is an application landmark that owns a whole edge of the window; a set of links in a column is NavItem, and putting those in a rail gives a page two navigation landmarks competing for the same reader.
- Do not pass shortcut and then bind Cmd+B yourself. Two handlers on one chord toggle twice and land back where they started, which reads as a rail that ignores its own shortcut. Pass shortcut={null} where the app owns it.
- Do not nest a branch inside a branch. The indent is sized for two levels at this width, and a third takes the words with it — what a reader gets is an outline with a horizontal scrollbar under it.
- Do not control open without onOpenChange. The trigger and the shortcut then both do nothing, and the state that looks broken is the one the caller froze.
- Do not put a transform, filter or perspective on an element wrapping the provider. The drawer is fixed, and any of those makes that ancestor its containing block — so it opens inside the wrapper instead of against the edge of the window.
- Do not build the phone drawer yourself around this. It already is one under breakpoint, with the scrim, the inert closed state and the close-on-navigate; a second one outside gives the page two drawers and one of them has no scrim.

## Accessibility

- label is required, and names the landmark. A page with two navigations in it announces two things called “navigation” unless each says which it is.
- The trigger’s name says what it will DO and aria-expanded reports what is true now, so it is never the permanently ambiguous “Toggle sidebar”.
- A collapsed row keeps its label as its accessible name, through a tooltip — an icon alone is a guess for a sighted reader and nothing at all for a screen reader.
- A collapsed group keeps its heading as the group’s name even though the words are not drawn.
- The current row carries aria-current="page", not only a darker ground.
- The closed drawer is inert, not merely translated off-screen. Off-screen it still holds focus and is still read aloud, so a shut drawer puts its whole index between the reader and the page they were on.
- The scrim is a button with a name, because tapping beside a drawer is how a drawer is closed — and a gesture that exists only for a pointer is one a keyboard cannot make.

## Keyboard

- ⌘B / Ctrl B — Opens and closes the rail.
- Enter / Space — On a group heading, folds or unfolds it.
- Tab — Moves through the rows in the order they are drawn.

## useSidebar

The rail's own state, for anything that has to answer to it. A page beside the rail needs it to reserve the right width; a control inside needs to know whether its label is being drawn. This one THROWS outside a provider, and the parts above do not, and the difference is who made the mistake. A part rendered on its own is somebody writing `<Sidebar>` to see what it looks like; a call to this hook is code asking for state that nothing is keeping, and returning a plausible default there is a layout that is wrong in one state and right in the other with nothing to say which.

## SidebarProvider

Holds whether the rail is open, and binds the shortcut that changes it. Separate from `Sidebar` itself because the answer is needed on BOTH sides of the layout: the rail draws itself from it, and the content beside the rail reserves width from it. A state that lived inside the rail could only ever be read downwards.

### Props

- `open` — `boolean`. Controlled open state. Leave off to let the provider own it.
- `defaultOpen` — `boolean` default `true`.
- `onOpenChange` — `(open: boolean) => void`.
- `collapsible` — `SidebarCollapsible` default `'icon'`. What closing does to the rail. See SidebarProps.collapsible.
- `shortcut` — `string | null` default `'b'`. The keyboard shortcut that toggles the rail, as a single letter. `b`, with the platform's own modifier, because that is what every editor and every application shell already uses for the same thing. Pass `null` to bind nothing — an app that already owns that chord should not have it taken twice, and a rail that cannot be closed does not need a shortcut for closing it.
- `side` — `SidebarSide` default `'start'`. Which edge the rail is on. Logical: `end` is the right in LTR, the left in RTL.
- `variant` — `SidebarVariant` default `'flush'`. How the rail meets the page. `flush` is a column with a hairline down its inner edge — the rail and the page are one surface divided by a line. `floating` lifts the rail off that surface as its own bordered panel with the page ground showing around it. `inset` is the same gesture the other way up: the rail sits on the page ground and `SidebarInset` draws the CONTENT as the panel. `floating` and `inset` both need a ground to sit on — put `bg-(--stone)` on the element holding the provider, or they are a panel on the same colour as the thing behind it.
- `breakpoint` — `SidebarBreakpoint | null` default `'md'`. The step below which the rail becomes a drawer over the page. A rail is a column when there is a column's worth of room and an overlay when there is not; below this the rail is `fixed`, covers the page from its own edge, and closes onto a scrim. `null` pins it as a column at every width, for a layout that is never narrow — an embedded console, a preview frame. Named, not a number: the switch is a media query in the stylesheet, and a class built from a runtime number is a class the compiler never emitted. It also puts the rail on the same four steps as the page around it.
- `persist` — `string | null` default `null`. A `localStorage` key under which the DOCKED state is remembered. A reader who put the rail away did not mean "until the next page". Only the docked state is kept: an open drawer is a thing a reader did to this screen, and restoring it on the next visit is a page that opens with its navigation over the top of itself. Read after mount, never during render — a value from storage in the first pass is a hydration mismatch, and the markup the server sent is the one the client has to agree with.
- `contained` — `boolean` default `false`. The drawer covers its nearest positioned ancestor rather than the window. For a rail inside a bounded frame — a device preview, an embedded console, an example on a documentation page. `fixed` resolves against the viewport wherever the markup sits, so without this the drawer inside a 400px preview opens across the whole page it is previewed on. Give the frame `relative`.
- `children` (required) — `ReactNode`.

## Sidebar

A navigation rail down the side of an application. A `<nav>`, not an `<aside>`. The element decides the landmark, and a rail of links announced as "complementary" is not the one a screen reader user jumps to when they go looking for the navigation. Composed rather than configured: a rail is a header, a scrolling middle and a footer, and every product wants different things in all three. What this owns is the part that is the same everywhere — the width, the edge, the scroll behaviour, and what happens when it closes. **Closing has three shapes**, and `collapsible` on the provider picks one. `icon` keeps the rail and drops the labels, which is right when the rows are a fixed set a reader learns the shape of. `offcanvas` takes the whole rail away, which is right when the rows are a long index nobody memorises. `none` is a rail that does not close. The trigger belongs INSIDE the rail — `SidebarHeader` places it — rather than out in an application's masthead. A control that hides a thing should live on the thing: in the masthead it is one more anonymous icon in a row of them, and nothing connects it to the column it operates. **Under the provider's `breakpoint` it is a drawer**, not a column: `fixed` against its own edge, over a scrim, and `inert` while closed. Merely translating it off-screen is not closed — it keeps focus and it is still read aloud, so a shut drawer puts its whole index between the reader and the page they were on. The scrim is a real button, because tapping beside a drawer is how a drawer is closed and that gesture has to exist for a keyboard too. `fixed` resolves against the viewport unless an ancestor has a `transform`, `filter` or `perspective`, which makes that ancestor the containing block instead. Do not put one on an element wrapping the provider, or the drawer opens inside it.

### Props

- `label` (required) — `string`. Names the landmark. Required: a page with two navigations in it announces two things called "navigation" unless each of them says which it is.
- `scrimLabel` — `string` default `'Close the navigation'`. What the scrim behind the open drawer announces. It is a button — tapping beside a drawer closes it, and that has to be a control a keyboard and a screen reader can reach, not a decorated `<div>`.
- `children` (required) — `ReactNode`.

Also accepts: `Omit<ComponentProps<'nav'>, 'children'>`.

## SidebarInset

The page beside the rail. Every layout built on this component was writing the same `flex min-w-0 flex-1 flex-col` by hand, and `min-w-0` is the half everybody forgets: a flex child's floor is its content, so one wide table inside pushes the whole page past the viewport and takes the rail's width with it. It is also the other half of `variant="inset"`. There the rail is the ground and this is the panel — a bordered `--paper` surface with the ground showing around it — which is why the variant lives on the provider rather than on either piece: one setting, two components, and no way to set half of it. A `<div>`, not a `<main>`. What goes in here is usually a masthead AND the page under it, and only one of those is the main landmark.

## SidebarHeader

The block at the top of the rail: a brand, a workspace, a switcher. It is also where `SidebarTrigger` belongs, and the layout assumes one: anything passed as `children` takes the space and the trigger sits at the inline end of the row. `--bar-h` is the floor, not a number of its own. This block and the masthead beside it meet at a corner, and their two bottom rules are read as one line — so a floor typed here is a floor that has to be retyped there, and the two were 56px and 64px for exactly that reason. The token also survives a rail that pins its own density: `--bar-h` is declared on the root, so its `var(--control-h-md)` resolves there and inherits as one answer, which is what keeps a compact rail's head level with a comfortable page's bar.

## SidebarContent

The scrolling middle. Everything that is a list of places goes here.

## SidebarFooter

The block at the bottom: the utilities, the account, the thing a rail ends on. A separate landmark from the content above it because it is a separate kind of thing — a reader scanning the index does not want Trash and Help in it.

## SidebarSeparator

A rule between blocks of rows, inset to the rail's own padding.

## SidebarTrigger

The control that opens and closes the rail. Its accessible name changes with what it will DO, and `aria-expanded` reports what is true now — a button permanently called "Toggle sidebar" tells a screen reader user nothing about which way it will go.

### Props

- `labels` — `{ open: string; close: string }` default `{ open: 'Open the sidebar', close: 'Close the sidebar' }`. What the button announces. Both states, because it says both things.

Also accepts: `ComponentProps<'button'>`.

## SidebarGroup

A labelled block of rows, optionally foldable. The heading is the same SIZE as the rows beneath it and outranks them by weight and by ink. Both halves of that are corrections. Smaller, it inverted the hierarchy it exists to express — a group read as a footnote over a list rather than as a title over its own contents. In the MONO face, which is where it went next, ten of them stacked in a column read as a terminal listing: mono is this system's voice for code, metadata and figures, and a navigation heading is none of those. Rank belongs to weight and to a step up the ink ladder, which are the two signals that can outrank a row without changing what kind of thing it is. An open group draws a hairline down its rows. Fifty rows under seven headings have nothing in them saying which heading any given row belongs to — only the distance to the last one, which is gone the moment the list is scrolled. The whole block hides when the rail is collapsed to icons: a heading with no room for its own word is two or three letters and a number, and the rows are still there underneath as icons.

### Props

- `label` (required) — `string`. The heading over the rows.
- `count` — `number`. How many rows are inside, printed on the far side of the heading.
- `badge` — `ReactNode`. A mark that belongs to the GROUP — "Beta", "3 new". Beside the label, not out at the end with the count: it qualifies the words, and a qualifier that has drifted to the other side of the row reads as a second, unrelated fact.
- `action` — `ReactNode`. A control on the heading row — a menu, an "add" button. Sits between the label and the count, and is NOT rendered inside the heading's own button: a control nested in a control is one the keyboard reaches by pressing the thing it is inside.
- `collapsible` — `boolean` default `true`. Whether the group folds at all. A group of two rows usually should not.
- `defaultOpen` — `boolean` default `true`.
- `children` (required) — `ReactNode`.
- `className` — `string`.

## SidebarBranch

A row that opens onto more rows. The thing a rail is for and the thing a flat list of groups cannot do: a workspace with projects in it, a folder with documents in it, a service with its environments. `SidebarGroup` is a HEADING over a set — it is not itself a place, and it has no icon and no state. This is a place that contains places, so it is a row like any other and it carries the same icon, trailing slot and hover as its children. The children sit behind the same hairline a group draws, one indent further in, so nesting reads as depth rather than as two unrelated lists. Two levels is what the indent has room for at this width; a third is a tree, and a tree in a 16rem column is a horizontal scrollbar with an outline in it. Collapsed to icons the row becomes its icon and the children are not drawn — there is nowhere for an indent to go, and a nested icon under an unnested one is two glyphs with no visible relationship.

### Props

- `label` (required) — `string`. The row's own words, and the name of the group it opens.
- `icon` — `RemixiconComponentType`. Drawn at the start of the row, and the whole of the row when collapsed.
- `trailing` — `ReactNode`. A count or a state at the end of the row.
- `defaultOpen` — `boolean` default `false`.
- `open` — `boolean`.
- `onOpenChange` — `(open: boolean) => void`.
- `children` (required) — `ReactNode`.
- `className` — `string`.

## SidebarItem

One row. `NavItem` with the two things a RAIL adds: a trailing slot, and an answer for the state where there is no room for words. Collapsed to icons the label is removed from the layout rather than hidden with CSS — a `sr-only` label still occupies the flex row's gap — and moves into a tooltip, because an icon on its own is a guess for everyone and unusable for a screen reader. A row with no `icon` keeps its label collapsed, since hiding it would leave a blank row: the icon is what makes the collapsed state legible, and a rail that collapses needs one on every row.

### Props

- `trailing` — `ReactNode`. A count or a state on the far side of the row. Hidden with the label.

Also accepts: `NavItemProps`.

## Example — default

```tsx
<SidebarProvider breakpoint={null} collapsible="icon">
  <div className="flex h-[38rem] w-full overflow-hidden rounded-(--radius-lg) border border-(--rule)">
    <Sidebar label="Workspace">
      <SidebarHeader>
        <span className="grid size-6 shrink-0 place-items-center rounded-(--radius-sm) bg-(--ink) text-[11px] text-(--paper)">
          A
        </span>
        <span className="truncate font-heading text-[15px] text-(--ink)">Acme Labs</span>
        <SidebarTrigger className="ms-auto" />
      </SidebarHeader>

      <SidebarContent>
        <SidebarGroup label="Workspace" count={2} collapsible={false}>
          <SidebarItem href="#home" icon={RiHomeLine} active>
            Home
          </SidebarItem>
          <SidebarItem href="#inbox" icon={RiInboxLine} trailing="12">
            Inbox
          </SidebarItem>
        </SidebarGroup>

        <SidebarGroup label="Agents" count={1} badge={<Badge tone="outline">Beta</Badge>}>
          <SidebarItem href="#personal" icon={RiAddLine}>
            Add new
          </SidebarItem>
        </SidebarGroup>

        <SidebarGroup label="Teamspaces" count={2}>
          <SidebarBranch label="Acme HQ" icon={RiBuilding2Line} defaultOpen>
            <SidebarItem href="#hq" icon={RiHomeLine}>
              Overview
            </SidebarItem>
            <SidebarItem href="#hq-roadmap" icon={RiFileTextLine}>
              Roadmap
            </SidebarItem>
          </SidebarBranch>
          <SidebarBranch label="Engineering" icon={RiBuilding2Line}>
            <SidebarItem href="#eng-sprints" icon={RiFileTextLine}>
              Sprints
            </SidebarItem>
          </SidebarBranch>
        </SidebarGroup>
      </SidebarContent>

      <SidebarFooter>
        <SidebarItem href="#library" icon={RiBookOpenLine}>
          Library
        </SidebarItem>
        <SidebarItem href="#trash" icon={RiDeleteBinLine}>
          Trash
        </SidebarItem>
        <SidebarSeparator />
        {/* `secondary`, so the shortcut key inside it keeps a ground to sit
            on. A Kbd on a filled button is a plate the same colour as the
            thing under it, which reads as a hole rather than as a key. */}
        <Button size="sm" variant="secondary" className="w-full justify-between">
          New chat
          <Kbd>⌘N</Kbd>
        </Button>
      </SidebarFooter>
    </Sidebar>
    <div className="flex-1 p-6 text-sm text-(--ink-3-aa)">The page, beside the rail.</div>
  </div>
</SidebarProvider>
```

## Example — offcanvas

```tsx
<SidebarProvider breakpoint={null} collapsible="offcanvas" shortcut={null}>
  <div className="flex h-72 w-full overflow-hidden rounded-(--radius-lg) border border-(--rule)">
    <Sidebar label="Handbook">
      <SidebarHeader>
        <span className="truncate font-heading text-[15px] text-(--ink)">Handbook</span>
        <SidebarTrigger className="ms-auto" />
      </SidebarHeader>
      <SidebarContent>
        <SidebarGroup label="Getting started" count={2}>
          <SidebarItem href="#install" icon={RiHomeLine} active>
            Installation
          </SidebarItem>
          <SidebarItem href="#tokens" icon={RiFileTextLine}>
            Tokens
          </SidebarItem>
        </SidebarGroup>
        <SidebarGroup label="Guides" count={2} defaultOpen={false}>
          <SidebarItem href="#theming" icon={RiFileTextLine}>
            Theming
          </SidebarItem>
          <SidebarItem href="#agents" icon={RiFileTextLine}>
            Working with agents
          </SidebarItem>
        </SidebarGroup>
      </SidebarContent>
    </Sidebar>
    {/* Gone means gone: the rail takes no width at all, so the page beside
        it gets the whole window rather than a strip of icons it cannot
        read. Something has to bring it back — here, the page does. */}
    <div className="flex flex-1 items-start gap-3 p-6 text-sm text-(--ink-3-aa)">
      <SidebarTrigger className="shrink-0" />
      The page, with the rail away.
    </div>
  </div>
</SidebarProvider>
```

## Example — a drawer on a phone

```tsx
<SidebarProvider breakpoint="xl" contained shortcut={null}>
  <div className="relative flex h-72 w-full overflow-hidden rounded-(--radius-lg) border border-(--rule)">
    <Sidebar label="Console" scrimLabel="Close the navigation">
      <SidebarHeader>
        <span className="truncate font-heading text-[15px] text-(--ink)">Console</span>
        <SidebarTrigger className="ms-auto" />
      </SidebarHeader>
      <SidebarContent>
        <SidebarGroup label="Monitor" count={3}>
          <SidebarItem href="#overview" icon={RiHomeLine} active>
            Overview
          </SidebarItem>
          <SidebarItem href="#deploys" icon={RiStackLine} trailing="4">
            Deploys
          </SidebarItem>
          <SidebarItem href="#settings" icon={RiSettings3Line}>
            Settings
          </SidebarItem>
        </SidebarGroup>
      </SidebarContent>
    </Sidebar>

    <SidebarInset>
      <div className="flex items-center gap-2 border-b border-(--rule) px-3 py-2.5">
        <SidebarTrigger />
        <span className="font-heading text-[15px] text-(--ink)">Overview</span>
      </div>
      <p className="m-0 p-4 text-sm leading-relaxed text-(--ink-3-aa)">
        The page keeps the whole frame: at this width the rail takes no room until it is asked
        for, and gives it all back the moment a row is taken.
      </p>
    </SidebarInset>
  </div>
</SidebarProvider>
```

## Example — inset floating and the other edge

```tsx
<div className="flex w-full flex-col gap-4">
  {ARRANGEMENTS.map(({ variant, side, note }) => (
    <div key={note} className="flex flex-col gap-1.5">
      <span className="mono-meta text-(--ink-3-aa)">{note}</span>
      <SidebarProvider
        variant={variant}
        side={side}
        collapsible="none"
        breakpoint={null}
        shortcut={null}
      >
        <div
          className={`flex h-40 overflow-hidden rounded-(--radius-lg) border border-(--rule) ${
            variant === 'flush' ? 'bg-(--paper)' : 'bg-(--stone)'
          } ${side === 'end' ? 'flex-row-reverse' : ''}`}
        >
          <Sidebar label={`Rail ${note}`}>
            <SidebarHeader>
              <span className="truncate font-heading text-[15px] text-(--ink)">Acme</span>
            </SidebarHeader>
            <SidebarContent>
              <SidebarGroup label="Inbox" count={2} collapsible={false}>
                <SidebarItem href="#all" icon={RiInboxLine} active>
                  All mail
                </SidebarItem>
                <SidebarItem href="#home" icon={RiHomeLine}>
                  Home
                </SidebarItem>
              </SidebarGroup>
            </SidebarContent>
          </Sidebar>
          <SidebarInset>
            <p className="m-0 p-4 text-sm leading-relaxed text-(--ink-3-aa)">
              The page. Under <code>inset</code> this is the panel and the rail is the ground.
            </p>
          </SidebarInset>
        </div>
      </SidebarProvider>
    </div>
  ))}
</div>
```

# NavItem

A row in a sidebar.

- Group: Navigation
- Import: `import { NavItem } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/nav-item/
- Related: app-shell

## Anatomy

- **Row** (required) — An <a href> at --control-h-sm with the --radius corner — or, under asChild, the router link you handed it, which receives the classes and aria-current and becomes the row itself.
- **Icon** — An optional Remix Icon component at 18px, aria-hidden, ahead of the label. It is rendered by the native branch only: a slotted row takes its icon inside the child, because Slot accepts exactly one.
- **Label** (required) — children, and the row’s whole accessible name — the icon contributes nothing to it.
- **Active ground** — What active turns on, in one move: a --stone fill, medium weight, and aria-current="page". Three signals, so the current row survives monochrome and low contrast.

## Best practices

### Do

- Repeat href on the slotted child: asChild forwards the classes and aria-current and nothing else, so a <Link> that does not carry its own href is a row that navigates nowhere.
- Put the icon inside the child in asChild mode — the icon prop is silently dropped there, which is how a whole sidebar renders as a column of unlabelled-looking rows.
- Derive active from the router’s current path rather than from the last click: it is what writes aria-current="page", so a sidebar tracking its own clicks tells a reader they are on the row they pressed instead of the page they are on.

### Don’t

- Do not mark a parent row active to show which section contains the page: active means aria-current="page", and two of them is a reader told they are in two places at once.
- Do not tighten the row further: it is --control-h-sm, which is 36px comfortable and 30px under data-density="compact", and a py class below that leaves a column of targets a thumb has to aim at.

## Accessibility

- aria-current="page" and not only a colour: the active row is also carried by weight and a filled ground.

## NavItem

A row in a sidebar. `aria-current="page"` and not only a colour: the active row has to be identifiable to a reader who cannot see that it is darker. In this system it is also carried by weight and by a filled ground, so it survives monochrome printing and low contrast. Framework-agnostic. `asChild` is how a Next or React Router app gets client-side navigation without this package importing either.

### Props

- `href` (required) — `string`.
- `icon` — `RemixiconComponentType`. Optional leading icon (a `@remixicon/react` component, rendered at 18px).
- `active` — `boolean` default `false`. Marks the current route. Also sets `aria-current="page"`.
- `asChild` — `boolean` default `false`. Hand the styling to a router's own `Link` instead of a native `<a>`. The slotted child receives the classes and `aria-current`, and becomes the row — so `icon` is not rendered in this mode; put it inside the child.
- `children` (required) — `ReactNode`.
- `className` — `string`.

Also accepts: `Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'className' | 'children'>`.

## Example — default

```tsx
import { NavItem } from '@misoto22/design'

<nav className="flex w-56 flex-col gap-1" aria-label="Example">
  <NavItem href="#" icon={RiShapesLine} active>Components</NavItem>
  <NavItem href="#" icon={RiPaletteLine}>Colour</NavItem>
  <NavItem href="#" icon={RiText}>Typography</NavItem>
</nav>
```

## Example — one current row

```tsx
import { NavItem } from '@misoto22/design'

<nav className="flex w-56 flex-col gap-5" aria-label="Sectioned example">
  <div className="flex flex-col gap-1">
    <span className="px-3 pb-1 mono-meta text-(--ink-3-aa)">Learn</span>
    <NavItem href="#" icon={RiBookOpenLine}>Getting started</NavItem>
    <NavItem href="#" icon={RiFileTextLine}>Principles</NavItem>
  </div>
  <div className="flex flex-col gap-1">
    <span className="px-3 pb-1 mono-meta text-(--ink-3-aa)">Reference</span>
    <NavItem href="#" icon={RiShapesLine} active>Components</NavItem>
    <NavItem href="#" icon={RiPaletteLine}>Colour</NavItem>
    <NavItem href="#" icon={RiLayoutRowLine}>Tokens</NavItem>
  </div>
</nav>
```

## Example — router link

```tsx
import { NavItem } from '@misoto22/design'

<nav className="flex w-56 flex-col gap-1" aria-label="Router example">
  <NavItem asChild href="/">
    <a href="/">
      <RiHomeLine size={18} aria-hidden className="shrink-0" />
      Overview
    </a>
  </NavItem>
  <NavItem asChild href="/components" active>
    <a href="/components">
      <RiShapesLine size={18} aria-hidden className="shrink-0" />
      Components
    </a>
  </NavItem>
</nav>
```

# Collapsible

One thing that opens, on its own.

- Group: Navigation
- Import: `import { Collapsible } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/collapsible/
- Related: accordion

## When to reach for it

The difference from Accordion is arithmetic: an accordion is a SET and can coordinate. An accordion of one manages a value nobody reads.

## Anatomy

- **Root** (required) — Collapsible — Radix’s root, holding open or defaultOpen and drawing nothing. CollapsibleSection is the same root with the trigger and panel already composed, and is what most call sites want.
- **Trigger** (required) — A plain <button> carrying aria-expanded and aria-controls — and, unlike an accordion row, wrapped in no heading at all. Nothing here appears in a document outline.
- **Marker** (required) — A chevron rotating 180°, chosen against the accordion’s plus on purpose: this reveals more of the same thing, where an accordion row opens a distinct answer.
- **Panel** — Radix’s Content, unmounted while closed and animating on the measured --radix-collapsible-content-height, so a long group and a short one take the same time. A bare div: no region role and no name of its own, again unlike an accordion’s. Both this and the loose CollapsibleContent carry data-m22-animated, so the two agree under prefers-reduced-motion rather than only one of them honouring it.

## Best practices

### Do

- Give the trigger a heading of your own when the section is a section: Accordion wraps every trigger in an <h3> and this deliberately wraps none, so a page built from CollapsibleSections has nothing for heading navigation to stop at.
- Reach for the loose CollapsibleTrigger and CollapsibleContent only when the header has to hold more than a title — a count on one side, a switch on the other. They exist so that call site does not go to Radix and re-derive aria-expanded by hand.
- Set defaultOpen when what it hides is why the reader came: the closed panel is unmounted rather than hidden, so its text is not in the page for find-in-page, for a print, or for anything reading the rendered DOM.
- Control it with open and onOpenChange when something outside has to open it — a sidebar group that must expand for the route living inside it cannot be told to from a component that owns its own state.

### Don’t

- Do not build a set out of these: two sections cannot close each other, so the reader ends with every one open and a column to scroll past. That coordination is the whole of what Accordion’s single value buys.
- Do not flip the title between “Show more” and “Show less”: aria-expanded on the trigger already carries the state, so the row is announced with its state twice and with a new name each time it is pressed.

## Keyboard

- Enter / Space — Opens or closes it.

## Collapsible

Re-export of `CollapsiblePrimitive.Root`.

Radix Collapsible root, as a typed passthrough.

## CollapsibleTrigger

Re-export of `CollapsiblePrimitive.Trigger`.

The trigger and the panel, unstyled, for a disclosure that needs its own layout — a sidebar group whose header carries a count and a chevron on opposite sides, say. `CollapsibleSection` is the composed version and is what most call sites want; these two exist so the ones that do not have to reach for Radix directly and re-derive the keyboard and `aria-expanded` wiring. The panel animates on `--radix-collapsible-content-height`, which Radix measures — so it opens to its real height rather than to a guessed `max-height`, which is what makes a long group and a short one take the same time instead of the long one appearing to stall.

## CollapsibleContent

## CollapsibleSection

One thing that opens, on its own. The difference from `Accordion` is arithmetic: an accordion is a SET, and a set can coordinate — opening one closes another. A collapsible is one disclosure with nothing to coordinate with. Reaching for an accordion of one gets you a component managing a value you never read. The marker here is a chevron rather than the accordion's plus, and deliberately: this reveals more of the same thing, where an accordion row opens a distinct answer.

### Props

- `title` (required) — `ReactNode`. What the trigger says.
- `children` (required) — `ReactNode`.

Also accepts: `Omit<ComponentProps<typeof CollapsiblePrimitive.Root>, 'children' | 'title'>`.

## Example — default

```tsx
import { CollapsibleSection, Field, Input } from '@misoto22/design'

<div className="w-full max-w-md divide-y divide-(--rule) border-y border-(--rule)">
  <CollapsibleSection title="Advanced settings">
    <Field label="Retries" hint="How many times a failed job is tried again.">
      <Input type="number" defaultValue={3} />
    </Field>
  </CollapsibleSection>
</div>
```

## Example — a custom header

```tsx
import { Badge, Collapsible, CollapsibleContent, CollapsibleTrigger } from '@misoto22/design'

<Collapsible defaultOpen className="w-full max-w-md">
  <div className="flex items-center justify-between gap-4 border-b border-(--rule) py-3">
    <span className="text-sm text-(--ink)">Failed checks</span>
    <div className="flex items-center gap-3">
      <Badge tone="danger">3</Badge>
      <CollapsibleTrigger
        aria-label="Show the failed checks"
        className="group inline-flex size-8 items-center justify-center rounded-(--radius) text-(--ink-3-aa) transition-colors duration-(--duration-fast) hover:text-(--ink)"
      >
        <RiArrowDownSLine
          size={16}
          aria-hidden
          className="transition-transform duration-(--duration-base) ease-(--ease-out-expo) group-data-[state=open]:rotate-180"
        />
      </CollapsibleTrigger>
    </div>
  </div>
  <CollapsibleContent>
    <ul className="m-0 flex list-none flex-col gap-2 p-0 py-3 text-sm text-(--ink-2)">
      <li>typecheck — 2 errors in apps/docs/src/lib/docs.ts</li>
      <li>lint — unused import in Toolbar.tsx</li>
      <li>visual diff — 1 changed screenshot</li>
    </ul>
  </CollapsibleContent>
</Collapsible>
```

## Example — sidebar group

```tsx
import { CollapsibleSection, NavItem } from '@misoto22/design'

<nav className="flex w-56 flex-col gap-1" aria-label="Docs sections">
  <NavItem href="#" icon={RiHomeLine}>Overview</NavItem>
  <CollapsibleSection title="Components" open={open} onOpenChange={setOpen}>
    <div className="flex flex-col gap-1 ps-3">
      <NavItem href="#">Button</NavItem>
      <NavItem href="#" active>Pagination</NavItem>
      <NavItem href="#">Tabs</NavItem>
    </div>
  </CollapsibleSection>
</nav>
```

# Dialog

A modal surface: portal, scrim, centred panel.

- Group: Overlays
- Import: `import { Dialog } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/dialog/
- Related: dropdown-menu, tooltip

## Anatomy

- **Scrim** (required) — The full-viewport --scrim layer at --z-overlay (200). It is what a click outside lands on, and it paints over everything the page had pinned below that rank — a FloatingIconButton at 100 included. Not over an anchored panel: those sit at 220 precisely so a Select opened inside this dialog is still reachable.
- **Panel** (required) — The centred box at --z-modal (210), capped at min(92vw, 32rem) wide and 85vh tall, scrolling its own body past that. It centres itself with a translate, which has consequences for anything fixed inside it.
- **Title** (required) — title, rendered as the Radix Title. Always present: when title is omitted a visually hidden one is rendered reading the literal word “Dialog”, and development warns DIALOG_TITLE_MISSING — the fallback exists so an unnamed modal is not shipped, not so one can be.
- **Description** — description, a quiet line under the title. It shares one wrapper with the title, so hideTitle hides both.
- **Close** — The 36px X in the top-end corner, rendered while showClose is true (the default) and carrying its own aria-label of “Close”.

## Best practices

### Do

- Pass title even when you set hideTitle: with no title at all the fallback accessible name is the literal string “Dialog”, so every unnamed modal in the app is announced as the same thing — and it passes an automated accessibility check while doing it, which is why development warns instead of leaving it to a review.
- Wrap the cancelling control in DialogClose rather than flipping your own state — the close then runs through Radix, which returns focus to the trigger instead of dropping it at the top of the document.
- Keep it to what fits. The panel stops at 32rem by 85vh and scrolls its own body past that, so a form long enough to scroll has become a Sheet, which gets the full height of the viewport, or a page.
- Leave showClose on unless the panel supplies its own exit: Escape and the scrim are the only other ways out and neither is visible, so showClose={false} on a dialog full of content is a room with an unmarked door.

### Don’t

- An OverlayContainer whose element is not positioned hands the dialog the wrong box: naming a container switches the panel from fixed to absolute, and an unpositioned container sends it to the nearest positioned ancestor instead — usually the page, which looks like the container was ignored.
- Two dialogs open at once are ordered by the DOM, not by a rank: both sit at --z-modal, so the one mounted last paints over the first — a command palette summoned over a dialog lands on top because it opened second, and reversing that order reverses the picture.
- The panel centres itself with a transform, which makes it the containing block for every position: fixed descendant — a FloatingIconButton dropped inside a dialog pins to the panel’s corner rather than the screen’s.

## Accessibility

- Radix owns the focus trap, Escape, the scroll lock and aria-modal.
- A dialog without a visible heading still renders a hidden title, rather than shipping an unnamed modal.

## Keyboard

- Escape — Closes it, and focus returns to the trigger it came from.
- Tab — Cycles inside the dialog; focus cannot leave while it is open.

## Dialog

Re-export of `DialogPrimitive.Root`.

Radix Dialog root + trigger + close, re-exported as typed passthroughs.

## DialogTrigger

Re-export of `DialogPrimitive.Trigger`.

## DialogClose

Re-export of `DialogPrimitive.Close`.

## DialogContent

A modal surface: portal → scrim → centred panel. Radix owns the focus trap, the escape key, the scroll lock and the `aria-modal` wiring — all of which a hand-rolled dialog gets subtly wrong, usually by leaving focus behind in the page underneath. Radix requires a `Dialog.Title` whether or not one is shown, so a dialog without a visible heading still renders a hidden one rather than shipping an unnamed modal — and warns in development, because the fallback it renders is the literal word "Dialog" and a placeholder that passes an accessibility check is how the problem survives a review. Portals into the element an enclosing `OverlayContainer` names, and switches from viewport positioning to container positioning when there is one. A `fixed` panel covers the page whatever it is portalled into, so honouring the container without that swap would have moved the markup and left the picture unchanged.

### Props

- `title` — `ReactNode`. Heading text. Pass one even when `hideTitle` is set. Radix requires a title, so omitting it renders a hidden fallback reading the literal word "Dialog" — which satisfies an automated accessibility check and announces every unnamed modal in the application as the same thing. Development says so out loud.
- `description` — `ReactNode`. Sub-heading under the title.
- `className` — `string`.
- `showClose` — `boolean` default `true`. Show the top-right close control (default true).
- `hideTitle` — `boolean` default `false`. Keeps the title for assistive tech and hides it visually. For a surface whose purpose is obvious to anyone who can see it — a command palette, a media lightbox — where a printed heading would be furniture. The title itself is never optional: Radix requires one, and a modal with no accessible name drops a screen reader into an unnamed region.

Also accepts: `Omit<ComponentProps<typeof DialogPrimitive.Content>, 'title' | 'className'>`.

## Example — a destructive confirm

```tsx
import { Button, Dialog, DialogClose, DialogContent, DialogTrigger } from '@misoto22/design'

<Dialog>
  <DialogTrigger asChild>
    <Button variant="danger">Delete frame</Button>
  </DialogTrigger>
  <DialogContent
    title="Delete this frame?"
    description="It will be removed from the archive and from every collection it appears in."
  >
    <div className="mt-6 flex justify-end gap-3">
      <DialogClose asChild>
        <Button variant="secondary">Cancel</Button>
      </DialogClose>
      <DialogClose asChild>
        <Button variant="danger">Delete</Button>
      </DialogClose>
    </div>
  </DialogContent>
</Dialog>
```

## Example — a hidden title

```tsx
<Dialog>
  <DialogTrigger asChild>
    <Button variant="secondary">Review the release</Button>
  </DialogTrigger>
  <DialogContent title="Release 0.4.0" hideTitle>
    <div className="flex items-center gap-3">
      <span className="eyebrow text-(--ink-3-aa)">changeset</span>
      <Badge tone="success">ready</Badge>
    </div>
    <Heading level={2} size="item" className="mt-2">
      Release 0.4.0
    </Heading>
    <Text size="sm" className="mt-3">
      Five packages, one minor bump. The tag is cut when this merges, and the
      registry has the tarball about ninety seconds later.
    </Text>
    <div className="mt-6 flex justify-end gap-3">
      <DialogClose asChild>
        <Button variant="secondary">Not yet</Button>
      </DialogClose>
      <DialogClose asChild>
        <Button>Merge and tag</Button>
      </DialogClose>
    </div>
  </DialogContent>
</Dialog>
```

## Example — or a sheet

```tsx
<div className="flex flex-wrap items-center gap-3">
  <Dialog>
    <DialogTrigger asChild>
      <Button variant="secondary">Rename (dialog)</Button>
    </DialogTrigger>
    <DialogContent title="Rename this collection" description="Its public link does not change.">
      <Field label="Name" className="mt-4">
        <Input defaultValue="Kyoto, February" />
      </Field>
      <div className="mt-6 flex justify-end gap-3">
        <DialogClose asChild>
          <Button variant="secondary">Cancel</Button>
        </DialogClose>
        <DialogClose asChild>
          <Button>Rename</Button>
        </DialogClose>
      </div>
    </DialogContent>
  </Dialog>

  <Sheet>
    <SheetTrigger asChild>
      <Button variant="secondary">Edit details (sheet)</Button>
    </SheetTrigger>
    <SheetContent
      side="end"
      title="Collection details"
      description="Six fields, and room to see them all at once."
    >
      <div className="mt-4 flex flex-col gap-4">
        <Field label="Name">
          <Input defaultValue="Kyoto, February" />
        </Field>
        <Field label="Slug" hint="Used in the public link.">
          <Input defaultValue="kyoto-february" />
        </Field>
        <Field label="Camera">
          <Input defaultValue="Pentax 67" />
        </Field>
        <Field label="Notes">
          <Textarea rows={4} defaultValue="Portra 400, pushed one stop." />
        </Field>
        <div className="flex justify-end gap-3">
          <SheetClose asChild>
            <Button variant="secondary">Cancel</Button>
          </SheetClose>
          <SheetClose asChild>
            <Button>Save</Button>
          </SheetClose>
        </div>
      </div>
    </SheetContent>
  </Sheet>
</div>
```

# DropdownMenu

A menu of actions.

- Group: Overlays
- Import: `import { DropdownMenu } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/dropdown-menu/
- Related: dialog, select

## When to reach for it

Actions. Items that navigate belong in a nav; items that set a value are a Select or a RadioGroup.

## Anatomy

- **Trigger** (required) — A passthrough to Radix, which renders its own bare button unless you pass asChild. It carries aria-haspopup and data-state, which is what lets a Button show that its menu is open.
- **Panel** (required) — The portalled menu: at least 11rem wide, 6px off the trigger, colliding with 8px of padding against the viewport or the OverlayContainer frame. It has no max height, so it flips rather than scrolls.
- **Item** — A row. icon takes either spelling — the icon component, sized to 16px here, or a rendered element, placed as given; destructive paints the row --danger; disabled drops pointer events and the opacity.
- **Label** — A mono eyebrow, on its own. Visual only — Radix renders it as a plain div, and the arrow keys skip it. DropdownMenuGroup is the one that heads rows: it renders role="group" and points its aria-labelledby at this.
- **Group** — A named section: role="group" around the rows, with label rendered inside it as the Label and named through aria-labelledby. The wiring is the component’s job because a caller doing it by hand has to invent an id.
- **Separator** — A hairline between groups, and a real role="separator" — which a menu permits, unlike the listbox a Command palette is built on.

## Best practices

### Do

- Pass icon the component — icon={Settings} — and let the row size it, so a menu of ten rows draws ten icons at one size rather than ten sizes. The element spelling is accepted too, and used to be the exact opposite of what CommandItem took one import away.
- Give the trigger asChild and a real Button: without it Radix renders its own unstyled button, and the menu ends up hanging off a control that is not part of the system’s set.
- Hold a dialog’s open state yourself and call event.preventDefault() in the item’s onSelect — selecting a row closes the menu, and Radix’s close moves focus back to the trigger, which arrives after the dialog has claimed it and pulls the reader straight back out.
- Stop at about a dozen rows. There is no max height on the panel, so a longer menu grows until it hits the collision padding and flips above the trigger — SearchableMenu is the same list once it has outgrown this one.

### Don’t

- Radix defaults modal to true and nothing here overrides it, so while the menu is open the page behind is scroll-locked and its pointer events are off — a menu is not the place for something the reader is meant to consult the page while using.
- A bare DropdownMenuLabel over rows is a picture of a heading: Radix’s MenuLabel is a plain div with no role and nothing tying it to what follows, so the sections a sighted reader sees arrive as one undivided list. DropdownMenuGroup renders both halves and wires them together.
- There is no checkbox item, radio item or submenu in this package’s exports — a menu that needs a checked state has to import from @radix-ui/react-dropdown-menu directly, and that row arrives with none of this file’s styling on it.

## Accessibility

- Inside a bounded frame — a device preview, an embedded console — wrap the subtree in `<OverlayContainer container={el}>`. The panel then renders into that element and collides with its edges instead of the viewport’s, and inherits the `dir` and `data-density` set there.
- Highlight is driven by data-highlighted, which covers hover AND keyboard focus — styling :hover alone leaves the keyboard user unable to see where they are.
- DropdownMenuGroup segments the menu for a screen reader as well as for the eye; a bare Label does it for the eye alone.

## Keyboard

- Enter / Space / ↓ — Opens the menu and lands on the first item.
- ↑ / ↓ — Moves between items.
- a–z — Jumps to the next item starting with that letter.
- Escape — Closes the menu and returns focus to the trigger.

## DropdownMenu

Re-export of `DropdownMenuPrimitive.Root`.

Radix DropdownMenu root + trigger, re-exported as typed passthroughs.

## DropdownMenuTrigger

Re-export of `DropdownMenuPrimitive.Trigger`.

## DropdownMenuContent

A menu surface. A menu is a list of ACTIONS. If the items navigate somewhere, they belong in a nav; if they set a value, that is a `Select` or a `RadioGroup` — this package ships no checkbox or radio menu item, and a plain item pretending to be a choice loses the checked state a screen reader needs.

Also accepts: `ComponentProps<typeof DropdownMenuPrimitive.Content>`.

## DropdownMenuItem

A menu row. Highlight is driven by Radix's `data-highlighted`, which covers both pointer hover and keyboard focus — styling `:hover` alone leaves the keyboard user unable to see where they are.

### Props

- `icon` — `RemixiconComponentType | ReactNode`. Optional leading icon, rendered before the label. Either spelling: `icon={Settings}` passes the component and this sizes it, `icon={<Settings size={16} />}` passes the element and this places it. The two used to mean opposite things one import apart — `CommandItem.icon` took the element while this took the component — and the wrong one did not fail a type check into anything actionable, it failed at render.
- `destructive` — `boolean` default `false`. Paints the row as destructive. Use for delete, revoke, disconnect.

Also accepts: `ComponentProps<typeof DropdownMenuPrimitive.Item>`.

## DropdownMenuSeparator

Hairline divider between menu groups.

## DropdownMenuLabel

Mono eyebrow heading, on its own. Visual only: Radix renders it as a bare `<div>` with no role, so it segments the menu for a reader who can see it and for nobody else. Reach for `DropdownMenuGroup` when the eyebrow is a HEADING over rows; this is right for a line that heads nothing — the signed-in address at the top of an account menu.

## DropdownMenuGroup

A named section of a menu. The eyebrow alone was a picture of a heading. Radix's `MenuLabel` carries no role and no `aria-labelledby` wiring, and `MenuGroup` — which does carry `role="group"` — was not re-exported by this package at all, so a sighted reader saw three labelled sections and a screen-reader user got one undifferentiated list. This renders the group, renders the label inside it, and points the one at the other, which is the whole of the fix and not something a caller should have to remember.

### Props

- `label` — `ReactNode`. The eyebrow over the rows, and the group's accessible name.

Also accepts: `ComponentProps<typeof DropdownMenuPrimitive.Group>`.

## Example — an account menu

```tsx
<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <Button variant="secondary">Account</Button>
  </DropdownMenuTrigger>
  <DropdownMenuContent align="start">
    <DropdownMenuLabel>Signed in</DropdownMenuLabel>
    <DropdownMenuItem icon={RiSettings3Line}>Settings</DropdownMenuItem>
    <DropdownMenuItem icon={RiLogoutBoxRLine}>Sign out</DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem icon={RiDeleteBinLine} destructive>Delete account</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

## Example — an overflow button

```tsx
<div className="flex w-full max-w-sm items-center justify-between gap-3 rounded-(--radius) border border-(--rule) px-4 py-3">
  <Text size="sm" tone="strong" className="font-mono">
    kyoto-february.tif
  </Text>
  <DropdownMenu>
    <DropdownMenuTrigger asChild>
      <Button iconOnly aria-label="Actions for kyoto-february.tif" variant="ghost" size="sm">
        <RiMoreLine size={16} aria-hidden />
      </Button>
    </DropdownMenuTrigger>
    <DropdownMenuContent align="end">
      <DropdownMenuItem icon={RiFileCopyLine}>Copy link</DropdownMenuItem>
      <DropdownMenuItem icon={RiDownloadLine}>Download original</DropdownMenuItem>
      <DropdownMenuItem icon={RiPushpinLine} disabled>
        Pin to the collection
      </DropdownMenuItem>
      <DropdownMenuSeparator />
      <DropdownMenuItem icon={RiDeleteBinLine} destructive>
        Delete
      </DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>
</div>
```

## Example — where it opens

```tsx
<div className="flex w-full max-w-md items-center justify-between gap-3 rounded-(--radius) border border-(--rule) p-2">
  <DropdownMenu>
    <DropdownMenuTrigger asChild>
      <Button variant="ghost" size="sm">
        <RiFilterLine size={16} aria-hidden /> Filter
      </Button>
    </DropdownMenuTrigger>
    <DropdownMenuContent align="start">
      <DropdownMenuItem icon={RiLayoutRowLine}>Failed runs only</DropdownMenuItem>
      <DropdownMenuItem icon={RiTableLine}>Main branch only</DropdownMenuItem>
      <DropdownMenuItem icon={RiEqualizerLine}>Longer than two minutes</DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>

  <DropdownMenu>
    <DropdownMenuTrigger asChild>
      <Button variant="ghost" size="sm">
        <RiArrowUpDownLine size={16} aria-hidden /> Sort
      </Button>
    </DropdownMenuTrigger>
    <DropdownMenuContent align="end">
      <DropdownMenuItem>Newest first</DropdownMenuItem>
      <DropdownMenuItem>Longest first</DropdownMenuItem>
      <DropdownMenuItem>Branch, A to Z</DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>
</div>
```

# Tooltip

A short label on hover and on focus.

- Group: Overlays
- Import: `import { Tooltip } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/tooltip/
- Related: dialog

## When to reach for it

Never for anything the reader NEEDS: a tooltip is unreachable on touch and invisible while scanning.

## Anatomy

- **Provider** (required) — TooltipProvider, wrapped once around the app or the smallest subtree that has tooltips. It holds the shared 700ms open delay and the 300ms skip window; Radix throws without it rather than rendering an untimed tip.
- **Trigger** (required) — children, handed to Radix with asChild — so the child IS the trigger and no wrapper is inserted around it.
- **Tip** (required) — content, in the portalled panel: 11px mono on --feature-surface, capped at 16rem, 6px off the chosen side, at --z-toast (300) so it stays above a modal it was opened inside.
- **Portal** — Where the tip lands — document.body, or the element an enclosing OverlayContainer names, which is also the box it collides against with 8px of padding.

## Best practices

### Do

- Put the Provider high and put one there. Radix throws without it, and a provider per tooltip defeats the shared timing that stops a row of icon buttons flashing a separate tip on every hover.
- Match the tip to the control’s aria-label word for word: two different names for one control is the “label in name” failure (WCAG 2.5.3), and a voice-control user says the words they can see.
- Keep the tip to a phrase. It is capped at 16rem and set in 11px mono, so a sentence wraps into a five-line block that covers the thing it was describing.
- Put it on a control that already works without it: Radix returns early when the pointer type is touch, so the tip never opens on a phone at all and anything it is the sole carrier of is simply missing there.

### Don’t

- delayDuration={0} does not just make it faster — the state becomes instant-open rather than delayed-open, and the fade is keyed to delayed-open, so the tip appears with no transition at all.
- Setting delayDuration on one Tooltip overrides the provider for that trigger alone, which is how a toolbar ends up with one tip that appears instantly beside neighbours at 700ms — read as lag, not as emphasis.
- Nothing focusable belongs in content: the tip is not in the tab order and closes when the trigger loses focus, so a link or a button in there is reachable by pointer and by nothing else. That is a Popover.

## Accessibility

- Inside a bounded frame — a device preview, an embedded console — wrap the subtree in `<OverlayContainer container={el}>`. The panel then renders into that element and collides with its edges instead of the viewport’s, and inherits the `dir` and `data-density` set there.
- The trigger is asChild, so the child must be focusable — a div trigger simply has no keyboard tooltip, which this API shape makes obvious rather than silent.
- Not an accessible name. An icon-only button still needs its own aria-label.

## Keyboard

- Tab — Shows the tip — focus reveals it, not only hover.
- Escape — Dismisses it.

## TooltipProvider

Re-export of `TooltipPrimitive.Provider`.

Wrap the app — or the smallest subtree that has tooltips — once. Radix needs it to share the open/close timing between neighbouring triggers, which is what stops a row of icon buttons flashing a tooltip per hover.

## Tooltip

A short label on hover and on focus. `asChild` on the trigger by design: the tooltip must not add a wrapper that swallows the trigger's own focus ring or breaks a flex row. It also means the child has to be focusable — a `<div>` trigger gets no keyboard tooltip, which is the failure this API shape makes obvious rather than silent. Not a replacement for an accessible name. An icon-only button still needs its own `aria-label`; the tooltip repeats that name for sighted pointer users.

### Props

- `children` (required) — `ReactNode`. The element the tooltip describes. Must be focusable.
- `content` (required) — `ReactNode`. The tip. Keep it to a phrase — a tooltip is unreachable on touch and invisible to a reader who is scanning, so anything a user NEEDS belongs on the page instead.
- `side` — `ComponentProps<typeof TooltipPrimitive.Content>['side']` default `'top'`.
- `sideOffset` — `number` default `6`.

Also accepts: `Pick<ComponentProps<typeof TooltipPrimitive.Root>, 'open' | 'defaultOpen' | 'onOpenChange' | 'delayDuration'>`.

## Example — an icon button

```tsx
import { Button, Tooltip, TooltipProvider } from '@misoto22/design'

) => clearTimeout(timer)
  }, [copied])

  return (
<TooltipProvider>
  <div className="flex items-center gap-3">
    {/* One string for the tip and the name, so the two cannot drift apart
        — and both change with the icon, because a copy control that looks
        identical before and after leaves the reader clicking it twice. */}
    <Tooltip content={label}>
      <Button iconOnly aria-label={label} variant="secondary" onClick={() => setCopied(true)}>
        {copied ? (
          <RiCheckLine size={16} className="text-(--ok)" aria-hidden />
        ) : (
          <RiFileCopyLine size={16} aria-hidden />
        )}
      </Button>
    </Tooltip>

    <Tooltip content="Share this frame" side="bottom">
      <Button iconOnly aria-label="Share this frame" variant="secondary">
        <RiShareLine size={16} aria-hidden />
      </Button>
    </Tooltip>
  </div>
</TooltipProvider>
```

## Example — one provider

```tsx
import { Button, Tooltip, TooltipProvider } from '@misoto22/design'

<TooltipProvider>
  <div className="flex items-center gap-1 rounded-(--radius) border border-(--rule) p-1">
    {TOOLS.map((tool) => (
      <Tooltip key={tool.name} content={tool.name}>
        <Button iconOnly aria-label={tool.name} variant="ghost" size="sm">
          <tool.icon size={16} aria-hidden />
        </Button>
      </Tooltip>
    ))}
  </div>
</TooltipProvider>
```

## Example — a shortcut hint

```tsx
import { Button, Kbd, Text, Tooltip, TooltipProvider } from '@misoto22/design'

<TooltipProvider>
  <div className="flex flex-col items-center gap-4">
    <div className="flex items-center gap-3">
      <Tooltip content="Save the draft" side="bottom">
        <Button keycap="S">Save draft</Button>
      </Tooltip>
      <Tooltip content="Publish this post" side="bottom">
        <Button variant="secondary">Publish</Button>
      </Tooltip>
    </div>
    <Text size="sm" tone="muted">
      The same keys are printed on the page, so <Kbd>S</Kbd> is not news a
      hover has to break.
    </Text>
  </div>
</TooltipProvider>
```

# Popover

A panel anchored to a control, holding content you can interact with.

- Group: Overlays
- Import: `import { Popover } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/popover/
- Related: tooltip, dropdown-menu

## When to reach for it

Anything with a link, a field or a button in it. A tooltip describes and cannot be entered — put a control inside one and it becomes unreachable.

## Anatomy

- **Trigger** (required) — PopoverTrigger, a passthrough. Pass asChild to keep your own control; Radix returns focus here when the panel closes on Escape.
- **Panel** (required) — The anchored dialog: a flat 18rem wide with 1rem of padding, 8px off the trigger, named by label. Focus moves into it on open, but it is not trapped there.
- **Anchor** — PopoverAnchor, for when the panel should be positioned against something other than the control that opened it — the row an overflow button acts on, a selection in text.
- **Close** — PopoverClose, and the 32px X that showClose renders in the top-end corner. Off by default, unlike Dialog’s.

## Best practices

### Do

- Make label say what the panel holds rather than echoing the trigger: it is announced on entry, so “Filter options” tells a reader where they have landed where a repeat of the button text tells them nothing new.
- Use PopoverAnchor when the visual anchor is not the trigger — a toolbar button acting on a selected row — otherwise the panel tracks the button and drifts away from the thing it is editing.
- Wrap the dismissing control in PopoverClose rather than flipping your own state, so the close runs through Radix and focus goes back to the trigger instead of to the top of the document.
- Turn showClose on when the panel holds a form. It is off by default, and a non-modal panel whose only exit is clicking away gives an in-progress edit no deliberate end.

### Don’t

- It is not modal — Radix defaults modal to false and nothing here changes that, so there is no focus trap and no scroll lock: tabbing past the last control inside moves focus into the page, which Radix reads as a focus-outside and closes the panel mid-task.
- A list of actions belongs in a DropdownMenu. A popover’s contents are ordinary tab stops, so ten actions is ten stops with no type-ahead, where a menu is one stop with arrow keys and a letter jump inside it.
- The panel sits at --z-dropdown, which resolves to 220 — above a Dialog’s 210, so that a popover opened FROM a dialog is reachable. A popover the page opened and your own state holds open therefore paints over a modal that arrives afterwards; Radix closes it on the interaction outside, and a controlled open that ignores that is the one way to see it.

## Accessibility

- Inside a bounded frame — a device preview, an embedded console — wrap the subtree in `<OverlayContainer container={el}>`. The panel then renders into that element and collides with its edges instead of the viewport’s, and inherits the `dir` and `data-density` set there.
- label is required: a popover is a dialog, and an unnamed one announces nothing.
- Its contents Tab like the rest of the page, unlike a menu’s arrow-key list.

## Keyboard

- Enter / Space — Opens it.
- Tab — Moves through its contents like the rest of the page.
- Escape — Closes it and returns focus to the trigger.

## Popover

Re-export of `PopoverPrimitive.Root`.

Radix Popover root, trigger, anchor and close, as typed passthroughs.

## PopoverTrigger

Re-export of `PopoverPrimitive.Trigger`.

## PopoverAnchor

Re-export of `PopoverPrimitive.Anchor`.

## PopoverClose

Re-export of `PopoverPrimitive.Close`.

## PopoverContent

A panel anchored to a control, holding content the reader can interact with. The line against `Tooltip` is not visual, it is behavioural: a tooltip describes and cannot be entered; a popover holds things you tab to. Anything with a link, a field or a button in it is a popover, and putting that inside a tooltip makes it unreachable — the tooltip closes as soon as focus tries to move into it. Against `DropdownMenu`: a menu is a list of actions with menu semantics and arrow-key navigation. A popover is free-form, and its contents Tab like the rest of the page.

### Props

- `label` (required) — `string`. Names the panel for assistive tech. Required — a popover is a dialog.
- `showClose` — `boolean` default `false`. Show the top-end close control.

Also accepts: `ComponentProps<typeof PopoverPrimitive.Content>`.

## Example — a filter panel

```tsx
import { Button, Field, Popover, PopoverClose, PopoverContent, PopoverTrigger, Select, SelectItem } from '@misoto22/design'

<Popover>
  <PopoverTrigger asChild>
    <Button variant="secondary">Filters</Button>
  </PopoverTrigger>
  <PopoverContent label="Deploy filters" showClose>
    <div className="flex flex-col gap-4">
      <Field label="Status">
        <Select label="Status" defaultValue="all">
          <SelectItem value="all">Any</SelectItem>
          <SelectItem value="live">Live</SelectItem>
        </Select>
      </Field>
      <PopoverClose asChild>
        <Button size="sm">Apply</Button>
      </PopoverClose>
    </div>
  </PopoverContent>
</Popover>
```

## Example — anchored elsewhere

```tsx
<Popover>
  <div className="flex w-full max-w-sm flex-col gap-3">
    <div className="flex items-center justify-between gap-3">
      <Text size="sm" tone="muted">Selected row</Text>
      <PopoverTrigger asChild>
        <Button variant="secondary" size="sm">Rename</Button>
      </PopoverTrigger>
    </div>
    <PopoverAnchor asChild>
      <div className="flex items-center justify-between gap-3 rounded-(--radius) border border-(--accent) bg-(--accent-muted) px-4 py-3">
        <span className="font-mono text-sm text-(--ink)">codex/photo-cache</span>
        <span className="mono-meta text-(--ink-3-aa)">62s</span>
      </div>
    </PopoverAnchor>
  </div>
  <PopoverContent label="Rename this branch" showClose>
    <div className="flex flex-col gap-4">
      <Field label="Branch name">
        <Input defaultValue="codex/photo-cache" />
      </Field>
      <PopoverClose asChild>
        <Button size="sm">Rename</Button>
      </PopoverClose>
    </div>
  </PopoverContent>
</Popover>
```

## Example — panel or menu

```tsx
<div className="flex flex-wrap items-center gap-3">
  <Popover>
    <PopoverTrigger asChild>
      <Button variant="secondary">Export size</Button>
    </PopoverTrigger>
    <PopoverContent label="Export size" showClose>
      <div className="flex flex-col gap-4">
        <Slider
          label="Longest edge"
          defaultValue={[2400]}
          min={800}
          max={6000}
          step={100}
          showValue
          format={(pixels) => `${pixels}px`}
        />
        <PopoverClose asChild>
          <Button size="sm">Export</Button>
        </PopoverClose>
      </div>
    </PopoverContent>
  </Popover>

  <DropdownMenu>
    <DropdownMenuTrigger asChild>
      <Button variant="secondary">Share</Button>
    </DropdownMenuTrigger>
    <DropdownMenuContent align="start">
      <DropdownMenuItem icon={RiFileCopyLine}>Copy link</DropdownMenuItem>
      <DropdownMenuItem icon={RiShareLine}>Post to the channel</DropdownMenuItem>
      <DropdownMenuItem icon={RiDownloadLine}>Download original</DropdownMenuItem>
      <DropdownMenuSeparator />
      <DropdownMenuItem icon={RiDeleteBinLine} destructive>Revoke the link</DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>
</div>
```

# Sheet

A panel docked to an edge of the viewport.

- Group: Overlays
- Import: `import { Sheet } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/sheet/
- Related: dialog, popover

## When to reach for it

A modal that needs room — a filter panel, a detail view. It IS a Dialog, docked; the sides are named in reading order, so `end` is the right in English and the left in Arabic.

## Anatomy

- **Scrim** (required) — The same --scrim at --z-overlay that Dialog uses — the same component, in fact, so the page behind is inert and scroll-locked exactly as it is under a dialog.
- **Panel** (required) — The docked box. start and end are a min(24rem, 92vw) column at full height; top and bottom are a full-width band capped at 85vh. A flex column that scrolls itself.
- **Title** (required) — title, typed as required rather than optional — there is no unnamed-sheet path to fall into, only a hidden-title one via hideTitle.
- **Description** — description, under the title, sharing the wrapper that hideTitle hides.
- **Close** (required) — The X in the top-end corner. Unlike Dialog there is no showClose to turn it off, so every sheet has one whichever edge it is docked to.

## Best practices

### Do

- Reach for a Sheet over a Dialog when the content is a list or a form long enough to scroll: it gets the full height of the viewport rather than Dialog’s 32rem by 85vh box, and the reader keeps the page edge as an anchor.
- Use top or bottom when the content is wide and short — a filter bar, a date range. start and end are a 24rem column, and a table pushed into one wraps into a ribbon.
- Name the sides start and end rather than reaching for left and right: each edge has its own literal class string carrying its own rtl: variant, so end arrives from the right in English and the left in Arabic with no second code path.
- Wrap the cancelling control in SheetClose so the close runs through Radix — a sheet closed by your own state setter leaves focus inside a panel that is no longer on the page.

### Don’t

- Do not re-declare the travel in className. The panel carries data-m22-animated, which removes its transform outright under reduced motion; a second transform of your own only gets the universal floor, so it still arrives — a hundredth of a millisecond later, from wherever you put it.
- An OverlayContainer whose element is not positioned docks the sheet to the wrong box: naming a container switches the panel from fixed to absolute, so an unpositioned container sends it to the nearest positioned ancestor rather than to the frame.
- It is a modal dialog, so the page behind is scroll-locked and pointer-inert: this is not the home for a filter panel the reader is meant to work alongside. That is a Popover, or a column in the layout.

## Accessibility

- Shares Dialog’s focus trap, Escape handling and scroll lock rather than reproducing them — a second focus trap is a second one to get wrong.
- The title is required, visible or not.

## Keyboard

- Escape — Closes it, and focus returns to the trigger.
- Tab — Cycles inside the sheet.

## Sheet

Re-export of `DialogPrimitive.Root`.

Radix Dialog root, trigger and close — a sheet IS a dialog, docked.

## SheetTrigger

Re-export of `DialogPrimitive.Trigger`.

## SheetClose

Re-export of `DialogPrimitive.Close`.

## SheetContent

A panel docked to an edge of the viewport. It is a modal dialog — Radix's, so the focus trap, the escape key, the scroll lock and the `aria-modal` wiring are the same ones `Dialog` gets. The only differences are where it sits and which way it arrives, which is why this shares that implementation rather than reproducing it: a second focus trap is a second focus trap to get wrong. The title is required, visible or not. A modal with no accessible name drops a screen reader into an unnamed region with no way back out. Portals into the element an enclosing `OverlayContainer` names, docking to that element's edge rather than the viewport's when there is one.

### Props

- `side` — `SheetSide` default `'end'`. Which edge it is docked to. `end` by default.
- `title` (required) — `ReactNode`.
- `description` — `ReactNode`.
- `hideTitle` — `boolean` default `false`. Hide the title visually while keeping it for assistive tech.
- `closeLabel` — `string` default `'Close'`. Accessible close action, supplied by the host locale.

Also accepts: `Omit<ComponentProps<typeof DialogPrimitive.Content>, 'title'>`.

## Example — sides

```tsx
import { Button, Field, Input, Sheet, SheetContent, SheetTrigger } from '@misoto22/design'

<div className="flex flex-wrap gap-3">
  {(['start', 'end', 'top', 'bottom'] as const).map((side) => (
    <Sheet key={side}>
      <SheetTrigger asChild>
        <Button variant="secondary" size="sm">{side}</Button>
      </SheetTrigger>
      <SheetContent side={side} title="Filters" description="Narrow the list.">
        <Field label="Search"><Input type="search" /></Field>
      </SheetContent>
    </Sheet>
  ))}
</div>
```

## Example — room to scroll

```tsx
<Sheet>
  <SheetTrigger asChild>
    <Button variant="secondary">Filter deploys</Button>
  </SheetTrigger>
  <SheetContent side="end" title="Filter deploys" description="Six branches, one search.">
    <div className="mt-4 flex flex-col gap-4">
      <Field label="Search">
        <Input type="search" placeholder="Branch or commit" />
      </Field>
      <fieldset className="m-0 flex flex-col gap-3 border-0 p-0">
        <legend className="mb-2 p-0 eyebrow text-(--ink-3-aa)">Branch</legend>
        {BRANCHES.map((branch) => (
          <label key={branch} className="flex cursor-pointer items-center gap-2.5 text-sm text-(--ink-2)">
            <Checkbox defaultChecked={branch === 'main'} />
            {branch}
          </label>
        ))}
      </fieldset>
      <div className="flex justify-end gap-3 pt-2">
        <SheetClose asChild>
          <Button variant="secondary">Cancel</Button>
        </SheetClose>
        <SheetClose asChild>
          <Button>Apply</Button>
        </SheetClose>
      </div>
    </div>
  </SheetContent>
</Sheet>
```

## Example — a wide band

```tsx
<Sheet>
  <SheetTrigger asChild>
    <Button variant="secondary">Set the reporting range</Button>
  </SheetTrigger>
  <SheetContent side="bottom" title="Reporting range" description="Applied to every chart on the page.">
    <div className="mt-4 grid gap-4 sm:grid-cols-4">
      <Field label="From">
        <Input type="date" defaultValue="2026-07-01" />
      </Field>
      <Field label="To">
        <Input type="date" defaultValue="2026-09-30" />
      </Field>
      <Field label="Region">
        <NativeSelect defaultValue="au">
          <option value="au">Australia</option>
          <option value="jp">Japan</option>
          <option value="all">Everywhere</option>
        </NativeSelect>
      </Field>
      <Field label="Compare with">
        <NativeSelect defaultValue="previous">
          <option value="previous">Previous period</option>
          <option value="year">Same period last year</option>
          <option value="none">Nothing</option>
        </NativeSelect>
      </Field>
    </div>
    <div className="mt-6 flex justify-end gap-3">
      <SheetClose asChild>
        <Button variant="secondary">Cancel</Button>
      </SheetClose>
      <SheetClose asChild>
        <Button>Apply</Button>
      </SheetClose>
    </div>
  </SheetContent>
</Sheet>
```

# ContextMenu

The menu a right-click opens.

- Group: Overlays
- Import: `import { ContextMenu } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/context-menu/
- Related: dropdown-menu

## When to reach for it

Never as the only way to reach an action. Touch users, trackpad users and keyboard users may have no way to open it.

## Anatomy

- **Trigger** (required) — The region a secondary click opens the menu over. Radix wraps children in its own inline span unless you pass asChild, and sets -webkit-touch-callout: none on it so the OS text callout does not fire first.
- **Panel** (required) — The portalled menu, placed at the POINTER rather than against the trigger — there is no side or align to set here, only the 8px collision padding that keeps it inside the viewport or the OverlayContainer frame.
- **Item** — A row, taking the same icon, destructive and disabled props as DropdownMenuItem — icon in either spelling — and highlighting on the same data-highlighted.
- **Label** — A mono eyebrow, on its own, and visual only. ContextMenuGroup is the one that heads rows: it renders role="group" and points its aria-labelledby at this.
- **Group** — A named section: role="group" around the rows, with label rendered inside it as the Label and named through aria-labelledby.
- **Separator** — A hairline between groups, as a real role="separator".

## Best practices

### Do

- Pass asChild and hand it the element itself: without it Radix inserts a span between you and your child, and that span becomes the flex or grid item while your card is laid out inside it as inline content.
- Build the same array of actions into a DropdownMenu behind an overflow button — the two take identical icon, destructive and disabled props, so one list feeds both and the right-click becomes the shortcut rather than the only door.
- Wrap the subtree in OverlayContainer when the right-clickable region lives in a scrolling or bounded frame: this is the one panel whose position the reader personally chose, and a flip against a viewport edge they cannot see lands it somewhere they did not point.

### Don’t

- Do not read “no touch support” as the whole story: Radix opens the menu on a 700ms long press for touch and pen, but cancels the moment the pointer moves — so on a scrollable list the long press and the scroll gesture compete and the scroll usually wins.
- A bare ContextMenuLabel over rows is a picture of a heading: Radix’s MenuLabel is a plain div with no role and nothing tying it to what follows, so the sections a sighted reader sees arrive as one undivided list. ContextMenuGroup renders both halves and wires them together.
- Radix defaults modal to true here too, so the page behind is scroll-locked and pointer-inert while the menu is open — a right-click menu over a long list stops the list moving under it, which is right for a short action list and wrong for anything the reader must scroll to answer.

## Keyboard

- Shift / F10 — Opens the menu from the keyboard, where the platform supports it.
- ↑ / ↓ — Moves between items.
- Escape — Closes it.

## ContextMenu

Re-export of `ContextMenuPrimitive.Root`.

Radix ContextMenu root and trigger, as typed passthroughs.

## ContextMenuTrigger

Re-export of `ContextMenuPrimitive.Trigger`.

## ContextMenuContent

The menu a right-click opens. Never the only way to reach an action. A context menu is opened by a secondary pointer button or a keyboard's own menu key, and a meaningful share of readers have neither — a touch user, someone on a trackpad they have not configured, anyone driving the page by keyboard alone. Whatever is in here belongs somewhere reachable too: a row's overflow button, a toolbar.

## ContextMenuItem

A row. Highlight follows `data-highlighted`, which covers hover and keyboard.

### Props

- `icon` — `RemixiconComponentType | ReactNode`. Optional leading icon. Either spelling — `icon={Copy}` passes the component and this sizes it, `icon={<Copy size={16} />}` passes the element and this places it.
- `destructive` — `boolean` default `false`. Paints the row as destructive. Use for delete, revoke, disconnect.

Also accepts: `ComponentProps<typeof ContextMenuPrimitive.Item>`.

## ContextMenuSeparator

Hairline divider between groups.

## ContextMenuLabel

Mono eyebrow heading, on its own. Visual only: Radix renders it as a bare `<div>` with no role. Reach for `ContextMenuGroup` when the eyebrow is a HEADING over rows; this is right for a line that heads nothing.

## ContextMenuGroup

A named section of a menu. The eyebrow alone was a picture of a heading: Radix's `MenuLabel` carries no role and no `aria-labelledby` wiring, so a sighted reader saw sections and a screen-reader user got one undifferentiated list. This renders the group, renders the label inside it, and points the one at the other.

### Props

- `label` — `ReactNode`. The eyebrow over the rows, and the group's accessible name.

Also accepts: `ComponentProps<typeof ContextMenuPrimitive.Group>`.

## Example — on a region

```tsx
<ContextMenu>
  <ContextMenuTrigger asChild>
    <div className="grid h-28 w-full max-w-sm place-items-center rounded-(--radius) border border-dashed border-(--rule-2) text-sm text-(--ink-3-aa)">
      Right-click anywhere in this box
    </div>
  </ContextMenuTrigger>
  <ContextMenuContent>
    <ContextMenuLabel>Frame</ContextMenuLabel>
    <ContextMenuItem icon={RiFileCopyLine}>Copy link</ContextMenuItem>
    <ContextMenuItem icon={RiDownloadLine}>Download original</ContextMenuItem>
    <ContextMenuSeparator />
    <ContextMenuItem icon={RiDeleteBinLine} destructive>Delete</ContextMenuItem>
  </ContextMenuContent>
</ContextMenu>
```

## Example — two doors

```tsx
<ContextMenu>
  <ContextMenuTrigger asChild>
    <div className="flex w-full max-w-sm items-center justify-between gap-3 rounded-(--radius) border border-(--rule) px-4 py-3">
      <Text size="sm" tone="strong" className="font-mono">
        kyoto-february.tif
      </Text>
      <DropdownMenu>
        <DropdownMenuTrigger asChild>
          <Button iconOnly aria-label="Actions for kyoto-february.tif" variant="ghost" size="sm">
            <RiMoreLine size={16} aria-hidden />
          </Button>
        </DropdownMenuTrigger>
        <DropdownMenuContent align="end">
          {ACTIONS.map((action) => (
            <DropdownMenuItem key={action.label} icon={action.icon} destructive={action.destructive}>
              {action.label}
            </DropdownMenuItem>
          ))}
        </DropdownMenuContent>
      </DropdownMenu>
    </div>
  </ContextMenuTrigger>
  <ContextMenuContent>
    {ACTIONS.map((action) => (
      <ContextMenuItem key={action.label} icon={action.icon} destructive={action.destructive}>
        {action.label}
      </ContextMenuItem>
    ))}
  </ContextMenuContent>
</ContextMenu>
```

## Example — a card trigger

```tsx
<ContextMenu>
  <ContextMenuTrigger asChild>
    <Card className="w-full max-w-sm">
      <CardHeader>
        <CardTitle as="h3">api.misoto22.com</CardTitle>
        <Badge tone="success">live</Badge>
      </CardHeader>
      <CardBody>
        Deployed from main four minutes ago. Right-click the card for its actions.
      </CardBody>
    </Card>
  </ContextMenuTrigger>
  <ContextMenuContent>
    <ContextMenuItem icon={RiExternalLinkLine}>Open the deployment</ContextMenuItem>
    <ContextMenuItem icon={RiPushpinLine}>Pin to the dashboard</ContextMenuItem>
    <ContextMenuItem icon={RiResetLeftLine} destructive>Roll back to the previous build</ContextMenuItem>
  </ContextMenuContent>
</ContextMenu>
```

# SearchableMenu

A menu of actions you can type into.

- Group: Overlays
- Import: `import { SearchableMenu } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/searchable-menu/
- Related: dropdown-menu, command, combobox

## When to reach for it

A DropdownMenu past about a dozen rows stops being scannable, and nesting submenus makes it worse. This is the same list with a filter over it. Not a Command palette: that is page-level and modal; this is anchored to a control.

## Anatomy

- **Trigger** (required) — A pill button built here rather than a Button: --control-h-sm tall, hairline bordered, with a chevron. Its accessible name is label, not the children you passed as its text.
- **Panel** (required) — A Popover with its padding removed and a flat 16rem width, so the filter and the list run edge to edge inside it. Not modal — this is a Popover, not a Dialog.
- **Filter** (required) — The Command input. Focus lands here on open and stays there; the highlight moves under it through aria-activedescendant.
- **Rows** — One per MenuAction, as listbox options. shortcut prints as a Kbd at the end of the row, destructive paints it --danger, and selecting one closes the menu before running onSelect.
- **Empty state** — emptyMessage, shown when the filter matches nothing. Say what would match rather than “no results”.

## Best practices

### Do

- Give an action keywords for the word a reader reaches for that the label does not print — “download” for Export, “bin” for Delete. The label’s own text is lifted into the filter for you; a label built only from elements prints none, and development warns SEARCHABLE_MENU_LABEL_UNREADABLE rather than shipping a row nothing matches.
- Make label the trigger’s visible text. It is set as aria-label on the trigger and overrides the children, so a button reading “Status” under a label of “Row actions” is announced as something the reader cannot say aloud (WCAG 2.5.3).
- Keep actions that share a group next to each other in the array: groups are built by walking the list and extending only the LAST one, so the same group name appearing again after other rows produces a second heading with identical text.

### Don’t

- It is a Popover underneath, so it is not modal: the page behind still scrolls while the filter is open and the panel is re-anchored as it does. A surface that should hold the page still is CommandDialog.
- className lands on the TRIGGER, not on the panel — the panel is a flat 16rem with no prop that widens it, so a long label wraps to a second line instead of the box growing to take it.
- The trigger is --control-h-sm — 36px comfortable, 30px under data-density="compact" — which is below the 44px pointer target (WCAG 2.5.5), and it is not the system Button, so variant and size do not reach it.

## Accessibility

- Inside a bounded frame — a device preview, an embedded console — wrap the subtree in `<OverlayContainer container={el}>`. The panel then renders into that element and collides with its edges instead of the viewport’s, and inherits the `dir` and `data-density` set there.
- The rows are options inside a listbox rather than menuitems, because filtering requires it — the highlight moves through aria-activedescendant while focus stays in the input, and a menu cannot do that.
- The trade is deliberate: a menu that cannot be filtered is worse for the reader than a listbox that runs actions.

## Keyboard

- Enter / Space — Opens the menu.
- ↑ / ↓ — Moves the highlight while focus stays in the filter.
- Enter — Runs the highlighted action.
- Escape — Closes without running anything.

## SearchableMenu

A menu of actions you can type into. The fourth corner of a square the system otherwise had three of, and the distinction is worth stating because reaching for the wrong one is easy: | | few options | many options | |---|---|---| | **sets a value** | `Select` | `Combobox` | | **runs an action** | `DropdownMenu` | `SearchableMenu` | A `DropdownMenu` past about a dozen rows stops being scannable, and the usual response — nesting submenus — makes it worse. This is the same list with a filter over it. Not the same thing as `Command`: that is a page-level palette, usually modal and usually bound to ⌘K. This is anchored to a control, like the menu it replaces. The rows are `option`s inside a listbox rather than `menuitem`s, because that is what the filtering pattern requires — the highlight moves through `aria-activedescendant` while focus stays in the input, and a menu cannot do that. The trade is deliberate: a menu that cannot be filtered is worse for the reader than a listbox that runs actions.

### Props

- `actions` (required) — `MenuAction[]`.
- `children` (required) — `ReactNode`. The trigger's text.
- `label` (required) — `string`. Names the menu for assistive tech.
- `searchPlaceholder` — `string` default `'Filter…'`.
- `emptyMessage` — `string` default `'Nothing matches.'`.
- `align` — `'start' | 'center' | 'end'` default `'start'`.
- `className` — `string`.

## Example — a filtered menu

```tsx
import { SearchableMenu, type MenuAction } from '@misoto22/design'

<div className="flex flex-col items-center gap-4">
  <SearchableMenu label="Actions" actions={actions} searchPlaceholder="Filter actions…">
    Actions
  </SearchableMenu>
  <p className="m-0 mono-meta text-(--ink-3-aa)">{last ? `ran: ${last}` : 'nine actions, one filter'}</p>
</div>
```

## Example — searchable keywords

```tsx
import { SearchableMenu, Text, type MenuAction } from '@misoto22/design'

<div className="flex flex-col items-center gap-4">
  <SearchableMenu label="Release actions" actions={actions} searchPlaceholder="Try spreadsheet…">
    Release actions
  </SearchableMenu>
  <Text size="sm" tone="muted">
    {last ? `ran: ${last}` : 'four opaque ids, matched by their keywords'}
  </Text>
</div>
```

## Example — groups in order

```tsx
import { SearchableMenu, type MenuAction } from '@misoto22/design'

<div className="flex flex-col items-center gap-4">
  <SearchableMenu
    label="Collection actions"
    actions={actions}
    searchPlaceholder="Filter actions…"
    emptyMessage="Nothing here matches. Try share, or delete."
  >
    Collection actions
  </SearchableMenu>
  <p className="m-0 mono-meta text-(--ink-3-aa)">{last ? `ran: ${last}` : 'two groups, written adjacent'}</p>
</div>
```

# Command

A filterable list of actions — the ⌘K surface.

- Group: Overlays
- Import: `import { Command } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/command/
- Related: combobox, dialog

## Anatomy

- **Input** (required) — CommandInput, the combobox, with the search glyph and a hairline under it. A hard 52px tall rather than a --control-h token, so it does not move with data-density.
- **List** (required) — CommandList, capped at 18rem inline and raised to 26rem inside CommandDialog, scrolling on its own six-pixel hairline bar.
- **Item** — A row: an icon ELEMENT, the label, an optional meta note and a shortcut printed as a Kbd. The highlighted row takes --accent-muted and a leading accent rule, because a fill alone is hard to catch while scrolling.
- **Empty** — CommandEmpty. cmdk renders an empty state only if one exists in the tree, so without it an unmatched filter leaves the input over a blank strip.
- **Footer** — CommandFooter and its CommandHint rows. A palette is a keyboard surface whose keys are invisible; this is the only place they get printed.

## Best practices

### Do

- Reach for CommandDialog, not the bare Command. The root is an inline bordered box with no scrim, no focus trap and no Escape handling of its own, so a palette built from it alone stays open until something else closes it.
- Always render CommandEmpty. cmdk shows an empty state only when one is present, so the palette that omits it answers a filter matching nothing with an input above a blank strip and no explanation.
- Pass CommandItem an icon element — icon={<Search size={16} />} — when the glyph needs its own size or colour, and the component — icon={Search} — when it does not. Both spellings work here and in DropdownMenuItem; they used to be the reverse of each other one import apart.
- Bind ⌘K yourself and then print it: nothing in this component listens for a key, so the palette has no shortcut until the app adds a keydown handler, and a CommandFooter is where the reader finds out it exists.

### Don’t

- Do not pass value to CommandItem unless the value is what a reader would type — cmdk filters on value first and only falls back to the row’s own text when there is none, so an id passed as the value makes the visible label unsearchable. Pass the label’s words as keywords when the id has to stay the value, which is what SearchableMenu does.
- CommandDialog renders with hideTitle and showClose={false}, so the palette has no visible heading and no visible close: Escape and the scrim are the only exits and neither announces itself. Print Escape in a CommandFooter rather than assuming it is known.
- Do not expect the palette to follow data-density — CommandInput is a hard 52px, not a --control-h token, so its field stays put while every other control in the app shrinks under compact.

## Accessibility

- The list filters as you type, the highlight moves with the arrow keys, and focus stays in the input. That last part is the ARIA combobox pattern and the part a home-made palette gets wrong.

## Keyboard

- ↑ / ↓ — Moves the highlight. Focus stays in the input, so what you typed stays editable.
- Enter — Runs the highlighted item.
- Escape — Closes the palette.

## Command

A filterable list of actions — the ⌘K surface. Built on cmdk rather than on a `Select` or a menu, because the interaction is neither: the list is filtered as you type, the highlighted row moves with the arrow keys while focus STAYS in the input, and Enter runs the highlighted row. That is the ARIA combobox pattern, and it is the part nobody should hand-roll — `aria-activedescendant` moving without focus moving is precisely where a home-made palette stops working with a screen reader.

## CommandInput

The filter field. Carries the search icon and the combobox semantics.

## CommandList

## CommandEmpty

Shown when the filter matches nothing. Say what would match, not "no results".

## CommandFooter

The key-hint strip along the bottom. A palette is a keyboard surface whose keys are invisible: nothing on screen says the arrows move the row or that Enter runs it, and a reader who reaches for the mouse has been failed by the design rather than by themselves.

## CommandHint

One key-and-verb pair inside a `CommandFooter`.

### Props

- `keys` (required) — `string[]`. The keys this hint describes, printed as `Kbd` chips.
- `children` (required) — `ReactNode`. What they do — a verb, lowercase, no sentence.

Also accepts: `Omit<ComponentProps<'span'>, 'children'>`.

## CommandGroup

## CommandSeparator

A divider between groups. Marked presentational, because ARIA permits a `listbox` to contain only `option` and `group` — and the library renders this as `role="separator"`, which puts a critical `aria-required-children` violation inside every palette that uses one. The grouping is already announced by the groups themselves, so removing the divider from the accessibility tree loses nothing.

## CommandItem

### Props

- `shortcut` — `string`. A shortcut printed at the end of the row.
- `icon` — `RemixiconComponentType | ReactNode`. A leading glyph. Either spelling — `icon={<Settings size={16} />}` passes the element, `icon={Settings}` passes the component and this sizes it. It is what makes a long list scannable — the eye sorts by shape before it reads, and forty identical rows of text defeat that.
- `meta` — `ReactNode`. A quiet note at the end of the row — what kind of thing this is, or its current state. Not a description: a palette that prints a sentence per row stops being scannable at about six of them.

Also accepts: `ComponentProps<typeof CommandPrimitive.Item>`.

## CommandDialog

The palette in a modal, which is how it is nearly always used. The dialog's own padding is removed: a palette is edge-to-edge, and its input is the first thing focus lands on.

### Props

- `open` (required) — `boolean`.
- `onOpenChange` (required) — `(open: boolean) => void`.
- `label` (required) — `string`. Names the palette for assistive tech.
- `inputLabel` — `string`. Names the search field when it should read differently from the dialog — a "Search records" field inside a "Library search" palette. Defaults to `label`. An `aria-label` on `CommandInput` cannot do this: the field is labelled by reference, and a reference outranks an `aria-label`.
- `children` (required) — `ReactNode`.
- `shouldFilter` — `boolean`. Pass `false` when the host has already filtered the rows — a server search or an index of its own. The palette would otherwise filter them a second time against the input and hide results the host meant to show.
- `onOpenAutoFocus` — `DialogContentProps['onOpenAutoFocus']`. Runs as the dialog moves focus in. Prevent the default to place focus yourself.
- `onCloseAutoFocus` — `DialogContentProps['onCloseAutoFocus']`. Runs as the dialog hands focus back on close. The default returns it to a `DialogTrigger`, and a palette opened by a shortcut has none, so focus falls to the page. Prevent the default and focus what opened it.
- `onEscapeKeyDown` — `DialogContentProps['onEscapeKeyDown']`. Runs before Escape closes the dialog. Prevent the default to keep it open, as a nested view stepping back does.

## Example — inline

```tsx
<Command label="Command palette" className="w-full max-w-md">
  <CommandInput placeholder="Type a command or search…" />
  <CommandList>
    <CommandEmpty>No command matches that. Try “theme”.</CommandEmpty>
    {/* The glyph is what makes a long list scannable: the eye sorts by
        shape before it reads. */}
    <CommandGroup heading="Navigate">
      <CommandItem value="components" icon={<RiShapesLine aria-hidden />} meta="49" shortcut="C">
        Components
      </CommandItem>
      <CommandItem value="foundations" icon={<RiRulerLine aria-hidden />} shortcut="F">
        Foundations
      </CommandItem>
      <CommandItem value="principles" icon={<RiScales3Line aria-hidden />} shortcut="P">
        Principles
      </CommandItem>
      <CommandItem value="templates" icon={<RiCompassLine aria-hidden />}>
        Templates
      </CommandItem>
    </CommandGroup>
    <CommandSeparator />
    <CommandGroup heading="Theme">
      <CommandItem value="light" icon={<RiSunLine aria-hidden />} meta="current">
        Switch to light
      </CommandItem>
      <CommandItem value="dark" icon={<RiMoonLine aria-hidden />}>
        Switch to dark
      </CommandItem>
    </CommandGroup>
  </CommandList>
  {/* Nothing on screen otherwise says the arrows move the row or that
      Enter runs it. */}
  <CommandFooter>
    <CommandHint keys={['↑', '↓']}>navigate</CommandHint>
    <CommandHint keys={['↵']}>run</CommandHint>
    <CommandHint keys={['esc']}>close</CommandHint>
  </CommandFooter>
</Command>
```

## Example — dialog

```tsx
) => document.removeEventListener('keydown', onKey)
  }, [])

  return (
<div className="flex flex-col items-center gap-3">
  <Button variant="secondary" onClick={() => setOpen(true)}>
    Open the palette
  </Button>
  <p className="m-0 text-sm text-(--ink-3-aa)">
    or press <Kbd>⌘</Kbd> <Kbd>K</Kbd>
  </p>
  <CommandDialog open={open} onOpenChange={setOpen} label="Command palette">
    <CommandInput placeholder="Type a command…" />
    <CommandList>
      <CommandEmpty>No command matches that.</CommandEmpty>
      <CommandGroup heading="Navigate">
        <CommandItem value="components" onSelect={() => setOpen(false)}>Components</CommandItem>
        <CommandItem value="principles" onSelect={() => setOpen(false)}>Principles</CommandItem>
      </CommandGroup>
    </CommandList>
  </CommandDialog>
</div>
```

## Example — values and keywords

```tsx
<Command label="Project commands" className="w-full max-w-md">
  <CommandInput placeholder="Try revert, or teammate…" />
  <CommandList>
    <CommandEmpty>Nothing matches. Try branch, export or revert.</CommandEmpty>
    <CommandGroup heading="Release">
      <CommandItem
        value="roll back the release"
        keywords={['revert', 'undo', 'previous']}
        icon={<RiResetLeftLine size={16} aria-hidden />}
        meta="release"
      >
        Roll back the release
      </CommandItem>
      <CommandItem
        value="create a release branch"
        keywords={['cut', 'branch', 'tag']}
        icon={<RiGitBranchLine size={16} aria-hidden />}
        meta="git"
      >
        Create a release branch
      </CommandItem>
    </CommandGroup>
    <CommandGroup heading="Project">
      <CommandItem
        value="invite a collaborator"
        keywords={['teammate', 'member', 'people']}
        icon={<RiGroupLine size={16} aria-hidden />}
        meta="people"
      >
        Invite a collaborator
      </CommandItem>
      <CommandItem
        value="export the deploy log"
        keywords={['csv', 'download', 'spreadsheet']}
        icon={<RiFileDownloadLine size={16} aria-hidden />}
        meta="data"
      >
        Export the deploy log
      </CommandItem>
    </CommandGroup>
  </CommandList>
</Command>
```

# Spinner

The one “working” indicator — a ring, never a shimmer.

- Group: Feedback
- Import: `import { Spinner } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/spinner/
- Related: skeleton, progress

## When to reach for it

A wait short enough that the shape of what is coming does not matter. Longer than that, use a Skeleton.

## Anatomy

- **Live region** (required) — The outer span, and the only part with a voice. It carries role="status" while there is a label; pass label={null} and it turns into an aria-hidden box with no role at all.
- **Ring** (required) — The inner span — 14px, 18px or 26px of border on a transparent box, and the only element size, tone and className reach.
- **Leading quarter** (required) — border-t, drawn in --ink at the default tone and in the inherited colour at current. It is the whole difference between a ring and a plain circle, which is why a still ring still reads as unfinished.
- **Screen-reader label** — An sr-only span holding label, present unless label is null. Announced once, when the spinner mounts, and never again.

## Best practices

### Do

- Pass tone="current" for a spinner on any filled ground: the default draws the leading quarter in --ink over a --rule-2 track, and inside a primary Button both of those are the ground it is sitting on.
- Announce the arrival somewhere else. The label is read once on mount and nothing is said on the way out, so a reader who heard “Loading projects” is never told the projects came.
- Reach for label={null} only inside a control that already names the operation — it hides the whole element from assistive tech rather than merely dropping the text, so a silenced spinner standing on its own is a wait nobody is told about.

### Don’t

- label defaults to the bare word “Loading”, so a Spinner written without the prop ships the exact announcement the prop exists to prevent — the default is a placeholder, not a value.
- className is merged onto the ring AFTER size and tone, so it beats both: <Spinner size="lg" className="size-4" /> is a 16px ring, and the prop whose whole job was naming the size is the one that lost.
- Nothing here sets aria-busy — Button does that for its own control — so a spinner laid over a panel leaves the panel announced as ready while its contents are stale and its buttons still take clicks.

## Accessibility

- label names the specific thing being waited on; three spinners all saying “Loading” tell a screen reader nothing.
- label={null} silences it for use inside a control that already announces the operation.
- Spins under motion-safe only; the static ring still reads as unfinished because the leading quarter is darker.

## Spinner

The system's one "working" indicator. A ring, not a blurred glow and not a shimmer: the White Reset has no light source, so depth and softness are not available to it. The leading quarter is the only thing that distinguishes the ring from a plain circle, which is why the track stays a hairline — a spinner is a hint that time is passing, not a feature of the page. It spins under `motion-safe` only. A reader who has asked for less motion gets a static ring, which still reads as "not finished" because the leading quarter is darker than the track. For a wait long enough that the reader would otherwise wonder whether the page is broken, prefer `Skeleton` — a shape that describes what is coming beats a dot that describes nothing. `className` reaches the RING, alongside `size` and `tone`, and overrides them: every utility a caller has for a spinner is about the ring, and merged onto the wrapper instead `className="size-8"` grew an invisible box around an unchanged 18px circle. Layout still works from there — the wrapper is `inline-flex` and takes the ring's margin box as its own.

### Props

- `size` — `'sm' | 'md' | 'lg'` default `'md'`. 14px / 18px / 26px. Match the size of the type it sits beside.
- `tone` — `'default' | 'current'` default `'default'`. `default` draws the ring against the page — a hairline track in the rule colour with the leading quarter in ink. `current` draws it in the inherited text colour, which is what a spinner inside a filled button needs: on an ink ground an ink ring is invisible.
- `className` — `string`. Merged onto the RING, after `size` and `tone`, so it overrides both.
- `label` — `string | null` default `'Loading'`. Announced to assistive tech. Pass the specific thing being waited on ("Loading projects"), not the generic word — a screen reader user hearing "Loading" three times cannot tell which three things. Pass `null` for a spinner that sits inside a control which already names the operation (a button whose own label changes to "Saving…"), so the two are not read out twice.

Also accepts: `HTMLAttributes<HTMLSpanElement>`.

## Example — sizes

```tsx
import { Spinner } from '@misoto22/design'

<div className="flex items-center gap-6">
  <Spinner size="sm" label="Loading, small" />
  <Spinner size="md" label="Loading, medium" />
  <Spinner size="lg" label="Loading, large" />
</div>
```

## Example — on a filled ground

```tsx
import { Button, Spinner } from '@misoto22/design'

<div className="flex flex-wrap items-center gap-4">
  <Button loading>Saving…</Button>
  <span className="inline-flex items-center gap-2.5 rounded-(--radius) bg-(--feature-surface) px-4 py-3 text-sm text-(--on-feature)">
    <Spinner size="sm" tone="current" label={null} />
    Indexing 1,204 frames
  </span>
</div>
```

## Example — which wait shape

```tsx
<div className="grid w-full gap-8 sm:grid-cols-3">
  <div className="flex flex-col gap-3">
    <Text size="xs" tone="muted">
      Unknown duration
    </Text>
    <Spinner label="Checking the deploy" />
  </div>
  <div className="flex flex-col gap-3">
    <Text size="xs" tone="muted">
      Known shape
    </Text>
    <SkeletonPage label="Loading the changelog" className="flex flex-col gap-3">
      <SkeletonLine className="h-2.5 w-20" />
      <SkeletonBlock className="h-10" />
    </SkeletonPage>
  </div>
  <div className="flex flex-col gap-3">
    <Text size="xs" tone="muted">
      Known fraction
    </Text>
    <Progress value={41} label="Uploading footage.mov" showValue />
  </div>
</div>
```

# Skeleton

The shape of the page, before the page.

- Group: Feedback
- Import: `import { Skeleton } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/skeleton/
- Related: spinner, empty-state

## When to reach for it

A wait the reader would otherwise think was a broken page. A shape that describes what is coming beats a dot that describes nothing.

## Anatomy

- **Frame** (required) — SkeletonPage: the div carrying role="status", aria-busy="true" and the single pulse. It is the only part that speaks and the only part that moves — the shapes inside it do neither.
- **Label** (required) — The sr-only sentence inside the frame, from the required label prop. Every shape is aria-hidden, so this one sentence is the entire loading state for a screen reader.
- **Fill** — Skeleton itself: a --stone rectangle one line tall — h-3 — and, being a div, already full width. Height is the one dimension the element does not have on its own, so that is the one the base supplies; anything in className replaces it.
- **Line, Block and Circle** — The three presets over that fill. SkeletonLine is a 12px pill and takes its width from the caller, SkeletonBlock only sets --radius-sm, and SkeletonCircle is a fixed 36px round.
- **Paragraph** — SkeletonText: three lines by default, the last at 62% so it ends mid-measure the way prose does rather than squaring off into a table.

## Best practices

### Do

- Wrap the shapes in SkeletonPage even when there is only one bar. The role, the aria-busy and the pulse all live on the frame, so parts used loose are aria-hidden, silent and completely still — a grey rectangle that never resolves.
- Give every Skeleton the height of the thing it stands in for. The base falls back to one line, so a block left unsized is no longer invisible — it is a 12px bar where a 160px plate is about to land, and the page jumps by the difference.
- Make whatever replaces the skeleton announce itself or take focus. aria-busy never flips to false here — the frame is unmounted, not updated — so the end of the wait is the disappearance of the only thing that was speaking.

### Don’t

- Do not add animate-pulse to a part. The frame already animates opacity and a second ramp on a child multiplies with it, so the part beats at a rate the shape around it does not. Reduced motion is not the reason it is wrong: the rule in keyframes.css is a universal floor on animation-duration and transition-duration, so a hand-written Tailwind animation is clamped along with everything else. data-m22-animated is a component asserting its motion is decorative, not the mechanism that does the cancelling.
- Do not nest one SkeletonPage inside another. Each is a role="status" region with its own sr-only sentence, so a page assembled from two skeleton sections announces two loading messages and marks two regions busy for a single wait.
- Do not carry a skeleton between screens unedited. SkeletonCircle is 36px and SkeletonLine is 12px tall whatever they stand in for, so a copied avatar mount and a copied heading are two guaranteed reflows the moment the real content lands.

## Accessibility

- One live region on the wrapper; every shape inside it is aria-hidden.
- One pulse on the wrapper, not one per bar, so the page breathes together.

## Skeleton

The fill every skeleton part is drawn from: `--stone`, at the height of one line until something says otherwise. Deliberately NOT a shimmer. A shimmer sweeps a highlight across the shape, which implies a light source; the White Reset has none, so the sweep reads as a bug rather than as loading. The whole page breathes together instead — see `SkeletonPage`, which owns the single pulse. `h-3` is a default rather than a design. A `<div>` is already full width, so height was the one dimension a caller could omit and get nothing for — a bare `<Skeleton />` was a zero-height box, which is not a small skeleton but an absent one. Twelve pixels is the height `SkeletonLine` already chose, and any class the caller passes replaces it.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## SkeletonLine

A line of type. Height is the line's; width is how far it runs.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## SkeletonBlock

A block: an image mount, a plate, a chart.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## SkeletonCircle

A circle: an avatar, a marker.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## SkeletonText

A paragraph. The last line is short, because real prose ends mid-measure. A block of equal full-width bars reads as a table, and the reader then flinches when a paragraph arrives instead.

### Props

- `lines` — `number` default `3`. How many lines of prose to stand in for.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## SkeletonPage

The frame a skeleton sits in: the live region, and the single pulse. One `animate-pulse` on the wrapper rather than one per part, so the page breathes together instead of shimmering out of phase — twenty independently animated bars is a visual noise floor, not a loading state. A skeleton whose shape does not match what replaces it is worse than none: it promises a layout and then the page jumps out from under the reader. Compose the parts to match the real thing, and change both together.

### Props

- `label` (required) — `string`. What is loading, in words. Announced once; the shapes themselves are `aria-hidden`, so this sentence is the entire experience for a screen reader and "Loading" alone tells it nothing.
- `children` (required) — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## Example — record list

```tsx
import { SkeletonBlock, SkeletonLine, SkeletonPage, SkeletonText } from '@misoto22/design'

<SkeletonPage label="Loading projects">
  <div className="border-t border-(--rule-hard)">
    {[0, 1].map((row) => (
      <div key={row} className="grid gap-x-8 gap-y-4 border-b border-(--rule) py-6 sm:grid-cols-[9rem_minmax(0,1fr)]">
        <SkeletonBlock className="h-24" />
        <div>
          <SkeletonLine className="h-2.5 w-24" />
          <SkeletonBlock className="mt-4 h-5 w-[min(100%,16rem)]" />
          <SkeletonText className="mt-5" lines={2} />
        </div>
      </div>
    ))}
  </div>
</SkeletonPage>
```

## Example — parts

```tsx
import { SkeletonBlock, SkeletonCircle, SkeletonLine, SkeletonPage, SkeletonText } from '@misoto22/design'

<SkeletonPage label="Loading the example" className="flex flex-col gap-5">
  <div className="flex items-center gap-3">
    <SkeletonCircle />
    <SkeletonLine className="w-32" />
  </div>
  <SkeletonBlock className="h-20" />
  <SkeletonText lines={3} />
</SkeletonPage>
```

## Example — shape match

```tsx
import { Avatar, SkeletonBlock, SkeletonCircle, SkeletonLine, SkeletonPage, Text } from '@misoto22/design'

<div className="grid w-full gap-8 sm:grid-cols-2">
  <div className="flex flex-col gap-3">
    <Text size="xs" tone="muted">
      While it loads
    </Text>
    <SkeletonPage label="Loading the comment" className="flex gap-3">
      <SkeletonCircle />
      <div className="min-w-0 flex-1">
        <SkeletonLine className="h-2.5 w-24" />
        <SkeletonBlock className="mt-3 h-4 w-full" />
        <SkeletonBlock className="mt-2 h-4 w-[62%]" />
      </div>
    </SkeletonPage>
  </div>
  <div className="flex flex-col gap-3">
    <Text size="xs" tone="muted">
      What lands
    </Text>
    <div className="flex gap-3">
      <Avatar alt="" fallback="HC" />
      <div className="min-w-0 flex-1">
        <Text size="xs" tone="muted">
          Henry Chen
        </Text>
        <Text size="sm" className="mt-2">
          Rebased onto main and the typecheck is green again. Merging once CI finishes.
        </Text>
      </div>
    </div>
  </div>
</div>
```

# Progress

A bar that fills, or sweeps when the end is unknown.

- Group: Feedback
- Import: `import { Progress } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/progress/
- Related: spinner

## Anatomy

- **Track** (required) — The Radix root: 4px of --stone at the pill radius, carrying role="progressbar" and aria-label from label. It is full width by default, so it takes the measure of whatever column it is dropped into.
- **Fill** — The indicator, in --accent, sized by width rather than a translate so it grows from the inline start in a right-to-left document too. Present only when value is a number.
- **Sweep** — What replaces the fill when value is null: a quarter-width --accent bar travelling the track on transform alone, mirrored under rtl so it never reads as progress running backwards. Under prefers-reduced-motion it stops where it is drawn rather than filling the track.
- **Value row** — label on the left, a tabular-nums percentage on the right, above the track. It renders only when showValue is set and value is a number, which makes it the only place label is ever visible.
- **Column** — The flex wrapper holding the row and the track. className lands here; every other prop is forwarded to the Radix root instead.

## Best practices

### Do

- Pass showValue on any determinate bar. It is the only thing that puts label on screen — without it the name exists solely as aria-label, and a sighted reader is left with an unlabelled 4px rule and no number.
- Switch value back to null the moment the estimate stops being real. The fill transitions its width over --duration-slow, so a number that revises downward animates backwards and the reader watches progress undo itself.
- Set max to the real total rather than converting to a percentage yourself. The width and aria-valuemax come off the same number, so the picture and the announcement cannot drift — but a value past the ceiling still clamps, and an underestimated total parks the bar at full for the rest of the operation rather than admitting the estimate was wrong.

### Don’t

- Do not pass a max that is not a positive number. Radix refuses it, prints its own warning and falls back to 100, and the width falls back with it — so value={40} paints and announces forty per cent of a ceiling nobody chose.
- Do not read the resting sweep as a position. Under prefers-reduced-motion it stops at a quarter of the track, which is what a determinate bar at 25% looks like — the announcement is the only thing that tells the two apart, and it is the reason omitting value matters.
- className styles the column, not the track, so a height utility passed that way stretches the wrapper and leaves the 4px bar exactly where it was.

## Accessibility

- Omitting value drops aria-valuenow, so a screen reader hears “indeterminate” rather than a number that is a guess.
- label is required — a bare bar announces nothing.
- The width is computed from value and max, the same pair Radix announces as aria-valuenow and aria-valuemax, so what is drawn and what is said cannot disagree.

## Progress

A bar that fills, or sweeps when the end is unknown. Flat: a track in `--stone`, a fill in `--ink`. The White Reset has no gradient and no glow, so the only thing carrying the reading is the boundary between the two.

### Props

- `value` — `number | null` default `null`. 0 to `max`, which is 100 unless you say otherwise. Omit (or pass `null`) when the duration is genuinely unknown — the bar then sweeps instead of filling, and Radix drops `aria-valuenow` so a screen reader is told "indeterminate" rather than a number that is a guess.
- `max` — `number`. What `value` is measured against. 100 by default. The width is computed from it as well as announced from it. It used to be only announced: `max` reached Radix through `...rest` while the width was `value` clamped to 100, so `max={500}` with `value={100}` painted a full bar and told a screen reader "100 of 500". A max that is not a positive number is refused the way Radix refuses it — Radix warns, and both fall back to 100 rather than drawing one picture and announcing another.
- `label` (required) — `string`. Names what is progressing. Required: a bare bar announces nothing.
- `showValue` — `boolean` default `false`. Prints the percentage above the bar. Only meaningful when `value` is set.

Also accepts: `Omit<ComponentProps<typeof ProgressPrimitive.Root>, 'value' | 'max'>`.

## Example — determinate

```tsx
import { Progress } from '@misoto22/design'

<div className="w-full max-w-sm">
  <Progress value={62} label="Uploading photos" showValue />
</div>
```

## Example — indeterminate

```tsx
import { Progress, Text } from '@misoto22/design'

<div className="flex w-full max-w-sm flex-col gap-3">
  <Text size="sm" tone="strong">
    Rebuilding the search index
  </Text>
  <Progress label="Rebuilding the search index" />
  <Text size="xs" tone="muted">
    Started 40 seconds ago. No estimate yet.
  </Text>
</div>
```

## Example — bytes into percent

```tsx
import { Progress, Text } from '@misoto22/design'

<div className="flex w-full max-w-sm flex-col gap-2">
  <Progress
    value={Math.round((18.2 / 29.4) * 100)}
    label="Uploading footage.mov"
    showValue
  />
  <Text size="xs" tone="muted">
    18.2 MB of 29.4 MB
  </Text>
</div>
```

# Alert

A message about the page, in place.

- Group: Feedback
- Import: `import { Alert } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/alert/
- Related: toast, error-state

## When to reach for it

Something the reader needs to see and may need to act on. Something they only need to notice is a Toast.

## Anatomy

- **Region** (required) — The container, carrying the role and the aria-live the tone chooses, plus the tone’s ground. It is not focusable and it is not a landmark, so it exists for the reader who is already there and for the announcement.
- **Mark** — The tone’s Remix Icon glyph at 18px — RiInformationLine, RiCheckboxCircleLine, RiAlertLine or RiCloseCircleLine — aria-hidden, so it doubles the colour for sighted readers only. hideIcon removes it.
- **Title** — title, as a medium-weight paragraph in --ink. A p and not a heading, so it never appears in a screen reader’s heading list.
- **Body** — children, in --ink-2 at relaxed leading, offset from the title only when there is a title to offset from.
- **Action** — action, below the body and inside the region — so its label is read out with the message rather than being something the reader has to go looking for.

## Best practices

### Do

- Mount the Alert when there is something to say and unmount it when there is not. A region kept permanently in the page announces only when its words change, so a second failed submit carrying the same message is announced to nobody.
- Move focus after a failed submit — to the Alert or to the field it names. The component announces and then stays put, so a keyboard reader hears the error from wherever they were standing and has no way back to it.
- Put the retry, the link or the escape in action rather than describing it in the prose. It sits inside the live region, which is the difference between the announcement telling the reader what to do and merely telling them something is wrong.

### Don’t

- hideIcon takes away one of the two things that double the colour, and the tinted grounds are 13–16% alpha over paper. With the mark gone the severity is carried by a wash the reader may not resolve at all, so the words have to say it outright.
- info is the default and the only tone with a border and no tint — --paper-2 inside a --rule-2 hairline, which is a card. An Alert written without tone therefore looks like page furniture rather than like a notice.
- Do not stack alerts as a running log. Each one is its own live region, so five on a page are five announcements competing for the same speech queue, and a danger among them is assertive enough to cut off the four that explain it.

## Accessibility

- danger is role="alert" and interrupts; the other three are role="status" and wait for a pause.
- Colour is doubled by an icon and by the words.

## Alert

A message about the page, in place. Carries `role="alert"` for the danger tone and `role="status"` for the rest, which is the difference between interrupting the reader and waiting for a pause. Getting that backwards is the usual accessibility failure here: a "saved" toast that talks over someone mid-sentence, or a payment error that is never announced at all. The tone is the message's SEVERITY, not its decoration. Colour is doubled by an icon and by the words, so the meaning survives both monochrome printing and colour-blindness.

### Props

- `tone` — `AlertTone` default `'info'`.
- `title` — `ReactNode`.
- `children` — `ReactNode`.
- `action` — `ReactNode`. Optional action — a retry, a link to the settings that fix this.
- `hideIcon` — `boolean` default `false`. Hides the leading icon for a dense inline notice.

Also accepts: `Omit<HTMLAttributes<HTMLDivElement>, 'title'>`.

## Example — tones

```tsx
import { Alert, Button } from '@misoto22/design'

<div className="flex w-full flex-col gap-3">
  <Alert title="Read-only mode">A migration is running; edits are paused until it finishes.</Alert>
  <Alert tone="success" title="Deployed">misoto22-site is live at commit a1b2c3d.</Alert>
  <Alert tone="warning" title="Token expires in 6 days">Rotate it before the next release.</Alert>
  <Alert
    tone="danger"
    title="Upload failed"
    action={<Button size="sm" variant="secondary">Try again</Button>}
  >
    The file exceeds the 25 MB limit.
  </Alert>
</div>
```

## Example — a failed submit

```tsx
import { Alert, Button, Field, Input } from '@misoto22/design'

<div className="flex w-full max-w-sm flex-col gap-5">
  <Alert
    tone="danger"
    title="We could not send the invitation"
    action={<Button size="sm" variant="secondary">Try again</Button>}
  >
    The address bounced when we checked it.
  </Alert>
  <Field label="Email" error="Enter an address we can deliver to.">
    <Input defaultValue="henry@exmaple.com" />
  </Field>
</div>
```

## Example — inside the panel

```tsx
import { Alert, Button, Card, CardBody, CardHeader, CardTitle } from '@misoto22/design'

<Card className="w-full max-w-md">
  <CardHeader>
    <CardTitle>Deploy history</CardTitle>
  </CardHeader>
  <CardBody>
    <Alert
      tone="warning"
      title="History is unavailable"
      action={<Button size="sm" variant="secondary">Reload</Button>}
    >
      The build log service did not answer. Everything else on this page is current.
    </Alert>
  </CardBody>
</Card>
```

# EmptyState

A collection with nothing in it — yet.

- Group: Feedback
- Import: `import { EmptyState } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/empty-state/
- Related: error-state, skeleton

## When to reach for it

Nothing went wrong. The copy says what to do, not what failed.

## Anatomy

- **Frame** (required) — A centred column with 80px of padding above and below and --page-pad either side. View-scale, and carrying no role and no live region of its own.
- **Medallion** — The optional Remix Icon glyph at 24px inside a 56px --stone circle, aria-hidden. Decoration that gives the column something to start from, never the message.
- **Title** (required) — title in the heading face at --fs-sub, rendered through Heading. level picks the element and defaults to 2; the size does not follow it, so the title is --fs-sub at every level.
- **Description** — description in --ink-3-aa, capped at 24rem so it stays a readable measure while the column stays centred.
- **Action** — The one thing to do next, 32px below the description and the only interactive element the frame offers.

## Best practices

### Do

- Announce the swap yourself. This component has no role and no live region, so replacing a SkeletonPage with it removes the region that said “Loading projects” and puts nothing in its place — a screen reader is left at the last thing it heard.
- Say which kind of empty this is. The same component serves a collection that is new and one that a filter has emptied, and “No projects yet” shown over an active filter tells the reader their projects are gone.
- Set level from the heading above it. The default of 2 is right directly under a page’s h1; inside a section that already has its own h2, pass 3. Get it wrong and the outline gains a hole a screen reader navigates by.

### Don’t

- Do not show it for a failed request. A reader told the collection is empty acts on it — creating the record they already have, or reporting a data loss that never happened — and the recovery from that costs more than the error page would have.
- Do not put it inside a card or a panel. 160px of vertical padding is sized to stand in for a view, and in a bordered box it reads as a box with a hole in it.
- Do not write a paragraph into description. It is capped at 24rem and centred, so long copy becomes a narrow ragged column that the eye returns from before the sentence that mattered.

## EmptyState

A collection with nothing in it — yet. Distinct from `ErrorState`: nothing went wrong here, so the copy says what to do rather than what failed. The two are different components because the shared temptation — one component with a `variant` — produces error pages that read like empty folders.

### Props

- `icon` — `RemixiconComponentType`. Optional Remix Icon glyph, shown muted inside a quiet circle.
- `title` (required) — `ReactNode`.
- `description` — `ReactNode`.
- `action` — `ReactNode`. The one thing to do next. An empty state without an action is a dead end.
- `level` — `HeadingLevel` default `2`. The heading level `title` opens, in the document the empty state lands in. Defaults to `2`, which is the placement this component is sized for: it stands in for a whole view inside a page that already has an `h1`, so the level below that one is the level that does not leave a hole in heading navigation. Under a section that already has its own `h2`, pass `3`. The default was `3` and fixed, which was wrong in the ordinary case and impossible to correct — the documentation could name the rule but a caller had no prop to follow it with. `2` is the common case rather than a compromise, and it is optional rather than required because the correct placement has one answer often enough that making every existing call site restate it would buy nothing. The size does not follow the level. `title` renders at `--fs-sub` at every level, because moving a state down the outline is a fact about the document and not a request for smaller type.

Also accepts: `Omit<HTMLAttributes<HTMLDivElement>, 'title'>`.

## Example — default

```tsx
import { Button, EmptyState } from '@misoto22/design'

<EmptyState
  icon={RiInboxLine}
  title="No projects yet"
  description="Everything you publish will show up here. Start with the one you are already building."
  action={<Button>New project</Button>}
/>
```

## Example — emptied by a filter

```tsx
import { Button, EmptyState, Tag } from '@misoto22/design'

<div className="w-full">
  <div className="flex flex-wrap items-center gap-2 border-b border-(--rule) pb-4">
    <Tag active>Archived</Tag>
    <Tag active>2019</Tag>
  </div>
  <EmptyState
    icon={RiFilterOffLine}
    title="No projects match these filters"
    description="Archived and 2019 are both on. Clearing them brings back 34 projects."
    action={<Button variant="secondary">Clear filters</Button>}
  />
</div>
```

## Example — empty or failed

```tsx
import { Button, EmptyState, ERROR_ACTION_CLASS, ErrorState } from '@misoto22/design'

<div className="grid w-full gap-8 md:grid-cols-2">
  <EmptyState
    className="py-10"
    icon={RiFileTextLine}
    title="No invoices yet"
    description="The first invoice you issue for this client will appear here."
    action={<Button>New invoice</Button>}
  />
  <ErrorState
    className="min-h-0 pt-0"
    level={2}
    code="503"
    heading="Invoices could not be loaded"
    message="The billing service did not answer. Your invoices are not affected."
    action={<a href="/status" className={ERROR_ACTION_CLASS}>Check service status</a>}
  />
</div>
```

# ErrorState

A page that could not be shown.

- Group: Feedback
- Import: `import { ErrorState } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/error-state/
- Related: empty-state, alert

## Anatomy

- **Screen** (required) — A section at least one viewport tall, painting its own --paper ground and holding 96px of clearance for a header. It is a page, not a block.
- **Code** (required) — code at the top of the type ladder, aria-hidden. The largest thing on the screen and the one thing a screen reader is never told.
- **Heading** (required) — heading through Heading at --fs-heading, and the first thing said aloud. level defaults to 1 because this replaces the page; the size is fixed, so an error state demoted to an h2 is the same size it was.
- **Message** (required) — message at --measure-record, which is where the explanation of what happened goes.
- **Action** (required) — The way back. Required rather than optional, and the only focusable thing on the screen.

## Best practices

### Do

- Render it instead of the page, not inside it. It is a full viewport with its own ground and its own top clearance, so nested in a layout that already has a header it adds a second screen of blank below the fold.
- Announce it or move focus into it on a client-side failure. There is no role and no live region here, so a route that swaps the whole screen for this one changes everything a sighted reader can see and says nothing at all.
- Point action at a real destination rather than at history. A reader often arrives at an error page cold or from a link, so going back returns them to the page that just failed, or to nothing.

### Don’t

- Do not leave level at 1 inside an app shell that already has an h1. Two h1s on one document leave a heading list that no longer says which one is the page — pass level={2} for a state rendered into a shell rather than instead of one.
- Do not put a request id, a trace or a sentence into code. It is set at --fs-title with leading-none and it is aria-hidden, so anything long becomes the biggest object on the page and is simultaneously invisible to the reader most likely to have to quote it.
- Do not use it when one panel failed and the rest of the page still works. Replacing the whole screen throws away the navigation the reader needed to get out; an Alert inside the panel keeps both the error and the way past it.

## Accessibility

- The big status code is aria-hidden; the heading immediately after says the same thing in words.

## ERROR_ACTION_CLASS

Re-export of `'text-sm text-(--ink) underline decoration-(--rule-2) underline-offset-4 transition-colors duration-(--duration-fast) hover:decoration-(--ink)'`.

The recovery affordance's look, exported so every error page offers the same one rather than each inventing a link style.

## ErrorState

A page that could not be shown. The code is set at the top of the type ladder and marked `aria-hidden` — read aloud, "404" before the sentence explaining it is noise, and the heading immediately after says the same thing in words.

### Props

- `code` (required) — `ReactNode`. The status, set large — "404", "500". Decorative; the heading carries the meaning.
- `heading` (required) — `ReactNode`.
- `message` (required) — `ReactNode`.
- `action` (required) — `ReactNode`. The way back. Render it with ERROR_ACTION_CLASS.
- `level` — `HeadingLevel` default `1`. The heading level `heading` opens, in the document the error state lands in. Defaults to `1`, and that is not a compromise: this component replaces the page rather than sitting inside one — its own ground, its own viewport, its own top clearance — so the page's single `h1` is the one it renders. Kept as the default, existing call sites render exactly the markup they did. The prop exists because the level was previously fixed, and the one piece of advice this component's documentation gives about headings — do not put it inside a shell that already has an `h1` — was advice a caller had no way to take. Now they do: inside a shell that owns the page heading, pass `2`. The size does not follow the level. `heading` renders at `--fs-heading` at every level; a failure demoted in the outline is the same failure.

Also accepts: `HTMLAttributes<HTMLElement>`.

## Example — not found

```tsx
import { ERROR_ACTION_CLASS, ErrorState } from '@misoto22/design'

<ErrorState
  className="min-h-0 pt-0"
  level={2}
  code="404"
  heading="Page not found"
  message="The page you're looking for has moved, or never existed."
  action={<a href="/" className={ERROR_ACTION_CLASS}>Back home</a>}
/>
```

## Example — a way back

```tsx
import { ERROR_ACTION_CLASS, ErrorState } from '@misoto22/design'

<ErrorState
  className="min-h-0 pt-0"
  level={2}
  code="500"
  heading="Something went wrong at our end"
  message="The request reached us and failed while it was being handled. Nothing you sent was lost."
  action={
    <div className="flex flex-wrap items-center gap-6">
      <a href="/" className={ERROR_ACTION_CLASS}>Back to the dashboard</a>
      <a href="/status" className={ERROR_ACTION_CLASS}>Service status</a>
    </div>
  }
/>
```

## Example — the trace id

```tsx
import { Code, ERROR_ACTION_CLASS, ErrorState } from '@misoto22/design'

<ErrorState
  className="min-h-0 pt-0"
  level={2}
  code="500"
  heading="We could not load this deploy"
  message={
    <>
      The build service timed out. Quote <Code>req_8f31c0</Code> if you report it — it
      identifies this request.
    </>
  }
  action={<a href="/support" className={ERROR_ACTION_CLASS}>Contact support</a>}
/>
```

# Toast

A transient confirmation, mounted once near the app root.

- Group: Feedback
- Import: `import { Toaster } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/toast/
- Related: alert

## When to reach for it

Something succeeded and needs no response. A toast is dismissed by time, and time is not an acknowledgement.

## Anatomy

- **Toaster** (required) — The single mount, bottom-right by default. It renders sonner’s list into a portal at the end of body, which is why the theming is an inline style — a stylesheet scoped to the app never reaches there.
- **Token style** (required) — sonner’s --normal-bg, --normal-text, --normal-border and --border-radius pointed at --paper, --ink, --rule-2 and --radius, plus the sans face. The --success-* and --error-* pairs join them only when richColors is on, which is the only state sonner reads them in.
- **Notification region** (required) — sonner’s own section, aria-live="polite" and labelled “Notifications altKey+KeyT”. Taken out of the tab order and reachable by that shortcut, and polite for every toast type — there is no assertive path.
- **Toast** — One entry, pushed by toast() or one of its typed variants and removed from the DOM after sonner’s default four seconds, which this wrapper does not change. Three are visible at once; the rest queue.
- **Close button** — On by default here, where sonner ships it off. Without it the only ways out are the timer and a swipe, and a keyboard has no swipe.

## Best practices

### Do

- Mount exactly one Toaster. Every toast() call reaches every Toaster listening, so one in a root layout and one in a nested layout render the same message twice, in two corners.
- Set duration per toast for anything longer than a short sentence. The wrapper leaves sonner’s default at four seconds — roughly ten words read aloud — and the rest of the message is removed from the page before it has been read.
- Keep the message to what happened. Three toasts are visible at a time and the rest wait their turn, so a loop that toasts per item shows the last three and delivers the others after the reader has moved on.
- Set data-mode on <html> and leave theme alone. sonner hard-codes the description’s colour per theme — #3f3f3f, overridden only under its dark theme — so a page painted dark by an attribute the Toaster was not following put that grey on --paper at roughly 1.85:1, and every toast with a description lost its second half.

### Don’t

- Nothing a reader must act on belongs here. Four seconds is a deadline they were never told about, and the button is in a portal at the end of body that a keyboard reaches last — an Undo in a toast is an offer most people cannot take.
- Nothing a reader must read twice belongs here either — an error code, a reference, a name to type elsewhere. There is no history: once the timer expires the text is out of the DOM and unrecoverable.
- Do not report a failure with toast.error and consider it reported. The region is polite for every type, so the failure queues behind whatever the screen reader was already saying and can be removed before its turn comes.
- Do not pass theme="system". It reads prefers-color-scheme, not data-mode, so a reader who overrode a dark operating system with a light page gets a dark toast over it — the same defect the old default had, pointing the other way.

## Toaster

Transient confirmations, mounted once near the app root. A toast is for something that succeeded and needs no response. Anything the reader must act on belongs in the page — a toast is dismissed by time, and time is not an acknowledgement. `theme` follows `data-mode`. sonner defaults to `light` and hard-codes the description's colour per theme — `#3f3f3f`, overridden only under `[data-sonner-theme=dark]` — so a Toaster that never passed `theme` put dark grey text on this system's `--paper: #0d0d0d` and every `toast(title, { description })` lost its second half. Pass `theme` yourself and that wins; sonner's own `system` is the one value not to reach for, since it reads the OS rather than the attribute the page is actually painted from. `richColors` stays off by default: sonner's rich palette is not this system's status scale, and turning it on reintroduces chroma the White Reset spends only on state.

## Example — default

```tsx
import { Button, Toaster, toast } from '@misoto22/design'

<div className="flex flex-wrap items-center gap-3">
  <Toaster />
  <Button variant="secondary" onClick={() => toast('Draft saved')}>Neutral</Button>
  <Button variant="secondary" onClick={() => toast.success('Deployed to production')}>Success</Button>
  <Button variant="secondary" onClick={() => toast.error('Could not reach the API')}>Error</Button>
</div>
```

## Example — long enough to read

```tsx
import { Button, toast } from '@misoto22/design'

<div className="flex flex-wrap items-center gap-3">
  <Button variant="secondary" onClick={() => toast('Draft saved')}>
    Four seconds
  </Button>
  <Button
    variant="secondary"
    onClick={() =>
      toast('Draft saved. The version from 14:02 is still in the history if you want it back.', {
        duration: 8000,
      })
    }
  >
    Eight seconds
  </Button>
</div>
```

## Example — not in a toast

```tsx
import { Alert, Button, toast } from '@misoto22/design'

<div className="flex w-full max-w-md flex-col gap-4">
  <Alert tone="danger" title="Payment declined">
    The card was declined. Quote reference pay_4Kd91 when you call the bank.
  </Alert>
  <Button
    variant="secondary"
    onClick={() =>
      toast.error('The card was declined. Quote reference pay_4Kd91 when you call the bank.')
    }
  >
    The same message as a toast
  </Button>
</div>
```

# Badge

A count or a state, set in mono so it reads as metadata.

- Group: Display
- Import: `import { Badge } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/badge/
- Related: tag, status-pill

## When to reach for it

One fact about one record. If it names what something is ABOUT, that is a Tag.

## Anatomy

- **Chip** (required) — The <span>: inline-flex on the --radius-sm corner, mono at 12px with wide tracking. The mono face is the whole signal — it is what tells a reader this is metadata rather than a word of the sentence it sits in.
- **Ground** (required) — The tone’s fill — --stone for neutral, the soft tint of --ok, --warn or --danger for the three status tones, and nothing at all for outline.
- **Border** (required) — Always drawn, and transparent for every tone but outline, so the box reserves the pixel either way and swapping tone at runtime moves nothing beside it.
- **Content** (required) — children, with a 6px gap between them — so a StatusDot or a Kbd set beside the text spaces itself without a wrapper.

## Best practices

### Do

- Leave tone at neutral unless the badge names a STATE: the three status tones are the only chroma this system spends, and a badge that is red because the page wanted red is the thing the scale exists to prevent.
- Reach for outline when the badge sits on --stone already — every other tone fills its own ground, and a neutral badge on stone is a chip with no visible edge at all.
- Keep it to a count, a word, or a short state. It is 12px mono sized for one line, so a phrase in it is prose set in the metadata face and wraps inside a box that was never given a second line.

### Don’t

- A row of them is a Tag list drawn in the wrong component: Badge has no active state, so the filter bar it turns into cannot show which facet is on.
- A neutral Badge and an inactive Tag are the same corner, the same padding and the same 12px mono, separated by one ink step — so a row that mixes states and topics reads as one undifferentiated run of chips.
- There is no dismiss affordance here. A × written into children is text inside the accessible name, so the badge is announced as “beta ×” and the close it advertises does not exist.

## Accessibility

- Not interactive. A badge with an onClick is a control a keyboard cannot reach.
- The status tones double their colour with words, so the meaning survives monochrome and colour-blindness.

## Badge

A count, a state, a small inline marker. Mono and small, so it reads as metadata rather than as content. A badge is not interactive — if it can be clicked or dismissed it is a `Tag` or a button, and giving this one an `onClick` produces a control a keyboard cannot reach.

### Props

- `children` (required) — `ReactNode`.
- `tone` — `BadgeTone` default `'neutral'`. `neutral` is the default and the right answer nearly always. The three status tones are the system's only chroma and are bound to STATE — a badge that is red because the design wanted a red badge is the thing this scale exists to prevent.

Also accepts: `HTMLAttributes<HTMLSpanElement>`.

## Example — tones

```tsx
import { Badge } from '@misoto22/design'

<div className="flex flex-wrap items-center gap-2">
  <Badge>12</Badge>
  <Badge tone="outline">Draft</Badge>
  <Badge tone="success">Deployed</Badge>
  <Badge tone="warning">Degraded</Badge>
  <Badge tone="danger">Failed</Badge>
</div>
```

## Example — with a status dot

```tsx
import { Badge, StatusDot } from '@misoto22/design'

<div className="flex flex-wrap items-center gap-2">
  <Badge tone="success">
    <StatusDot size="sm" pulse={false} /> Deployed
  </Badge>
  <Badge tone="warning">
    <StatusDot size="sm" tone="warning" pulse={false} /> Degraded
  </Badge>
  <Badge tone="danger">
    <StatusDot size="sm" tone="danger" pulse={false} /> Failed
  </Badge>
</div>
```

## Example — on a stone ground

```tsx
import { Badge } from '@misoto22/design'

<div className="flex flex-wrap items-center gap-2 rounded-(--radius) bg-(--stone) p-4">
  <Badge>Neutral</Badge>
  <Badge tone="outline">Outline</Badge>
</div>
```

# Tag

A subject label — a topic, a technology, a filter facet — that filters with onClick and is dismissed with onRemove.

- Group: Display
- Import: `import { Tag } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/tag/
- Related: badge, status-pill

## When to reach for it

Several sit together and the reader scans them. One fact about one record is a Badge. A chip the reader can toggle or dismiss is this one with onClick or onRemove, not a fourth component.

## Anatomy

- **Chip** (required) — The <span>: the same --radius-sm corner, the same 10px by 4px padding and the same 12px mono as a Badge, with no border of its own.
- **Ground** (required) — --stone at rest, --accent once active, cross-fading over --duration-fast. The accent is the system’s one pointer at a choice, which is why it is what selection is drawn in.
- **Label** (required) — children, in --ink-3-aa — the AA floor rather than a light grey — and in --accent-foreground once active.
- **Remove button** — On onRemove only: a real <button type="button"> after the label, holding a 12px X and named by removeLabel. The drawn box is 16px, under the 24px WCAG 2.5.8 floor, so an inset pseudo-element takes the hit area out to 24 without changing the drawing or pushing the chips apart.
- **Filter control** — On onClick only: the chip itself becomes the <button>, carrying aria-pressed from active. Given onRemove as well, the label splits into its own button beside the X — two siblings, never one inside the other — and takes the leading padding with it so the target is the chip up to the X rather than just the words.

## Best practices

### Do

- Filter with onClick, not with a wrapper. The chip becomes the button itself, so the padding is part of the target and the focus ring is drawn around what the reader sees — and a removable chip does not end up with a button inside a button.
- Pass active on a chip that toggles, and leave it off one that does not. aria-pressed is read off that same value, so the accent fill and the state assistive tech hears cannot drift apart; omitted, nothing is announced, which is the right answer for a chip that navigates rather than toggles.
- Give a filter row an off state to come back to — active is the accent, and a row in which every tag is active spends the mark that means “this one” on all of them.
- Name the subject in removeLabel — "Remove Rust filter", not "Remove". It is required alongside onRemove because eight chips whose controls are all called Remove is eight controls a screen reader cannot tell apart.

### Don’t

- It carries no tone at all, so a tag cannot say success or danger. Colouring one in through className puts a hue into the system by hand and leaves the accent as the only thing that still reads as selected.
- One tag on its own is a Badge that lost its tone. The component is built to be scanned in a row, and a single chip beside a record is one fact about one record.
- Do not wrap it in a button of your own. Around a removable chip that is a button inside a button — invalid markup a parser splits into siblings, leaving a DOM neither the author nor the accessibility tree expects. onClick is what that wrapper was for.

## Accessibility

- Presentational until it is given a handler. onClick makes the chip a real button carrying aria-pressed from active, so the focus ring and the pressed state stay on the element that draws them.
- Both controls are real <button type="button">s and siblings, so Tab reaches each, Enter and Space fire each, and neither submits the form it happens to sit in.
- removeLabel is required with onRemove and is the button’s whole accessible name — the X itself is aria-hidden.

## Tag

A subject label — a topic, a technology, a filter facet — that can filter with `onClick` and be dismissed with `onRemove`. Distinct from `Badge`, which carries a state or a count. A tag names what something is ABOUT, so several sit together in a row and the reader scans them; a badge is one fact about one record. This is where a `Token` component would have gone. It was not built: a token is a tag with a remove button, and the difference between the two is one prop, not one component. The system already ships three things that look alike — `Badge`, `Tag`, `StatusPill` — and a fourth whose whole distinction is an X on the end would be the one a call site picks by coin toss. Presentational until it is given a handler, and the component owns both interactive cases rather than leaving one to a wrapper at the call site. That is not a convenience: a wrapping `<button>` around a chip that already holds the remove `<button>` is a button inside a button, which no parser keeps and no accessibility tree reports the way it was written. Given both, the chip renders the label and the X as SIBLING buttons — the label takes the leading padding with it, so it is the whole of the chip up to the X rather than the words with dead padding around them.

### Props

- `children` (required) — `ReactNode`.
- `active` — `boolean`. Renders the pressed/selected look, and declares the chip a toggle. An interactive chip reads `aria-pressed` off this same value, so the accent fill and the state a screen reader hears cannot drift apart. Leave it off for a chip whose `onClick` navigates or opens something: a control that is neither pressed nor unpressed is better announced as neither than as "not pressed".
- `onClick` — `() => void`. Makes the chip ITSELF the filter control. This prop exists because the alternative did not survive contact with `onRemove`. The advice used to be to wrap the tag in a button at the call site, which is fine on its own and invalid the moment the chip is also removable: the remove control is a real `<button>`, so the wrapper puts a button inside a button — markup the parser splits into siblings, leaving a DOM neither the author nor the accessibility tree expects. With this the wrapper is never written. The chip carries the click, the focus ring and the pressed state on the element that draws them, and a removable filter chip renders its two controls side by side instead of one inside the other.
- `onRemove` — `() => void`. Called when the reader dismisses the chip.
- `removeLabel` — `string`. The remove button's accessible name. Name the subject, not the action.

Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'onClick'>`.

## Example — default

```tsx
import { Tag } from '@misoto22/design'

<div className="flex flex-wrap items-center gap-2">
  <Tag active>All</Tag>
  <Tag>TypeScript</Tag>
  <Tag>Rust</Tag>
  <Tag>Photography</Tag>
</div>
```

## Example — a filter row

```tsx
import { Tag } from '@misoto22/design'

<div className="flex flex-wrap items-center gap-2">
  {FACETS.map((facet) => (
    <button
      key={facet}
      type="button"
      aria-pressed={chosen.includes(facet)}
      onClick={() => toggle(facet)}
      className="rounded-(--radius-sm)"
    >
      <Tag active={chosen.includes(facet)}>{facet}</Tag>
    </button>
  ))}
</div>
```

## Example — tag badge or pill

```tsx
import { Badge, StatusPill, Tag } from '@misoto22/design'

<div className="flex max-w-md flex-col gap-3">
  <div className="flex flex-wrap items-center gap-2">
    <span className="font-heading text-[length:var(--fs-item)] text-(--ink)">
      Retrieval rewrite
    </span>
    <Badge tone="success">Merged</Badge>
  </div>
  <div className="flex flex-wrap items-center gap-2">
    <Tag>TypeScript</Tag>
    <Tag>pgvector</Tag>
    <Tag>Search</Tag>
  </div>
  <StatusPill pulse={false}>Deployed to production</StatusPill>
</div>
```

## Example — a removable chip

```tsx
import { Tag } from '@misoto22/design'

<div className="flex flex-wrap items-center gap-2">
  {chosen.map((facet) => (
    <Tag
      key={facet}
      onRemove={() => setChosen((current) => current.filter((item) => item !== facet))}
      removeLabel={`Remove the ${facet} filter`}
    >
      {facet}
    </Tag>
  ))}
  {chosen.length === 0 && <span className="text-sm text-(--ink-3-aa)">No filters</span>}
</div>
```

# Kbd

A key on a keyboard, set as one.

- Group: Display
- Import: `import { Kbd } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/kbd/
- Related: badge

## Anatomy

- **Key** (required) — The <kbd>: a --rule-2 hairline on the --radius-sm corner, min-w-[1.6em] so a single character is a cap rather than a sliver, and 0.8em type so the whole cap scales with the copy around it.
- **Legend** (required) — children, printed verbatim. One key per element — the space between two of them is a real space in the markup, not a separator the component draws.

## Best practices

### Do

- Write one Kbd per key. A whole chord in one box — ⌘K — is a single cap with two glyphs in it, and the min-w-[1.6em] that makes one character square just stretches to hold both.
- Let it take its size from its surroundings: it is set in em, so the same shortcut printed in a heading and in body copy comes out right in both. Pinning it to px is how one shortcut ended up three sizes on one page.
- Give a glyph-only key an aria-label — ⌘, ⌥ and ⇧ are read out as their Unicode names or skipped entirely, so a Mac shortcut written in symbols alone is a silent instruction.

### Don’t

- An outline Badge and a Kbd are near enough identical on screen, so the choice between them is entirely about meaning: <kbd> says the reader presses this, and a badge shaped like a key invites a press nothing answers.
- Nothing here binds anything. The element is typography, so a key printed for a shortcut no handler listens for is documentation of a feature the page does not have.

## Accessibility

- Renders <kbd>, which carries the meaning a styled <span> does not.

## Kbd

A key on a keyboard, set as one. Renders a `<kbd>`, which is the element that means this — a `<span>` styled to look like a key tells a screen reader nothing. Sized in `em` so it tracks whatever type it sits beside rather than fixing itself at one px value, which is how the same shortcut ended up three different sizes across a page. Every dimension here tracked its context except the leading, which was a literal `1.6` — the body's READING leading, on a chip that is never a paragraph. Inside a control it therefore stood proud of the label beside it and pushed the whole box past its own height token: the masthead's search field measured 39px against a 36px `sm`, and it was this keycap doing it. `--control-lh` is the leading a one-line box gets, and this is one.

### Props

- `children` (required) — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLElement>`.

## Example — default

```tsx
import { Kbd } from '@misoto22/design'

<p className="m-0 text-sm text-(--ink-2)">
  Press <Kbd>⌘</Kbd> <Kbd>K</Kbd> to open the palette, or <Kbd>Esc</Kbd> to close it.
</p>
```

## Example — one cap per key

```tsx
import { Kbd, Text } from '@misoto22/design'

<div className="flex flex-col gap-3">
  <Text size="sm">
    Reformat the file with <Kbd aria-label="Command">⌘</Kbd>{' '}
    <Kbd aria-label="Shift">⇧</Kbd> <Kbd>P</Kbd>.
  </Text>
  <Text size="sm">
    On Windows and Linux the same chord is <Kbd>Ctrl</Kbd> <Kbd>Shift</Kbd> <Kbd>P</Kbd>.
  </Text>
</div>
```

## Example — sized by its copy

```tsx
import { Heading, Kbd, Text } from '@misoto22/design'

<div className="flex flex-col gap-4">
  <Heading level={3}>
    Press <Kbd>/</Kbd> to search
  </Heading>
  <Text>
    The same <Kbd>/</Kbd> works from anywhere on the page.
  </Text>
  <Text size="xs" tone="muted">
    Shortcut: <Kbd>/</Kbd>
  </Text>
</div>
```

# Avatar

A person, as a circle, with initials until the image lands.

- Group: Display
- Import: `import { Avatar } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/avatar/

## Anatomy

- **Circle** (required) — The Radix root: a --rule hairline over --stone, overflow hidden, and one of three fixed squares — 28px, 36px or 48px. It carries role="img" and alt as its own name, because it is the one element in here that is always rendered.
- **Image** — Rendered only when src is given, object-cover so a portrait crops to the circle instead of distorting. Its own alt is empty on purpose — the circle around it is what names the person, and a second name here is the same person read twice.
- **Initials** — The Radix fallback: mono, uppercase, --ink-3-aa, and aria-hidden. Radix shows it while the image is loading and once it has failed, which is why it does not flash on every render the way a hand-rolled onError swap does.

## Best practices

### Do

- Write alt for the person, not for the row: the circle carries it whether or not a photograph ever arrives, so a list where photographs are optional announces every person rather than every second one.
- Pass initials that hold up on their own: fallback is required because the image is the optional half, and most rows of a real list render as this element rather than as a photograph.
- Let Radix own the swap rather than reaching for onError — it flips to the fallback only once the image has actually failed, which is what keeps the initials from appearing for a frame before the cache answers.

### Don’t

- The avatar is not the control. sm is 28px and md is 36px, both under the 44px pointer-target floor (WCAG 2.5.8), and the root is a <span> nothing has made focusable — an account menu made by hanging onClick on it is unreachable and undersized at once.
- children is deliberately omitted from the props: the image and the fallback are the only two things that go in the circle, and the root is overflow-hidden, so a presence dot placed inside it is clipped by the very border that makes it round.

## Accessibility

- alt names the circle itself, as role="img", so an avatar with no photograph still says who it is.
- An empty alt is correct when the name is already printed beside it: the circle then takes no role at all rather than an unnamed one, and leaves the tree entirely.
- The initials are aria-hidden — read aloud beside a name the root already gives, they are noise.

## Avatar

A person, as a circle. Wraps Radix so the fallback appears only after the image has actually failed or is still loading — a hand-rolled `onError` swap flashes the initials on every render before the cache answers. The ROOT carries the accessible name, not the image. `alt` on the image reaches the DOM only when `src` does, and the initials are aria-hidden, so an avatar with no photograph announced nothing at all however carefully `alt` was written — and a user list where photographs are optional is full of them.

### Props

- `src` — `string`.
- `alt` (required) — `string`. Describes the person, not the picture. It names the circle itself rather than the image inside it, because the image is the optional half and most rows of a real list render as initials. Empty string is correct and deliberate when the name is already printed beside the avatar: the circle then leaves the accessibility tree entirely, rather than repeating a name a screen reader has just read.
- `fallback` (required) — `string`. Shown while the image loads and if it never does. Usually initials.
- `size` — `'sm' | 'md' | 'lg'` default `'md'`.

Also accepts: `Omit<ComponentProps<typeof AvatarPrimitive.Root>, 'children'>`.

## Example — sizes

```tsx
import { Avatar } from '@misoto22/design'

<div className="flex items-center gap-3">
  <Avatar size="sm" alt="" fallback="HC" />
  <Avatar size="md" alt="" fallback="MI" />
  <Avatar size="lg" alt="" fallback="22" />
</div>
```

## Example — a name beside it

```tsx
import { Avatar, Text } from '@misoto22/design'

<ul className="m-0 flex list-none flex-col gap-4 p-0">
  <li className="flex items-center gap-3">
    <Avatar alt="" fallback="HC" />
    <div className="flex flex-col">
      <Text as="span" size="sm" tone="strong">Henry Chen</Text>
      <Text as="span" size="xs" tone="muted">Design systems</Text>
    </div>
  </li>
  <li className="flex items-center gap-3">
    <Avatar alt="" fallback="RW" />
    <div className="flex flex-col">
      <Text as="span" size="sm" tone="strong">Rui Wang</Text>
      <Text as="span" size="xs" tone="muted">Infrastructure</Text>
    </div>
  </li>
</ul>
```

## Example — inside the control

```tsx
import { Avatar, Button } from '@misoto22/design'

<div className="flex flex-wrap items-center gap-3">
  <Button variant="secondary">
    <Avatar size="sm" alt="" fallback="HC" />
    Henry Chen
  </Button>
  <Button variant="ghost">
    <Avatar size="sm" alt="" fallback="RW" />
    Switch account
  </Button>
</div>
```

# StatusDot

The dot beside a status word.

- Group: Display
- Import: `import { StatusDot } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/status-dot/
- Related: status-pill

## Anatomy

- **Box** (required) — The aria-hidden <span> the whole thing lives in — 8px square at md, 7px at sm, inline-grid and shrink-0 so it stays circular in a flex row however long the label beside it runs.
- **Dot** (required) — An absolutely-positioned filled circle in --ok, --warn, --danger or --ink-3-aa. It is the only part of this component tone touches.
- **Halo** — A second ring of the same colour on the m22-halo keyframes, present only while pulse is true. A separate element rather than a box-shadow, because a shadow in this system is never blurred.

## Best practices

### Do

- Set pulse={false} for anything settled. It defaults to true, so a dot for a build that finished or a status that will not change today carries a halo announcing that something is happening right now.
- Reach for StatusPill the moment you find yourself writing the dot and its label together — that pairing assembled per call site is how one site ended up with three dot sizes and two pulse timings for the same state.
- Let it sit directly in the flex row beside its label: shrink-0 is what keeps it round, and a dot wrapped in a div that can shrink comes out an ellipse as soon as the label runs long.

### Don’t

- An aria-label on the dot buys nothing — aria-hidden is still set, and a hidden element has no name to give. A call site with no visible label is a state no screen reader ever reports.
- sm and md are 7px and 8px, one pixel apart. That is an optical adjustment for sitting beside smaller type, not a size scale, and nothing in a layout should be built on the difference.

## Accessibility

- aria-hidden without exception: it repeats a state the adjacent label already names.
- The halo is motion-safe, so a reader who asked for less motion gets a still dot.

## StatusDot

The dot beside a status word. `aria-hidden` without exception: the dot repeats a state the adjacent label already names, and a screen reader announcing "available" twice is worse than not announcing the decoration at all. If a call site has no visible label, the fix is a label, not an `aria-label` on the dot. The halo is a separate absolutely-positioned ring rather than a box-shadow, because Law 2 of this system is that a shadow is never blurred — and it is motion-safe, so a reader who asked for less motion gets a static dot.

### Props

- `size` — `'sm' | 'md'` default `'md'`. 7px / 8px. `md` is the default.
- `tone` — `StatusTone` default `'success'`.
- `pulse` — `boolean` default `true`. A halo that grows and dissolves, for "live right now". Off for a settled state.

Also accepts: `HTMLAttributes<HTMLSpanElement>`.

## Example — tones

```tsx
import { StatusDot } from '@misoto22/design'

<div className="flex flex-wrap items-center gap-6 text-sm text-(--ink-2)">
  <span className="inline-flex items-center gap-2"><StatusDot /> Live</span>
  <span className="inline-flex items-center gap-2"><StatusDot tone="warning" pulse={false} /> Degraded</span>
  <span className="inline-flex items-center gap-2"><StatusDot tone="danger" pulse={false} /> Down</span>
  <span className="inline-flex items-center gap-2"><StatusDot tone="neutral" pulse={false} /> Idle</span>
</div>
```

## Example — live and settled

```tsx
import { StatusDot } from '@misoto22/design'

<div className="flex flex-col gap-3 text-sm text-(--ink-2)">
  <span className="inline-flex items-center gap-2">
    <StatusDot /> Deploying 0.4.1 to production
  </span>
  <span className="inline-flex items-center gap-2">
    <StatusDot pulse={false} /> Deployed 0.4.0, fourteen minutes ago
  </span>
</div>
```

## Example — down a table

```tsx
import { StatusDot, Table, TBody, TD, TH, THead, TR } from '@misoto22/design'

<Table caption="Service health" density="compact">
  <THead>
    <TR>
      <TH>Service</TH>
      <TH>State</TH>
      <TH align="end">Last check</TH>
    </TR>
  </THead>
  <TBody>
    <TR>
      <TD>api.misoto22.com</TD>
      <TD>
        <span className="inline-flex items-center gap-2">
          <StatusDot size="sm" pulse={false} /> Healthy
        </span>
      </TD>
      <TD align="end">30s ago</TD>
    </TR>
    <TR>
      <TD>Search index</TD>
      <TD>
        <span className="inline-flex items-center gap-2">
          <StatusDot size="sm" tone="warning" pulse={false} /> Rebuilding
        </span>
      </TD>
      <TD align="end">2m ago</TD>
    </TR>
    <TR>
      <TD>Image pipeline</TD>
      <TD>
        <span className="inline-flex items-center gap-2">
          <StatusDot size="sm" tone="neutral" pulse={false} /> Paused
        </span>
      </TD>
      <TD align="end">1h ago</TD>
    </TR>
  </TBody>
</Table>
```

# Steps

A numbered sequence, as a rail — one thing after another, with a rule through them.

- Group: Display
- Import: `import { Steps } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/steps/
- Related: diagram, article

## When to reach for it

A pipeline, a migration, a recipe: an order with no branches. The moment something forks or points at something else it is a Diagram, and drawing a fork as a list hides it.

## Anatomy

- **Rail** (required) — The <ol>, carrying --step-size — one number that three rules read: the marker’s own box, where the connector starts, and where it is centred.
- **Marker** (required) — A 2rem circle per step, aria-hidden: the position number, or a blank hairline node when marker is "rule". Filled with --accent for the current one.
- **Connector** — A hairline drawn on every item but the last, placed absolutely from the foot of that marker to the foot of its row — so it spans the gap rather than running behind the markers, and no tail hangs off the end of the sequence.
- **Title** (required) — step.title, at 15px in the interface face. The step’s name — a noun, not a description of what happens in it.
- **Note** — step.note, a mono line under the title: what the step is made of, what it costs, what it uses.

## Best practices

### Do

- Use marker="rule" for a sequence of states. “Queued, running, done” is an order rather than an instruction list, and a digit in front of each one tells the reader they are steps to perform.
- Mark at most one step current: it is the one thing the rail states rather than draws, and two filled markers put the process in two places at once.
- Pass label when no heading names the sequence — it is the list’s only name, so without it the rail is announced as five items belonging to nothing.
- Retune the rail through --step-size on the list rather than by restyling the marker: the marker box, the connector’s start and its centring all read that one number, and moving one of the three leaves the line beginning in mid-air.

### Don’t

- A fork drawn here is a fork the reader never sees. The connector runs from each step to the next one in the array and to nothing else, so two branches flatten into four consecutive steps and the choice between them leaves the figure entirely.
- steps={[]} renders null rather than an empty rail, so a list filtered down to nothing leaves a heading standing over a gap unless the call site checks the length itself.
- Nothing here is clickable and the props spread onto the <ol>, so an onClick meant for a step lands on the whole list. A sequence the reader is meant to move through is a Breadcrumb or a Tabs.

## Accessibility

- An <ol>, because the order IS the content — a stack of divs says nothing about sequence.
- aria-current="step" marks the filled one, which is the only thing here a reader could not infer from the reading order.
- The markers and the connector are aria-hidden: the number is the list position, and screen readers already announce that.

## Steps

A numbered sequence, as a rail. The shape a pipeline actually has: one thing after another, each with a name and a line of detail, and a rule running through them so the eye reads them as one process rather than as five unrelated rows. It is the figure a technical post reaches for most often after a diagram, and it is NOT a diagram — nothing branches, nothing points at anything, and drawing it with boxes and arrows says otherwise. The connector is drawn on the ITEM rather than as a full-height line behind the markers, so it starts under one and stops above the next instead of running through both — and so the last step has no tail hanging off it. That is the detail that separates a rail from a list with a border on it. An `<ol>`, because the order is the content. `aria-current="step"` marks the filled one, which is the only thing here a screen reader could not otherwise infer from the order it is read in.

### Props

- `steps` (required) — `Step[]`.
- `label` — `string`. Names the sequence for assistive tech when no heading does.
- `marker` — `'number' | 'rule'` default `'number'`. How the marker is drawn. `number` counts from one and is right for a pipeline, a recipe, a migration. `rule` drops the digit for a plain hairline node, which is what a sequence of states wants — "queued, running, done" is an order, not a numbered list.

Also accepts: `Omit<HTMLAttributes<HTMLOListElement>, 'children'>`.

## Example — default

```tsx
import { Steps } from '@misoto22/design'

<Steps
  label="How an answer is built"
  steps={[
    { title: 'Corpus', note: 'Blog MDX · project database · profile' },
    { title: 'Chunking', note: 'By heading · 300–800 tokens' },
    { title: 'Embedding', note: 'Voyage 3.5-lite · 1024 dimensions' },
    { title: 'Storage', note: 'pgvector — the site’s own database' },
    { title: 'Retrieval', note: 'Top 5 by cosine · 0.2 floor' },
    { title: 'Answer', note: 'Reasoning filtered · live citations', current: true },
  ]}
/>
```

## Example — states not instructions

```tsx
import { Steps } from '@misoto22/design'

<Steps
  label="Release 0.4.1"
  marker="rule"
  steps={[
    { title: 'Queued', note: 'Behind one earlier build' },
    { title: 'Building', note: 'pnpm build · 1m 20s so far', current: true },
    { title: 'Published', note: 'npm registry, then the docs site' },
  ]}
/>
```

## Example — notes that carry code

```tsx
import { Code, Steps } from '@misoto22/design'

<Steps
  label="Adding the package to an app"
  steps={[
    { title: 'Install', note: <Code>pnpm add @misoto22/design</Code> },
    { title: 'Import the stylesheet', note: <Code>@misoto22/design/styles.css</Code> },
    { title: 'Render', note: <Code>{'<Button>Save</Button>'}</Code>, current: true },
  ]}
/>
```

# StatusPill

A live state, named: a dot plus an uppercase mono label.

- Group: Display
- Import: `import { StatusPill } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/status-pill/
- Related: status-dot, badge

## Anatomy

- **Pill** (required) — The outlined <span>: --radius-pill, a --rule-2 hairline, --paper ground, and deliberately uneven padding — 10px before the dot, 12px after the label — so the pair sits optically centred rather than mathematically.
- **Dot** (required) — A StatusDot handed tone and pulse. It is aria-hidden, so it is not where the tone reaches a reader who cannot see it.
- **Label** (required) — children in the eyebrow idiom — 11px uppercase mono, tracking pulled back from 0.2em to 0.12em because a pill is a shorter run than a section kicker.
- **Severity** — A visually-hidden “Warning” or “Error” at the warning and danger tones, so those two reach a reader through something other than a colour on a hidden dot. success and neutral add nothing: they are the absence of alarm, which is what a reader already assumes.

## Best practices

### Do

- Put the state in the words anyway. The severity word reaches a screen reader and nothing else — the pill’s own text is --ink-2 at every tone, so on a monochrome screen “Degraded” in a warning pill and in a neutral one are still the same pill.
- Set pulse={false} once the state has settled — the default halo means “right now”, and an archived or shipped pill pulsing forever tells the reader something is live when nothing is.
- Take the whole pill rather than composing a dot and a span at the call site: that assembly is how the same “available for work” chip came out at three dot sizes and two pulse timings on one site.

### Don’t

- It is not a live region. The pill is a plain <span>, so a state flipping from Available to Degraded while the reader is on the page changes silently — if the change is the news, the call site owns the role="status" around it.
- One per view, not one per row. The label is an uppercase eyebrow at 0.12em tracking — the loudest small type the system has — and a column of them down a table is Badge’s job, which is why Badge carries the same status tones in plain 12px mono.

## Accessibility

- The warning and danger tones are doubled by a visually-hidden severity word, because the dot that carries the colour is aria-hidden and has no name to give.
- success and neutral are silent on purpose: announcing “OK” before every settled pill is noise charged to the two tones worth interrupting for.
- Not a live region. A state that flips while the reader is on the page changes silently unless the call site owns a role="status" around it.

## StatusPill

A live state, named: a dot plus an uppercase mono label in an outlined pill. One component rather than a dot and a pill assembled per call site, which is how the same "available for work" chip ended up with three different dot sizes and two different pulse timings on one site. A warning or danger tone is doubled by a visually-hidden severity word, so the tone survives the dot being hidden. It does not survive monochrome: the pill's own text is `--ink-2` at every tone, and the state itself still belongs in the words the call site writes.

### Props

- `children` (required) — `ReactNode`.
- `tone` — `StatusTone` default `'success'`.
- `pulse` — `boolean` default `true`. Pulsing live dot (default) vs a settled one.

Also accepts: `HTMLAttributes<HTMLSpanElement>`.

## Example — default

```tsx
import { StatusPill } from '@misoto22/design'

<div className="flex flex-wrap items-center gap-3">
  <StatusPill>Available for work</StatusPill>
  <StatusPill tone="warning" pulse={false}>Partial outage</StatusPill>
</div>
```

## Example — settled and live

```tsx
import { StatusPill } from '@misoto22/design'

<div className="flex flex-wrap items-center gap-3">
  <StatusPill>Live</StatusPill>
  <StatusPill tone="warning" pulse={false}>Degraded</StatusPill>
  <StatusPill tone="danger" pulse={false}>Incident open</StatusPill>
  <StatusPill tone="neutral" pulse={false}>Archived</StatusPill>
</div>
```

## Example — one per view

```tsx
import { Badge, Separator, StatusPill } from '@misoto22/design'

<div className="flex w-full max-w-md flex-col gap-4">
  <div className="flex items-center justify-between gap-4">
    <span className="font-heading text-[length:var(--fs-item)] text-(--ink)">
      Deploy pipeline
    </span>
    <StatusPill tone="warning">Degraded</StatusPill>
  </div>
  <Separator />
  <ul className="m-0 flex list-none flex-col gap-2 p-0 text-sm text-(--ink-2)">
    <li className="flex items-center justify-between gap-4">
      Build <Badge tone="success">Passed</Badge>
    </li>
    <li className="flex items-center justify-between gap-4">
      Typecheck <Badge tone="success">Passed</Badge>
    </li>
    <li className="flex items-center justify-between gap-4">
      Visual diff <Badge tone="warning">2 changed</Badge>
    </li>
  </ul>
</div>
```

# LinkArrow

The mark on a link that leaves the page.

- Group: Display
- Import: `import { LinkArrow } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/link-arrow/

## Anatomy

- **Marker box** (required) — An aria-hidden inline-block <span> carrying the 0.22em of lead-in, the 0.28em baseline lift and --ink-3-aa. inline-block is load-bearing twice over: it stops an underlined parent drawing its rule through the glyph, and it is what the alignment is measured against.
- **Glyph** (required) — The ↗ itself at 0.68em, so it tracks the type beside it instead of competing with it. Exported as EXTERNAL_LINK_ARROW, so a surface that is not React uses the same character.

## Best practices

### Do

- Put it inside the <a>, as the last child. Outside it, it is an arrow pointing at a link the pointer misses by 0.22em.
- Reach for EXTERNAL_LINK_ARROW when the surface is not React — a Markdown pipeline, an OG image, an email — so the mark stays one character rather than three near-identical arrows across a site.
- Pass a colour through className on a reversed plate: it is set in --ink-3-aa, which is the AA floor against paper and close to invisible on ink.

### Don’t

- The arrow is not the announcement. It is aria-hidden, and target="_blank" is not announced either, so a link that opens a new tab has to say so in its own accessible name — otherwise this glyph is the only warning anyone gets, and only if they can see it.
- Do not pin it to a px size. 0.68em is what makes one component right in body copy and in a heading; fixed at 11px it is correct in one of them and a speck in the other.
- Do not put it on every row of an index. It marks a change of destination, so a list where every link leaves the site marks nothing at all and pays 0.22em a row for it.

## Accessibility

- aria-hidden, so it is not read as “north east arrow” in the middle of a sentence.
- Sized in em, so it tracks whatever type it sits beside instead of competing with it.

## EXTERNAL_LINK_ARROW

Re-export of `'↗'`.

The glyph itself, exported so a non-React surface can use the same mark.

## LinkArrow

The mark on a link that leaves the page — outbound, or on to a full index. Call sites used to write a bare `↗` inside the link text, which inherited the link's own size (a 17px arrow beside a 17px word, competing with it) and was read aloud as "north east arrow" because nothing hid it. `inline-block` is load-bearing twice over: it stops an underlined parent drawing its rule through the glyph, and it is what `align` is measured against. Sized in `em`, so it tracks whatever type it sits beside; coloured against paper, so a call site on a reversed plate passes its own colour.

Also accepts: `HTMLAttributes<HTMLSpanElement>`.

## Example — default

```tsx
import { LinkArrow } from '@misoto22/design'

<p className="m-0 text-sm text-(--ink-2)">
  <a
    href="https://misoto22.com"
    className="text-(--ink) underline decoration-(--rule-2) underline-offset-4 hover:decoration-(--ink)"
  >
    Read the whole thing
    <LinkArrow />
  </a>
</p>
```

## Example — only where it leaves

```tsx
import { LinkArrow } from '@misoto22/design'

<ul className="m-0 flex list-none flex-col gap-2 p-0 text-sm text-(--ink-2)">
  <li>
    <a href="#tokens" className="text-(--ink) underline decoration-(--rule-2) underline-offset-4">
      Tokens, further down this page
    </a>
  </li>
  <li>
    <a href="#changelog" className="text-(--ink) underline decoration-(--rule-2) underline-offset-4">
      What changed in 0.4.0
    </a>
  </li>
  <li>
    <a
      href="https://www.w3.org/TR/WCAG22/"
      target="_blank"
      rel="noreferrer"
      className="text-(--ink) underline decoration-(--rule-2) underline-offset-4"
    >
      WCAG 2.2 on w3.org, opens in a new tab
      <LinkArrow />
    </a>
  </li>
</ul>
```

## Example — on a reversed plate

```tsx
import { LinkArrow } from '@misoto22/design'

<div className="rounded-(--radius-lg) bg-(--ink) p-5">
  <a
    href="https://github.com/misoto22"
    className="text-sm text-(--paper) underline decoration-(--ink-3-aa) underline-offset-4"
  >
    The repository on GitHub
    <LinkArrow className="text-(--paper)" />
  </a>
</div>
```

# Separator

A rule, in the three weights a monochrome page needs — with words in it when the break has something to say.

- Group: Display
- Import: `import { Separator } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/separator/

## When to reach for it

Hairline between rows, edge between blocks, hard under a masthead. label puts words in the break: "or continue with", "Older".

## Anatomy

- **Rule** (required) — One <div>. A pixel on its cross axis and 100% on its main axis, so it takes the width — or the height — of whatever contains it, and nothing else.
- **Ink** (required) — The only thing weight changes: --rule inside a block, --rule-2 between blocks, --rule-hard under a masthead. The hard one is not a darker grey, it is --ink itself.
- **Label** — label, horizontal only. It changes the construction rather than the styling: the rule is drawn TWICE, one aria-hidden piece either side of the words in mono-meta at --ink-3-aa, and the gap between them is a gap.

## Best practices

### Do

- Give a vertical separator a height. It is h-full, which against a parent with no height of its own resolves to zero — the element renders, occupies nothing, and reads as a component that failed to load.
- Pass decorative={false} when the rule is the only thing dividing two sections a screen reader should hear as distinct: that is what swaps role="none" for role="separator" and sets aria-orientation with it.
- Use label rather than building "or continue with" out of two Separators and a span. The two rules are drawn for you and neither of them needs to know the ground it is on.

### Don’t

- Do not pick the weight by eye. The three are ordered, so a hard rule between two table rows tells the reader the table ended there.
- Do not hand-tune a fourth grey through className. Three named weights are the whole set, and the names exist because a monochrome page drifts into five slightly different rules the moment one of them is chosen by feel.
- Do not lay the label over a single rule with a background colour to punch a hole in it. That version has to be told the ground it is sitting on, and a --paper notch on a --stone card reads as a rendering bug.

## Accessibility

- role="none" by default. A rule that only groups things visually must not be announced.
- With a label, the words are the content and the two rules are aria-hidden decoration — so decorative no longer applies, and nothing announces a separator over the top of the text.
- A label on a vertical rule is ignored rather than silently redrawn as a horizontal bar: there is no sensible place for words inside a one-pixel column.

## Separator

A rule, with or without words in it. In a monochrome system the rule does the work colour would otherwise do, so it has three weights rather than one: hairline between rows, edge between blocks, hard under a masthead. Picking by name keeps a page from drifting into five hand-tuned greys. **On the label.** "or continue with" was two Separators and a span at every call site, and the usual one-element version — text laid over a single rule with a background to punch a hole in it — needs to know the ground it is sitting on. Get that wrong and the notch is `--paper` on a card that is `--stone`, which reads as a rendering bug. So there is no ground: the rule is drawn twice, one piece either side of the label, and the gap is a gap. It is correct on any surface without being told which one it is on.

### Props

- `orientation` — `'horizontal' | 'vertical'` default `'horizontal'`.
- `weight` — `'hairline' | 'edge' | 'hard'` default `'hairline'`. `hairline` divides rows inside one block; `edge` divides one block from the next.
- `decorative` — `boolean` default `true`. A rule that only groups things visually is decoration and must not be announced. Set `false` when the rule genuinely separates two sections a screen reader should hear as distinct.
- `label` — `ReactNode`. Words in the break — "or continue with", "Older". Horizontal only, and it changes the construction rather than the styling: see the note on the component. `decorative` no longer applies, because the label is content and the two rules beside it are decoration either way.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## Example — weights

```tsx
import { Separator } from '@misoto22/design'

<div className="flex w-full flex-col gap-5">
  <div>
    <p className="m-0 mb-2 mono-meta text-(--ink-3-aa)">hairline — between rows</p>
    <Separator />
  </div>
  <div>
    <p className="m-0 mb-2 mono-meta text-(--ink-3-aa)">edge — between blocks</p>
    <Separator weight="edge" />
  </div>
  <div>
    <p className="m-0 mb-2 mono-meta text-(--ink-3-aa)">hard — under a masthead</p>
    <Separator weight="hard" />
  </div>
</div>
```

## Example — vertical needs a height

```tsx
import { Separator } from '@misoto22/design'

<div className="flex flex-wrap items-center gap-3 text-sm text-(--ink-2)">
  <span>12 releases</span>
  <Separator orientation="vertical" className="h-4" />
  <span>0 rollbacks</span>
  <Separator orientation="vertical" className="h-4" />
  <span>99.98% uptime</span>
</div>
```

## Example — announced between sections

```tsx
import { Heading, Separator, Text } from '@misoto22/design'

<div className="flex w-full flex-col gap-5">
  <section className="flex flex-col gap-2">
    <Heading level={3}>Installation</Heading>
    <Text size="sm">One package, and one stylesheet next to it.</Text>
  </section>
  <Separator weight="edge" decorative={false} />
  <section className="flex flex-col gap-2">
    <Heading level={3}>Upgrading</Heading>
    <Text size="sm">Minor versions add exports; they never move one.</Text>
  </section>
</div>
```

## Example — words in the rule

```tsx
import { Separator } from '@misoto22/design'

<div className="flex w-full flex-col gap-6">
  <Separator label="or continue with" />
  <div className="rounded-(--radius-lg) bg-(--stone) p-5">
    <Separator weight="edge" label="Older" />
  </div>
</div>
```

# Diagram

A flow or architecture figure, drawn out of the system’s own parts.

- Group: Display
- Import: `import { Diagram } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/diagram/
- Related: card, figure-band

## When to reach for it

A picture of structure, in a page rather than in a terminal. Nesting is containment and an edge is a step between siblings — a diagram that needs arbitrary wiring wants a drawing, not this.

## Anatomy

- **Frame** (required) — The <figure role="group"> and the panel inside it: a --rule hairline on the --radius-lg corner over --paper-2, with fluid padding and overflow-x-auto on a hairline scrollbar — so a wide figure scrolls inside its own box instead of widening the page.
- **Leaf plate** — A node with NO children: a bordered card on --paper, or filled with --accent when accent is set. Its label breaks inside itself, because an identifier like TenantMainMiddleware has no break opportunity and would otherwise run into the plate’s edge.
- **Container band** — A node WITH children: a labelled hairline — ink at the top rank, --rule-2 below it — with its children underneath and no frame of its own. That is the whole design: drawing a container as another box puts three borders around anything two levels deep.
- **Node note** — node.note, a mono line beside a band’s label or under a plate’s. One short line, a step back from the name.
- **Edge mark** — The arrow between two adjacent siblings an edge names, with the edge’s label under it. aria-hidden, and rotated a quarter turn below the sm breakpoint, where a row of nodes stacks into a column and the arrow has to point the way the layout actually runs.
- **Caption** — spec.caption, printed under the frame — as a <div>, not a <figcaption>, because an article stylesheet styles figcaption unlayered and an unlayered rule beats a utility whatever the specificity.

## Best practices

### Do

- Write an edge from a node to the node immediately after it in the same rank, in that order. An edge between non-adjacent nodes, or one written to→from, draws no arrow — and now says so in the console rather than leaving the author to spot a missing arrow in a picture that otherwise looks finished.
- Keep ids unique across the whole spec. Each edge is now spent at the first pair that matches it, so a reused pair no longer draws the arrow twice — but the arrow lands on whichever pair comes first, which is a diagram asserting something nobody wrote.
- Give the spec a caption or a label. The figure’s role="group" is named by whichever is present, and with neither the reader is told there is a group and never told what of.

### Don’t

- accent is read only in the plate branch, so setting it on a node with children compiles, type-checks and paints nothing — a container is a band, and a band has no fill to take. Development says so; a production build does not.
- direction is read only from a node that HAS children. Set on a leaf it is ignored, because the axis a leaf sits on belongs to its parent — and, like accent on a band, it is reported in development rather than silently dropped.
- Do not put six nodes across the top rank. A row is flex-col below sm and only flex-row above it, so a figure that reads as a pipeline on a desktop is six stacked plates and five arrows on a phone.

## Accessibility

- A <figure> with role="group", named by its caption, so the whole picture is one thing a reader can skip.
- Arrows are aria-hidden: assistive tech reads the nodes in document order and has no use for a glyph pointing at the next one.
- Server-rendered markup, not a canvas — every label is real text a screen reader and a search engine can read.
- A spec the renderer cannot honour — an unmatched edge, a duplicate id, accent on a band, direction on a leaf — prints a named warning in development, because the alternative is a confident picture of something else.

## Diagram

A flow or architecture diagram, drawn out of the system's own parts. The alternative it replaces is a fenced block of box-drawing characters — `┌──────┬──────┐` — which is a picture rendered in a font chosen for code. It inherits the code block's frame and scrollbar, so a diagram reads as terminal output; it cannot wrap, so on a phone it either overflows or is scaled to nothing; the box edges are text, so a screen reader reads the rules out loud; and none of it responds to the theme. The other alternative is a diagramming library, which is several hundred kilobytes of layout engine, renders after hydration, and draws in its own palette. This is neither: hairline frames on the radius scale, mono labels, the muted step for anything supporting — so a diagram belongs to the page it sits on. It server-renders, because it is markup. NESTING IS CONTAINMENT, which is what most architecture diagrams actually describe: this is inside that, and these two sit beside each other. Edges are for the sequence between siblings, not for arbitrary wiring — a diagram that needs arbitrary wiring is a diagram that wants a drawing, and this will not pretend otherwise. It takes a spec rather than markup, so a fenced ```diagram block in an article and a hand-written figure on a page are one renderer and one look — and a wrong diagram is corrected by editing data.

### Props

- `spec` (required) — `DiagramSpec`.
- `className` — `string`.

## Example — default

```tsx
import { Diagram } from '@misoto22/design'

<Diagram
  spec={{
    caption: 'One request, from the edge to the row it reads.',
    edges: [
      { from: 'edge', to: 'app', label: 'HTTPS' },
      { from: 'app', to: 'data', label: 'SQL' },
    ],
    nodes: [
      { id: 'edge', label: 'Edge', note: 'CDN + WAF', footnote: 'Cached for 60s' },
      {
        id: 'app',
        label: 'Application',
        note: 'one process',
        direction: 'column',
        children: [
          { label: 'Router' },
          { label: 'Handlers', accent: true, note: 'where the work is' },
          { label: 'Serialisers' },
        ],
      },
      { id: 'data', label: 'Postgres', note: 'primary' },
    ],
  }}
/>
```

## Example — containment not wiring

```tsx
import { Diagram } from '@misoto22/design'

<Diagram
  spec={{
    direction: 'column',
    caption: 'What the package contains, and who contains the package.',
    nodes: [
      {
        label: 'Consumers',
        note: 'two hosts',
        children: [
          { label: 'misoto22.com', note: 'the public site' },
          { label: 'Admin console', note: 'behind a login' },
        ],
      },
      {
        label: '@misoto22/design',
        note: 'one package',
        direction: 'column',
        children: [
          {
            label: 'Components',
            note: 'React, server-rendered',
            children: [
              { label: 'Display' },
              { label: 'Forms' },
              { label: 'Overlays' },
            ],
          },
          { label: 'Tokens', note: 'CSS and TypeScript, one source' },
        ],
      },
    ],
  }}
/>
```

## Example — a column of ranks

```tsx
import { Diagram } from '@misoto22/design'

<Diagram
  spec={{
    direction: 'column',
    caption: 'A search query, top to bottom.',
    edges: [
      { from: 'query', to: 'embed', label: 'text' },
      { from: 'embed', to: 'search', label: '1024-d vector' },
    ],
    nodes: [
      { id: 'query', label: 'Query', note: 'typed by a reader' },
      { id: 'embed', label: 'Embedding', note: 'Voyage 3.5-lite' },
      {
        id: 'search',
        label: 'pgvector',
        note: 'top 5 by cosine',
        direction: 'row',
        children: [
          { label: 'Posts' },
          { label: 'Projects' },
          { label: 'Profile' },
        ],
      },
    ],
  }}
/>
```

## Example — the node it is about

```tsx
import { Diagram } from '@misoto22/design'

<Diagram
  spec={{
    label: 'Where an answer is assembled',
    edges: [
      { from: 'retrieval', to: 'model', label: 'context' },
      { from: 'model', to: 'answer', label: 'tokens' },
    ],
    nodes: [
      { id: 'retrieval', label: 'Retrieval', note: 'five chunks' },
      {
        id: 'model',
        label: 'Model',
        note: 'streamed',
        accent: true,
        footnote: 'The only step that leaves the machine',
      },
      { id: 'answer', label: 'Answer', note: 'with citations' },
    ],
  }}
/>
```

# FigureBand

A row of counted facts, divided by hairlines and nothing else.

- Group: Display
- Import: `import { FigureBand } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/figure-band/
- Related: table

## Anatomy

- **Query wrapper** (required) — A plain <div> around the list, and it has to be: a container query resolves against an ANCESTOR container, never against the element declaring one. Its w-full is load-bearing too — contain: inline-size computes width without looking at the contents, so as a shrink-to-fit flex item it resolved to zero and the band rendered as two 0px columns.
- **Band** (required) — The <dl>: ruled top and bottom in --rule, two columns until the wrapper reaches @3xl and four after — a decision about how wide THIS band is, not how wide the window is.
- **Cell** (required) — One <div> per figure. Each divider width names the cells that do NOT open a row rather than adding a rule and taking it back, so no edge is ever painted past the last column.
- **Label** (required) — The <dt>: the mono uppercase kicker over the value.
- **Value** (required) — The <dd>, set in the heading face at --fs-lead or --fs-sub depending on scale.
- **Note** — A second <dd> under the same term — a trend, a qualifier, a second fact.

## Best practices

### Do

- Give it two or four figures. The grid is two columns until @3xl and four after, so three leaves a hole in both arrangements and five leaves three holes once the band goes four across.
- Use scale="sub" for a band that supports the page rather than being it: --fs-lead is the band-heading step, so a supporting figure set at lead is competing with the page’s own subject.
- Key each figure by the fact it counts — id is required rather than optional, because it is the React key and an index puts the next render’s number under the previous label as soon as the list reorders.

### Don’t

- Do not put a sentence in note. The value and the note are two <dd>s under one <dt>, so a screen reader reads them as two values of the same term: “Posts: 48, +6 this year” works, a clause does not.
- Do not set the column count with a viewport breakpoint through className. The band reads a container query, so a sm:grid-cols-4 written on it is wrong in a 390px sidebar of a 1440px window — which is the arrangement this replaced.
- figures={[]} renders null, so a band fed a filtered-empty array leaves no rules behind and no zero state either — if the absence is the news, the call site has to say so.

## Accessibility

- A <dl>: each cell is a term and its value, which a grid of divs cannot express.

## FigureBand

A framed, responsive group of related facts with semantic term/value pairs.

### Props

- `figures` (required) — `Figure[]`.
- `scale` — `'lead' | 'sub'` default `'lead'`. How large the value is set. `lead` is for a band that is the point of its page — a stats headline, where the numbers ARE the content. `sub` is for a band that supports the page around it, and keeps the ladder honest: a supporting figure must not be set at the same size as the page's own subject.
- `label` — `string`. Names the band for assistive tech when it has no visible heading of its own.

Also accepts: `Omit<HTMLAttributes<HTMLDListElement>, 'children'>`.

## Example — default

```tsx
import { FigureBand } from '@misoto22/design'

<FigureBand
  label="Deploys, last 30 days"
  figures={[
    { id: 'releases', label: 'Releases', value: '12' },
    { id: 'duration', label: 'Median build', value: '2m 14s', note: 'down from 3m 40s' },
    { id: 'rollbacks', label: 'Rollbacks', value: '0' },
    { id: 'uptime', label: 'Uptime', value: '99.98%', note: 'measured at the edge' },
  ]}
/>
```

## Example — a supporting band

```tsx
import { FigureBand, Heading, Text } from '@misoto22/design'

<div className="flex w-full flex-col gap-5">
  <Heading level={3}>Retrieval rewrite</Heading>
  <Text size="sm">
    Chunking moved from a fixed window to headings, and the citation panel
    started reading the same rows the answer did.
  </Text>
  <FigureBand
    scale="sub"
    label="Retrieval, before and after"
    figures={[
      { id: 'latency', label: 'Median latency', value: '240ms', note: 'from 610ms' },
      { id: 'recall', label: 'Answers with a citation', value: '96%', note: 'from 71%' },
    ]}
  />
</div>
```

## Example — a note is a second value

```tsx
import { FigureBand } from '@misoto22/design'

<FigureBand
  label="The site, at a glance"
  figures={[
    { id: 'posts', label: 'Posts', value: '48', note: '+6 this year' },
    { id: 'frames', label: 'Frames', value: '1,204', note: '38 rolls' },
    { id: 'projects', label: 'Projects', value: '11', note: '3 shipped' },
    { id: 'words', label: 'Words', value: '86k', note: 'English and Chinese' },
  ]}
/>
```

## Example — in a narrow column

```tsx
import { FigureBand } from '@misoto22/design'

<div className="w-full max-w-96 rounded-(--radius-lg) border border-(--rule) p-4">
  <FigureBand
    scale="sub"
    label="This release"
    figures={[
      { id: 'components', label: 'Components', value: '61' },
      { id: 'tokens', label: 'Tokens', value: '145' },
      { id: 'examples', label: 'Examples', value: '147' },
      { id: 'size', label: 'Peer deps', value: '2' },
    ]}
  />
</div>
```

# Text

The system’s paragraph, on the second rung of the ink ladder.

- Group: Display
- Import: `import { Text } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/text/
- Related: heading, article, markdown

## When to reach for it

One paragraph, or one run of text, outside a reading column. A whole column of prose is an Article.

## Anatomy

- **Box** (required) — The element `as` names — a <p> unless told otherwise. It carries the size, the tone and margin: 0, so the spacing between blocks belongs to the surface rather than to the paragraph.
- **Type step** (required) — size, one of four: xs, sm, base and lead. lead is --fs-item, the bottom rung of the heading ladder, and is the standfirst that carries a piece.
- **Ink step** (required) — tone, one of three, because the ink ladder has three rungs: body is --ink-2, strong is --ink, muted is --ink-3-aa.

## Best practices

### Do

- Leave tone alone for body copy. The default is --ink-2 on purpose: a page whose paragraphs are all full-strength ink has spent the top of the ladder on its body text and has nothing left for the headings.
- Use as="span" for a run inside a sentence. A <p> nested inside a <p> is not nesting — the HTML parser closes the outer one and you get two paragraphs and a broken layout.
- Reach for size="lead" for the standfirst under a title, and stop there. It is --fs-item, the same step an in-card title uses; anything larger is a heading that has not admitted it.

### Don’t

- Do not set spacing on it. Every Text is margin: 0, so a stack of them inside a plain <div> has no rhythm by design — put them in an Article or give the container the gap, or every surface ends up with its own idea of what a paragraph gap is.
- tone="muted" is --ink-3-aa, never --ink-3. The two look identical on paper and are not the same token: --ink-3 is a translucent tint that takes on whatever is under it, so it clears AA on the page ground and quietly fails on a card or a code plate.
- Do not use it as a heading with a bigger size. The element is what a screen reader navigates by, and a <p> at --fs-item is invisible to a heading list.

## Accessibility

- as changes the element and nothing else, so the markup can say what the content is without the look changing under it.
- Every tone is an AA-safe rung; the muted step is --ink-3-aa rather than the translucent --ink-3.

## Text

A paragraph, or a run of text that wants the system's voice. The step between `Article` and raw JSX. `Article` styles a whole reading column from element selectors and is the right answer for a post; this is for the single paragraph that is NOT in a column — a card's description, a dialog's explanation, the line under an empty state. The default tone is `body` (`--ink-2`), not `--ink`. A page whose paragraphs are all full-strength ink has spent the top of the ladder on its body copy and has nothing left for the headings, which is the single most common way a monochrome page loses its hierarchy.

### Props

- `children` — `ReactNode`.
- `size` — `TextSize` default `'base'`. Which rung of the type scale. See TextSize.
- `tone` — `TextTone` default `'body'`. Which rung of the ink ladder. See TextTone.
- `as` — `TextElement` default `'p'`. The element, and ONLY the element. Changing it changes what the markup means — a `span` inside a sentence, an `li` inside a list someone else opened — and changes nothing about the look. That separation is the whole point: the alternative is a `<p>` nested inside a `<p>`, which the HTML parser silently splits into two, or a paragraph faked out of a `<div>` because the real element brought a size with it.

Also accepts: `HTMLAttributes<HTMLElement>`.

## Example — sizes and tones

```tsx
import { Text } from '@misoto22/design'

<div className="flex max-w-prose flex-col gap-4">
  <Text size="lead" tone="strong">
    A monochrome system for software and writing.
  </Text>
  <Text>
    Body copy at the base step, on the second rung of the ink ladder. Use{' '}
    <Text as="span" tone="strong">
      strong
    </Text>{' '}
    for a run that has to carry, and nothing above lead.
  </Text>
  <Text size="sm" tone="muted">
    Updated just now — the muted rung is --ink-3-aa, which clears AA on any
    ground in the system.
  </Text>
</div>
```

## Example — a run inside a sentence

```tsx
import { Text } from '@misoto22/design'

<div className="flex max-w-prose flex-col gap-4">
  <Text>
    The release went out at 09:14.{' '}
    <Text as="span" tone="strong">Twelve deploys</Text> since the rewrite, and{' '}
    <Text as="span" tone="muted">no rollbacks</Text>.
  </Text>
  <ul className="m-0 flex list-none flex-col gap-1 ps-0">
    <Text as="li" size="sm">Tokens rebuilt from the CSS source</Text>
    <Text as="li" size="sm">Every example carries the sentence that explains it</Text>
    <Text as="li" size="sm">Chinese copy still owed for the newest five</Text>
  </ul>
</div>
```

## Example — a standfirst under a title

```tsx
import { Heading, Text } from '@misoto22/design'

<div className="flex max-w-prose flex-col gap-3">
  <Heading level={2}>The White Reset</Heading>
  <Text size="lead">
    A monochrome system for software and writing, published as one package
    and one stylesheet.
  </Text>
  <Text>
    Structure is carried by weight, rules and space rather than by colour,
    which leaves the two status hues free to mean something when they appear.
  </Text>
  <Text size="sm" tone="muted">Updated this morning</Text>
</div>
```

# Heading

A heading whose element and whose size are two decisions.

- Group: Display
- Import: `import { Heading } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/heading/
- Related: text, article, markdown

## When to reach for it

Any heading. level follows the document outline; size follows the design, and defaults from level.

## Anatomy

- **Element** (required) — level, 1 to 6, rendered as the matching <h1>–<h6>. This is the document outline — what a screen reader navigates by — so it follows the section the heading opens, never the size it wants to be.
- **Step** (required) — size, one of title, lead, heading, sub, item and label. Defaults from level through the system ladder, so writing only level is correct.
- **Anchor offset** (required) — scroll-margin-top: var(--scroll-offset), carried by every heading, so one given an id and linked from a table of contents comes to rest below the masthead instead of under it.

## Best practices

### Do

- Write level alone unless the outline and the design genuinely disagree. The default ladder is 1→title, 2→heading, 3→sub, 4→item, 5 and 6→label — the same map article.css applies to rendered Markdown, which is what makes a post and a component page read as one publication.
- Notice that the default ladder SKIPS lead between levels 1 and 2, and skip a step yourself when you set size by hand: --fs-lead over --fs-heading is a ratio of 1.14 and reads as a rendering accident, where --fs-title over --fs-heading is 1.86 and reads as a hierarchy.
- Give a heading an id when anything links to it. The component already carries the scroll offset the anchor needs; nothing else on the page does.

### Don’t

- Do not raise level to get a bigger heading. Two <h1>s on a page make its outline unnavigable, and size is one prop away.
- Do not reach past size="title". The ladder ends there because a page has exactly one thing larger than its own records; a bigger heading is className territory and it is the moment the page stopped being in the system.
- size="label" is the mono kicker at 11px and --ink-3-aa, not a small serif heading — it is what levels 5 and 6 should look like, and setting it on an <h2> makes the section title read as metadata.

## Accessibility

- level renders the real heading element, so the outline is navigable rather than merely visible.
- The two decisions are separate props, which is what lets a semantically-correct h3 look like a page title without bending the outline.
- Carries scroll-margin-top so an anchored heading is not hidden under a fixed masthead (WCAG 2.4.7 in practice).

## Heading

A heading, with its element and its size decided separately. Every heading component that takes one number gets this wrong in one of two directions: either the outline is bent to reach a size (an `<h1>` in the middle of a page because the design wanted big type), or the size is bent to keep the outline (a section title set at 20px because it is the fourth level down). Both are one prop away from being right, so there are two. `level` is the document. `size` is the page. The default binds them through the system's ladder, so writing only `level` is correct — and the moment they come apart, the call site says so. Set in the editorial serif at weight 400, like every heading in the system. It also carries `scroll-margin-top`, so a heading given an `id` and linked from a table of contents comes to rest below the masthead rather than under it.

### Props

- `children` — `ReactNode`.
- `level` (required) — `HeadingLevel`. The element: `1` renders `<h1>`, `6` renders `<h6>`. This is the document outline and nothing else — it is what a screen reader navigates by, so it follows the section the heading opens, never the size it wants to be. A heading two levels down inside an `<h2>` section is an `<h3>` even when the design calls for something enormous.
- `size` — `HeadingSize`. The size, when the outline and the design genuinely disagree. Defaults from `level` through the ladder above, which is the answer nearly always. Reach for this when a semantically-correct `h3` opens a page and has to look like one — not to squeeze a fourth step between two that are already only 14% apart.

Also accepts: `HTMLAttributes<HTMLHeadingElement>`.

## Example — level and size

```tsx
import { Heading, Text } from '@misoto22/design'

<div className="flex flex-col gap-5">
  <Heading level={1}>The White Reset</Heading>
  <Heading level={2}>A record title</Heading>
  <Heading level={3}>A sub-head inside it</Heading>
  <Heading level={4} size="label">
    Metadata
  </Heading>
  <Heading level={3} size="title">
    Third level, page-title sized
  </Heading>
  <Text size="sm" tone="muted">
    The last one is an h3. Nothing about the outline moved.
  </Text>
</div>
```

## Example — anchored headings

```tsx
import { Heading, Text } from '@misoto22/design'

<div className="flex flex-col gap-4">
  <nav aria-label="Section links" className="flex flex-col gap-1">
    <a href="#installation" className="text-sm text-(--ink-2) underline decoration-(--rule-2) underline-offset-4">
      Installation
    </a>
    <a href="#upgrading" className="text-sm text-(--ink-2) underline decoration-(--rule-2) underline-offset-4">
      Upgrading
    </a>
  </nav>
  <Heading level={2} id="installation">Installation</Heading>
  <Text size="sm">One package, and one stylesheet next to it.</Text>
  <Heading level={2} id="upgrading">Upgrading</Heading>
  <Text size="sm">Minor versions add exports; they never move one.</Text>
</div>
```

## Example — a fragment that starts at h2

```tsx
import { Heading, Text } from '@misoto22/design'

<div className="flex w-full max-w-md flex-col gap-4 rounded-(--radius-lg) border border-(--rule) bg-(--paper-2) p-5">
  <Heading level={2} size="title">Publish 0.4.1</Heading>
  <div className="flex flex-col gap-2">
    <Heading level={3}>What ships</Heading>
    <Text size="sm">Five display components, and the examples that explain them.</Text>
  </div>
  <div className="flex flex-col gap-2">
    <Heading level={3}>What it breaks</Heading>
    <Text size="sm">Nothing — every export in 0.4.0 is still exported here.</Text>
  </div>
</div>
```

# Code

A function name or a flag, inside a sentence.

- Group: Display
- Import: `import { Code } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/code/
- Related: code-block, kbd

## When to reach for it

Inline code within running text. A multi-line snippet is a CodeBlock.

## Anatomy

- **Chip** (required) — A real <code> on the --radius-sm corner, filled with --stone. Sized at 0.85em rather than in pixels, so the same token is proportionate in body copy, in a caption and in a table cell.

## Best practices

### Do

- Use it for anything the reader would type or the machine would read: a flag, a path, a function, an env var name. The mono face is the signal that the string is literal.
- Let it inherit its size. It is set in em on purpose — fixed at one pixel value, the identical token comes out three different sizes on one page depending on where it landed.

### Don’t

- Do not hand it a multi-line string. It keeps no whitespace and draws no plate, so the snippet collapses into one run — that is CodeBlock’s job.
- Do not style a <span> to look like this instead. The element is the whole point: a mono span reads identically and tells a screen reader nothing, and "pass dash dash force" is not what the sentence said.

## Accessibility

- Renders <code>, which is what tells assistive tech the run is literal rather than prose.

## Code

A function name, a flag, a filename — inside a sentence. Renders a `<code>`, which is the element that means this. A `<span>` in a mono face looks identical and tells a screen reader nothing, and "pass dash dash force" is not what the sentence said. Sized in `em` rather than in pixels, so the chip tracks whatever type it sits beside — the same rule `Kbd` follows, and for the same reason: fixed at one value, the identical token came out three different sizes on one page depending on whether it landed in body copy, a caption or a table cell. The block form is `CodeBlock`. This one is inline by construction: it draws no plate, keeps no whitespace, and a multi-line string handed to it collapses into one run.

### Props

- `children` (required) — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLElement>`.

## Example — inline

```tsx
import { Code, Text } from '@misoto22/design'

<div className="flex flex-col gap-3">
  <Text>
    Pass <Code>--force</Code> to overwrite <Code>dist/</Code>, and read the
    merge helper in <Code>src/lib/cn.ts</Code>.
  </Text>
  <Text size="sm" tone="muted">
    At the small step it tracks down with the sentence: <Code>--force</Code>.
  </Text>
</div>
```

## Example — a literal or a key

```tsx
import { Code, Kbd, Text } from '@misoto22/design'

<div className="flex max-w-prose flex-col gap-3">
  <Text size="sm">
    Press <Kbd>⌘</Kbd> <Kbd>K</Kbd> to open the palette, then type{' '}
    <Code>Markdown</Code> to reach the component.
  </Text>
  <Text size="sm">
    The flag is <Code>--force</Code>; the key that cancels the run is <Kbd>Esc</Kbd>.
  </Text>
</div>
```

## Example — a list of flags

```tsx
import { Code } from '@misoto22/design'

<dl className="m-0 grid grid-cols-[auto_1fr] items-baseline gap-x-5 gap-y-2 text-sm text-(--ink-2)">
  <dt><Code>--force</Code></dt>
  <dd className="m-0">Overwrites <Code>dist/</Code> instead of failing on it.</dd>
  <dt><Code>--filter</Code></dt>
  <dd className="m-0">Runs in one workspace package.</dd>
  <dt><Code>--dry-run</Code></dt>
  <dd className="m-0">Prints what would be published, and publishes nothing.</dd>
</dl>
```

# CodeBlock

A multi-line snippet, on a plate, with a way to take it away.

- Group: Display
- Import: `import { CodeBlock } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/code-block/
- Related: code, markdown, article

## When to reach for it

Any snippet longer than a word. Pass html when a build-time highlighter has already run; pass code alone when it has not.

## Anatomy

- **Plate** (required) — The --paper-2 box on the --radius-lg corner with a --rule hairline. One elevated step, not a second surface colour.
- **Strip** — The bar along the top: title at the start, the language label at the end, the copy button after it. Present whenever there is anything to put in it, and never a hover-only affordance.
- **Copy button** — A ghost iconOnly Button that puts code — the string, never the rendered markup — on the clipboard, and flips its own accessible name to “Copied” for 1.6 seconds.
- **Body** (required) — A focusable, named role="group" that scrolls in both axes. Focusable because a scrollable box containing nothing focusable is unreachable by keyboard: there is nothing to Tab to, so the right-hand half of a long line does not exist without a mouse. A group and not a region, because a region is a landmark and a snippet is not one — three fenced blocks in an article would be three landmarks all called Code.
- **Line row** — One <span data-line> per line on the plain path, carrying its own number and its own highlight band. The number is a child of the line it numbers, so the two cannot come apart.

## Best practices

### Do

- Always pass code, even alongside html. It is what the copy button copies: a block that copies its rendered markup hands the reader a wall of spans, and one that scrapes textContent back out of the DOM is a non-breaking space away from pasting something that does not run.
- Highlight at build time and pass html. A highlighter is a few hundred kilobytes of grammar shipped to re-derive spans that never change, which would be the largest thing on the page.
- Give maxHeight to a long snippet rather than letting it run. The body scrolls and is focusable, so what is past the fold stays reachable by keyboard.

### Don’t

- lineNumbers and highlightLines are typed out of the html form and passing both is a compile error. They are a per-line structure, and html is one opaque string the component does not parse — which is why the type says so rather than the prop quietly rendering nothing.
- html is dangerouslySetInnerHTML. It is for the output of your own highlighter over your own source; markdown a reader wrote goes to code as a string, where it renders as text and cannot be mis-executed.
- Do not drop copyable to tidy the strip. The button is the reason a reader stops selecting a wrapped command by hand, and on a touch screen a manual selection is most of the interaction.

## Accessibility

- The scrolling body is tabbable and carries role="group" with a name, so its overflow is reachable with a keyboard and the tab stop announces what it is. Deliberately not role="region": that is a landmark, and a page with two code samples would put two of them in the landmark map under one name.
- The copy button is an iconOnly Button with a required aria-label that becomes “Copied” on success — the state change is announced rather than only drawn.
- The copy control clears the 44px pointer target on a coarse pointer, where the compact strip alone would not (WCAG 2.5.5).

## CodeBlock

A multi-line snippet, on a plate, with a way to take it away. A labelled block has a strip for its title, language and copy button. Without a label, copying sits beside the code in the same row. It is deliberately not a hover affordance: a control that appears on hover does not exist on a touch screen, which is where a reader is most likely to want the snippet and least able to select it by hand. Line numbers live INSIDE their own line's row rather than in a parallel gutter column. Two columns sharing a line-height align right up until one of them wraps, ships a different font, or scrolls on its own; a number that is a child of the line it numbers cannot come apart from it. The cost is that a number scrolls away with its line: it is inside the scrolling box, not in a gutter beside it. A gutter that stayed put would be a second column to keep in sync, which is the failure this avoids. The body is a focusable, named `role="group"`, and both halves of that are load-bearing. Focusable, because a scrollable box whose contents are not themselves focusable is unreachable by keyboard — there is nothing to Tab to and therefore no way to press an arrow key at it, so the right-hand half of a long line does not exist for anyone not using a mouse. Named, because a tab stop that announces nothing lands the reader in an anonymous box and leaves them to work out what they have arrived in. `group` rather than `region`, and that is the deliberate half. A region is a LANDMARK — one of the handful of major sections a reader navigates a whole page by — and a snippet is not one of those. Three fenced blocks in one article would put three landmarks called "Code" into that map, which is exactly the noise the `landmark-unique` rule exists to catch, and it would push the page's real landmarks down a list nobody can now skim. `group` carries the same accessible name to the same reader on the way in, and carries it nowhere else. For a function name inside a sentence, reach for `Code`.

### Props

- `code` (required) — `string`. The snippet, verbatim. Required even when `html` is supplied, and that is the point: this is what the copy button puts on the clipboard. A block that copies its own rendered markup hands the reader a wall of `<span>`s, and one that copies `textContent` scraped back out of the DOM is a single non-breaking space away from pasting something that does not run.
- `title` — `string`. A filename or a caption, printed at the start of the strip.
- `lang` — `string`. The language, printed at the end of the strip. Optional, and the omission is visible rather than silent: a block with no language gets no label instead of claiming a wrong one. A code block that does not say what it is written in makes the reader infer it from the syntax, which is the one thing they came to the block to learn.
- `maxHeight` — `number | string`. Caps the block's height and scrolls past it. A number is pixels; a string is any CSS length (`'24rem'`, `'50vh'`). The body scrolls in both axes and is focusable, so what is past the fold stays reachable with a keyboard rather than merely present in the DOM.
- `copyable` — `boolean` default `true`. Drops the copy button, for a block nobody is meant to run.
- `copyLabel` — `string` default `'Copy the snippet'`. Accessible copy action, supplied by the host locale.
- `copiedLabel` — `string` default `'Copied'`. Accessible confirmation after copying.
- `label` — `string`. Names the scrollable body for a screen reader. Defaults to `title`, and to "Code" when there is not one.
- `className` — `string`.
- `html` — `undefined`. Absent on this form; `string` on the other. Pass pre-highlighted markup — Shiki's output, run at build time over this same `code` — and the block renders that instead of the plain text. Doing so takes `lineNumbers` and `highlightLines` away with it.
- `lineNumbers` — `boolean` default `false`. Numbers every line, counting from one.
- `highlightLines` — `number[]`. Lines to band, counting from one. A number past the end of the snippet is ignored rather than throwing — the usual cause is a snippet that got shorter while the annotation did not.

## Example — numbered and banded

```tsx
import { CodeBlock } from '@misoto22/design'

<CodeBlock
  title="cn.ts"
  lang="ts"
  lineNumbers
  highlightLines={[5]}
  maxHeight="18rem"
  code={SOURCE}
/>
```

## Example — a command to copy

```tsx
import { CodeBlock } from '@misoto22/design'

<div className="flex w-full flex-col gap-3">
  <CodeBlock code="pnpm add @misoto22/design" lang="bash" label="Install command" />
  <CodeBlock code="pnpm --filter @misoto22/design build" lang="bash" label="Build command" />
</div>
```

## Example — highlighted somewhere else

```tsx
import { CodeBlock } from '@misoto22/design'

<CodeBlock title="tone.ts" lang="ts" code={SOURCE} html={HIGHLIGHTED} />
```

## Example — output nobody runs

```tsx
import { CodeBlock } from '@misoto22/design'

<CodeBlock code={OUTPUT} copyable={false} label="Build output" maxHeight="12rem" />
```

# Markdown

A Markdown string, rendered as this system’s components.

- Group: Display
- Import: `import { Markdown } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/markdown/
- Related: article, code-block, heading, text

## When to reach for it

Content nobody on this side wrote — a comment, a README, a model’s answer. Trusted HTML from your own pipeline is an Article.

## Anatomy

- **Fragment** (required) — What it renders. There is no wrapper element, because Article’s rhythm is a direct-child combinator — anything between the two, display: contents included, would cost every paragraph its spacing.
- **Parser** (required) — parseMarkdown by default: ATX headings, paragraphs, fenced code, blockquotes, nested lists, thematic breaks, and inline emphasis, strong, code, links, images and escapes. Raw HTML is dropped rather than rendered, so this path has no dangerouslySetInnerHTML in it at all.
- **Nodes** (required) — The system’s own components: Heading, Text, Code, CodeBlock and Separator. That is what makes it styled on its own rather than only inside a reading column. One of them is not server-only — a fenced block renders CodeBlock, which is ‘use client’ with useState, useEffect and two icons, so content containing code brings a client component with it.
- **Heading ids** (required) — Slugged from each heading’s own text, in any script, deduplicated within the document with -2, -3. Exported as slugify, so a table of contents can arrive at the same ids without reading them back off the DOM.

## Best practices

### Do

- Set headingLevelStart to the level BELOW the heading the content sits under. Markdown is written as a document, so its # is an <h1>; dropped into a page that already has one, that is two first-level headings and an outline nobody can navigate.
- Put it inside an Article — <Article as="div"> for a comment or an answer, <Article> for a document. Markdown makes the nodes, Article is the column they sit in and the only thing that spaces them, which is also why Markdown renders no element of its own.
- Pass idPrefix when two documents share a page. Both would otherwise claim #installation, and a fragment link lands on whichever the browser found first.
- Bring your own parser through parse for tables, footnotes or task lists. The package ships no parser dependency on purpose: markdown-it measures 110.7 kB minified against the 38.9 kB this package had left under its bundle budget.

### Don’t

- Do not hand it HTML. It parses Markdown; a string of tags renders as the text of those tags, which is the safe answer and not the one you wanted — trusted HTML belongs in Article.
- Do not expect the rhythm without a surface, and do not try to buy it with a gap. Every node renders m-0 into a bare fragment, and prose spacing is not uniform — article.css gives a heading 2.25em above and 0.75em below, which is what sits it with the paragraph it introduces. A uniform gap on a container cannot reproduce that; <Article as="div"> can.
- Do not assume the full GFM surface. Tables, footnotes, task lists, setext headings, reference links and hard breaks are outside the built-in parser, and asking for one silently gets you a paragraph.

## Accessibility

- headingLevelStart shifts the whole document at once, so nested content keeps a valid outline instead of restarting at h1.
- Every heading gets a stable, script-preserving id, deduplicated in document order, so a table of contents can link into it.
- A link whose href carries a scheme that is not http, https, mailto or tel renders as plain text — javascript: never becomes a control.
- A link that leaves for another site carries rel="noreferrer nofollow", so an untrusted author cannot spend the page’s ranking or read its URL out of the Referer. It is not configurable; markExternalLinks adds the visible outbound arrow and is off by default.
- A malformed or empty string renders nothing rather than throwing, which is the normal case for content a reader wrote.

## Markdown

A Markdown string, rendered as this system's components. The gap it fills is content nobody on this side wrote: a comment, a README, a model's answer, a description out of a database. `Article` cannot take those — it renders HTML through `dangerouslySetInnerHTML` and is documented as trusted-input-only — and until now the alternative was a `<pre>` or a sanitiser bolted onto a styling primitive. IT IS NOT AN `Article`, and the two do not merge. `Markdown` turns a string into nodes; `Article` is the reading column those nodes can sit in. It renders a FRAGMENT rather than a wrapper, which is what makes that nesting work — `Article`'s rhythm is a direct-child combinator, so any element between the two, `display: contents` included, would cost every paragraph its spacing. ── It brings type and colour, and no vertical rhythm ── The nodes carry the system's faces and inks on their own, so one of these looks right in isolation. It is not SPACED in isolation: every node renders `m-0`, and a fragment has no box of its own to put a gap in. Nor does a uniform `gap` on a container reproduce it, because prose spacing is not uniform — `article.css` gives a heading 2.25em above and 0.75em below, which is what sits a heading with the paragraph it introduces rather than midway between two. For anything longer than a sentence — a comment, an answer, a README — put it in `<Article as="div">` and get the real rhythm for the cost of one element. ── A fenced code block brings a client component with it ── The renderer is plain functions and has no state, but a fenced block renders `CodeBlock`, which is `'use client'` and arrives with `useState`, `useEffect` and two icons. That is correct — the copy button is the reason the block exists — but "server-rendered" only holds for content with no code in it, which is worth knowing before this goes into a route that has no client bundle yet. ── Why there is no parser in `dependencies` ── Three options, and the decision is written here because it is the one a reader will want to argue with. 1. BUNDLE A PARSER. markdown-it is the obvious pick, and the documentation site already depends on it — but the site is an app and this is a library, where the dependency list is part of the contract every consumer signs. Measured with the same esbuild pass `check:size` uses, markdown-it is 110.7 kB minified against the 38.9 kB this package had left under its bundle budget. It is not close, and "we will raise the budget" is how a design system becomes the largest thing on a page. 2. TAKE PRE-PARSED HTML, the way `Article` does. Cheapest, and wrong for the case this exists for: HTML from an untrusted author is the input this is supposed to make safe, and it cannot carry `headingLevelStart` or stable heading ids without the component parsing markup back apart to find them. 3. PARSE THE SUBSET WE STYLE, and take a `parse` function for the rest. Chosen. The block grammar is line-based and small (see `parse.ts`), it emits React elements rather than markup — so there is no `dangerouslySetInnerHTML` in this path at all, no sanitiser to configure and no sanitiser to get wrong — and a consumer who needs tables, footnotes or task lists passes `parse` and keeps every other promise the component makes. Headings carry an `id` slugged from their own text and deduplicated within the document, so a table of contents can link to them without the caller post-processing the DOM to find out where they went. A link in the source is validated here, at the boundary: a scheme that is not `http`, `https`, `mailto` or `tel` never becomes a link, and one that leaves for another site carries `rel="noreferrer nofollow"` — so an author the page does not trust cannot spend its ranking or read its URL out of the `Referer`.

### Props

- `children` (required) — `string`. The Markdown source. A string — not nodes, not HTML.
- `headingLevelStart` — `MarkdownHeadingLevel` default `1`. The level the document's top heading renders at. Markdown is written as a document, so its `#` is an `<h1>`. Dropped into a page that already has one — inside an `<h2>` section, in a card, under a dialog's title — that produces two first-level headings and an outline a screen reader cannot navigate. Set this to the level BELOW the heading the content sits under, and every level in the document shifts with it.
- `idPrefix` — `string`. Namespaces the generated heading ids. Two documents on one page both containing "Installation" would otherwise both claim `#installation`, and a fragment link would land on whichever the browser found first.
- `markExternalLinks` — `boolean` default `false`. Adds the system's outbound arrow to links that leave for another site. Off by default, and opt-in rather than automatic for two reasons. The mark is an addition to a sentence the component did not write, which is a different kind of act from styling one. And `Markdown` has no idea what origin it is being rendered on, so "leaves for another site" can only mean "carries an `http`/`https` scheme" — an absolute link back to your own domain gets the arrow too. A caller who knows the shape of their content turns it on; one who does not should not have it turned on for them. The `rel` on an outbound link is NOT opt-in and cannot be turned off: it is the security half of the same boundary as the scheme check.
- `parse` — `(source: string) => MarkdownNode[]` default `parseMarkdown`. Bring your own parser. Anything that turns the source into `MarkdownNode`s: markdown-it, remark, or a pipeline that already has an AST and only needs mapping. The node shapes are exported alongside the component as `MarkdownNode`, `MarkdownInline` and `MarkdownHeadingLevel`. The built-in parser covers the subset this system styles; this is the seam for tables, footnotes, task lists and everything else.

## Example — a string into nodes

```tsx
import { Article, Markdown } from '@misoto22/design'

<Article>
  <Markdown headingLevelStart={2}>{SOURCE}</Markdown>
</Article>
```

## Example — a readme fragment

```tsx
import { Article, Markdown } from '@misoto22/design'

<Article>
  <Markdown headingLevelStart={2}>{README}</Markdown>
</Article>
```

## Example — an answer mid stream

```tsx
import { Markdown } from '@misoto22/design'

<div className="flex max-w-prose flex-col gap-4">
  <Markdown headingLevelStart={4}>{ANSWER}</Markdown>
</div>
```

## Example — shifting the outline

```tsx
import { Article, Heading, Markdown, slugify } from '@misoto22/design'

<div className="flex flex-col gap-4">
  <Heading level={2}>Getting started</Heading>
  <nav aria-label="Section links" className="flex flex-col gap-1">
    {SECTIONS.map((section) => (
      <a
        key={section}
        href={`#guide-${slugify(section)}`}
        className="text-sm text-(--ink-2) underline decoration-(--rule-2) underline-offset-4"
      >
        {section}
      </a>
    ))}
  </nav>
  <Article>
    <Markdown headingLevelStart={3} idPrefix="guide">{GUIDE}</Markdown>
  </Article>
</div>
```

## Example — your own parser

```tsx
import { Article, Markdown, parseMarkdown, type MarkdownNode } from '@misoto22/design'

<Article>
  <Markdown parse={withTaskMarks} headingLevelStart={3}>{CHECKLIST}</Markdown>
</Article>
```

# Timestamp

A date or a time, rendered the one way the system renders them.

- Group: Display
- Import: `import { Timestamp } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/timestamp/
- Related: text, badge, description-list

## When to reach for it

Any instant on screen. The alternative is toLocaleString() at the call site, which is how a product ends up with four date formats on one screen.

## Anatomy

- **Element** (required) — A <time> whose datetime is the full ISO instant from the very first render and never changes, so anything parsing the markup gets the exact moment whether or not the effect has run.
- **First paint** (required) — The UTC calendar date, sliced straight out of the ISO string with no Intl anywhere near it. It is what the server renders and what the client renders while hydrating — both sides compute it from the same characters, so they cannot disagree.
- **Local reading** (required) — Applied after mount, in an effect, where there is a reader to be local to: Intl.RelativeTimeFormat with numeric "auto" for the relative form, Intl.DateTimeFormat at dateStyle medium for the absolute one.
- **Missing value** — A value nothing can parse renders an em dash at --ink-3-aa and no <time> at all, because an element whose datetime cannot be written is not a time.

## Best practices

### Do

- Leave format on auto for a record list. It reads relative while the gap is under relativeWithin — a week by default — and switches to the calendar date past it, which is both the more useful fact and the one that stops changing.
- Pass the instant, not a formatted string. A Date, an ISO string or epoch milliseconds all work, and all three end up as the same ISO datetime attribute.
- Re-render from above when a list has to tick. It formats once per mount on purpose: a hundred rows each holding an interval to keep "3 minutes ago" honest is a cost nobody asked for.

### Don’t

- Do not expect the relative text in the server-rendered HTML. The first paint is deliberately the UTC date — a crawler, a static export and a test reading markup all see 2026-01-14, and only a mounted browser sees "3 hours ago".
- Do not format a date beside it with toLocaleString. The two would disagree the moment one page renders on a build server, which is exactly the hydration mismatch this component is built around.
- Do not use it for a duration. It renders an instant relative to now; "2m 14s of build time" is a length, not a moment, and belongs in a plain string.

## Accessibility

- The datetime attribute carries the exact ISO instant from the first render, so assistive technology reading the machine value never depends on an effect having run.
- The visible text changes once after mount and the machine value never does, which keeps the announced value and the parsed value in agreement.
- An unparseable value renders an em dash rather than the browser’s literal "Invalid Date" string, which is an engineering artefact and not something to put in front of a reader.

## Timestamp

A date or a time, rendered the one way the system renders them. Every list of records needs this, and `new Date().toLocaleString()` at the call site is precisely how a product ends up with four date formats on one screen. **On hydration.** Both halves of a formatted date are environment-dependent: a relative time depends on when it is read, and even an absolute one depends on the reader's locale and time zone, none of which a static build knows. So the first paint — the one the server produces and the one the client must reproduce exactly — is the ISO calendar date in UTC, sliced straight out of the ISO string with no `Intl` anywhere near it. Both sides compute it from the same characters, so they cannot disagree. The locale-aware and relative forms are applied after mount, in an effect, where there is a reader to be local to. This package statically exports every page, so the alternative is a hydration mismatch on any page with a date on it. The `datetime` attribute is the full ISO instant from the first render onwards and never changes, so a screen reader, a crawler, or anything else parsing the markup gets the exact moment whether or not the effect has run. It formats once per mount. A hundred rows each holding a ticking interval to keep "3 minutes ago" honest is a cost nobody asked for; a list that must tick should re-key or re-render from above.

### Props

- `value` (required) — `Date | string | number`. The instant. A `Date`, an ISO string, or epoch milliseconds.
- `format` — `TimestampFormat` default `'auto'`. How the instant reads. See TimestampFormat.
- `relativeWithin` — `number` default `604_800_000`. How far from now `auto` still prints a relative time, in milliseconds. Seven days by default — past a week the calendar date is the more useful fact, and it is also the one that stops changing.
- `showTime` — `boolean` default `false`. Adds the clock time to the absolute form.

Also accepts: `Omit<TimeHTMLAttributes<HTMLTimeElement>, 'dateTime' | 'children'>`.

## Example — relative and absolute

```tsx
import { DescriptionList, Timestamp } from '@misoto22/design'

<DescriptionList
  layout="row"
  items={[
    { term: 'Thirty seconds ago', description: <Timestamp value={ago(30_000)} /> },
    { term: 'Ninety seconds ago', description: <Timestamp value={ago(90 * 1000)} /> },
    { term: 'Three hours ago', description: <Timestamp value={ago(3 * HOUR)} /> },
    { term: 'Yesterday', description: <Timestamp value={ago(DAY)} /> },
    {
      term: 'Past auto’s window',
      description: <Timestamp value={ago(30 * DAY)} />,
    },
    {
      term: 'Forced absolute, with the time',
      description: <Timestamp value={ago(5 * MINUTE)} format="absolute" showTime />,
    },
    {
      term: 'A value nothing can parse',
      description: <Timestamp value="tomorrow-ish" />,
    },
  ]}
/>
```

## Example — a column of records

```tsx
import { Badge, TBody, TD, TH, THead, TR, Table, Timestamp } from '@misoto22/design'

<Table caption="Recent deploys">
  <THead>
    <TR>
      <TH>Commit</TH>
      <TH>Finished</TH>
      <TH align="end">Outcome</TH>
    </TR>
  </THead>
  <TBody>
    {DEPLOYS.map((deploy) => (
      <TR key={deploy.sha}>
        <TD className="font-mono text-xs">{deploy.sha}</TD>
        <TD>
          <Timestamp value={deploy.at} />
        </TD>
        <TD align="end">
          <Badge tone={deploy.state}>{deploy.label}</Badge>
        </TD>
      </TR>
    ))}
  </TBody>
</Table>
```

## Example — what the markup carries

```tsx
import { Code, DescriptionList, Timestamp } from '@misoto22/design'

<DescriptionList
  items={[
    { term: 'The value passed in', description: <Code>{AT}</Code> },
    { term: 'auto, past its window', description: <Timestamp value={AT} /> },
    { term: 'absolute, with the time', description: <Timestamp value={AT} format="absolute" showTime /> },
    { term: 'relative, however old', description: <Timestamp value={AT} format="relative" /> },
  ]}
/>
```

# Article

The long-form reading surface — everything a Markdown pipeline emits, in this system’s type.

- Group: Surfaces
- Import: `import { Article } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/article/
- Related: diagram, card

## When to reach for it

A post, a changelog entry, a document. Not for interface copy: a paragraph inside a card is a paragraph, and this is a whole reading column with its own rhythm.

## Anatomy

- **The column** (required) — Whatever as names — article, section or div — tagged data-m22-article, which is what every rule in article.css is scoped to. A 46rem measure and no inline margins of its own, so it sits wherever its parent puts it.
- **Blocks** (required) — The DIRECT children, and where the rhythm lives: air above every block, more above a heading, none on the first. A block one level deeper is outside that rule and outside its spacing.
- **Rendered HTML** — html, written with dangerouslySetInnerHTML. Present it and children are not rendered at all — the trust boundary is the pipeline that produced the string, because there is nothing here that will catch a script tag on the way through.
- **Lead** — p.lead — the standfirst, at --fs-item in full --ink. Marked by the author or the pipeline, never inferred: the stylesheet does not promote whatever happened to come first.
- **Wide blocks** — figure, table and .m22-wide are the three things allowed out of the measure, because a six-column table and an image with a subject in it are both unreadable at 46rem.

## Best practices

### Do

- Centre it yourself. It sets a measure, not a layout — with no auto margins it sits against the start edge of a wide page until a parent centres it.
- Keep every block a direct child: the rhythm is a child combinator, so a <div> wrapped around a run of paragraphs — even a display:contents one, which removes the box but not the node — costs all of them their spacing.
- Have the pipeline wrap a wide table in .m22-table-scroll. A table is allowed out of the measure and has nothing of its own to scroll inside, so eight columns push the whole page sideways instead.
- Sanitise before the string arrives, and mark the boundary where you do it: html is set as innerHTML, so a CMS field that reaches this prop unsanitised is stored XSS with a reading measure.

### Don’t

- Do not pass html and children together — html wins and the children are dropped. It says so in development now, but html="" is still html, so a pipeline that rendered nothing takes the children down with it. A post that mixes prose with components is two Articles in order, not one holding both.
- Do not count on a nested component’s utilities holding inside one: article.css is imported unlayered and beats Tailwind’s @layer utilities whatever the specificity, so any property these rules also set is overridden. A component that must keep one needs an inline style, or a tag the stylesheet does not reach.
- Do not nest six heading levels: h5 and h6 are set as mono uppercase 11px eyebrows rather than as smaller headings, so a document loses its type hierarchy at exactly the depth that needed one.

## Accessibility

- An <article> by default, so the piece is a landmark a reader can jump to.
- Every heading carries scroll-margin, so an anchored link does not park the heading under a fixed masthead.
- The styles are imported unlayered, so inside an article they beat a component’s layered utilities — which is what lets a Markdown paragraph give its margin up to the article’s rhythm.

## Article

The long-form reading surface. Everything a Markdown pipeline can emit — headings, prose, lists, tables, quotations, code, figures, footnotes, MathML — set in this system's type, colour and rules. The styles live in `article.css` rather than in a class string, because the input is not JSX: there is no component to hang a class on when the markup arrived as a string, so the contract has to be the element names themselves. That file is published on its own as `@misoto22/design/article.css`, so a site with its own Markdown pipeline can take the reading surface without taking the components — which is the case this exists for. Three sites hand-rolling a prose stylesheet is three prose stylesheets that drift. Composable either way: pass `html` for a rendered string, or children for real elements — one or the other, never both. `html` wins when both arrive, and says so in development: `html=""` is still `html`, which made losing a page of children a thing that could happen without a word. A post that mixes the two — prose with a `Diagram` dropped into the middle — renders its blocks in order and gives each one an `Article`. Inside one, these rules BEAT a component's utilities: `article.css` is imported unlayered while Tailwind's utilities sit in `@layer utilities`, and an unlayered rule wins over a layered one whatever either one's specificity is. That is the mechanism rather than an accident — it is what lets a `Markdown` paragraph, a `Text` carrying `m-0`, give its margin up to the article's rhythm. A component that has to hold a property inside an article needs an inline style, not a class.

### Props

- `html` — `string`. Rendered HTML from a Markdown or MDX pipeline. Trusted markup only. This sets `dangerouslySetInnerHTML`, so it must come from content you control — a repository's own posts, a CMS you author — and never from a reader. Untrusted Markdown has to be sanitised before it reaches here; that is a pipeline decision, not a component one, and a sanitiser bolted on inside a styling primitive would be the wrong place to make it and the easiest place to get it wrong.
- `as` — `'article' | 'div' | 'section'`. The element to render. `article` by default; pass `div` for a fragment.

Also accepts: `HTMLAttributes<HTMLElement>`.

## Example — the reading column

```tsx
import { Article } from '@misoto22/design'

<Article>
  <h2 id="a-heading">A heading, in the editorial serif</h2>
  <p className="lead">
    The opening paragraph is marked, not guessed. It is set at the item size
    in full ink, which is the one place a paragraph is allowed the top of
    the ladder.
  </p>
  <p>
    Body copy sits on the reading measure and nothing wider, with{' '}
    <a href="#a-heading">a link</a>, some <code>inline code</code> and a{' '}
    <strong>strong</strong> word in it.
  </p>
  <blockquote>
    Depth is a hairline and a change of ground, never a blur.
    <cite>The White Reset, law 2</cite>
  </blockquote>
  <ul>
    <li>The list marker is a hairline dash, not a filled disc.</li>
    <li>A filled circle in this system means a status dot.</li>
  </ul>
</Article>
```

## Example — a markdown block

```tsx
import { Article, Markdown } from '@misoto22/design'
import '@misoto22/design/tokens.css'

<Article>
  <h2>Notes from the review</h2>
  <p>
    One question came back on the packaging, and the answer is worth keeping
    with the code rather than in the thread it was asked in.
  </p>
  <Markdown headingLevelStart={2} idPrefix="reply">
    {REPLY}
  </Markdown>
</Article>
```

## Example — past the measure

```tsx
import { Article } from '@misoto22/design'

<Article>
  <h2>What each release changed</h2>
  <p>
    The table is wider than the column it sits in, which is the point: it
    scrolls inside its own wrapper instead of taking the page with it.
  </p>
  <div className="m22-table-scroll">
    <table>
      <caption>Published releases</caption>
      <thead>
        <tr>
          <th scope="col">Version</th>
          <th scope="col">Released</th>
          <th scope="col">Components</th>
          <th scope="col">Tokens</th>
          <th scope="col">Bundle</th>
          <th scope="col">Tag</th>
        </tr>
      </thead>
      <tbody>
        {RELEASES.map((release) => (
          <tr key={release.version}>
            <th scope="row">{release.version}</th>
            <td>{release.date}</td>
            <td>{release.components}</td>
            <td>{release.tokens}</td>
            <td>{release.size}</td>
            <td>{release.tag}</td>
          </tr>
        ))}
      </tbody>
    </table>
  </div>
  <figure>
    <div className="grid h-28 place-items-center rounded-(--radius) bg-(--stone) mono-meta text-(--ink-3-aa)">
      a figure, out past the measure
    </div>
    <figcaption>A figure takes the full width too, and keeps its caption with it.</figcaption>
  </figure>
</Article>
```

# Card

A bounded surface, with no shadow under it.

- Group: Surfaces
- Import: `import { Card } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/card/
- Related: table, figure-band

## When to reach for it

A card that needs to read as raised is a plate, which separates by reversal instead of by blur.

## Anatomy

- **Box** (required) — A <div> with the --radius-lg corner and one of three grounds: outline, a hairline on the page ground and the default; plate, the one reversed feature surface; flat, no border at all, for a card whose grid already draws the rules between cells. It brings no padding, and it clips to its own corner.
- **Header** — CardHeader — a space-between row above a hairline, px-5 py-4: title against the start edge, one marker or action against the end.
- **Title** — CardTitle, in the editorial serif at --fs-item. An <h3> unless as says otherwise, and it reads --card-title rather than --ink directly, which is what keeps it legible when plate re-points that variable.
- **Body** — CardBody — the content well at p-5, --ink-2, relaxed leading.
- **Footer** — CardFooter — a quiet strip under a hairline, mono-meta at --ink-3-aa, for metadata or a secondary action.

## Best practices

### Do

- Pass as on CardTitle: h3 is right inside a section that owns an h2 and wrong nearly everywhere else, and a grid of twelve cards is otherwise twelve h3s with no heading above them to belong to.
- Use CardTitle inside a plate rather than your own heading — plate re-points --card-title to --on-feature, and a title that reads --ink directly came out at 1.25:1 on that ground: invisible, and invisible only on the one variant whose job is to look different.
- Add the padding yourself when you skip the sub-parts: the box has none of its own, so children dropped straight in sit against the border.
- Pass overflow-visible for the card that deliberately overhangs — a marker pinned to its edge, a control that breaks the outline. The box clips by default, because a card that rounds and does not clip lays a full-bleed image’s square corners over its round ones.

### Don’t

- A Card with an onClick is a div with an onClick — not focusable, not announced, unreachable by keyboard. Put a real control inside and let it stretch, so what is announced is a button and the whole card is still the target.
- Do not spend plate more than once on a screen: it is the system’s single reversed surface, and a band of plates is a band with no ground left to reverse against.

## Card

A bounded surface. No shadow, by law: depth in this system is a hairline and a change of ground, never a blur. A card that needs to read as raised is a `plate`, which separates by reversal instead. It clips to its own corner. A card that rounds and does not clip lays a full-bleed image's square corners over its round ones at all four corners, and the same goes for a filled first child — a defect that is invisible until the first card with an image at the top of it. Pass `overflow-visible` for the rarer card that deliberately overhangs. Compose with the named sub-parts, or drop children straight in when the card has no header or footer to speak of.

### Props

- `variant` — `'outline' | 'plate' | 'flat'` default `'outline'`. `outline` is a hairline box on the page ground — the default, and correct for a card sitting among other cards. `plate` fills with the one reversed surface and is for a card that IS the point of its band; use at most one per screen. `flat` drops the border entirely, for a card whose grid already draws the rules between cells.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## CardHeader

Header row — title on the left, an action or marker on the right.

## CardTitle

The card's title, in the editorial serif. An `<h3>` by default, which is right inside a section with its own `<h2>` and wrong nearly everywhere else — pass `as` rather than leaving a page with a heading order that jumps.

## CardBody

The content well.

## CardFooter

A quiet strip for metadata or secondary actions.

## Example — variants

```tsx
import { Badge, Card, CardBody, CardFooter, CardHeader, CardTitle } from '@misoto22/design'

<div className="grid w-full gap-4 sm:grid-cols-2">
  <Card>
    <CardHeader>
      <CardTitle>Recent deploys</CardTitle>
      <Badge tone="success">green</Badge>
    </CardHeader>
    <CardBody>Twelve releases in the last thirty days, none rolled back.</CardBody>
    <CardFooter>Updated 4 minutes ago</CardFooter>
  </Card>
  <Card variant="plate">
    <CardHeader className="border-(--ink-3)">
      <CardTitle className="text-(--on-feature)">The reversed plate</CardTitle>
    </CardHeader>
    <CardBody className="text-(--on-feature)/80">
      One per screen. It separates by reversal, because this system has no blur to raise it with.
    </CardBody>
  </Card>
</div>
```

## Example — a real control

```tsx
import { Badge, Card, CardBody, CardHeader, CardTitle, Text } from '@misoto22/design'

<Card className="relative w-full max-w-sm transition-colors duration-(--duration-fast) hover:border-(--ink)">
  <CardHeader>
    <CardTitle as="h3">
      <a href="#deployments" className="text-inherit no-underline after:absolute after:inset-0">
        api.misoto22.com
      </a>
    </CardTitle>
    <Badge tone="success">live</Badge>
  </CardHeader>
  <CardBody>
    <Text size="sm">Deployed from main four minutes ago, in 2m 14s.</Text>
  </CardBody>
</Card>
```

## Example — a ruled grid

```tsx
import { Card, CardBody, CardTitle, Heading, Text } from '@misoto22/design'

<section className="w-full">
  <Heading level={2} size="item" className="mb-4">
    Revenue by region
  </Heading>
  <div className="grid gap-px overflow-hidden rounded-(--radius-lg) border border-(--rule) bg-(--rule) sm:grid-cols-3">
    {REGIONS.map((region) => (
      <Card key={region.name} variant="flat" className="rounded-none bg-(--paper)">
        <CardBody>
          <CardTitle as="h3">{region.name}</CardTitle>
          <Text size="sm" className="mt-2 tabular-nums">
            {region.orders} orders
          </Text>
          <Text size="sm" tone="strong" className="mt-1 tabular-nums">
            {region.revenue}
          </Text>
        </CardBody>
      </Card>
    ))}
  </div>
</section>
```

# AppShell

Two columns on a desktop, a drawer on a phone.

- Group: Surfaces
- Import: `import { AppShell } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/app-shell/
- Related: nav-item, page-header

## Anatomy

- **Frame** (required) — The root: min-h-svh on --paper, one column on a phone and a 15rem sidebar beside a 1fr content column from md up. It is the grid and nothing else — no padding, no measure.
- **Sidebar** (required) — An <aside> named by sidebarLabel, 15rem wide. A static grid column on a desktop; on a phone a fixed drawer that slides in from the edge reading STARTS at, so it comes from the right in a right-to-left document.
- **Brand** — brand, in a 3.5rem row at the top of the sidebar above a hairline — the same height as the topbar, so the two rules meet across the column boundary. Omit it and the nav starts at the top and that line is gone.
- **Nav** (required) — A <nav> named by navLabel, “Primary” by default, holding the sidebar prop. It is the part that scrolls, with scroll-slim, so a list that outgrows the column moves under a brand that stays put.
- **Topbar** (required) — A sticky 3.5rem header at --paper/85 with a backdrop blur and a hairline under it, holding the toggle and then topbar. It is rendered whether or not you pass one.
- **Drawer toggle** — A 44px button, phone-only, swapping Menu for X and carrying aria-expanded plus aria-controls pointing at the sidebar. Its only name is openLabel or closeLabel.
- **Scrim** — A full-screen <button> named by closeLabel, mounted only while the drawer is open and hidden from md up.
- **Content well** (required) — contentAs — a <main> by default — centred at --w-page with --page-pad either side and py-8. The measure and the page padding are the shell’s, so a child that adds its own puts a second measure inside the first.

## Best practices

### Do

- Pass contentAs="div" for a shell rendered inside another page — a documentation preview, a screenshot harness. A document may hold exactly one main, and the second one leaves assistive tech unable to answer “where is the content”.
- Name both landmarks when a page could hold two shells: sidebarLabel and navLabel are the only way one complementary is told from another, and the only way a non-English app gets landmark names its readers can read.
- Translate openLabel and closeLabel with everything else — the toggle holds an icon and no text, so those strings are its entire accessible name on every page of the app.
- Put the whole sidebar in the sidebar prop and let the nav scroll it: build the column yourself with the brand inside it and a long list carries the brand off the top of the screen with it.

### Don’t

- Do not treat the closed drawer as unmounted: below md it is translated off-screen and marked inert, not removed, so everything inside it still renders and still runs its effects — a nav item that measures itself measures a box nobody can see.
- Do not assume no topbar means no bar: the header renders regardless, so a shell with nothing to put up there still costs 3.5rem and a rule across the page.
- Do not wrap the children in your own max-width and page padding — the well already applies both, and the content ends up in the middle of the middle.

## Accessibility

- The drawer closes on Escape as well as on the scrim, so a keyboard user is not stranded inside it.
- The scrim is a <button>, because a div with an onClick is neither reachable nor announced.
- Below md the closed drawer carries inert, so its links are out of the tab order and out of the accessibility tree rather than merely off screen. Above md it never is: there the sidebar is the page’s navigation column.
- Both ways out return focus to the toggle. Focus left inside an inert subtree is focus the browser throws away, and the scrim is worse — it is the focused element and it unmounts.

## AppShell

Two columns on a desktop, one column and a drawer on a phone. The drawer closes on Escape as well as on the scrim, because a drawer that only closes by tapping outside it strands a keyboard user inside a menu they cannot leave. The scrim is a `<button>` for the same reason — a `<div>` with an `onClick` is not reachable by keyboard and not announced as anything. Below `md` the closed drawer is `inert`. Sliding it off-screen is a visual state and nothing more: without that attribute every link in it stays focusable and stays in the accessibility tree, so Tab from the toggle walks into a menu nobody can see. Closing it also returns focus to the toggle, because the element focus was on is the element that just left.

### Props

- `sidebar` (required) — `ReactNode`. Navigation content for the sidebar (e.g. a stack of `NavItem`s).
- `topbar` — `ReactNode`. Optional content for the sticky topbar, laid out after the mobile toggle.
- `brand` — `ReactNode`. Optional brand lockup pinned to the top of the sidebar.
- `contentAs` — `'main' | 'div'`. Which element the content well renders as. `main` is right for the shell of an application, and is the default. A document may contain exactly one `main` landmark, so an AppShell rendered INSIDE another page — a preview on a documentation site, a screenshot harness — must pass `div`, or the page has two and assistive tech can no longer answer "where is the content".
- `sidebarLabel` — `string` default `'Sidebar'`. Names the sidebar landmark. Two `complementary` landmarks with the same name cannot be told apart, and a shell rendered inside another page — a preview, a screenshot harness — makes exactly that pair. It is also the only way a non-English app gets a landmark name its readers can read.
- `navLabel` — `string` default `'Primary'`. Names the navigation landmark inside the sidebar.
- `openLabel` — `string` default `'Open navigation'`. The drawer toggle, closed and open.
- `closeLabel` — `string` default `'Close navigation'`.
- `children` (required) — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## Example — columns and drawer

```tsx
import { AppShell, Card, CardBody, CardTitle, NavItem } from '@misoto22/design'

<div className="h-96 w-full overflow-hidden rounded-(--radius) border border-(--rule) [&_[class*=min-h-svh]]:min-h-0">
  <AppShell
    // A page may have only one <main>, and this preview sits inside the
    // documentation site's own.
    contentAs="div"
    // The documentation site has a sidebar of its own, and two
    // complementary landmarks with one name cannot be told apart.
    sidebarLabel="Console sidebar"
    navLabel="Console navigation"
    brand={<span className="font-heading text-base">Console</span>}
    sidebar={
      <>
        <NavItem href="#" icon={RiHomeLine} active>Overview</NavItem>
        <NavItem href="#" icon={RiShapesLine}>Components</NavItem>
        <NavItem href="#" icon={RiSettings3Line}>Settings</NavItem>
      </>
    }
    topbar={<span className="mono-meta text-(--ink-3-aa)">production</span>}
  >
    <Card>
      <CardBody>
        <CardTitle>Content well</CardTitle>
      </CardBody>
    </Card>
  </AppShell>
</div>
```

## Example — a scrolling nav

```tsx
import { AppShell, NavItem, Separator, Text } from '@misoto22/design'

<div className="h-96 w-full overflow-hidden rounded-(--radius) border border-(--rule) [&_[class*=min-h-svh]]:min-h-0">
  <AppShell
    contentAs="div"
    sidebarLabel="Fleet sidebar"
    navLabel="Fleet navigation"
    brand={<span className="font-heading text-base">Fleet</span>}
    sidebar={
      <>
        {SECTIONS.map((section) => (
          <NavItem key={section.label} href="#" icon={section.icon} active={section.label === 'Deploys'}>
            {section.label}
          </NavItem>
        ))}
        <Separator className="my-2" />
        <NavItem href="#">Documentation</NavItem>
      </>
    }
  >
    <Text>
      The sidebar scrolls on its own. The brand row above it does not, and
      neither does the topbar — which is rendered here even though nothing
      was passed to it.
    </Text>
  </AppShell>
</div>
```

## Example — the content well

```tsx
<div className="h-96 w-full overflow-hidden rounded-(--radius) border border-(--rule) [&_[class*=min-h-svh]]:min-h-0">
  <AppShell
    contentAs="div"
    sidebarLabel="Project sidebar"
    navLabel="Project navigation"
    brand={<span className="font-heading text-base">misoto22</span>}
    sidebar={
      <>
        <NavItem href="#" icon={RiDashboardLine}>Overview</NavItem>
        <NavItem href="#" icon={RiGitBranchLine} active>Deploys</NavItem>
        <NavItem href="#" icon={RiStackLine}>Packages</NavItem>
      </>
    }
    topbar={<Badge tone="success">all green</Badge>}
  >
    <Heading level={1} size="heading">
      Deploys
    </Heading>
    <Text className="mt-3">
      Twelve releases in the last thirty days, none rolled back. No wrapper
      around this column — the well is the measure.
    </Text>
    <div className="mt-6 grid gap-4 sm:grid-cols-2">
      <Card>
        <CardHeader>
          <CardTitle as="h2">api</CardTitle>
          <Badge tone="success">live</Badge>
        </CardHeader>
        <CardBody>Deployed from main, 2m 14s ago.</CardBody>
      </Card>
      <Card>
        <CardHeader>
          <CardTitle as="h2">web</CardTitle>
          <Badge tone="warning">building</Badge>
        </CardHeader>
        <CardBody>Started 40 seconds ago on codex/ui-library.</CardBody>
      </Card>
    </div>
  </AppShell>
</div>
```

# PageHeader

A page opening: what this page is, and what qualifies it.

- Group: Surfaces
- Import: `import { PageHeader } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/page-header/
- Related: heading, breadcrumb, app-shell

## When to reach for it

The top of a route’s own column. AppShell is the frame AROUND a page; this is the first thing inside one.

## Anatomy

- **Header** (required) — A <header>, and therefore the page’s banner landmark. A column with a hairline under it and 24px of clearance below the rule — no top padding, so the shell decides where the page starts.
- **Trail** — breadcrumb, above everything, as a rendered Breadcrumb rather than its items — the crumbs stay the caller’s to wire to a router. Left off inside a frame that already pins one.
- **Eyebrow** — eyebrow in the mono kicker at --ink-3-aa, above the title and never below it. A page numeral, or the section the page belongs to.
- **Title** (required) — title through Heading at --fs-heading, as an h1 unless level says otherwise. The size never follows the level: a page opening stands over a working screen rather than over a document whose subject is its own title, at every step of the outline.
- **Actions** — actions, on the title’s baseline at the inline end. Controls that say which slice the title refers to — a range picker, a scope switch — not controls that act on the records.
- **Description** — description under the title, capped at --measure-record so it stays a readable measure while the row above it runs the full width.

## Best practices

### Do

- Put the range picker here rather than above the table. It qualifies the title — it says which slice of the archive the page is about — and below the rule it becomes a toolbar arguing with whatever strip the page starts with.
- Leave breadcrumb off inside a shell that already pins a trail. Two trails on one screen are two answers to “where am I”, and a reader checks both.

### Don’t

- Do not render two openings on one page at level 1. Each is an h1, so the second is a second document as far as heading navigation is concerned; a preview or a template inside a page that has its own h1 is what level is for.
- Do not put a second finding in description. One sentence saying what the page is for; a number that changes belongs under the rule, beside the figures it is comparable with.

## Accessibility

- The title is an h1 by default, so the page has a name in the heading list whatever the shell around it is doing, and level moves it where the opening is not the document’s.
- The <header> is the page’s banner landmark, which is what a landmark-based reader jumps to first.

## PageHeader

A page opening: what this page is, and what qualifies it. The system has `Heading` for a heading and `Breadcrumb` for a trail, and nothing that said how a page STARTS — so every application invented the arrangement, and the eyebrow landed above the title on one screen and below it on the next. This fixes the order, the rule under it, and where the controls sit. Distinct from `AppShell`, which is the frame around a page rather than the top of one: a shell holds the rail and the bar for every route, and this is the first thing inside the route's own column. The title renders as an `h1` unless `level` says otherwise, and it is worth saying why the default is the whole answer nearly always: a page has one name, and a shell that owns the document's heading has taken the page's own name away from it. A second opening on one screen is two pages. The SIZE is not a prop at all. `Heading` at level 1 defaults to `--fs-title`, which is the editorial step for a document whose subject IS its title; a page opening stands over a working screen, where the title is the label for what follows and the records under it are what the reader came for. `--fs-heading` is that step at every level, and `Heading` is what draws it, so the ladder stays one ladder and moving an opening down the outline never resizes it.

### Props

- `title` (required) — `ReactNode`. What this page is. One line, and the only thing at this weight.
- `eyebrow` — `ReactNode`. The kicker above the title. A wayfinding aid rather than decoration: in a console whose pages are referred to by a numeral, this is that numeral, and elsewhere it is the section the page belongs to.
- `description` — `ReactNode`. One sentence saying what the page is for. Never a second finding.
- `breadcrumb` — `ReactNode`. The trail above the opening, for a shell that does not already pin one. A page rendered inside an application frame usually leaves this off — two trails on one screen are two answers to "where am I". Takes the rendered `Breadcrumb` rather than its items, so the crumbs stay the caller's to wire to a router.
- `actions` — `ReactNode`. Controls that qualify what the page IS, set inside the opening rather than above the content. The distinction is worth holding: a range picker does not act on the records, it says which slice of them the title refers to. Below the rule it becomes a toolbar competing with whatever strip follows; beside the title it reads as part of the heading, which is what it is.
- `level` — `HeadingLevel` default `1`. The heading level `title` opens, in the document the opening lands in. Defaults to `1`, which is what a page opening IS: a page has one name, and a shell that owns the document's heading has taken the page's own name away from it. Move it only where the opening is not the document's — a preview canvas, a template shown inside a documentation page, a composition embedded under a host's own `h1`. The size does not follow the level. `title` renders at `--fs-heading` at every level, because moving an opening down the outline is a fact about the document and not a request for smaller type.
- `className` — `string`.

Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'title'>`.

## Example — default

```tsx
import { Breadcrumb, Button, PageHeader } from '@misoto22/design'

<PageHeader
  breadcrumb={
    <Breadcrumb
      label="Page trail"
      items={[{ label: 'Living', href: '#/living' }, { label: 'Money' }]}
    />
  }
  eyebrow="04"
  level={2}
  title="Money"
  description="Balances and flows across every account, as at the last sync."
  actions={
    <Button size="sm" variant="secondary">
      Last 7 days
    </Button>
  }
/>
```

## Example — a title and nothing else

```tsx
export function Example() {
  return <PageHeader level={2} title="Jobs" />
}
```

# Calendar

A month, as a grid of days.

- Group: Surfaces
- Import: `import { Calendar } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/calendar/
- Related: date-picker

## When to reach for it

On its own for a range view or an availability grid; inside a DatePicker for choosing one.

## Anatomy

- **Day grid** (required) — The month: a mono weekday row over one 36px pill-cornered button per day, five rows in most months and six in some. Days from the neighbouring months are shown and dimmed rather than left as holes.
- **Caption** (required) — “September 2026” as ONE button carrying aria-expanded, not two dropdowns — that is how the date is said, and splitting it put four controls in a 250px row that also has to hold two arrows.
- **Month arrows** (required) — The library’s nav, lifted out of the flow and laid across the caption at the same 36px height so the two sit at either end of the month name. Both step away while the picker is open: two ways to change the month, one of them behind a panel, is one too many.
- **Month and year picker** — A role="dialog" drawn IN PLACE of the day grid rather than over it — twelve months in a 3×4 and up to twenty-four years in a 4×6, at exactly the size of the grid they replace. Focus moves in when it opens and Tab wraps inside it; Escape closes it and puts focus back on the caption.
- **Day marks** (required) — Today is a ring and selected is a fill. In a range the wash lives on the CELL and the fill on the ends’ BUTTONS, which is what lets a range read as one band with round ends — and lets a one-day range, which is both ends at once, stay round.

## Best practices

### Do

- Pass locale rather than trusting the page’s lang: the caption is formatted by Intl from locale.code and falls back to en-US, so a French calendar says “September” until the prop is set.
- Re-add the library’s own class when you override a slot through classNames — yours REPLACES ours, and ours carries the .rdp-* hook every downstream selector depends on. Overriding root without rdp-root took that hook off the tree.
- Mark availability through the classNames slots rather than by styling the day button: the wash belongs to the cell and the mark to the button, and a background put on the button flattens the round end of a range.
- Know what widening the span costs: the year grid pages 24 at a time, so the default ten either side is one page and no paging, and a range wide enough for a birth date is a reader stepping through pages to reach 1974.
- Translate the picker’s chrome alongside locale. locale reaches the month names and stops there, so a French calendar with the prop set still names its two panels and its four chevrons “Month and year”, “Previous year” and “Earlier years” until the CalendarLabels props are passed.

### Don’t

- Do not stretch it with a width class: it is w-fit and lays out fixed 36px columns, so w-full only replaces w-fit and leaves the same grid sitting at the start edge of a wider box.
- Do not cut it to a fixed height. The grid is five weeks in most months and six in some, and the picker panel is sized against the grid rather than given a height of its own — a box measured on a five-week month clips the sixth.
- Do not replace MonthCaption through components: the month-and-year picker lives inside ours, so a custom caption leaves the reader with two arrows and no way to move more than one month at a time.

## Accessibility

- Arrows move a day, Page keys move a month, Home and End reach the week’s ends.
- “Today” is an outline and “selected” is a fill — one is a fact about the calendar, the other a choice the reader made, and they must not look alike.
- Month and year are one panel of buttons, not a native select: a platform list of a hundred years is a scroll rather than a choice, and it arrives styled by the operating system.
- Tab wraps inside the open panel. It is opaque and the day grid is still mounted under it, so a Tab that left would put the reader on a day they cannot see — and past the caption that owns the Escape handler.
- The default span is ten years either side. A birth date needs a wider one, and asks for it with startMonth.

## Keyboard

- ← / → — Moves by a day.
- ↑ / ↓ — Moves by a week.
- Page Up / Page Down — Moves by a month.
- Home / End — Jumps to the week's first or last day.
- Enter / Space — Chooses the focused day.

## Calendar

A month, as a grid of days. Wraps react-day-picker rather than building a calendar, and the reason is the long tail: a month grid is easy, and everything around it is not — the keyboard contract (arrows move a day, Page moves a month, Home and End reach the week's ends), the `aria-live` announcement when the month changes, week numbering, the first day of the week varying by locale, and the fact that "today" and "selected" are different states a screen reader must hear apart. Every class is replaced rather than layered over the library's stylesheet, so nothing here depends on a CSS file this package does not control — but the library's OWN class is kept on each slot, because passing a class REPLACES it and every `.rdp-*` selector downstream depends on those. The month names follow `locale`. The picker's own chrome — the two panels and the four chevrons that browse them — follows `CalendarLabels`, because `locale` cannot supply strings this package invented.

### Props

- `monthPanelLabel` — `string`. Names the panel showing twelve months.
- `yearPanelLabel` — `string`. Names the panel showing a page of years.
- `previousYearLabel` — `string`. The two chevrons that browse a year at a time, inside the month panel.
- `nextYearLabel` — `string`.
- `earlierYearsLabel` — `string`. The two chevrons that page the year grid, twenty-four at a time.
- `laterYearsLabel` — `string`.

Also accepts: `DayPickerProps`.

## Example — a range

```tsx
import { Calendar } from '@misoto22/design'

<Calendar
  mode="range"
  selected={range as never}
  onSelect={setRange as never}
  defaultMonth={new Date(2026, 8, 1)}
  labels={{ labelNav: () => 'Range example navigation' }}
/>
```

## Example — one day

```tsx
import { Calendar, Text } from '@misoto22/design'

<div className="flex flex-col items-center gap-4">
  <Calendar
    mode="single"
    selected={day}
    onSelect={setDay}
    defaultMonth={MONTH}
    labels={{ labelNav: () => 'One day example navigation' }}
  />
  <Text size="sm" tone="muted">
    {day ? day.toDateString() : 'nothing chosen'}
  </Text>
</div>
```

## Example — disabled days

```tsx
import { Calendar } from '@misoto22/design'

<Calendar
  mode="single"
  selected={day}
  onSelect={setDay}
  defaultMonth={MONTH}
  startMonth={new Date(2026, 0, 1)}
  endMonth={new Date(2027, 11, 31)}
  disabled={[{ dayOfWeek: [0, 6] }, { before: new Date(2026, 8, 7) }]}
  labels={{ labelNav: () => 'Disabled days example navigation' }}
/>
```

# ScrollArea

A box that scrolls, with a scrollbar that looks the same everywhere.

- Group: Surfaces
- Import: `import { ScrollArea } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/scroll-area/
- Related: table

## When to reach for it

A bounded panel — a long option list, a log. For page-level or prose scroll the scroll-slim utility is lighter and needs no component.

## Anatomy

- **Root** (required) — The bounded box, and where className lands. It is overflow-hidden and has no size of its own, so the height you give it here is the only thing that decides whether anything scrolls at all.
- **Viewport** (required) — The element that actually scrolls, and the one carrying role="region", tabIndex 0 and label. Radix hides the platform’s scrollbar on it and sets the axis WITHOUT a bar to overflow: hidden. It is positioned, so an absolutely-positioned descendant travels with the content instead of hanging still over it.
- **Bar** — One per orientation: an 8px track with a pill thumb at --rule-2, and touch-none — a finger scrolls the content, not the bar. It is drawn only while the pointer is inside the region and fades some 600ms after scrolling stops.
- **Corner** — The square where two bars meet, which exists only at orientation="both" — the default.

## Best practices

### Do

- Give it a height. With none, the root is as tall as its content, nothing ever overflows, and all the component added to the page was a keyboard stop.
- Narrow orientation only when clipping the other axis is the thing you meant. Both axes scroll by default, because the axis without a bar is set to overflow: hidden — what is past that edge is not merely unmarked, it is unreachable by every key and every gesture, with the content perfectly well rendered.
- Pass type="always" when the content ends flush at the boundary: the platform scrollbar is hidden and ours is not drawn until the pointer is inside, so at rest nothing on the screen says the box scrolls.

### Don’t

- Do not build a drag-to-scroll affordance over it — the thumb is deliberately touch-none and the viewport is a real overflow container, so touch dragging, momentum and the wheel are already the platform’s and behave as the reader expects.
- Do not nest one inside another on the same axis: the inner viewport consumes the wheel until it reaches its own end, so a reader aiming at the outer list moves the inner one instead.

## Accessibility

- The viewport stays focusable. A scrollable region whose contents are not focusable has nothing to Tab to, so everything past the fold does not exist without a mouse.
- label is required, because an unnamed keyboard stop announces "group" and nothing else.
- Both axes scroll unless a caller narrows orientation, so content wider than the box stays reachable rather than being clipped without a bar.

## Keyboard

- Tab — Moves focus into the region, which is what makes it scrollable at all without a mouse.
- ↑ / ↓ / Page Up / Page Down — Scrolls it.

## ScrollArea

A box that scrolls, with a scrollbar that looks the same on every platform. The reason to reach for this over `overflow-auto` is not the scrollbar — it is that Radix keeps the viewport focusable and the bar operable, which a bare overflow container does not. A scrollable region whose contents are not themselves focusable is unreachable by keyboard: there is nothing to Tab to, so everything past the fold does not exist without a mouse. For a page-level or prose scroll, the `scroll-slim` utility is lighter and needs no component. This is for a bounded panel: a long option list, a log, a sidebar that outgrows its column. Both axes scroll unless a caller says otherwise. The old vertical default read as a statement about which bar to draw and was in fact a statement about which half of the content existed: Radix sets the viewport's overflow from the mounted bars, so the axis without one was `hidden` and everything past it was unreachable — silently, and with the content perfectly well rendered.

### Props

- `label` (required) — `string`. Names the region. Required, and not decoration: a scroll container is a keyboard stop, and an unnamed stop announces "group" and nothing else.
- `orientation` — `'vertical' | 'horizontal' | 'both'` default `'both'`. Which axes get a bar — and therefore which axes scroll at all. Radix sets the viewport's overflow from the bars that are mounted, so an axis without one is `hidden`: what is past that edge is not merely unmarked, it is unreachable by every key and every gesture. `both` is the default for that reason. Narrow it only when clipping the other axis is the thing you meant.

Also accepts: `ComponentProps<typeof ScrollAreaPrimitive.Root>`.

## Example — a bounded log

```tsx
import { ScrollArea } from '@misoto22/design'

<ScrollArea label="Deploy log" className="h-40 w-full max-w-sm rounded-(--radius) border border-(--rule)">
  <ul className="m-0 list-none p-3 text-sm">
    {LINES.map((line) => (
      <li key={line.sha} className="flex justify-between gap-4 py-1 mono-meta text-(--ink-2)">
        <span>{line.sha}</span>
        <span className="text-(--ink-3-aa)">{line.state}</span>
      </li>
    ))}
  </ul>
</ScrollArea>
```

## Example — both axes

```tsx
import { ScrollArea } from '@misoto22/design'

<ScrollArea
  label="Request log"
  orientation="both"
  className="h-48 w-full max-w-md rounded-(--radius) border border-(--rule)"
>
  <table className="w-max border-collapse text-start">
    <caption className="sr-only">Request log</caption>
    <thead>
      <tr>
        {COLUMNS.map((column) => (
          <th key={column} scope="col" className="whitespace-nowrap px-3 py-2 text-start eyebrow text-(--ink-3-aa)">
            {column}
          </th>
        ))}
      </tr>
    </thead>
    <tbody>
      {ROWS.map((row) => (
        <tr key={row[4]}>
          {row.map((cell, index) => (
            <td key={index} className="whitespace-nowrap px-3 py-1 mono-meta text-(--ink-2)">
              {cell}
            </td>
          ))}
        </tr>
      ))}
    </tbody>
  </table>
</ScrollArea>
```

## Example — a permanent bar

```tsx
import { ScrollArea, Text } from '@misoto22/design'

<ScrollArea
  label="Keyboard shortcuts"
  type="always"
  className="h-44 w-full max-w-sm rounded-(--radius) border border-(--rule)"
>
  <dl className="m-0 grid grid-cols-[auto_1fr] items-baseline gap-x-4 gap-y-2 p-3">
    {SHORTCUTS.map(([keys, action]) => (
      <div key={keys} className="col-span-2 grid grid-cols-subgrid">
        <dt className="m-0 mono-meta text-(--ink)">{keys}</dt>
        <dd className="m-0">
          <Text as="span" size="sm">{action}</Text>
        </dd>
      </div>
    ))}
  </dl>
</ScrollArea>
```

# DescriptionList

One record’s fields, as a real <dl> rather than a grid of divs.

- Group: Surfaces
- Import: `import { DescriptionList } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/description-list/
- Related: table, card, timestamp

## When to reach for it

One record seen from the front — a detail page, a summary panel. Several records seen from above is a Table.

## Anatomy

- **List** (required) — The <dl>. It is the element that carries the pairing: a grid of divs looks identical and tells a screen reader there are two columns of unrelated text.
- **Pair** (required) — A <div> around each dt/dd, which the HTML specification allows inside a <dl> precisely so a pair can be laid out as a unit. It is what the hairline is drawn on, so the rule crosses the whole row rather than stopping in the column gap.
- **Term** (required) — item.term, rendered as <dt> at --ink-3-aa. In the row layout it holds a 12rem column at sm and above and stacks below it, because a 12rem label column on a phone leaves the value about eight characters wide.
- **Description** (required) — item.description, rendered as <dd> at --ink-2 with its browser margin reset. It takes a node, not a string, so a value can be a Badge, a link or a Timestamp.
- **Hairline** — divided, on by default: a --rule under every pair but the last. Turn it off inside a Card, which already has an edge of its own.

## Best practices

### Do

- Let it render nothing when items is empty. It returns null rather than an empty bordered box, so the page above is free to show an EmptyState instead of a hairline around no content.
- Put an element in description when the value is a state or a link — it is a <dd>, so a Badge, an anchor or a Timestamp belongs there and a string of text does not have to be faked into one.
- Pass id on each item when rows are added, removed or reordered. The index is the key without one, which is right for the fixed field list a record page renders and wrong for a list that changes shape.

### Don’t

- Do not reach for it to show several records. Every dt would repeat down the page and a reader comparing two records has to hold both in their head — that is what a Table’s column headings exist to avoid.
- Do not use layout="row" inside a narrow sidebar. It only collapses on the sm breakpoint, which is the viewport, not the container — a 12rem label column inside a 20rem panel leaves nothing for the value. Use layout="stacked" there.

## Accessibility

- A real <dl>, <dt> and <dd>, which is what tells a screen reader that a label names the value beside it.
- Each pair is grouped in a <div>, which the specification permits inside a <dl> and which assistive technology reads through.
- An empty list renders null rather than an empty <dl>, so nothing announces a list with no items in it.

## DescriptionList

A record's fields: label, value, label, value. The single most repeated shape in any detail page, and the one most often hand-built out of a `<div>` grid — which loses the only thing the markup was carrying. A `<dl>` tells a screen reader that "Owner" names the thing beside it; a grid of divs tells it there are two columns of unrelated text, and the reader has to infer the pairing from reading order alone. Reach for `Table` instead when there are several records. This is one record seen from the front; a table is many records seen from above. Each pair is wrapped in a `<div>` — which the HTML specification allows inside a `<dl>` precisely so a pair can be laid out as a unit — so the hairline runs the full width of the row rather than stopping in the column gap. An empty `items` renders `null` rather than an empty bordered box. A record with no fields is a state the page above should be handling with an `EmptyState`, and a hairline around nothing looks like a component that failed to load.

### Props

- `items` (required) — `DescriptionListItem[]`. The pairs, in the order they should read. An empty array renders nothing.
- `layout` — `DescriptionListLayout` default `'row'`. How the value sits relative to its label. See DescriptionListLayout.
- `divided` — `boolean` default `true`. Draws a hairline under every pair but the last. Off for a list inside a card that already has an edge, on for a list that is the page's structure.

Also accepts: `HTMLAttributes<HTMLDListElement>`.

## Example — record fields

```tsx
import { Badge, DescriptionList, Timestamp } from '@misoto22/design'

<DescriptionList
  items={[
    { term: 'Owner', description: 'Henry Chen' },
    { term: 'Region', description: 'ap-southeast-2' },
    { term: 'Status', description: <Badge tone="success">Deployed</Badge> },
    {
      term: 'Last deploy',
      description: <Timestamp value="2026-01-14T09:30:00.000Z" />,
    },
  ]}
/>
```

## Example — row and stacked

```tsx
import { DescriptionList } from '@misoto22/design'

<div className="grid w-full gap-8 sm:grid-cols-2">
  <DescriptionList items={FIELDS} />
  <DescriptionList layout="stacked" items={FIELDS} />
</div>
```

## Example — a metadata rail

```tsx
import { Badge, DescriptionList, Heading, Text, Timestamp } from '@misoto22/design'

<div className="grid w-full gap-6 sm:grid-cols-[minmax(0,1fr)_14rem]">
  <div className="flex flex-col gap-3">
    <Heading level={3}>ui.misoto22.com</Heading>
    <Text size="sm">
      The documentation site for the design package. Statically exported, so every
      page is HTML on a CDN and the only JavaScript is the parts a reader touches.
    </Text>
  </div>
  <aside className="rounded-(--radius) border border-(--rule-2) p-4">
    <DescriptionList
      layout="stacked"
      divided={false}
      items={[
        { term: 'Owner', description: 'Henry Chen' },
        { term: 'Status', description: <Badge tone="success">Deployed</Badge> },
        { term: 'Region', description: 'ap-southeast-2' },
        {
          term: 'Last deploy',
          description: <Timestamp value="2026-08-28T22:14:00.000Z" />,
        },
      ]}
    />
  </aside>
</div>
```

# Toolbar

The bar of actions at the edge of a working surface.

- Group: Surfaces
- Import: `import { Toolbar } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/toolbar/
- Related: button, app-shell, card

## When to reach for it

A form’s actions that must stay in reach while the form scrolls, or a filter bar over a list. Not a page header — that is AppShell.

## Anatomy

- **Bar** (required) — A <div role="group"> named by label, wrapping its children on a flex row at --z-sticky. It is not role="toolbar": that role promises a single tab stop with arrow keys between the controls, and this implements no such thing.
- **Ground** (required) — Opaque --paper, and deliberately not a blur. Content scrolls UNDER this bar, so anything translucent puts the last row of a table behind the submit button and makes both unreadable.
- **Edge** (required) — A --rule-2 hairline on the side the bar sticks to: border-t for bottom, border-b for top. position="static" keeps the rule and drops the stickiness.
- **Actions** (required) — children, on a flex-wrap row with a --gap of 3. align places them along the inline axis and defaults to end, which is where a form’s primary action goes.

## Best practices

### Do

- Write label as what the bar IS — "Form actions", "List filters". A group with no name is announced as "group", and a page with two of them announces the same nothing twice.
- Give the scrolling ancestor a height for position="bottom". A sticky element sticks within its scroll container, so a bar inside a container that is as tall as its content has nothing to stick to and simply sits at the end.
- Keep it to the actions. A bar that has grown a title, a status and a breadcrumb is a page header, and a page header that follows the reader down the screen is a page with less of itself visible.

### Don’t

- Do not add role="toolbar" through props. The role tells a screen-reader user that arrow keys move between the controls; nothing here implements roving tabindex, so those keys would do nothing and the promise would be false.
- Do not make the ground translucent to "let the content show through". The content it would show through is the row the reader is trying to read, and the button they are trying to press.

## Accessibility

- label is required and becomes the group’s accessible name, so a page with a filter bar and an action bar announces two distinct things.
- Every control keeps its own place in the tab order, because the bar deliberately does not claim role="toolbar" and its single-tab-stop contract.
- The ground is opaque, so a control on the bar always meets its contrast ratio against --paper rather than against whatever happens to be scrolling behind it.

## Keyboard

- Tab — Reaches each control in turn — the bar itself is not a stop.

## Toolbar

The bar of actions at the edge of a working surface. Two page templates built the same thing independently — a sticky strip on `--paper` with a rule along the edge it sticks to — which is the signal that it belongs here rather than in each of them. The ground is opaque `--paper` and not a blur. Content scrolls UNDER this bar, so anything translucent puts the last row of a table behind the submit button and makes both unreadable; `FloatingIconButton` blurs because it floats over a gap, which is a different problem. It is not `role="toolbar"`. That role's contract is a single tab stop with arrow keys moving between the controls inside it, and this implements no such thing — declaring the role without the behaviour tells a screen-reader user to press arrow keys that do nothing. It is a named `group`, so the controls keep their own places in the tab order and the bar is still announced.

### Props

- `label` (required) — `string`. Names the bar for a screen reader — "Form actions", "List filters". Required, because a group with no name is announced as "group" and a page with two of them is a page with two identical announcements.
- `position` — `ToolbarPosition` default `'bottom'`. Which edge the bar sticks to. See ToolbarPosition.
- `align` — `ToolbarAlign` default `'end'`. Where the contents sit along the inline axis.
- `children` (required) — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## Example — form actions

```tsx
import { Button, Text, Toolbar } from '@misoto22/design'

<div className="flex h-56 flex-col overflow-y-auto rounded-(--radius) border border-(--rule-2)">
  <div className="flex flex-1 flex-col gap-4 p-4">
    <Text>Scroll this panel — the bar below stays where it is.</Text>
    <Text size="sm" tone="muted">
      A sticky element sticks within its scroll container, so the container
      needs a height of its own for the bar to have anything to stick to.
    </Text>
    <Text size="sm" tone="muted">
      Keep the bar to the actions. One that has grown a title and a
      breadcrumb is a page header following the reader down the screen.
    </Text>
  </div>
  <Toolbar label="Form actions">
    <Button variant="secondary">Cancel</Button>
    <Button type="submit">Save changes</Button>
  </Toolbar>
</div>
```

## Example — a filter bar on top

```tsx
import { Button, NativeSelect, Text, Toolbar } from '@misoto22/design'

<div className="flex h-56 w-full flex-col overflow-y-auto rounded-(--radius) border border-(--rule-2)">
  <Toolbar label="List filters" position="top" align="between">
    <NativeSelect defaultValue="all" aria-label="Branch">
      <option value="all">All branches</option>
      <option value="main">main</option>
    </NativeSelect>
    <Button size="sm" variant="secondary">
      Export CSV
    </Button>
  </Toolbar>
  <ul className="m-0 flex list-none flex-col gap-3 p-4">
    {ROWS.map((sha) => (
      <li key={sha}>
        <Text as="span" size="sm" className="font-mono">
          {sha}
        </Text>
      </li>
    ))}
  </ul>
</div>
```

## Example — every control is a tab stop

```tsx
import { Button, Text, Toolbar } from '@misoto22/design'

<Toolbar label="Bulk actions for the selected rows" position="static" align="between">
  <Text as="span" size="sm" tone="muted">
    3 rows selected
  </Text>
  <div className="flex flex-wrap items-center gap-2">
    <Button size="sm" variant="secondary">
      Archive
    </Button>
    <Button size="sm" variant="danger">
      Delete
    </Button>
    <Button size="sm" variant="ghost">
      Clear
    </Button>
  </div>
</Toolbar>
```

# AspectRatio

A box that keeps its shape whatever is inside it.

- Group: Surfaces
- Import: `import { AspectRatio } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/aspect-ratio/
- Related: skeleton, card

## When to reach for it

The height has to be known before the content loads — a media grid that would otherwise reflow every time an image arrives.

## Anatomy

- **Box** (required) — A relative, full-width <div> carrying aspect-ratio as an inline style. A style and not a class because Tailwind can only generate what it reads verbatim in the source, and this value arrives at runtime.
- **Children** (required) — Every DIRECT child, taken out of flow and stretched to fill the box. That is what guarantees the ratio holds: nothing inside can contribute a height, so content with no intrinsic size of its own still gets the whole box.
- **Crop** — object-cover on a direct <img> or <video>, so media fills the box rather than being letterboxed inside it. Content that must not be cropped sets object-contain on itself.

## Best practices

### Do

- Reach for it wherever a reflow would otherwise happen when an image lands. That reflow is the layout shift a Core Web Vitals score measures, and reserving the box is the whole fix.
- Set object-contain on the child when the whole picture matters — a logo, a diagram, a screenshot. The default crops, which is right for a photograph and wrong for anything with an edge that means something.
- Give it a width. It is w-full, so inside a container with no width of its own it has no height either, and a box with a ratio and no size is a box that is not there.

### Don’t

- Do not fall back to the padding-top percentage trick beside it. That percentage resolves against the WIDTH, which is why it works at all and also why it breaks as a flex child and eats the element’s own padding.
- Do not put text in it and expect the box to grow. Every child is absolutely positioned, so a paragraph longer than the box is clipped by overflow-hidden rather than pushing it open.

## Accessibility

- A plain box with no role: it constrains geometry and says nothing, so an <img> inside keeps its own alt and nothing is added to the accessible tree.
- Reserving the height before the content arrives is what stops the content under it moving out from under a pointer or a reader mid-tap.

## AspectRatio

A box that keeps its shape whatever is inside it. The one layout primitive that is genuinely hard to hand-roll. The `padding- top: 56.25%` trick everyone reaches for is a percentage of the WIDTH, which is why it works at all and also why it silently breaks the moment the box is a flex or grid child — and it takes the element's own padding with it. The modern `aspect-ratio` property does the same job in one line, and only holds if nothing inside forces a height, which is what the absolute positioning below guarantees. So: the box declares the ratio, and every direct child is stretched to fill it and taken out of flow. That means a child with no intrinsic size at all — an empty `<div>`, a map that measures its container, a skeleton — still gets the full box, and an `<img>` or `<video>` is cropped to cover it rather than letterboxed. Content that must not be cropped should set `object-contain` on itself. Reach for this when the height must be known before the content loads: a media grid that would otherwise reflow every time an image arrives is the usual case, and that reflow is the layout shift a Core Web Vitals score is measuring.

### Props

- `ratio` — `number | string` default `16 / 9`. Width over height. A number (`16 / 9`) or the CSS form (`'16 / 9'`). It is a style rather than a class because Tailwind can only generate what it can read verbatim in the source, and this value arrives at runtime.
- `children` — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## Example — reserved boxes

```tsx
import { AspectRatio, Text } from '@misoto22/design'

<div className="grid gap-4 sm:grid-cols-3">
  {RATIOS.map((ratio) => (
    <div key={ratio} className="flex flex-col gap-2">
      <AspectRatio
        ratio={ratio}
        className="rounded-(--radius) border border-(--rule-2) bg-(--stone)"
      >
        <div />
      </AspectRatio>
      <Text as="span" size="xs" tone="muted" className="font-mono">
        {ratio}
      </Text>
    </div>
  ))}
</div>
```

## Example — a grid that cannot reflow

```tsx
import { AspectRatio, Skeleton, Text } from '@misoto22/design'

<div className="grid w-full gap-4 sm:grid-cols-3">
  {POSTS.map((post) => (
    <article key={post.slug} className="flex flex-col gap-2">
      <AspectRatio ratio="3 / 2" className="rounded-(--radius) border border-(--rule-2)">
        <Skeleton />
      </AspectRatio>
      <Text as="span" size="sm">
        {post.title}
      </Text>
    </article>
  ))}
</div>
```

## Example — the ratio wins

```tsx
import { AspectRatio, Text } from '@misoto22/design'

<div className="grid w-full gap-4 sm:grid-cols-2">
  <div className="flex flex-col gap-2">
    <AspectRatio ratio="16 / 9" className="rounded-(--radius) border border-(--rule-2)">
      <Text size="sm" className="p-3">
        {NOTE}
      </Text>
    </AspectRatio>
    <Text as="span" size="xs" tone="muted" className="font-mono">
      clipped
    </Text>
  </div>
  <div className="flex flex-col gap-2">
    <AspectRatio ratio="16 / 9" className="rounded-(--radius) border border-(--rule-2)">
      <div className="overflow-y-auto p-3 scroll-slim">
        <Text size="sm">{NOTE}</Text>
      </div>
    </AspectRatio>
    <Text as="span" size="xs" tone="muted" className="font-mono">
      overflow-y-auto on the child
    </Text>
  </div>
</div>
```

# Table

A ruled data table — alignment, sorting and rules all per column.

- Group: Data
- Import: `import { Table } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/table/
- Related: card, figure-band

## When to reach for it

Alignment is per column and numbers belong at the end edge, so digits line up. Sorting is opt-in per column: a table where every header is a button invites sorting a column the data cannot be ordered by.

## Anatomy

- **Scroll region** (required) — The focusable <div role="region"> around the table, named by caption. It carries the border setting and the density attribute, and it is what scrolls sideways — so the table exceeds the measure and the page does not. It is also positioned, which is what keeps an sr-only label inside a cell from resolving against the document and dragging the page sideways with it.
- **Caption** (required) — A real <caption>, visually hidden unless showCaption prints it as an eyebrow above the table. The same string is the scroll region’s accessible name, so it is heard on the way in and again from the table.
- **Column label** (required) — TH — mono and uppercase so it never reads as data, aligned per column, and always emitting scope="col" unless a call site overrides it.
- **Sort control** — On a sortable header only: a <button> INSIDE the th, with ArrowUp, ArrowDown or a dimmed ChevronsUpDown beside the label, and aria-sort on the th set from sortDirection.
- **Cells** (required) — TD — top-aligned at --ink-2, sharing --table-pad-x with the header so the columns line up, and taking their row height from --table-pad-y, which density halves from 14px to 8px.

## Best practices

### Do

- Bound the height from outside for stickyHeader: className and every other prop land on the <table>, not on the scrolling div around it, so only a constraining parent — a flex column with a height — gives that div something to stick within. A max-height on a plain wrapper does not, and the header simply travels with the page.
- Pass scope="row" on a row’s first cell — TH writes scope="col" and your props are spread after it, so the override lands; without it every row header claims to head a column and a cell traced back reaches the wrong label.
- Reset the other columns to sortDirection="none" when the sort moves: each header carries its own aria-sort and nothing coordinates them, so a table can end up announcing two columns as sorted at once.
- Give TD the same align as its TH — alignment is per cell, not inherited down the column, and end-aligned numbers under a start-aligned label is a column whose digits stop lining up with their own heading.

### Don’t

- aria-sort tells a reader how the table is ordered once they reach the header; it announces nothing at the moment the button is pressed. A table that re-orders under a screen reader has to say so somewhere the reader already is, or every row silently changes and nothing is said.
- Do not expect it to reflow on a phone: nothing stacks, the region scrolls sideways behind a hairline scrollbar, and a column past the fold is reachable only by a reader who works out that it scrolls. Eight columns at 375px wants a different presentation, not a smaller font.

## Accessibility

- caption is required: an unnamed table on a page with three tables is unnavigable.
- Column labels are <th scope="col">, so a cell can be traced back to its heading.
- A sortable header is a button INSIDE the th, not a click handler on the cell — a cell with an onClick is not focusable and not announced, so the sort would exist only for a mouse.
- aria-sort is set from sortDirection, which is the only way a screen reader learns the table is ordered at all.
- No zebra striping at any border setting: in a monochrome system a striped row is a second surface competing with the page ground.
- The scroll region is a containing block, so a visually-hidden label in a cell stays inside the table rather than escaping it and widening the page.

## Keyboard

- Tab — Reaches the scroll region, and each sortable column header.
- ← / → — Scrolls the table sideways once the region has focus.

## Table

A ruled data table. Wrapped in its own horizontally scrolling container, because a table is the one block that legitimately exceeds the measure — and a page that scrolls sideways as a whole is a layout bug, while a table that does is a table. That container is focusable, and it has to be. A scrollable region whose contents are not themselves focusable is unreachable by keyboard: there is no element to Tab to and therefore no way to press an arrow key at it, so the columns past the fold simply do not exist for anyone not using a mouse. It is also POSITIONED, which is not decoration. `sr-only` is `position: absolute`, so a visually-hidden label in a cell resolves against the nearest positioned ancestor — and with none between it and the document, it escapes the scroll container and every `overflow-hidden` around it, and widens the page by however far the table happens to be scrolled. No zebra striping at any border setting. In a monochrome system a striped row is a second surface competing with the page ground, and the hairline between rows is already enough to track a line across.

### Props

- `caption` (required) — `string`. Describes the table for a screen reader, which cannot see the heading above it. Rendered as a visually-hidden `<caption>` — required, because an unnamed table in a page with three tables is unnavigable.
- `showCaption` — `boolean` default `false`. Prints the caption instead of hiding it.
- `stickyHeader` — `boolean` default `false`. Pins the header row while the body scrolls. Needs a bounded height on the container — otherwise the page scrolls, not the table, and nothing sticks.
- `borders` — `TableBorders` default `'rows'`. Which rules to draw. See TableBorders.
- `density` — `'comfortable' | 'compact'` default `'comfortable'`. Tightens the row padding, for a table that is mostly numbers.

Also accepts: `TableHTMLAttributes<HTMLTableElement>`.

## THead

Header group. The rule under it is drawn by the table's border setting.

## TBody

## TR

## TH

A column label. Mono and uppercase, so it never reads as data. When sortable, the label becomes a `<button>` INSIDE the `<th>` rather than the `<th>` becoming clickable: a cell with a click handler is not focusable and not announced as a control, so the sort exists only for a mouse. Sorting is per column and opt-in. A table where every header is a button invites the reader to try sorting a column the data cannot be ordered by.

### Props

- `align` — `TableAlign` default `'start'`. Which edge the column's contents sit against. Numbers belong at `end`.
- `sortable` — `boolean` default `false`. Makes the label a button and shows the sort marker.
- `sortDirection` — `SortDirection` default `'none'`. Which way this column is sorted. Also set as `aria-sort`, which is the only way a screen reader learns a table is ordered at all — a caret drawn in the header tells it nothing.
- `onSort` — `() => void`.

Also accepts: `Omit<ThHTMLAttributes<HTMLTableCellElement>, 'align'>`.

## TD

A body cell. TOP-aligned, and that is a choice about which kind of table is the common one here: a cell holding a paragraph. Top is what lines the first lines of a row up with each other, and centring a two-word term against a four-line description puts the term in the middle of nothing. It is the wrong default for the other kind — a row of one-line values with a control in it. A 36px button next to 16px of text makes a 52px row, and every other cell then hangs at the top of it with twenty pixels of nothing underneath, which reads as a column that has slipped. Pass `className="align-middle"` on those rows; the data-table template does.

### Props

- `align` — `TableAlign` default `'start'`. Which edge the cell's contents sit against. Match the column's header.

Also accepts: `Omit<TdHTMLAttributes<HTMLTableCellElement>, 'align'>`.

## Example — a sortable column

```tsx
import { Badge, TBody, TD, TH, THead, TR, Table, type SortDirection } from '@misoto22/design'

<Table caption="Recent deploys">
  <THead>
    <TR>
      <TH>Commit</TH>
      <TH>Branch</TH>
      {/* Sorting is opt-in per column: a table where every header is a
          button invites sorting a column the data cannot be ordered by. */}
      <TH
        align="end"
        sortable
        sortDirection={sort}
        onSort={() => setSort(sort === 'ascending' ? 'descending' : 'ascending')}
      >
        Duration
      </TH>
      <TH align="center">State</TH>
    </TR>
  </THead>
  <TBody>
    {rows.map((row) => (
      <TR key={row.sha}>
        <TD className="font-mono text-xs">{row.sha}</TD>
        <TD>{row.branch}</TD>
        {/* Numbers belong at the end edge, so their digits line up. */}
        <TD align="end" className="tabular-nums">
          {format(row.seconds)}
        </TD>
        <TD align="center">
          <Badge tone={row.state === 'passed' ? 'success' : 'danger'}>{row.state}</Badge>
        </TD>
      </TR>
    ))}
  </TBody>
</Table>
```

## Example — borders

```tsx
import { TBody, TD, TH, THead, TR, Table, type TableBorders } from '@misoto22/design'

<div className="flex w-full flex-col gap-8">
  {OPTIONS.map((option) => (
    <div key={option.value} className="flex flex-col gap-2">
      <p className="m-0 eyebrow text-(--ink-3-aa)">
        {option.value} — {option.note}
      </p>
      <Table caption={`${option.value} example`} borders={option.value} density="compact">
        <THead>
          <TR>
            <TH>Region</TH>
            <TH align="end">Orders</TH>
            <TH align="end">Revenue</TH>
          </TR>
        </THead>
        <TBody>
          <TR>
            <TD>Australia</TD>
            <TD align="end" className="tabular-nums">1,204</TD>
            <TD align="end" className="tabular-nums">$48,210</TD>
          </TR>
          <TR>
            <TD>Japan</TD>
            <TD align="end" className="tabular-nums">862</TD>
            <TD align="end" className="tabular-nums">$31,940</TD>
          </TR>
        </TBody>
      </Table>
    </div>
  ))}
</div>
```

## Example — a sticky header

```tsx
import { TBody, TD, TH, THead, TR, Table } from '@misoto22/design'

<div className="flex h-72 w-full max-w-md flex-col overflow-hidden rounded-(--radius) border border-(--rule-2)">
  <Table caption="Every run on this branch" stickyHeader density="compact">
    <THead>
      <TR>
        <TH>Commit</TH>
        <TH>Branch</TH>
        <TH align="end">Duration</TH>
      </TR>
    </THead>
    <TBody>
      {RUNS.map((run) => (
        <TR key={run.sha}>
          <TD className="font-mono text-xs">{run.sha}</TD>
          <TD>{run.branch}</TD>
          <TD align="end" className="tabular-nums">
            {format(run.seconds)}
          </TD>
        </TR>
      ))}
    </TBody>
  </Table>
</div>
```

## Example — seven columns

```tsx
import { TBody, TD, TH, THead, TR, Table } from '@misoto22/design'

<Table caption="Fleet at a glance" showCaption density="compact" borders="bordered-grid">
  <THead>
    <TR>
      <TH>Host</TH>
      <TH>Region</TH>
      <TH>Version</TH>
      <TH align="end">CPU</TH>
      <TH align="end">Memory</TH>
      <TH align="end">p95</TH>
      <TH align="end">Uptime</TH>
    </TR>
  </THead>
  <TBody>
    {HOSTS.map((host) => (
      <TR key={host.host}>
        <TH scope="row">{host.host}</TH>
        <TD className="whitespace-nowrap">{host.region}</TD>
        <TD className="tabular-nums">{host.version}</TD>
        <TD align="end" className="tabular-nums">{host.cpu}</TD>
        <TD align="end" className="tabular-nums">{host.memory}</TD>
        <TD align="end" className="tabular-nums">{host.p95}</TD>
        <TD align="end" className="tabular-nums">{host.uptime}</TD>
      </TR>
    ))}
  </TBody>
</Table>
```

# Heatmap

A grid of values read by weight.

- Group: Data
- Import: `import { Heatmap } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/heatmap/
- Related: table, scatter-chart

## When to reach for it

A calendar of activity, a confusion matrix, an hour-by-weekday load. The one form a monochrome system renders better than a chromatic one.

## Anatomy

- **Figure caption** (required) — title in a figcaption, hidden from sight unless showTitle prints it above the grid with description under it. The same string is also the table’s own sr-only caption, so the grid is named on the way in and again from the table.
- **Column headers** (required) — One th scope="col" per entry in columns, in the order given, preceded by an sr-only corner cell reading “Row” so the header line has something standing over the row labels.
- **Row headers** (required) — One th scope="row" per entry in rows — end-aligned mono at --chart-axis, so every cell can be traced back to the pair of labels that names it.
- **Cell** (required) — A td whose background is a color-mix of --series-1 into --chart-surface at the value’s position in the domain. Continuous rather than stepped, because banding a ramp invents boundaries the data does not have, and 2px of border-spacing between cells is what makes two neighbouring weights countable.
- **Missing cell** — What a null draws — and what a row and column pair absent from cells draws too: a dashed --rule outline over the page, announcing “no data” instead of a number.
- **Printed value** — formatValue inside the cell. Visible with showValues, otherwise sr-only and un-hidden again under forced colours, where the wash that WAS the encoding has been remapped away.

## Best practices

### Do

- Switch scale to diverging the moment the values cross zero. sequential ramps on POSITION in the domain, so on a grid of changes the deepest fall is the palest cell and the biggest rise the darkest; diverging ramps on distance from the midpoint instead, which is the read a delta actually wants.
- Pin domain when one cell is an order of magnitude clear of the rest. The derived domain runs from zero — or the lowest value, when that is negative — to the highest, so a single 10,000 among readings of 5 to 40 puts every other cell inside the first half percent of the ramp, and forty distinct numbers render as one dark square on a blank grid.
- Spell a cell’s row and column exactly as they appear in rows and columns: cells are looked up by that pair, so an unmatched entry draws nothing at all. It no longer counts toward the derived domain either — a typo used to stretch the ramp with a value that appeared nowhere on the grid, pushing every drawn cell into the first fraction of it.
- Take the contrast trade knowingly when showValues goes on. The wash is capped at 35 percent of the ramp so one ink colour clears 4.5:1 on every cell — the ORDER of the cells survives untouched, the spread between them narrows, and the printed numbers become the thing carrying the detail.

### Don’t

- Do not let a pipeline fill gaps with zero before the grid sees them. A null is drawn as a dashed outline and announced as no data, and a zero is drawn as the palest cell on the ramp — so substituting one for the other turns an outage into a quiet hour, and nothing on the grid says which it was.
- Do not expect a reader to recover a figure from the wash. There is no legend and no step: weight orders the cells and never states one. The forced-colours fallback un-hides the numbers because the background has stopped existing there, which is a rescue for a remapped ground rather than a substitute for showValues on a grid whose exact figures matter.

## Accessibility

- A real <table>, not an SVG: the structure a screen reader walks is the structure the eye reads, and every cell announces its own row, column and value.
- Lightness is the only channel that is unambiguously ordered, which is why the standing advice everywhere else is “one hue, light to dark”. Here there is no hue left to get wrong.
- A null is drawn as a dashed outline, never as the palest cell — a missing reading is not a zero.
- Pin domain whenever two grids are compared: on independent domains they look alike and mean different things, which is the one failure a shared legend cannot fix.

## Heatmap

A grid of values read by weight — a calendar of activity, a confusion matrix, an hour-by-weekday load. The one form in the set that a monochrome system renders BETTER than a chromatic one. A heatmap needs a scale whose order the eye can read without consulting a legend, and lightness is the only channel that is unambiguously ordered — which is why "one hue, light to dark" is the standing advice everywhere else, and why the rainbow heatmap is a perennial mistake. Here there is no hue left to get wrong. It is built as a real `<table>` rather than as an SVG, so the structure a screen reader walks is the structure the eye reads: a header row, a header column, and a cell that announces its own value. Nothing else in the package can say that, and nothing else needs to — which is also why this one takes no rendering engine at all.

### Props

- `title` (required) — `string`. What the grid shows. Required, and it names the table.
- `showTitle` — `boolean` default `false`. Prints the title above the grid instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `columns` (required) — `string[]`. Column headers, in the order they should appear.
- `rows` (required) — `string[]`. Row headers, in the order they should appear.
- `cells` (required) — `HeatmapCell[]`.
- `scale` — `HeatmapScale` default `'sequential'`.
- `domain` — `[number, number]`. The domain, as `[min, max]`. Derived from the data when omitted. Pin it whenever two grids are meant to be compared: two heatmaps on independent domains look alike and mean different things, which is the one failure a shared legend cannot fix.
- `formatValue` — `(value: number, cell: HeatmapCell) => string` default `(value) => value.toLocaleString()`. Formats a value for the cell's announcement and its printed label. The cell is handed over as well, so a grid whose columns are not self-describing can name the reading rather than only the number. A calendar is the case that needs it: two days with the same count are two different readings, and the row and column headers a cell is announced with — "Mon" and a month name over a block of five weeks — do not say which day it was.
- `showValues` — `boolean` default `false`. Prints the number inside each cell. Only legible on a coarse grid.
- `className` — `string`.
- `empty` — `ChartEmptyProps`. What the grid shows when it has no rows or no columns to draw. A heatmap with no headers renders as a caption over nothing, which reads as a grid that failed to load rather than as one with nothing in it.

## Example — default

```tsx
import { Heatmap, type HeatmapCell } from '@misoto22/design/charts'

<Heatmap
  title="Commits by weekday and hour"
  showTitle
  description="Darker is busier"
  columns={HOURS}
  rows={DAYS}
  cells={cells}
/>
```

## Example — diverging

```tsx
import { Heatmap, type HeatmapCell } from '@misoto22/design/charts'

<Heatmap
  title="Weekly delta against target"
  showTitle
  description="Zero is the page; darker is further from target in either direction"
  columns={WEEKS}
  rows={TEAMS}
  cells={cells}
  scale="diverging"
  domain={[-40, 40]}
  showValues
/>
```

## Example — shared domain

```tsx
import { Heatmap, formatNumber, type HeatmapCell } from '@misoto22/design/charts'

<div className="grid w-full gap-8 lg:grid-cols-2">
  <Heatmap
    title="Median queue wait — Sydney"
    showTitle
    description="Darker is a longer wait"
    columns={SHIFTS}
    rows={DAYS}
    cells={sydney}
    domain={WAIT}
    formatValue={asDuration}
  />
  <Heatmap
    title="Median queue wait — Frankfurt"
    showTitle
    description="Same scale, so the two grids can be compared"
    columns={SHIFTS}
    rows={DAYS}
    cells={frankfurt}
    domain={WAIT}
    formatValue={asDuration}
  />
</div>
```

# CalendarHeatmap

A year of daily readings, as a week-by-week grid.

- Group: Data
- Import: `import { CalendarHeatmap } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/calendar-heatmap/
- Related: heatmap, calendar, sparkline

## When to reach for it

The readings are dated and the question is about the calendar. Heatmap is the grid underneath and knows nothing about dates; this is the arrangement everybody writes on top of it and nobody writes the same way twice.

## Anatomy

- **Grid** (required) — A Heatmap: one column per week, one row per weekday, drawn from the dates rather than from the order of the array. Every date is arithmetic on UTC midnights, so the same window renders identically in every timezone.
- **Window** (required) — from and to, or the earliest and latest date in values when they are left off. The grid runs back to the start of the first week and on to the end of the last, so a column is always a whole week.
- **Weekday rows** (required) — Seven row headers from weekdayLabels, always Sunday-first in the ARRAY and rotated onto the grid by weekStartsOn — so a Monday-first calendar and a translation are two separate decisions.
- **Month headers** — A name from monthLabels on the first column each month touches, blank on the rest. The blanks carry a run of zero-width spaces so the grid can still tell them apart, which is what a lookup by column NAME requires.
- **Gaps** — A day inside the window with no entry, and every day in the leading and trailing partial weeks: a dashed outline with an announced “no data”, never the palest cell on the ramp.
- **Cell reading** — What describe returns for that day, announced with the cell. Keyed by the cell rather than by the number, so two days with the same count are two different readings.

## Best practices

### Do

- Pass from and to whenever the window is a fact about the question rather than about the data. Derived from the values, a quiet January does not exist — the grid silently becomes a different window from the one beside it, and the two are then compared anyway.
- Write describe so it names the unit. The row and column a cell is announced with are a weekday and a month over a block of five weeks, so without it the reading a screen reader gets is a date and a bare number.
- Pin domain to compare two calendars. A quiet year and a busy one drawn on their own domains look identical, and the comparison the reader came for is not merely lost but inverted.

### Don’t

- Do not send a zero for a day nothing was recorded. Null is drawn as a gap and zero as the palest cell, and a page that draws them alike invites the reader to explain an outage that was a hole in collection.
- Do not hand it dates carrying a time or a zone. Every bound is parsed as a UTC midnight from YYYY-MM-DD, so a timestamp that is 23:00 somewhere lands on the day before it in the grid.
- Do not reach for it where the rows are not weekdays. An hour-by-weekday load or a confusion matrix is a Heatmap, and going through this one means inventing dates for cells that do not have any.

## Accessibility

- The grid is a real <table>, so a screen reader walks the same structure the eye reads: a header row, a header column, and a cell that announces its own reading.
- A day with no entry announces “no data” rather than a number, so a gap and a zero are different to a reader who cannot see the ramp.
- The reading is keyed by the cell, so the date is announced with the count — the row and column headers alone name a weekday and a month, not a day.

## CalendarHeatmap

A year of daily readings, as a week-by-week grid. `Heatmap` draws a grid of named rows and columns and knows nothing about dates; this is the arrangement everybody writes on top of it and nobody writes the same way twice — a column per week, a row per weekday, a month name on the first column it touches, and the days either side of the window left as gaps rather than as zeroes. The grid is built from the DATES rather than from the order of the array, so a gap in the data is a gap on the calendar. That is the failure this exists to prevent: given a bare list of counts, a missing Tuesday shifts every reading after it by one cell, and the result is a plausible picture of a year that did not happen. Every date is arithmetic on UTC midnights. A local-time calendar drawn in two timezones is two different calendars, and the disagreement is exactly one day wide — small enough to survive review and large enough to move a reading into the wrong week.

### Props

- `title` (required) — `string`. What the calendar shows. Required, and it names the table.
- `showTitle` — `boolean` default `false`. Prints the title above the grid instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `values` (required) — `CalendarHeatmapValue[]`. One entry per day that has a reading. Order does not matter; the grid is built from the dates. A day inside the window with no entry is drawn as a gap rather than as a zero, which is the distinction a calendar most often loses: "nothing happened" and "nothing was recorded" are different readings, and a page that draws them alike invites the reader to explain an outage that was a gap in collection.
- `from` — `string`. The first day the grid covers, as `YYYY-MM-DD`. Defaults to the earliest date in `values`. Give both ends whenever the window is a fact about the QUESTION rather than about the data — "the last year", "this quarter". Derived from the values, a quiet January simply does not exist, and the grid silently becomes a different window than the one beside it.
- `to` — `string`. The last day the grid covers, as `YYYY-MM-DD`. Defaults to the latest date in `values`.
- `describe` — `(value: number, date: string) => string`. What each cell announces, given its reading and its date. The default is the date and the number. Reach for this to name the unit — "3 commits on 2026-01-05" — because the row and column headers a cell is announced with are a weekday and a month over a block of five weeks, and neither says which day it was.
- `weekdayLabels` — `string[]` default `WEEKDAYS`. The seven row headers, Sunday first, whatever `weekStartsOn` is. Sunday first in the ARRAY and not on the grid: the labels are a translation and the first column is a calendar convention, and tying the two together would make a Monday-first German calendar a different array from a Monday-first English one.
- `monthLabels` — `string[]` default `MONTHS`. The twelve column headers, January first.
- `weekStartsOn` — `0 | 1 | 2 | 3 | 4 | 5 | 6` default `0`. Which weekday the grid's first row is. `0` is Sunday, `1` Monday.
- `domain` — `[number, number]`. The domain, as `[min, max]`. Derived from the readings when omitted. Pin it whenever two calendars are meant to be compared: a quiet year and a busy one drawn on their own domains look identical, and the comparison the reader came for is not merely lost but inverted.
- `className` — `string`.
- `empty` — `ChartEmptyProps`. What the grid shows when there is no window to draw.

## Example — default

```tsx
import { CalendarHeatmap, type CalendarHeatmapValue } from '@misoto22/design/charts'

<CalendarHeatmap
  title="Commits per day"
  showTitle
  description="Darker is busier"
  values={values}
  from={FROM}
  to="2026-07-03"
  describe={(value, date) => `${String(value)} commits on ${date}`}
/>
```

## Example — a monday first week

```tsx
import { CalendarHeatmap, type CalendarHeatmapValue } from '@misoto22/design/charts'

<CalendarHeatmap
  title="Beiträge pro Tag"
  showTitle
  values={values}
  from={FROM}
  to="2026-04-05"
  weekStartsOn={1}
  weekdayLabels={['So', 'Mo', 'Di', 'Mi', 'Do', 'Fr', 'Sa']}
  monthLabels={['Jan', 'Feb', 'Mär', 'Apr', 'Mai', 'Jun', 'Jul', 'Aug', 'Sep', 'Okt', 'Nov', 'Dez']}
  domain={[0, 20]}
  describe={(value, date) => `${String(value)} Beiträge am ${date}`}
/>
```

# Sparkline

A run of numbers at the size of a word.

- Group: Data
- Import: `import { Sparkline } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/sparkline/
- Related: line-chart, table

## When to reach for it

In a table cell, beside a figure, at the end of a row. When the trend needs reading precisely it wants a LineChart and its own space.

## Anatomy

- **Inline row** (required) — An inline-flex span, full width with 8px of gap, so the run sits in a table cell or beside a figure without breaking the line it is on.
- **Plot** (required) — One svg role="img" over a 0–100 by 0–100 viewBox with preserveAspectRatio="none", so it stretches to whatever width the container gives it. height, 28px by default, is the only fixed dimension.
- **Mark** (required) — The path, its area fill, or the bars — variant picks one. The stroke is drawn with non-scaling-stroke, which is what keeps the line the same weight in a narrow cell and a wide one after the box has been stretched to fit.
- **Last point** — A 2px dot on the final reading, from showLast, on the line and area variants. The bars variant carries the end of the run in its own last bar and draws no dot.
- **Printed value** — value, in mono tabular figures after the plot. It is also what the accessible name says after the label, and it is the only figure this component ever prints.
- **Too-short state** — What renders in place of the whole plot when fewer than two finite numbers survive: the label and “not enough data”, as one line of mono meta text.

## Best practices

### Do

- Pass value whenever a figure matters. The plot has no axis and no scale, so it carries shape and nothing else, and value is both the one number printed and the reading appended to the accessible name. Left out, that name falls back to the last point through toLocaleString — the raw number, without the unit, the currency or the rounding the row beside it uses.
- Pin domain across any two that will be read against each other. Each run is normalised into the same fixed box from its OWN min and max, so the highest point always touches the top edge and the lowest always the floor: a series moving between 4 and 6 and a series moving between 400 and 900 draw the same silhouette, and the difference between them is drawn nowhere.
- Downsample a long run before handing it over. The x step is 100 divided by one less than the number of points, spread across whatever width the cell has, so four hundred readings in a 200px cell land half a pixel apart and the path fills in as a band.
- Read a flat line through the middle as “unchanged”, not as “at its floor”. A run whose min equals its max has a scale with no width, so no position on it is truer than another and every point sits at the centre — the same answer Heatmap and BulletChart give a zero span, and the one that keeps “unchanged” and “pinned at its worst” apart in a column of them.

### Don’t

- Do not assume something chart-shaped always renders. Non-finite entries are filtered out first, and anything left under two points returns a line of text instead of an SVG, so the new account’s row is a sentence where every other row in the column is a chart.

## Accessibility

- label is required and is the whole accessible name: a sparkline has no axes and no legend, so nothing else describes it.
- Axis-less by design. Every piece of chrome that would let it answer “what value exactly” also makes it too big to sit inline, which was the only reason to reach for it.
- Pin domain for a column of them: on independent domains every row peaks and troughs identically, which is how a table of sparklines becomes actively misleading.
- One path, no rendering engine — so a hundred of them in a table cost nothing.

## Sparkline

A run of numbers at the size of a word — in a table cell, beside a figure, at the end of a row. Deliberately axis-less, gridless and label-less: a sparkline answers "what shape has this been", and every piece of chrome that would make it answer "what value exactly" also makes it too big to sit inline, which was the only reason to reach for it. When the exact value matters, print the number beside it — `value` does — and when the trend needs reading precisely, it wants a `<LineChart>` and its own space. No rendering engine: it is one `<path>` over a normalised viewBox, so it costs nothing to put a hundred of them in a table.

### Props

- `data` (required) — `number[]`. The numbers, in order. Anything shorter than two points draws nothing.
- `label` (required) — `string`. What the run is, in a sentence. Required, and it is the whole accessible name: a sparkline has no axes and no legend, so nothing else describes it.
- `variant` — `SparklineVariant` default `'line'`.
- `height` — `number` default `28`. Height in pixels. The width comes from the container.
- `domain` — `[number, number]`. The domain, as `[min, max]`. Derived from the data when omitted. Pin it whenever a column of sparklines is meant to be compared: on independent domains every row peaks and troughs identically, which is the one way a table of sparklines can be actively misleading.
- `showLast` — `boolean` default `true`. Marks the last point, which is usually the one being asked about.
- `value` — `ReactNode`. The value announced alongside the label — the current reading, formatted. Falls back to the last number.
- `className` — `string`.

## Example — variants

```tsx
import { Sparkline, type SparklineVariant } from '@misoto22/design/charts'

<div className="flex w-full max-w-sm flex-col gap-5">
  {VARIANTS.map((variant) => (
    <div key={variant} className="flex items-center gap-4">
      <span className="w-12 shrink-0 mono-meta text-(--ink-3-aa)">{variant}</span>
      <Sparkline label={`Weekly signups, ${variant}`} data={data} variant={variant} value="61" />
    </div>
  ))}
</div>
```

## Example — in a table

```tsx
import { TBody, TD, TH, THead, TR, Table } from '@misoto22/design'
import { Sparkline } from '@misoto22/design/charts'

<Table caption="Visitors by channel, last seven weeks">
  <THead>
    <TR>
      <TH>Channel</TH>
      <TH>Trend</TH>
      <TH align="end">This week</TH>
    </TR>
  </THead>
  <TBody>
    {ROWS.map((row) => (
      <TR key={row.channel}>
        <TD>{row.channel}</TD>
        <TD>
          <Sparkline
            label={`${row.channel}, last seven weeks`}
            data={row.trend}
            domain={DOMAIN}
            height={22}
          />
        </TD>
        <TD align="end" className="font-mono tabular-nums">
          {row.now}
        </TD>
      </TR>
    ))}
  </TBody>
</Table>
```

## Example — not enough data

```tsx
import { Sparkline } from '@misoto22/design/charts'

<div className="flex w-full max-w-sm flex-col gap-5">
  {ROWS.map((row) => (
    <div key={row.project} className="flex items-center gap-4">
      <span className="w-16 shrink-0 mono-meta text-(--ink-3-aa)">{row.project}</span>
      <Sparkline label={`${row.project}, last seven days`} data={row.trend} />
    </div>
  ))}
</div>
```

# BarList

A ranked list, with the bar behind the name rather than beside it.

- Group: Data
- Import: `import { BarList } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/bar-list/
- Related: bar-chart, table

## When to reach for it

Top referrers, slowest endpoints, biggest accounts. A horizontal BarChart spends a third of its width on an axis repeating labels the rows could simply contain.

## Anatomy

- **Caption** (required) — label, as the table’s real caption — sr-only unless showLabel prints it as an eyebrow above the rows. It is what names the list for a screen reader.
- **Header row** (required) — An sr-only thead of two th scope="col" cells, Name and Value, so both columns are named even though the list never shows a header.
- **Name cell** (required) — A th scope="row" holding the row’s name truncated to one line, with item.icon before it as aria-hidden decoration and item.href turning the name itself into the link.
- **Bar** (required) — Not an element: a linear-gradient on the name cell’s inner span, a hard stop at the row’s share of the ceiling. Drawn as a sibling div it would be one more empty thing in the accessibility tree saying nothing.
- **Value cell** (required) — A td at the end edge in mono tabular figures at --ink-2, written by formatValue — the same compact default the axes use unless the call site replaces it.
- **Other row** — What limit adds: one final row named Other carrying the summed tail, so the rows shown still account for the whole they were cut from.
- **Empty state** — ChartEmpty under the label when there is nothing to rank. A caption over an empty tbody is a list that failed to load as far as the reader can tell, and reloading does not change it.

## Best practices

### Do

- Pin max when rows arrive over time. The ceiling is the largest row currently shown, so one new leader rescales every bar under it — a track that was two thirds full yesterday is a quarter full today with exactly the same number in it, and the movement the reader sees happened to a different row.
- Reach for limit rather than slicing items at the call site. The tail is summed into the Other row instead of being dropped, so the five rows shown still add up to the whole; a top five cut by hand discards the other forty silently, and nothing in the list says so.
- Keep names short enough to survive the truncation. The name is a single truncated line sharing its width with the value column, so two endpoints that differ only past the fortieth character render as the same row with the same ellipsis.
- Pass sort={false} when the order is the point — a funnel, a set of steps, a fixed set of regions. sort defaults to true and orders descending, which turns a sequence into a ranking without saying that it did.

### Don’t

- The bar is the row over the largest row, never a share of a total: the leading row always fills its track, so five rows that make up 3 percent of traffic look exactly like five that make up all of it. Where the whole matters, the caption is where it goes.
- Do not mix number shapes down the value column. It is end-aligned mono with tabular figures, which lines digits up only while the strings are the same shape — and the default formatter switches to the compact form at 10,000, so a list spanning that threshold puts 9,400 under 1.2M and there is nothing left to compare down.
- Two rows cannot share a name. It is the row’s label and its React key at once, so a list built from a query that can repeat a label renders duplicate keys, which React warns about and reconciles wrongly the moment the list updates.

## Accessibility

- A real <table> with two columns and one row per thing, because that is what a ranked list is. The bar is a background on the name cell, so it is never a second element a screen reader has to walk past.
- limit sums the tail into an “Other” row rather than dropping it — a top five that silently discards the other forty misstates the whole, and the reader has no way to tell.
- Pin max to compare two lists side by side: on independent scales the leading row of each fills its track, and two very different numbers look identical.

## BarList

A ranked list, with the bar behind the name rather than beside it. The answer to "top referrers", "slowest endpoints", "biggest accounts" — and a better one than a horizontal bar chart, which spends a third of its width on a category axis repeating labels the rows could simply contain. Reading a name off a y-axis and matching it to a bar is two steps; reading it off the bar is none. It is a `<table>`, because that is what it is: two columns, a header, and one row per thing. The bar is a background on the name cell, so it never becomes a second element a screen reader has to walk past. Reach for `<BarChart orientation="horizontal">` instead when the categories are few and fixed and the axis is doing real work — a scale a reader needs to read values off, rather than a ranking they need to skim.

### Props

- `label` (required) — `string`. What the list ranks. Required: it names the table for a screen reader.
- `showLabel` — `boolean` default `false`. Prints the label above the list instead of hiding it from sight.
- `items` (required) — `BarListItem[]`.
- `limit` — `number`. Keeps the top N and folds the rest into one "Other" row.
- `formatValue` — `(value: number) => string` default `defaultTick`. Formats each value. Defaults to the same compact form the axes use.
- `max` — `number`. The scale's ceiling. Derived from the largest row when omitted. Pin it to compare two lists side by side — on independent scales the leading row of each fills its track, and two very different numbers look identical.
- `sort` — `boolean` default `true`. Sorts descending before rendering.
- `className` — `string`.
- `empty` — `ChartEmptyProps`. What the list shows when it has nothing to rank. A caption over an empty `<tbody>` is a list that failed to load as far as the reader can tell, and the reader's next move is to reload the page.

## Example — default

```tsx
'use client'

import { BarList } from '@misoto22/design/charts'

const referrers = [
  { name: 'google.com', value: 42_100 },
  { name: 'github.com', value: 18_800 },
  { name: 'news.ycombinator.com', value: 9_400 },
  { name: 'x.com', value: 6_120 },
  { name: 'reddit.com', value: 3_280 },
  { name: 'lobste.rs', value: 1_940 },
  { name: 'bsky.app', value: 1_100 },
  { name: 'linkedin.com', value: 640 },
]

export function Example() {
  return <BarList label="Top referrers" showLabel items={referrers} />
}
```

## Example — limit

```tsx
'use client'

import { BarList } from '@misoto22/design/charts'

const referrers = [
  { name: 'google.com', value: 42_100, href: 'https://google.com' },
  { name: 'github.com', value: 18_800, href: 'https://github.com' },
  { name: 'news.ycombinator.com', value: 9_400, href: 'https://news.ycombinator.com' },
  { name: 'x.com', value: 6_120 },
  { name: 'reddit.com', value: 3_280 },
  { name: 'lobste.rs', value: 1_940 },
  { name: 'bsky.app', value: 1_100 },
  { name: 'linkedin.com', value: 640 },
]

export function Example() {
  return <BarList label="Top referrers" showLabel items={referrers} limit={3} />
}
```

## Example — a shared ceiling

```tsx
import { BarList, formatNumber } from '@misoto22/design/charts'

<div className="grid w-full gap-8 sm:grid-cols-2">
  <BarList
    label="New ARR this quarter"
    showLabel
    items={thisQuarter}
    max={CEILING}
    formatValue={money}
  />
  <BarList
    label="New ARR last quarter"
    showLabel
    items={lastQuarter}
    max={CEILING}
    formatValue={money}
  />
</div>
```

# Metric

One reading, on a plate: a label, a figure, and what qualifies it.

- Group: Data
- Import: `import { Metric } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/metric/
- Related: big-number, status-dot, sparkline

## When to reach for it

Four across on a console. BigNumber is the same idea at headline scale for the ONE figure a view is about, and needs the charts entry; this is the tile, and needs nothing.

## Anatomy

- **Plate** (required) — An <article> at --radius with a hairline round it and 12px of padding, or whatever asChild is handed. It has no heading and no landmark: a row of four is a row of readings, not four sections.
- **Label** (required) — label as an eyebrow at --ink-3-aa. Nothing binds it to the figure programmatically, so document order is the whole association.
- **Tone dot** — A StatusDot beside the label when tone is set, un-pulsed and aria-hidden. Decoration by construction, which is why whatever it means has to be in detail as well.
- **Figure** (required) — value in the mono face at --fs-item with tabular figures, printed exactly as handed over — no unit, currency or locale is guessed. Tabular because four tiles in a row are read down the column as much as along it.
- **Detail** — detail under the figure at --ink-2 in the small step. One line: what makes the number a reading rather than a count.
- **Aside** — aside, last, unwrapped and unstyled: a Sparkline, a denominator, a caveat. Unlike BigNumber’s note slot it carries no margin of its own, so a tight tile stays tight.

## Best practices

### Do

- Put whatever the tone means into detail as well. The dot is aria-hidden by construction, so a tile whose only account of a failure is that it is red says nothing at all to a screen reader, and nothing in greyscale.
- Format value at the call site. It is printed exactly as handed over, which is what lets a locale, a currency and a unit be decided once by the application rather than guessed four times by four tiles.
- Give the slotted child no children of its own under asChild. The label and the figure are injected into it, so `<Link href="/jobs" />` is the whole call — a child with content of its own gets that content and the tile both.

### Don’t

- Do not reach for this where there is one figure and a change to report. BigNumber has a delta, a direction stated by the call site and an announced verdict; a tone dot is not any of those, and re-implementing them in aside gets the announcement wrong.
- Do not write a sentence into detail under asChild. The whole tile is inside one link, so the link’s accessible name is every word in it read in order, and a clause added there is a clause read out every time the link is reached.
- Do not put a heading inside one. The plate is an <article> with no name, so a heading in it opens a section a screen reader will list — four tiles then read as four sections of the page rather than as one row of figures.

## Accessibility

- The tone dot is aria-hidden without exception, so colour is never the only carrier — the words in detail are.
- value is taken already formatted. The component does not guess a unit, a currency or a locale.
- Under asChild the tile becomes the caller’s element, so the link or button is the whole plate rather than a target inside it.

## Metric

One reading, on a plate: a label, a figure, and what qualifies it. Distinct from `BigNumber`, which is the same idea at headline scale for the ONE figure a view is about, and which needs the charts entry. This is the tile that appears four across on a console: smaller, monospaced rather than editorial, and carrying two things `BigNumber` has nowhere for — a status tone, and a free slot under the number that is not a delta. Those two are the whole reason it exists; a dashboard whose tiles have to be a `<div>` because the delta does not apply is a dashboard with two tile designs in it. The figure is monospace and tabular by construction, because four of these in a row are read down the column as much as along it, and proportional digits put the same magnitude at two different widths.

### Props

- `label` (required) — `ReactNode`. What the figure counts.
- `value` (required) — `ReactNode`. The figure, already formatted — this does not guess a unit or a locale.
- `detail` — `ReactNode`. One line of context. A figure without it is a number, not a reading.
- `tone` — `StatusTone`. How the reading stands. Drawn as a dot beside the label, and only ever a SECOND carrier: the dot is `aria-hidden`, so whatever the tone means has to be in `detail` as well or it reaches nobody who cannot see it.
- `aside` — `ReactNode`. A sparkline, a denominator, a caveat. Sits under the figure.
- `asChild` — `boolean` default `false`. Render `children` as the tile instead of the `<article>`, keeping these styles — how a linkable tile gets a router's own `Link` without this package importing one. The slotted element must take no children of its own: the label, the figure and everything under them are injected INTO it, which is the point. A whole tile inside one link also means the link's accessible name is every word in it, read in order — "Rows, 63,851, newest yesterday" — so keep `detail` short enough to be heard as part of a link.
- `children` — `ReactNode`. The element the tile becomes under `asChild`. Ignored without it.
- `className` — `string`.

Also accepts: `HTMLAttributes<HTMLElement>`.

## Example — default

```tsx
import { Metric } from '@misoto22/design'

<div className="grid w-full gap-3 sm:grid-cols-2 lg:grid-cols-4">
  <Metric label="Rows" value="63,851" detail="newest yesterday" tone="success" />
  <Metric label="Sync" value="0" detail="failing since Tuesday" tone="danger" />
  <Metric label="Queue" value="12" detail="3 waiting on approval" tone="warning" />
  <Metric label="Accounts" value="7" detail="all reconciled" />
</div>
```

## Example — a tile that is a link

```tsx
import { Metric } from '@misoto22/design'

<div className="grid w-full gap-3 sm:grid-cols-2">
  <Metric asChild label="Jobs" value="12" detail="3 waiting">
    <a href="#/jobs" />
  </Metric>
  <Metric asChild label="Approvals" value="4" detail="oldest 2 days">
    <a href="#/approvals" />
  </Metric>
</div>
```

# BigNumber

One number, at the size of a headline.

- Group: Data
- Import: `import { BigNumber } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/big-number/
- Related: sparkline, figure-band

## When to reach for it

There is exactly one figure to report. A plot of a single value is a plot whose shape carries nothing, and the reader has to decode an axis to recover a number that could simply have been printed.

## Anatomy

- **Label** (required) — What the number counts, as an eyebrow at --ink-3-aa above it. Nothing binds it to the value programmatically — no aria-labelledby, no role — so document order is the whole association.
- **Value** (required) — The number itself, in the editorial face at --fs-lead with tabular figures. Rendered exactly as handed over: no unit, currency or locale is guessed on its behalf.
- **Delta** — The line under the number, from delta: the change through format — a signed percentage unless replaced — and delta.label at --ink-3-aa saying what it is a change from.
- **Direction mark** — Inside the delta: an aria-hidden arrow, up, down or flat at zero, and the status tint, --ok or --danger, or --ink-2 while nothing has been judged. Two carriers, so the reading survives greyscale and forced colours.
- **Verdict** — The sr-only words beside the arrow — up or down, then better or worse once intent has been set. It is what a screen reader gets in place of the tint.
- **Note slot** — children, under the number with a margin: where a Sparkline, a denominator or a caveat goes.

## Best practices

### Do

- Give the figure something to be judged against. On its own a number cannot be read — 48,210 is neither good nor bad until it is beside last month — and this component carries exactly two places for that: delta for one comparison, children for the Sparkline or the denominator under it.
- Pass delta.value as a ratio. The default formatter multiplies by a hundred and prefixes the sign, so 0.124 prints as +12.4% and 12.4 prints as +1240%. A change already expressed in points needs its own format handed over with it.
- Set intent on any delta meant to be coloured. It defaults to neutral, which renders the change at --ink-2 and says only which way it moved — correct for a figure nobody has judged, and rarely what the author of a revenue card thought they had written.
- Let value be null when there is no reading. It prints an em dash at --ink-3-aa with an sr-only “No data” behind it, which is a number nobody has; a blank line under a label is a broken layout as far as the reader can tell. emptyValue changes what the dash is.

### Don’t

- Do not expect a delta of exactly zero to carry the intent’s verdict. There is no direction for an intent to judge, so the tone, the arrow and the announced words all say “no change” and stop — a zero under up-is-good used to be announced as “no change, worse” while the page showed no judgement at all.
- Do not separate the label from the number. The value is text in a span rather than a labelled element, and the label is a sibling read before it, so a layout that moves the figure into its own column — or reuses one label over two figures — hands a screen reader a bare number with nothing naming it.

## Accessibility

- The delta’s direction is stated by the call site through intent, never inferred from the sign: “errors down 12%” is good news and “revenue down 12%” is not, and no component can tell which it is holding.
- The arrow and the words carry the direction; the status tint is the third signal, never the only one — so the reading survives greyscale, forced colours and colour blindness.
- value is taken already formatted. The component does not guess a unit, a currency or a locale.

## BigNumber

One number, at the size of a headline. The form most dashboards need most often and most chart libraries do not ship, on the grounds that it is not a chart. It is the right answer whenever there is exactly one figure to report: a plot of a single value is a plot whose shape carries nothing, and the reader has to decode an axis to recover a number that could simply have been printed. The delta is where this earns its place over a `<p>`. Direction is stated by the CALL SITE (`intent`), never inferred: "errors down 12%" is good news and "revenue down 12%" is not, and no component can tell which it is holding. Where the direction is known, the arrow and the word carry it — the status colour is the third signal, never the only one.

### Props

- `label` (required) — `ReactNode`. What the number counts.
- `value` (required) — `ReactNode`. The number, already formatted — this component does not guess a unit. `null` and `undefined` are the empty state rather than a blank space: a headline with nothing under it reads as a figure that failed to load, and the reader's next move is to reload a page that will look the same.
- `emptyValue` — `ReactNode` default `'—'`. What stands in for the number when there is none.
- `delta` — `BigNumberDelta`.
- `children` — `ReactNode`. A sparkline, a note, a caveat. Sits under the number.
- `className` — `string`.

## Example — default

```tsx
import { BigNumber } from '@misoto22/design/charts'

<div className="grid w-full gap-10 sm:grid-cols-3">
  <BigNumber
    label="Monthly revenue"
    value="$48,210"
    delta={{ value: 0.124, label: 'vs last month', intent: 'up-is-good' }}
  />
  <BigNumber
    label="Error rate"
    value="2.4%"
    delta={{ value: 0.08, label: 'vs last week', intent: 'down-is-good' }}
  />
  <BigNumber
    label="Active projects"
    value="1,204"
    delta={{ value: 0, label: 'vs last month', intent: 'neutral' }}
  />
</div>
```

## Example — with sparkline

```tsx
import { Card, CardBody } from '@misoto22/design'
import { BigNumber, Sparkline } from '@misoto22/design/charts'

<div className="grid w-full gap-6 sm:grid-cols-2">
  <Card>
    <CardBody>
      <BigNumber
        label="Monthly revenue"
        value="$48,210"
        delta={{ value: 0.124, label: 'vs last month', intent: 'up-is-good' }}
      >
        <Sparkline label="Revenue, last eight months" data={trend} variant="area" />
      </BigNumber>
    </CardBody>
  </Card>

  <Card>
    <CardBody>
      <BigNumber
        label="p95 latency"
        value="1.34s"
        delta={{ value: -0.29, label: 'vs last week', intent: 'down-is-good' }}
      >
        <Sparkline
          label="p95 latency, last eight weeks"
          data={[2.1, 2.0, 1.9, 2.2, 1.8, 1.6, 1.5, 1.34]}
          variant="bars"
        />
      </BigNumber>
    </CardBody>
  </Card>
</div>
```

## Example — points and a missing value

```tsx
import { BigNumber } from '@misoto22/design/charts'

<div className="grid w-full gap-10 sm:grid-cols-2">
  <BigNumber
    label="Checkout conversion"
    value="4.8%"
    delta={{ value: 0.6, label: 'vs last quarter', intent: 'up-is-good', format: points }}
  />
  <BigNumber label="Refund rate" value="—" />
</div>
```

# BulletChart

A measure, its target, and the bands that say whether it is any good.

- Group: Data
- Import: `import { BulletChart } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/bullet-chart/
- Related: bar-list, big-number

## When to reach for it

A status page of ten tracked numbers. Stephen Few designed it to replace the dashboard gauge, which spends a whole card saying one number badly.

## Anatomy

- **Figure caption** (required) — title on the shared chart figure, referenced by aria-labelledby rather than left to be inferred from the figcaption, and hidden from sight unless showTitle prints it with description beneath.
- **Measure line** (required) — The row above each track: the measure’s name with its optional detail at the start, the formatted value at the end, and the target after a slash where there is one. This line is the reading a screen reader gets, because the graphic under it is not in the accessibility tree at all.
- **Track** (required) — The 24px aria-hidden box holding the bands, the bar and the target rule, laid out with inline-axis offsets rather than in SVG user space — which is what makes the whole chart mirror correctly in a right-to-left document.
- **Bands** — The qualitative ground, built from ranges as ascending upper bounds: heaviest at the low end of the scale and lightening as it rises, so the solid bar stands out most where performance is best.
- **Measure bar** (required) — The value, solid --series-1 at a third of the track’s height, running from the start of the scale. The one mark here that is a measurement rather than a judgement, and the only one drawn at full weight.
- **Target rule** — target, as a 2px rule of --ink straight across the bar rather than a second bar beside it — so which number was achieved and which was asked for is a glance rather than a comparison.

## Best practices

### Do

- Keep every range bound inside the domain. Bounds at or outside the two ends have no boundary to draw and are dropped before the bands are built, so ranges of 60 and 80 on a domain of 0 to 50 draws one flat band — the row LOOKS evaluated and is not. They stay in the table’s range-bounds cell, which is the only place the mismatch is visible.
- Hold to five bands. The weights are spread evenly from the full --chart-fill down to three tenths of it across however many bands are passed, so a sixth and a seventh boundary only slice that same span thinner and the ground stops having edges a reader can read a threshold off.
- Leave hideDataTable off unless the page prints the measures itself. The whole graphic is aria-hidden — bands, bar and target alike — so the generated sr-only table of value, target and range bounds is the only account of the chart a screen reader ever reaches.

### Don’t

- A value past the end of the scale is clamped, not overflowed: 130 on a domain of 0 to 100 fills the track exactly as 100 does. A notch at the end of the track says it happened and the figure printed above says by how much — but the track itself cannot, so pin domain wide enough for the overshoot you expect rather than reading the row that blew through its target as one that merely finished.
- Do not put a range bound on the target. Both are placed by the same scale, so the rule lands exactly on a band edge and the one mark that says what was ASKED for disappears into the ground it was meant to be read against.

## Accessibility

- Plain HTML with logical properties — no rendering engine, server-renderable, and correct in a right-to-left document. Usable with recharts absent.
- The bands are a JUDGEMENT drawn in the same ink as the measurement, so the page has to say where they came from. Ranges that encode nothing but thirds make the chart look evaluated when it is not.
- It shows one instant and no change over time; target is the only comparison it carries. “How did we get here” wants a LineChart.
- Shared bands only mean something when the measures share a scale — a latency beside a conversion rate needs ranges and domain per measure.

## BulletChart

A measure, its target, and the bands that say whether the number is any good — one dense row per thing being tracked. Stephen Few designed this to replace the dashboard gauge, and the argument has held: a speedometer spends a whole card saying one number badly, where a bullet graph says the same number, its target, and the qualitative context around it in the height of a line of text. Ten of them stack into a status page a reader can scan in one pass. What it will not do is show change over time. A bullet graph is one instant, and `target` is the only comparison it carries; when the question is "how did we get here" it wants a `<LineChart>`, and when several measures have to be compared against each OTHER rather than each against its own target, a `<BarList>` ranks them and this does not. **The bands are the part to be careful with.** They are a judgement — someone decided that 80 is "good" — drawn in the same ink as the measurement, and a reader has no way to tell an agreed threshold from a number somebody typed. They also compress: a value near the top of the scale sits in the same band whether it cleared the boundary by a point or by thirty. The band answers "is this acceptable", never "by how much". No rendering engine, deliberately — this is the one chart in the set with nothing to compute. Each row is a single linear scale with no axis, no ticks and no shared plot area, so it is laid out as HTML: the bands and the bar are inline-axis offsets, which means the whole chart mirrors correctly in a right-to-left document, where an SVG drawn in user space would not.

### Props

- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
- `showTitle` — `boolean`. Prints the title above the rows instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `data` (required) — `BulletMeasure[]`. One entry per measure. Order is the reading order; it is not sorted.
- `ranges` — `number[]`. The bands every measure falls back to, as ascending upper bounds. Shared bands only mean something when the measures share a scale. Where they do not — a latency beside a conversion rate — put `ranges` and `domain` on each measure instead.
- `domain` — `[number, number]`. The scale every measure falls back to, as `[min, max]`.
- `formatValue` — `(value: number) => string` default `defaultTick`. Formats every number the chart prints.
- `showScale` — `boolean` default `false`. Prints the scale's two ends under each track.
- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
- `empty` — `ChartEmptyProps`. What the chart shows when it has nothing to draw.

## Example — default

```tsx
import { BulletChart } from '@misoto22/design/charts'

<BulletChart
  title="Quarterly targets"
  showTitle
  description="Bar is the measure, rule is the target"
  data={data}
  ranges={[50, 80]}
  domain={[0, 100]}
/>
```

## Example — per measure scales

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'
import { BulletChart, formatNumber } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-4">
  <ToggleGroup
    type="single"
    value={showScale ? 'shown' : 'hidden'}
    onValueChange={(next) => next && setShowScale(next === 'shown')}
    aria-label="Scale labels"
  >
    <ToggleGroupItem value="hidden">no scale</ToggleGroupItem>
    <ToggleGroupItem value="shown">scale</ToggleGroupItem>
  </ToggleGroup>

  <BulletChart
    title="Platform health"
    data={data}
    showScale={showScale}
    formatValue={formatNumber({ style: 'plain' })}
  />
</div>
```

## Example — empty

```tsx
import { Button } from '@misoto22/design'
import { BulletChart } from '@misoto22/design/charts'

<BulletChart
  title="Quarterly targets"
  showTitle
  description="Bar is the measure, rule is the target"
  data={[]}
  empty={{
    title: 'No targets set for this quarter',
    description: 'Targets carry over when a quarter opens. This one has none yet.',
    action: <Button variant="secondary">Set targets</Button>,
  }}
/>
```

# AreaChart

A filled series over a continuous axis, where the area means something.

- Group: Charts
- Import: `import { AreaChart } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/area-chart/
- Related: line-chart, bar-chart, composed-chart

## When to reach for it

Reading one magnitude over time. Comparing several series against each other is a LineChart — four translucent fills stacked on each other answer neither question.

## Anatomy

- **Figure frame** (required) — The <figure> ChartFigure draws, named through aria-labelledby rather than left to the figcaption, because deriving a name from a <figcaption> resolves in only some screen readers. The caption holds title and description together and is sr-only until showTitle is set, so a caveat written into description is announced and never printed.
- **Plot** (required) — ChartContainer: a 16:9 box floored at 13rem and capped at 26rem, and the one place Recharts’ hard-coded #ccc axis and grid strokes are re-pointed at --chart-grid and --chart-axis.
- **Areas** (required) — <AreaChart.Area>, one per series. Each generates its own id and scopes its gradient, its texture pattern and its reveal mask under it, so six variants share a plot without one overwriting another’s definitions.
- **Brush strip** — <AreaChart.Brush>, rendered in the container’s footer rather than inside the SVG. Both handles are role="slider" with aria-valuetext naming the row they sit on, so the window is reachable by arrow key.
- **Toolbar** — <AreaChart.Toolbar>, a role="group" row of at most five 44px icon buttons above the plot. Composing it also switches the plot’s own wheel, drag and keyboard zoom on, and the two drive one window rather than two.
- **Hidden data table** — An sr-only <table> built from the FULL data rather than the brushed window, so a reader on the table is never shown less than the CSV export holds. hideDataTable removes it, and zero rows render nothing.

## Best practices

### Do

- Stack only quantities that genuinely add up. Under stackType="stacked" a band’s HEIGHT is its own value but its POSITION is the sum of everything under it, so stacking four independent rates draws a running total nobody measured.
- Reach for stackType="expanded" when the reading is share rather than volume: it sets Recharts’ expand offset and <AreaChart.YAxis> swaps in percentTick on its own, so the axis reads 0% to 100% without a formatter at the call site. A tickFormatter of your own still wins — the axis defers to it rather than dropping it, which it used to do without a word.
- Vary variant before the ramp on a two-area chart. The six fills are the primary encoding in the monochrome default, and under forced colours every --series-* token resolves to CanvasText — at which point the texture is the only thing left separating two areas.
- Pass xDataKey. It is the rowKey of the hidden table, and without it the table renders no row-header column at all: a screen reader gets a column of numbers with no month beside them.

### Don’t

- Four translucent fills over each other is this form’s failure mode — the third area is read through two layers of --chart-fill and its own height stops being recoverable. Several series compared against each other is a LineChart, where nothing occludes anything.
- connectNulls defaults to false for a reason: turned on, a gap in the data is drawn as a straight segment indistinguishable from a measured flat period. Set it only where the gap is a rendering artefact rather than a missing observation.
- A single row draws nothing. One point has no segment to fill, dot is false unless <AreaChart.Dot> is composed, and the empty state does not fire because there IS a row — so the axes render over a blank plot.

## Accessibility

- title is required and becomes the figure’s accessible name, printed or not.
- The rows are rendered again as a visually hidden table, so the numbers are reachable rather than only drawn. hideDataTable opts out when the page already prints them.
- Six fill variants exist because in the monochrome default TEXTURE is the primary carrier of identity and the grey ramp is the second — which is also what keeps two series apart in greyscale print and under forced colours.
- The intro reveal is a per-frame SVG mask and is dropped entirely under prefers-reduced-motion, as is the crawling dash.

## Keyboard

- Tab — Reaches the plot, which Recharts’ accessibility layer makes navigable.
- ← / → — Moves the cursor between points, announcing each.

## AreaChart

A filled series over a category axis — the shape for a magnitude that is continuous, where the area under the line means something. Composed rather than configured: axes, grid, tooltip, legend and the areas themselves are children, so a chart renders exactly the parts it asked for and nothing is switched on by a prop nobody can see. Reach for `<LineChart>` instead when the reader is comparing several series against each other rather than reading one total, and for `<BarChart>` when the categories are discrete.

### Props

- `config` (required) — `TConfig & ValidateKeys<TData, TConfig>`. Series keys → their label and paint. Declaration order is ramp order.
- `data` (required) — `TData[]`. The rows the chart draws. One entry per point, bar or category.
- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, legend, and the marks themselves.
- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
- `chartProps` — `ComponentProps<typeof RechartsAreaChart>`. Escape hatch onto the raw Recharts chart element.
- `curveType` — `ChartCurveType` default `'linear'`. The curve every `<AreaChart.Area>` inherits.
- `animationType` — `ChartRevealType` default `'forward'`. The intro wipe every `<AreaChart.Area>` inherits.
- `stackType` — `AreaStackType` default `'default'`. How several marks combine: side by side, stacked, or normalised to 100%.
- `defaultSelectedDataKey` — `string | null` default `null`. The series lit on first render, when the chart keeps its own selection.
- `selectedDataKey` — `string | null`. The selected series, driven from outside. Give this and the chart follows it; leave it undefined and the chart keeps its own, starting from `defaultSelectedDataKey`.
- `onSelectionChange` — `(selectedDataKey: string | null) => void`. Fires when the selection changes, and with null when it is cleared.
- `isLoading` — `boolean` default `false`. Swaps the marks for an animated skeleton, keeping the measured height so the page does not jump when the data lands.
- `loadingPoints` — `number`. How many points the skeleton draws.
- `xDataKey` — `keyof TData & string`. The row field on the category axis. Needed by the brush and by the table view.
- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. Rendered instead of the plot whenever `data` is empty and the chart is not loading — the state a real dashboard reaches within a week, and the one an empty pair of axes is indistinguishable from a failed load. `false` keeps the axes, for a chart whose emptiness is itself the reading.

## Example — default

```tsx
import { AreaChart, type ChartConfig } from '@misoto22/design/charts'

<AreaChart title="Visitors per month" config={config} data={data} xDataKey="month">
  <AreaChart.Grid />
  <AreaChart.XAxis dataKey="month" />
  <AreaChart.YAxis />
  <AreaChart.Legend />
  <AreaChart.Tooltip />
  <AreaChart.Area dataKey="desktop" />
  <AreaChart.Area dataKey="mobile" variant="hatched" />
</AreaChart>
```

## Example — fill variants

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'
import { AreaChart, type AreaVariant, type ChartConfig } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-4">
  <ToggleGroup
    type="single"
    value={variant}
    onValueChange={(next) => next && setVariant(next as AreaVariant)}
    aria-label="Fill variant"
  >
    {VARIANTS.map((option) => (
      <ToggleGroupItem key={option} value={option}>
        {option}
      </ToggleGroupItem>
    ))}
  </ToggleGroup>

  <AreaChart title={`Visitors per month — ${variant} fill`} config={config} data={data}>
    <AreaChart.Grid />
    <AreaChart.XAxis dataKey="month" />
    <AreaChart.Tooltip />
    <AreaChart.Area dataKey="desktop" variant={variant} />
  </AreaChart>
</div>
```

## Example — stroke and curve

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'

<div className="flex w-full flex-col gap-4">
  <div className="flex flex-wrap gap-3">
    <ToggleGroup
      type="single"
      value={stroke}
      onValueChange={(next) => next && setStroke(next as AreaStrokeVariant)}
      aria-label="Stroke"
    >
      {STROKES.map((option) => (
        <ToggleGroupItem key={option} value={option}>
          {option}
        </ToggleGroupItem>
      ))}
    </ToggleGroup>

    <ToggleGroup
      type="single"
      value={String(curve)}
      onValueChange={(next) => next && setCurve(next as ChartCurveType)}
      aria-label="Curve"
    >
      {CURVES.map((option) => (
        <ToggleGroupItem key={option} value={option}>
          {option}
        </ToggleGroupItem>
      ))}
    </ToggleGroup>
  </div>

  <AreaChart title="Visitors per month" config={config} data={data} curveType={curve}>
    <AreaChart.Grid />
    <AreaChart.XAxis dataKey="month" />
    <AreaChart.Tooltip />
    <AreaChart.Area dataKey="desktop" variant="solid" strokeVariant={stroke} />
  </AreaChart>
</div>
```

## Example — stacking

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'
import { AreaChart, type AreaStackType, type ChartConfig } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-4">
  <ToggleGroup
    type="single"
    value={stackType}
    onValueChange={(next) => next && setStackType(next as AreaStackType)}
    aria-label="Stacking"
  >
    {STACKS.map((option) => (
      <ToggleGroupItem key={option} value={option}>
        {option}
      </ToggleGroupItem>
    ))}
  </ToggleGroup>

  <AreaChart
    title={`Visitors per month — ${stackType}`}
    config={config}
    data={data}
    stackType={stackType}
  >
    <AreaChart.Grid />
    <AreaChart.XAxis dataKey="month" />
    <AreaChart.YAxis />
    <AreaChart.Legend />
    <AreaChart.Tooltip />
    <AreaChart.Area dataKey="desktop" variant="solid" />
    <AreaChart.Area dataKey="mobile" variant="lines" />
  </AreaChart>
</div>
```

## Example — dots and reveal

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'

<div className="flex w-full flex-col gap-4">
  <div className="flex flex-wrap gap-3">
    <ToggleGroup
      type="single"
      value={dot}
      onValueChange={(next) => next && setDot(next as ChartDotVariant)}
      aria-label="Dot"
    >
      {DOTS.map((option) => (
        <ToggleGroupItem key={option} value={option}>
          {option}
        </ToggleGroupItem>
      ))}
    </ToggleGroup>

    <ToggleGroup
      type="single"
      value={reveal}
      onValueChange={(next) => next && setReveal(next as ChartRevealType)}
      aria-label="Reveal"
    >
      {REVEALS.map((option) => (
        <ToggleGroupItem key={option} value={option}>
          {option}
        </ToggleGroupItem>
      ))}
    </ToggleGroup>
  </div>

  <AreaChart
    key={`${dot}-${reveal}`}
    title="Visitors per month"
    config={config}
    data={data}
    animationType={reveal}
  >
    <AreaChart.Grid />
    <AreaChart.XAxis dataKey="month" />
    <AreaChart.Tooltip />
    <AreaChart.Area dataKey="desktop" variant="solid">
      <AreaChart.Dot variant={dot} />
      <AreaChart.ActiveDot variant="colored-border" />
    </AreaChart.Area>
  </AreaChart>
</div>
```

## Example — brush

```tsx
import { AreaChart, type ChartConfig } from '@misoto22/design/charts'

<AreaChart title="Visitors per day" config={config} data={data} xDataKey="day">
  <AreaChart.Grid />
  <AreaChart.XAxis dataKey="day" />
  <AreaChart.Tooltip />
  <AreaChart.Area dataKey="desktop" variant="gradient" />
  <AreaChart.Brush height={56} />
</AreaChart>
```

## Example — loading

```tsx
import { AreaChart, type ChartConfig } from '@misoto22/design/charts'

<AreaChart title="Visitors per month" config={config} data={[]} isLoading>
  <AreaChart.Grid />
  <AreaChart.Area dataKey="desktop" />
</AreaChart>
```

## Example — chroma palette

```tsx
import { AreaChart, type ChartConfig } from '@misoto22/design/charts'

<div data-chart-palette="chroma" className="w-full">
  <AreaChart title="Visitors per month" config={config} data={data} xDataKey="month">
    <AreaChart.Grid />
    <AreaChart.XAxis dataKey="month" />
    <AreaChart.Legend />
    <AreaChart.Tooltip />
    <AreaChart.Area dataKey="desktop" variant="gradient" />
    <AreaChart.Area dataKey="mobile" variant="solid" />
    <AreaChart.Area dataKey="tablet" variant="lines" />
  </AreaChart>
</div>
```

## Example — annotations

```tsx
import { AreaChart, type ChartConfig } from '@misoto22/design/charts'

<AreaChart title="Visitors per month" config={config} data={data} xDataKey="month">
  <AreaChart.Grid />
  <AreaChart.XAxis dataKey="month" />
  <AreaChart.YAxis label="Visitors" />
  <AreaChart.Tooltip />

  <AreaChart.ReferenceBand x={['Mar', 'Apr']} label="Migration" />
  <AreaChart.ReferenceLine y={250} label="Target" weight="firm" />
  <AreaChart.Annotation x="Mar" y={148} text="Deploy freeze" showAnchor />

  <AreaChart.Area dataKey="desktop" variant="solid" />
</AreaChart>
```

## Example — empty

```tsx
import { AreaChart, type ChartConfig } from '@misoto22/design/charts'

<AreaChart
  title="Visitors per month"
  config={config}
  data={[]}
  empty={{
    title: 'No visits in this range',
    description: 'This project had no traffic before March. Try a wider range.',
  }}
>
  <AreaChart.Grid />
  <AreaChart.Area dataKey="desktop" />
</AreaChart>
```

## Example — sonify

```tsx
import { AreaChart, type ChartConfig } from '@misoto22/design/charts'

<AreaChart title="Visitors per month" config={config} data={data} xDataKey="month">
  <AreaChart.Sonify />
  <AreaChart.Grid />
  <AreaChart.XAxis dataKey="month" />
  <AreaChart.YAxis label="Visitors" />
  <AreaChart.Tooltip />
  <AreaChart.Area dataKey="desktop" variant="gradient" />
</AreaChart>
```

# BarChart

Discrete categories compared by length.

- Group: Charts
- Import: `import { BarChart } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/bar-chart/
- Related: area-chart, composed-chart, radial-chart

## When to reach for it

The categories are buckets rather than a continuum. If the axis is time and the reader is following a trend, an AreaChart or LineChart reads it faster.

## Anatomy

- **Figure frame** (required) — ChartFigure’s <figure>, named by title whether or not the page prints a heading above it.
- **Bars** (required) — <BarChart.Bar>, drawn through a custom shape: a transparent rectangle for the hit area, then the painted bar three pixels shorter than its slot so a stacked segment keeps a hairline of page between it and the one above. A bar shorter than that trim is floored at one pixel rather than taken to nothing, so a small count is never pixel-identical to an absent one.
- **Axes** — <BarChart.XAxis> and <BarChart.YAxis>, both flat by default — no tick line, no axis line. Every Recharts prop passes straight through, domain included, which is the door a truncated baseline comes in through.
- **Legend** — <BarChart.Legend>. With isClickable each entry is a real <button> carrying aria-pressed rather than a div with a handler, which is the difference between a filter a keyboard can reach and one it cannot.
- **Value labels** — <BarChart.Values>, a slot composed inside a bar. show defaults to last; all is for five or six bars where the exact figures are the point, and past that it is a table wearing a chart.
- **Hidden data table** — The sr-only table of the FULL data rather than of the brushed window, so a reader on the table is never shown less than the CSV export holds. hideDataTable removes it, and zero rows render nothing.
- **Empty state** — ChartEmpty, rendered in place of the plot when data is empty — a title, a reason and an optional action, so a filter that matched nothing is told apart from a load that failed. empty={false} keeps the bare axes instead.

## Best practices

### Do

- Reach for buffer on a period still open. It hatches the last ROW rather than the last bar on screen, so brushing back into the middle of the range hatches nothing — a month that closed in March is never drawn as still being counted.
- Leave the value axis anchored at zero. A bar encodes by LENGTH from the baseline, so a domain of ["dataMin", "dataMax"] passed through <BarChart.YAxis> turns a two percent gap into a doubled bar. This is the distortion a bar chart cannot survive and a LineChart can: a line encodes by slope, so clipping its domain rescales the reading rather than inventing one.
- Reach for orientation="horizontal" when the category names are long. The alternative is a tick label rotated under every column, and a rotated label is slower to read than the bar it names.
- Pass a tickFormatter to <BarChart.YAxis> under stackType="percent". Unlike AreaChart’s expanded stack, which swaps in percentTick itself, the bar chart’s axis keeps defaultTick — so a normalised chart reads 0 to 1 instead of 0% to 100%.
- Put the series that has to be compared across categories at the BASELINE of a stack. Only the bottom segment starts at zero; every band above it floats on the ones below, and reading a third band across twelve months is a comparison the eye cannot make. When that comparison is the point, group the bars instead.

### Don’t

- hideDataTable leaves no exact figure anywhere. defaultTick compacts at ten thousand and above, so the axis says 1.2M and so do the <BarChart.Values> labels; the sr-only table, where every cell is a full toLocaleString, was the only place the real number was written.
- Twenty bars at variant="default" is a wall rather than twenty values. stripped draws a 2px cap over a wash and stays countable at that density, which is the density it exists for.
- Do not close barCategoryGap up. The space between groups is the only thing telling a reader that two adjacent bars are two series rather than two categories, so a grouped chart with no category gap reads as a stacked one.

## Accessibility

- title is required; the rows are also rendered as a visually hidden table.
- Every bar carries an invisible full-height hit rectangle, so a 3px bar at the bottom of the scale is as easy to hit as a full-height one.
- A clickable legend entry is a real button with aria-pressed, not a div with a click handler.
- The staggered grow-in is anchored to the chart’s own start rather than to each bar’s mount, so a hover cannot replay it — and reduce-motion drops it entirely.

## BarChart

Discrete categories compared by length — the shape for "how much, per thing". Reach for `<AreaChart>` or `<LineChart>` when the axis is continuous and the reader is following a trend rather than comparing buckets.

### Props

- `config` (required) — `TConfig & ValidateKeys<TData, TConfig>`.
- `data` (required) — `TData[]`. The rows the chart draws. One entry per point, bar or category.
- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, legend, and the marks themselves.
- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
- `chartProps` — `ComponentProps<typeof RechartsBarChart>`. Escape hatch onto the raw Recharts chart element.
- `stackType` — `BarStackType` default `'default'`. How several marks combine: side by side, stacked, or normalised to 100%.
- `orientation` — `BarOrientation` default `'vertical'`. Which way the bars run. Reach for `horizontal` when the category names are long enough to need rotating under a column.
- `barRadius` — `number` default `BAR_RADIUS`. The corner every `<BarChart.Bar>` inherits.
- `animationType` — `ChartRevealType` default `'forward'`. The grow-in order every `<BarChart.Bar>` inherits.
- `barGap` — `number`. Gap between bars inside one category.
- `barCategoryGap` — `number`. Gap between categories.
- `defaultSelectedDataKey` — `string | null` default `null`. The series lit on first render, when the chart keeps its own selection.
- `selectedDataKey` — `string | null`. The selected series, driven from outside. Give this and the chart follows it; leave it undefined and the chart keeps its own, starting from `defaultSelectedDataKey`.
- `onSelectionChange` — `(selectedDataKey: string | null) => void`. Fires when the selection changes, and with null when it is cleared.
- `isLoading` — `boolean` default `false`. Swaps the marks for an animated skeleton, keeping the measured height so the page does not jump when the data lands.
- `loadingBars` — `number`. How many bars the skeleton draws.
- `xDataKey` — `keyof TData & string`. The row field on the category axis. Needed by the brush and by the table view.
- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. Rendered instead of the plot whenever `data` is empty and the chart is not loading — the state a real dashboard reaches within a week, and the one an empty pair of axes is indistinguishable from a failed load. `false` keeps the axes, for a chart whose emptiness is itself the reading.

## Example — default

```tsx
import { BarChart, type ChartConfig } from '@misoto22/design/charts'

<BarChart title="Visitors by month" config={config} data={data} xDataKey="month">
  <BarChart.Grid />
  <BarChart.XAxis dataKey="month" />
  <BarChart.YAxis />
  <BarChart.Legend />
  <BarChart.Tooltip />
  <BarChart.Bar dataKey="desktop" />
  <BarChart.Bar dataKey="mobile" variant="hatched" />
</BarChart>
```

## Example — fill variants

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'
import { BarChart, type BarVariant, type ChartConfig } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-4">
  <ToggleGroup
    type="single"
    value={variant}
    onValueChange={(next) => next && setVariant(next as BarVariant)}
    aria-label="Fill variant"
  >
    {VARIANTS.map((option) => (
      <ToggleGroupItem key={option} value={option}>
        {option}
      </ToggleGroupItem>
    ))}
  </ToggleGroup>

  <BarChart title={`Visitors by month — ${variant}`} config={config} data={data}>
    <BarChart.Grid />
    <BarChart.XAxis dataKey="month" />
    <BarChart.Tooltip />
    <BarChart.Bar dataKey="desktop" variant={variant} />
  </BarChart>
</div>
```

## Example — stacking and orientation

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'

<div className="flex w-full flex-col gap-4">
  <div className="flex flex-wrap gap-3">
    <ToggleGroup
      type="single"
      value={stackType}
      onValueChange={(next) => next && setStackType(next as BarStackType)}
      aria-label="Stacking"
    >
      {STACKS.map((option) => (
        <ToggleGroupItem key={option} value={option}>
          {option}
        </ToggleGroupItem>
      ))}
    </ToggleGroup>

    <ToggleGroup
      type="single"
      value={orientation}
      onValueChange={(next) => next && setOrientation(next as BarOrientation)}
      aria-label="Orientation"
    >
      {ORIENTATIONS.map((option) => (
        <ToggleGroupItem key={option} value={option}>
          {option}
        </ToggleGroupItem>
      ))}
    </ToggleGroup>
  </div>

  <BarChart
    title={`Visitors by channel — ${stackType}, ${orientation}`}
    config={config}
    data={data}
    stackType={stackType}
    orientation={orientation}
  >
    <BarChart.Grid />
    {horizontal ? (
      <>
        <BarChart.XAxis />
        <BarChart.YAxis dataKey="channel" width={128} />
      </>
    ) : (
      <>
        <BarChart.XAxis dataKey="channel" />
        <BarChart.YAxis />
      </>
    )}
    <BarChart.Legend />
    <BarChart.Tooltip />
    <BarChart.Bar dataKey="desktop" variant="duotone" />
    <BarChart.Bar dataKey="mobile" variant="hatched" />
  </BarChart>
</div>
```

## Example — emphasis

```tsx
import { BarChart, type ChartConfig } from '@misoto22/design/charts'

<div className="grid w-full gap-8 lg:grid-cols-3">
  <BarChart title="Glowing" showTitle config={config} data={data}>
    <BarChart.XAxis dataKey="month" />
    <BarChart.Bar dataKey="desktop" glowing />
  </BarChart>

  <BarChart title="Buffer — the last period is still open" showTitle config={config} data={data}>
    <BarChart.XAxis dataKey="month" />
    <BarChart.Bar dataKey="desktop" buffer />
  </BarChart>

  <BarChart title="Hover highlight" showTitle config={config} data={data}>
    <BarChart.XAxis dataKey="month" />
    <BarChart.Tooltip />
    <BarChart.Bar dataKey="desktop" variant="stripped" enableHoverHighlight />
  </BarChart>
</div>
```

## Example — interaction

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'

<div className="flex w-full flex-col gap-4">
  <div className="flex flex-wrap gap-3">
    <ToggleGroup
      type="single"
      value={variant}
      onValueChange={(next) => next && setVariant(next as ChartTooltipVariant)}
      aria-label="Tooltip ground"
    >
      {VARIANTS.map((option) => (
        <ToggleGroupItem key={option} value={option}>
          {option}
        </ToggleGroupItem>
      ))}
    </ToggleGroup>

    <ToggleGroup
      type="single"
      value={roundness}
      onValueChange={(next) => next && setRoundness(next as ChartTooltipRoundness)}
      aria-label="Tooltip corner"
    >
      {ROUNDNESS.map((option) => (
        <ToggleGroupItem key={option} value={option}>
          {option}
        </ToggleGroupItem>
      ))}
    </ToggleGroup>
  </div>

  <BarChart title="Visitors by month" config={config} data={data}>
    <BarChart.Grid />
    <BarChart.XAxis dataKey="month" />
    <BarChart.Legend isClickable />
    <BarChart.Tooltip variant={variant} roundness={roundness} defaultIndex={1} />
    <BarChart.Bar dataKey="desktop" isClickable />
    <BarChart.Bar dataKey="mobile" variant="hatched" isClickable />
  </BarChart>
</div>
```

## Example — brush

```tsx
import { BarChart, type ChartConfig } from '@misoto22/design/charts'

<BarChart title="Visitors by day" config={config} data={data} xDataKey="day">
  <BarChart.Grid />
  <BarChart.XAxis dataKey="day" />
  <BarChart.Tooltip />
  <BarChart.Bar dataKey="desktop" variant="stripped" />
  <BarChart.Brush height={56} />
</BarChart>
```

## Example — loading

```tsx
import { BarChart, type ChartConfig } from '@misoto22/design/charts'

<BarChart title="Visitors by month" config={config} data={[]} isLoading loadingBars={10}>
  <BarChart.Grid />
  <BarChart.Bar dataKey="desktop" />
</BarChart>
```

## Example — value labels

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'
import { BarChart, type ChartConfig, type ValueLabelMode } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-4">
  <ToggleGroup
    type="single"
    value={show}
    onValueChange={(next) => next && setShow(next as ValueLabelMode)}
    aria-label="Which points are labelled"
  >
    {MODES.map((option) => (
      <ToggleGroupItem key={option} value={option}>
        {option}
      </ToggleGroupItem>
    ))}
  </ToggleGroup>

  <BarChart title="Visitors by month" config={config} data={data}>
    <BarChart.Grid />
    <BarChart.XAxis dataKey="month" />
    {/* The value axis compacts itself above four digits: 30.5K rather than
        30,500, which is the same fact in half the width. */}
    <BarChart.YAxis label="Visitors" />
    <BarChart.Bar dataKey="desktop" variant="stripped">
      <BarChart.Values show={show} />
    </BarChart.Bar>
  </BarChart>
</div>
```

## Example — sonify

```tsx
import { BarChart, formatNumber, type ChartConfig } from '@misoto22/design/charts'

<BarChart title="Revenue by month" config={config} data={data} xDataKey="month">
  <BarChart.Sonify keys={['revenue']} formatValue={money} />
  <BarChart.Grid />
  <BarChart.XAxis dataKey="month" />
  <BarChart.YAxis tickFormatter={money} width={72} />
  <BarChart.Legend />
  <BarChart.Tooltip />
  <BarChart.Bar dataKey="revenue" variant="duotone" />
  <BarChart.Bar dataKey="refunds" variant="hatched" />
</BarChart>
```

## Example — toolbar

```tsx
import { BarChart, type ChartConfig } from '@misoto22/design/charts'

<BarChart title="Visitors by month" config={config} data={data} xDataKey="month">
  <BarChart.Toolbar exports={['png', 'csv']} />
  <BarChart.Grid />
  <BarChart.XAxis dataKey="month" />
  <BarChart.YAxis label="Visitors" />
  <BarChart.Tooltip />
  <BarChart.Bar dataKey="desktop" variant="duotone" />
</BarChart>
```

# LineChart

Several series compared over a continuous axis.

- Group: Charts
- Import: `import { LineChart } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/line-chart/
- Related: area-chart, composed-chart

## When to reach for it

The reader is comparing series against each other. When the area under one line is the point, fill it — that is an AreaChart.

## Anatomy

- **Figure frame** (required) — ChartFigure’s <figure> and its sr-only caption. description is announced with the title and printed only under showTitle, which is where a note about a clipped axis belongs.
- **Lines** (required) — <LineChart.Line>, one per series at a 1.6px stroke. isClickable adds a second, fully transparent 15px line underneath the visible one, because a hairline is not a pointer target.
- **Point markers** — <LineChart.Dot> and <LineChart.ActiveDot>, both slots and both off by default. The resting dot shares the intro wipe mask so it arrives with its own line; the active dot is never masked, because it exists only on hover, long after the wipe has finished.
- **Buffer segment** — buffer draws the last leg dashed by measuring the real path with getPointAtLength, so a projection reads as a different kind of fact at any curve type. Fewer than two drawable points and it falls back to a plain curve.
- **Sonification control** — <LineChart.Sonify>, a real <button> above the plot that plays the visible rows as pitch. Sound never starts from an effect, only from that click, and it reads the brushed window rather than the whole series.
- **Hidden data table** — The sr-only table of the full data. Recharts’ accessibilityLayer gives a keyboard cursor that announces one point at a time, which is navigation; this is the figures.

## Best practices

### Do

- This is the one chart in the family that survives a truncated value axis. A line encodes by SLOPE, so clipping the domain to the data’s own range is often what makes a two percent move visible at all — state the range in description when you do it.
- Reach for buffer on a period still open rather than dropping it. A part-month plotted solid reads as a crash; plotted as a dashed final leg it reads as what it is, which is incomplete.
- Compose <LineChart.Dot> when the series is sparse. With dots off — the default — five points are four segments, and the reader cannot tell a measured value from a bend in the interpolation.

### Don’t

- A single row draws nothing at all: one point has no segment, dot is false unless composed, and the empty state does not fire because a row exists. Guard the one-row case at the call site.
- Eight lines in one frame is a hairball, and a 1.6px stroke over an eight-step grey ramp makes it a worse one than a chromatic chart would. Past about five series the answer is Facet, not a ninth ramp slot — SERIES_SLOTS is 8 and there is no ninth.
- connectNulls turns a gap into a straight segment that looks measured. It costs more here than on an area, because the reader reads the slope of that invented segment as a rate.

## Accessibility

- title is required; the rows are also rendered as a visually hidden table.
- A clickable line gets a 15px transparent line underneath it, because a 1.6px stroke is not a pointer target.
- buffer draws the last segment dashed by measuring the real path length, so a projection is visibly a different kind of fact at any curve type.

## LineChart

Several series compared over a continuous axis — the shape for "which of these is going where". The difference from `<AreaChart>` is what the reader is asked to do: an area says "read the magnitude under this", a line says "compare these against each other". Filling four overlapping series makes the second question unanswerable, which is why a line chart has no fill variant to offer.

### Props

- `config` (required) — `TConfig & ValidateKeys<TData, TConfig>`.
- `data` (required) — `TData[]`. The rows the chart draws. One entry per point, bar or category.
- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, legend, and the marks themselves.
- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
- `chartProps` — `ComponentProps<typeof RechartsLineChart>`. Escape hatch onto the raw Recharts chart element.
- `curveType` — `ChartCurveType` default `'linear'`. How the line between two points is interpolated. Every mark inherits it unless it says otherwise.
- `animationType` — `ChartRevealType` default `'forward'`.
- `defaultSelectedDataKey` — `string | null` default `null`. The series lit on first render, when the chart keeps its own selection.
- `selectedDataKey` — `string | null`. The selected series, driven from outside. Give this and the chart follows it; leave it undefined and the chart keeps its own, starting from `defaultSelectedDataKey`.
- `onSelectionChange` — `(selectedDataKey: string | null) => void`. Fires when the selection changes, and with null when it is cleared.
- `isLoading` — `boolean` default `false`. Swaps the marks for an animated skeleton, keeping the measured height so the page does not jump when the data lands.
- `loadingPoints` — `number`. How many points the skeleton draws.
- `xDataKey` — `keyof TData & string`. The row field on the category axis. Needed by the brush and by the table view.
- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. Rendered instead of the plot whenever `data` is empty and the chart is not loading — the state a real dashboard reaches within a week, and the one an empty pair of axes is indistinguishable from a failed load. `false` keeps the axes, for a chart whose emptiness is itself the reading.

## Example — default

```tsx
import { LineChart, type ChartConfig } from '@misoto22/design/charts'

<LineChart title="Visitors per month" config={config} data={data} xDataKey="month">
  <LineChart.Grid />
  <LineChart.XAxis dataKey="month" />
  <LineChart.YAxis />
  <LineChart.Legend />
  <LineChart.Tooltip />
  <LineChart.Line dataKey="desktop" />
  <LineChart.Line dataKey="mobile" strokeVariant="dashed" />
</LineChart>
```

## Example — stroke dot curve

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'

<div className="flex w-full flex-col gap-4">
  <div className="flex flex-wrap gap-3">
    <ToggleGroup
      type="single"
      value={stroke}
      onValueChange={(next) => next && setStroke(next as LineStrokeVariant)}
      aria-label="Stroke"
    >
      {STROKES.map((option) => (
        <ToggleGroupItem key={option} value={option}>
          {option}
        </ToggleGroupItem>
      ))}
    </ToggleGroup>

    <ToggleGroup
      type="single"
      value={dot}
      onValueChange={(next) => next && setDot(next as ChartDotVariant)}
      aria-label="Dot"
    >
      {DOTS.map((option) => (
        <ToggleGroupItem key={option} value={option}>
          {option}
        </ToggleGroupItem>
      ))}
    </ToggleGroup>

    <ToggleGroup
      type="single"
      value={String(curve)}
      onValueChange={(next) => next && setCurve(next as ChartCurveType)}
      aria-label="Curve"
    >
      {CURVES.map((option) => (
        <ToggleGroupItem key={option} value={option}>
          {option}
        </ToggleGroupItem>
      ))}
    </ToggleGroup>
  </div>

  <LineChart title="Visitors per month" config={config} data={data} curveType={curve}>
    <LineChart.Grid />
    <LineChart.XAxis dataKey="month" />
    <LineChart.Tooltip />
    <LineChart.Line dataKey="desktop" strokeVariant={stroke}>
      <LineChart.Dot variant={dot} />
      <LineChart.ActiveDot variant="colored-border" />
    </LineChart.Line>
  </LineChart>
</div>
```

## Example — legend variants

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'
import { LineChart, type ChartConfig, type ChartLegendVariant } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-4">
  <ToggleGroup
    type="single"
    value={variant}
    onValueChange={(next) => next && setVariant(next as ChartLegendVariant)}
    aria-label="Legend swatch"
  >
    {VARIANTS.map((option) => (
      <ToggleGroupItem key={option} value={option}>
        {option}
      </ToggleGroupItem>
    ))}
  </ToggleGroup>

  <LineChart title="Visitors per month" config={config} data={data}>
    <LineChart.Grid />
    <LineChart.XAxis dataKey="month" />
    <LineChart.Legend variant={variant} />
    <LineChart.Tooltip />
    <LineChart.Line dataKey="desktop" />
    <LineChart.Line dataKey="mobile" strokeVariant="dashed" />
  </LineChart>
</div>
```

## Example — backgrounds

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'
import { LineChart, type ChartBackgroundVariant, type ChartConfig } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-4">
  <ToggleGroup
    type="single"
    value={variant}
    onValueChange={(next) => next && setVariant(next as ChartBackgroundVariant)}
    aria-label="Background plate"
    className="flex-wrap"
  >
    {VARIANTS.map((option) => (
      <ToggleGroupItem key={option} value={option}>
        {option}
      </ToggleGroupItem>
    ))}
  </ToggleGroup>

  <LineChart title={`Visitors per month — ${variant} plate`} config={config} data={data}>
    <LineChart.Background variant={variant} />
    <LineChart.XAxis dataKey="month" />
    <LineChart.Tooltip />
    <LineChart.Line dataKey="desktop" />
  </LineChart>
</div>
```

## Example — emphasis

```tsx
import { LineChart, type ChartConfig } from '@misoto22/design/charts'

<div className="grid w-full gap-8 lg:grid-cols-2">
  <LineChart title="Glowing — one series is the point" showTitle config={config} data={data}>
    <LineChart.Grid />
    <LineChart.XAxis dataKey="month" />
    <LineChart.Line dataKey="desktop" glowing />
    <LineChart.Line dataKey="mobile" strokeVariant="dashed" />
  </LineChart>

  {/* The last segment is dashed by measuring the real path length, so the
      split lands exactly on the second-to-last point at any curve type —
      which an arithmetic dasharray cannot do. */}
  <LineChart title="Buffer — the last leg is a projection" showTitle config={config} data={data}>
    <LineChart.Grid />
    <LineChart.XAxis dataKey="month" />
    <LineChart.Line dataKey="desktop" buffer />
  </LineChart>
</div>
```

## Example — brush

```tsx
import { LineChart, type ChartConfig } from '@misoto22/design/charts'

<LineChart title="Visitors per day" config={config} data={data} xDataKey="day">
  <LineChart.Grid />
  <LineChart.XAxis dataKey="day" />
  <LineChart.Legend />
  <LineChart.Tooltip />
  <LineChart.Line dataKey="desktop" />
  <LineChart.Line dataKey="mobile" strokeVariant="dashed" />
  <LineChart.Brush height={56} />
</LineChart>
```

## Example — loading

```tsx
import { LineChart, type ChartConfig } from '@misoto22/design/charts'

<LineChart title="Visitors per month" config={config} data={[]} isLoading>
  <LineChart.Grid />
  <LineChart.Line dataKey="desktop" />
</LineChart>
```

## Example — axis labels and format

```tsx
import { LineChart, formatNumber, type ChartConfig } from '@misoto22/design/charts'

<div className="grid w-full gap-8 lg:grid-cols-2">
  <LineChart title="p95 latency" showTitle config={latency} data={data}>
    <LineChart.Grid />
    <LineChart.XAxis dataKey="week" />
    <LineChart.YAxis
      label="Latency"
      tickFormatter={formatNumber({ style: 'duration' })}
      width={56}
    />
    <LineChart.Tooltip />
    <LineChart.Line dataKey="p95" />
  </LineChart>

  <LineChart title="Ad spend" showTitle config={spend} data={data}>
    <LineChart.Grid />
    <LineChart.XAxis dataKey="week" />
    <LineChart.YAxis
      tickFormatter={formatNumber({ style: 'currency', currency: 'AUD', fractionDigits: 0 })}
      width={72}
    />
    <LineChart.Tooltip />
    <LineChart.Line dataKey="spend" strokeVariant="dashed" />
  </LineChart>
</div>
```

## Example — sonify

```tsx
import { LineChart, type ChartConfig } from '@misoto22/design/charts'

<LineChart title="Latency per week, milliseconds" config={config} data={data} xDataKey="week">
  <LineChart.Sonify align="start" noteMs={180} />
  <LineChart.Grid />
  <LineChart.XAxis dataKey="week" />
  <LineChart.YAxis label="ms" />
  <LineChart.Legend />
  <LineChart.Tooltip />
  <LineChart.Line dataKey="p95" />
  <LineChart.Line dataKey="p50" strokeVariant="dashed" />
</LineChart>
```

## Example — toolbar

```tsx
import { LineChart, type ChartConfig } from '@misoto22/design/charts'

<LineChart title="Visitors per day" config={config} data={data} xDataKey="day">
  <LineChart.Toolbar exports={['png', 'csv']} />
  <LineChart.Grid />
  <LineChart.XAxis dataKey="day" />
  <LineChart.YAxis label="Visitors" />
  <LineChart.Legend />
  <LineChart.Tooltip />
  <LineChart.Line dataKey="desktop" />
  <LineChart.Line dataKey="mobile" strokeVariant="dashed" />
  <LineChart.Brush height={48} />
</LineChart>
```

# ComposedChart

Bars and lines over one axis — the volume, and the rate it moved at.

- Group: Charts
- Import: `import { ComposedChart } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/composed-chart/
- Related: bar-chart, line-chart

## When to reach for it

Two measures that share a scale. Two that do NOT share one belong in two charts or indexed to a common base: there is no second y-axis here, on purpose.

## Anatomy

- **Figure frame** (required) — ChartFigure’s <figure>, named by title, with the composed marks inside one measured ChartContainer.
- **The single value axis** (required) — <ComposedChart.YAxis>. One of them is the entire design: there is no dual-axis affordance and no second scale to configure, so the two measures are read against the same numbers.
- **Bars** — <ComposedChart.Bar>, the volume. Custom-shaped like BarChart’s, with the same transparent hit rectangle and the same grow-in anchored to the chart’s start rather than to each bar’s mount, so a hover cannot replay it.
- **Lines** — <ComposedChart.Line>, the rate. It inherits the chart’s curveType and reveal, so bars and line arrive as one figure rather than as two animations on two clocks.
- **Column highlight** — enableHoverHighlight dims every mark outside the hovered column, driven by the chart’s own onMouseMove index rather than by each mark’s hover — which is what makes a bar and a line in the same column light together.
- **Brush and toolbar** — <ComposedChart.Brush> in the container footer and <ComposedChart.Toolbar> above the plot. They drive one window, so a brushed range and a zoomed range cannot disagree about what is on screen.
- **Hidden data table** — The sr-only table of the FULL data rather than of the brushed window, so a reader on the table is never shown less than the CSV export holds. hideDataTable removes it, and zero rows render nothing.

## Best practices

### Do

- Index two measures to a common base — both as a percentage of January, say — when they do not share a scale. That is the substitute for the second axis this component deliberately does not have.
- Compose <ComposedChart.Legend> above two marks. A bar and a line at --series-1 and --series-2 differ by one step of grey and a shape, and only the shape is self-describing.
- Set enableHoverHighlight on every mark or on none. Set on one, the hovered column dims half of itself, which reads as a rendering fault rather than as emphasis.

### Don’t

- Do not smuggle a second y-axis in through chartProps or a yAxisId on <ComposedChart.YAxis>. Recharts allows it; the component’s claim is that it does not. Two scales chosen independently let the author decide where the lines cross, which is the single most misleading thing a chart can do — and it always works, on any two series.
- Do not assume the audio reading is here. AreaChart, BarChart and LineChart each carry a Sonify slot and this one does not, so a reader who has been listening across a dashboard falls back to the sr-only table — which is why hideDataTable is the prop not to set on this chart.

## Accessibility

- title is required; the rows are also rendered as a visually hidden table.
- One value axis only. A dual-axis chart lets its author choose where the lines cross, which is the single most misleading thing a chart can do.
- enableHoverHighlight dims every bar outside the hovered column, driven by the chart’s own tooltip index.

## ComposedChart

Bars and lines over one axis — the shape for "the volume, and the rate it moved at". One axis, always. Two measures at different scales belong in two charts or indexed to a common base; a second y-scale lets the author choose where the lines cross, which is the single most misleading thing a chart can do.

### Props

- `config` (required) — `TConfig & ValidateKeys<TData, TConfig>`.
- `data` (required) — `TData[]`. The rows the chart draws. One entry per point, bar or category.
- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, legend, and the marks themselves.
- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
- `chartProps` — `ComponentProps<typeof RechartsComposedChart>`. Escape hatch onto the raw Recharts chart element.
- `curveType` — `ChartCurveType` default `'linear'`. How the line between two points is interpolated. Every mark inherits it unless it says otherwise.
- `animationType` — `ChartRevealType` default `'forward'`.
- `barGap` — `number`.
- `barCategoryGap` — `number`.
- `defaultSelectedDataKey` — `string | null` default `null`. The series lit on first render, when the chart keeps its own selection.
- `selectedDataKey` — `string | null`. The selected series, driven from outside. Give this and the chart follows it; leave it undefined and the chart keeps its own, starting from `defaultSelectedDataKey`.
- `onSelectionChange` — `(selectedDataKey: string | null) => void`. Fires when the selection changes, and with null when it is cleared.
- `isLoading` — `boolean` default `false`. Swaps the marks for an animated skeleton, keeping the measured height so the page does not jump when the data lands.
- `loadingBars` — `number`. How many bars the skeleton draws.
- `xDataKey` — `keyof TData & string`. The row field on the category axis. Needed by the brush and by the table view.
- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. Rendered instead of the plot whenever `data` is empty and the chart is not loading — the state a real dashboard reaches within a week, and the one an empty pair of axes is indistinguishable from a failed load. `false` keeps the axes, for a chart whose emptiness is itself the reading.

## Example — default

```tsx
import { ComposedChart, type ChartConfig } from '@misoto22/design/charts'

<ComposedChart title="Revenue and profit" config={config} data={data} xDataKey="month">
  <ComposedChart.Grid />
  <ComposedChart.XAxis dataKey="month" />
  <ComposedChart.YAxis />
  <ComposedChart.Legend />
  <ComposedChart.Tooltip />
  <ComposedChart.Bar dataKey="revenue" />
  <ComposedChart.Line dataKey="profit" />
</ComposedChart>
```

## Example — variants

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'

<div className="flex w-full flex-col gap-4">
  <div className="flex flex-wrap gap-3">
    <ToggleGroup
      type="single"
      value={bar}
      onValueChange={(next) => next && setBar(next as BarVariant)}
      aria-label="Bar fill"
    >
      {BARS.map((option) => (
        <ToggleGroupItem key={option} value={option}>
          {option}
        </ToggleGroupItem>
      ))}
    </ToggleGroup>

    <ToggleGroup
      type="single"
      value={stroke}
      onValueChange={(next) => next && setStroke(next as AreaStrokeVariant)}
      aria-label="Line stroke"
    >
      {STROKES.map((option) => (
        <ToggleGroupItem key={option} value={option}>
          {option}
        </ToggleGroupItem>
      ))}
    </ToggleGroup>
  </div>

  <ComposedChart title="Revenue and profit" config={config} data={data}>
    <ComposedChart.Grid />
    <ComposedChart.XAxis dataKey="month" />
    <ComposedChart.Tooltip />
    <ComposedChart.Bar dataKey="revenue" variant={bar} />
    <ComposedChart.Line dataKey="profit" strokeVariant={stroke}>
      <ComposedChart.Dot variant="border" />
    </ComposedChart.Line>
  </ComposedChart>
</div>
```

## Example — hover highlight

```tsx
import { ComposedChart, type ChartConfig } from '@misoto22/design/charts'

<ComposedChart title="Revenue and profit" config={config} data={data}>
  <ComposedChart.Background variant="diagonal-lines" />
  <ComposedChart.XAxis dataKey="month" />
  <ComposedChart.Legend isClickable />
  <ComposedChart.Tooltip />
  <ComposedChart.Bar dataKey="revenue" enableHoverHighlight isClickable />
  <ComposedChart.Line dataKey="profit" glowing isClickable />
</ComposedChart>
```

## Example — brush and loading

```tsx
import { ComposedChart, type ChartConfig } from '@misoto22/design/charts'

<div className="grid w-full gap-8 lg:grid-cols-2">
  <ComposedChart title="Revenue and profit" showTitle config={config} data={data} xDataKey="day">
    <ComposedChart.Grid />
    <ComposedChart.XAxis dataKey="day" />
    <ComposedChart.Tooltip />
    <ComposedChart.Bar dataKey="revenue" variant="stripped" />
    <ComposedChart.Line dataKey="profit" />
    <ComposedChart.Brush height={48} />
  </ComposedChart>

  <ComposedChart title="Loading" showTitle config={config} data={[]} isLoading>
    <ComposedChart.Grid />
    <ComposedChart.Bar dataKey="revenue" />
  </ComposedChart>
</div>
```

# PieChart

Parts of one whole.

- Group: Charts
- Import: `import { PieChart } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/pie-chart/
- Related: radial-chart, bar-chart

## When to reach for it

Roughly what share, and nothing more precise. Ranking or comparing wedges — especially across two pies — is a BarChart’s job.

## Anatomy

- **Figure frame** (required) — ChartFigure’s <figure>, with an empty state at zero rows. There are no axes here, so without one a pie at zero rows was a name over a blank box with the hidden table returning null — the picture and its text equivalent silent together. empty={false} restores that, for a chart whose emptiness is the reading.
- **Wedges** (required) — <PieChart.Pie>. Each sector is painted from a diagonal gradient keyed on the row’s nameKey value, so config keys must match those values exactly — a row whose name is absent from config points at a gradient that was never defined and comes out unpainted.
- **Legend** — <PieChart.Legend>, under the pie and centred by default. A pie has no category axis naming its sectors, so this is where the names live.
- **Wedge labels** — <PieChart.Label>, a LabelList reversed out in --chart-surface. Its dataKey defaults to the pie’s VALUE key, so composing it prints the numbers.
- **Tooltip** — <PieChart.Tooltip>, with the heading suppressed: the wedge’s own name is the row label, so a heading would print it twice.

## Best practices

### Do

- Keep it under about five wedges. Past that the reader is ranking angles, which is the comparison a pie is worst at — a BarChart puts the same shares on a length scale and the ranking falls out of the picture for free.
- Compose <PieChart.Label> whenever the exact share matters. It defaults to the value key, and a printed number removes the angle estimate entirely, which is this form’s only real weakness and its cheapest fix.
- Give it an innerRadius. A donut is read by arc LENGTH rather than by wedge area, which the eye does better, and the hole is somewhere to put the total.

### Don’t

- A negative value has no wedge. Parts of one whole cannot include a negative part, so a breakdown carrying a refund or churn against expansion is a WaterfallChart, which is built for signed contributions.
- Two pies side by side is not a comparison. Reading a wedge across two circles is harder than reading two wedges inside one, and the reader will try anyway — put the two periods in one grouped BarChart.
- Pass a POSITIVE paddingAngle if the chart has to survive forced colours. There is one fill variant here, so all eight --series-* tokens collapse to CanvasText and every wedge is the same solid shape; what separates them is geometry, and a gap of a degree or two is it. The stroke is not the mechanism — it is drawn only when paddingAngle is NEGATIVE, where the wedges overlap and the surface-coloured stroke re-separates them into stacked cards. 0 is the one value with neither, and a default pie in forced colours is one uniform disc with the legend and the labels carrying the whole reading.

## Accessibility

- title is required; the rows are also rendered as a visually hidden table.
- The legend sits under the pie by default, because a pie has no category axis naming its sectors.
- Compose a Label to print the numbers on the wedges: a pie’s weakness is that an angle is hard to read, and a printed number removes the guess.
- One fill variant, deliberately. A wedge is small and awkwardly shaped, and a texture inside one reads as noise.

## PieChart

Parts of one whole. Worth saying plainly: a pie answers "roughly what share" and nothing more precise. Comparing two adjacent wedges by eye is unreliable past about five of them, and comparing a wedge across two pies is worse. When the reader needs to rank or compare, a `<BarChart>` answers the same question better.

### Props

- `config` (required) — `ChartConfig`. Sector names → their label and paint. Keys must match the `nameKey` values.
- `data` (required) — `TData[]`. The rows the chart draws. One entry per point, bar or category.
- `dataKey` (required) — `keyof TData & string`. The row field holding each sector's number.
- `nameKey` (required) — `keyof TData & string`. The row field holding each sector's name.
- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, legend, and the marks themselves.
- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
- `chartProps` — `ComponentProps<typeof RechartsPieChart>`. Escape hatch onto the raw Recharts chart element.
- `defaultSelectedSector` — `string | null` default `null`. The sector lit on first render, when the chart keeps its own selection.
- `selectedSector` — `string | null`. The selected sector, driven from outside. Give this and the chart follows it; leave it undefined and the chart keeps its own, starting from `defaultSelectedSector`.
- `onSelectionChange` — `(selection: { name: string; value: number } | null) => void`. Fires when the selection changes, and with null when it is cleared.
- `isLoading` — `boolean` default `false`. Swaps the marks for an animated skeleton, keeping the measured height so the page does not jump when the data lands.
- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. `false` keeps the empty plot, for a chart whose emptiness is itself the reading.

## Example — default

```tsx
import { PieChart, type ChartConfig } from '@misoto22/design/charts'

<PieChart
  title="Visitors by browser"
  config={config}
  data={data}
  dataKey="visitors"
  nameKey="browser"
>
  <PieChart.Pie />
  <PieChart.Tooltip />
  <PieChart.Legend />
</PieChart>
```

## Example — shape

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'
import { PieChart, type ChartConfig } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-4">
  <ToggleGroup
    type="single"
    value={shape}
    onValueChange={(next) => next && setShape(next as Shape)}
    aria-label="Shape"
  >
    {(Object.keys(SHAPES) as Shape[]).map((option) => (
      <ToggleGroupItem key={option} value={option}>
        {option}
      </ToggleGroupItem>
    ))}
  </ToggleGroup>

  <PieChart
    title={`Visitors by browser — ${shape}`}
    config={config}
    data={data}
    dataKey="visitors"
    nameKey="browser"
  >
    <PieChart.Pie {...SHAPES[shape]} />
    <PieChart.Tooltip />
    <PieChart.Legend />
  </PieChart>
</div>
```

## Example — labels and emphasis

```tsx
import { PieChart, type ChartConfig } from '@misoto22/design/charts'

<div className="grid w-full gap-8 lg:grid-cols-2">
  <PieChart
    title="Labelled"
    showTitle
    config={config}
    data={data}
    dataKey="visitors"
    nameKey="browser"
  >
    <PieChart.Pie innerRadius="45%">
      <PieChart.Label />
    </PieChart.Pie>
    <PieChart.Legend />
  </PieChart>

  <PieChart
    title="One wedge is the point"
    showTitle
    config={config}
    data={data}
    dataKey="visitors"
    nameKey="browser"
  >
    <PieChart.Background variant="overlapping-circles" />
    <PieChart.Pie innerRadius="50%" glowingSectors={['chrome']} isClickable />
    <PieChart.Tooltip />
    <PieChart.Legend isClickable />
  </PieChart>
</div>
```

## Example — loading

```tsx
import { PieChart, type ChartConfig } from '@misoto22/design/charts'

<PieChart
  title="Visitors by browser"
  config={config}
  data={[]}
  dataKey="visitors"
  nameKey="browser"
  isLoading
>
  <PieChart.Pie innerRadius="50%" />
</PieChart>
```

# RadarChart

A profile across several named dimensions.

- Group: Charts
- Import: `import { RadarChart } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/radar-chart/
- Related: line-chart, pie-chart

## When to reach for it

Recognising a silhouette. The area a radar encloses depends on the order its spokes happen to be in, so it is the wrong chart for comparing magnitudes.

## Anatomy

- **Figure frame** (required) — ChartFigure’s <figure>, with the polar plot inside one ChartContainer.
- **Polygons** (required) — <RadarChart.Radar>. variant="filled" is the default and paints at 2.2 times --chart-fill, because a radar’s fill IS the mark rather than a wash under a line and has to hold its shape where two of them overlap.
- **Spoke labels** — <RadarChart.PolarAngleAxis>, the names around the perimeter. They are the only thing that says what a corner of the silhouette measures.
- **Radial scale** — <RadarChart.PolarRadiusAxis>, and it is opt-in. Leave it out and the rings carry no numbers at all: the reader has a shape and no idea what one ring is worth.
- **Grid** — <RadarChart.PolarGrid>, polygonal rather than circular by default, so the rings line up with the polygon the data draws over them.
- **Legend** — <RadarChart.Legend>. Two overlapping outlines two steps apart on the grey ramp name nothing, and there is no axis here to name them instead.

## Best practices

### Do

- Fix the spoke ORDER and keep it fixed across every radar on the page. The area a polygon encloses is a function of the order the dimensions happen to sit in, so re-ordering the spokes changes the silhouette without changing one number.
- Put every dimension on a comparable scale first — a percentile, a score out of ten, an index. One radius serves all the spokes, so a spoke in milliseconds beside one in percent draws a spike that means nothing.
- Switch to variant="lines" past two series. Filled polygons overlap, and judging areas through two layers of translucency is precisely what this form is worst at.

### Don’t

- Do not read magnitude off it. A radar is for recognising a silhouette — the same profile before and after — and which of two is bigger is a question a BarChart answers and this one only appears to.
- Do not skip <RadarChart.PolarRadiusAxis> and call the chart finished. It renders, the rings render, and nothing on screen says whether the outer ring is 100 or 1,000; the sr-only table still has the figures, the sighted reader does not.

## Accessibility

- title is required; the rows are also rendered as a visually hidden table.
- Two or three series at most: filled polygons overlap, and judging areas through two layers of translucency is what a radar is worst at. Past that, variant="lines".

## RadarChart

A profile across several named dimensions — the shape for "what is this thing strong and weak at". It reads a SHAPE, not a set of values: the area a radar encloses depends on the order the spokes happen to be in, so it is the wrong chart for comparing magnitudes and the right one for recognising a silhouette. Two or three series at most.

### Props

- `config` (required) — `TConfig & ValidateKeys<TData, TConfig>`.
- `data` (required) — `TData[]`. The rows the chart draws. One entry per point, bar or category.
- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, legend, and the marks themselves.
- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
- `chartProps` — `ComponentProps<typeof RechartsRadarChart>`. Escape hatch onto the raw Recharts chart element.
- `defaultSelectedDataKey` — `string | null` default `null`. The series lit on first render, when the chart keeps its own selection.
- `selectedDataKey` — `string | null`. The selected series, driven from outside. Give this and the chart follows it; leave it undefined and the chart keeps its own, starting from `defaultSelectedDataKey`.
- `onSelectionChange` — `(selectedDataKey: string | null) => void`. Fires when the selection changes, and with null when it is cleared.
- `isLoading` — `boolean` default `false`. Swaps the marks for an animated skeleton, keeping the measured height so the page does not jump when the data lands.
- `loadingPoints` — `number`. How many points the skeleton draws.
- `angleDataKey` — `keyof TData & string`. The row field naming each spoke. Used by the table view.
- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. `false` keeps the empty plot, for a chart whose emptiness is itself the reading.

## Example — default

```tsx
import { RadarChart, type ChartConfig } from '@misoto22/design/charts'

<RadarChart title="Team profile" config={config} data={data} angleDataKey="skill">
  <RadarChart.PolarGrid />
  <RadarChart.PolarAngleAxis dataKey="skill" />
  <RadarChart.Tooltip />
  <RadarChart.Radar dataKey="current">
    <RadarChart.Dot variant="border" />
  </RadarChart.Radar>
</RadarChart>
```

## Example — variant and grid

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'
import { RadarChart, type ChartConfig, type RadarVariant } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-4">
  <div className="flex flex-wrap gap-3">
    <ToggleGroup
      type="single"
      value={variant}
      onValueChange={(next) => next && setVariant(next as RadarVariant)}
      aria-label="Radar fill"
    >
      {VARIANTS.map((option) => (
        <ToggleGroupItem key={option} value={option}>
          {option}
        </ToggleGroupItem>
      ))}
    </ToggleGroup>

    <ToggleGroup
      type="single"
      value={gridType}
      onValueChange={(next) => next && setGridType(next as (typeof GRIDS)[number])}
      aria-label="Grid"
    >
      {GRIDS.map((option) => (
        <ToggleGroupItem key={option} value={option}>
          {option}
        </ToggleGroupItem>
      ))}
    </ToggleGroup>
  </div>

  <RadarChart title="Team profile" config={config} data={data} angleDataKey="skill">
    <RadarChart.PolarGrid gridType={gridType} />
    <RadarChart.PolarAngleAxis dataKey="skill" />
    <RadarChart.Legend isClickable />
    <RadarChart.Tooltip />
    <RadarChart.Radar dataKey="current" variant={variant} isClickable />
    <RadarChart.Radar dataKey="target" variant={variant} isClickable />
  </RadarChart>
</div>
```

## Example — loading

```tsx
import { RadarChart, type ChartConfig } from '@misoto22/design/charts'

<RadarChart title="Team profile" config={config} data={[]} isLoading>
  <RadarChart.PolarGrid />
  <RadarChart.Radar dataKey="current" />
</RadarChart>
```

# RadialChart

Values on an arc — a gauge, or a few totals against one scale.

- Group: Charts
- Import: `import { RadialChart } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/radial-chart/
- Related: pie-chart, bar-chart

## When to reach for it

A single value against a fixed total. Past about four bars a BarChart is the honest choice, because a radial bar’s radius is not its value.

## Anatomy

- **Figure frame** (required) — ChartFigure’s <figure>, with an empty state at zero rows. Its hidden table needs a value field, which it takes from valueKey or, failing that, from the dataKey of the composed <RadialChart.RadialBar> — so a chart that names neither still has no table.
- **Arcs** (required) — <RadialChart.RadialBar>, one per row, 14px thick with a 5px cap. variant="semi" drops the centre to 70% so a half arc sits in the middle of its own box rather than at the top of it.
- **Track** — showTrack, on by default, painting the unfilled remainder behind each arc in --chart-track. It is what makes a gauge a gauge: without it there is no visible whole for the fill to be a part of.
- **Scale** — The PolarAngleAxis the root inserts when max is set, with domain [0, max] and its ticks off. Leave max unset and the domain is taken from the data instead.
- **Legend** — <RadialChart.Legend>. An arc has no category axis, so above one bar this is the only thing naming them.

## Best practices

### Do

- Set max on anything that is a gauge. Without it the scale comes from the data, so the largest bar always fills the arc and 62% and 98% are drawn identically.
- Pass valueKey when the arc is not the only mark. It names the field the hidden table prints and the field the LEGEND reports a selection from; without either it or a composed <RadialChart.RadialBar> there is no value field, and the table is not empty but absent.
- Use variant="semi" for a single value. A half arc reads as a dial with a floor and a ceiling, where a full ring asks the reader to work out what a whole circle was worth.

### Don’t

- Do not compare bars across radii. A radial bar’s LENGTH is its value but its RADIUS is not, so an inner arc and an outer arc holding the same number are drawn different lengths — past about four bars a BarChart is the honest form.
- Do not let a reader take an arc as a share of the ring when max is unset. A full sweep then means the biggest thing here, which is a different sentence from all of it.

## Accessibility

- title is required; pass valueKey and the rows are also rendered as a visually hidden table.
- Set max or the scale comes from the data and the largest bar always fills the arc — which makes 62% and 98% look identical.
- showTrack draws the unfilled remainder, which is what makes a gauge readable at all.

## RadialChart

Values on an arc — a gauge, or a small set of totals against one scale. The caveat worth knowing before reaching for it: a radial bar's LENGTH is its value, but its RADIUS is not, so an inner bar and an outer bar of the same value are drawn different lengths. That makes it a poor comparison and a good single-value gauge; past about four bars, a `<BarChart>` is the honest choice.

### Props

- `config` (required) — `ChartConfig`. Bar names → their label and paint. Keys must match the `nameKey` values.
- `data` (required) — `TData[]`. The rows the chart draws. One entry per point, bar or category.
- `nameKey` (required) — `keyof TData & string`. The row field naming each bar.
- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, legend, and the marks themselves.
- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
- `chartProps` — `ComponentProps<typeof RechartsRadialBarChart>`. Escape hatch onto the raw Recharts chart element.
- `variant` — `RadialVariant` default `'full'`. The arc shape — a full ring, or the half circle a gauge wants.
- `max` — `number`. What a full sweep is worth. Without it the scale comes from the data, so the largest bar always fills the arc — which is right for a comparison and wrong for a gauge. Set it (typically 100) whenever a single value has to read against a fixed total, or "62%" and "98%" will look identical.
- `innerRadius` — `number | string` default `'30%'`. Where the arc starts, from the centre.
- `outerRadius` — `number | string` default `'100%'`. Where the arc ends.
- `defaultSelectedBar` — `string | null` default `null`. The bar lit on first render, when the chart keeps its own selection.
- `selectedBar` — `string | null`. The selected bar, driven from outside. Give this and the chart follows it; leave it undefined and the chart keeps its own, starting from `defaultSelectedBar`.
- `onSelectionChange` — `(selection: { name: string; value: number } | null) => void`. Fires when the selection changes, and with null when it is cleared.
- `isLoading` — `boolean` default `false`. Swaps the marks for an animated skeleton, keeping the measured height so the page does not jump when the data lands.
- `valueKey` — `keyof TData & string`. The row field holding each bar's number, for the table view and for the selection the legend reports. Falls back to the `dataKey` of the composed `<RadialChart.RadialBar>`, so the usual call site needs neither.
- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. `false` keeps the empty plot, for a chart whose emptiness is itself the reading.

## Example — default

```tsx
import { RadialChart, type ChartConfig } from '@misoto22/design/charts'

<RadialChart
  title="Storage used by tier"
  config={config}
  data={data}
  nameKey="tier"
  valueKey="used"
>
  <RadialChart.RadialBar dataKey="used" isClickable />
  <RadialChart.Tooltip />
  <RadialChart.Legend isClickable />
</RadialChart>
```

## Example — gauge

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'
import { RadialChart, type ChartConfig, type RadialVariant } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-4">
  <ToggleGroup
    type="single"
    value={variant}
    onValueChange={(next) => next && setVariant(next as RadialVariant)}
    aria-label="Arc"
  >
    {VARIANTS.map((option) => (
      <ToggleGroupItem key={option} value={option}>
        {option}
      </ToggleGroupItem>
    ))}
  </ToggleGroup>

  <RadialChart
    title="Storage used"
    config={config}
    data={data}
    nameKey="tier"
    valueKey="used"
    variant={variant}
    max={100}
    innerRadius="65%"
  >
    <RadialChart.RadialBar dataKey="used" barSize={22} cornerRadius={11} />
    <RadialChart.Tooltip />
  </RadialChart>
</div>
```

## Example — loading

```tsx
import { RadialChart, type ChartConfig } from '@misoto22/design/charts'

<RadialChart title="Storage used by tier" config={config} data={[]} nameKey="tier" isLoading>
  <RadialChart.RadialBar dataKey="used" />
</RadialChart>
```

# SankeyChart

Where a quantity goes as it moves through stages.

- Group: Charts
- Import: `import { SankeyChart } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/sankey-chart/
- Related: bar-chart

## When to reach for it

A funnel, a budget, an energy or traffic breakdown. The only chart here whose data is a graph rather than a table.

## Anatomy

- **Figure frame** (required) — ChartFigure’s <figure>, named by title, with the diagram inside one ChartContainer.
- **Node rectangles** (required) — The root’s own node renderer. A node whose name is in config is painted from its gradient; one that is not falls back to currentColor, so it is drawn plainly rather than lost.
- **Node labels** — <SankeyChart.NodeLabel>, composed inside <SankeyChart.Node>, and entirely opt-in. Leave it out and NOTHING on the diagram is named — there is no legend here, so the names exist only in the tooltip and in the hidden table.
- **Flow bands** — <SankeyChart.Link>. gradient fades the source’s colour into the target’s and is the variant that actually reads as flow; solid gives up colour entirely and lets the node rectangles carry identity.
- **Hidden data table** (required) — The sr-only table lists the LINKS — from, to, value — rather than the nodes, because a table of node totals loses every from-and-to the diagram exists to state.

## Best practices

### Do

- Treat the nodes array as an addressing table. A link’s source and target are INDEXES into it, so inserting a node at the front silently re-points every link at a different pair — and the layout still renders, which is why this belongs in a test rather than in an eyeball.
- Compose <SankeyChart.Node> with a <SankeyChart.NodeLabel> inside it. Names are opt-in and there is no legend to fall back on, so a sankey without labels is a set of anonymous grey bands.
- Keep the flows conserved, or give the shortfall a node of its own with a name. Band width is the only arithmetic on screen, and a node that quietly loses eight percent simply reads as a smaller node.

### Don’t

- Do not reach for it when the quantity only narrows along one path. That is a FunnelChart; a sankey spends its whole layout budget on splits that are not there.
- Do not put twenty nodes in one column. nodePadding is 10px and the layout distributes what is left, so past a dozen a node rectangle is a few pixels tall and a label centred on it has nowhere to sit.

## Accessibility

- title is required. The hidden table lists the FLOWS rather than the nodes — a table of node totals would lose every “from → to” the diagram exists to show.
- Four link variants: gradient reads as flow, source and target attribute a band to one end, solid gives up colour and lets the nodes carry identity.

## SankeyChart

Where a quantity goes as it moves through stages — the shape for a funnel, a budget, an energy or traffic breakdown. The only chart here whose data is a GRAPH rather than a table, so it takes `{ nodes, links }` instead of rows, and the table view lists the flows rather than the nodes.

### Props

- `data` (required) — `SankeyData`. The nodes and the links between them, in Recharts' own shape.
- `config` (required) — `ChartConfig`. Node names → their label and paint.
- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, legend, and the marks themselves.
- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
- `sankeyProps` — `Omit<SankeyProps, 'data'>`. Escape hatch onto the raw Recharts Sankey element.
- `nodeWidth` — `number` default `10`. How wide each node rectangle is, in pixels.
- `nodePadding` — `number` default `10`. Vertical gap between nodes in the same column, in pixels.
- `linkCurvature` — `number` default `0.5`. 0 draws straight links, 1 the fullest curve.
- `iterations` — `number` default `32`. Layout passes. More is tidier and slower.
- `sort` — `boolean` default `true`. Lets the layout reorder nodes for the fewest crossings.
- `align` — `'left' | 'justify'` default `'justify'`. How nodes are placed along the flow axis.
- `verticalAlign` — `'justify' | 'top'` default `'justify'`. How nodes are distributed within a column.
- `defaultSelectedNode` — `string | null` default `null`. The node lit on first render, when the chart keeps its own selection. Selecting one dims every flow it does not touch.
- `selectedNode` — `string | null`. The selected node, driven from outside. Give this and the chart follows it; leave it undefined and the chart keeps its own, starting from `defaultSelectedNode`.
- `onSelectionChange` — `(selection: { name: string; value: number } | null) => void`. Fires when the selection changes, and with null when it is cleared.
- `isLoading` — `boolean` default `false`. Swaps the marks for an animated skeleton, keeping the measured height so the page does not jump when the data lands.
- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. `false` keeps the empty plot, for a chart whose emptiness is itself the reading.

## Example — default

```tsx
import { SankeyChart, type ChartConfig } from '@misoto22/design/charts'

<SankeyChart title="Visits by source and outcome" config={config} data={data} nodeWidth={12}>
  <SankeyChart.Node radius={3}>
    <SankeyChart.NodeLabel position="outside" showValues />
  </SankeyChart.Node>
  <SankeyChart.Link variant="gradient" />
  <SankeyChart.Tooltip />
</SankeyChart>
```

## Example — links and labels

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'

<div className="flex w-full flex-col gap-4">
  <div className="flex flex-wrap gap-3">
    <ToggleGroup
      type="single"
      value={link}
      onValueChange={(next) => next && setLink(next as SankeyLinkVariant)}
      aria-label="Link"
    >
      {LINKS.map((option) => (
        <ToggleGroupItem key={option} value={option}>
          {option}
        </ToggleGroupItem>
      ))}
    </ToggleGroup>

    <ToggleGroup
      type="single"
      value={position}
      onValueChange={(next) => next && setPosition(next as SankeyLabelPosition)}
      aria-label="Labels"
    >
      {LABELS.map((option) => (
        <ToggleGroupItem key={option} value={option}>
          {option}
        </ToggleGroupItem>
      ))}
    </ToggleGroup>
  </div>

  <SankeyChart
    title="Visits by source and outcome"
    config={config}
    data={data}
    nodeWidth={position === 'inside' ? 76 : 12}
  >
    <SankeyChart.Node radius={3} isClickable>
      <SankeyChart.NodeLabel position={position} showValues />
    </SankeyChart.Node>
    <SankeyChart.Link variant={link} verticalPadding={2} />
    <SankeyChart.Tooltip />
  </SankeyChart>
</div>
```

## Example — loading

```tsx
import { SankeyChart, type ChartConfig } from '@misoto22/design/charts'

<SankeyChart title="Visits by source and outcome" config={config} data={data} isLoading>
  <SankeyChart.Node />
  <SankeyChart.Link />
</SankeyChart>
```

# ScatterChart

Two measures against each other, one mark per observation.

- Group: Charts
- Import: `import { ScatterChart } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/scatter-chart/
- Related: line-chart, heatmap

## When to reach for it

Correlation, clustering, outliers — the questions that do not survive being bucketed into a bar. The only chart here whose x axis is a number rather than a category.

## Anatomy

- **Figure frame** (required) — ChartFigure’s <figure>, with isLoading and an empty state. Emptiness is read from the declared table rows, for the same reason the table is declared at all: the observations live on each <Scatter>, and the root cannot see them.
- **Numeric axes** (required) — <ScatterChart.XAxis> and <ScatterChart.YAxis>, both type="number" by default. The only chart in the group whose horizontal axis is a measurement rather than a category.
- **Clouds** (required) — <ScatterChart.Scatter>, one per series, each carrying its OWN data array rather than reading the root’s. Six mark shapes, and a solid mark takes a 1px --chart-surface ring so two coincident observations stay countable.
- **Size channel** — <ScatterChart.ZAxis>, range [40, 400] by default. That range is in AREA, not radius: doubling a radius quadruples the ink, which is how a bubble chart usually lies.
- **Crosshair** — The tooltip’s cursor, a pair of rules rather than one band. A scatter point is located by two coordinates and a single vertical cursor answers half of that.
- **Declared table** — table is a PROP here, not inferred. Scatter data lives on each series, so there are no rows on the root to read off — and passing nothing ships a figure with no table at all.

## Best practices

### Do

- Declare table. It is the one chart in the group whose hidden table cannot be derived, so omitting it fails silently: the figure renders, is named, and has no numbers behind it.
- Separate series by shape before anything else. Circle against cross stays legible where two steps of grey do not, and shape survives overprinting and forced colours — where every --series-* token becomes CanvasText and a lightness step is gone.
- Reach for variant="outline" or shape="ring" on a dense cloud. A hollow mark shows what is under it; a solid one at two thousand points is a silhouette of the densest region and nothing else.

### Don’t

- Do not vary size between series to mean something. size is a flat radius in pixels, so it encodes nothing while looking exactly as if it does; <ScatterChart.ZAxis> is the only path that maps a value to a mark’s area.
- Past three series shape stops separating them — circle, cross and triangle are distinct, and a fourth glyph is a diamond most readers see as a rotated square. Small multiples on shared axes is the answer, not a fourth mark.

## Accessibility

- title is required. The table view is declared rather than inferred: scatter data lives on each series, so there is no single set of rows to read off the root.
- Shape does the work hue does elsewhere. Two overlapping clouds separate far better by circle-versus-cross than by two steps of grey — and shape survives overprinting, which a lightness step does not.
- A solid mark carries a surface-coloured ring, so two observations that land on top of each other stay countable.
- ZAxis maps its measure to a mark’s AREA, not its radius: doubling a radius quadruples the ink, which is the most common way a bubble chart lies.

## ScatterChart

Two measures against each other, one mark per observation — the shape for "is there a relationship here". The only chart in the set whose x axis is a NUMBER rather than a category, which is the whole point: a scatter answers correlation, clustering and outliers, and none of those questions survive being bucketed into a bar. Past three series, shape stops separating them and the answer is small multiples — one chart per series, same axes — rather than a fourth mark.

### Props

- `config` (required) — `ChartConfig`. Series keys → their label and paint. Declaration order is ramp order.
- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, legend, and the marks themselves.
- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
- `chartProps` — `ComponentProps<typeof RechartsScatterChart>`. Escape hatch onto the raw Recharts chart element.
- `defaultSelectedDataKey` — `string | null` default `null`. The series lit on first render, when the chart keeps its own selection.
- `selectedDataKey` — `string | null`. The selected series, driven from outside. Give this and the chart follows it; leave it undefined and the chart keeps its own, starting from `defaultSelectedDataKey`.
- `onSelectionChange` — `(selectedDataKey: string | null) => void`. Fires when the selection changes, and with null when it is cleared.
- `table` — `ScatterTable | false`. The rows behind the hidden table view, with the fields to print. Scatter data lives on each `<Scatter>` rather than on the root, so unlike every other chart here the table cannot be inferred — it is declared.
- `isLoading` — `boolean` default `false`. Swaps the marks for an animated skeleton, keeping the measured height so the page does not jump when the data lands.
- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. `false` keeps the empty plot, for a chart whose emptiness is itself the reading. Read from the declared `table` rows, for the same reason the table is declared: the observations live on each `<Scatter>`, and the root cannot see them.

## Example — default

```tsx
import { ScatterChart, type ChartConfig } from '@misoto22/design/charts'

<ScatterChart
  title="Load time against bundle size"
  config={config}
  table={{
    rows: desktop,
    rowKey: 'kb',
    columns: [{ key: 'ms', label: 'Load (ms)' }],
  }}
>
  <ScatterChart.Grid />
  <ScatterChart.XAxis dataKey="kb" name="Bundle" unit=" kB" />
  <ScatterChart.YAxis dataKey="ms" name="Load" unit=" ms" />
  <ScatterChart.Tooltip />
  <ScatterChart.Scatter dataKey="desktop" data={desktop} />
</ScatterChart>
```

## Example — shape and variant

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'

<div className="flex w-full flex-col gap-4">
  <div className="flex flex-wrap gap-3">
    <ToggleGroup
      type="single"
      value={shape}
      onValueChange={(next) => next && setShape(next as ScatterShape)}
      aria-label="Mark shape"
    >
      {SHAPES.map((option) => (
        <ToggleGroupItem key={option} value={option}>
          {option}
        </ToggleGroupItem>
      ))}
    </ToggleGroup>

    <ToggleGroup
      type="single"
      value={variant}
      onValueChange={(next) => next && setVariant(next as ScatterVariant)}
      aria-label="Mark fill"
    >
      {VARIANTS.map((option) => (
        <ToggleGroupItem key={option} value={option}>
          {option}
        </ToggleGroupItem>
      ))}
    </ToggleGroup>
  </div>

  <ScatterChart
    title="Load time against bundle size"
    config={config}
    table={{
      rows: [...desktop, ...mobile],
      rowKey: 'kb',
      columns: [{ key: 'ms', label: 'Load (ms)' }],
    }}
  >
    <ScatterChart.Grid />
    <ScatterChart.XAxis dataKey="kb" name="Bundle" unit=" kB" />
    <ScatterChart.YAxis dataKey="ms" name="Load" unit=" ms" />
    <ScatterChart.Legend isClickable />
    <ScatterChart.Tooltip />
    <ScatterChart.Scatter
      dataKey="desktop"
      data={desktop}
      shape={shape}
      variant={variant}
      isClickable
    />
    <ScatterChart.Scatter dataKey="mobile" data={mobile} shape="cross" isClickable />
  </ScatterChart>
</div>
```

## Example — bubbles

```tsx
import { ScatterChart, type ChartConfig } from '@misoto22/design/charts'

<ScatterChart
  title="Load time, bundle size and downloads"
  config={config}
  table={{
    rows: releases,
    rowKey: 'kb',
    columns: [
      { key: 'ms', label: 'Load (ms)' },
      { key: 'downloads', label: 'Downloads' },
    ],
  }}
>
  <ScatterChart.Grid />
  <ScatterChart.XAxis dataKey="kb" name="Bundle" unit=" kB" />
  <ScatterChart.YAxis dataKey="ms" name="Load" unit=" ms" />
  <ScatterChart.ZAxis dataKey="downloads" name="Downloads" range={[60, 900]} />
  <ScatterChart.Tooltip />
  <ScatterChart.Scatter dataKey="releases" data={releases} variant="outline" />
</ScatterChart>
```

# FunnelChart

Stages that only ever narrow.

- Group: Charts
- Import: `import { FunnelChart } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/funnel-chart/
- Related: sankey-chart, bar-chart

## When to reach for it

A signup flow, a hiring pipeline, a checkout. When the flow can SPLIT rather than only shrink, it is a SankeyChart — a funnel has one path through it by construction.

## Anatomy

- **Figure frame** (required) — ChartFigure’s <figure>, with an empty state at zero stages. There is still no loading skeleton, so that state remains the call site’s job.
- **Stages** (required) — <FunnelChart.Funnel>. The rows are drawn in the order given and never sorted, and each stage is cut from the next by a --chart-surface stroke gap pixels wide rather than by a transparent gap, so the stages still touch.
- **Stage labels** — <FunnelChart.Label>, positioned right by default. Its dataKey defaults to the NAME field, not the value — printing the numbers means pointing it at the value key yourself.
- **Tooltip** — <FunnelChart.Tooltip>, heading suppressed and cursor off. There is no axis here for a crosshair to run along.
- **Hidden data table** — The sr-only table, one row per stage. It is the only exact reading this form offers, because a funnel has no axis and no ticks anywhere on it.

## Best practices

### Do

- Point <FunnelChart.Label> at the value field. With no dataKey it prints the stage NAME, which the reader already has, and the number — the one thing the taper cannot be read for — goes unprinted.
- Order the rows widest first yourself. The component draws them in the order it is handed and does not sort, so a stage out of place renders a funnel that widens, which a reader will read as a data error.
- Keep variant="stepped" unless the stages are also a sequence of kinds. ramp walks the series ramp stage by stage, which encodes the drop a second time when the taper has already said it.

### Don’t

- Do not use it for a flow that splits. A funnel has one path through it by construction; where a stage divides into two outcomes the honest form is a SankeyChart, which can draw both branches.
- Do not read the fall-off off the shape. The taper is a ratio between neighbours and the eye reads the enclosed AREA, so a shallow drop is exaggerated and a steep one flattened, with no axis anywhere to check it against.

## Accessibility

- title is required; the stages are also rendered as a visually hidden table.
- The taper encodes a ratio between neighbouring stages and the eye reads the enclosed area, so a funnel exaggerates a shallow drop. Compose a Label to print the numbers — that is the relief.
- The default variant holds one fill for every stage and lets the shape carry the drop. A ramp that also darkens each stage encodes the same fact twice.

## FunnelChart

Stages that only ever narrow — a signup flow, a hiring pipeline, a checkout. The caveat is the same one every funnel has: the taper encodes a RATIO between neighbouring stages, and the eye reads the enclosed area, so a funnel exaggerates a shallow drop and flattens a steep one. Where the exact fall-off is the point, put the percentages on the stages — `<Funnel.Label>` does — or use a `<BarChart>`, which encodes each stage on one honest scale. Reach for `<SankeyChart>` instead when the flow can SPLIT rather than only shrink: a funnel has one path through it by construction.

### Props

- `config` (required) — `ChartConfig`. Stage names → their label and paint. Keys must match the `nameKey` values.
- `data` (required) — `TData[]`. The stages, widest first. Order is the funnel; it is not sorted for you.
- `dataKey` (required) — `keyof TData & string`. The row field holding each stage's number.
- `nameKey` (required) — `keyof TData & string`. The row field naming each stage.
- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `children` (required) — `ReactNode`. The composed parts — `<Funnel>`, `<Tooltip>`.
- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
- `chartProps` — `ComponentProps<typeof RechartsFunnelChart>`. Escape hatch onto the raw Recharts chart element.
- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. `false` keeps the empty plot, for a chart whose emptiness is itself the reading.

## Example — default

```tsx
import { FunnelChart, type ChartConfig } from '@misoto22/design/charts'

<FunnelChart
  title="Signup funnel"
  config={config}
  data={stages}
  dataKey="people"
  nameKey="stage"
>
  <FunnelChart.Funnel>
    <FunnelChart.Label />
  </FunnelChart.Funnel>
  <FunnelChart.Tooltip />
</FunnelChart>
```

## Example — variant

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'
import { FunnelChart, type ChartConfig, type FunnelVariant } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-4">
  <ToggleGroup
    type="single"
    value={variant}
    onValueChange={(next) => next && setVariant(next as FunnelVariant)}
    aria-label="Stage fill"
  >
    {VARIANTS.map((option) => (
      <ToggleGroupItem key={option} value={option}>
        {option}
      </ToggleGroupItem>
    ))}
  </ToggleGroup>

  <FunnelChart
    title={`Signup funnel — ${variant}`}
    config={config}
    data={stages}
    dataKey="people"
    nameKey="stage"
  >
    <FunnelChart.Funnel variant={variant} gap={3}>
      <FunnelChart.Label dataKey="people" position="center" />
    </FunnelChart.Funnel>
    <FunnelChart.Tooltip />
  </FunnelChart>
</div>
```

## Example — stage to stage rates

```tsx
import { FunnelChart, type ChartConfig } from '@misoto22/design/charts'

<FunnelChart
  title="Signup funnel, stage to stage"
  showTitle
  description="Each stage as a share of the one above it"
  config={config}
  data={stages}
  dataKey="people"
  nameKey="stage"
>
  <FunnelChart.Funnel>
    <FunnelChart.Label position="center" />
    <FunnelChart.Label dataKey="kept" position="right" />
  </FunnelChart.Funnel>
  <FunnelChart.Tooltip />
</FunnelChart>
```

# TreemapChart

Part of a whole, when the whole has too many parts for a pie — and the parts nest.

- Group: Charts
- Import: `import { TreemapChart } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/treemap-chart/
- Related: pie-chart, bar-chart

## When to reach for it

Fifty items where a pie fails at six. Under a dozen items with a ranking to read, a BarChart’s length is the more precise encoding.

## Anatomy

- **Figure frame** (required) — ChartFigure’s <figure>, named by title, wrapping one ChartContainer.
- **Tiles** (required) — The root’s own tile renderer. The gap between tiles is a 2px --chart-surface STROKE rather than a smaller rect, so the tiles still tile — a treemap whose parts do not touch stops reading as a partition of one whole.
- **Tile labels** — showLabels, on by default, but a tile is only labelled when it is wider than 56px and taller than 26px. Below that the name is dropped rather than clipped, so the long tail is unlabelled by design.
- **Tooltip** — <TreemapChart.Tooltip>, keyed on the tile name. It is doing more work here than elsewhere: it is the only way to name a tile too small to carry its own label.
- **Hidden data table** (required) — The sr-only table lists the LEAVES, each with the path that names it. A nested tree read row by row is not something anyone can follow, so the hierarchy is flattened into the row header instead.
- **Paint** — variant="ramp" walks --series-1 to --series-8 by tile INDEX; variant="nested" steps by DEPTH instead, which is the right encoding once the question is what is inside what.

## Best practices

### Do

- Feed it non-negative values that sum to something the reader recognises as the whole. Area is the encoding, an area cannot be negative, and a leaf at zero or below is laid out at zero width and dropped from the picture — the hidden table prints it as “not drawn” rather than letting the two views disagree about how many leaves there are.
- Compose <TreemapChart.Tooltip> whenever there is a tail. Anything under 56 by 26 pixels carries no label at all, and on a fifty-item treemap that is most of it.
- Switch to variant="nested" once the tree has a second level. ramp keys the fill off the tile index, so it separates siblings and says nothing at all about depth.

### Don’t

- Do not read the ramp as a key. The slot is index modulo eight, so tile one and tile nine are painted identically — the fill here is separation, not identity, and the picture will not correct a reader who assumes otherwise.
- Do not reach for it to rank a dozen items. A bar’s length is read far more precisely than a rectangle’s area, and the squarify layout deliberately does not order tiles by value alone, so a reader cannot even scan them in order.

## Accessibility

- title is required. The table view lists the LEAVES with the path that names them: a nested tree read row by row is not something anyone can follow.
- Area is the encoding, so the data must be non-negative and must sum to something the reader recognises as the whole.
- The gap between tiles is a surface-coloured stroke rather than a smaller rect — a treemap whose parts do not touch stops reading as a partition.

## TreemapChart

Part of a whole, when the whole has too many parts for a pie — and the parts nest. A treemap encodes value as AREA, which the eye reads worse than length but far better than angle, and it is the only form here that stays readable at fifty items. Two rules make it honest: no negative values (an area cannot be negative), and the tiles have to sum to something a reader recognises as the whole. Reach for `<BarChart>` when there are under a dozen items and the ranking matters — a bar's length is the more precise encoding, and a treemap's layout deliberately does not order its tiles by value alone.

### Props

- `config` — `ChartConfig` default `{}`. Tile names → their label and paint. Optional: the ramp covers unnamed tiles.
- `data` (required) — `TreemapNode[]`. The tree. One level is a flat set of tiles; two is a nested treemap.
- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
- `variant` — `TreemapVariant` default `'ramp'`.
- `dataKey` — `string` default `'size'`. The leaf field holding each tile's number.
- `aspectRatio` — `number` default `4 / 3`. How square the tiles are pushed to be. Recharts' own squarify parameter.
- `showLabels` — `boolean` default `true`. Prints each tile's name on it, where the tile is big enough to hold it.
- `children` — `ReactNode`. The hover panel.
- `chartProps` — `TreemapExtras`.
- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. `false` keeps the empty plot, for a chart whose emptiness is itself the reading.

## Example — default

```tsx
import { TreemapChart } from '@misoto22/design/charts'

<TreemapChart title="Bundle size by package" data={packages} showLabels>
  <TreemapChart.Tooltip />
</TreemapChart>
```

## Example — nested

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'
import { TreemapChart, type TreemapVariant } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-4">
  <ToggleGroup
    type="single"
    value={variant}
    onValueChange={(next) => next && setVariant(next as TreemapVariant)}
    aria-label="Tile fill"
  >
    {VARIANTS.map((option) => (
      <ToggleGroupItem key={option} value={option}>
        {option}
      </ToggleGroupItem>
    ))}
  </ToggleGroup>

  <TreemapChart
    title={`Bundle size by group — ${variant}`}
    data={tree}
    variant={variant}
    showLabels
  >
    <TreemapChart.Tooltip />
  </TreemapChart>
</div>
```

## Example — many small tiles

```tsx
import { TreemapChart, type TreemapNode } from '@misoto22/design/charts'

<TreemapChart
  title="Route payload by file"
  showTitle
  description="Kilobytes, gzipped"
  data={files}
  dataKey="bytes"
  showLabels
>
  <TreemapChart.Tooltip />
</TreemapChart>
```

# BoxPlot

The spread of a measurement, per category.

- Group: Charts
- Import: `import { BoxPlot } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/box-plot/
- Related: histogram, scatter-chart

## When to reach for it

How variable is this, across six things at once. When the shape of ONE distribution is the question it wants a Histogram; when there are few enough observations to draw them all, a ScatterChart.

## Anatomy

- **Figure frame** (required) — ChartFigure’s <figure>, with an empty state when no category survives resolving. empty={false} keeps the axes for a chart whose emptiness is itself the reading.
- **Boxes** (required) — <BoxPlot.Boxes>: one range bar per category spanning min to max, entirely unpainted, with the glyph drawn over it. Recharts supplies the category band and the scale; the box, the median rule, the whiskers and the outlier dots are the package’s own.
- **Value axis** — <BoxPlot.YAxis>, and it is deliberately NOT anchored at zero — a box plot compares distributions, and dragging the domain to zero to be honest about bar length flattens every box into the same band of pixels. The honesty it owes is a labelled axis, which it has.
- **Notch** — notch pinches the box in at the median by 1.58 times IQR over the square root of n — a confidence interval drawn inside the shape it belongs to. It needs count on every box; a box without one is drawn square and says nothing about it.
- **Outlier dots** — showOutliers, on by default. Points past Tukey’s 1.5 IQR fences are drawn one dot each, and the whiskers then stop at the most extreme observation still INSIDE the fence rather than at the fence itself, so no whisker claims a reading the data does not contain.
- **Hidden data table** (required) — The sr-only table carries all five numbers per category plus the outlier count, so the figure is fully readable without seeing the glyph.

## Best practices

### Do

- Carry count on every box. A box over six observations and a box over six thousand are drawn identically, and count is also what a notch reads — without it, notch is accepted and quietly does nothing.
- Say which quantile rule produced a pre-computed summary. This component uses R type 7 when it summarises raw values, and on [1, 2, 3, 4] that puts the lower quartile at 1.75 where the median-of-the-lower-half rule puts it at 1.5 — the same data under two rules is two different pictures.
- Hand it the raw values rather than a summary when you have them. One pass applies Tukey’s fences, splits the outliers out and fills count in, so the five numbers and the dots cannot drift apart.

### Don’t

- A box cannot tell one hump from two. A latency series with a cache path and a database path in it draws exactly the box a smooth distribution centred in the same place draws, and the middle of that box is a value almost nothing takes. When the SHAPE is the question it is a Histogram.
- A category whose values array is empty is dropped outright — no box, no tick, no table row — because summarising it yields nothing to draw. The chart renders six boxes where seven were asked for and says nothing about the seventh.
- One observation draws a box with no box: q1, the median and q3 are the same number, the IQR is zero, and the glyph collapses to a single rule. It is not an error and it is not a distribution, so guard it at the call site.

## Accessibility

- A box is five numbers, and five numbers cannot tell one hump from two. A bimodal distribution draws exactly the same box as a smooth one centred in the same place — the component says so in its own description rather than in a footnote.
- It also hides sample size: a box over six points and a box over six thousand are drawn identically. Carry count, and turn on notched whenever medians are being compared.
- Raw values are summarised with Tukey’s fences, which is stated on the page rather than assumed — a different fence rule draws different outliers from the same data.
- The hidden data table carries all five numbers per category, so the figure is readable without seeing the glyph.

## BoxPlot

The spread of a measurement, per category — median, middle half, reach, and the points that sit outside it. The form to reach for when the question is "how variable is this", and the one that answers it in a tenth of the ink a histogram per category would take. Six response-time distributions fit across one screen as six boxes; as six histograms they do not fit at all. **What a box plot hides is multimodality.** A box is five numbers, and five numbers cannot tell a single hump from two. A bimodal distribution — a fast cache path and a slow database path, two cohorts inside one average — draws exactly the same box as a smooth one centred in the same place, and the reader has no way to tell from the picture that the middle of the box is a value almost nothing takes. It also hides sample size: a box over six points and a box over six thousand are drawn identically, which is why `count` is worth carrying and why a notch, which does read `count`, is worth turning on when medians are being compared. When the SHAPE of one distribution is the question, reach for `<Histogram>`; when there are few enough observations to draw them all, reach for `<ScatterChart>` and plot the points. Recharts earns its place here: the boxes need a shared value axis with real ticks, a category axis, a grid and a tooltip, which is most of a cartesian chart. What it does not have is a box mark, so each box is drawn as a custom shape over a range bar — the bar supplies the category band and the scale, and the glyph inside it is ours.

### Props

- `config` — `ChartConfig` default `DEFAULT_CONFIG`. The single series — its label and its paint. Only the FIRST entry is read; a box plot has one measurement and as many categories as it has boxes.
- `data` (required) — `BoxPlotDatum[]`. One entry per category, as raw observations or as a summary.
- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, and `<BoxPlot.Boxes>`.
- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
- `chartProps` — `ComponentProps<typeof RechartsBarChart>`. Escape hatch onto the raw Recharts chart element.
- `orientation` — `BoxPlotOrientation` default `'vertical'`. Which way the boxes run. Reach for `horizontal` when the category names are long enough to need rotating under a column.
- `formatValue` — `(value: number) => string` default `defaultTick`. Formats every number the chart prints — ticks, tooltip, table.
- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. `false` keeps the axes, for a chart whose emptiness is itself the reading.

## Example — default

```tsx
import { BoxPlot } from '@misoto22/design/charts'

<BoxPlot
  title="Response time by region"
  showTitle
  description="One box per edge location, 24 hours"
  data={data}
>
  <BoxPlot.Grid />
  <BoxPlot.XAxis />
  <BoxPlot.YAxis label="ms" />
  <BoxPlot.Tooltip />
  <BoxPlot.Boxes />
</BoxPlot>
```

## Example — orientation

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'
import { BoxPlot, type BoxPlotOrientation } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-4">
  <ToggleGroup
    type="single"
    value={orientation}
    onValueChange={(next) => next && setOrientation(next as BoxPlotOrientation)}
    aria-label="Orientation"
  >
    {ORIENTATIONS.map((option) => (
      <ToggleGroupItem key={option} value={option}>
        {option}
      </ToggleGroupItem>
    ))}
  </ToggleGroup>

  <BoxPlot title="Response time by region" data={data} orientation={orientation}>
    <BoxPlot.Grid />
    <BoxPlot.XAxis />
    <BoxPlot.YAxis />
    <BoxPlot.Tooltip />
    <BoxPlot.Boxes />
  </BoxPlot>
</div>
```

## Example — notched

```tsx
import { BoxPlot } from '@misoto22/design/charts'

<BoxPlot
  title="Checkout latency by variant"
  showTitle
  description="Notch width falls with the square root of the sample"
  data={data}
>
  <BoxPlot.Grid />
  <BoxPlot.XAxis />
  <BoxPlot.YAxis label="ms" />
  <BoxPlot.Tooltip />
  <BoxPlot.Boxes notch />
</BoxPlot>
```

# Histogram

The shape of one distribution.

- Group: Charts
- Import: `import { Histogram } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/histogram/
- Related: box-plot, bar-chart

## When to reach for it

A single distribution has to be understood — two clusters, a hard floor, a pile-up at a timeout. Several distributions side by side want a BoxPlot.

## Anatomy

- **Figure frame** (required) — ChartFigure’s <figure>, with an empty state when no bucket survives binning — which is what zero finite observations produces.
- **Bars** (required) — <Histogram.Bars>, each drawn from its bucket’s own two edges rather than placed in an equal category slot, which is what lets an uneven bucket be as wide as it really is. radius is 0 by default, unlike BarChart’s: a rounded corner draws a gap between two buckets that touch.
- **Measured axis** (required) — <Histogram.XAxis>, numeric, running from the first bucket’s lower edge to the last one’s upper edge.
- **Count axis** — <Histogram.YAxis>. Under mode="frequency" it is a count; under mode="density" it is count over n times width, and the bars then enclose an area of one.
- **Binning rule** — Not a mark on screen and the most consequential part of the figure: bins takes a bucket count or the explicit edges, and the default is Freedman-Diaconis capped at 200 buckets, falling back to Sturges when the interquartile range is zero. Explicit edges are also a RANGE — an observation outside the first and last has no bucket, and is counted into the tooltip’s share and into a Below or Above row of the table rather than dropped.
- **Hidden data table** — The sr-only table prints each bucket’s two edges as its row header and its count beside them — the only exact reading a binned chart can offer, since every bar stands for a range rather than for a value. Observations outside explicit edges get their own Below and Above rows, because they have no bar anywhere.

## Best practices

### Do

- Name the binning rule on the page. The same numbers cut into eight buckets and into eighty are two different pictures, and a gap between two humps can be created or erased by moving one edge — so look at more than one width before believing a feature.
- Set mode="density" whenever the buckets are uneven. Under frequency a bucket twice as wide stands twice as tall at the same underlying rate, which is the trap pre-counted buckets from a metrics backend walk straight into.
- Give values or data, never both. data wins when both arrive, so the values array is then binned by nothing and drawn by nothing, with no warning anywhere.

### Don’t

- Do not read the tooltip’s share as a share of the bars. It is a share of the SAMPLE, so a set of buckets summing to 96% is telling you the other 4% fell outside your own edges — which is the one reading a share taken over the drawn buckets could never give, because it always sums to 100.
- Do not use it to compare several distributions. Two histograms overlaid occlude each other and six side by side do not fit; that is a BoxPlot, which spends a tenth of the ink per distribution.
- Do not assume the automatic rule kept the resolution you asked for. Freedman-Diaconis divides by the interquartile range, so a tight middle with a long tail asks for tens of thousands of sub-pixel bars — the 200-bucket cap turns that into a coarse histogram rather than a hung tab, and a coarse histogram is a different picture.
- Do not read a single-value distribution as a shape. Every observation on one number still draws: the edges become that value plus and minus a half, and the result is one honest bar that is not a distribution.

## Accessibility

- The shape is a property of the bin width, not only of the data: the same numbers cut into eight buckets and into eighty are two different pictures. The rule that drew it — Freedman–Diaconis by default — is named on the page.
- The x axis is numeric and every bar is drawn from its own two edges, so an uneven bucket is as wide as it really is rather than flattened into an equal slot.
- mode="density" corrects the trap uneven buckets create: under frequency a bucket twice as wide stands twice as tall at the same underlying rate.
- The hidden data table prints each bucket’s two edges and its count, which is the only exact reading a binned chart can offer.

## Histogram

The shape of one distribution — where the mass sits, how it leans, whether there is more than one hump in it. The form that answers what a `<BoxPlot>` structurally cannot: two clusters, a hard floor, a pile-up at a timeout value. Reach for the box plot when several distributions have to be compared side by side, and for this one when a single distribution has to be understood. **A histogram's shape is a property of its bin width, not only of its data.** The same numbers cut into eight buckets and into eighty are two different pictures, and a gap between two humps can be created or erased by moving a bin edge. That is not a defect to be fixed, it is what binning IS, and the defence is to say which rule drew the picture — the default here is Freedman–Diaconis — and to look at more than one width before believing a feature. Uneven buckets add a second trap: under `frequency` a bucket twice as wide stands twice as tall at the same underlying rate, which is what `mode="density"` exists to correct. Recharts earns its place here for the axes, the grid and the tooltip, but not for the bars: a bar chart's bars are positioned by CATEGORY and a histogram's are positioned and SIZED by a continuous measurement. So the x axis is numeric and each bar is drawn from its own two edges — which is what lets an uneven bucket be as wide as it really is instead of being flattened into an equal slot beside its neighbours.

### Props

- `config` — `ChartConfig` default `DEFAULT_CONFIG`. The single series — its label and its paint. Only the FIRST entry is read; a histogram has one distribution and as many bars as it has buckets.
- `values` — `number[]`. The raw observations, in any order. Binned for you by `bins`. Give this OR `data`, not both — `data` wins if both arrive.
- `data` — `HistogramBin[]`. Buckets that were counted somewhere else — by a database, by a sketch, by a metrics backend that only ever ships histograms. Uneven bucket widths are drawn at their real widths, which is the whole reason this takes edges rather than labels. Set `mode="density"` when they are uneven, or the wide buckets will read as tall ones.
- `bins` — `number | number[]`. How to cut `values` up: a number of equal-width bins, or the explicit edges. Defaults to Freedman–Diaconis (`2 × IQR × n^(-1/3)`), falling back to Sturges when the interquartile range is zero. Explicit edges are a RANGE as well as a set of buckets: an observation outside the first and last edge has no bucket to fall in. It is counted anyway — into the tooltip's share-of-total, and into a "Below" or "Above" row in the table — so a tail your edges cut off is still somewhere a reader can find it.
- `mode` — `HistogramMode` default `'frequency'`. What the bar heights mean. `frequency` is the count in each bucket and is what a reader assumes. `density` is `count / (n × bin width)`, so the total area is 1 — which is what makes two histograms of different sample sizes comparable, and what makes uneven buckets honest.
- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, and `<Histogram.Bars>`.
- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
- `chartProps` — `ComponentProps<typeof RechartsBarChart>`. Escape hatch onto the raw Recharts chart element.
- `formatValue` — `(value: number) => string` default `defaultTick`. Formats the measured values — bin edges, ticks, the tooltip's heading.
- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. `false` keeps the axes, for a chart whose emptiness is itself the reading.

## Example — default

```tsx
import { Histogram } from '@misoto22/design/charts'

<Histogram
  title="Request duration"
  showTitle
  description="Binned by Freedman–Diaconis"
  values={samples}
>
  <Histogram.Grid />
  <Histogram.XAxis label="ms" />
  <Histogram.YAxis />
  <Histogram.Tooltip />
  <Histogram.Bars />
</Histogram>
```

## Example — bin width

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'
import { Histogram } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-4">
  <ToggleGroup
    type="single"
    value={choice}
    onValueChange={(next) => next && setChoice(next as (typeof WIDTHS)[number])}
    aria-label="Bin count"
  >
    {WIDTHS.map((option) => (
      <ToggleGroupItem key={option} value={option}>
        {option === 'auto' ? 'auto' : `${option} bins`}
      </ToggleGroupItem>
    ))}
  </ToggleGroup>

  <Histogram
    title={`Request duration — ${choice === 'auto' ? 'Freedman–Diaconis' : `${choice} bins`}`}
    values={samples}
    bins={choice === 'auto' ? undefined : Number(choice)}
  >
    <Histogram.Grid />
    <Histogram.XAxis label="ms" />
    <Histogram.YAxis />
    <Histogram.Tooltip />
    <Histogram.Bars />
  </Histogram>
</div>
```

## Example — density

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'
import { Histogram, type HistogramBin, type HistogramMode } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-4">
  <ToggleGroup
    type="single"
    value={mode}
    onValueChange={(next) => next && setMode(next as HistogramMode)}
    aria-label="Bar height"
  >
    {MODES.map((option) => (
      <ToggleGroupItem key={option} value={option}>
        {option}
      </ToggleGroupItem>
    ))}
  </ToggleGroup>

  <Histogram title={`Request duration — ${mode}`} data={buckets} mode={mode}>
    <Histogram.Grid />
    <Histogram.XAxis label="ms" />
    <Histogram.YAxis />
    <Histogram.Tooltip />
    <Histogram.Bars />
  </Histogram>
</div>
```

# WaterfallChart

How a total got from one figure to another.

- Group: Charts
- Import: `import { WaterfallChart } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/waterfall-chart/
- Related: bar-chart, funnel-chart

## When to reach for it

“Why did this change”, where the contributions can be negative. A pie cannot hold a negative slice; a BarChart is right when the parts need not add up to the gap between two totals.

## Anatomy

- **Figure frame** (required) — ChartFigure’s <figure>, with an empty state at zero steps. description is where the ordering caveat goes, and it is sr-only until showTitle is set.
- **Steps** (required) — <WaterfallChart.Bars>: one floating range bar per step, running from the previous total to the new one, with a custom shape over it. Increases and totals take the solid series fill, decreases the 45 degree hatch, so direction survives greyscale and forced colours.
- **Connectors** — connectors, on by default, joining each bar’s closing edge to where the next one starts. Without them a waterfall is a row of bars floating at unrelated heights and the reader has to reconstruct the cascade.
- **Zero baseline** (required) — A reference line at zero that <WaterfallChart.Bars> draws itself. It is what the total bars stand on, and a waterfall with no visible zero asks the reader to take every floating bar on trust.
- **Step labels** — showValues, and it is OFF by default. It prints each step’s signed change beside its bar — worth more here than anywhere else, because an intermediate bar has no baseline under it and its length is the one thing the axis cannot give back.
- **Hidden data table** — The sr-only table carries the CHANGE and the RUNNING TOTAL per step, which is exactly the pair the picture encodes as a length and a position.

## Best practices

### Do

- Turn showValues on. It is off by default and it is the relief for this form’s central weakness: an intermediate bar floats, so a reader can see that a step was small and cannot see how small.
- Leave value off the closing total step. Omitted, it is computed from the deltas above it; typed by hand it can disagree with them, and the chart will draw the disagreement without saying a word.
- Say in description when the step order is editorial, and pass showTitle so the sentence is actually printed. The connectors draw the steps as a sequence and most breakdowns are not one — churn and expansion in the same month are simultaneous — and a reader takes the leftmost bar as the first cause.

### Don’t

- Do not net two opposing movements into one step. A bar reading minus twenty that is really plus one hundred and eighty against minus two hundred is drawn exactly like a quiet month, and showing what moved is the entire purpose of the form.
- Do not compare an intermediate bar with a total bar by eye. Only the totals sit on the zero line; everything between them is a length at an arbitrary height, so a small step high in the cascade and a large one near zero are not on comparable ground.
- Do not reach for a pie when the contributions are signed. This is the form that exists because a pie cannot hold a negative slice — and a BarChart is the right one instead when the parts need not add up to the gap between two totals.

## Accessibility

- The connectors draw the steps as a sequence, and most breakdowns are not sequential — churn and expansion in the same month are simultaneous, and a reader takes the leftmost bar as the first cause. Where the order is arbitrary, say so in description.
- Intermediate bars are floating lengths read against no baseline, so a small step high up the cascade is hard to compare with a large one near zero. Total bars sit on the axis and are the only ones a reader can read absolutely.
- Direction is carried by the label’s sign and the bar’s texture as well as its position, so the reading survives greyscale and forced colours.
- A closing bar with no value is computed from the deltas, which keeps the arithmetic in the data rather than in the caller’s head.

## WaterfallChart

How a total got from one figure to another — an opening balance, the signed contributions that moved it, and where it closed. The form for "why did this change", which a pair of bars cannot answer and a pie chart answers wrongly, because contributions can be NEGATIVE and a slice cannot. Reach for `<BarChart>` when the parts do not have to add up to the gap between two totals, and for `<FunnelChart>` when the quantity only ever shrinks. **The connectors are the claim to be careful about.** They draw the steps as a sequence — this happened, then this — and most breakdowns are not sequential at all: churn and expansion in the same month are simultaneous, and the order they are listed in is an editorial choice. The arithmetic survives any order; the STORY does not, and a reader will take the leftmost bar as the first cause. Two related traps: the intermediate bars are floating lengths read against no baseline, so a small step high up the cascade is hard to compare with a large one near zero; and any step that is itself a net of two larger opposing movements is invisible as such. Where the order is arbitrary, say so in the `description`. Recharts earns its place for the axes, grid and tooltip. Each bar is a floating range — from the running total to the new one — with a custom shape over it, because Recharts has no waterfall mark and the connectors have to be drawn from the same geometry as the bars they join.

### Props

- `config` — `ChartConfig` default `DEFAULT_CONFIG`. The single series — its label and its paint. Only the FIRST entry is read; a waterfall has one quantity and as many bars as it has steps.
- `data` (required) — `WaterfallStep[]`. The steps, in the order they are applied. Order is the arithmetic: the chart does not sort, because a different order is a different total at every intermediate bar.
- `title` (required) — `string`. What the chart shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
- `showTitle` — `boolean`. Prints the title above the plot instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `children` (required) — `ReactNode`. The composed parts — axes, grid, tooltip, and `<WaterfallChart.Bars>`.
- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
- `chartProps` — `ComponentProps<typeof RechartsBarChart>`. Escape hatch onto the raw Recharts chart element.
- `formatValue` — `(value: number) => string` default `defaultTick`. Formats every number the chart prints — ticks, labels, tooltip, table.
- `hideDataTable` — `boolean` default `false`. Drops the hidden table view. Only correct when the page prints the data itself.
- `empty` — `ChartEmptyProps | false`. What the chart shows when it has nothing to draw. `false` keeps the axes, for a chart whose emptiness is itself the reading.

## Example — default

```tsx
import { WaterfallChart, formatNumber, type WaterfallStep } from '@misoto22/design/charts'

<WaterfallChart
  title="ARR bridge, FY24 to FY25"
  showTitle
  description="Thousands of AUD. The steps are simultaneous; the order is editorial."
  data={steps}
  formatValue={formatNumber({ style: 'compact' })}
>
  <WaterfallChart.Grid />
  <WaterfallChart.XAxis />
  <WaterfallChart.YAxis />
  <WaterfallChart.Tooltip />
  <WaterfallChart.Bars showValues />
</WaterfallChart>
```

## Example — subtotals

```tsx
import { ToggleGroup, ToggleGroupItem } from '@misoto22/design'
import { WaterfallChart, formatNumber, type WaterfallStep } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-4">
  <ToggleGroup
    type="single"
    value={connectors ? 'joined' : 'loose'}
    onValueChange={(next) => next && setConnectors(next === 'joined')}
    aria-label="Connectors"
  >
    <ToggleGroupItem value="joined">connectors</ToggleGroupItem>
    <ToggleGroupItem value="loose">bars only</ToggleGroupItem>
  </ToggleGroup>

  <WaterfallChart
    title="Operating profit bridge"
    data={steps}
    formatValue={formatNumber({ style: 'compact' })}
  >
    <WaterfallChart.Grid />
    <WaterfallChart.XAxis />
    <WaterfallChart.YAxis />
    <WaterfallChart.Tooltip />
    <WaterfallChart.Bars connectors={connectors} showValues />
  </WaterfallChart>
</div>
```

## Example — against a plan

```tsx
import { WaterfallChart, formatNumber, type WaterfallStep } from '@misoto22/design/charts'

<WaterfallChart
  title="ARR bridge against plan, H1 to H2"
  showTitle
  description="Thousands of AUD. The steps are simultaneous; the order is editorial."
  data={steps}
  formatValue={formatNumber({ style: 'compact' })}
>
  <WaterfallChart.Grid />
  <WaterfallChart.XAxis />
  <WaterfallChart.YAxis label="ARR" />
  <WaterfallChart.ReferenceLine y={PLAN} label="Plan" weight="firm" />
  <WaterfallChart.Tooltip />
  <WaterfallChart.Bars showValues />
</WaterfallChart>
```

# Facet

The same chart once per group, on one shared scale.

- Group: Charts
- Import: `import { Facet } from '@misoto22/design/charts'`
- Page: https://ui.misoto22.com/components/facet/
- Related: line-chart, sparkline

## When to reach for it

Eight series overplot into a hairball in one frame. Two or three series that genuinely need comparing point-for-point still belong in one chart.

## Anatomy

- **Figure frame** (required) — ChartFigure’s <figure> around the whole grid, named by title. Its empty state has no false escape hatch, unlike a single chart’s: an empty pair of axes is at least a chart, and an empty grid is nothing.
- **Panel grid** (required) — A role="list" of <li> panels on a CSS auto-fit track. list-none strips the list role in Safari, so it is set back by hand — a grid of twelve plots that does not announce twelve items takes away the reader’s only cue for how far they have to go.
- **Panel name** — A <p> above each plot. showPanelNames={false} makes it sr-only rather than removing it, because a grid whose panels a screen reader cannot tell apart is one figure with twelve anonymous plots in it.
- **Shared domain** (required) — panel.domain, computed across the panels that survive the cap and handed to the render function. It is not applied for you: a panel that does not pass it to its own value axis has opted back into independent scales.
- **Grid-level legend and axis labels** — legend, yLabel and xLabel, printed once above and below the grid. A legend inside every panel is the same three swatches twelve times, restating what the reader learned from the first one.
- **Overflow note** — The line under a capped grid, saying how many groups were left out or folded. limit is 12 by default and nothing is ever dropped in silence.

## Best practices

### Do

- Pass panel.domain to the panel chart’s value axis. That one line is what the component is for: on independent scales a group peaking at 40 and one peaking at 4,000 draw the same shape, so the comparison is not merely lost, it is inverted — and nothing on screen says so.
- Name every plotted field in value. It is what the shared domain is measured over, so a panel that draws a series value does not mention can overflow its own axis while the rest of the grid looks correct.
- Set hideDataTable when the panel charts carry their own. Every chart in the package renders its rows as an sr-only table, so a twelve-panel grid otherwise puts thirteen tables into the accessibility tree.
- Keep sort="max" for a grid a reader scans and switch to "name" for one they look things up in. Reading order is what a reader takes as ranking, so it is a decision in either direction.

### Don’t

- overflow="fold" is not free. The folded panel is the SUM of the tail at each category and its statistics go into the shared domain, so folding twenty-eight small groups can produce one tall panel that squashes the twelve the reader came for. Use note when the tail is numerous rather than large.
- Do not turn includeZero off under bars or areas. It is on by default for the same reason a bar axis is anchored at zero — a length read against a truncated baseline overstates every difference, and a grid exists to have its differences compared.
- Do not reach for it at two or three series. Faceting buys back every individual shape and pays for it with the direct overlay, and crossovers, gaps and shares of one total are exactly what the overlay was for.

## Accessibility

- The shared domain is the default and the whole point: on independent scales a group peaking at 40 and one peaking at 4,000 draw the same shape, and the comparison the reader came for is not merely lost but inverted.
- Every panel is a figure with its own accessible name, so a screen reader walks eight named charts rather than one unnamed grid.
- Panels beyond max fold into a stated overflow rather than being dropped, and the count is printed — a grid silently missing four groups is not something a reader can detect.
- Panel order is a choice the call site makes explicitly through sort, because reading order is what a reader takes as ranking.

## Facet

The same chart repeated once per group, on one shared scale — small multiples. The answer to the question a multi-series chart stops being able to answer at around five series: eight lines in one plot is a hairball, and the reader spends their attention untangling strands instead of reading them. Splitting the same lines across eight small plots costs the direct overlay comparison and buys back every individual shape, which is almost always the better trade — this is Tufte's small multiple, and Observable Plot and Vega-Lite both treat it as a first-class operation for the same reason. Reach for a multi-series `<LineChart>` or `<AreaChart>` instead when the series really do have to be read AGAINST each other — crossovers, gaps, shares of one total — and when there are few enough of them to tell apart. Reach for this when each group has its own shape worth seeing, when the groups are many, or when the reader's question is "which of these is different". What it gets right that a hand-rolled `data.map()` does not: the panels share one domain by default. On independent scales every panel fills its own plot, so a group peaking at 40 and a group peaking at 4,000 come out the same shape — the comparison is not merely lost, it is inverted, and nothing on screen says so. `panel.domain` is that shared scale; the render function has to pass it to the panel's value axis. It also caps the grid, folds or counts the tail, and prints one legend and one axis label instead of twelve.

### Props

- `title` (required) — `string`. What the whole grid shows, in a sentence a reader could act on. Required, and announced to a screen reader even when it is not printed.
- `showTitle` — `boolean`. Prints the title above the grid instead of hiding it from sight.
- `description` — `ReactNode`. A line under the title — the unit, the window, the caveat.
- `data` (required) — `TRow[]`. Every row, across every group. The split happens here, not at the call site.
- `by` (required) — `keyof TRow & string`. The row field the data is split on. One panel per distinct value.
- `value` (required) — `(keyof TRow & string) | (keyof TRow & string)[]`. The row field, or fields, holding the numbers. This is what the shared domain is measured over and what a statistical sort reads, so it has to name every series a panel draws — a panel that plots a field this does not mention can still overflow its own axis.
- `xDataKey` — `keyof TRow & string`. The shared category field — the x axis every panel has in common. Feeds the hidden table view, and is what lets `overflow="fold"` add the tail up at each category instead of concatenating it.
- `scales` — `FacetScales` default `'shared'`. Whether every panel is drawn against one domain or against its own. `"shared"` — the default, and the entire reason this component exists. On independent scales every panel fills its own plot, so a group peaking at 40 and a group peaking at 4,000 come out the same shape, and the comparison the reader opened the grid to make is not merely hard but actively wrong. The shared domain is computed across all the panels that survive the cap and handed to each one as `panel.domain`; a panel that does not pass it to its value axis has opted back into the broken version. `"independent"` is the escape hatch for the case where the panels are not comparable — different units, different orders of magnitude that carry no relation — and where each panel's own shape is the only reading. It is never the safe answer, which is why it is not the default.
- `domain` — `[number, number]`. Pins the domain outright, ignoring the data and `scales` alike.
- `includeZero` — `boolean` default `true`. Pulls the shared domain out to include zero. On by default, and the same default Recharts applies on its own: bars and areas read against a truncated baseline overstate every difference in the grid, and a grid exists to be compared. Turn it off when the values live far from zero and the differences between them ARE the reading — temperatures, latencies, ratings out of five.
- `nice` — `boolean` default `true`. Rounds the domain out so the panels' ticks land on numbers a reader recognises. Off, a shared domain of `[0, 314]` gives ticks at 78.5.
- `sort` — `FacetSort<TRow>` default `'max'`. The panel order. Defaults to the largest peak first, because that is what makes a grid readable: eye order becomes rank order, and "which of these is the problem" is answered by position before a single axis is read. `"name"` for a grid a reader will look things up in, an explicit array of names for an order the data does not carry — stages, weekdays, severities — and a comparator over `{ name, rows, stats }` for anything else.
- `order` — `'asc' | 'desc'`. The sort direction. Omit and it follows the sort: A→Z for a name or an explicit list, biggest first for a statistic.
- `limit` — `number | false` default `12`. How many panels are drawn before the rest are dealt with. Twelve by default rather than unlimited, because the failure this prevents is silent: a `by` field with forty values renders forty plots, each one roughly a postage stamp, and nothing on the page says the grid stopped being readable. `false` lifts the cap when the call site has genuinely decided to draw them all.
- `overflow` — `FacetOverflow` default `'note'`. What happens to the groups past the cap. `"note"` — the default — draws the top N and prints a line under the grid saying how many are missing. `"fold"` adds one more panel holding the tail summed at each category, the same bargain `BarList`'s "Other" row makes: the total stays true, and one panel absorbs the long tail. Either way a capped grid says so; nothing is dropped in silence.
- `otherLabel` — `string` default `'Other'`. What the folded panel is called.
- `overflowNote` — `(info: FacetOverflowInfo) => ReactNode` default `defaultOverflowNote`. Writes the line under a capped grid. The default sentence is English; this is where a translated call site replaces it.
- `columns` — `'auto' | number` default `'auto'`. How many columns the grid holds at its widest. `"auto"` — the default — fits as many panels as `minPanelWidth` allows and reflows on its own, which is the behaviour a card, a sidebar and a full-width page all need from the same call site. A number caps the count without pinning it: the grid still drops to fewer columns when the container is narrow, rather than shrinking twelve plots to nothing.
- `minPanelWidth` — `number` default `MIN_PANEL_PX`. How narrow a panel may get before the grid drops a column, in pixels.
- `legend` — `ReactNode`. One key for the whole grid, printed above it. A legend inside every panel is the same three swatches repeated twelve times, which is ink spent restating what the reader learned from the first panel. Put `<LineChart.Legend>` in one panel and this is unnecessary; put it here and take it out of the panels.
- `yLabel` — `ReactNode`. The value axis's name, printed once above the grid instead of per panel.
- `xLabel` — `ReactNode`. The category axis's name, printed once under the grid.
- `showPanelNames` — `boolean` default `true`. Prints each panel's group name above its plot. On by default. Turning it off only hides the name — it stays in the accessibility tree, because a grid whose panels a screen reader cannot tell apart is a grid with one figure and twelve anonymous plots in it.
- `hideDataTable` — `boolean` default `false`. Drops the hidden table view of every row. Worth setting when the panels' own charts already ship theirs — each chart in the package renders its rows as a table too, so a twelve-panel grid can otherwise put thirteen tables in the accessibility tree.
- `empty` — `ChartEmptyProps`. What the grid shows when the data yields no groups at all. No `false` escape hatch, unlike a single chart's: an empty pair of axes is at least a chart, but an empty grid is nothing — there is no reading for the absence to be.
- `className` — `string`. Merged onto the figure, last, so a call site can size or space it.
- `children` (required) — `(panel: FacetPanel<TRow>) => ReactNode`. One panel, called once per group. Hand `panel.domain` to the panel chart's value axis. That single line is what the component is for; without it the panels are on independent scales and the grid is decorative.

## Example — default

```tsx
import { Facet, LineChart, type ChartConfig } from '@misoto22/design/charts'

<Facet
  title="Visitors by channel, 2026"
  data={ROWS}
  by="channel"
  value="visitors"
  xDataKey="month"
  columns={3}
  yLabel="Visitors"
  xLabel="Jan – Aug 2026"
>
  {(panel) => (
    <LineChart
      title={`${panel.name} visitors`}
      config={config}
      data={panel.rows}
      // The grid ships one table for every row, above; a table per panel
      // would put seven of them in the accessibility tree.
      hideDataTable
    >
      <LineChart.Grid />
      <LineChart.XAxis dataKey="month" interval="preserveStartEnd" />
      {/* The line that makes this a comparison rather than six pictures. */}
      <LineChart.YAxis domain={panel.domain} />
      <LineChart.Line dataKey="visitors" />
    </LineChart>
  )}
</Facet>
```

## Example — overplotted vs faceted

```tsx
import { Facet, LineChart, type ChartConfig } from '@misoto22/design/charts'

<div className="flex w-full flex-col gap-10">
  <section className="flex flex-col gap-2">
    <p className="eyebrow text-(--ink-3-aa)">Overplotted — six series, one plot</p>
    <LineChart
      title="Visitors by channel, overplotted"
      config={overplotted}
      data={WIDE}
      xDataKey="month"
    >
      <LineChart.Grid />
      <LineChart.XAxis dataKey="month" />
      <LineChart.YAxis />
      <LineChart.Legend />
      <LineChart.Tooltip />
      {Object.keys(SERIES).map((channel) => (
        <LineChart.Line key={channel} dataKey={channel} />
      ))}
    </LineChart>
  </section>

  <section className="flex flex-col gap-2">
    <p className="eyebrow text-(--ink-3-aa)">Faceted — six plots, one domain</p>
    <Facet
      title="Visitors by channel, faceted"
      data={LONG}
      by="channel"
      value="visitors"
      xDataKey="month"
      columns={3}
      yLabel="Visitors"
    >
      {(panel) => (
        <LineChart title={`${panel.name} visitors`} config={single} data={panel.rows} hideDataTable>
          <LineChart.Grid />
          <LineChart.XAxis dataKey="month" interval="preserveStartEnd" />
          <LineChart.YAxis domain={panel.domain} />
          <LineChart.Line dataKey="visitors" />
        </LineChart>
      )}
    </Facet>
  </section>
</div>
```

## Example — scale and overflow

```tsx
import { Facet, Sparkline } from '@misoto22/design/charts'

<Sparkline
  label={`${name}, eight months`}
  data={values}
  domain={domain}
  height={44}
  value={values.at(-1)?.toLocaleString()}
/>
  )
}

export function Example() {
  return (
<div className="flex w-full flex-col gap-10">
  <div className="grid gap-8 md:grid-cols-2">
    <Facet
      title="Visitors by channel, shared scale"
      showTitle
      description="scales=&quot;shared&quot; — the default"
      data={TOP_FOUR}
      by="channel"
      value="visitors"
      xDataKey="month"
      columns={1}
      hideDataTable
    >
      {(panel) => (
        <Panel
          name={panel.name}
          values={panel.rows.map((row) => row.visitors)}
          domain={panel.domain}
        />
      )}
    </Facet>

    <Facet
      title="Visitors by channel, independent scales"
      showTitle
      description="scales=&quot;independent&quot; — every panel lies about its size"
      data={TOP_FOUR}
      by="channel"
      value="visitors"
      xDataKey="month"
      scales="independent"
      columns={1}
      hideDataTable
    >
      {(panel) => (
        <Panel
          name={panel.name}
          values={panel.rows.map((row) => row.visitors)}
          domain={panel.domain}
        />
      )}
    </Facet>
  </div>

  <Facet
    title="Visitors by channel, top six"
    showTitle
    description="Fourteen channels, sorted by where each ended up"
    data={ROWS}
    by="channel"
    value="visitors"
    xDataKey="month"
    sort="last"
    limit={6}
    overflow="fold"
    columns={3}
  >
    {(panel) => (
      <Panel
        name={panel.name}
        values={panel.rows.map((row) => row.visitors)}
        domain={panel.domain}
      />
    )}
  </Facet>
</div>
```

# ArchitectureFigure

A component map: services, datastores, trust boundaries, and what talks to what.

- Group: Diagrams
- Import: `import { ArchitectureFigure } from '@misoto22/design/diagrams'`
- Page: https://ui.misoto22.com/components/architecture-figure/
- Related: dataflow-figure, diagram, diagram-canvas

## When to reach for it

Reach for it when the question is "what talks to what". If the question is "in what order", that is a workflow or a sequence; if it is "what is in this arrow", that is a data flow.

## Anatomy

- **Figure shell** (required) — The frame all five figures sit in — a serif title, the scrolling paper surface, the role="img" svg. What a map hands it is the relationship list: every connection published as "CloudFront → API: HTTPS", which is the sentence this diagram type exists to make.
- **Grid** (required) — What row and col index into: a 184 × 72 cell with 64 and 76 unit gutters, overridable per figure through spec.layout — where cellW is the pitch AND the width of the plates drawn at it. A component declaring neither row nor col flows into the next free cell, wrapping at layout.cols; pos replaces the grid entirely and puts the box at an absolute coordinate.
- **Component plate** (required) — One box per component: a sigil and an eyebrow on the top line, the name at reading size, the sublabel in mono under it. The eyebrow prints the component’s own tag when it has one and the kind word otherwise, and the box grows past a declared height rather than printing through its own bottom rule.
- **Boundary frame** — A labelled rule around the union of the boxes its wraps names, inflated by pad — 28 units by default. Solid for a region, dashed for a security-group, so where a thing runs and what may reach it are two different lines before either label is read.
- **Connections** — Lines that leave and arrive perpendicular to a face, spread across that face when several share it, each with its wording on a mask that punches the line out from under itself.
- **Key** — The kinds actually drawn, each shown with the same sigil the plates carry. legend="all" names all seven instead; legend="hidden" prints none.

## Best practices

### Do

- Build a new spec object when something changes. The model is memoised on the spec’s identity, so mutating spec.components in place leaves the same reference and the figure goes on drawing the picture it was first given — development prints DIAGRAM_SPEC_MUTATED when it catches that, and a production build prints nothing and still draws the old picture.
- Place both ends with pos when a connection carries a hand-tuned via, channelX or channelY. Those are honoured only when both endpoints were placed absolutely — on the grid they are coordinates in a space this renderer did not choose, so a route between two row/col components is dropped and re-routed.
- Drive a guided reading yourself. meta.views typechecks and no renderer reads it — a chapter is a control rather than a layout — so the chapter’s focus ids have to arrive as activeIds, which is what dims everything else and adds the "n highlighted" status line.
- Leave row and col off the components you have no opinion about. They flow into the next free cell in declaration order, wrapping at layout.cols and stepping around whatever the placed ones claimed — a component declaring neither used to mean row 0, column 0, which is one plate with the rest of them underneath it.

### Don’t

- Two components on one cell are still two plates at one coordinate, one drawn over the other: there is no second place to put the second plate. Development prints DIAGRAM_CELL_COLLISION naming both, which is the only signal — the picture is identical either way.
- A boundary silently shrinks to the components it can find. A wraps id no component declares is skipped, and a boundary whose ids are all missing draws no frame at all — a trust boundary can leave the picture while the specification still claims it.

## Accessibility

- The <svg> is role="img" with a name, so a screen reader announces a picture instead of walking two hundred <text> nodes in drawing order.
- The diagram’s content is published beside it as an ordinary list — every node with its kind, every relationship as "A → B: over HTTPS". That list is where the meaning lives for anyone not looking at the picture.
- Passing onSelectNode turns that list into real buttons, which is the keyboard’s only route to a selection: the plates inside the picture are presentational by construction.

## ArchitectureFigure

A component map: services, datastores, boundaries, and what talks to what. Takes the same JSON an archify `architecture` specification carries — `components`, `boundaries`, `connections` — and draws it in this system's own terms: paper plates on a hairline, one reversed plate for the component the diagram is about, and seven drawn sigils where archify uses seven hues. IT RENDERS ON A SERVER because every position is already in the specification. A component gives a `row` and a `col` into a grid whose cell size is either declared or defaulted, or it gives an absolute `pos` — nothing here is solved for, relaxed, or measured. So the markup is a pure function of the input, it is identical on the server and in the browser, and there is no layout shift on hydration because there is no layout to do. A component that declares NEITHER flows: it takes the next free cell in declaration order, wrapping at `layout.cols`. That is still arithmetic on numbers the specification carries rather than a solver — and the alternative was every unplaced component defaulting to row 0, column 0 and stacking into one plate. BOUNDARIES ARE DRAWN FIRST, AND DRAWN DIFFERENTLY. A `region` is where something RUNS — a VPC, a zone, a cluster — and is a solid frame. A `security-group` is what may REACH it, and is dashed. That is not decoration: an infrastructure diagram is very often read for exactly one of those two questions, and a reader should be able to tell which line answers which without reading either label.

### Props

- `spec` (required) — `ArchitectureSpec`.

Also accepts: `FigureChrome`.

## Example — default

```tsx
import { ArchitectureFigure } from '@misoto22/design/diagrams'

<ArchitectureFigure
  spec={{
    meta: { title: 'One request, end to end', subtitle: 'The edge, the service, the row it reads.' },
    components: [
      { id: 'client', type: 'external', label: 'Browser', sublabel: 'Safari / Chrome', row: 0, col: 0 },
      { id: 'edge', type: 'cloud', label: 'CloudFront', sublabel: 'CDN', row: 0, col: 1 },
      { id: 'api', type: 'backend', label: 'API', sublabel: 'FastAPI', row: 0, col: 2, tag: ':8000' },
      { id: 'cache', type: 'database', label: 'Redis', sublabel: 'read-through', row: 1, col: 2 },
      { id: 'db', type: 'database', label: 'Postgres', sublabel: 'primary', row: 0, col: 3 },
    ],
    boundaries: [{ kind: 'region', label: 'ap-southeast-2', wraps: ['api', 'cache', 'db'] }],
    connections: [
      { id: 'a', from: 'client', to: 'edge', label: 'HTTPS', variant: 'emphasis' },
      { id: 'b', from: 'edge', to: 'api' },
      { id: 'c', from: 'api', to: 'cache', label: 'read-through' },
      { id: 'd', from: 'api', to: 'db', label: 'SQL' },
    ],
    cards: [
      { dot: 'cyan', title: 'Edge', items: ['Every request is fronted by the CDN.'] },
      { dot: 'emerald', title: 'Application', items: ['Reads go through Redis first.', 'Postgres is the source of truth.'] },
    ],
  }}
/>
```

## Example — two kinds of boundary

```tsx
import { ArchitectureFigure } from '@misoto22/design/diagrams'

<ArchitectureFigure
  spec={{
    meta: { title: 'An inbound webhook', subtitle: 'Where it runs, and what is allowed to reach it.' },
    components: [
      { id: 'partner', type: 'external', label: 'Partner', sublabel: 'webhook sender', row: 0, col: 0 },
      { id: 'gateway', type: 'security', label: 'Gateway', sublabel: 'signature check', row: 0, col: 1, tag: 'mTLS' },
      { id: 'queue', type: 'messagebus', label: 'Ingest queue', sublabel: 'SQS', row: 0, col: 2 },
      { id: 'worker', type: 'backend', label: 'Worker', sublabel: 'consumer', row: 0, col: 3 },
    ],
    boundaries: [
      { kind: 'region', label: 'ap-southeast-2', wraps: ['gateway', 'queue', 'worker'], pad: 38 },
      { kind: 'security-group', label: 'Reachable only from the gateway', wraps: ['queue', 'worker'], pad: 16 },
    ],
    connections: [
      { id: 'a', from: 'partner', to: 'gateway', label: 'signed POST' },
      { id: 'b', from: 'gateway', to: 'queue', label: 'verified', variant: 'security' },
      { id: 'c', from: 'queue', to: 'worker' },
    ],
  }}
/>
```

## Example — a denser map

```tsx
import { ArchitectureFigure } from '@misoto22/design/diagrams'

<ArchitectureFigure
  spec={{
    meta: { title: 'The platform', subtitle: 'Eight services, and one path through them.' },
    layout: { gapX: 58, gapY: 58 },
    components: [
      { id: 'web', type: 'frontend', label: 'Web', sublabel: 'Next.js', row: 0, col: 0 },
      { id: 'mobile', type: 'frontend', label: 'Mobile', sublabel: 'iOS', row: 1, col: 0 },
      { id: 'gw', type: 'backend', label: 'Gateway', sublabel: 'routing', row: 0, col: 1 },
      { id: 'auth', type: 'security', label: 'Auth', sublabel: 'OIDC', row: 1, col: 1 },
      { id: 'orders', type: 'backend', label: 'Orders', sublabel: 'service', row: 0, col: 2 },
      { id: 'search', type: 'backend', label: 'Search', sublabel: 'service', row: 1, col: 2 },
      { id: 'db', type: 'database', label: 'Postgres', sublabel: 'primary', row: 0, col: 3 },
      { id: 'index', type: 'database', label: 'OpenSearch', sublabel: 'index', row: 1, col: 3 },
    ],
    connections: [
      { id: 'a', from: 'web', to: 'gw' },
      { id: 'b', from: 'mobile', to: 'gw', fromSide: 'right', toSide: 'left' },
      { id: 'c', from: 'gw', to: 'auth', label: 'verify' },
      { id: 'd', from: 'gw', to: 'orders', label: 'REST', variant: 'emphasis' },
      { id: 'e', from: 'gw', to: 'search', label: 'REST' },
      { id: 'f', from: 'orders', to: 'db', label: 'SQL', variant: 'emphasis' },
      { id: 'g', from: 'search', to: 'index', label: 'query' },
      { id: 'h', from: 'orders', to: 'index', label: 'reindex', variant: 'dashed' },
    ],
    cards: [
      { dot: 'cyan', title: 'Checkout', items: ['Gateway to Orders to Postgres carries every paid order.'] },
      { dot: 'slate', title: 'Coupling', items: ['Orders writes the index Search reads.', 'Only Orders and Search reach a datastore at all.'] },
    ],
  }}
/>
```

## Example — placed by hand

```tsx
import { ArchitectureFigure } from '@misoto22/design/diagrams'

<ArchitectureFigure
  spec={{
    meta: { title: 'Orders, with the retry drawn under the row', subtitle: 'Every box placed by hand, so the loop can be too.' },
    components: [
      { id: 'api', type: 'backend', label: 'Checkout API', sublabel: 'Fastify', pos: [40, 40] },
      { id: 'queue', type: 'messagebus', label: 'SQS orders', sublabel: 'standard queue', pos: [300, 40] },
      { id: 'worker', type: 'backend', label: 'Fulfilment worker', sublabel: 'ECS service', pos: [560, 40] },
      { id: 'dlq', type: 'messagebus', label: 'orders-dlq', sublabel: 'paged on depth > 0', pos: [820, 40] },
    ],
    connections: [
      { id: 'a', from: 'api', to: 'queue', label: 'publish' },
      { id: 'b', from: 'queue', to: 'worker', label: 'consume', variant: 'emphasis' },
      { id: 'c', from: 'worker', to: 'dlq', label: 'after 5 attempts', variant: 'dashed' },
      {
        id: 'retry',
        from: 'worker',
        to: 'queue',
        label: 'retry in 30s',
        variant: 'dashed',
        fromSide: 'bottom',
        toSide: 'bottom',
        via: [
          [652, 180],
          [392, 180],
        ],
      },
    ],
  }}
/>
```

# WorkflowFigure

A process in lanes and phases, with the main path drawn heavier than its branches.

- Group: Diagrams
- Import: `import { WorkflowFigure } from '@misoto22/design/diagrams'`
- Page: https://ui.misoto22.com/components/workflow-figure/
- Related: lifecycle-figure, sequence-figure, steps

## When to reach for it

A runbook, an approval chain, a CI pipeline — anything with an owner per step. mainPath is what turns fourteen boxes into a diagram with a subject.

## Anatomy

- **Figure shell** (required) — The same frame every figure sits in. What a process hands it is a key of LINE variants rather than of node kinds — Call, Primary path, Crosses a trust boundary, Asynchronous — because a runbook is read for its arrows and not for its boxes.
- **Lane** (required) — A 92-unit band per lane with its name set in the 118-unit gutter to its left. The band spans only what the lane actually holds, and a lane marked exception is washed rather than ruled — the one wash in the package’s diagrams, because nothing routes across it.
- **Column** (required) — What col indexes: a 168-unit column with a 58-unit gutter, the same across every lane. A node sits centred in its lane’s depth, moved off that centre line only by yOffset.
- **Phase header** — A mono caption at the x of its fromCol, over a rule drawn across the columns from fromCol to toCol — so a phase’s extent is something a reader can see rather than a field only its author knows. variant dashes that rule for security and thickens it for emphasis. A phase is an axis label, so it is set like one rather than framed.
- **Group frame** — A labelled rule around a run of columns inside ONE lane — a planning loop, an evidence path — dashed when its variant is security.
- **Main path** — mainPath, drawn as weight rather than as a mark of its own: every edge between two consecutive ids on it goes heavier whatever its own variant says.

## Best practices

### Do

- Give every node a lane that spec.lanes declares. An unknown lane id still resolves to the first lane — there is nowhere else to put the box — so a step written for the exception band is drawn in the right column, at the right size, in the wrong row, and development prints DIAGRAM_LANE_UNKNOWN naming the node.
- Write mainPath as the path in order. The heavier weight is applied to CONSECUTIVE pairs, so [intake, review, ship] emphasises intake→review and review→ship and nothing else; an id whose neighbour on the list is not the far end of a real edge changes nothing at all.
- Say what an edge MEANS with role and let the drawing follow it. async and error take the quiet dashed line, return takes an open arrowhead, and main and branch add no stroke of their own because mainPath already draws that distinction as weight. An explicit variant overrides all of it, which is what it is for.

### Don’t

- Phases partition the columns; they do not stack. Each is drawn as a rule across its own span, so two phases claiming the same columns put two rules on one line and one caption over the other — and a reader cannot tell that from one phase drawn twice.
- An empty lane is not a spacer. The band is sized from what the lane holds, so a lane with no nodes collapses to about one column beside the gutter with its name still set — and an exception lane in that state washes a strip of ground next to the figure rather than under the failure path.

## Accessibility

- Same contract as every figure: a named picture, with its nodes and relationships published as text beside it.
- The exception lane is the one washed band in the system’s diagrams, and it is still labelled — the wash is not carrying the meaning on its own.

## WorkflowFigure

A process: who does what, in what order, and where it can go wrong. Three structures stacked on one grid, and they are three because they answer three different questions a reader brings to a runbook. **Lanes** are rows and answer WHO. A lane marked `exception` is the one band that gets a wash rather than a rule, and it earns the exception to the frames-are-rules law because nothing routes across it — it IS the ground for the failure path, not a frame drawn over the happy one. **Phases** are columns across every lane and answer WHEN. Printed as captions on one header rule, because a phase is an axis label. **Groups** are frames inside a single lane and answer WHAT BELONGS TOGETHER — a planning loop, an evidence path. THE MAIN PATH IS HEAVIER, and that is the whole hierarchy. `mainPath` lists the node ids a reader should be able to follow without thinking. Every edge between two consecutive ids on it is drawn at the emphasis weight whatever its own variant says, which is the one thing that turns fourteen boxes and nineteen arrows into a diagram with a subject. An `error` role goes the other way — dashed and soft — so the exception path recedes without disappearing, and so does `async`. `branch` adds no stroke of its own: a branch is an edge the main path does not list, and that is already the difference on the page.

### Props

- `spec` (required) — `WorkflowSpec`.

Also accepts: `FigureChrome`.

## Example — default

```tsx
import { WorkflowFigure } from '@misoto22/design/diagrams'

<WorkflowFigure
  spec={{
    schema_version: 2,
    meta: { title: 'Release', subtitle: 'Green tests ship; a red deploy rolls back.' },
    lanes: [
      { id: 'ci', label: 'CI' },
      { id: 'recover', label: 'Recovery', variant: 'exception' },
    ],
    phases: [
      { id: 'verify', label: 'Verify', fromCol: 0, toCol: 1 },
      { id: 'ship', label: 'Ship', fromCol: 2, toCol: 2 },
    ],
    nodes: [
      { id: 'lint', lane: 'ci', col: 0, type: 'backend', label: 'Lint', sublabel: 'eslint' },
      { id: 'test', lane: 'ci', col: 1, type: 'backend', label: 'Tests', sublabel: 'vitest' },
      { id: 'deploy', lane: 'ci', col: 2, type: 'cloud', label: 'Deploy', sublabel: 'Cloudflare' },
      { id: 'roll', lane: 'recover', col: 2, type: 'security', label: 'Roll back', sublabel: 'previous build' },
    ],
    mainPath: ['lint', 'test', 'deploy'],
    edges: [
      { id: 'a', from: 'lint', to: 'test' },
      { id: 'b', from: 'test', to: 'deploy', label: 'green' },
      { id: 'c', from: 'deploy', to: 'roll', label: 'health check failed', role: 'error', variant: 'dashed' },
    ],
  }}
/>
```

## Example — a branch and both outcomes

```tsx
import { WorkflowFigure } from '@misoto22/design/diagrams'

<WorkflowFigure
  spec={{
    schema_version: 2,
    meta: {
      title: 'A pull request',
      subtitle: 'One gate, two ways out, and the way back in.',
      legend: { entries: { dashed: { label: 'Failed check' } } },
    },
    lanes: [
      { id: 'bot', label: 'Automation' },
      { id: 'author', label: 'Author' },
    ],
    groups: [{ id: 'gate', label: 'Merge gate', lane: 'bot', fromCol: 1, toCol: 2 }],
    nodes: [
      { id: 'open', lane: 'bot', col: 0, type: 'frontend', label: 'PR opened', sublabel: 'branch pushed' },
      { id: 'check', lane: 'bot', col: 1, type: 'backend', label: 'Checks', sublabel: 'lint and tests' },
      { id: 'merge', lane: 'bot', col: 2, type: 'cloud', label: 'Merge', sublabel: 'squash' },
      { id: 'changes', lane: 'author', col: 1, type: 'external', label: 'Changes requested', sublabel: 'review comment' },
    ],
    mainPath: ['open', 'check', 'merge'],
    edges: [
      { id: 'a', from: 'open', to: 'check' },
      { id: 'b', from: 'check', to: 'merge', label: 'all green' },
      { id: 'c', from: 'check', to: 'changes', label: 'a check failed', role: 'branch', variant: 'dashed' },
      { id: 'd', from: 'changes', to: 'check', label: 'pushed a fix', role: 'return' },
    ],
  }}
/>
```

## Example — three structures on one grid

```tsx
import { WorkflowFigure } from '@misoto22/design/diagrams'

<WorkflowFigure
  spec={{
    schema_version: 2,
    meta: { title: 'Order fulfilment', subtitle: 'Three teams, three stages, one hop nobody waits for.' },
    lanes: [
      { id: 'store', label: 'Storefront' },
      { id: 'ops', label: 'Fulfilment' },
      { id: 'finance', label: 'Finance' },
    ],
    phases: [
      { id: 'take', label: 'Take', fromCol: 0, toCol: 0 },
      { id: 'settle', label: 'Settle', fromCol: 1, toCol: 2 },
      { id: 'ship', label: 'Ship', fromCol: 3, toCol: 3 },
    ],
    groups: [{ id: 'pci', label: 'PCI scope', lane: 'finance', fromCol: 1, toCol: 2, variant: 'security' }],
    nodes: [
      { id: 'cart', lane: 'store', col: 0, type: 'frontend', label: 'Checkout', sublabel: 'web' },
      { id: 'receipt', lane: 'store', col: 2, type: 'messagebus', label: 'Receipt email', sublabel: 'queued' },
      { id: 'pick', lane: 'ops', col: 3, type: 'backend', label: 'Pick and pack', sublabel: 'warehouse' },
      { id: 'auth', lane: 'finance', col: 1, type: 'security', label: 'Authorise', sublabel: 'card network', tag: 'PCI' },
      { id: 'capture', lane: 'finance', col: 2, type: 'backend', label: 'Capture', sublabel: 'settled' },
    ],
    mainPath: ['cart', 'auth', 'capture', 'pick'],
    edges: [
      { id: 'a', from: 'cart', to: 'auth', label: 'card token' },
      { id: 'b', from: 'auth', to: 'capture', label: 'approved' },
      { id: 'c', from: 'capture', to: 'pick', label: 'paid', fromSide: 'right', toSide: 'bottom' },
      { id: 'd', from: 'capture', to: 'receipt', label: 'confirmation', role: 'async', variant: 'dashed' },
    ],
    cards: [
      { dot: 'amber', title: 'PCI scope', items: ['Only the two boxes inside the dashed frame see a card number.'] },
      { dot: 'slate', title: 'Off the path', items: ['The receipt is queued, so a slow mailer cannot hold up a shipment.'] },
    ],
  }}
/>
```

## Example — what a role draws

```tsx
import { WorkflowFigure } from '@misoto22/design/diagrams'

<WorkflowFigure
  spec={{
    schema_version: 2,
    meta: { title: 'Canary deploy', subtitle: 'One path forward, three ways off it.' },
    lanes: [
      { id: 'pipeline', label: 'Pipeline' },
      { id: 'side', label: 'Out of band' },
      { id: 'oncall', label: 'On call', variant: 'exception' },
    ],
    nodes: [
      { id: 'build', lane: 'pipeline', col: 0, type: 'backend', label: 'Build', sublabel: 'container image' },
      { id: 'canary', lane: 'pipeline', col: 1, type: 'cloud', label: 'Canary', sublabel: '5% of traffic' },
      { id: 'full', lane: 'pipeline', col: 2, type: 'cloud', label: 'Full rollout', sublabel: 'all regions' },
      { id: 'notify', lane: 'side', col: 1, type: 'messagebus', label: 'Announce', sublabel: '#deploys' },
      { id: 'page', lane: 'oncall', col: 2, type: 'security', label: 'Page the on-call', sublabel: 'PagerDuty' },
    ],
    mainPath: ['build', 'canary', 'full'],
    edges: [
      { id: 'a', from: 'build', to: 'canary', role: 'main' },
      { id: 'b', from: 'canary', to: 'full', label: 'healthy for 10m', role: 'main' },
      { id: 'c', from: 'canary', to: 'notify', label: 'posts the diff', role: 'async', variant: 'dashed' },
      { id: 'd', from: 'canary', to: 'page', label: 'errors above 2%', role: 'error', variant: 'dashed' },
      { id: 'e', from: 'page', to: 'build', label: 'previous image restored', role: 'return', variant: 'dashed' },
    ],
  }}
/>
```

# SequenceFigure

A call chain over time: who asks whom, in what order, and what comes back.

- Group: Diagrams
- Import: `import { SequenceFigure } from '@misoto22/design/diagrams'`
- Page: https://ui.misoto22.com/components/sequence-figure/
- Related: workflow-figure, architecture-figure

## When to reach for it

The only figure whose vertical axis means something. A message carries an explicit y, so two calls eight units apart happened together and two two hundred apart did not.

## Anatomy

- **Figure shell** (required) — The frame around the picture. What a trace hands it is a message list, and it is published in the order the messages array is written — which is the only ordering a reader who cannot see the axis is given.
- **Participant head** (required) — A 148-unit plate per participant at the top of its column, in the order the participants array puts them. meta.column_fit: "spread" widens every column to the widest name instead of holding the fixed width.
- **Lifeline** (required) — A hairline dropped from each head to below the last thing on the axis. A hairline and not a rule, because it is the axis: seven lifelines at message weight is seven vertical lines competing with twelve horizontal ones.
- **Message** (required) — A horizontal line at its own y, inset from both lifelines so the arrowhead lands clear of the axis, with the wording on a mask above it. A return is dashed AND takes an open head — two signals, because the reply is what a reader picks out of a dense trace.
- **Activation bar** — A narrow bar on a lifeline from one y to another: who is BUSY. It is the fact a sequence diagram carries that a list of calls does not, and one bar overlapping another is the reason to draw the picture at all.
- **Segment band** — A dashed rule across the whole figure with a mono caption on a masked patch — request, fallback, response. A caption rather than a tinted panel, because a second ground inside the figure would sit under every message label’s mask.

## Best practices

### Do

- Author the messages in ascending y. The picture reads the axis and the summary list beside it iterates the array, so a message written out of order is drawn at one point in the exchange and read aloud at another.
- Reach for meta.column_fit: "spread" when a participant’s name is longer than the fixed column. The plate wraps to two lines and ellipsises whatever still does not fit, and shortening the name to make it fit is not a repair — the name is the data.
- Space the messages by what actually happened. Nothing normalises y, so eight units between two calls reads as together and two hundred reads as a wait; an evenly spaced list is tidier and says something the trace does not.

### Don’t

- A message naming a participant that participants does not declare leaves the picture and the summary list together — there is no column to draw it between, and a text equivalent reporting a call the picture cannot show is two halves of one figure disagreeing. Development prints DIAGRAM_EDGE_DANGLING with both ends, which is now the only place that message is reported at all.
- This figure ASSERTS order. Three calls a service makes concurrently, given three y values because they had to be given something, are a picture claiming the second waited for the first — an activation bar or a segment caption is where "these overlap" belongs.

## Accessibility

- Return messages are dashed AND take an open arrowhead — two signals, because the reply is what a reader most often needs to pick out of a dense trace.
- The message list beside the picture reads in order, which is the same order the axis is drawn in.

## SequenceFigure

A call chain over time: who asks whom, in what order, and what comes back. The one diagram type here whose vertical axis MEANS something. Every other figure's y is layout; a sequence's y is time, which is why a message carries an explicit `y` rather than an index — two calls 8 units apart happened together, and two 200 apart did not, and an evenly spaced list of messages would erase that distinction while looking tidier. **Lifelines** are hairlines, not solid rules, because they are the axis rather than the content. A lifeline drawn at the weight of a message is a diagram where seven vertical lines compete with twelve horizontal ones. **Activation bars** say who is BUSY, which is the fact a sequence diagram carries that a list of calls does not — the third participant's bar overlapping the second's is the reason to draw them at all. **Segments** band the axis into phases — request, fallback, response — printed as a rule with a mono caption rather than as a tinted panel, for the same reason architecture boundaries are: a second ground inside the figure would sit under every message label's mask. A `return` message is dashed AND takes an open arrowhead. Two signals rather than one, because the reply is the thing a reader most often needs to pick out of a dense trace, and a dash alone is doing the same work as `dashed` already does for an asynchronous call.

### Props

- `spec` (required) — `SequenceSpec`.

Also accepts: `FigureChrome`.

## Example — default

```tsx
import { SequenceFigure } from '@misoto22/design/diagrams'

<SequenceFigure
  spec={{
    meta: { title: 'A cache miss', subtitle: 'The vertical axis is time, not layout.' },
    participants: [
      { id: 'web', type: 'frontend', label: 'Web app', sublabel: 'React' },
      { id: 'api', type: 'backend', label: 'API', sublabel: 'handler' },
      { id: 'cache', type: 'database', label: 'Redis' },
      { id: 'db', type: 'database', label: 'Postgres' },
    ],
    segments: [
      { from: 130, to: 250, label: 'Request' },
      { from: 260, to: 380, label: 'Fallback' },
    ],
    messages: [
      { id: 'get', from: 'web', to: 'api', y: 160, label: 'GET /me', variant: 'emphasis' },
      { id: 'read', from: 'api', to: 'cache', y: 200, label: 'read' },
      { id: 'miss', from: 'cache', to: 'api', y: 235, label: 'miss', variant: 'return' },
      { id: 'query', from: 'api', to: 'db', y: 285, label: 'select', variant: 'emphasis' },
      { id: 'rows', from: 'db', to: 'api', y: 320, label: 'rows', variant: 'return' },
      { id: 'json', from: 'api', to: 'web', y: 360, label: '200 JSON', variant: 'return' },
    ],
    activations: [
      { participant: 'api', from: 155, to: 365, type: 'backend' },
      { participant: 'cache', from: 195, to: 240, type: 'database' },
      { participant: 'db', from: 280, to: 325, type: 'database' },
    ],
  }}
/>
```

## Example — an asynchronous hop

```tsx
import { SequenceFigure } from '@misoto22/design/diagrams'

<SequenceFigure
  spec={{
    meta: {
      title: 'Webhook delivery',
      subtitle: 'A queue absorbs the retry the caller never waits for.',
      column_fit: 'spread',
    },
    participants: [
      { id: 'billing', type: 'backend', label: 'Billing', sublabel: 'invoice writer' },
      { id: 'outbox', type: 'messagebus', label: 'Outbox', sublabel: 'delivery queue' },
      { id: 'partner', type: 'external', label: 'Partner webhook endpoint', sublabel: 'customer-operated' },
    ],
    segments: [{ from: 262, to: 340, label: 'Retry' }],
    messages: [
      { id: 'enq', from: 'billing', to: 'outbox', y: 150, label: 'enqueue', variant: 'dashed' },
      { id: 'post1', from: 'outbox', to: 'partner', y: 195, label: 'POST /hooks', variant: 'security' },
      { id: 'fail', from: 'partner', to: 'outbox', y: 230, label: '503', variant: 'return' },
      { id: 'post2', from: 'outbox', to: 'partner', y: 290, label: 'attempt 2', variant: 'security' },
      { id: 'ok', from: 'partner', to: 'outbox', y: 325, label: '200', variant: 'return' },
    ],
    activations: [{ participant: 'outbox', from: 145, to: 335, type: 'messagebus' }],
  }}
/>
```

## Example — time as the axis

```tsx
import { SequenceFigure } from '@misoto22/design/diagrams'

<SequenceFigure
  spec={{
    meta: { title: 'A slow dependency', subtitle: 'Three calls in 24 units, then 186 of waiting.' },
    participants: [
      { id: 'gw', type: 'backend', label: 'Gateway' },
      { id: 'search', type: 'backend', label: 'Search' },
      { id: 'rank', type: 'backend', label: 'Ranker' },
      { id: 'vendor', type: 'external', label: 'Pricing vendor' },
    ],
    messages: [
      { id: 'q', from: 'gw', to: 'search', y: 150, label: 'query' },
      { id: 'f', from: 'gw', to: 'rank', y: 162, label: 'features' },
      { id: 'p', from: 'gw', to: 'vendor', y: 174, label: 'quote', variant: 'emphasis' },
      { id: 'hits', from: 'search', to: 'gw', y: 205, label: 'hits', variant: 'return' },
      { id: 'scores', from: 'rank', to: 'gw', y: 225, label: 'scores', variant: 'return' },
      { id: 'price', from: 'vendor', to: 'gw', y: 360, label: 'price', variant: 'return' },
    ],
    activations: [
      { participant: 'gw', from: 145, to: 368, type: 'backend' },
      { participant: 'search', from: 155, to: 210, type: 'backend' },
      { participant: 'rank', from: 167, to: 230, type: 'backend' },
      { participant: 'vendor', from: 179, to: 365, type: 'external' },
    ],
    cards: [
      { dot: 'rose', title: 'The tail', items: ['Search and Ranker both answer within 75 units of the first call.', 'The vendor holds its request open for 186.'] },
    ],
  }}
/>
```

## Example — names that do not fit

```tsx
import { SequenceFigure } from '@misoto22/design/diagrams'

<SequenceFigure
  spec={{
    meta: {
      title: 'Signing in to the dealer portal',
      subtitle: 'Every column as wide as the longest real name.',
      column_fit: 'spread',
    },
    participants: [
      { id: 'browser', type: 'frontend', label: 'Dealer portal (browser)', sublabel: 'Next.js' },
      { id: 'api', type: 'backend', label: 'dealer-portal-api', sublabel: 'Django + DRF' },
      { id: 'db', type: 'database', label: 'SQL Server 2025', sublabel: 'legacy schema' },
    ],
    messages: [
      { id: 'post', from: 'browser', to: 'api', y: 160, label: 'POST /api/v1/token/', variant: 'emphasis' },
      { id: 'lookup', from: 'api', to: 'db', y: 200, label: 'SELECT dealer WHERE email = ?' },
      { id: 'row', from: 'db', to: 'api', y: 240, label: 'one row', variant: 'return' },
      { id: 'pair', from: 'api', to: 'browser', y: 282, label: 'access + refresh', variant: 'return' },
    ],
    activations: [
      { participant: 'api', from: 168, to: 288, type: 'backend' },
      { participant: 'db', from: 196, to: 246, type: 'database' },
    ],
  }}
/>
```

# DataflowFigure

A pipeline: where data comes from, what happens to it, and who ends up with it.

- Group: Diagrams
- Import: `import { DataflowFigure } from '@misoto22/design/diagrams'`
- Page: https://ui.misoto22.com/components/dataflow-figure/
- Related: architecture-figure, lifecycle-figure

## When to reach for it

Structurally close to an architecture map, read for a different question. classification gets its own chip because a governance reviewer is looking for exactly that.

## Anatomy

- **Figure shell** (required) — The frame around the picture. What a pipeline hands it is a flow list with the classification folded in — "clickstream — PII touch" — so the fact the diagram was opened for reaches a reader who never sees the chip.
- **Stage heading** (required) — One mono caption per stage on a rule across the top. It is the axis: a node’s stage is how far along the pipeline it sits, so "has this been aggregated yet" is answered by looking up rather than by tracing arrows.
- **Node plate** (required) — One box per node, placed by stage across and row down. The row pitch leaves a clear band between two boxes in the same column, which is where a line and its wording go.
- **Flow** — A routed line with a single arrowhead, at its to end. It is the direction claim the whole figure is read for.
- **Classification chip** — classification, printed in mono under the wording rather than inside it. "clickstream" and "clickstream / PII touch" are two different facts, and only one of them is what a governance review came for.

## Best practices

### Do

- Put the governance fact in classification rather than in the label. It prints as its own chip on the line and is appended to the flow’s summary line, so it survives both a reader who is scanning the picture and one who only has the text.
- Keep stage inside the stages you declared. A node’s x is computed from its own stage index rather than looked up, so a node at stage 5 beside four stages is drawn a full column past the last heading, under no heading at all — development prints DIAGRAM_STAGE_OUT_OF_RANGE, and the summary files it under a band called outside the declared stages rather than beside the nodes the axis does label.
- Write a two-way exchange as two flows. Every line carries a head at its to end only, so one flow between a service and its cache says data moves one way, whatever the label claims about the round trip.

### Don’t

- via, channelX and channelY are never honoured here — a data-flow node is always placed by stage and row, so an author’s waypoints refer to a grid this renderer did not build. They are dropped and every line is routed from scratch: the specification still typechecks and the picture is not the one it drew.
- Watch the fan-in. Lines sharing a face are spread evenly across it, and an arrowhead is 11 user units wide against a plate about 55 units tall — so four lines into one face is where the heads meet, and the fifth and sixth arrive as one thick mark. A pipeline at that density wants splitting, not more edges.

## Accessibility

- A flow’s classification is folded into its summary line, so "clickstream — PII touch" reaches a reader who cannot see the chip.

## DataflowFigure

A pipeline: where data comes from, what happens to it, and who ends up with it. Structurally close to an architecture map and read for a completely different question, which is why it is a separate renderer rather than a preset. An architecture diagram is read for "what talks to what". A data-flow diagram is read for "what is IN this arrow" — and that question is why `classification` gets its own mono chip under the label rather than being folded into the wording. `clickstream / PII touch` and `clickstream` are two different facts, and a governance reviewer is looking for the second one. Stages are printed as column headings on a rule across the top. They are the axis of the figure: a node's `stage` is its position along the pipeline, and a reader should be able to answer "how far has this got" by looking up rather than by tracing arrows.

### Props

- `spec` (required) — `DataflowSpec`.

Also accepts: `FigureChrome`.

## Example — default

```tsx
import { DataflowFigure } from '@misoto22/design/diagrams'

<DataflowFigure
  spec={{
    meta: { title: 'Event pipeline', subtitle: 'What is in the arrow matters more than the arrow.' },
    stages: [{ label: 'Sources' }, { label: 'Gate' }, { label: 'Store' }],
    nodes: [
      { id: 'web', type: 'frontend', label: 'Web SDK', sublabel: 'browser', stage: 0, row: 0, tag: 'events' },
      { id: 'app', type: 'frontend', label: 'Mobile', sublabel: 'iOS / Android', stage: 0, row: 1, tag: 'events' },
      { id: 'gate', type: 'security', label: 'Consent gate', sublabel: 'policy filter', stage: 1, row: 0, tag: 'PII guard' },
      { id: 'wh', type: 'database', label: 'Warehouse', sublabel: 'analytics tables', stage: 2, row: 0, tag: 'curated' },
    ],
    flows: [
      { id: 'a', from: 'web', to: 'gate', label: 'clickstream', classification: 'user events', variant: 'emphasis' },
      { id: 'b', from: 'app', to: 'gate', label: 'app events', classification: 'device events' },
      { id: 'c', from: 'gate', to: 'wh', label: 'accepted', classification: 'no PII', variant: 'emphasis' },
    ],
  }}
/>
```

## Example — one source three consumers

```tsx
import { DataflowFigure } from '@misoto22/design/diagrams'

<DataflowFigure
  spec={{
    meta: { title: 'What leaves the events table', subtitle: 'One source, three consumers, three payloads.' },
    stages: [{ label: 'Source' }, { label: 'Consumers' }],
    nodes: [
      { id: 'events', type: 'database', label: 'Events table', sublabel: 'raw', stage: 0, row: 1, tag: 'PII' },
      { id: 'bi', type: 'cloud', label: 'BI dashboards', sublabel: 'internal', stage: 1, row: 0 },
      { id: 'ml', type: 'backend', label: 'Model training', sublabel: 'nightly', stage: 1, row: 1 },
      { id: 'ads', type: 'external', label: 'Ad partner', sublabel: 'third party', stage: 1, row: 2 },
    ],
    flows: [
      { id: 'a', from: 'events', to: 'bi', label: 'daily rollup', classification: 'aggregated' },
      { id: 'b', from: 'events', to: 'ml', label: 'training set', classification: 'hashed ids' },
      { id: 'c', from: 'events', to: 'ads', label: 'conversions', classification: 'no PII', variant: 'security' },
    ],
    cards: [
      { dot: 'rose', title: 'Leaving the estate', items: ['Only the ad partner sits outside the account.', 'That is the arrow a reviewer reads first.'] },
    ],
  }}
/>
```

## Example — a stage the data skips

```tsx
import { DataflowFigure } from '@misoto22/design/diagrams'

<DataflowFigure
  spec={{
    meta: { title: 'Clickstream', subtitle: 'Three stages, and one copy that skips the middle one.' },
    stages: [{ label: 'Collect' }, { label: 'Scrub' }, { label: 'Serve' }],
    nodes: [
      { id: 'sdk', type: 'frontend', label: 'Web SDK', sublabel: 'browser', stage: 0, row: 0, tag: 'raw' },
      { id: 'scrub', type: 'security', label: 'Redactor', sublabel: 'drops identifiers', stage: 1, row: 0 },
      { id: 'lake', type: 'database', label: 'Lake', sublabel: 'partitioned', stage: 2, row: 0, tag: 'curated' },
      { id: 'debug', type: 'database', label: 'Debug bucket', sublabel: '7-day TTL', stage: 2, row: 1 },
    ],
    flows: [
      { id: 'a', from: 'sdk', to: 'scrub', label: 'events', classification: 'PII' },
      { id: 'b', from: 'scrub', to: 'lake', label: 'hourly', classification: 'no PII', variant: 'emphasis' },
      { id: 'c', from: 'sdk', to: 'debug', label: 'sampled 1%', classification: 'PII', variant: 'dashed', fromSide: 'bottom', toSide: 'left' },
    ],
  }}
/>
```

## Example — what is in the arrow

```tsx
import { DataflowFigure } from '@misoto22/design/diagrams'

<DataflowFigure
  spec={{
    meta: { title: 'Card data, minimised', subtitle: 'Read for what crosses each stage, not for what talks to what.' },
    stages: [{ label: 'Collected' }, { label: 'Minimised' }, { label: 'Stored' }, { label: 'Served' }],
    nodes: [
      { id: 'checkout', type: 'frontend', label: 'Checkout form', sublabel: 'browser', stage: 0, row: 0, tag: 'raw' },
      { id: 'support', type: 'frontend', label: 'Support inbox', sublabel: 'ticket bodies', stage: 0, row: 1, tag: 'raw' },
      { id: 'vault', type: 'security', label: 'Tokeniser', sublabel: 'Vault transit', stage: 1, row: 0 },
      { id: 'wh', type: 'database', label: 'Warehouse', sublabel: 'order tables', stage: 2, row: 0 },
      { id: 'bi', type: 'backend', label: 'Dashboards', sublabel: 'finance team', stage: 3, row: 0 },
    ],
    flows: [
      { id: 'a', from: 'checkout', to: 'vault', label: 'card and email', classification: 'PII', variant: 'emphasis' },
      { id: 'b', from: 'support', to: 'vault', label: 'free text', classification: 'PII, unstructured' },
      { id: 'c', from: 'vault', to: 'wh', label: 'order rows', classification: 'tokenised, no PAN', variant: 'emphasis' },
      { id: 'd', from: 'wh', to: 'bi', label: 'daily rollup', classification: 'aggregated' },
    ],
  }}
/>
```

# LifecycleFigure

A state machine: what something can be, and what moves it between states.

- Group: Diagrams
- Import: `import { LifecycleFigure } from '@misoto22/design/diagrams'`
- Page: https://ui.misoto22.com/components/lifecycle-figure/
- Related: workflow-figure, steps

## When to reach for it

The one figure that spends colour, and it spends exactly the two tokens the system reserves for state. Every other distinction is shape, so a greyscale print keeps six of the eight.

## Anatomy

- **Figure shell** (required) — The frame around the picture. What a machine hands it is a transition list with each note folded in after an em dash, so the condition on an arrow — the timeout, the retry count — is in the text copy and not only on the line.
- **State plate** (required) — One shape per kind: a filled cap for a start, a diamond for a decision, a dashed frame for a wait, a cut corner for an external, and the two washes the system reserves for the terminals. The name is centred, step sits in the leading corner and tag along the bottom edge.
- **Main rail** — The first lane’s states, sorted by col and joined consecutively at the emphasis weight — one line per neighbouring pair the transitions do not already declare, so a spine written out in full is drawn from the transitions and a spine left implied is drawn anyway. Without it the top row reads as five unconnected boxes, because the spine of a machine is the part nobody writes down.
- **Transition** — A routed line with its label on a mask and its note in a quieter line beneath. A declared transition between two rail neighbours replaces the implicit one rather than doubling it.
- **Lane** — A rule with a mono caption above it, drawn only as far as that lane’s own states reach. A lane past the first has its columns shifted along the main rail, which is what keeps a drop out of the spine vertical rather than a dogleg.

## Best practices

### Do

- Keep the first lane for the ordered spine and nothing else. Consecutive states there are joined by the implicit rail even when no transition declares the pair, so a state parked in lane 0 for spacing invents an edge the machine does not have. A state whose lane id nothing declares is kept out of that rail and reported as DIAGRAM_LANE_UNKNOWN instead, because a typo should not be able to add an arrow.
- Count a secondary lane’s columns from the rail. Every col in a lane past the first is shifted two columns along, so col: 0 in the second lane sits under col: 2 in the first — the convention archify’s lifecycle contract already implies, restated here because it is what makes a drop land on the state it came from.
- Say whether a failure is recoverable with an edge, not with the type. type: "failure" only paints the plate; a retryable error and a terminal one are identical until a reader follows the arrows out, and the one with none is where the run ended.

### Don’t

- yOffset moves the plate and moves nothing out of its way. The lane’s rule is drawn from what that lane holds, so a negative nudge drags the rule up with the state and a large positive one drops the plate into the band below — a state needing that much room wants a column of its own rather than a push.
- The figure claims a state can be left only the ways its arrows say. A cancel that can happen from anywhere and is drawn from nowhere reads as impossible, which is a reading the picture makes and the specification never wrote — draw it, or say in the subtitle that it is not drawn.

## Accessibility

- success and failure are the only coloured marks in the package’s diagrams, and each is also a distinct plate shape — colour is never the only carrier.
- The main rail is drawn between consecutive states in the first lane even when the specification does not list those transitions, because they are the diagram’s spine rather than its exceptions.

## LifecycleFigure

A state machine: what something can BE, and what moves it. The one figure here that spends colour, and it spends exactly the two tokens this system reserves for state: `--success` on a terminal success, `--danger` on a terminal failure. Nothing else in the package is allowed those two, and a lifecycle diagram is the case they were reserved for — the whole point of the picture is which end a run came out of. The other six kinds are carried by shape, so a greyscale print loses the two outcomes' hue and keeps every other distinction: a start is a filled cap, a decision is a diamond, a wait is a dashed frame, an external is a plate with a cut corner. A RECOVERABLE FAILURE IS A FAILURE WITH A WAY BACK. `type: "failure"` says how a state is drawn; a transition OUT of it is what says whether the run is over. A retryable error and a terminal one look identical until you follow the arrows, which is correct — the difference between them is a real edge in the machine, not an adjective on a box.

### Props

- `spec` (required) — `LifecycleSpec`.

Also accepts: `FigureChrome`.

## Example — default

```tsx
import { LifecycleFigure } from '@misoto22/design/diagrams'

<LifecycleFigure
  spec={{
    meta: { title: 'A job run', subtitle: 'The only figure that spends colour, on the two outcomes.' },
    lanes: [
      { id: 'main', label: 'Phases' },
      { id: 'wait', label: 'Interruptions' },
      { id: 'exit', label: 'Terminal' },
    ],
    states: [
      { id: 'queued', type: 'start', label: 'Queued', sublabel: 'accepted', lane: 'main', col: 0, step: '01' },
      { id: 'running', type: 'active', label: 'Running', sublabel: 'tool calls', lane: 'main', col: 1, step: '02' },
      { id: 'review', type: 'decision', label: 'Review', sublabel: 'quality gate', lane: 'main', col: 2, step: '03' },
      { id: 'done', type: 'success', label: 'Completed', sublabel: 'final answer', lane: 'main', col: 3, step: '04' },
      { id: 'blocked', type: 'waiting', label: 'Blocked', sublabel: 'missing input', lane: 'wait', col: 0 },
      { id: 'failed', type: 'failure', label: 'Failed', sublabel: 'timed out', lane: 'exit', col: 0 },
    ],
    transitions: [
      { id: 'a', from: 'review', to: 'blocked', label: 'needs input' },
      { id: 'b', from: 'blocked', to: 'failed', label: 'expired', note: 'after 24h', variant: 'dashed' },
      { id: 'c', from: 'blocked', to: 'running', label: 'answered', variant: 'emphasis' },
    ],
  }}
/>
```

## Example — a decision with both ends

```tsx
import { LifecycleFigure } from '@misoto22/design/diagrams'

<LifecycleFigure
  spec={{
    meta: { title: 'Card authorisation', subtitle: 'One decision, and the two ends a run can come out of.' },
    lanes: [
      { id: 'flow', label: 'Authorisation' },
      { id: 'refuse', label: 'Refusals' },
    ],
    states: [
      { id: 'submitted', type: 'start', label: 'Submitted', sublabel: 'card token', lane: 'flow', col: 0, step: '01' },
      { id: 'risk', type: 'decision', label: 'Risk score', sublabel: 'model and rules', lane: 'flow', col: 1, step: '02' },
      { id: 'approved', type: 'success', label: 'Approved', sublabel: 'funds held', lane: 'flow', col: 2, step: '03' },
      { id: 'declined', type: 'failure', label: 'Declined', sublabel: 'no retry', lane: 'refuse', col: 0 },
    ],
    transitions: [
      { id: 'no', from: 'risk', to: 'declined', label: 'score above 90', fromSide: 'bottom', toSide: 'top' },
    ],
    cards: [
      { dot: 'emerald', title: 'Two ends', items: ['A run leaves through Approved or through Declined and nowhere else.'] },
      { dot: 'amber', title: 'The rail', items: ['Submitted to Risk score to Approved is drawn without being declared.'] },
    ],
  }}
/>
```

## Example — a failure with a way back

```tsx
import { LifecycleFigure } from '@misoto22/design/diagrams'

<LifecycleFigure
  spec={{
    meta: { title: 'A delivery attempt', subtitle: 'Two failures on the same plate; one of them is not the end.' },
    lanes: [
      { id: 'run', label: 'Delivery' },
      { id: 'faults', label: 'Faults' },
    ],
    states: [
      { id: 'queued', type: 'start', label: 'Queued', sublabel: 'accepted', lane: 'run', col: 0, step: '01' },
      { id: 'sending', type: 'active', label: 'Sending', sublabel: 'attempt n', lane: 'run', col: 1, step: '02', tag: 'HTTP' },
      { id: 'delivered', type: 'success', label: 'Delivered', sublabel: '2xx', lane: 'run', col: 3, step: '03' },
      { id: 'timeout', type: 'failure', label: 'Timed out', sublabel: 'no response', lane: 'faults', col: 0 },
      { id: 'rejected', type: 'failure', label: 'Rejected', sublabel: 'no retry', lane: 'faults', col: 1 },
    ],
    transitions: [
      { id: 'slow', from: 'sending', to: 'timeout', label: 'no reply in 10s', toSide: 'top' },
      { id: 'retry', from: 'timeout', to: 'sending', label: 'retry', note: 'up to 5 times', variant: 'emphasis', fromSide: 'left', toSide: 'bottom' },
      { id: 'bad', from: 'sending', to: 'rejected', label: '400 invalid body', fromSide: 'bottom', toSide: 'top' },
    ],
    cards: [
      { dot: 'amber', title: 'Same plate, different run', items: ['Timed out and Rejected are drawn identically.', 'Only the arrow leaving Timed out says the run continues.'] },
    ],
  }}
/>
```

## Example — the implicit rail

```tsx
import { LifecycleFigure } from '@misoto22/design/diagrams'

<LifecycleFigure
  spec={{
    meta: { title: 'An article, from draft to live', subtitle: 'The spine is drawn; only the departures are written.' },
    lanes: [
      { id: 'main', label: 'Review' },
      { id: 'aside', label: 'Off the rail' },
    ],
    states: [
      { id: 'draft', type: 'start', label: 'Draft', sublabel: 'author only', lane: 'main', col: 0, step: '01' },
      { id: 'review', type: 'active', label: 'In review', sublabel: 'two readers', lane: 'main', col: 1, step: '02' },
      { id: 'decide', type: 'decision', label: 'Accept?', sublabel: 'editor', lane: 'main', col: 2, step: '03' },
      { id: 'live', type: 'success', label: 'Published', sublabel: 'on the site', lane: 'main', col: 3, step: '04' },
      { id: 'pulled', type: 'neutral', label: 'Withdrawn', sublabel: 'by the author', lane: 'aside', col: 0 },
      { id: 'held', type: 'waiting', label: 'Held', sublabel: 'awaiting legal', lane: 'aside', col: 1 },
    ],
    transitions: [
      { id: 'a', from: 'review', to: 'pulled', label: 'author pulled it', variant: 'dashed' },
      { id: 'b', from: 'decide', to: 'held', label: 'legal question', note: 'blocks publication' },
      { id: 'c', from: 'held', to: 'decide', label: 'cleared', variant: 'emphasis' },
    ],
  }}
/>
```

# DiagramCanvas

A frame that a picture larger than it can be panned and zoomed inside.

- Group: Diagrams
- Import: `import { DiagramCanvas } from '@misoto22/design/diagrams'`
- Page: https://ui.misoto22.com/components/diagram-canvas/
- Related: diagram-minimap, architecture-figure, scroll-area

## When to reach for it

Any oversized figure — an SVG, an image, a table that will not fold. It knows nothing about nodes, which is what makes it reusable.

## Anatomy

- **Frame** (required) — The outer box: a fixed height — 24rem unless height says otherwise — a hairline, the diagram ground, and overflow hidden. It is the window the artwork is bigger than.
- **Viewport** (required) — The focusable layer inside it: role="group" with a name, tabIndex 0, the drag handlers, the key handler and a focus ring drawn inside the frame. This is the tab stop, and it is what makes the keys pressable at all.
- **Stage** (required) — The wrapper the translate and scale are applied to. The transform is on the wrapper and never on the child, so the figure inside keeps its own coordinate space and every measurement taken inside it stays true.
- **Zoom controls** — The cluster pinned to the bottom corner: zoom out, the current percentage — which is also the reset button, named for what it does — and zoom in. controls={false} removes the cluster and leaves the keys.
- **Keyboard hint** (required) — A visually hidden paragraph, referenced by aria-describedby, saying that the frame drags and which keys pan, zoom and reset. Nothing on screen carries that sentence.

## Best practices

### Do

- Name it. label is the group’s accessible name and it defaults to "Diagram canvas", so two canvases on one page announce the same thing until each is given its own.
- Strip the figure inside to its artwork with heading={false}, legend="hidden" and cards={false}. Everything in the frame pans and zooms together, so a title left on travels away from the diagram it names and a key leaves the frame at exactly the zoom that made a reader want it.
- Move the view through the ref — zoomIn, zoomOut, reset, centerOn — rather than re-rendering the child at a new size. centerOn takes a point in the content’s own coordinates, which is what a minimap reports back.
- Hand onViewChange straight to a minimap. Each view carries the frame it was measured against as well as the scale and the offset, and that pair is the whole of the arithmetic a viewport rectangle is — the frame being the one number nothing outside the canvas can measure.

### Don’t

- Nothing clamps the pan. The offset is whatever the drag or the arrow keys left it at, so the artwork can be pushed entirely outside the frame; 0 and the reset button are the whole way back, and controls={false} without a replacement takes the pointer’s half of that away.
- The scale stops at 0.35. A figure more than about three times the frame cannot be zoomed out far enough to be seen whole, so the frame has to be sized for the diagram — a minimap answers where you are, never what is there.
- The wheel is left alone and the thumb is not: the frame sets touch-action to none, so a finger dragged inside it pans the diagram and never scrolls the page. A full-width canvas in an article is a band a touch reader has to swipe around rather than through, which is the argument for giving it a height short enough to leave page beside it.

## Accessibility

- The frame is a real tab stop, so the keyboard controls can be pressed at all.
- A plain wheel scrolls the page. Zoom needs the platform modifier, so the canvas is never a scroll trap in the middle of an article.

## Keyboard

- + / = — Zooms in about the centre of the frame.
- - — Zooms out.
- 0 — Resets the scale and the offset together.
- ← / → / ↑ / ↓ — Pans. Shift pans further per press.

## DiagramCanvas

A frame that a picture larger than it can be moved around inside. Pan with a drag, zoom with the controls or with ⌘/Ctrl and the wheel, and reset with a key. That is the whole of it — this is deliberately a VIEWPORT and not a diagram editor: nothing here knows what a node is, so it works for any oversized figure, an SVG, an image, a table that will not fold. Three decisions here are not obvious. **A plain wheel scrolls the page, not the diagram.** A canvas that swallows the wheel is a scroll trap: a reader flicking down an article hits the figure and the page stops moving for no reason they can see. Zooming needs the modifier — which is also the platform gesture for zoom everywhere else, and is what a trackpad pinch already sends. **The transform is on a wrapper, not on the content.** The child keeps its own coordinate space, so a figure inside can still be measured, exported and read by anything that walks it. Scaling the child directly would make every `getBoundingClientRect` inside it a lie. **Keyboard first, and the frame is a real tab stop.** `+` / `-` / `0` and the arrow keys move the view; the frame takes focus so they can be pressed at all. A canvas that only answers a drag is a canvas half the readers cannot operate.

### Props

- `children` (required) — `ReactNode`.
- `className` — `string`.
- `height` — `string` default `'24rem'`. How tall the frame is. Anything CSS accepts.
- `onViewChange` — `(view: CanvasView) => void`. Told about every view change, for a minimap or a percentage readout.
- `controls` — `boolean` default `true`. Hides the built-in zoom controls, for a caller supplying its own.
- `label` — `string` default `'Diagram canvas'`. Names the region for assistive tech.
- `ref` — `Ref<DiagramCanvasHandle>`.

## Example — default

```tsx
import { ArchitectureFigure, DiagramCanvas } from '@misoto22/design/diagrams'

<DiagramCanvas height="16rem" label="Request path">
  <ArchitectureFigure spec={SPEC} heading={false} legend="hidden" cards={false} />
</DiagramCanvas>
```

## Example — your own controls

```tsx
import { Button } from '@misoto22/design'
import { ArchitectureFigure, DiagramCanvas, type DiagramCanvasHandle } from '@misoto22/design/diagrams'

<div className="flex flex-col gap-3">
  <DiagramCanvas ref={canvas} controls={false} height="13rem" label="Request path">
    <ArchitectureFigure spec={SPEC} heading={false} legend="hidden" cards={false} />
  </DiagramCanvas>
  <div className="flex items-center gap-2">
    <Button size="sm" variant="ghost" iconOnly aria-label="Zoom out" onClick={() => canvas.current?.zoomOut()}>
      <RiSubtractLine size={14} aria-hidden />
    </Button>
    <Button size="sm" variant="ghost" iconOnly aria-label="Zoom in" onClick={() => canvas.current?.zoomIn()}>
      <RiAddLine size={14} aria-hidden />
    </Button>
    <Button size="sm" variant="secondary" onClick={() => canvas.current?.reset()}>
      <RiResetLeftLine size={14} aria-hidden /> Reset
    </Button>
  </div>
</div>
```

## Example — following the view

```tsx
import { Button } from '@misoto22/design'

<div className="flex flex-col gap-3">
  <DiagramCanvas ref={canvas} height="13rem" label="Request path" onViewChange={setView}>
    <ArchitectureFigure spec={SPEC} heading={false} legend="hidden" cards={false} />
  </DiagramCanvas>
  <div className="flex flex-wrap items-center gap-4">
    <span className="mono-meta text-(--ink-2)">
      {Math.round(view.scale * 100)}% at {Math.round(view.x)}, {Math.round(view.y)}
    </span>
    <Button size="sm" variant="secondary" onClick={() => canvas.current?.centerOn(820, 84)}>
      Centre on the far end
    </Button>
  </div>
</div>
```

# DiagramToolbar

A bar of actions belonging to the surface underneath them.

- Group: Diagrams
- Import: `import { DiagramToolbar } from '@misoto22/design/diagrams'`
- Page: https://ui.misoto22.com/components/diagram-toolbar/
- Related: floating-icon-button, diagram-export-menu

## When to reach for it

FloatingIconButton is one pinned action. This is the container for several, so they read as one object rather than as a scatter.

## Anatomy

- **Bar** (required) — role="toolbar" with a horizontal orientation, on a panel plate with a hairline and the system’s corner. One plate and one border is what makes six pinned buttons read as one object instead of as six.
- **Name** (required) — label, which becomes the bar’s accessible name. It is a required prop with no default, because a toolbar that announces its role and nothing else is a group a screen reader cannot tell from the next one.
- **Group** (required) — DiagramToolbarGroup: one run of related controls, divided by a hairline on its leading edge rather than by space. The first group carries no rule, so the bar does not open with a divider.
- **Controls** (required) — The children, at whatever size the caller gives them. The bar sets the gap and paints no state of its own — a button in here is the same button it is anywhere else.
- **Pin** — placement="floating" takes the bar out of the flow and pins it to the top edge of the nearest POSITIONED ancestor, at the sticky rank — under every anchored panel and every dialog — with align choosing the corner. placement="inline" leaves it in the flow and pins nothing.

## Best practices

### Do

- Give label the bar’s job rather than its shape — "Diagram actions", not "Toolbar" — because a page with a figure and a table otherwise announces two toolbars and distinguishes neither.
- Divide with DiagramToolbarGroup rather than with a gap. The rule is drawn on the group, and a gap wide enough to read as a boundary is also wide enough to stop the bar reading as one object, which is the reason the controls were collected at all.
- Keep it to a handful of controls. There is no roving focus here, so Tab visits every one of them: ten actions in the bar is ten stops between the reader and the rest of the page.

### Don’t

- A floating bar sits over the surface, not beside it. Whatever is in that corner of the figure is underneath it — pad the surface, or use placement="inline" and let the bar take its own row.
- role="toolbar" is a promise about the keyboard as well as a name: a reader is told this is a toolbar and expects the arrow keys to move inside it. For two buttons that merely sit next to each other, a plain div makes no promise this component then has to keep.
- A floating bar is a SIBLING of the canvas inside a positioned wrapper, never a child of it. Everything handed to DiagramCanvas renders inside the transformed stage, so a bar passed as a child zooms and pans away with the diagram it was put there to control — and with no positioned ancestor at all it pins to whichever box further up the page happens to be one.

## Accessibility

- role="toolbar" announces a toolbar rather than six unrelated buttons. It does not implement roving focus — Tab visits every control, which is honest for a bar of three.

## DiagramToolbar

A bar of actions that belong to the surface underneath them. The package already has `FloatingIconButton` for ONE pinned action. This is the container for several — which is a different problem, because several pinned buttons need to read as one object rather than as a scatter: one plate, one border, hairlines between the groups, and a single `role="toolbar"` so a screen reader announces a toolbar instead of six unrelated buttons. `role="toolbar"` also changes the keyboard contract, and callers should know what they are opting into: arrow keys are expected to move between the controls and Tab is expected to leave the bar. This component does not implement roving focus for you — a bar of three buttons where Tab visits all three is honest and fine — so pass `placement="inline"` and skip the role by using a plain `<div>` if that is not what you want.

### Props

- `children` (required) — `ReactNode`.
- `placement` — `'inline' | 'floating'` default `'inline'`. Where it sits. `floating` pins it over the surface it acts on.
- `align` — `'start' | 'end'` default `'end'`. Which corner a floating bar pins to.
- `label` (required) — `string`.

Also accepts: `Omit<ComponentProps<'div'>, 'children'>`.

## DiagramToolbarGroup

One run of related controls inside the bar. Separated by a hairline rather than by space, because a gap large enough to read as a group boundary is also large enough to stop the bar reading as one object — which is the whole reason the controls were collected into a bar.

## Example — default

```tsx
import { Button } from '@misoto22/design'
import { DiagramToolbar, DiagramToolbarGroup } from '@misoto22/design/diagrams'

<DiagramToolbar label="Diagram actions">
  <DiagramToolbarGroup>
    <Button size="sm" variant="ghost">
      Theme
    </Button>
    <Button size="sm" variant="ghost">
      Style
    </Button>
  </DiagramToolbarGroup>
  <DiagramToolbarGroup>
    <Button size="sm" variant="ghost">
      Present
    </Button>
    <Button size="sm" variant="secondary">
      Export
    </Button>
  </DiagramToolbarGroup>
</DiagramToolbar>
```

## Example — floating over a canvas

```tsx
import { Button } from '@misoto22/design'

<div className="relative" ref={stage}>
  <DiagramCanvas ref={canvas} height="14rem" label="Request path">
    <ArchitectureFigure spec={SPEC} heading={false} legend="hidden" cards={false} />
  </DiagramCanvas>
  <DiagramToolbar label="Diagram actions" placement="floating" align="start">
    <DiagramToolbarGroup>
      <Button size="sm" variant="ghost" iconOnly aria-label="Reset the view" onClick={() => canvas.current?.reset()}>
        <RiResetLeftLine size={14} aria-hidden />
      </Button>
      <Button size="sm" variant="ghost" iconOnly aria-label="Centre the diagram" onClick={() => canvas.current?.centerOn(420, 84)}>
        <RiFullscreenLine size={14} aria-hidden />
      </Button>
    </DiagramToolbarGroup>
    <DiagramToolbarGroup>
      <DiagramExportMenu targetRef={stage} title="Request path" />
    </DiagramToolbarGroup>
  </DiagramToolbar>
</div>
```

## Example — a different set of controls

```tsx
import { Button } from '@misoto22/design'
import { DiagramToolbar, DiagramToolbarGroup } from '@misoto22/design/diagrams'

<DiagramToolbar label="Chapters">
  <DiagramToolbarGroup>
    {CHAPTERS.map((chapter) => (
      <Button
        key={chapter.id}
        size="sm"
        variant={chapter.id === active ? 'secondary' : 'ghost'}
        aria-pressed={chapter.id === active}
        onClick={() => setActive(chapter.id)}
      >
        {chapter.label}
      </Button>
    ))}
  </DiagramToolbarGroup>
  <DiagramToolbarGroup>
    <span className="mono-meta px-1.5 text-(--ink-3-aa)">
      {position} of {CHAPTERS.length}
    </span>
  </DiagramToolbarGroup>
</DiagramToolbar>
```

# DiagramExportMenu

Taking the figure off the page: PNG, JPEG, WebP, SVG and a 1200×630 share card.

- Group: Diagrams
- Import: `import { DiagramExportMenu } from '@misoto22/design/diagrams'`
- Page: https://ui.misoto22.com/components/diagram-export-menu/
- Related: dropdown-menu, diagram-toolbar

## When to reach for it

It does the export rather than emitting a format name, because the interesting half — baking custom properties into real colours before serialising — is the half a caller would not know to write.

## Anatomy

- **Trigger** (required) — A small secondary button reading Export, or whatever trigger replaces it — the replacement is slotted, so it becomes the menu’s own control rather than sitting next to one.
- **Menu** (required) — A dropdown aligned to the trigger’s end, in three labelled groups separated by rules: Image, Vector, Share. The grouping is the answer to "which of these five do I want".
- **Format row** (required) — One menu row per format, with its name and a mono hint under it — "Lossless, 2× for retina", "Compact, flattened onto paper". Real menu rows, so the arrow keys walk them, typing jumps to one, and picking one closes the menu over the file it just wrote. The running one gains an ellipsis and every row is disabled until it finishes, so a second click cannot start a second export.
- **Serialiser** (required) — The part with nothing to point at: the artwork is cloned, every node’s computed paint is written inline, and the clone is placed on a plate the size of the picture plus its padding. It is what stops var(--ink) arriving in a document with no stylesheet and painting nothing.
- **Share card** — A fixed 1200 × 630 frame with the title printed on it and the whole diagram letterboxed inside — never cropped to fill, because a card cropped to fill is a picture of a different diagram.
- **Result** — onResult, called with the format, an ok or the Error, and the source that produced it. It is the only place a failed export is reported.

## Best practices

### Do

- Point targetRef at the wrapper rather than at an svg you found yourself. The export looks for the artwork marker first, which is what stops a page whose toolbar sits inside the same wrapper from exporting a picture of a chevron.
- Export after the artwork has been measured. The serialiser reads the element’s box and throws when it is still zero, so a call made in the same tick as the mount fails loudly instead of writing an empty file.
- Take onResult and put a failure in front of the reader. An unmeasured figure, a canvas tainted by a cross-origin image, a browser that returned no 2D context — each is reported there rather than thrown at the click, and the alternative is a menu item that quietly does nothing.
- Read source alongside ok. built-in says a file reached the browser; caller says your own onExport resolved, which is exactly what a handler that did nothing also does — the menu cannot see inside your pipeline and no longer reports as though it can.
- Pass background={null} for a figure going onto a coloured page. Every other export paints the reader’s own surface behind the artwork, and JPEG is flattened onto that surface whatever this says, because a transparent JPEG is a black one.

### Don’t

- The file is the artwork and the theme the reader was in. Paint is read off the live element, so a figure exported from a dark page is a dark image in a light document; and the toolbar, the inspector and the figure’s own hidden summary list are HTML, so none of them travels with it.
- Do not treat the SVG as a pixel-exact record. The isolated document cannot fetch the page’s web fonts, so the type falls back to what the machine has — the words and the line breaks are already fixed, but a name that just fitted its plate on screen can overrun its own rule in the file.
- The output is sized from the artwork’s box ON SCREEN rather than from its viewBox, so a figure sitting at 4× inside a DiagramCanvas serialises four times larger and then rasterises at 2× on top of that. Reset the view before exporting, or a reader gets a file whose dimensions record where the zoom happened to be.

## Accessibility

- A failed export is reported through onResult rather than swallowed: a click that quietly does nothing is indistinguishable from a broken button.

## DiagramExportMenu

Taking the figure off the page: five files, one menu. WHY THE MENU DOES THE WORK rather than handing back a format: every one of these exports is the same six steps — find the `<svg>`, walk it with `getComputedStyle` to bake the custom properties into real colours, serialise, rasterise, name the file, hand it to the browser — and only the last two differ between them. A menu that emitted `'png'` and left the caller to do the rest would be a menu that every consumer reimplements, badly, and the interesting half (a serialised SVG resolves `var(--ink)` to nothing and comes out invisible) is exactly the half a caller would not know to write. `onExport` is still there for a page with its own pipeline — a server-side renderer, a different frame size — and taking it turns everything below into a no-op, which is why a result from that path says `source: 'caller'`: this component cannot see whether the handler produced a file, so it does not report that it did. What each format actually is, stated rather than implied. **SVG** is the artwork with resolved colours. It is editable and it is the only lossless one, but it carries no web fonts: a machine without the family renders it in a fallback, so type metrics will differ. **The ground** is the reader's own surface unless `background` says otherwise. `background={null}` exports on transparency — for a figure being dropped onto a coloured page — except in JPEG, which has no alpha and is flattened onto paper whatever is asked for. **PNG, JPEG and WebP** are the browser's own rasteriser re-drawing that SVG at 2×. Not a screenshot — antialiasing and any effect a page stylesheet applied from OUTSIDE the `<svg>` are not in it. **JPEG has no alpha**, so it is flattened onto the resolved paper colour rather than onto black, which is what a transparent PNG becomes when a format with no transparency is asked to hold it. **The share card** is a 1200 × 630 frame with the title on it and the whole diagram letterboxed inside — never cropped. A card that cropped to fill the frame would be a picture of a different diagram.

### Props

- `targetRef` (required) — `RefObject<HTMLElement | SVGSVGElement | null>`. The `<svg>` to export, or an element containing exactly one. A ref rather than a selector, because a page can hold several figures and a selector would export whichever the document happened to reach first.
- `title` (required) — `string`. Names the file, and is printed on the share card.
- `trigger` — `ReactNode`. Replaces the trigger.
- `className` — `string`.
- `onExport` — `(format: ExportFormat) => void | Promise<void>`. Runs instead of the built-in export — for a caller with its own pipeline. Taking it turns everything below into a no-op, INCLUDING the part that knows whether a file was produced: a result from this path reports `source: 'caller'` and an `ok` that means only "your handler resolved".
- `onResult` — `(result: ExportResult) => void`. Told what happened, so a page can raise a toast.
- `background` — `string | null`. Painted behind the artwork. Defaults to the surface the reader is looking at; `null` exports on a transparent ground. JPEG has no alpha channel, so it is flattened onto the reader's own paper whatever this says — a transparent JPEG is a black one.

## exportFigure

One figure, one format, one file. Exported so a page can wire a keyboard shortcut or its own button to exactly what the menu does, without reimplementing the six steps.

## Example — default

```tsx
import { ArchitectureFigure, DiagramExportMenu } from '@misoto22/design/diagrams'

<div className="flex flex-col items-start gap-4">
  <DiagramExportMenu targetRef={figure} title="Request path" />
  <div ref={figure} className="w-full">
    <ArchitectureFigure spec={SPEC} heading={false} legend="hidden" />
  </div>
</div>
```

## Example — what lands in the file

```tsx
import { Button } from '@misoto22/design'

<div ref={stage} className="flex flex-col gap-4">
  <DiagramToolbar label="Diagram actions">
    <DiagramToolbarGroup>
      <Button size="sm" variant="ghost" iconOnly aria-label="About this diagram">
        <RiInformationLine size={14} aria-hidden />
      </Button>
    </DiagramToolbarGroup>
    <DiagramToolbarGroup>
      <DiagramExportMenu targetRef={stage} title="Order pipeline" />
    </DiagramToolbarGroup>
  </DiagramToolbar>
  <ArchitectureFigure spec={SPEC} heading={false} legend="hidden" />
</div>
```

## Example — your own pipeline

```tsx
import { Button } from '@misoto22/design'
import { ArchitectureFigure, DiagramExportMenu } from '@misoto22/design/diagrams'

<div className="flex flex-col items-start gap-4">
  <div className="flex flex-wrap items-center gap-3">
    <DiagramExportMenu
      targetRef={figure}
      title="Request path"
      trigger={
        <Button size="sm" variant="ghost" iconOnly aria-label="Export this diagram">
          <RiDownloadLine size={14} aria-hidden />
        </Button>
      }
      onExport={(format) => setNote(`Queued a ${format} render on the server.`)}
      onResult={(result) => {
        if (!result.ok) setNote(`The ${result.format} export failed: ${result.error?.message}`)
      }}
    />
    <span className="mono-meta text-(--ink-2)">{note}</span>
  </div>
  <div ref={figure} className="w-full">
    <ArchitectureFigure spec={SPEC} heading={false} legend="hidden" />
  </div>
</div>
```

# DiagramInspector

What the reader just picked, written out beside the picture.

- Group: Diagrams
- Import: `import { DiagramInspector } from '@misoto22/design/diagrams'`
- Page: https://ui.misoto22.com/components/diagram-inspector/
- Related: card, diagram-canvas

## When to reach for it

A node holds about eight words before it stops being a node. Everything past those — the port, the owner, the six relationships — belongs here.

## Anatomy

- **Region** (required) — A <section> named "<title> details" with aria-live="polite", on a panel plate. A region and not a dialog: nothing traps focus and nothing demands dismissal, because the reader clicked a node rather than opening a window.
- **Heading** (required) — The eyebrow over the title — what KIND of thing this is, then what it is called. The eyebrow is where the plate’s own kicker word belongs, so the panel and the picture say the same thing about the same node.
- **Facts** — A definition list, one term and value per row, the value settable in mono for an id, a path, a port. A list rather than a grid of divs, because a grid tells a screen reader nothing about which value belongs to which label.
- **Relationships** — One row per edge the node takes part in, each becoming a real button when it carries onSelect. The arrow glyph is hidden and the direction spelled out beside it, so "to" and "from" are heard rather than guessed.
- **Close** — A small control named for what it does — clearing the selection, not closing a window. It is the only thing that can empty the panel.
- **Actions** — A wrap of caller-supplied buttons under the facts: copy the id, open the source the node was read out of.

## Best practices

### Do

- Pair it with the figure’s onSelectNode. That is what turns the hidden summary list into real buttons, and without it the panel can only ever be filled by a pointer — the plates in the picture are presentational by construction.
- Give every relationship an onSelect. The rows become buttons and the graph becomes walkable peer by peer, which is how a keyboard reader gets from a node to the node it is connected to without going back through the list.
- Move the long facts here and leave about eight words on the plate. A box holding a port, an owning team and a file path grows to fit all three rather than clipping them, and a figure of boxes that size is a document with lines drawn on it.

### Don’t

- Two facts sharing a label are two rows, and neither says which is which. They are keyed by position, so both render — and a panel with "Source" twice leaves the reader deducing from the values what the labels should have said. Name them apart when they mean different things.
- floating pins the panel over the surface, so it covers that corner of the diagram for as long as it is mounted. It has no dismissal contract of its own — passing no onClose leaves the reader nothing to press and the corner hidden until the selection changes.

## Accessibility

- A labelled region with aria-live="polite", not a dialog: the reader clicked a node, they did not open anything, so focus is never trapped or demanded.
- Relationships are real buttons when they carry onSelect, which is how the graph becomes walkable peer by peer from the keyboard.

## DiagramInspector

What the reader just picked, written out. A diagram can hold about eight words per node before it stops being a diagram and starts being a document with lines drawn on it. Everything past those eight — the port, the owning team, the file it was read out of, the six relationships it takes part in — belongs beside the picture rather than inside it, and this is that place. NOT A DIALOG, and that is deliberate. An inspector is a REGION that changes with the selection, not a modal. Giving it `role="dialog"` would trap focus and demand dismissal for something the reader never opened — they clicked a node, and the panel followed. So it is a labelled region with `aria-live="polite"`, which is what makes a screen reader announce the new selection without stealing the cursor from whatever the reader was doing. The relationships are real buttons when they carry `onSelect`, which is how the diagram becomes navigable from the keyboard: a reader can walk the graph peer by peer without ever touching the picture.

### Props

- `eyebrow` — `string`. The kicker over the title — what KIND of thing this panel is showing.
- `title` (required) — `string`.
- `description` — `ReactNode`.
- `facts` — `InspectorFact[]` default `[]`.
- `links` — `InspectorLink[]` default `[]`.
- `actions` — `ReactNode`. Buttons under the facts — copy a link, open the source.
- `onClose` — `() => void`.
- `className` — `string`.
- `floating` — `boolean`. Renders as a floating panel over the surface rather than in the flow.

## Example — default

```tsx
import { DiagramInspector } from '@misoto22/design/diagrams'

<DiagramInspector
  eyebrow="Service"
  title="API"
  description="FastAPI, behind the load balancer. Owns every read the cache misses."
  facts={[
    { label: 'Port', value: '8000', mono: true },
    { label: 'Region', value: 'ap-southeast-2', mono: true },
    { label: 'Id', value: 'api', mono: true },
  ]}
  links={[
    { direction: 'in', label: 'HTTPS', peer: 'CloudFront' },
    { direction: 'out', label: 'read-through', peer: 'Redis' },
    { direction: 'out', label: 'SQL', peer: 'Postgres' },
  ]}
  onClose={() => {}}
/>
```

## Example — nothing selected

```tsx
import { Button } from '@misoto22/design'
import { DiagramInspector } from '@misoto22/design/diagrams'

<div className="flex flex-col gap-3">
  <div className="flex flex-wrap items-center gap-2">
    {NODES.map((entry) => (
      <Button key={entry.id} size="sm" variant="secondary" onClick={() => setSelected(entry.id)}>
        {entry.title}
      </Button>
    ))}
  </div>
  {node && peer ? (
    <DiagramInspector
      eyebrow={node.eyebrow}
      title={node.title}
      description={node.description}
      facts={[
        { label: 'Port', value: node.port, mono: true },
        { label: 'Id', value: node.id, mono: true },
      ]}
      links={[
        {
          direction: node.id === 'worker' ? 'out' : 'in',
          label: 'read-through',
          peer: peer.title,
          onSelect: () => setSelected(peer.id),
        },
      ]}
      onClose={() => setSelected(null)}
    />
  ) : (
    <p className="m-0 rounded-(--radius-lg) border border-dashed border-(--rule-2) p-4 text-[13px] leading-[1.55] text-(--ink-3-aa)">
      Pick a component to see what it is and what reaches it.
    </p>
  )}
</div>
```

## Example — pinned over the figure

```tsx
import { Button } from '@misoto22/design'
import { ArchitectureFigure, DiagramInspector } from '@misoto22/design/diagrams'

<div className="relative">
  <ArchitectureFigure spec={SPEC} heading={false} legend="hidden" cards={false} activeIds={['db']} />
  <DiagramInspector
    floating
    eyebrow="Datastore"
    title="Postgres"
    description="The primary, and the end of the request path above it."
    facts={[
      { label: 'Id', value: 'db', mono: true },
      { label: 'Links', value: '1' },
    ]}
    actions={
      <Button
        size="sm"
        variant="secondary"
        onClick={() => {
          void navigator.clipboard?.writeText('#db')
          setCopied(true)
        }}
      >
        {copied ? 'Copied' : 'Copy link'}
      </Button>
    }
  />
</div>
```

# DiagramMinimap

Where you are in something bigger than the window.

- Group: Diagrams
- Import: `import { DiagramMinimap } from '@misoto22/design/diagrams'`
- Page: https://ui.misoto22.com/components/diagram-minimap/
- Related: diagram-canvas

## When to reach for it

Pairs with DiagramCanvas. The viewport rectangle is derived from the canvas’s own view, never stored — a map that disagrees with its territory is worse than none.

## Anatomy

- **Map frame** (required) — A fixed-width plate — 200px unless width says otherwise — whose height follows the artwork’s own aspect ratio, named as a group so it is not an unlabelled box beside the figure.
- **Miniature** (required) — The children under a CSS scale of width over content.width, anchored top-left, hidden from assistive technology and transparent to the pointer. Drawn only once content has a size — at width 0 the scale would be 1 and the miniature would be the artwork’s top-left corner at full size. It answers "what is there" at a glance and nothing more.
- **Viewport rectangle** (required) — An accent-washed rectangle computed from the canvas’s view and the map’s scale, clipped to the plate so a viewport panned past the artwork stops claiming a map that reaches further, and floored at a few pixels so a deep zoom still leaves something on screen to see. It is derived on every render and never stored.
- **Seek layer** — The transparent layer over the map that turns a press, or a drag that STARTED on it, into a point in CONTENT coordinates and hands it to onSeek. A button pressed elsewhere and dragged across it moves nothing. Nor does the map itself — it has no authority over the view.

## Best practices

### Do

- Feed it the canvas’s own onViewChange. The rectangle is arithmetic on those three numbers, so a map wired that way cannot disagree with the frame it maps — and keeping a second copy of where the viewport is, is exactly how one comes to.
- Measure content at the artwork’s natural CSS size. Everything here is scaled by width over content.width, so a wrong content width scales the miniature and the rectangle by the same wrong factor: the map still looks plausible and points at the wrong part of the picture. A width of 0 draws an empty plate instead, which is what a measurement that has not landed yet should look like.
- Let the canvas say how big the frame is. Every view a DiagramCanvas emits carries the frame it was measured against, so passing onViewChange through is enough — the frame prop is for a frame this component cannot be told about, and a hand-declared one is the single number that makes the rectangle lie.
- Send onSeek straight to the canvas handle’s centerOn. The point arrives in content coordinates, which is the space centerOn already takes, so recentring needs no conversion of your own.

### Don’t

- It is pointer-only and hidden from assistive technology: no tab stop, no keys, and the miniature deliberately publishes nothing because the figure it mirrors already does. The canvas’s arrow keys stay the keyboard’s route to a far corner, so the minimap must never be the only way to reach one.
- The miniature is the same markup shrunk, not a simplified drawing — every label goes down with it, so a wide figure at 200px is a shape rather than a reading copy. It answers where you are; what a node says is the figure’s job.

## Accessibility

- The miniature is aria-hidden. The figure it mirrors already publishes its own summary, and a second copy would read the whole diagram out twice.

## DiagramMinimap

Where you are in something bigger than the window. Two things at once, and both are needed: a miniature of the whole artwork, and a rectangle showing which part of it the frame is currently over. The miniature alone answers "what is there"; the rectangle answers "and where am I", which is the question a reader who has just panned twice actually has. THE RECTANGLE IS DERIVED, never stored. Its position comes out of the canvas's own view — the same three numbers the canvas is already transforming by — divided by the map's scale, and clamped to the plate: a viewport that has been panned past the edge of the artwork is a viewport half over blank paper, and drawing the rectangle out there claims the map extends somewhere it does not. Keeping a second copy of "where the viewport is" is how a minimap comes to disagree with the thing it is a map of, and a map that disagrees is worse than none. NOTHING IS DRAWN UNTIL THE ARTWORK HAS A SIZE. `content` is usually a measurement, and a measurement's first value is zero — so the scale would be 1, the miniature would be the artwork's top-left corner at full size, and the rectangle would sit over it meaning nothing. An empty plate for one frame is the honest version of "not yet". CLICKING RECENTRES rather than jumping. `onSeek` reports a point in CONTENT coordinates, which is what a canvas's `centerOn` takes. The minimap does not move anything itself: it has no authority over the view, it only says where the reader pointed. A drag keeps seeking, and only a drag that STARTED on the map does — a button held down somewhere else and dragged across is not this component's gesture to answer.

### Props

- `content` (required) — `{ width: number; height: number }`. The whole artwork, at its natural size in CSS pixels.
- `frame` — `{ width: number; height: number }`. The frame the artwork is being looked at through, in CSS pixels. Optional because a `DiagramCanvas` now reports its own frame on every view it emits: wire `onViewChange` straight through and this is already right. Pass it only for a frame this component cannot be told about.
- `view` (required) — `CanvasView`. Where that frame currently sits — a `DiagramCanvas`'s `onViewChange`.
- `children` — `ReactNode`. A miniature of the artwork. Usually the same figure, rendered again.
- `onSeek` — `(x: number, y: number) => void`. Called with a point in CONTENT coordinates when the reader picks one.
- `width` — `number` default `200`. How wide the map is, in CSS pixels. Height follows the aspect ratio.
- `className` — `string`.
- `label` — `string` default `'Diagram overview'`.

## Example — default

```tsx
<div className="flex flex-col gap-3">
  <DiagramCanvas ref={canvas} height="14rem" label="Request path" onViewChange={setView}>
    <ArchitectureFigure spec={SPEC} heading={false} legend="hidden" cards={false} />
  </DiagramCanvas>
  <DiagramMinimap
    content={{ width: 900, height: 340 }}
    frame={{ width: 640, height: 224 }}
    view={view}
    width={180}
    onSeek={(x, y) => canvas.current?.centerOn(x, y)}
  >
    <ArchitectureFigure spec={SPEC} heading={false} legend="hidden" cards={false} />
  </DiagramMinimap>
</div>
```

## Example — what the rectangle is

```tsx
import { ArchitectureFigure, DiagramMinimap } from '@misoto22/design/diagrams'

<div className="flex flex-wrap items-start gap-6">
  {STATES.map((state) => (
    <div key={state.caption} className="flex flex-col gap-2">
      <DiagramMinimap
        content={CONTENT}
        frame={FRAME}
        view={state.view}
        width={150}
        label={`Overview, ${state.caption.toLowerCase()}`}
      >
        <ArchitectureFigure spec={SPEC} heading={false} legend="hidden" cards={false} />
      </DiagramMinimap>
      <span className="mono-meta text-(--ink-3-aa)">{state.caption}</span>
    </div>
  ))}
</div>
```

## Example — when a minimap earns its place

```tsx
import { ArchitectureFigure, DiagramMinimap } from '@misoto22/design/diagrams'

<div className="flex flex-wrap items-start gap-8">
  <div className="flex flex-col gap-2">
    <DiagramMinimap
      content={CONTENT}
      frame={{ width: 400, height: 190 }}
      view={{ scale: 1, x: -240, y: -60 }}
      width={150}
      label="Overview, a window on the diagram"
    >
      <ArchitectureFigure spec={SPEC} heading={false} legend="hidden" cards={false} />
    </DiagramMinimap>
    <span className="mono-meta text-(--ink-3-aa)">400 × 190 of 900 × 340</span>
  </div>
  <div className="flex flex-col gap-2">
    <DiagramMinimap
      content={CONTENT}
      frame={CONTENT}
      view={{ scale: 1, x: 0, y: 0 }}
      width={150}
      label="Overview, the whole diagram in frame"
    >
      <ArchitectureFigure spec={SPEC} heading={false} legend="hidden" cards={false} />
    </DiagramMinimap>
    <span className="mono-meta text-(--ink-3-aa)">900 × 340 of 900 × 340</span>
  </div>
</div>
```

# DiagramLegend

The key: which drawn form means which kind of thing.

- Group: Diagrams
- Import: `import { DiagramLegend } from '@misoto22/design/diagrams'`
- Page: https://ui.misoto22.com/components/diagram-legend/
- Related: architecture-figure, lifecycle-figure

## When to reach for it

Not optional furniture in a monochrome system. When a queue and a cache differ by a sigil rather than a colour, this is the only place a reader is told what the sigil means.

## Anatomy

- **Row** (required) — A wrapping, baseline-aligned row over a top rule. Inside a figure it sits between the picture and the conclusion cards, which is where a reader looks after failing to recognise a mark.
- **Kicker** — The word Key before the row. title={null} drops it for a bare row, and the list keeps that word as its own accessible name either way.
- **List** (required) — A <ul> of pairs rather than a row of spans, so the count is part of what a screen reader says about it — "list, six items" is the first useful fact about a key.
- **Sample** (required) — A 14 × 14 svg carrying the entry’s own markup, hidden from assistive technology. Markup rather than a name from a fixed list, because a key has to show the SAME mark the figure drew.
- **Label** (required) — The word beside the mark, in the meta voice. The standard builders take it from the same table the plate’s eyebrow prints, so a plate reading SERVICE is never explained by a key reading Datastore.

## Best practices

### Do

- Build the entries with kindLegend, variantLegend or stateLegend. They are made out of the renderers’ own drawing code, so the key cannot come to show a mark the figure does not draw or a word the plate does not print.
- Leave a figure’s legend at "auto". It lists only the kinds actually drawn; "all" prints seven kinds beside a figure using three, which is four claims the picture does not support.
- Pass title={null} when the key sits under a caption that already says what it is. The list keeps Key as its accessible name, so the kicker can go without the row losing its name.

### Don’t

- A key is not where a distinction is MADE. The two state tokens are the only hues these figures spend and each terminal is also its own plate shape — a difference carried by colour alone is one a reader can only look up, an entry at a time, after noticing there is a key at all.
- legend="hidden" is not free on a figure of tagged plates. A plate prints its tag OR the kind word in the same eyebrow slot and the tag wins, so on a tagged plate the kind is carried by the sigil alone — hiding the key takes the only thing that teaches that sigil off the page.

## Accessibility

- A list of pairs rather than a row of spans, so the count is part of what a screen reader says about it.
- kindLegend, variantLegend and stateLegend build the standard sets out of the renderers’ own drawing code, so the key can never drift from the figure.

## DiagramLegend

The key: which drawn form means which kind of thing. Not optional furniture in a monochrome system, and this is the one place that has to be said plainly. When the difference between a queue and a cache is a sigil rather than a colour, the key is the only place a reader is told what the sigil means — a figure whose forms are undocumented is a figure whose forms might as well not have been drawn. A `<ul>` rather than a row of `<span>`s: it is a list of pairs, and the count is part of what a screen reader should say about it.

### Props

- `entries` (required) — `DiagramLegendEntry[]`.
- `title` — `string | null` default `'Key'`. The kicker before the row. Pass null for a bare row.
- `className` — `string`.

## Example — default

```tsx
import { DiagramLegend, kindLegend, stateLegend } from '@misoto22/design/diagrams'

<div className="flex flex-col gap-6">
  <DiagramLegend entries={kindLegend(['frontend', 'backend', 'database', 'messagebus', 'security'])} />
  <DiagramLegend title="States" entries={stateLegend(['start', 'active', 'decision', 'success', 'failure'])} />
</div>
```

## Example — lines rather than plates

```tsx
import { DiagramLegend, variantLegend } from '@misoto22/design/diagrams'

<div className="flex flex-col gap-6">
  <DiagramLegend title="Lines" entries={variantLegend(['default', 'emphasis', 'security', 'dashed'])} />
  <DiagramLegend
    title={null}
    entries={variantLegend(['emphasis', 'dashed'], {
      dashed: { label: 'Published to a topic' },
    })}
  />
</div>
```

## Example — a key you draw yourself

```tsx
import { DiagramLegend } from '@misoto22/design/diagrams'

<DiagramLegend title="Ownership" entries={OWNERSHIP} />
```

# SiteShell

Page landmarks, footer groups and shared section headings.

- Group: Website
- Import: `import { SiteShell } from '@misoto22/design/website'`
- Page: https://ui.misoto22.com/components/site-shell/

## When to reach for it

Compose the document shell while the host supplies routing links and content.

## Best practices

### Do

- Supply localized labels, descriptive links and meaningful image alternatives.

### Don’t

- Do not put service credentials, routing logic or backend models inside presentation components.

## SiteShell

One main landmark, a keyboard skip link, and the publication's common shell.

### Props

- `children` (required) — `ReactNode`.
- `navigation` — `ReactNode`.
- `footer` — `ReactNode`.
- `skipLabel` (required) — `string`.
- `contentId` — `string` default `'main-content'`.

## SiteFooter

A quiet footer with semantic, independently named destination groups.

### Props

- `brand` (required) — `ReactNode`.
- `contact` — `ReactNode`.
- `description` — `ReactNode`.
- `groups` (required) — `SiteFooterGroup[]`.
- `copyright` (required) — `ReactNode`.
- `colophon` — `ReactNode`.

## SiteSectionHeading

### Props

- `title` (required) — `string`.
- `subtitle` — `string`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## SiteLink

Styling for a host router's link without owning its destination.

### Props

- `children` (required) — `ReactElement`.
- `variant` — `'text' | 'back' | 'meta'` default `'text'`.
- `className` — `string`.

## Example — footer destinations

```tsx
import { SiteFooter, SiteLink } from '@misoto22/design/website'

<SiteFooter
  brand="Field Notes"
  description="An independent journal of design and observation."
  groups={[
    { id: 'read', label: 'Read', items: [
      { id: 'essays', content: <SiteLink><a href="#essays">Essays</a></SiteLink> },
      { id: 'index', content: <SiteLink><a href="#index">Archive</a></SiteLink> },
    ] },
    { id: 'about', label: 'About', items: [
      { id: 'studio', content: <SiteLink><a href="#studio">The studio</a></SiteLink> },
    ] },
  ]}
  copyright="© 2026 Field Notes"
  colophon="Set with care."
/>
```

# SiteNavigation

Responsive navigation and explicit language or appearance choices.

- Group: Website
- Import: `import { SiteNavigation } from '@misoto22/design/website'`
- Page: https://ui.misoto22.com/components/site-navigation/

## When to reach for it

Use one named navigation region with a keyboard-accessible mobile drawer.

## Best practices

### Do

- Supply localized labels, descriptive links and meaningful image alternatives.

### Don’t

- Do not put service credentials, routing logic or backend models inside presentation components.

## NavigationSearchTrigger

A visible search entry with its keyboard shortcut, compact on small screens.

### Props

- `label` (required) — `string`.
- `onClick` (required) — `() => void`.
- `shortcut` — `string` default `'⌘ K'`.

## PreferenceMenu

A compact named control for selecting one persistent reader preference.

### Props

- `label` (required) — `string`.
- `value` (required) — `string`.
- `onValueChange` (required) — `(value: string) => void`.
- `icon` (required) — `ReactNode`.
- `disabled` — `boolean`.
- `options` (required) — `{ value: string; label: string; icon?: ReactNode }[]`.

## SiteNavigation

A public-site masthead with a keyboard-safe mobile navigation sheet.

### Props

- `brand` (required) — `ReactNode`.
- `links` (required) — `SiteNavigationItem[]`.
- `actions` — `ReactNode`.
- `footer` — `ReactNode`.
- `label` (required) — `string`.
- `openLabel` (required) — `string`.
- `closeLabel` (required) — `string`.
- `overlay` — `boolean` default `false`. Transparent over media until the reader scrolls.
- `navigationKey` — `string`. A host navigation identity; changing it dismisses the mobile menu.

## Example — navigation and preferences

```tsx
import { PreferenceMenu, SiteNavigation } from '@misoto22/design/website'

<SiteNavigation
  brand={<a href="#journal">Field Notes</a>}
  label="Journal navigation"
  openLabel="Open navigation"
  closeLabel="Close navigation"
  links={[
    { id: 'writing', active: true, content: <a href="#writing">Writing</a> },
    { id: 'work', content: <a href="#work">Work</a> },
    { id: 'about', content: <a href="#about">About</a> },
  ]}
  actions={<PreferenceMenu label="Language" value={language} onValueChange={setLanguage}
    icon={<RiTranslate2 size={18} aria-hidden="true" />}
    options={[{ value: 'en', label: 'English' }, { value: 'zh', label: '中文' }]} />}
/>
```

# Portfolio

An editorial introduction, featured images, records and a question card.

- Group: Website
- Import: `import { Portfolio } from '@misoto22/design/website'`
- Page: https://ui.misoto22.com/components/portfolio/

## When to reach for it

Build a personal or studio index from supplied text, images and actions.

## Best practices

### Do

- Supply localized labels, descriptive links and meaningful image alternatives.

### Don’t

- Do not put service credentials, routing logic or backend models inside presentation components.

## Portfolio

An introduction and a chosen photograph, with content supplied by the host.

### Props

- `name` (required) — `string`.
- `monogram` — `string`.
- `biography` (required) — `ReactNode`.
- `facts` — `ReactNode[]` default `[]`.
- `quotation` — `ReactNode`.
- `feature` — `ReactNode`.

## PortfolioImage

### Props

- `children` (required) — `ReactElement`.
- `title` — `ReactNode`.
- `metadata` — `ReactNode`.
- `index` — `string`.
- `size` — `'feature' | 'tile' | 'thumbnail'` default `'tile'`.
- `natural` — `boolean` default `false`. Preserve the supplied image's intrinsic dimensions instead of cropping.

## PortfolioRecord

### Props

- `title` (required) — `ReactNode`.
- `description` — `ReactNode`.
- `context` — `ReactNode`.
- `image` — `ReactNode`.
- `action` — `ReactNode`.
- `metadata` — `ReactNode`.

## PortfolioList

### Props

- `children` (required) — `ReactNode`.
- `variant` — `'records' | 'frames' | 'thumbnails'` default `'records'`.
- `label` — `string`.

## PortfolioCategories

### Props

- `label` (required) — `string`.
- `items` (required) — `{ id: string; label: ReactNode; count: number }[]`.

## QuestionCard

A compact invitation to an application-owned conversation.

### Props

- `title` (required) — `ReactNode`.
- `description` (required) — `string`.
- `label` (required) — `string`.
- `placeholder` (required) — `string`.
- `value` (required) — `string`.
- `onChange` (required) — `(value: string) => void`.
- `onSubmit` (required) — `(value: string) => void`.
- `submitLabel` (required) — `string`.
- `examplesLabel` (required) — `string`.
- `examples` (required) — `string[]`.
- `disabled` — `boolean`.
- `maxLength` — `number`.
- `inputId` — `string`.

## Example — editorial introduction

```tsx
import { Text } from '@misoto22/design'
import { Portfolio, PortfolioCategories } from '@misoto22/design/website'

<Portfolio
  name="Avery Reed"
  monogram="AR"
  biography={<Text size="lead">Designer and writer exploring the everyday tools that help people think.</Text>}
  facts={['Independent practice', 'Working across places']}
  quotation="Start by paying attention."
  feature={<PortfolioCategories label="Selected work" items={[
    { id: 'essays', label: 'Essays', count: 12 },
    { id: 'projects', label: 'Projects', count: 4 },
  ]} />}
/>
```

# PortfolioIndex

Tabbed collections with a supporting editorial column.

- Group: Website
- Import: `import { PortfolioIndex } from '@misoto22/design/website'`
- Page: https://ui.misoto22.com/components/portfolio-index/

## When to reach for it

Group related collections under a named tab strip with keyboard selection.

## Best practices

### Do

- Supply localized labels, descriptive links and meaningful image alternatives.

### Don’t

- Do not put service credentials, routing logic or backend models inside presentation components.

## PortfolioIndex

A portfolio index whose categories and context follow the selected tab.

### Props

- `label` (required) — `string`.
- `items` (required) — `PortfolioIndexItem[]`.
- `aside` — `ReactNode`.
- `defaultValue` — `string`.

## Example — related collections

```tsx
import { Text } from '@misoto22/design'
import { PortfolioIndex, PortfolioRecord } from '@misoto22/design/website'

<PortfolioIndex label="Selected work" items={[
  { value: 'writing', label: 'Writing', count: 1,
    content: <PortfolioRecord title="The value of a small tool" description="An essay about useful constraints." context="Essay" />,
    aside: <Text size="sm">Notes on design, systems and everyday practice.</Text> },
  { value: 'projects', label: 'Projects', count: 1,
    content: <PortfolioRecord title="Reading room" description="A searchable index for a shared library." context="Product" />,
    aside: <Text size="sm">Selected work from an independent studio.</Text> },
]} />
```

# Collection

Collection headings, search controls, featured records and empty states.

- Group: Website
- Import: `import { ContentBand } from '@misoto22/design/website'`
- Page: https://ui.misoto22.com/components/collection/

## When to reach for it

Display a searchable archive without moving filtering or data access into the package.

## Best practices

### Do

- Supply localized labels, descriptive links and meaningful image alternatives.

### Don’t

- Do not put service credentials, routing logic or backend models inside presentation components.

## ContentBand

### Props

- `as` — `ElementType`.
- `tone` — `'base' | 'muted' | 'feature'` default `'base'`.
- `bleed` — `boolean` default `false`.
- `spacing` — `'none' | 'content' | 'section'` default `'none'`.

Also accepts: `HTMLAttributes<HTMLElement>`.

## CollectionIntro

### Props

- `title` (required) — `ReactNode`.
- `description` — `ReactNode`.
- `context` — `ReactNode`.
- `media` — `ReactNode`.
- `actions` — `ReactNode`.
- `compact` — `boolean` default `false`.

## CollectionMetadata

### Props

- `items` (required) — `CollectionMetadataItem[]`.

## CollectionGroup

### Props

- `title` — `ReactNode`.
- `caption` — `ReactNode`.
- `headingId` — `string`.
- `compact` — `boolean`.

Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'title'>`.

## CollectionSearch

### Props

- `value` (required) — `string`.
- `onChange` (required) — `(value: string) => void`.
- `label` (required) — `string`.
- `placeholder` — `string`.
- `clearLabel` (required) — `string`.
- `focusShortcut` — `boolean` default `false`.

## CollectionControls

### Props

- `items` (required) — `CollectionFilter[]`.
- `selected` (required) — `string | null`.
- `onSelect` (required) — `(value: string | null) => void`.
- `filterLabel` — `string`.
- `search` — `CollectionSearchProps`.
- `quiet` — `boolean`.
- `showCounts` — `boolean` default `true`.

## HighlightedText

### Props

- `text` (required) — `string`.
- `query` (required) — `string`.
- `className` — `string`.

## RecordRow

### Props

- `link` — `CollectionLink`.
- `title` (required) — `ReactNode`.
- `summary` — `ReactNode`.
- `context` — `ReactNode`.
- `media` — `ReactNode`.
- `index` — `ReactNode`.
- `metadata` — `ReactNode`.
- `trailing` — `ReactNode`.
- `subtitle` — `ReactNode`.
- `headingLevel` — `2 | 3` default `2`.
- `variant` — `'editorial' | 'media' | 'compact'` default `'editorial'`.

## FeaturedRecord

### Props

- `media` (required) — `ReactNode`.
- `title` (required) — `ReactNode`.
- `context` — `ReactNode`.
- `summary` — `ReactNode`.
- `action` — `ReactNode`.

## CollectionEmpty

### Props

- `message` (required) — `string`.
- `hint` — `string`.
- `action` — `ReactNode`.

## CollectionFooter

### Props

- `children` — `ReactNode`.
- `feedback` — `ReactNode`.

## TaxonomyLinks

### Props

- `children` (required) — `ReactNode`.
- `label` — `string`.

## ReferenceLink

A quiet resource link for references, separate from action buttons.

## ReferenceRows

### Props

- `items` (required) — `{ id?: string; label: ReactNode; hint?: ReactNode; content: ReactNode }[]`.

## CollectionTally

### Props

- `children` (required) — `ReactNode`.

## CollectionList

### Props

- `children` (required) — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLUListElement>`.

## Example — searchable records

```tsx
import { CollectionControls, CollectionEmpty, CollectionIntro, RecordRow } from '@misoto22/design/website'

<div className="w-full">
  <CollectionIntro title="Library" description="Essays and projects from the studio." />
  <CollectionControls filterLabel="Category" selected={category} onSelect={setCategory}
    items={[{ value: null, label: 'All' }, { value: 'essays', label: 'Essays' }, { value: 'projects', label: 'Projects' }]}
    search={{ value: query, onChange: setQuery, label: 'Search the library', placeholder: 'Search titles', clearLabel: 'Clear search' }} />
  {records.map((record) => <RecordRow key={record.id} variant="compact"
    link={<a href={`#${record.id}`} />} title={record.title} summary={record.summary} context={record.category} />)}
  {records.length === 0 && <CollectionEmpty message="No matching records" hint="Try another title or category." />}
</div>
```

# Reading

Article and project layouts, outlines, media and installation instructions.

- Group: Website
- Import: `import { DetailMasthead } from '@misoto22/design/website'`
- Page: https://ui.misoto22.com/components/reading/

## When to reach for it

Build long-form reading surfaces with consistent section spacing and accessible navigation.

## Best practices

### Do

- Supply localized labels, descriptive links and meaningful image alternatives.

### Don’t

- Do not put service credentials, routing logic or backend models inside presentation components.

## DetailMasthead

### Props

- `backLink` — `ReactNode`.
- `title` (required) — `string`.
- `dek` — `ReactNode`.
- `context` — `ReactNode`.
- `aside` — `ReactNode`.
- `actions` — `ReactNode`.
- `metadata` — `ReadingMetadataItem[]` default `[]`.
- `width` — `'page' | 'fill'` default `'page'`.

## ReadingLayout

### Props

- `outline` — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## ReadingSection

`seamless` lets a structured child continue directly from the section rule without drawing a second seam.

### Props

- `title` — `ReactNode`.
- `caption` — `ReactNode`.
- `lead` — `ReactNode`.
- `compact` — `boolean`.
- `seamless` — `boolean`.

Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'title'>`.

## ReadingLead

### Props

- `children` (required) — `ReactNode`.
- `muted` — `ReactNode`.
- `description` — `ReactNode`.

## RecordPager

### Props

- `label` (required) — `string`.
- `previous` — `ReadingPagerItem`.
- `next` — `ReadingPagerItem`.

## isSelfNumbered

## numberToc

## TableOfContents

### Props

- `items` (required) — `OutlineItem[]`.
- `label` (required) — `string`.
- `numbering` — `'auto' | 'none'` default `'auto'`.
- `onNavigate` — `(id: string) => void`.
- `expanded` — `boolean` default `false`.

## MobileOutline

### Props

- `items` (required) — `OutlineItem[]`.
- `title` (required) — `string`.
- `openLabel` (required) — `string`.
- `closeLabel` (required) — `string`.

## ReadingProgress

## AuthorPanel

### Props

- `avatar` — `ReactNode`.
- `name` (required) — `string`.
- `role` — `ReactNode`.
- `bio` — `ReactNode`.
- `links` — `ReactNode`.

## ReadingFigure

A reading image can preserve its source framing with `fit="contain"`, rather than silently cropping it to a house ratio.

### Props

- `media` (required) — `ReactNode`.
- `captionStart` — `ReactNode`.
- `captionEnd` — `ReactNode`.
- `width` — `'page' | 'fill'` default `'page'`.
- `ratio` — `string` default `'16 / 8'`.
- `fit` — `'cover' | 'contain'` default `'cover'`.

## MediaPlayback

### Props

- `src` (required) — `string`.
- `poster` — `string`.
- `label` (required) — `string`.
- `playLabel` (required) — `string`.
- `pauseLabel` (required) — `string`.
- `fallback` (required) — `ReactNode`.

## ActionBand

A terminal project invitation with one strong entry action and quieter supporting actions.

### Props

- `title` (required) — `ReactNode`.
- `description` — `ReactNode`.
- `actions` — `ReactNode`.
- `eyebrow` — `ReactNode`.

## FeaturePairs

### Props

- `items` (required) — `{ id?: string; label?: ReactNode; title?: ReactNode; description: ReactNode }[]`.

## DevicePreview

### Props

- `kind` (required) — `'browser' | 'phone'`.
- `label` — `string`.
- `media` (required) — `ReactNode`.
- `caption` — `ReactNode`.

## PreviewPair

### Props

- `desktop` (required) — `ReactNode`.
- `mobile` — `ReactNode`.

## CommandTabs

### Props

- `label` (required) — `string`.
- `tabs` (required) — `CommandTab[]`.
- `copyLabel` (required) — `string`.
- `copiedLabel` (required) — `string`.
- `footer` — `ReactNode`.

## ReadingSurface

### Props

- `numbered` — `boolean`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## ReadingForm

### Props

- `inline` — `boolean`.

Also accepts: `React.FormHTMLAttributes<HTMLFormElement>`.

## ArchitectureColumns

### Props

- `columns` (required) — `{ title: string; connected?: boolean; nodes: ArchitectureColumnNode[] }[]`.
- `foundation` — `ArchitectureColumnNode[]`.

## TokenLine

### Props

- `items` (required) — `{ label: ReactNode; strong?: boolean; icon?: ReactNode }[]`.
- `label` — `ReactNode`.
- `separator` — `string` default `'·'`.

## ContentFigure

### Props

- `children` (required) — `ReactNode`.
- `caption` — `ReactNode`.
- `wide` — `boolean`.

## ReadingPage

### Props

- `children` (required) — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLElement>`.

## CommandSnippet

### Props

- `code` (required) — `string`.
- `pieces` — `CommandPiece[]`.
- `copyLabel` (required) — `string`.
- `copiedLabel` (required) — `string`.
- `className` — `string`.

## Example — article and outline

```tsx
import { Text } from '@misoto22/design'
import { DetailMasthead, ReadingLayout, ReadingSection, RecordPager, TableOfContents } from '@misoto22/design/website'

<div className="w-full">
  <DetailMasthead title="A practice of attention" dek="A few observations from the daily walk."
    width="fill" metadata={[{ label: 'Published', value: '7 September 2026', dateTime: '2026-09-07' }]} />
  <ReadingLayout outline={<TableOfContents label="Example article sections" items={[
    { id: 'reading-notice', label: 'Notice', level: 2 },
    { id: 'reading-return', label: 'Return', level: 2 },
  ]} />}>
    <ReadingSection id="reading-notice" title="Notice"><Text>A familiar route still changes with the light. Record one detail before naming the whole scene.</Text></ReadingSection>
    <ReadingSection id="reading-return" title="Return"><Text>Compare what you wrote on the next visit. The difference often matters more than the first impression.</Text></ReadingSection>
    <RecordPager label="Essay navigation" next={{ link: <a href="#next-essay" />, direction: 'Next', title: 'Keeping a field journal' }} />
  </ReadingLayout>
</div>
```

# Contact

A correspondence form, contact facts, questions and location imagery.

- Group: Website
- Import: `import { CorrespondenceSection } from '@misoto22/design/website'`
- Page: https://ui.misoto22.com/components/contact/

## When to reach for it

Provide localized field labels and host-owned submission state to a complete form.

## Best practices

### Do

- Supply localized labels, descriptive links and meaningful image alternatives.

### Don’t

- Do not put service credentials, routing logic or backend models inside presentation components.

## CorrespondenceSection

A correspondence page's primary content and supporting facts.

### Props

- `aside` (required) — `ReactNode`.
- `children` (required) — `ReactNode`.
- `asidePosition` — `'start' | 'end'` default `'start'`. The secondary column can precede or follow the main content.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## ContactFormView

Controlled contact form. Validation, submission and delivery remain host responsibilities.

### Props

- `labels` (required) — `ContactFormLabels`.
- `values` (required) — `ContactFormValues`.
- `topics` (required) — `{ value: string; label: string }[]`.
- `topic` (required) — `string`.
- `onTopicChange` (required) — `(value: string) => void`.
- `onFieldChange` (required) — `(field: keyof ContactFormValues, value: string) => void`.
- `onSubmit` (required) — `FormEventHandler<HTMLFormElement>`.
- `limits` (required) — `Record<keyof ContactFormValues, number>`.
- `pending` — `boolean` default `false`.
- `error` — `string`.
- `success` — `{ title: string; description: string }`. A server-confirmed success. The host decides when the form can disappear.
- `idPrefix` — `string`. Optional stable prefix for links to a specific form.

## ContactFacts

Contact facts retain their definition-list semantics and optional navigation.

### Props

- `label` (required) — `string`.
- `items` (required) — `DescriptionListItem[]`.
- `links` — `ReactNode`.
- `linksLabel` — `string`.

## QuestionList

Visible questions and answers, useful when the complete answer set is short.

### Props

- `title` (required) — `string`.
- `description` — `string`.
- `items` (required) — `{ id: string; question: string; answer: string }[]`.

Also accepts: `HTMLAttributes<HTMLElement>`.

## LocationFigure

Static map presentation; provider URLs, credentials and theme selection stay in the host.

### Props

- `label` (required) — `string`.
- `coordinates` (required) — `string`.
- `image` — `ReactNode`.
- `credit` — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLElement>`.

## Example — controlled correspondence

```tsx
import { ContactFormView, type ContactFormValues } from '@misoto22/design/website'

<ContactFormView
  labels={{ heading: 'Start a conversation', topic: 'Topic', name: 'Name', email: 'Email', subject: 'Subject', message: 'Message',
    namePlaceholder: 'Your name', emailPlaceholder: 'you@example.com', subjectPlaceholder: 'A short introduction', messagePlaceholder: 'What would you like to discuss?',
    optional: 'Optional', note: 'This demonstration saves a local draft only.', submit: 'Capture draft', submitting: 'Capturing' }}
  values={values} onFieldChange={(field, value) => setValues((current) => ({ ...current, [field]: value }))}
  topic={topic} onTopicChange={setTopic} topics={[{ value: 'question', label: 'A question' }, { value: 'project', label: 'A project' }]}
  limits={{ name: 100, email: 200, subject: 160, message: 2000 }}
  onSubmit={(event) => { event.preventDefault(); setSaved(true) }}
  success={saved ? { title: 'Draft captured', description: 'The example retained this draft locally. No message was sent.' } : undefined}
/>
```

# Music

Featured recordings, track rows and playlist collections.

- Group: Website
- Import: `import { MediaListRow } from '@misoto22/design/website'`
- Page: https://ui.misoto22.com/components/music/

## When to reach for it

Present supplied listening data and playback controls without choosing a music service.

## Best practices

### Do

- Supply localized labels, descriptive links and meaningful image alternatives.

### Don’t

- Do not put service credentials, routing logic or backend models inside presentation components.

## MediaListRow

A ranked recording or artist, controlled by the host's one media player.

### Props

- `index` (required) — `number`.
- `artwork` — `ReactNode`.
- `title` (required) — `ReactNode`.
- `description` — `ReactNode`.
- `trailing` — `ReactNode`.
- `preview` (required) — `MediaPreviewAction`.
- `active` — `boolean` default `false`.
- `artworkShape` — `'square' | 'circle'` default `'square'`.

Also accepts: `Omit<HTMLAttributes<HTMLDivElement>, 'title'>`.

## MusicFeature

The same media feature geometry for playing, recent and unavailable recordings.

### Props

- `label` (required) — `string`.
- `title` (required) — `ReactNode`.
- `description` — `ReactNode`.
- `artwork` — `ReactNode`.
- `artworkFallback` (required) — `string`.
- `live` — `boolean` default `false`.
- `notice` — `string`.
- `action` — `ReactNode`.
- `progress` — `{ label: string; value: number; max: number; currentLabel: string; endLabel: string }`.

Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'title'>`.

## MediaCollectionCard

A playlist, album or other media collection with one explicit preview action.

### Props

- `title` (required) — `ReactNode`.
- `artwork` — `ReactNode`.
- `tag` — `string | null`.
- `description` — `string | null`.
- `metadata` — `ReactNode`.
- `preview` (required) — `MediaPreviewAction`.

Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'title'>`.

## MusicSection

A media list's heading, caption and collection layout.

### Props

- `title` (required) — `string`.
- `caption` — `string`.
- `children` (required) — `ReactNode`.
- `layout` — `'list' | 'collections'` default `'list'`.

Also accepts: `HTMLAttributes<HTMLElement>`.

## Example — recording and preview state

```tsx
import { MediaListRow, MusicFeature } from '@misoto22/design/website'

<div className="w-full">
  <MusicFeature label="Selected recording" title="Morning light" description="The Field Ensemble"
    artworkFallback="Artwork unavailable" progress={{ label: 'Playback position', value: 42, max: 180, currentLabel: '0:42', endLabel: '3:00' }} />
  <MediaListRow index={1} title="Morning light" description="The Field Ensemble" trailing="3:00" active={playing}
    preview={{ label: playing ? 'Show paused state' : 'Show playing state', playing, onToggle: () => setPlaying((value) => !value) }} />
</div>
```

# Timeline

Career records, profile narratives and chronological lists.

- Group: Website
- Import: `import { Timeline } from '@misoto22/design/website'`
- Page: https://ui.misoto22.com/components/timeline/

## When to reach for it

Present dated work, education and personal background using supplied content.

## Best practices

### Do

- Supply localized labels, descriptive links and meaningful image alternatives.

### Don’t

- Do not put service credentials, routing logic or backend models inside presentation components.

## RecordSection

A named ledger section. The host supplies its chronology without reordering.

### Props

- `title` (required) — `string`.
- `count` — `string`.
- `headingId` (required) — `string`.
- `children` (required) — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLElement>`.

## CareerRecord

One dated record, reusable for a role, qualification or other chronology.

### Props

- `title` (required) — `string`.
- `organization` (required) — `ReactNode`.
- `period` (required) — `string`.
- `periodLabel` (required) — `string`.
- `location` (required) — `string`.
- `locationLabel` (required) — `string`.
- `description` (required) — `string[]`.
- `tags` (required) — `string[]`.
- `tagsLabel` (required) — `string`.
- `mark` — `ReactNode`.
- `currentLabel` — `string`.

Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'title'>`.

## ProfileSection

A profile section follows the same heading and spacing contract as its neighbors.

### Props

- `headingId` (required) — `string`.
- `title` (required) — `string`.
- `description` — `string`.
- `children` (required) — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLElement>`.

## ProfileNarrative

A short introduction with a pull quote and a longer account alongside it.

### Props

- `headingId` (required) — `string`.
- `title` (required) — `string`.
- `pull` (required) — `string`.
- `paragraphs` (required) — `string[]`.
- `action` — `ReactNode`.

## ProfileSkills

Skill labels and theme-aware artwork, supplied by the host's content adapter.

### Props

- `groups` (required) — `{ id: string; title: string; items: ProfileSkill[] }[]`.

## ProfileInterests

A small set of interests or areas of practice.

### Props

- `items` (required) — `{ id: string; title: string; description: string }[]`.

## ProfileFigure

Source-faithful profile photography: retain the supplied image's aspect ratio.

### Props

- `children` (required) — `ReactNode`.
- `caption` — `string`.

## Timeline

An ordered collection frame. No sorting or business data is owned here.

## TimelineItem

A record mount, isolated so motion can follow the shared data-motion axis.

## Example — dated records

```tsx
import { CareerRecord, RecordSection, Timeline, TimelineItem } from '@misoto22/design/website'

<RecordSection title="Experience" count="1 role" headingId="timeline-experience">
  <Timeline><TimelineItem><CareerRecord
    title="Product designer" organization={<a href="#studio">Independent studio</a>}
    period="2023 — present" periodLabel="Period" location="Remote" locationLabel="Location" currentLabel="Current"
    description={['Designing practical tools for research and publishing.', 'Working with small teams from prototype to delivery.']}
    tags={['Research', 'Design systems']} tagsLabel="Areas of practice"
  /></TimelineItem></Timeline>
</RecordSection>
```

# Recovery

Loading, unavailable and missing-page states with recovery actions.

- Group: Website
- Import: `import { RecoveryState } from '@misoto22/design/website'`
- Page: https://ui.misoto22.com/components/recovery/

## When to reach for it

Explain the current state and provide a real next action.

## Best practices

### Do

- Supply localized labels, descriptive links and meaningful image alternatives.

### Don’t

- Do not put service credentials, routing logic or backend models inside presentation components.

## RecoveryState

A recovery page composed from the system error primitive and caller-owned destinations.

### Props

- `elsewhere` — `ReactNode`.

Also accepts: `ErrorStateProps`.

## RecoveryLinks

Suggested destinations, with routing supplied by the host.

### Props

- `label` (required) — `string`.
- `items` (required) — `{ id: string; link: ReactElement }[]`.

## LoadingRouteIntro

The shared masthead geometry, drawn from the core loading primitives.

### Props

- `titleClassName` — `string` default `'w-[min(100%,18rem)]'`.

## LoadingRecords

A collection skeleton with or without a media column.

### Props

- `rows` — `number` default `4`.
- `media` — `boolean` default `true`.

## WebsiteLoading

Named loading layouts for the website's reusable page shapes.

### Props

- `label` (required) — `string`.
- `layout` — `'records' | 'gallery' | 'media' | 'metrics' | 'identity'` default `'records'`.
- `filters` — `boolean` default `false`.
- `rows` — `number` default `4`.
- `media` — `boolean` default `true`.
- `titleClassName` — `string`.

## Example — missing record

```tsx
import { Button } from '@misoto22/design'
import { RecoveryLinks, RecoveryState } from '@misoto22/design/website'

<RecoveryState code="404" heading="This record is unavailable" message="The entry may have moved or been removed." level={2}
  action={<Button asChild><a href="#library">Return to the library</a></Button>}
  elsewhere={<RecoveryLinks label="You can also explore" items={[
    { id: 'essays', link: <a href="#essays">Recent essays</a> },
    { id: 'projects', link: <a href="#projects">Selected projects</a> },
  ]} />}
/>
```

# Media

Photograph collections, lightboxes, image details and map controls.

- Group: Website
- Import: `import { MediaMasthead } from '@misoto22/design/website'`
- Page: https://ui.misoto22.com/components/media/

## When to reach for it

Compose image browsing and map presentation while the host owns images and map lifecycles.

## Best practices

### Do

- Supply localized labels, descriptive links and meaningful image alternatives.

### Don’t

- Do not put service credentials, routing logic or backend models inside presentation components.

## MediaMasthead

The quiet opening to an image collection, before its controls and prints.

### Props

- `eyebrow` — `ReactNode`.
- `title` (required) — `ReactNode`.
- `description` — `ReactNode`.
- `headingLevel` — `1 | 2 | 3 | 4 | 5 | 6` default `1`. The title level when this page composition sits inside another document.

Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'title'>`.

## PhotographFeature

A photograph and an editorial introduction, with the original image ratio.

### Props

- `image` (required) — `ReactNode`.
- `title` (required) — `ReactNode`.
- `eyebrow` — `ReactNode`.
- `description` — `ReactNode`.
- `caption` — `ReactNode`.
- `action` — `ReactNode`.

Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'title'>`.

## MediaCollection

Page-level gallery composition; the host owns its filters and collection.

### Props

- `masthead` (required) — `ReactNode`.
- `controls` — `ReactNode`.
- `collectionId` — `string`.
- `footer` — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## MediaGallery

Level mounts keep unlike aspect ratios aligned without cropping the prints.

### Props

- `children` — `ReactNode`.
- `emptyTitle` — `ReactNode`. Supply localized empty copy when the collection may have no children.
- `emptyAction` — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLUListElement>`.

## MediaGalleryItem

### Props

- `children` (required) — `ReactElement`. A host link containing its image. The package supplies the print layout.
- `title` (required) — `ReactNode`.
- `index` — `ReactNode`.
- `location` — `ReactNode`.
- `orientation` — `'portrait' | 'landscape' | 'square'`.

Also accepts: `Omit<HTMLAttributes<HTMLLIElement>, 'title'>`.

## MediaGallerySkeleton

### Props

- `label` (required) — `string`.
- `count` — `number` default `6`.

## MediaDetailLayout

Portraits share a spread with their notes; landscapes lead a full-width spread.

### Props

- `title` (required) — `ReactNode`.
- `titleId` (required) — `string`.
- `headingLevel` — `1 | 2 | 3 | 4 | 5 | 6` default `1`. The title level when this page composition sits inside another document.
- `category` — `ReactNode`.
- `notesLabel` (required) — `string`.
- `orientation` (required) — `'portrait' | 'landscape' | 'square'`.
- `backLink` (required) — `ReactElement`.
- `index` — `ReactNode`.
- `media` (required) — `ReactNode`.
- `light` — `ReactNode`.
- `actions` — `ReactNode`.
- `metadata` — `ReactNode`.
- `location` — `ReactNode`.
- `pager` — `ReactNode`.
- `related` — `ReactNode`.

Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'title'>`.

## MediaMetadata

### Props

- `items` (required) — `DescriptionListItem[]`.

Also accepts: `HTMLAttributes<HTMLDListElement>`.

## MediaPager

### Props

- `label` (required) — `string`.
- `previous` — `ReactNode`.
- `next` — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLElement>`.

## MediaPagerItem

### Props

- `link` (required) — `ReactElement`.
- `direction` (required) — `'previous' | 'next'`.
- `label` (required) — `ReactNode`.
- `title` (required) — `ReactNode`.
- `image` — `ReactNode`.

## MediaThumbnailStrip

### Props

- `heading` (required) — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLElement>`.

## MediaThumbnail

### Props

- `children` (required) — `ReactElement`.

## MediaLightNote

The host supplies observations and formatted labels; this is presentation only.

### Props

- `label` (required) — `ReactNode`.
- `lines` (required) — `MediaLightNoteLine[]`.

## MediaMapSection

### Props

- `title` (required) — `ReactNode`.
- `hint` — `ReactNode`.
- `aliasId` — `string`. An optional legacy anchor, owned and named by the host.
- `map` (required) — `ReactNode`.
- `preview` (required) — `ReactNode`.

Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'title'>`.

## MediaMapFrame

### Props

- `label` — `ReactNode`.
- `hint` — `ReactNode`.
- `navigation` — `ReactNode`.
- `compact` — `boolean` default `false`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## MediaMapNavigation

### Props

- `zoomInLabel` (required) — `string`.
- `zoomOutLabel` (required) — `string`.
- `onZoomIn` (required) — `() => void`.
- `onZoomOut` (required) — `() => void`.

## MediaMapCanvas

A sized provider container. Map creation, themes and geographic math stay in the host.

Also accepts: `ComponentPropsWithRef<'div'>`.

## MediaMapPreview

### Props

- `title` (required) — `ReactNode`.
- `image` — `ReactNode`.
- `action` — `ReactNode`.
- `place` — `ReactNode`.
- `coordinates` — `ReactNode`.
- `children` — `ReactNode`.

## MediaMapAreaList

### Props

- `items` (required) — `MediaMapArea[]`.
- `value` — `string`.
- `onValueChange` (required) — `(value: string) => void`.

## MediaMapMarker

A keyboard-operable 44px marker for a host's map-provider portal.

### Props

- `label` (required) — `string`.
- `active` — `boolean` default `false`.

Also accepts: `Omit<Extract<ButtonProps, { href?: undefined }>, 'children' | 'iconOnly'>`.

## MediaMapPin

### Props

- `active` — `boolean` default `false`.

## MediaMapSkeleton

## MediaLightbox

A print and its controlled, focus-trapped full-screen dialog.

### Props

- `open` (required) — `boolean`.
- `onOpenChange` (required) — `(open: boolean) => void`.
- `title` (required) — `string`.
- `triggerLabel` (required) — `string`.
- `closeLabel` (required) — `string`.
- `aspectRatio` (required) — `number`. Intrinsic width divided by height; invalid dimensions use a safe fallback.
- `media` (required) — `ReactNode`.
- `expandedMedia` — `ReactNode` default `media`.

## Example — photograph collection

```tsx
import { MediaCollection, MediaGallery, MediaGalleryItem, MediaMasthead } from '@misoto22/design/website'

<MediaCollection masthead={<MediaMasthead title="Field observations" description="A small collection of places and light." headingLevel={4} />}>
  <MediaGallery>
    <MediaGalleryItem title="The far shore" index="01" location="Coast" orientation="landscape">
      <a href="#far-shore"><svg viewBox="0 0 640 420" role="img" aria-label="Illustration of a shoreline beneath a pale sky">
        <rect width="640" height="420" fill="var(--bg-2)" /><path d="M0 270 L180 210 L420 260 L640 160 V420 H0Z" fill="var(--rule)" />
      </svg></a>
    </MediaGalleryItem>
    <MediaGalleryItem title="A quiet corner" index="02" location="City" orientation="portrait">
      <a href="#quiet-corner"><svg viewBox="0 0 420 560" role="img" aria-label="Illustration of a doorway with afternoon shadow">
        <rect width="420" height="560" fill="var(--bg-2)" /><path d="M110 90 H310 V560 H110Z" fill="var(--rule)" />
      </svg></a>
    </MediaGalleryItem>
  </MediaGallery>
</MediaCollection>
```

## Example — photograph detail

```tsx
import { MediaDetailLayout } from '@misoto22/design/website'

<MediaDetailLayout
  title="Low tide"
  titleId="low-tide"
  headingLevel={4}
  notesLabel="Field notes for low tide"
  orientation="landscape"
  index="02 / 12"
  backLink={<a href="#field-observations">Back to field observations</a>}
  media={
    <figure className="m-0 w-full">
      <svg viewBox="0 0 960 540" role="img" aria-label="Illustration of a low shoreline at dusk">
        <rect width="960" height="540" fill="var(--bg-2)" />
        <path d="M0 350 L240 290 L480 340 L720 245 L960 310 V540 H0Z" fill="var(--rule)" />
      </svg>
    </figure>
  }
/>
```

# Metrics

Metric panels, accessible data tables and chart arrangements.

- Group: Website
- Import: `import { MetricsRange } from '@misoto22/design/website'`
- Page: https://ui.misoto22.com/components/metrics/

## When to reach for it

Arrange measurements and externally rendered charts without importing chart engines.

## Best practices

### Do

- Supply localized labels, descriptive links and meaningful image alternatives.

### Don’t

- Do not put service credentials, routing logic or backend models inside presentation components.

## MetricsRange

A controlled range selector. Selection represents the data the host successfully loaded.

### Props

- `label` (required) — `string`.
- `value` (required) — `string`.
- `options` (required) — `{ value: string; label: string }[]`.
- `onChange` (required) — `(value: string) => void`.

## MetricsSection

A dashboard section without a dependency on a chart engine or a domain response.

### Props

- `title` — `ReactNode`.
- `caption` — `ReactNode`.
- `action` — `ReactNode`.
- `children` (required) — `ReactNode`.

Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'title'>`.

## MetricsPanel

A labeled panel. Children may use the separately imported charts entry.

### Props

- `title` (required) — `string`.
- `caption` — `string`.
- `children` (required) — `ReactNode`.

Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'title'>`.

## MetricsPanelGrid

Responsive grids share their dividers and minimum panel width.

### Props

- `columns` — `2 | 4` default `2`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## MetricsEmptyState

An empty time series retains its plot space and tells the reader what will appear once the first observation arrives.

### Props

- `title` (required) — `ReactNode`.
- `description` (required) — `ReactNode`.

## MetricsList

Already-formatted metric rows, with a named value relation and an explicit empty state.

### Props

- `label` (required) — `string`.
- `items` (required) — `{ id: string; label: ReactNode; value: ReactNode; icon?: ReactNode }[]`.
- `empty` (required) — `string`.

## MetricValue

A supplied number with its units on the supporting type step.

### Props

- `segments` (required) — `{ text: string; unit?: boolean }[]`.

## MetricDelta

Neutral direction marks never assume an increase is good or a decrease is an error.

### Props

- `direction` (required) — `'up' | 'down' | 'steady'`.
- `children` (required) — `ReactNode`.

## LiveCount

Unknown live counts remain absent; a measured zero is a real reading.

### Props

- `value` (required) — `number | null`.
- `label` (required) — `string`.

## Example — a controlled range

```tsx
import { MetricsList, MetricsPanel, MetricsPanelGrid, MetricsRange, MetricsSection } from '@misoto22/design/website'

<MetricsSection title="Library activity" caption="Sample data"
  action={<MetricsRange label="Period" value={range} onChange={setRange} options={[{ value: 'week', label: 'Week' }, { value: 'month', label: 'Month' }]} />}>
  <MetricsPanelGrid>
    <MetricsPanel title="Reading"><MetricsList label="Reading totals" empty="No readings" items={[
      { id: 'articles', label: 'Articles opened', value: range === 'week' ? '24' : '96' },
      { id: 'minutes', label: 'Minutes reading', value: range === 'week' ? '180' : '720' },
    ]} /></MetricsPanel>
    <MetricsPanel title="Collection"><MetricsList label="Collection totals" empty="No records" items={[
      { id: 'saved', label: 'Saved records', value: range === 'week' ? '7' : '28' },
      { id: 'notes', label: 'Notes written', value: range === 'week' ? '3' : '12' },
    ]} /></MetricsPanel>
  </MetricsPanelGrid>
</MetricsSection>
```

# SearchPalette

Search results, actions and a detail view in one accessible modal.

- Group: Website
- Import: `import { SearchPalette } from '@misoto22/design/website'`
- Page: https://ui.misoto22.com/components/search-palette/

## When to reach for it

Pass already-filtered results; the package owns the combobox and focus behavior.

## Best practices

### Do

- Supply localized labels, descriptive links and meaningful image alternatives.

### Don’t

- Do not put service credentials, routing logic or backend models inside presentation components.

## SearchPalette

Search, actions and an optional result detail inside one accessible modal.

### Props

- `open` (required) — `boolean`.
- `onOpenChange` (required) — `(open: boolean) => void`.
- `label` (required) — `string`.
- `inputLabel` (required) — `string`.
- `placeholder` (required) — `string`.
- `query` (required) — `string`.
- `onQueryChange` (required) — `(query: string) => void`.
- `groups` (required) — `SearchPaletteGroup[]`. Already filtered results; search and data access belong to the consumer.
- `emptyLabel` (required) — `ReactNode`.
- `labels` (required) — `{ close: string; navigate: string; select: string; back: string }`.
- `detail` — `{ label: string; content: ReactNode; onBack: () => void; onSubmit: () => void; submitDisabled?: boolean }`. Optional answer or detail view, with Escape returning to the results.
- `onContentLinkClick` — `() => void`.
- `onCloseAutoFocus` — `DialogContentProps['onCloseAutoFocus']`.

## SearchExcerpt

Render query highlights as text, never as consumer-supplied HTML.

### Props

- `segments` (required) — `ReadonlyArray<{ text: string; highlighted: boolean }>`.

## Example — host filtered results

```tsx
import { Button, Text } from '@misoto22/design'
import { SearchPalette } from '@misoto22/design/website'

<div className="min-h-[26rem]">
  <Button onClick={() => setOpen(true)}>Search the library</Button>
  <Text role="status" size="sm">{selected}</Text>
  <SearchPalette open={open} onOpenChange={setOpen} label="Library search" inputLabel="Search records"
    placeholder="Search titles" query={query} onQueryChange={setQuery} emptyLabel="No matching records"
    labels={{ close: 'Close search', navigate: 'Navigate', select: 'Select', back: 'Back to results' }}
    groups={[{ id: 'records', label: 'Records', items: titles.filter((title) => title.toLowerCase().includes(query.toLowerCase())).map((title) => ({
      id: title, title, onSelect: () => { setSelected(title); setOpen(false) },
    })) }]} />
</div>
```

# Content

Formatted code, clipboard actions, step sequences and rich-content elements.

- Group: Website
- Import: `import { StepSequence } from '@misoto22/design/website'`
- Page: https://ui.misoto22.com/components/content/

## When to reach for it

Render supplied text and highlighted code with consistent reading and copy affordances.

## Best practices

### Do

- Supply localized labels, descriptive links and meaningful image alternatives.

### Don’t

- Do not put service credentials, routing logic or backend models inside presentation components.

## StepSequence

A process rail whose source order, counters and annotations belong to the host.

### Props

- `spec` (required) — `StepSequenceSpec`.

Also accepts: `HTMLAttributes<HTMLElement>`.

## ContentTable

Keeps a rendered article table intact inside a keyboard-scrollable region.

Also accepts: `TableHTMLAttributes<HTMLTableElement>`.

## ExternalLinkMark

### Props

- `children` — `ReactNode` default `'↗'`.

## ClipboardButton

Confirms copying only after the browser accepts the clipboard write.

### Props

- `text` — `string`.
- `getText` — `() => string`. Read the current rendered code at activation, when the host owns highlighting.
- `copyLabel` (required) — `string`.
- `copiedLabel` (required) — `string`.
- `className` — `string`.

## CodePanel

A rendered-code panel for Markdown and MDX, preserving the host's highlighted nodes.

### Props

- `languageLabel` — `ReactNode`. A display label, already mapped from the host highlighter's language id.
- `preProps` — `HTMLAttributes<HTMLPreElement>`.
- `framed` — `boolean` default `true`. False when the host renderer has already supplied an enclosing figure.
- `copyLabel` (required) — `string`.
- `copiedLabel` (required) — `string`.
- `children` (required) — `ReactNode`.

## Example — a documented process

```tsx
import { CodePanel, StepSequence } from '@misoto22/design/website'

<div className="w-full">
  <StepSequence spec={{ label: 'Publish a reading list', caption: 'Review each step before publishing.', steps: [
    { n: '1', label: 'Collect', note: 'Gather the records.' },
    { n: '2', label: 'Review', note: 'Check titles and links.', anchor: true },
    { n: '3', label: 'Publish', note: 'Share the finished list.' },
  ] }} />
  <CodePanel languageLabel="JavaScript" copyLabel="Copy example" copiedLabel="Example copied">
    <code>{'const readingList = records.filter(record => record.reviewed)'}</code>
  </CodePanel>
</div>
```

# Actions

Share action menus and a scroll-to-top control.

- Group: Website
- Import: `import { ActionMenu } from '@misoto22/design/website'`
- Page: https://ui.misoto22.com/components/actions/

## When to reach for it

Connect generic accessible controls to host-owned share and scroll intentions.

## Best practices

### Do

- Supply localized labels, descriptive links and meaningful image alternatives.

### Don’t

- Do not put service credentials, routing logic or backend models inside presentation components.

## ActionMenu

A collision-aware action menu with roving focus and an optional native trigger.

### Props

- `label` (required) — `string`.
- `icon` (required) — `ReactNode`.
- `items` (required) — `ActionMenuItem[]`.
- `open` (required) — `boolean`.
- `onOpenChange` (required) — `(open: boolean) => void`.
- `side` — `'top' | 'bottom'` default `'bottom'`.
- `align` — `'start' | 'center' | 'end'` default `'center'`.
- `onTriggerAction` — `() => void`. A host-native action may replace the menu on a supported device.
- `className` — `string`.

## ScrollControl

Page position belongs to the host; visibility and a safe tab stop belong here.

### Props

- `label` (required) — `string`.
- `visible` (required) — `boolean`.
- `onActivate` (required) — `() => void`.

## Example — a record action menu

```tsx
import { Text } from '@misoto22/design'
import { ActionMenu } from '@misoto22/design/website'

<div className="flex items-center gap-4">
  <Text role="status">{read ? 'Read' : 'Unread'}</Text>
  <ActionMenu label="Record actions" icon={<RiMoreLine size={18} aria-hidden="true" />}
    open={open} onOpenChange={setOpen} items={[
      { id: 'read', label: 'Mark as read', onSelect: () => setRead(true) },
      { id: 'unread', label: 'Mark as unread', onSelect: () => setRead(false) },
    ]} />
</div>
```

# Conversation

Conversation threads, answers, citations, composers and floating chat surfaces.

- Group: Website
- Import: `import { ConversationLayout } from '@misoto22/design/website'`
- Page: https://ui.misoto22.com/components/conversation/

## When to reach for it

Compose a localized assistant interface while the host owns streaming, history and service calls.

## Best practices

### Do

- Supply localized labels, descriptive links and meaningful image alternatives.

### Don’t

- Do not put service credentials, routing logic or backend models inside presentation components.

## ConversationLayout

A reading-width conversation with a separate, sticky evidence rail.

### Props

- `evidence` (required) — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## ConversationFacts

### Props

- `items` (required) — `DescriptionListItem[]`.

Also accepts: `HTMLAttributes<HTMLDListElement>`.

## ConversationSuggestions

### Props

- `label` (required) — `string`.
- `items` (required) — `ConversationSuggestion[]`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## ConversationThread

Host owns turns and folding; this composition owns their hierarchy and controls.

### Props

- `label` (required) — `string`.
- `intro` — `{ title: ReactNode; description: ReactNode; suggestionsLabel: string; suggestions: ConversationSuggestion[] }`.
- `summary` — `ReactNode`.
- `controls` — `ConversationControl[]` default `[]`.
- `composer` (required) — `ReactNode`.
- `proposal` — `ReactNode`.
- `hasTurns` (required) — `boolean`.

Also accepts: `HTMLAttributes<HTMLElement>`.

## ConversationLog

### Props

- `compact` — `boolean`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## QuestionComposer

A controlled, labelled composer. Request limits and sending remain host concerns.

### Props

- `id` (required) — `string`.
- `label` (required) — `string`.
- `hideLabel` — `boolean`.
- `value` (required) — `string`.
- `onValueChange` (required) — `(value: string) => void`.
- `onSubmit` (required) — `() => void`.
- `inputRef` — `Ref<HTMLInputElement>`.
- `placeholder` — `string`.
- `maxLength` — `number`.
- `disabled` — `boolean`.
- `submitDisabled` — `boolean`.
- `pending` — `boolean`.
- `submitLabel` (required) — `string`.
- `hint` — `ReactNode`.
- `hideHint` — `boolean`.
- `counter` — `ReactNode`.
- `actions` — `ReactNode`.
- `compact` — `boolean`.

Also accepts: `Omit<HTMLAttributes<HTMLFormElement>, 'onSubmit'>`.

## ConversationTurn

### Props

- `title` (required) — `ReactNode`.
- `metadata` — `ReactNode`.
- `expanded` (required) — `boolean`.
- `onToggle` (required) — `() => void`.
- `bodyId` (required) — `string`.
- `preview` — `ReactNode`.

Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'title'>`.

## ConversationQuote

### Props

- `label` (required) — `string`.
- `compact` — `boolean`.

Also accepts: `HTMLAttributes<HTMLElement>`.

## ConversationAnswer

### Props

- `question` (required) — `ReactNode`.
- `questionLabel` (required) — `string`.
- `quote` — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## ConversationProse

Trusted React nodes from the host's sanitized answer parser, never raw model HTML.

## ConversationAnswerHeading

Model-generated headings are prose labels, so they do not alter the page outline.

## StreamingCaret

## ConversationSources

### Props

- `label` (required) — `string`.
- `count` (required) — `ReactNode`.
- `items` (required) — `ConversationSource[]`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## ActionProposal

### Props

- `label` (required) — `string`.
- `destination` (required) — `ReactNode`.
- `detail` — `ReactNode`.
- `approveLabel` (required) — `string`.
- `dismissLabel` (required) — `string`.
- `onApprove` (required) — `() => void`.
- `onDismiss` (required) — `() => void`.
- `approvalAttributes` — `Record<`data-${string}`, string>`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## ConversationLauncher

### Props

- `visible` (required) — `boolean`.
- `buttonRef` — `Ref<HTMLButtonElement>`.

Also accepts: `ButtonHTMLAttributes<HTMLButtonElement>`.

## ConversationDock

The host supplies placement, dismissal and stream state; the dock draws them.

### Props

- `label` (required) — `string`.
- `open` (required) — `boolean`.
- `card` (required) — `boolean`.
- `corner` (required) — `ConversationDockCorner`.
- `dragging` — `boolean`.
- `moving` — `boolean`.
- `panelRef` — `Ref<HTMLElement>`.
- `logRef` — `Ref<HTMLDivElement>`.
- `roomLink` (required) — `ReactElement`.
- `closeLabel` (required) — `string`.
- `onClose` (required) — `() => void`.
- `onHeaderPointerDown` — `(event: PointerEvent<HTMLElement>) => void`.
- `handles` — `ReactNode`.
- `proposal` — `ReactNode`.
- `notice` — `ReactNode`.
- `composer` (required) — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLElement>`.

## ConversationDockWelcome

### Props

- `lead` (required) — `ReactNode`.
- `suggestionsLabel` (required) — `string`.
- `suggestions` (required) — `ConversationSuggestion[]`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## ConversationResizeHandle

Keyboard equivalents for the host's pointer resize controller.

### Props

- `axis` (required) — `'size-vertical' | 'size-horizontal'`.
- `side` (required) — `'top' | 'bottom' | 'left' | 'right'`.
- `label` (required) — `string`.
- `dragging` (required) — `boolean`.
- `onStart` (required) — `(axis: 'size-vertical' | 'size-horizontal', event: PointerEvent<HTMLElement>) => void`.
- `onNudge` (required) — `(axis: 'size-vertical' | 'size-horizontal', delta: number) => void`.

## SelectionToolbar

Selection actions with a real toolbar's single tab stop and arrow navigation.

### Props

- `label` (required) — `string`.
- `actions` (required) — `SelectionToolbarAction[]`.
- `floating` (required) — `boolean`.
- `toolbarRef` — `Ref<HTMLDivElement>`.
- `style` — `CSSProperties`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## ConversationRoomLink

A router link keeps its own destination and behavior inside a standard action.

## Example — a local conversation

```tsx
import { ConversationAnswer, ConversationProse, ConversationThread, QuestionComposer } from '@misoto22/design/website'

<ConversationThread label="Library conversation" hasTurns={questions.length > 0}
  summary={`${questions.length} questions`}
  intro={questions.length ? undefined : {
    title: 'Explore the library', description: 'Try a question to preview the conversation layout.',
    suggestionsLabel: 'Start with', suggestions: [{ id: 'recent', label: 'What has been added recently?', onSelect: () => setQuestion('What has been added recently?') }],
  }}
  composer={<QuestionComposer id="conversation-example-question" label="Your question" value={question} onValueChange={setQuestion}
    placeholder="Ask about the collection" submitLabel="Add question" submitDisabled={!question.trim()}
    hint="Local demonstration; no service request is made."
    onSubmit={() => { if (question.trim()) { setQuestions((items) => [...items, question.trim()]); setQuestion('') } }} />}>
  {questions.map((item, index) => <ConversationAnswer key={`${index}-${item}`} questionLabel="Question" question={item}>
    <ConversationProse><p>The question is now part of this local conversation. A connected application would supply its answer here.</p></ConversationProse>
  </ConversationAnswer>)}
</ConversationThread>
```

# Evidence

Expandable traces, source stages, scores and timing summaries.

- Group: Website
- Import: `import { EvidenceStatus } from '@misoto22/design/website'`
- Page: https://ui.misoto22.com/components/evidence/

## When to reach for it

Explain supplied evidence and progress without exposing private prompts or service details.

## Best practices

### Do

- Supply localized labels, descriptive links and meaningful image alternatives.

### Don’t

- Do not put service credentials, routing logic or backend models inside presentation components.

## EvidenceStatus

### Props

- `state` (required) — `EvidenceState`.

Also accepts: `HTMLAttributes<HTMLElement>`.

## ActivityTrace

Tool and job traces share one presentation; the caller supplies truthful, localized labels.

### Props

- `label` (required) — `string`.
- `items` (required) — `ActivityTraceItem[]`.
- `waiting` — `boolean`.
- `waitingLabel` — `string`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## EvidencePanel

### Props

- `title` (required) — `string`.
- `eyebrow` (required) — `ReactNode`.
- `state` (required) — `EvidenceState`.
- `stateLabel` (required) — `string`.

Also accepts: `Omit<HTMLAttributes<HTMLElement>, 'title'>`.

## EvidenceSelection

### Props

- `label` (required) — `string`.
- `selectedId` (required) — `string | null`.
- `options` (required) — `{ id: string; label: string }[]`.
- `onSelect` (required) — `(id: string) => void`.

Also accepts: `Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'>`.

## EvidenceFacts

### Props

- `title` — `ReactNode`.
- `description` — `ReactNode`.
- `items` (required) — `DescriptionListItem[]`.

Also accepts: `Omit<HTMLAttributes<HTMLDivElement>, 'title'>`.

## EvidenceDisclosure

### Props

- `label` (required) — `string`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## EvidenceQuery

### Props

- `label` (required) — `string`.
- `query` (required) — `string`.
- `fingerprint` (required) — `string`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## EvidenceStages

## EvidenceStage

### Props

- `number` (required) — `string`.
- `state` (required) — `'idle' | 'active' | 'done'`.
- `stateLabel` (required) — `string`.
- `title` (required) — `ReactNode`.
- `description` (required) — `ReactNode`.
- `time` (required) — `ReactNode`.

Also accepts: `Omit<HTMLAttributes<HTMLLIElement>, 'title'>`.

## EvidenceScores

### Props

- `items` (required) — `EvidenceScore[]`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## SignalFigure

A decorative signature supplied by the host, kept out of the evidence's accessibility tree.

### Props

- `bars` (required) — `{ height: number; opacity: number }[]`.
- `running` — `boolean`.
- `settled` — `boolean`.
- `caption` (required) — `ReactNode`.
- `detail` (required) — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## EvidenceMeter

### Props

- `label` (required) — `string`.
- `value` — `number | null`. Leave unset while the total is unknown.
- `valueText` (required) — `ReactNode`.
- `detail` (required) — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## EvidenceDurations

### Props

- `label` (required) — `string`.
- `total` (required) — `number | null`.
- `totalText` (required) — `string`.
- `items` (required) — `EvidenceDuration[]`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## EvidenceSummary

### Props

- `items` (required) — `DescriptionListItem[]`.

Also accepts: `HTMLAttributes<HTMLDListElement>`.

## Example — a recorded trace

```tsx
import { ActivityTrace, EvidenceDisclosure, EvidenceFacts, EvidencePanel, EvidenceStage, EvidenceStages } from '@misoto22/design/website'

<EvidencePanel title="Reading-list evidence" eyebrow="Recorded sample" state="done" stateLabel="Complete">
  <EvidenceFacts title="Source summary" items={[
    { term: 'Collection', description: 'Studio library' },
    { term: 'Records reviewed', description: '12' },
  ]} />
  <EvidenceStages>
    <EvidenceStage number="1" state="done" stateLabel="Complete" title="Find records" description="Matched the supplied collection query." time="120 ms" />
    <EvidenceStage number="2" state="done" stateLabel="Complete" title="Review sources" description="Checked titles and publication dates." time="80 ms" />
  </EvidenceStages>
  <EvidenceDisclosure label="View recorded activity">
    <ActivityTrace label="Recorded activity" items={[
      { id: 'find', state: 'done', label: 'Collection lookup', summary: '12 records' },
      { id: 'review', state: 'done', label: 'Source review', summary: '12 records retained' },
    ]} />
  </EvidenceDisclosure>
</EvidencePanel>
```