# misoto22 design

> 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

Six attributes on the root re-point tokens the package already defines.
No component reads any of them, and none of them introduces a token.

- `data-mode`: light | dark
- `data-surface`: paper | warm | cool
- `data-radius`: sharp | soft | round
- `data-rules`: quiet | hairline | firm
- `data-type`: editorial | grotesk | bookish
- `data-motion`: still | calm | snappy
- `data-density`: comfortable | compact

Plus `data-accent`, which re-points the single token every chosen state reads.
An unset attribute is the default; nothing is anchored to `:root`, so an
axis set on any element applies to the subtree below it.

## Components

- [Button](https://ui.misoto22.com/components/button/llms.txt): The system’s action, as a pill that does not move on hover.
- [FloatingIconButton](https://ui.misoto22.com/components/floating-icon-button/llms.txt): A round action pinned to a screen corner.
- [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.
- [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.
- [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.
- [FigureBand](https://ui.misoto22.com/components/figure-band/llms.txt): A row of counted facts, divided by hairlines and nothing else.
- [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.
- [Field](https://ui.misoto22.com/components/field/llms.txt): A labelled form row: label, control, and the one message below it.
- [Input](https://ui.misoto22.com/components/input/llms.txt): A single line of text entry.
- [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.
- [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.
- [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.
- [NavItem](https://ui.misoto22.com/components/nav-item/llms.txt): A row in a sidebar.
- [Card](https://ui.misoto22.com/components/card/llms.txt): A bounded surface, with no shadow under it.
- [Table](https://ui.misoto22.com/components/table/llms.txt): A ruled data table — alignment, sorting and rules all per column.
- [AppShell](https://ui.misoto22.com/components/app-shell/llms.txt): Two columns on a desktop, a drawer on a phone.
- [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.
- [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.
- [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.
- [Collapsible](https://ui.misoto22.com/components/collapsible/llms.txt): One thing that opens, on its own.
- [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.

## Foundations

- [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 four radii.
- [Motion](https://ui.misoto22.com/foundations/motion/): One curve, three durations, and a reduced-motion rule that is not optional.

## Templates

- [Dashboard](https://ui.misoto22.com/templates/dashboard/): A console: a sidebar, a figure band, tabs, a filterable table and two job cards.
- [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.

## 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, as a pill that does not move on hover.

- 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.

## 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">
    <Copy size={16} strokeWidth={1.5} />
  </Button>
  <Button iconOnly aria-label="Share" variant="ghost">
    <Share2 size={16} strokeWidth={1.5} />
  </Button>
  <Button iconOnly aria-label="Open in a new tab">
    <ArrowUpRight size={16} strokeWidth={1.5} />
  </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.

## 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 — default

```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">
    <ArrowUp size={16} strokeWidth={1.5} />
  </FloatingIconButton>
</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.

## 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>
```

# Tag

A subject label — a topic, a technology, a filter facet.

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

## When to reach for it

Several sit together and the reader scans them. One fact about one record is a Badge.

## Accessibility

- Presentational. To filter with it, wrap it in a button and pass active, so the focus ring and the pressed state stay with the element that owns them.

## Tag

A subject label — a topic, a technology, a filter facet. 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. Presentational on purpose. To make a tag filter a list, wrap it in a button or a link at the call site and pass `active` — that keeps the focus ring, the pressed state and the keyboard handling with the element that actually owns them.

### Props

- `children` (required) — `ReactNode`.
- `active` — `boolean` default `false`. Renders the pressed/selected look. Pair with `aria-pressed` on a wrapper button.

Also accepts: `HTMLAttributes<HTMLSpanElement>`.

## 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>
```

# 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

## 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.

### 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>
```

# 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/

## Accessibility

- alt describes the person, not the picture. An empty string is correct when the name is already printed beside it.
- The initials are aria-hidden — read aloud 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.

### Props

- `src` — `string`.
- `alt` (required) — `string`. Describes the person, not the picture. Empty string is correct and deliberate when the name is already printed beside the avatar — repeating it makes a screen reader say it twice.
- `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>
```

# 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

## 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>
```

# 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

## 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.

### 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>
```

# 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/

## 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>
```

# Separator

A rule, in the three weights a monochrome page needs.

- 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.

## Accessibility

- role="none" by default. A rule that only groups things visually must not be announced.

## Separator

A rule. 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.

### 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.

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>
```

# 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

## Accessibility

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

## FigureBand

A row of counted facts, divided by hairlines and nothing else. A `<dl>`, because that is what this is: each cell is a term and its value, and a grid of `<div>`s tells a screen reader nothing about which number goes with which label. Each divider width names the cells that do NOT open a row rather than adding a rule and taking it back — an `undo` at equal specificity resolves on Tailwind's own sort order, which is not something a layout should depend on. Drawn this way, no edge is ever painted past the last column.

### 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' },
  ]}
/>
```

# 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.

## 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.

### 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.
- `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>
```

# 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.

## 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`, and nothing else. 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.

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>
```

# 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

## 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.

## 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–100. 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.
- `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'>`.

## Example — determinate

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

<div className="flex w-full flex-col gap-6">
  <Progress value={62} label="Uploading photos" showValue />
  <Progress label="Rebuilding the search index" />
</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.

## 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>
```

# 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.

## 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` — `LucideIcon`. Optional lucide icon, 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.

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

## Example — default

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

<EmptyState
  icon={Inbox}
  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>}
/>
```

# 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

## 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 .

Also accepts: `HTMLAttributes<HTMLElement>`.

## Example — not found

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

<ErrorState
  className="min-h-0 pt-0"
  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>}
/>
```

# Toast

A transient confirmation, mounted once near the app root.

- Group: Feedback
- Import: `import { Toast } 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.

## 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. `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>
```

# Field

A labelled form row: label, control, and the one message below it.

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

## 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.

## 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.

### 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.
- `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`.
- `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>
```

# 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

## 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>
```

# 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

## 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
export function Example() {
  return <Textarea className="max-w-md" rows={4} aria-label="Notes" placeholder="Tell us more…" />
}
```

# 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.

## 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. The trigger shows a value, and a value is not a name.

## 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.
- `placeholder` — `string` default `'Select…'`.
- `invalid` — `boolean`. Paints the resting border with `--danger` and reflects `aria-invalid`.
- `disabled` — `boolean`.
- `className` — `string`.
- `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>
```

# 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.

## 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.

### 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>
```

# 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.

## 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. 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>
```

# 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

## 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.

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>
```

# 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.

## 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>
```

# 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

## 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 logging a warning and shipping an unnamed modal.

### Props

- `title` — `ReactNode`. Heading text. When omitted, a visually-hidden title is rendered for a11y.
- `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 — default

```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>
```

# 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.

## 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.

## 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` — Radix has menu variants for both, 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` — `LucideIcon`. Optional leading icon, rendered before the label.
- `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 for a group of items.

## Example — default

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

# 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.

## 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 — default

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

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

  return (
<TooltipProvider>
  <div className="flex items-center gap-3">
    {/* The tooltip text, the icon and the button's own accessible name all
        change together. A copy control that looks identical before and
        after leaves the reader clicking it twice to be sure. */}
    <Tooltip content={copied ? 'Copied' : 'Copy to clipboard'}>
      <Button
        iconOnly
        aria-label={copied ? 'Copied' : 'Copy'}
        variant="secondary"
        onClick={() => setCopied(true)}
      >
        {copied ? (
          <Check size={16} strokeWidth={2} className="text-(--ok)" />
        ) : (
          <Copy size={16} strokeWidth={1.5} />
        )}
      </Button>
    </Tooltip>

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

# Tabs

One strip, several panels.

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

## 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

Re-export of `TabsPrimitive.Root`.

Radix Tabs root, re-exported as a typed passthrough.

## 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  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>
```

# 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”.

## 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>
```

# Breadcrumb

Where you are, as a path.

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

## 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”.

## 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".

### 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'

<Breadcrumb
  items={[
    { label: 'Home', href: '/' },
    { label: 'Components', href: '/components' },
    { label: 'Breadcrumb' },
  ]}
/>
```

# Pagination

Numbered pages, with the middle elided.

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

## 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.

## 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.

### 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'`.

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>
```

# 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

## 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` — `LucideIcon`. Optional leading icon (a lucide-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={Component} active>Components</NavItem>
  <NavItem href="#" icon={Palette}>Colour</NavItem>
  <NavItem href="#" icon={Type}>Typography</NavItem>
</nav>
```

# 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.

## 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. 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>
```

# Table

A ruled data table — alignment, sorting and rules all per column.

- Group: Surfaces
- 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.

## 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.

## 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. 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 .
- `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

### 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 — default

```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>
```

# 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

## 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.

## 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.

### 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".
- `children` (required) — `ReactNode`.

Also accepts: `HTMLAttributes<HTMLDivElement>`.

## Example — default

```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"
    brand={<span className="font-heading text-base">Console</span>}
    sidebar={
      <>
        <NavItem href="#" icon={Home} active>Overview</NavItem>
        <NavItem href="#" icon={Component}>Components</NavItem>
        <NavItem href="#" icon={Settings}>Settings</NavItem>
      </>
    }
    topbar={<span className="mono-meta text-(--ink-3-aa)">production</span>}
  >
    <Card>
      <CardBody>
        <CardTitle>Content well</CardTitle>
      </CardBody>
    </Card>
  </AppShell>
</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.

## 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: the trigger prints a value, and a value is not a name.

## 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.
- `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`.

## 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>
```

# 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.

## Accessibility

- The trigger prints the date in the visitor’s own locale, not a fixed dd/mm/yyyy.
- 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.
- `placeholder` — `string` default `'Pick a date'`.
- `disabled` — `boolean` default `false`.
- `disabledDates` — `ComponentProps<typeof Calendar>['disabled']`. Days the reader may not choose. Passed straight to the calendar.
- `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`.

## 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`.
- `placeholder` — `string` default `'Pick a range'`.
- `disabled` — `boolean` default `false`.
- `disabledDates` — `ComponentProps<typeof Calendar>['disabled']`.
- `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`.

## 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>
```

# Slider

A value chosen along a range.

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

## 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.
- 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.

### 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.
- `format` — `(value: number) => string` default `String`. Renders the value with a unit or a currency, e.g. `(n) => n + '%'`.

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>
```

# 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.

## 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.

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>
```

# 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.

## 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 — default

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

<Popover>
  <PopoverTrigger asChild>
    <Button variant="secondary">Filters</Button>
  </PopoverTrigger>
  <PopoverContent label="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>
      <Button size="sm">Apply</Button>
    </div>
  </PopoverContent>
</Popover>
```

# 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.

## 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.

### 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.

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>
```

# 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.

## 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` — `LucideIcon`.
- `destructive` — `boolean` default `false`.

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

## ContextMenuSeparator

Hairline divider between groups.

## ContextMenuLabel

Mono eyebrow heading for a group.

## Example — default

```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={Copy}>Copy link</ContextMenuItem>
    <ContextMenuItem icon={Download}>Download original</ContextMenuItem>
    <ContextMenuSeparator />
    <ContextMenuItem icon={Trash2} destructive>Delete</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.

## 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 — default

```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>
```

# 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

## 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` — `ReactNode`. A leading glyph. Pass the icon element, sized 16. 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.
- `children` (required) — `ReactNode`.

## 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={<Blocks />} meta="49" shortcut="C">
        Components
      </CommandItem>
      <CommandItem value="foundations" icon={<Ruler />} shortcut="F">
        Foundations
      </CommandItem>
      <CommandItem value="principles" icon={<Scale />} shortcut="P">
        Principles
      </CommandItem>
      <CommandItem value="templates" icon={<Compass />}>
        Templates
      </CommandItem>
    </CommandGroup>
    <CommandSeparator />
    <CommandGroup heading="Theme">
      <CommandItem value="light" icon={<Sun />} meta="current">
        Switch to light
      </CommandItem>
      <CommandItem value="dark" icon={<Moon />}>
        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>
```

# 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.

## Keyboard

- Enter / Space — Opens or closes it.

## Collapsible

Re-export of `CollapsiblePrimitive.Root`.

Radix Collapsible root, as a typed passthrough.

## 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>
```

# 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.

## 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 the system’s own Select, not the platform’s: a native list of a hundred years is a scroll rather than a choice, and it arrives styled by the operating system.
- 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.

Also accepts: `DayPickerProps`.

## Example — default

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

<Calendar
  mode="range"
  selected={range as never}
  onSelect={setRange as never}
  defaultMonth={new Date(2026, 8, 1)}
/>
```

# 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.

## 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.

## 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.

### 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 `'vertical'`.

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

## Example — default

```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>
```