# Miltinson Design System — full corpus

> Miltinson Design System — tokens, React 19 components, and AI patterns for the products built on it. Ink-led palette with one amber accent, sharp radii, hairline borders, WCAG AA by default. Packages: @elirobinson/tokens, @elirobinson/react, @elirobinson/ai-patterns (GitHub Packages registry).

## System constraints (machine-checkable ids from @elirobinson/ai-patterns/contracts)

- **no-barrel-imports** — Import via package subpaths only — @elirobinson/react/components/<tier>/<Name>, @elirobinson/react/hooks/<name>, @elirobinson/tokens/tokens.css. There are no barrel files; a bare @elirobinson/react import does not resolve. Check: Every import from an @elirobinson package names a subpath (components/*, hooks/*, styles/*.css, styles.css, tokens.css, tailwind.css, tokens.json, tokens-data, manifest, patterns, contracts, agents/*, testing/*).
- **no-foreign-component-libraries** — @elirobinson/react is the component vocabulary. A second library (MUI, Chakra, Ant Design, Mantine, HeroUI, Headless UI, DaisyUI) forks the system's behaviour and accessibility guarantees. Radix is already wrapped by the system, so importing it directly does the same. Check: No import resolves to a foreign component library, and no direct Radix import appears outside a repo's sanctioned gap-filler directory.
- **no-hardcoded-design-values** — Colour, radius, shadow and motion come from tokens — a mapped Tailwind utility, a .t-* class, or var(--token) in an arbitrary value. A literal cannot be re-pointed, so it silently stops responding to [data-theme="dark"] and to any token change. Check: No hex / rgb() / hsl() / oklch() literal, and no magic px or ms for radius, shadow or duration, appears in a className string, a style object, or a stylesheet that consumes values.
- **no-underlined-control-label** — A control does not underline its own label. An underline is the one visual signal a hyperlink owns; drawn under a button, chip, tab or pagination item it stops telling a reader whether the thing navigates or acts, and on a filled surface it reads as a link wearing a button. Emphasis on a control comes from the fill, the label weight, or a border. A link-styled button on no fill is a different, legitimate pattern and is out of scope. Check: No rule that paints a control's own filled surface also declares text-decoration: underline (or its longhand) on that control.
- **control-edge-contrast** — A control's edge comes from --border-control, not --border or --border-strong. The decorative pair measures 1.24:1 and 1.53:1 against --bg and is for surface seams — card edges, table rules, dividers, the edge of a floating panel — where nothing depends on seeing the line. --border-control is 3.64:1 light and 3.95:1 dark in the default palette, clearing the 3:1 SC 1.4.11 asks of the boundary that tells a user where an input, switch, chip, slider, stepper or segmented control is. Both tokens measure correctly on their own, so a per-token contrast sweep cannot see the mistake; it is a component reaching for the wrong one. Check: No rule whose selector names a control paints a border (border, border-color, or any side/logical longhand) with var(--border) or var(--border-strong). The test: if the border were invisible, would the user lose the control?
- **status-surface-foreground** — A status surface is three tokens that only work together. --status-success | warning | danger | info is the fill and is never text; --status-X-on is the text drawn on that fill; --status-X-fg is status-coloured text on --bg or --surface; --status-X-tint with --status-X-tint-edge is the quiet pair. --status-success and --status-warning stopped being brand aliases and now own palette-independent hues, so a foreground that flips with the theme — var(--fg-inverse), or the legacy var(--fg-on-signal) — no longer tracks the fill it sits on and misses 4.5:1 in whichever theme it was not measured in. --status-warning is 1.87:1 against --bg in light, a documented SC 1.4.11 exception that holds only while the hue is a fill and the text on it carries the contrast; as a line it is the whole signal, so a warning fill or rule is edged with --status-warning-border (3.76:1 light, 11.22:1 dark). --fg-on-signal survives only as an alias of --accent-fg and collapses under any non-default palette. Check: No rule that paints a status fill (background or background-color set to var(--status-success | warning | danger | info)) also sets color to var(--fg-inverse) or var(--fg-on-signal) — the text on a status fill is var(--status-<state>-on). No border, outline or column-rule colour is var(--status-warning) — an edge is var(--status-warning-border). No value anywhere, including a custom-property definition, references var(--fg-on-signal). The -on, -fg, -tint, -tint-edge and -border members are the fixes and are never the defect.
- **forward-ref** — Every component that renders a focusable or interactive native element uses forwardRef, forwarding to the outermost interactive element the component owns. Check: The component is wrapped in React.forwardRef and the forwarded ref resolves to the interactive DOM node (or a documented handle, e.g. VirtualListHandle).
- **touch-target-primary** — Primary interactive controls at their default size — buttons, pagination items, segmented-control options, nav items — have a minimum touch target of var(--target) square (44x44px, and what every primary control gets under data-platform="mobile" and on a coarse-pointer phone; the dense tier is excluded from that floor by name rather than inflated to it, because it is already measured against 24x24). Reach for the token, not the number: a literal is what no-hardcoded-design-values forbids, and it cannot be re-pointed by the platform dial. Where visual density matters, keep the painted glyph small and expand the hit area with padding or a bounded overlay rather than inflating the visible control. A control whose whole purpose is to be compact belongs under touch-target-dense instead; padding it back up to var(--target) only turns it into the default size and removes the reason the compact variant exists. Check: The computed hit area of each primary control is at least var(--target) square, measured on whichever single surface receives the interaction — the control itself, or a <label> that activates it. A label counts only if it is var(--target) square on its own; a control and its label are not added together across the gap between them. Controls nothing routes to (anything behind an open modal dialog) are not measured rather than being reported as 1x1. Anything matching touch-target-dense is measured against that contract's floor instead of this one's — it is a different floor, not an exemption from measurement.
- **touch-target-dense** — Deliberately compact controls follow shadcn/MUI-scale sizing rather than var(--target), and are measured against var(--target-min) (24x24, WCAG 2.2 AA SC 2.5.8) instead. This is a second floor, not an exemption: a dense control below 24x24 fails, under touch-target-dense. Three kinds qualify: dense inline affordances — a chip's remove glyph, a search field's clear button, rating stars, calendar day cells — a component's explicitly compact size variant, of which Button's size="sm" (36px) is the one the system ships, and a chip that is a control (<a class="ds-chip">, <button class="ds-chip">) at 32px. Reference for the painted scale: MUI Chip is 32px tall (24px small) with a 22px (16px small) delete icon; shadcn Badge is ~20px tall with 12px icons; shadcn Button sm is 36px. 36px clears WCAG 2.2 AA (SC 2.5.8, 24x24) with margin — var(--target) is AAA (SC 2.5.5) and this system's stricter default, not the standard. Choosing a compact variant is a design decision about density; it is not a licence to make a page's primary action small, and it is not a way to stop a control being measured — the 24x24 floor still applies and there is no marker below it. Check: The computed hit area of each compact control is at least var(--target-min) square, measured the same way touch-target-primary measures — on the control itself or on a <label> that activates it. The painted control stays at the shadcn/MUI reference scale; where the two differ, the hit area is expanded with padding or a bounded overlay rather than by inflating the paint, and that overlay must still satisfy hit-area-no-overlap. Compact controls are measured against this floor instead of touch-target-primary's, not exempted from measurement.
- **hit-area-no-overlap** — An expanded hit area must never overlap sibling content. Bound the hit area — for example stretch it to the container's height, not a symmetric negative inset — so a control's overlay cannot cover an adjacent label. Check: No interactive hit area intersects a sibling element's painted or interactive area.
- **ui-copy** — Functional UI copy — errors, empty states, helper and hint text, toasts, labels, button text, tooltips, confirmations, validation — is chrome. It states the fact, then the consequence, then the action, and stops. No unverifiable frequency claims ("almost always"), blame attribution ("on their side", "check your connection"), filler pacing ("in a moment", "hang tight"), unprompted reassurance or apology ("don't worry", "we'll sort it out"), escalation paths nobody asked for, or enthusiasm and exclamation marks. Reassurance is allowed only where it answers a question the reader is actually asking, and only as a fact: "You have not been charged." Past two short sentences, functional copy is explaining, reassuring or selling. This governs chrome only — a product's editorial voice in marketing prose, conversational surfaces and written deliverables is content, is a deliberate design decision, and is out of scope; where a surface mixes the two, the chrome follows this and the content is left alone. Check: No banned phrase appears in a copy prop (title, description, label, placeholder, helperText, error, tooltip, aria-label and friends) or in the children of a chrome component (Alert, Toast, Tooltip, Callout, Banner, EmptyState, FormMessage, …). Editorial content is out of scope and is not checked.
- **tier-boundary** — Components live under packages/react/src/components/<tier>/. The tiers are not a fixed list — they are read off that directory layout into @elirobinson/react/manifest's `tiers`, which is the only roster; check it rather than assuming the set you last saw. Most tiers answer "how much is assembled here": a component that renders into a portal, traps focus, or manages open/closed state across multiple sub-elements is an organism; one assembled from 2+ atoms with no such orchestration is a molecule; otherwise an atom. `ai` is the exception and answers what the component is for. A component belongs in `ai/` when it has no meaning outside an assistant surface — a turn-taking message log, a token-by-token streaming affordance. The test is the domain, not the shape: if you can describe the component without saying "assistant", "model" or "streaming", it is not an `ai` component, whatever produced the content it renders. A card that happens to show a model's reply is still a Card. `ai/` inherits every other constraint here unchanged; being a tier buys a directory and nothing else. Check: The component's directory is one of the tiers @elirobinson/react/manifest reports, and matches the boundary rule for its behavior — its domain for `ai`, how much it assembles otherwise.

UI contracts: minimum touch target var(--target) — 44x44. Write the token, not the pixel value: a literal is what no-hardcoded-design-values forbids, and it cannot be re-pointed by data-platform="mobile". var(--target-lg) is 56px, for the one action a thumb reaches for without looking. (scoped — see touch-target-dense). Dense floor: var(--target-min) — 24x24, WCAG 2.2 AA SC 2.5.8 Target Size Minimum. The floor a deliberately compact control is measured against instead of var(--target), not a size it is exempted to: a dense affordance below 24x24 is a violation under touch-target-dense. 44x44 is AAA (SC 2.5.5) and this system's stricter default, which is what makes the second floor a relaxation to the standard rather than a discount off it. There is no third tier below this one and no per-element opt-out — 24x24 is the standard's own floor, so there is nothing left to be held to underneath it. Focus-visible required: true, contrast level WCAG AA.

## Import rules

There are no barrel files. Every import names a subpath:
  import '@elirobinson/tokens/tokens.css';
  import '@elirobinson/react/styles.css';
  import { Button } from '@elirobinson/react/components/atoms/Button';
  import { useRovingFocus } from '@elirobinson/react/hooks/useRovingFocus';
A bare import from '@elirobinson/react' does not resolve.

## Design tokens (every token stylesheet @elirobinson/tokens declares, via readTokenStylesheets())

- `--n-h: 247` — neutral hue
- `--n-mult: 1` — neutral chroma multiplier — 1 near-achromatic, 1.6 charcoal
- `--signal-50: oklch(97.5% 0.025 75)`
- `--signal-100: oklch(94% 0.055 75)`
- `--signal-200: oklch(89% 0.1 75)`
- `--signal-300: oklch(83% 0.14 72)`
- `--signal-400: oklch(78% 0.16 68)`
- `--signal-500: oklch(72.5% 0.175 65)` — primary — Miltinson Amber
- `--signal-600: oklch(63% 0.165 55)`
- `--signal-700: oklch(52% 0.145 45)`
- `--signal-800: oklch(40% 0.115 40)`
- `--signal-900: oklch(28% 0.08 38)`
- `--anchor-50: oklch(96% 0.018 165)`
- `--anchor-100: oklch(91% 0.035 165)`
- `--anchor-200: oklch(82% 0.055 162)`
- `--anchor-300: oklch(70% 0.075 160)`
- `--anchor-400: oklch(55% 0.085 158)`
- `--anchor-500: oklch(42% 0.08 156)` — primary — Miltinson Forest
- `--anchor-600: oklch(34% 0.065 156)`
- `--anchor-700: oklch(26% 0.05 156)`
- `--anchor-800: oklch(19% 0.035 156)`
- `--anchor-900: oklch(13% 0.025 156)`
- `--accent: var(--signal-500)` — fill — 2.53:1, fill-only
- `--accent-hover: var(--signal-400)` — fill — 2.06:1, fill-only
- `--accent-press: var(--signal-600)` — fill — 3.69:1
- `--accent-fg: var(--ink-1000)` — on the three fills: 8.30 / 10.17 / 5.69
- `--accent-tint: var(--signal-50)` — with --accent-ink: 8.96:1
- `--accent-ink: var(--signal-800)` — 9.69:1
- `--accent-ink-inverse: var(--signal-400)` — on --bg-inverse — 10.17:1
- `--anchor: var(--anchor-500)` — fill — 8.13:1
- `--anchor-hover: var(--anchor-400)` — fill — 4.65:1
- `--anchor-press: var(--anchor-600)` — fill — 11.41:1
- `--anchor-fg: var(--ink-0)` — on the three fills: 8.13 / 4.65 / 11.41
- `--anchor-tint: var(--anchor-50)` — with --anchor-ink: 10.23:1
- `--anchor-ink: var(--anchor-600)` — 11.41:1
- `--focus-ring: var(--ink-1000)` — 21:1 — high-contrast focus, ink-on-bg
- `--link: var(--ink-1000)` — 21:1
- `--link-hover: var(--signal-800)` — 9.69:1 — was --signal-700 at 5.86:1
- `--link-visited: var(--ink-700)` — 13.62:1
- `--link-on-fill: currentColor`
- `--status-success: oklch(51.9% 0.145 150)` — fill — 5.17:1 light, 4.06:1 dark
- `--status-success-on: var(--ink-0)` — on the fill — 5.17:1
- `--status-success-fg: oklch(44% 0.12 150)` — 7.35:1 on --bg
- `--status-success-tint: oklch(96.5% 0.03 150)` — with -fg: 6.71:1
- `--status-success-tint-edge: oklch(88% 0.06 150)` — decorative hairline on the tint
- `--status-warning: oklch(80.25% 0.16 85)` — fill — 1.87:1 light, 11.22:1 dark — must be edged
- `--status-warning-border: oklch(61.9% 0.14 70)` — 3.76:1 — the edge that carries SC 1.4.11
- `--status-warning-on: var(--ink-1000)` — on the fill — 11.22:1
- `--status-warning-fg: oklch(47% 0.105 72)` — 6.97:1 on --bg
- `--status-warning-tint: oklch(96.5% 0.05 85)` — with -fg: 6.24:1
- `--status-warning-tint-edge: oklch(87% 0.1 85)` — decorative hairline on the tint
- `--status-danger: oklch(54.85% 0.2 27)` — fill — 5.41:1 light, 3.88:1 dark
- `--status-danger-on: var(--ink-0)` — on the fill — 5.41:1
- `--status-danger-fg: oklch(47% 0.19 27)` — 7.54:1 on --bg
- `--status-danger-tint: oklch(96.5% 0.025 27)` — with -fg: 6.69:1
- `--status-danger-tint-edge: oklch(87% 0.07 27)` — decorative hairline on the tint
- `--status-info: oklch(54% 0.155 250)` — fill — 5.06:1 light, 4.15:1 dark
- `--status-info-on: var(--ink-0)` — on the fill — 5.06:1
- `--status-info-fg: oklch(46% 0.14 250)` — 7.09:1 on --bg
- `--status-info-tint: oklch(96.5% 0.03 250)` — with -fg: 6.38:1
- `--status-info-tint-edge: oklch(87% 0.07 250)` — decorative hairline on the tint
- `--chart-1: oklch(62% 0.13 25)` — 3.87:1
- `--chart-2: oklch(62% 0.13 205)` — 3.34:1
- `--chart-3: oklch(62% 0.13 115)` — 3.55:1
- `--chart-4: oklch(62% 0.13 295)` — 3.81:1
- `--chart-5: oklch(62% 0.13 70)` — 3.74:1
- `--chart-6: oklch(62% 0.13 250)` — 3.63:1
- `--chart-7: oklch(62% 0.13 160)` — 3.42:1
- `--chart-8: oklch(62% 0.13 340)` — 3.90:1
- `--chart-grid: var(--border-strong)` — decorative — 1.53:1
- `--chart-axis: var(--border-control)` — 3.64:1 — the axis is a meaningful line
- `--ink-0: #ffffff` — pure white
- `--ink-50: oklch(98.4% calc(0.002 * var(--n-mult)) var(--n-h))` — off-white surface
- `--ink-100: oklch(96.2% calc(0.003 * var(--n-mult)) var(--n-h))` — hairline backgrounds
- `--ink-200: oklch(92.8% calc(0.004 * var(--n-mult)) var(--n-h))` — dividers
- `--ink-300: oklch(86% calc(0.005 * var(--n-mult)) var(--n-h))` — borders
- `--ink-400: oklch(70% calc(0.006 * var(--n-mult)) var(--n-h))` — disabled / placeholder
- `--ink-500: oklch(55% calc(0.008 * var(--n-mult)) var(--n-h))` — tertiary text
- `--ink-600: oklch(42% calc(0.01 * var(--n-mult)) var(--n-h))` — secondary text
- `--ink-700: oklch(30% calc(0.01 * var(--n-mult)) var(--n-h))` — high-contrast secondary
- `--ink-800: oklch(20% calc(0.01 * var(--n-mult)) var(--n-h))` — near-black surfaces
- `--ink-900: oklch(12% calc(0.008 * var(--n-mult)) var(--n-h))` — deep surface
- `--ink-950: oklch(6% calc(0.006 * var(--n-mult)) var(--n-h))` — card on dark
- `--ink-1000: #000000` — pure black
- `--bg: var(--ink-0)` — page background
- `--bg-subtle: var(--ink-50)` — zebra / panel
- `--bg-muted: var(--ink-100)` — code blocks, inset wells
- `--bg-inverse: var(--ink-1000)` — dark hero, footer
- `--surface: var(--ink-0)` — cards
- `--surface-2: var(--ink-50)` — nested cards
- `--surface-3: var(--ink-100)` — deeper inset
- `--border: var(--ink-200)` — decorative hairline — 1.24:1
- `--border-strong: var(--ink-300)` — decorative, emphasized — 1.53:1
- `--border-inverse: oklch(100% 0 0 / 0.12)` — on dark
- `--border-control: oklch(62% calc(0.008 * var(--n-mult)) var(--n-h))` — 3.64:1 on --bg — control edges, SC 1.4.11
- `--fg: var(--ink-1000)` — primary text
- `--fg-1: var(--ink-1000)` — alias
- `--fg-2: var(--ink-600)` — secondary text
- `--fg-3: var(--ink-500)` — tertiary / meta
- `--fg-4: var(--ink-400)` — decorative / non-informational grey — 2.67:1
- `--fg-disabled: var(--ink-500)` — 4.85:1 — disabled control text
- `--fg-inverse: var(--ink-0)` — on dark
- `--fg-inverse-2: var(--ink-300)` — secondary on --bg-inverse — 13.73:1
- `--fg-inverse-3: var(--ink-400)` — tertiary / meta on --bg-inverse — 7.87:1
- `--fg-on-signal: var(--accent-fg)`
- `--target-min: 24px` — absolute AA floor, SC 2.5.8 — the dense tier, on every platform
- `--target: 44px` — primary controls, and every primary control on mobile
- `--target-lg: 56px` — thumb-zone primary action
- `--safe-t: env(safe-area-inset-top, 0px)` — @kind spacing
- `--safe-r: env(safe-area-inset-right, 0px)` — @kind spacing
- `--safe-b: env(safe-area-inset-bottom, 0px)` — @kind spacing
- `--safe-l: env(safe-area-inset-left, 0px)` — @kind spacing
- `--scrim: oklch(0% 0 0 / 0.56)`
- `--font-sans: var(--ds-font-sans-override, 'Geist', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif)`
- `--font-display: var(--ds-font-display-override, 'Geist', ui-sans-serif, system-ui, -apple-system, sans-serif)`
- `--font-mono: var(--ds-font-mono-override, 'JetBrains Mono', ui-monospace, 'SF Mono', Menlo, Consolas, monospace)`
- `--fs-3xs: 10px`
- `--fs-2xs: 11px`
- `--fs-xs: 12px`
- `--fs-sm: 14px`
- `--fs-md: 16px` — base
- `--fs-lg: 18px`
- `--fs-xl: 20px`
- `--fs-2xl: 24px`
- `--fs-3xl: 30px`
- `--fs-4xl: 38px`
- `--fs-5xl: 48px`
- `--fs-6xl: 64px`
- `--fs-7xl: 84px`
- `--fs-8xl: 112px`
- `--lh-tight: 1.05`
- `--lh-snug: 1.2`
- `--lh-normal: 1.5`
- `--lh-relaxed: 1.65`
- `--tr-tight: -0.025em`
- `--tr-snug: -0.015em`
- `--tr-normal: 0em`
- `--tr-wide: 0.04em`
- `--tr-caps: 0.08em`
- `--fw-light: 300`
- `--fw-regular: 400`
- `--fw-medium: 500`
- `--fw-semibold: 600`
- `--fw-bold: 700`
- `--fw-black: 800`
- `--space-0: 0`
- `--space-px: 1px`
- `--space-1: 4px`
- `--space-2: 8px`
- `--space-3: 12px`
- `--space-4: 16px`
- `--space-5: 20px`
- `--space-6: 24px`
- `--space-7: 32px`
- `--space-8: 40px`
- `--space-9: 48px`
- `--space-10: 64px`
- `--space-11: 80px`
- `--space-12: 96px`
- `--space-13: 128px`
- `--space-14: 160px`
- `--space-15: 192px`
- `--radius-none: 0`
- `--radius-xs: 2px`
- `--radius-sm: 4px` — default for inputs, buttons
- `--radius-md: 6px` — cards
- `--radius-lg: 10px` — modals
- `--radius-xl: 16px` — heroes
- `--radius-pill: 999px` — tags only
- `--shadow-xs: 0 1px 0 0 oklch(0% 0 0 / 0.04)`
- `--shadow-sm: 0 1px 2px 0 oklch(0% 0 0 / 0.06), 0 0 0 1px oklch(0% 0 0 / 0.04)`
- `--shadow-md: 0 4px 12px -2px oklch(0% 0 0 / 0.08), 0 0 0 1px oklch(0% 0 0 / 0.04)`
- `--shadow-lg: 0 12px 32px -8px oklch(0% 0 0 / 0.14), 0 0 0 1px oklch(0% 0 0 / 0.05)`
- `--shadow-xl: 0 24px 56px -12px oklch(0% 0 0 / 0.2), 0 0 0 1px oklch(0% 0 0 / 0.05)`
- `--shadow-inset: inset 0 1px 0 0 oklch(0% 0 0 / 0.04)`
- `--shadow-focus: 0 0 0 2px var(--bg), 0 0 0 4px var(--focus-ring)`
- `--ease-out: cubic-bezier(0.22, 1, 0.36, 1)`
- `--ease-in-out: cubic-bezier(0.65, 0, 0.35, 1)`
- `--ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1)`
- `--dur-instant: 80ms`
- `--dur-fast: 140ms`
- `--dur-normal: 220ms`
- `--dur-slow: 420ms`
- `--container-sm: 640px`
- `--container-md: 768px`
- `--container-lg: 1024px`
- `--container-xl: 1280px`
- `--container-2xl: 1440px`
- `--gutter: max(20px, round(4vw, 4px))`
- `--z-base: 0`
- `--z-raised: 10`
- `--z-sticky: 100`
- `--z-overlay: 1000`
- `--z-modal: 1100`
- `--z-toast: 1200`
- `--z-tooltip: 1300`

## Foundations

# Color

The palette is ink-led: black type on white surfaces, hairline borders, and one loud color,
Miltinson Amber. Every value on this page is read live from the
token stylesheets `@elirobinson/tokens` ships — `tokens.css` and the `palettes.css` it imports —
so the swatches and contrast ratios below cannot drift from what the package ships. They are the
default palette in its light theme; the palette is a `data-palette` attribute on the root element,
and nothing on this page is hardcoded per brand.

## How to think about it

- **Ink does the work.** Headings are pure black, body text near-black, and hierarchy
  comes from the ink scale — not from adding color.
- **Amber is the only loud color.** Primary CTAs, the dot in the wordmark, eyebrow
  underlines, key stats, link hovers. If two things on a screen are amber, one of them
  is wrong.
- **Forest is the quiet second.** Trust marks and the earnest surfaces (coaching guides). It is
  no longer what success is made of — status has its own four hues, which stay put when the
  palette changes.
- **No gradients, no purple.** Flat color only.

Reference semantic tokens (`--fg`, `--surface`, `--accent`) in components, never raw
scale values (`--ink-500`) — the semantic layer is what makes a future dark theme
possible without touching component code.

## Ink — the neutral scale

## Signal — Miltinson Amber

Warm, craftsman, honest. `--signal-500` is the brand amber; the darker steps exist
because raw amber fails AA on white — anything amber a user has to read uses `--accent-ink`,
which the default palette points at `--signal-800`.

## Anchor — Miltinson Forest

## Semantic tokens

These are the names components actually use. Each references a base-scale value, so
retuning the palette is a one-line change per token.

## Contrast

Computed from the live token values with WCAG 2.x math. Two pairings deserve a note. Raw amber
(`--accent`) is a fill and fails AA as text on white — which is why button labels use
`--accent-fg` and why anything amber that has to be read uses `--accent-ink`. And
`--status-warning` is the documented exception: yellow cannot clear 3:1 on white and still read
as yellow, so a warning fill or rule must be edged with `--status-warning-border`, which carries
that 3:1 itself. Warning text is `--status-warning-fg`, never the fill.

# Typography

Two families do everything: Geist for the interface, JetBrains Mono for code, eyebrows, pricing,
and anywhere numbers need to line up. Sizes, weights, and spacing below are read live from
`@elirobinson/tokens/tokens.css`.

## Families

Geist covers Latin, Latin-Extended, Cyrillic, and Greek. The package currently loads both
families from Google Fonts via `@import` — the stylesheet's own comment flags this as a
placeholder: if you have licensed `.woff2` files, self-host them and replace the import.

Each family reads a `--ds-font-*-override` before its own stack, which is how an app whose
framework loads the fonts re-points them. `next/font` in particular generates a hashed
family name and exposes it only as a CSS variable, so the literal `'Geist'` above matches
nothing it loaded:

```css
:root {
  --ds-font-sans-override: var(--font-geist-sans);
  --ds-font-mono-override: var(--font-geist-mono);
}
```

Leave it unset and you get the stack shown above. See
[Installation](/installation#override-a-token) for the cascade rule that applies to every
other token.

## The scale

A perfect-fourth-ish ramp on a 16px base. Body text never goes below `--fs-md` — the
smaller steps are for captions, eyebrows, and metadata, not paragraphs.

## Weights

400 for body, 500 for UI labels, 600 for headings, 700+ for display peaks. Light (300)
exists but earns its place rarely.

## Line height

Body text sits at 1.65 — relaxed and forgiving on purpose; accessibility-first beats
dense. Display type tightens to 1.05.

## Tracking

Display sizes tighten (−0.025em), body stays neutral, and mono eyebrows open up
(+0.08em, uppercase).

## Rules that keep it coherent

- **Sentence case for headings.** Title Case is reserved for product names and the
  tagline.
- **Mono for numbers that compare** — tables, pricing, stats — with tabular figures.
- **`clamp()` for display sizes** so long translations don't break layouts (the `t-display-*`
  classes in tokens.css already do this).
- **Never justify text.** Left-aligned, ragged right.

# Spacing

A 4px base, 8px-friendly, sixteen steps. Use the scale and nothing else. A value off the scale
has nothing to re-point when the scale changes, so it survives every redesign unchanged and
wrong.

## The scale

## How the scale gets used

- **Generous vertical rhythm.** Major sections on landing pages get `--space-13` (128px)
  between them.
- **Tight horizontal density inside cards.** `--space-4` (16px) is the default inner
  padding for compact components; `--space-6` (24px) for roomier cards.
- **Gaps within a control cluster:** `--space-2` or `--space-3`. Between distinct
  groups: `--space-6` and up.
- When in doubt, take the larger step for vertical space and the smaller for
  horizontal.

## Layout containers

Content clamps at `--container-xl` (1280px); editorial body copy clamps tighter at
`--container-md` (768px) for a readable measure. `--gutter` scales with the viewport.

## Asymmetry is encouraged

7–5 and 8–4 column splits beat 6–6. A perfectly symmetric layout reads as template-made;
the brand prefers a deliberate lean.

# Radii and elevation

Sharp by default, and borders do most of the work shadows usually do. A card in this system is a
1px hairline on white — not a floating drop shadow.

## Radii

4px for buttons and inputs, 6px for cards, 10px for modals. The pill radius is reserved
for tags — category labels like "Food" or "Education" — and never for CTAs, where it
would read as a tag.

## Shadows

The scale is deliberately restrained. Default cards take `--shadow-sm`, a hairline tint.
`--shadow-lg` and up are for modals only.
`--shadow-inset` marks input wells.

## Borders

- `--border` (1px hairline) is the primary divider — between cards, table rows,
  sections.
- `--border-strong` for emphasis and hover states.
- On dark surfaces, `--border-inverse` (12% white) keeps hairlines visible without
  glowing.

## What to avoid

- No glassmorphism, no frosted panels — the one sanctioned blur is the sticky header
  at 92% white when scrolled.
- No left-border accent stripes on cards.
- No stacking shadows to fake depth; if hierarchy isn't reading, fix the spacing.

# Motion

Motion here confirms what happened. Hovers answer in 140ms, state changes in 220ms, and nothing
bounces across the screen.

## Durations

## Easings

`--ease-out` is the default for almost everything. `--ease-spring` is reserved for icon
micro-interactions — a check mark settling into place — never for panels or pages.

## Try the durations

## Rules

- **Hovers:** `--dur-fast`, color/background only — no scale, no opacity tricks.
- **State changes** (open, select, expand): `--dur-normal` with `--ease-out`.
- **No bouncy page transitions, no parallax.**
- **`prefers-reduced-motion` is honored globally** — tokens.css collapses every
  transition and animation to 0.01ms when the user asks for reduced motion. You get
  this for free; don't opt out of it.

# Accessibility

The rules below are applied by the tokens and the components rather than checked afterwards.
Import `tokens.css` and the focus ring and the reduced-motion handling arrive with it; the rest
is what a component has to clear before it ships.

## The standard

- **WCAG 2.1 AA at minimum.** Every color pairing the system ships passes AA for its
  intended use — the [color page](/foundations/color) computes the ratios live so the
  claim stays checkable.
- **16px minimum body text.** The smaller type steps exist for captions and metadata,
  never paragraphs.
- **Visible focus, always.** A high-contrast ink ring (`2px solid var(--focus-ring)`,
  2px offset) on every interactive element, applied globally via `:focus-visible` in
  tokens.css. It's ink on both light and dark — never amber on amber.
- **Reduced motion honored globally.** tokens.css collapses all animation under
  `prefers-reduced-motion: reduce`.

## Touch targets are scoped, not blanket

Two classes of control, two rules:

- **Primary interactive controls** — buttons, pagination items, segmented-control
  options, nav items — get a minimum **44×44px** hit area. Where visual density
  matters, the painted control stays small and the hit area expands via padding or a
  bounded overlay.
- **Dense inline affordances** — a chip's remove glyph, a search field's clear button,
  rating stars, calendar day cells — follow the shadcn/MUI dense scale instead. A 44px
  remove button inside a 24px chip is how you get overlapping hit areas.
- **In both cases** an expanded hit area must never overlap sibling content — a hit
  area that covers a neighboring label fires the wrong action from a correct click.

## Keyboard, by construction

- Native elements first: `<button>`, `<input>`, `<dialog>` — their keyboard behavior
  comes from the platform, not a re-implementation.
- Composite widgets (tabs, segmented controls) use a roving tabindex via
  `useRovingFocus`; listbox popups (combobox, command palette) keep DOM focus in the
  input and track the highlighted option with `aria-activedescendant` via
  `useActiveDescendant`.
- Every component page documents its exact keyboard contract in its Accessibility
  section — those contracts are backed by the component test suites.

## What the system can't do for you

- **Labels.** Icon-only buttons need `aria-label`; images need real `alt` text.
- **Reading order.** The DOM order is the reading order — keep it sensible before
  reaching for CSS ordering.
- **Content.** Plain language is an accessibility feature; see
  [voice and content](/guidelines/voice).

The [audit prompt](/build-with-ai) packages these checks for an agent to run against a
page of your app.

## Components

### ChatMessage (ai)

A single turn in a conversation: avatar, optional attribution, content, and actions.

Import: `import { ChatMessage } from '@elirobinson/react/components/ai/ChatMessage';`
Styles: @elirobinson/react/styles/ai/ChatMessage.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| avatar | `ReactNode` | yes | — | The avatar mark. Required — the system derives nothing from the variant. |
| actions | `ReactNode` | no | — | Turn-level affordances, as a node. |
| name | `string` | no | — | Who is speaking. This, not the avatar, is what identifies the turn. |
| timestamp | `string` | no | — | Pre-formatted time string. Formatting is the product's call, not the system's. |
| variant | `"sent" \| "received"` | no | received | Which side of the conversation this turn is. Default 'received'. |

Constraints: no-barrel-imports, forward-ref (see System constraints)

> **Deprecated.** Use `Message` from `@elirobinson/ai-elements`. It takes a `UIMessage`
> role directly, renders markdown through Streamdown, and carries branch navigation. This
> component still works and is removed on the next major.

#### When to use it

`ChatMessage` is one turn in a conversation: an avatar column, optional attribution, the
content, and optional turn-level affordances. Put turns inside a `ChatThread`, which owns
the announcement contract; the message itself is layout and typography.

`variant` is `received` by default. A `sent` turn reads as settled through `--fg-2` — a
real foreground token that follows the theme and holds its contrast — never through
`opacity`, which would drop body copy to roughly 3.4:1 and fail SC 1.4.3 while looking
merely quiet.

#### Two required decisions

`avatar` is a **required** node, and there is deliberately no fallback derived from
`variant`. A system that invented a mark for the assistant would be picking a product's
voice for it, and a system that invented one for the person would be guessing at their
identity. Pass initials, a glyph, an image — whatever the product actually knows.

`actions` is a node, not an `[{ label, onClick }]` array. An array shape would mean the
system owns how an action renders, which button variant it gets, and what happens when a
product needs a menu, a link, or a copy control with its own state. A node owns none of
that: you pass the buttons you already have.

#### Coming from a `role` union?

There is no `role` prop, and there is no `ChatRole` type. An earlier draft of this
component had `'user' | 'assistant' | 'system'`, and it was cut rather than extended.

An author enum is a domain model, and the design system does not own your domain. Three
members is wrong for a product with four authors and wrong again for one with two —
`name` plus `avatar` is wrong for none of them, because it asks you for what you already
have rather than asking you to translate into our vocabulary and then translate back.
Cutting it also removed the thing that made a union attractive in the first place:
deriving the avatar from the role. That derivation is why `avatar` is required — a mark
the system picks for you is a pure-ink glyph, and a pure-ink glyph disappears against
`--ink-950` in dark mode.

So keep your union. It is yours, it belongs in your state, and you translate it where you
render:

```tsx
const AUTHOR = {
  user: { variant: 'sent', name: 'Eli', avatar: 'E' },
  assistant: { variant: 'received', name: 'Assistant', avatar: '◆' },
  admin: { variant: 'received', name: 'Support', avatar: 'S' },
} as const;

{
  messages.map((message) => (
    <ChatMessage key={message.id} {...AUTHOR[message.role]}>
      {message.text}
    </ChatMessage>
  ));
}
```

A fourth author is one line in that object, on your release schedule rather than ours. And
`admin` sharing a side with `assistant` becomes a product decision you can see, instead of
a fact buried in a union somebody else versions.

The one thing not to do is push the table back down into the component. A `ChatMessage`
that took a role-to-props map would be the same domain model, one indirection further
away — and then your fourth author would need a release of this package.

#### Props

#### Accessibility

- The avatar wrapper is `aria-hidden="true"` — always. It's a decorative restatement of
  the speaker, so `name` is the single thing that identifies a turn to a screen reader.
  That keeps one turn from being announced twice, and keeps identification off a node a
  consumer may pass as a bare glyph.
- Because the avatar carries nothing, a turn with no `name` is announced with no
  attribution at all. Pass `name` on any thread where speakers alternate.
- `timestamp` is a pre-formatted string. Formatting is the product's call — locale,
  relative versus absolute, seconds or not — so the system never parses or reformats it.
- The avatar frame is an `Avatar` at its `md` step — it carries `ds-avatar ds-avatar--md`
  so the 40px circle comes from `Avatar.css` and the system has one avatar scale. It is
  drawn as a `--border-control` outline over that fill rather than a solid ink fill, so the
  mark inside survives both themes. It is not 44px: the 44px floor is scoped to primary
  interactive controls, and this frame is `aria-hidden` and not focusable.
- **Keyboard:** the turn itself is not focusable. Anything tabbable comes from the node
  you pass as `actions`.
- The ref forwards to the outer `<div>`.

Do:
- Pass name on both sides of a conversation so each turn is attributed once.
- Format the timestamp before passing it, in the reader’s locale.
- Pass real buttons as actions, styled the way the rest of your product styles them.
- Use variant="sent" for the person and the default for the assistant.

Don't:
- Expect an avatar to appear on its own — it is required, with no derived fallback.
- Rely on the avatar to say who is speaking; it is hidden from screen readers.
- Dim a settled turn with opacity; --fg-2 is what carries that state.
- Pass an array of action descriptors — actions takes nodes.

#### Product theming

The assistant mark reads `--product-signal-fg` with a fallback to the system's
`--status-warning-fg`, so a product can own that hue without forking the token set. The
convention is documented in `docs/agents/product-token-layer.md`; the fallback means a
product that declares nothing gets Miltinson Amber and measured contrast.

#### Related

Machine-readable record: /r/chat-message.json

### ChatThread (ai)

A scrolling conversation region that announces new turns to assistive technology.

Import: `import { ChatThread } from '@elirobinson/react/components/ai/ChatThread';`
Styles: @elirobinson/react/styles/ai/ChatThread.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| label | `string` | yes | — | Accessible name for the log region. Required — no copy lives in the component. |
| announce | `boolean` | no | true | Default true. False opts a closed or replayed thread out of live announcement. |
| followNewMessages | `boolean` | no | true | Keep the newest turn in view as the thread grows. Default true.

Only a reader already at the bottom is followed — scroll up to re-read an
earlier turn and the thread stays put until you return. The scroll is
instant, never animated, and moves nothing in the focus order, so a
composer keeps the caret while turns arrive behind it. |

Constraints: no-barrel-imports, forward-ref (see System constraints)

> **Deprecated.** Use `Conversation` from `@elirobinson/ai-elements`. It is backed by
> `use-stick-to-bottom`, which already follows the newest turn only for a reader who is
> already at the bottom, and this system pins its scroll to instant rather than smooth.
> The `announce` prop has no direct equivalent — write the attributes instead:
> `aria-live="polite"` and `aria-relevant="additions text"`, or `aria-live="off"` for a
> replayed thread. This component still works and is removed on the next major.

#### When to use it

`ChatThread` is the scrolling region a conversation lives in: a column of `ChatMessage`
turns that announces new ones as they arrive. It's the region, not the transcript — it
holds no state and keeps no message list. What it owns is the announcement contract and
keeping the newest turn in view, which are the two parts that are easy to get wrong by
hand.

It sits in the `ai` tier because it only means anything inside an assistant interaction.
The tier answers "what is this for," not "how much is assembled here" — a component earns
`ai` when you can't describe it without saying assistant, model, or streaming. A card that
happens to render a model's answer is still a `Card`.

#### Announcing, and not announcing

`announce` defaults to `true`, which is right for a live conversation: `aria-live="polite"`
means a turn that arrives while the reader is elsewhere still reaches them, at the next
pause rather than mid-sentence.

Pass `announce={false}` for a thread that isn't live — a closed conversation, a saved
transcript, a replay in a history view. That sets `aria-live="off"`, so mounting a hundred
past turns doesn't queue a hundred announcements. Rendering history is the case where the
default is wrong.

#### Following the newest turn

`followNewMessages` defaults to `true`: as the thread grows, the newest turn is scrolled
into view. This isn't a preference the system left to you, because a live region that
announces a turn and then renders it below the fold is a defect for exactly the readers
the live region is for.

**It only follows a reader who is already at the bottom.** Scroll up to re-read an earlier
turn and the thread stays where you put it, however many turns arrive behind you; return
to the bottom and it picks up again. "At the bottom" allows 32px of slack, which is enough
that a zoomed page's fractional scroll offsets still count as pinned and far less than the
~60px it takes to scroll back past a single turn.

**It never animates.** The scroll is an assignment, not a smooth transition — there is no
motion to reduce, so nothing here needs a `prefers-reduced-motion` branch. The component
sets `scroll-behavior: auto` on itself for that reason: the property inherits, and an
`html { scroll-behavior: smooth }` in your reset would otherwise turn every arriving turn
into an animation inside a live region.

Pass `followNewMessages={false}` to own scrolling yourself — for a jump-to-a-quoted-turn
view, or a thread that opens on an unread marker rather than at the end. The ref still
forwards to the element, so you have everything the component has.

#### Props

#### Accessibility

- Renders `role="log"` with `aria-live="polite"` and `aria-relevant="additions text"`. The
  `text` half matters for assistant output: a turn that grows token by token is a text
  change inside an existing node, not an addition, and `additions` alone would announce
  the empty turn and then go quiet.
- `label` is **required** and becomes `aria-label`. No copy lives inside the component, so
  the region's name is always the product's — and a page with more than one thread has two
  distinguishable regions rather than two unnamed logs.
- The region scrolls (`overflow-y: auto`), so it needs to be keyboard scrollable. If it
  isn't focusable through its content, give it `tabIndex={0}` yourself; the component
  doesn't add one, because a region full of focusable turns doesn't need it and a stray
  tab stop is its own problem.
- **Keyboard:** none of its own — `ChatThread` renders no controls. Anything focusable
  comes from the turns you put inside it.
- Following the newest turn moves nothing in the focus order: setting `scrollTop` is not a
  focus change, so a composer below the thread keeps the caret and the typed text while
  turns arrive above it.
- The ref forwards to the outer `<div>` — the component holds its own reference internally
  and merges the two, so what you receive is the same element it scrolls.

Do:
- Give every thread a label that says which conversation it is.
- Pass announce={false} when you are rendering history rather than a live stream.
- Keep the turns inside it ChatMessage elements, so the avatar column lines up.
- Leave followNewMessages on unless you are deliberately opening somewhere other than the end.

Don't:
- Mount a long replayed transcript with announce left at its default.
- Wrap the thread in another live region; nesting them announces twice.
- Expect ChatThread to hold or order messages — it renders the children you give it.
- Use it as a generic scrolling list; outside an assistant surface, the log role is wrong.

#### Product theming

`ChatThread` draws only system tokens, but it's the container for turns that read the
optional product token layer — the `--product-*` convention documented in
`docs/agents/product-token-layer.md`. Every read there falls back to a system token, so a
product that declares none of it gets the system palette unchanged.

#### Related

Machine-readable record: /r/chat-thread.json

### StreamingCaret (ai)

A blinking caret marking the message an assistant is still writing.

Import: `import { StreamingCaret } from '@elirobinson/react/components/ai/StreamingCaret';`
Styles: @elirobinson/react/styles/ai/StreamingCaret.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLSpanElement>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| active | `boolean` | no | true | Default true. False renders nothing at all, so it cannot outlive the stream. |
| label | `string` | no | — | Accessible name. Present promotes the caret to role="status"; absent hides it. |

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

`StreamingCaret` is the blinking mark at the end of a message an assistant is still
writing. Put it inline, after the last of the text, inside the turn that's growing. It is
a state graphic and nothing else: it holds no timer, watches no stream, and knows nothing
about your transport.

#### It cannot outlive the stream

When `active` is `false` the component returns `null` — no element, no wrapper, nothing in
the DOM. That's the whole design. A caret that could be left mounted on a finished message
is a caret that eventually is, and a finished answer that still looks like it's writing is
worse than no affordance at all. Because the falsy case renders nothing, the only way to
show a stale caret is to keep telling the component the stream is live.

#### Props

#### Accessibility

- Pass `label` and the caret becomes `role="status"` with that accessible name — a polite
  announcement that the assistant is still writing, which is the right call when the
  content it precedes takes a while to arrive.
- Omit `label` and the caret is `aria-hidden`. That's the right call when the turn already
  announces its own progress through the thread's live region, and a second announcement
  would just be noise.
- Under `prefers-reduced-motion: reduce` the blink stops and the caret goes **solid** —
  never invisible. Removing the animation must not remove the state, because the caret is
  the only signal that a message is still being written.
- The fill is `--accent-press` rather than `--accent`: as a non-text state graphic it owes
  3:1 against its surface under SC 1.4.11, and `--accent` measures 2.53:1.
- **Keyboard:** none — it renders a single non-interactive `<span>`.
- The ref forwards to that `<span>`, when one exists.

Do:
- Drive active from the same state that decides whether the stream is still open.
- Pass label when the caret is the only sign that a slow answer is coming.
- Place it inline, immediately after the last rendered text of the turn.
- Let the reduced-motion rule stand — a solid caret still says "writing."

Don't:
- Leave it mounted on a settled message and rely on CSS to hide it.
- Give every caret on a busy thread a label; the announcements stack up.
- Restyle it to a lighter accent — it would drop under the 3:1 graphics threshold.
- Use it as a generic loading spinner; that is Spinner, or Skeleton.

#### Product theming

The caret fill reads `--product-signal` with a fallback to the system's `--accent-press`,
so a product can substitute its own hue for the same job. The convention — one level of
fallback, always landing on a system token — is documented in
`docs/agents/product-token-layer.md`, and the fallback is what keeps the layer optional.

#### Related

Machine-readable record: /r/streaming-caret.json

### Avatar (atoms)

Image avatar with initials fallback, in sm/md/lg sizes.

Import: `import { Avatar, AvatarImage, AvatarFallback } from '@elirobinson/react/components/atoms/Avatar';`
Styles: @elirobinson/react/styles/atoms/Avatar.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| alt | `string` | no |  | — |
| fallback | `string` | no | — | — |
| size | `"sm" \| "md" \| "lg"` | no | md | — |
| src | `string` | no | — | — |

#### AvatarImage

(no props of its own beyond inherited HTML attributes)
Also accepts all `ImgHTMLAttributes<HTMLImageElement>` props.

#### AvatarFallback

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLSpanElement>` props.

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `Avatar` to identify a person or account — a client roster, a comment thread, a
user menu. It's a circle crop, so it suits photos and initials, not logos: a rectangular
mark gets distorted by the crop. Pair it with a visible name wherever it appears; don't
make the avatar carry identification on its own.

#### Sizes

#### With a photo

`src` and the initials fallback aren't linked at runtime — `Avatar` doesn't detect a
failed image load and swap to `fallback` for you. If `src` is set, the `<img>` renders
unconditionally.

#### Props

#### Accessibility

- When `src` is set, `alt` becomes the `<img>`'s accessible name — always pass a real
  name, not a filename or generic string.
- When there's no `src`, the initials render inside a `<span aria-hidden="true">` and
  the wrapping `<div>` carries no accessible name of its own. A fallback-only avatar is
  effectively invisible to screen readers unless you add `aria-label` yourself or the
  name is already visible next to it.
- `AvatarImage` and `AvatarFallback` are exported alongside `Avatar` for custom layouts,
  but they're standalone primitives — `Avatar` doesn't render them internally, and they
  don't coordinate with each other. Building a custom composition means supplying your
  own wrapper and sizing.
- The ref forwards to the outer `<div>`.

Do:
- Pass a real name in alt even when showing initials — it drives the fallback text and doubles as the accessible name when there’s a photo.
- Keep sizes consistent within one list so avatars align.
- Pair every avatar with visible name text nearby — don’t rely on the image alone to identify someone.
- Pass fallback explicitly when you want specific initials instead of the auto-derived ones.

Don't:
- Assume Avatar swaps to the fallback automatically on a failed image load — it doesn’t; src wins whenever it’s set.
- Use Avatar for a company or app logo — a circle crop distorts most rectangular marks.
- Leave a fallback-only avatar with no adjacent text and no aria-label — screen reader users get nothing.
- Pack more than two characters into fallback — that’s the design, and more just clips.

#### Related

Machine-readable record: /r/avatar.json

### Badge (atoms)

Small status label — default, signal, anchor, solid, and outline variants.

Import: `import { Badge } from '@elirobinson/react/components/atoms/Badge';`
Styles: @elirobinson/react/styles/atoms/Badge.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLSpanElement>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| variant | `"default" \| "signal" \| "anchor" \| "solid" \| "outline"` | no | default | — |

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `Badge` for a static status or category label — it's a `<span>`, not a control.
Reach for `Chip` instead the moment the label needs to be removable or clickable.

- **default** is the neutral workhorse for category tags.
- **signal** is Miltinson Amber — reserve it for the one badge you most want noticed.
- **anchor** ties to the Forest color family — use it for trust- and coaching-flavored
  content.
- **solid** is high-contrast ink; use it sparingly, like a "New" marker.
- **outline** is the quietest option, for a label that shouldn't compete for attention.

#### Variants

#### Props

#### Accessibility

- Renders a plain `<span>` with no implicit ARIA role — it's a visual label, not a live
  region.
- If a badge shows a count or status that changes and the change matters to screen
  reader users, add `role="status"` (or similar) yourself — `Badge` doesn't announce
  updates on its own.
- Non-interactive by design: no keyboard handling, no focus state.

Do:
- Use default for neutral category tags and outline for a quieter, low-emphasis label.
- Reserve signal (amber) for the one badge you most want noticed on a screen.
- Use anchor for trust- and coaching-flavored content — it’s tied to the Forest color family.
- Keep badge text to one or two words; it’s a label, not a sentence.

Don't:
- Make a Badge clickable — reach for Chip or Button if it needs to respond to interaction.
- Stack more than one solid badge in the same row; it reads as visual noise.
- Use Badge to show a live, changing count without adding your own aria-label or role="status".
- Put a badge color to work purely decoratively — each variant should mean something.

#### Related

Machine-readable record: /r/badge.json

### Button (atoms)

The primary action control — primary, accent, secondary, and ghost variants in three sizes.

Import: `import { Button } from '@elirobinson/react/components/atoms/Button';`
Styles: @elirobinson/react/styles/atoms/Button.css (included in styles.css)
Also accepts all `ButtonHTMLAttributes<HTMLButtonElement>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| size | `"sm" \| "md" \| "lg"` | no | md | — |
| variant | `"primary" \| "accent" \| "secondary" \| "ghost"` | no | primary | — |

Constraints: no-barrel-imports, forward-ref, touch-target-primary, hit-area-no-overlap (see System constraints)

#### When to use it

Use `Button` for actions — submitting a form, opening a dialog, confirming a step. For
navigation, use a real link: an `<a>` styled as a link is honest about what happens on
click, works with middle-click and cmd-click, and needs no JavaScript.

- **primary** is the default: ink-solid, one per view is a good ceiling.
- **accent** is Miltinson Amber — reserve it for the single most important action on the screen.
- **secondary** is the bordered workhorse for everything alongside a primary.
- **ghost** sits in toolbars and card corners where a border would add noise.

#### Variants

#### Sizes

All three sizes keep the 44×44px minimum touch target — the smaller sizes shrink the
visible control, not the hit area.

#### Disabled

#### Props

#### Accessibility

- Renders a native `<button>` with `type="button"` by default, so a button inside a form
  never submits it by accident — pass `type="submit"` when submitting is the point.
- **Keyboard:** `Tab` focuses, `Enter` and `Space` activate. That contract comes from the
  native element; nothing re-implements it.
- Focus is marked with the system's high-contrast ink ring (`:focus-visible`), never
  removed.
- The ref forwards to the underlying `<button>` element, so focus management from a
  parent (`ref.current.focus()`) works directly.
- Icon-only buttons need an `aria-label` — the component doesn't invent one.

Do:
- Use one primary or accent button per view — hierarchy is the point.
- Write button labels as verbs: "Save changes", not "Changes".
- Pass type="submit" explicitly inside forms when submitting is intended.
- Give icon-only buttons an aria-label.

Don't:
- Use a Button for navigation — style a link instead.
- Disable a submit button to signal a validation error — show the error and keep it clickable.
- Stack multiple accent buttons in one section; amber is a signal, not a fill.
- Shrink the hit area below 44×44px — density comes from the visible control, not the target.

#### Related

Machine-readable record: /r/button.json

### Checkbox (atoms)

Labelled checkbox with a full-height 44px click row.

Import: `import { Checkbox } from '@elirobinson/react/components/atoms/Checkbox';`
Styles: @elirobinson/react/styles/atoms/Checkbox.css (included in styles.css)
Also accepts all `Omit<InputHTMLAttributes<HTMLInputElement>, 'type'>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| label | `string` | yes | — | — |

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Reach for `Checkbox` when the choice is independent and part of a form that gets
submitted — pick any number of options, in any combination. Reach for `Switch` instead
when flipping it takes effect immediately, with no submit step (a notification
preference, a feature flag). Reach for `RadioGroup` when only one of several options can
be true at once.

#### States

#### Controlled

`Checkbox` forwards every native input prop, so `checked` and `onChange` work exactly
like a plain `<input type="checkbox">`.

#### Props

#### Accessibility

- Renders a native `<input type="checkbox">` paired with a `<label>` — `label` is
  required and is the input's only accessible name.
- The id is auto-generated with `useId` when you don't pass one, so `htmlFor` always
  resolves.
- **Keyboard:** `Tab` focuses, `Space` toggles — native `input` behavior, nothing
  reimplemented.
- The row reserves a 44px minimum height for rhythm alongside other controls, but the
  actual hit target is the 18×18 box and the label text — clicking the empty vertical
  space around them doesn't toggle it.
- The ref forwards to the underlying `<input>`.

Do:
- Use Checkbox for independent yes/no choices inside a form that submits together.
- Always pass a real, specific label — it’s required, and it’s the input’s only accessible name.
- Group related checkboxes visually (a card, a list) so “N selected” context is clear.
- Let defaultChecked or checked drive pre-selected state — don’t manage a shadow copy elsewhere.

Don't:
- Use Checkbox when only one answer can be true — that’s RadioGroup.
- Use Checkbox for a setting that takes effect the instant it’s flipped — that’s Switch.
- Expect the full 44px row to be clickable — only the box and the label text respond.
- Omit the label prop and lean on placeholder or nearby text — there’s no other accessible name path.

#### Related

Machine-readable record: /r/checkbox.json

### Eyebrow (atoms)

Uppercase mono section label — marketing typography.

Import: `import { Eyebrow } from '@elirobinson/react/components/atoms/Eyebrow';`
Styles: @elirobinson/react/styles/atoms/Eyebrow.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLSpanElement>` props.

(no props of its own beyond inherited HTML attributes)

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

`Eyebrow` is marketing typography — an uppercase, tracked mono label that introduces a
section on a landing or content page ("Case Study", "Coaching Guides"). It's not a form
label (use `Label` or the built-in `label` prop on a field) and it's not a status tag
(use `Badge`).

#### Paired with a heading

Eyebrow carries no heading semantics — it's a visual lead-in, so keep the real `<h1>`
through `<h6>` right after it.

#### Props

#### Accessibility

- Renders a plain `<span>` — no heading role, no landmark, nothing implied beyond its
  visible text.
- Screen readers and search engines read it as ordinary inline text; it doesn't
  substitute for document structure.

Do:
- Pair every Eyebrow with a real heading right after it — it’s a lead-in, not the heading itself.
- Keep eyebrow text short — two to four words reads best in the tracked uppercase type.
- Use it to introduce a section on a marketing or landing page.

Don't:
- Use Eyebrow as a heading substitute — it has no heading semantics for assistive tech or SEO.
- Use Eyebrow inside product UI chrome where Label or a section heading already does the job.
- Write full sentences in an Eyebrow — the uppercase tracking makes long text hard to read.

#### Related

Machine-readable record: /r/eyebrow.json

### Input (atoms)

Batteries-included labelled text input with hint and error wiring.

Import: `import { Input } from '@elirobinson/react/components/atoms/Input';`
Styles: @elirobinson/react/styles/atoms/field.css (included in styles.css)
Also accepts all `InputHTMLAttributes<HTMLInputElement>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| label | `string` | yes | — | — |
| error | `string` | no | — | — |
| hint | `string` | no | — | — |

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

`Input` is batteries-included: label, hint, and error are wired up for you, with the
right `aria-describedby` and `aria-invalid` set automatically. `label` is required —
there's no placeholder-as-label escape hatch. Reach for a standalone `Label` plus a bare
`<input>` only when this fixed layout (label above, hint or error below) doesn't fit
your design. Reach for `Textarea` once the content needs more than one line.

#### With a hint

Hint text is persistent guidance, shown until an error takes over.

#### With an error

`error` replaces `hint` — both aren't shown at once, and the error text gets
`role="alert"` so assistive tech picks up the change.

#### Props

#### Accessibility

- The label is a real `<label htmlFor>` pointed at the input's id — auto-generated with
  `useId` when you don't pass one.
- `hint` and `error` each render in their own `<span>`, wired into `aria-describedby`
  alongside anything you pass in `aria-describedby` yourself.
- Setting `error` also sets `aria-invalid="true"` on the input and gives the error text
  `role="alert"`, so a validation message that appears after submit gets announced.
- When both `hint` and `error` are set, only the error text renders — the hint is
  suppressed until the error clears.
- The ref forwards to the underlying `<input>`.

Do:
- Pass label always — it’s required, and it drives the native label/htmlFor association.
- Use hint for persistent guidance and error for validation feedback.
- Let error replace hint when both apply — one message at a time keeps the field readable.
- Pass a real HTML type (email, password, number) — Input forwards every native input attribute.

Don't:
- Render Input without a visible label to save vertical space — there’s no placeholder fallback.
- Write hint text so long it competes with the input itself — keep it to one short line.
- Set aria-invalid yourself — passing error already sets it.
- Reach for Input when the content needs multiple lines — that’s Textarea.

#### Related

Machine-readable record: /r/input.json

### Kbd (atoms)

Styled kbd element for keyboard-shortcut hints.

Import: `import { Kbd } from '@elirobinson/react/components/atoms/Kbd';`
Styles: @elirobinson/react/styles/atoms/Kbd.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLElement>` props.

(no props of its own beyond inherited HTML attributes)

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `Kbd` to label an actual physical key or shortcut inline — in help text, empty
states, or next to a `CommandPalette` trigger. It's typographic, not interactive: it
doesn't respond to clicks and doesn't listen for the key it names.

#### Shortcut combos

`Kbd` renders one key at a time — space or join multiple `Kbd` elements yourself for a
combo.

#### Props

#### Accessibility

- Renders a native `<kbd>` element — the correct semantic tag for "user input, such as a
  keyboard key," with no extra ARIA required.
- Purely presentational otherwise: not focusable, no keyboard handling of its own.

Do:
- Use Kbd to label an actual physical key or shortcut ("⌘K", "Esc", "Enter").
- Pair it with CommandPalette hints or empty-state copy ("Press ⌘K to search").
- Separate multi-key combos with your own spacer or "+" — Kbd renders one key at a time.

Don't:
- Make Kbd clickable — it’s typographic, not a control; use Button if it needs to do something.
- Use it for arbitrary code snippets — that’s an inline code block, not a keyboard hint.
- Write full words that aren’t keys inside Kbd — it reads oddly for anything but a key name.

#### Related

Machine-readable record: /r/kbd.json

### Label (atoms)

Standalone form label for controls that manage their own wiring.

Import: `import { Label } from '@elirobinson/react/components/atoms/Label';`
Styles: @elirobinson/react/styles/atoms/field.css (included in styles.css)
Also accepts all `LabelHTMLAttributes<HTMLLabelElement>` props.

(no props of its own beyond inherited HTML attributes)

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

`Label` is for controls that don't already ship their own — `RadioGroup`, a native
`<select>`, a third-party control. Every other field atom here (`Input`, `Textarea`,
`Checkbox`, `Switch`, `Slider`, `RadioGroupItem`) takes a required `label` prop and
renders its own `<label>`; adding a standalone `Label` on top of those just duplicates
markup.

#### Props

`Label` has no props of its own beyond the native `<label>` attributes — see the table
below.

#### Accessibility

- Renders a native `<label>`. It doesn't infer or wire up an association with a
  control — that's on you.
- For elements the `for`/`id` mechanism supports (`input`, `select`, `textarea`,
  `button`, and a few others), pass `htmlFor` matching the control's `id`.
- For a non-labelable container like `RadioGroup`'s `role="radiogroup"` `<div>`,
  `htmlFor` doesn't reliably associate — use `aria-labelledby` pointing at the `Label`'s
  own `id` instead, as in the demo above.
- The ref forwards to the underlying `<label>`.

Do:
- Give Label a stable id (or htmlFor) and connect it explicitly — that’s the one thing this component does.
- Reach for it to introduce a RadioGroup, since RadioGroup takes no label prop of its own.
- Keep it to one short phrase — it renders as a normal label, not a heading.

Don't:
- Add a standalone Label next to Input, Textarea, Checkbox, Switch, or Slider — they already render their own via the required label prop.
- Use htmlFor pointing at a role="radiogroup" div and expect it to behave like a form-control association — use aria-labelledby there instead.
- Leave it unconnected — an orphaned label with no for or aria-labelledby target just reads as plain text.

#### Related

Machine-readable record: /r/label.json

### Progress (atoms)

Determinate progress bar with an accessible value readout.

Import: `import { Progress } from '@elirobinson/react/components/atoms/Progress';`
Styles: @elirobinson/react/styles/atoms/Progress.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| value | `number` | yes | — | — |
| label | `string` | no | — | — |
| max | `number` | no | 100 | — |

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `Progress` when you know how far along a task is — an upload, an import, a
multi-step count. Use `Spinner` instead for indeterminate work where you don't know how
long it'll take, and `Skeleton` for a structural loading placeholder before content
exists at all.

#### Values and custom max

`value` clamps to the `0`–`max` range for you. Use `max` to represent the real unit
instead of normalizing everything to a percentage yourself.

#### Props

#### Accessibility

- Renders `role="progressbar"` with `aria-valuenow`, `aria-valuemin={0}`, and
  `aria-valuemax` kept in sync with `value`/`max`.
- `label` becomes the progress bar's `aria-label` — it's optional in the type, but it's
  the only accessible name the control gets. Skip it and screen readers announce an
  unlabeled progress bar.
- No internal timer or animation — the visual bar only moves when `value` changes, so
  the state you show is always the state you pass in.

Do:
- Always pass label — it’s optional in the type but it’s the only accessible name the progress bar gets.
- Use max to represent the real unit ("modules complete", "MB uploaded") instead of pre-converting to a percentage.
- Update value from state you already have — Progress has no internal timer of its own.

Don't:
- Use Progress for a task with no known duration or endpoint — use Spinner instead.
- Omit label and rely on nearby text to carry meaning — screen readers read the progress bar in isolation.
- Animate value with a fake setInterval — if the real progress is unknown, don’t simulate one.

#### Related

Machine-readable record: /r/progress.json

### RadioGroup (atoms)

Context-based radio group; the group owns name, checked state, and change handling.

Import: `import { RadioGroup, RadioGroupItem } from '@elirobinson/react/components/atoms/RadioGroup';`
Styles: @elirobinson/react/styles/molecules/RuleLink.css (included in styles.css)
Also accepts all `Omit<HTMLAttributes<HTMLDivElement>, 'role'>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| name | `string` | yes | — | Shared `name` for every item's `input[type="radio"]`, which makes it the
field name the group submits under. The group participates in native form
submission with no extra wiring: inside a `<form>` its selection shows up
in `FormData` and in a server action's payload under this `name`. Nothing
hidden needs to be added to carry the value across. |
| defaultValue | `string \| number \| readonly string[]` | no | — | — |
| onValueChange | `((value: string) => void)` | no | — | — |
| value | `string \| null` | no | — | Selection, when the group is controlled. `null` means controlled with
nothing selected; `undefined` means uncontrolled, and hands the selection
back to `defaultValue` and the group's own state. The distinction matters:
clear a controlled group with `null`, never with `undefined`. |

#### RadioGroupItem

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| label | `string` | yes | — | — |
| defaultValue | `string \| number \| readonly string[]` | no | — | — |
| value | `string \| number \| readonly string[]` | no | — | — |
Also accepts all `Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'name' | 'checked' | 'onChange'>` props.

Constraints: no-barrel-imports, forward-ref (see System constraints)
Notes: ds-radio-group styles are defined in molecules/RuleLink.css, not a RadioGroup sheet

#### When to use it

Use `RadioGroup` for a small, always-visible set of mutually exclusive options — two to
six is the sweet spot. Once the list gets long enough to need scrolling or search, reach
for `Select` or `Combobox` instead.

`RadioGroup` is context-based: the group owns `name`, the current value, and change
handling. `RadioGroupItem` only takes `value` and `label` — it can't take `checked`,
`onChange`, or `name` directly, so there's no way to desync an item from its group.
Rendering a `RadioGroupItem` outside a `RadioGroup` throws immediately; the two aren't
meant to be used apart.

#### Controlled

Pass `value` and `onValueChange` to drive selection from your own state. Passing
`defaultValue` instead makes it uncontrolled — don't pass both.

### Clearing a controlled group

`value` distinguishes empty from absent, and the difference decides the mode:

- **`null`** — controlled, nothing selected. This is how you clear a controlled group.
- **`undefined`** — uncontrolled. The group falls back to `defaultValue` and its own
  internal state, exactly as if `value` had never been passed.

So type your state `string | null`, not `string | undefined`:

```tsx
const [plan, setPlan] = useState<string | null>(null);

<RadioGroup name="plan" value={plan} onValueChange={setPlan}>
  <RadioGroupItem value="free" label="Free" />
  <RadioGroupItem value="pro" label="Pro" />
</RadioGroup>
<button onClick={() => setPlan(null)}>Clear</button>;
```

Clearing with `undefined` instead does not clear the group — it hands selection back to
the group's own state, which still holds the last click. TypeScript can't catch that,
since `undefined` is legal for an optional prop, so the group warns in development when
`value` goes from a string to `undefined`.

#### Form submission

The group works with native form submission on its own — no hidden input, no extra
wiring. `RadioGroupItem` renders a real `input[type="radio"]`, so the group's `name` is
also the submitted field name, and the selection is in `FormData` and in a server
action's payload under that name:

```tsx
<form action={savePlan}>
  <RadioGroup name="plan" defaultValue="free">
    <RadioGroupItem value="free" label="Free" />
    <RadioGroupItem value="pro" label="Pro" />
  </RadioGroup>
  <Button type="submit">Save</Button>
</form>
```

`formData.get('plan')` is `'free'` or `'pro'`. This holds in both modes — a controlled
group submits its current selection too.

#### Props

#### Accessibility

- The wrapper renders `role="radiogroup"`; each `RadioGroupItem` renders a native
  `input[type="radio"]` sharing the group's `name`.
- **Keyboard:** because the inputs share a native `name`, arrow keys move between items
  and select as they go, and `Tab` treats the whole group as a single stop — that's the
  browser's built-in radio-group behavior, not something this component reimplements.
- `RadioGroup` has no `label` prop of its own — introduce it with a standalone `Label`
  connected via `aria-labelledby` (a plain `div` isn't a labelable element, so `htmlFor`
  doesn't reliably associate here).
- The ref on `RadioGroup` forwards to the wrapping `<div>`; the ref on `RadioGroupItem`
  forwards to its `<input>`.

Do:
- Give RadioGroup a name and either defaultValue (uncontrolled) or value + onValueChange (controlled) — pick one mode.
- Type controlled state as string | null and clear it with null — undefined means uncontrolled.
- Rely on the group name for form submission; it submits natively, so no hidden input is needed.
- Use it for 2–6 mutually exclusive, always-visible options.
- Pair a standalone Label above the group via aria-labelledby, since RadioGroup has no label prop of its own.
- Give every RadioGroupItem a distinct, real value and label.

Don't:
- Try to pass checked, onChange, or name to a RadioGroupItem — the type doesn’t allow it, and the group owns all three.
- Render a RadioGroupItem outside a RadioGroup — it throws immediately, with no fallback behavior.
- Reach for RadioGroup when the option list is long or needs search — use Select or Combobox.
- Pass both value and defaultValue — value wins, and defaultValue is only read on the first render.
- Clear a controlled group with undefined — that switches it to uncontrolled and keeps the last selection. Pass null.
- Add a hidden input to carry the selection to a server action — the group already submits under its own name.

#### Related

Machine-readable record: /r/radio-group.json

### Separator (atoms)

Horizontal or vertical hairline divider.

Import: `import { Separator } from '@elirobinson/react/components/atoms/Separator';`
Styles: @elirobinson/react/styles/atoms/Separator.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| orientation | `"horizontal" \| "vertical"` | no | horizontal | — |

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `Separator` for a hairline divider that marks a real break between content
groups — sections, toolbar clusters, nav items. If you just need whitespace, a CSS gap
is simpler and skips the ARIA semantics this component adds.

#### Vertical

A vertical separator has no height of its own — give its flex container a defined
height.

#### Props

#### Accessibility

- Defaults to `role="separator"` with `aria-orientation` matching `orientation` — a
  static divider, not a focusable, resizable splitter.
- `role` is overridable: if the separator is purely decorative spacing with no
  thematic-break meaning, pass `role="none"` yourself to drop it out of the
  accessibility tree. The default assumes it _is_ meaningful.

Do:
- Use orientation="vertical" inside a flex row with a defined height — a vertical hairline has no height of its own.
- Let the default role="separator" stand when the divider marks a real content break.
- Override role="none" yourself when the separator is purely decorative.

Don't:
- Use Separator as a layout spacer where a CSS gap would do — that’s simpler and skips the ARIA semantics.
- Nest interactive content inside it — it’s a single hairline, not a container.
- Forget the fixed height for a vertical separator outside a flex context that already constrains height — it collapses to nothing.

#### Related

Machine-readable record: /r/separator.json

### Skeleton (atoms)

Loading placeholder block that respects reduced motion.

Import: `import { Skeleton } from '@elirobinson/react/components/atoms/Skeleton';`
Styles: @elirobinson/react/styles/atoms/Skeleton.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

(no props of its own beyond inherited HTML attributes)

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `Skeleton` for a structural loading placeholder that mimics the shape of the content
about to appear — it cuts layout shift and signals progress visually. Use `Spinner`
instead for a small, content-agnostic "working" indicator, and `Progress` when you
actually know the percent complete.

#### Composing a loading card

Stack skeletons to match the real content's layout — an image block, a title line, a
subtitle line.

#### Props

Skeleton has no props of its own — size and shape come from `className`/`style` on the
inherited `HTMLAttributes<HTMLDivElement>`.

#### Accessibility

- Always renders with `aria-hidden="true"` — it's invisible to screen readers by design,
  meaning it does not announce a loading state to assistive tech on its own.
- If the wait is long enough to matter, pair it with a `role="status"` wrapper or
  visually-hidden text (see the card demo above), or use `Spinner`, which already
  carries `role="status"`.
- The pulse animation respects `prefers-reduced-motion` — not through a per-component
  check, but because the design tokens stylesheet flattens all animation and transition
  durations globally when that preference is set.

Do:
- Shape skeletons to match the real content’s dimensions so the swap-in doesn’t jump.
- Stack multiple Skeletons to represent a whole loading card, mirroring the real layout.
- Pair it with a role="status" wrapper or screen-reader-only text when the wait genuinely needs to be announced.

Don't:
- Rely on Skeleton alone to tell screen reader users something is loading — it’s aria-hidden, silent by design.
- Leave skeletons on screen indefinitely if a request fails — swap to an error state, don’t strand the pulse.
- Use Skeleton for a single small icon-sized loading state — Spinner reads better at that scale.

#### Related

Machine-readable record: /r/skeleton.json

### Slider (atoms)

Labelled native range input.

Import: `import { Slider } from '@elirobinson/react/components/atoms/Slider';`
Styles: @elirobinson/react/styles/atoms/Slider.css (included in styles.css)
Also accepts all `Omit<InputHTMLAttributes<HTMLInputElement>, 'type'>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| label | `string` | yes | — | — |

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `Slider` for a value picked from a continuous or stepped numeric range, where the
gesture matters more than the exact typed number — volume, brightness, a price range.
Use `Input type="number"` instead when typed precision is the point (dollar amounts,
exact ages).

#### Controlled

`Slider` doesn't render the current value anywhere — show it yourself off the same
state.

#### Props

#### Accessibility

- Renders a native `<input type="range">`, which carries the implicit `slider` role and
  full keyboard support from the browser — arrow keys adjust by `step`, `Home`/`End`
  jump to the min/max. Nothing here reimplements it.
- The label is a real `<label htmlFor>` pointed at the input's id, auto-generated with
  `useId` when you don't pass one.
- No value bubble or tooltip appears while dragging — if readers need to see the number,
  render it next to the slider yourself.
- The ref forwards to the underlying `<input>`.

Do:
- Always pass min, max, and a sensible step — the native range default (0–100, step 1) is rarely what you actually want.
- Show the live value near the slider yourself when the exact number matters — the component doesn’t render one.
- Use defaultValue for uncontrolled, or value + onChange for controlled — same native contract as any range input.

Don't:
- Expect a tooltip or value bubble to appear automatically while dragging — build it yourself off the same state.
- Use Slider for a value that needs typed precision — Input type="number" is more honest there.
- Forget the label — it’s required, and it’s the only accessible name the range input gets.

#### Related

Machine-readable record: /r/slider.json

### Spinner (atoms)

Status-role loading indicator in three sizes.

Import: `import { Spinner } from '@elirobinson/react/components/atoms/Spinner';`
Styles: @elirobinson/react/styles/atoms/Spinner.css (included in styles.css)
Also accepts all `Omit<HTMLAttributes<HTMLSpanElement>, 'role'>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| label | `string` | no | Loading | — |
| size | `"sm" \| "md" \| "lg"` | no | md | — |

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `Spinner` for a small, indeterminate "working" indicator — you don't know how long
it'll take. Use `Progress` instead the moment you actually know the percent complete.

#### Sizes

#### Inside a button

A common pattern: a disabled button showing its own loading state.

#### Props

#### Accessibility

- Renders `role="status"` with `aria-label={label}` (default `"Loading"`) — a live
  region announced once when it mounts. `role` is fixed: the type omits it from the
  props you can pass, so you can't accidentally break the live region.
- When adjacent visible text already says the same thing — a "Saving changes" button,
  for example — pass `aria-hidden="true"` on the `Spinner` so the two don't both get
  announced, as in the button demo above.
- Give it a specific `label` when the default "Loading" isn't precise enough ("Loading
  invoices") and no visible text nearby already says so.

Do:
- Give Spinner a specific label when the default "Loading" isn’t precise enough.
- Use size="sm" inline next to text and reserve lg for a full-section loading state.
- Pass aria-hidden="true" when adjacent visible text already announces the same loading state.

Don't:
- Pair a Spinner with visible "Loading…" text without hiding one of the two from assistive tech — that’s a double announcement.
- Use Spinner for a task where you actually know the percent complete — that’s what Progress is for.
- Try to override role — the type doesn’t allow it; status is the fixed contract.

#### Related

Machine-readable record: /r/spinner.json

### Switch (atoms)

Switch-role toggle with a labelled click target.

Import: `import { Switch } from '@elirobinson/react/components/atoms/Switch';`
Styles: @elirobinson/react/styles/atoms/Switch.css (included in styles.css)
Also accepts all `Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'role'>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| label | `string` | yes | — | — |

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `Switch` for a setting that takes effect immediately, with no submit step — a
notification preference, a feature flag. Use `Checkbox` instead when the choice is part
of a form that gets submitted together.

#### States

#### Controlled

Under the hood it's still a checkbox — `checked` and `onChange` work exactly as they
would on a plain `<input type="checkbox">`.

#### Props

#### Accessibility

- Renders `<input type="checkbox" role="switch">` paired with a `<label>` — `label` is
  required and is the input's only accessible name.
- `role="switch"` changes how assistive tech announces state ("on"/"off" instead of
  "checked"/"unchecked"), but the element underneath is a real checkbox, so `checked`,
  `defaultChecked`, and `onChange` all behave exactly as they do on `Checkbox`.
- **Keyboard:** `Tab` focuses, `Space` toggles — native `input` behavior.
- `role` is fixed: the type omits it from the props you can pass, so `switch` can't be
  overridden.
- The ref forwards to the underlying `<input>`.

Do:
- Use Switch for settings that take effect immediately — no save step, no form submit.
- Always pass a real label; it’s required and the input’s only accessible name.
- Use defaultChecked for uncontrolled or checked + onChange for controlled — same contract as a native checkbox.

Don't:
- Use Switch when the choice only takes effect after a form submit — that’s Checkbox.
- Try to override role — the type omits it; switch is the fixed contract.
- Phrase the label as a question ("Enable X?") — a switch is a state, name the setting itself ("Email notifications").

#### Related

Machine-readable record: /r/switch.json

### Textarea (atoms)

Labelled multiline text field with hint and error wiring.

Import: `import { Textarea } from '@elirobinson/react/components/atoms/Textarea';`
Styles: @elirobinson/react/styles/atoms/field.css (included in styles.css)
Also accepts all `TextareaHTMLAttributes<HTMLTextAreaElement>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| label | `string` | yes | — | — |
| error | `string` | no | — | — |
| hint | `string` | no | — | — |

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

`Textarea` is `Input`'s multiline sibling — same label/hint/error wiring, same required
`label`. Use it for anything that needs more than one line: a message, notes, a
description. Reach for `Input` when a single line is enough.

#### With a hint

#### With an error

`error` replaces `hint` — only one message shows at a time, and the error text gets
`role="alert"`.

#### Props

#### Accessibility

- Same wiring as `Input`: a real `<label htmlFor>`, `hint`/`error` text linked through
  `aria-describedby`, and `aria-invalid="true"` plus `role="alert"` on the error text
  when `error` is set.
- The native resize handle is left on (`resize: vertical` in the stylesheet) — the
  component doesn't disable it.
- The ref forwards to the underlying `<textarea>`.

Do:
- Pass label always — required, same field pattern as Input.
- Use hint to set expectations before typing and error for validation feedback after submit.
- Let the native resize handle work — Textarea doesn’t disable it.

Don't:
- Use Textarea for a single line of text — Input is the right call there.
- Expect both hint and error to render together — only error shows once it’s set.
- Hardcode a tiny rows value for content you know runs long — give it room to breathe.

#### Related

Machine-readable record: /r/textarea.json

### Alert (molecules)

Status callout for success, warning, danger, and info messages.

Import: `import { Alert } from '@elirobinson/react/components/molecules/Alert';`
Styles: @elirobinson/react/styles/molecules/Alert.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| title | `string` | no | — | — |
| variant | `"default" \| "success" \| "warning" \| "danger" \| "info"` | no | default | — |

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `Alert` for a status message tied to the content around it — a save confirmation above
a form, a warning inline in a settings panel. It stays on the page until you remove it or
the underlying condition changes; it doesn't dismiss itself.

For a message that should interrupt briefly and then go away, use `Toast` instead. For a
single-word status label inline with other content (a row, a card header), `Badge` is the
lighter option — `Alert` is for a sentence, not a tag.

#### Variants

`default` is a neutral callout with no color association — use it for information that
isn't good or bad news. The other four map to status meaning: `success`, `warning`,
`danger`, `info`.

#### Props

#### Accessibility

- Renders with `role="alert"` by default, which most screen readers announce
  immediately as an assertive live region — reserve `Alert` for messages that genuinely
  need that interruption. Pass `role="status"` explicitly for a politer, non-interrupting
  announcement.
- `title` and `children` are both optional and render as separate elements
  (`ds-alert__title`, `ds-alert__description`) — pass at least one; an `Alert` with
  neither renders an empty shell.
- There's no built-in dismiss button. If you need one, compose it yourself and manage
  the `Alert`'s presence in state — the component doesn't invent a close affordance.
- The ref forwards to the outer `<div>`.

Do:
- Pair the variant with matching language — "warning" copy that actually warns, not a neutral status buried in an amber box.
- Keep the message short enough to read at a glance; link out for anything longer.
- Use variant="danger" for something the reader must act on, not routine information.
- Remove the Alert from the DOM once its condition resolves, rather than leaving a stale "Saved" banner on screen.

Don't:
- s Toast.",
    
- ,
    
- ,
    

#### Related

Machine-readable record: /r/alert.json

### Breadcrumb (molecules)

Page-hierarchy trail with a current-page marker.

Import: `import { Breadcrumb, BreadcrumbLink, BreadcrumbSeparator, BreadcrumbList, BreadcrumbItem } from '@elirobinson/react/components/molecules/Breadcrumb';`
Styles: @elirobinson/react/styles/molecules/Breadcrumb.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLElement>` props.

(no props of its own beyond inherited HTML attributes)

#### BreadcrumbLink

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| current | `boolean` | no | — | — |
| href | `string` | no | # | — |
Also accepts all `HTMLAttributes<HTMLSpanElement>` props.

#### BreadcrumbSeparator

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLSpanElement>` props.

#### BreadcrumbList

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLOListElement>` props.

#### BreadcrumbItem

(no props of its own beyond inherited HTML attributes)
Also accepts all `LiHTMLAttributes<HTMLLIElement>` props.

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `Breadcrumb` to show where a page sits in a fixed hierarchy — store category, then
product, then variant. It's a trail, not a navigation menu: it only goes up, and it only
makes sense when the hierarchy is real and shallow. If the structure is a flat set of
sibling pages instead, `NavigationMenu` or plain links fit better.

#### Custom separator

`BreadcrumbSeparator` defaults to `/` but accepts any children — pass an icon or a
different character to match a tighter visual rhythm.

#### Props

#### Accessibility

- `Breadcrumb` renders a `<nav aria-label="Breadcrumb">` — pass your own `aria-label` to
  override the default if you have more than one breadcrumb trail on a page.
- `BreadcrumbList` is a native `<ol>`; `BreadcrumbItem` is a native `<li>` — the ordered
  list is what gives the trail its "you are here, by way of these" semantics.
- `BreadcrumbLink` renders two different elements depending on `current`: a real
  `<a href>` for every ancestor crumb, and a non-interactive `<span aria-current="page">`
  for the current page. The current crumb is intentionally not a link — you're already
  there.
- `BreadcrumbSeparator` is `aria-hidden="true"`, so screen readers skip the `/` (or
  whatever you pass) entirely and rely on the list structure instead.
- **Keyboard:** ordinary link behavior — `Tab` moves between the ancestor links, `Enter`
  follows them. The current crumb isn't in the tab order since it isn't a link.
- `Breadcrumb`, `BreadcrumbList`, and `BreadcrumbItem` forward refs to their native
  elements; `BreadcrumbLink` and `BreadcrumbSeparator` don't.

Do:
- Mark the last crumb current — it renders as plain text instead of a dead link to the current page.
- Keep labels short: category and product names, not full sentences.
- Use real hrefs on every ancestor link so middle-click and cmd-click work.
- Limit the trail to the hierarchy that actually matters — three to five crumbs is typical.

Don't:
- Make the current page a clickable link to itself.
- s main navigation.",
    
- ,
    "Rely on the separator text for meaning — it

#### Related

Machine-readable record: /r/breadcrumb.json

### Card (molecules)

Bordered content surface with header, title, description, content, and footer subcomponents.

Import: `import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@elirobinson/react/components/molecules/Card';`
Styles: @elirobinson/react/styles/molecules/Card.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

(no props of its own beyond inherited HTML attributes)

#### CardHeader

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

#### CardTitle

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLHeadingElement>` props.

#### CardDescription

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLParagraphElement>` props.

#### CardContent

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

#### CardFooter

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `Card` to group related content into one bordered surface — a portfolio tile, a
pricing tier, a contact block. It's a layout primitive, not a status signal: for a
message about the state of the page, reach for `Alert`; for a placeholder where a list
of cards would normally go, use `EmptyState`.

`CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, and `CardFooter` are plain
layout slots — use the ones you need and skip the rest. A card doesn't require content
and a footer both.

#### With content and actions

#### Props

#### Accessibility

- `Card` and its subcomponents render plain `<div>`s (and `CardTitle` an `<h3>`,
  `CardDescription` a `<p>`) with no implicit ARIA role — a card is a visual grouping,
  not a landmark.
- `CardTitle` always renders an `<h3>`. It isn't configurable, so check that an `<h3>`
  is the right level in the surrounding heading outline before reaching for it — inside
  a page that's already past `<h3>`, write your own heading element instead.
- Only `Card` itself forwards a ref, to the outer `<div>`. `CardHeader`, `CardTitle`,
  `CardDescription`, `CardContent`, and `CardFooter` are plain functions with no ref
  forwarding.
- **Keyboard:** a `Card` has no interaction of its own. Any buttons or links placed
  inside it (as in `CardFooter`) keep their own native keyboard behavior.

Do:
- Put the primary action in CardFooter as a real Button or link.
- Keep CardTitle to a short name — a product, a plan, a project — and put detail in CardDescription.
- Use Badge inside CardHeader for category tags above the title.
- Give a Card a fixed maxWidth in a grid so cards align instead of stretching unevenly.

Don't:
- s a content surface, not a page layout tool.",
    
- ,
    
- ,
    

#### Related

Machine-readable record: /r/card.json

### Chip (molecules)

Compact tag with an optional dense remove button.

Import: `import { Chip } from '@elirobinson/react/components/molecules/Chip';`
Styles: @elirobinson/react/styles/molecules/Chip.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLSpanElement>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| onRemove | `(() => void)` | no | — | — |
| removeLabel | `string` | no | — | Accessible name for the remove button. Defaults to `Remove ${children}`,
which only produces a correct label when `children` is a plain string.
Pass this explicitly when `children` is an element (e.g. `<b>Design</b>`). |

Constraints: no-barrel-imports, forward-ref, touch-target-dense, hit-area-no-overlap (see System constraints)

#### When to use it

Use `Chip` for a compact, removable tag — an active filter, a selected item in a
multi-select field, a keyword attached to a piece of content. Without `onRemove` it's
just a static tag; with it, a small `×` button appears. For a status label that's never
removable, `Badge` is the simpler component.

#### Removable

Pass `onRemove` to get the dense remove button. It's sized to the shadcn/MUI scale, not
the 44px primary-control minimum — a chip is an inline, dense affordance, not a button.

#### Props

#### Accessibility

- Renders a `<span>` wrapper around a label span and, when `onRemove` is passed, a
  native `<button type="button">` for removal — everything else about the chip is
  non-interactive.
- The remove button's accessible name defaults to `` `Remove ${children}` ``. That only
  produces a correct label when `children` is a plain string — pass `removeLabel`
  explicitly when the content is an element (`<b>Design</b>` would otherwise stringify
  wrong).
- The remove button follows dense inline sizing (MUI/shadcn scale), not the 44px
  primary-control minimum, since a chip's own footprint is already small.
- **Keyboard:** the remove button is a native `<button>` — `Tab` reaches it, `Enter` and
  `Space` activate it. The chip body itself isn't focusable.
- The ref forwards to the outer `<span>`.

Do:
- Keep chip labels to a word or short phrase — a filter name, a tag, a selected value.
- Pass removeLabel when the chip content is anything other than plain text.
- Update surrounding state (a filter list, a form value) synchronously in onRemove.
- Use Chip for values the user actively chose and can un-choose.

Don't:
- t removable — that
- s target is bounded to its own footprint.",
    
- ,
    

#### Related

Machine-readable record: /r/chip.json

### DecisionCard (molecules)

A verdict, the figures behind it, and an action that exists only when the verdict allows one.

Import: `import { DecisionCard } from '@elirobinson/react/components/molecules/DecisionCard';`
Styles: @elirobinson/react/styles/molecules/DecisionCard.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| headline | `string` | yes | — | — |
| verdict | `"go" \| "no" \| "hold"` | yes | — | — |
| verdictLabel | `string` | yes | — | — |
| action | `ReactNode` | no | — | — |
| caveat | `string` | no | — | — |
| closing | `string` | no | — | — |
| contrast | `{ label: string; value: string; }` | no | — | — |
| figures | `DecisionFigure[]` | no | — | — |
| headingLevel | `2 \| 3 \| 4 \| 5 \| 6` | no | 2 | Heading level (2-6) for `headline`, which renders as the real heading
element rather than a styled paragraph. There is no single correct level
for an arbitrary document outline, so this is exposed rather than
hardcoded — a card sitting under a page `<h1>` leaves the default
(`headingLevel={2}`), one inside an `<h2>` section passes
`headingLevel={3}`. Defaults to 2. |
| subject | `string` | no | — | — |
| total | `{ label: string; value: string; }` | no | — | — |

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

`DecisionCard` is for a surface that has reached a conclusion and has to show its work: a
verdict at the head, the figures behind it, a contrasting figure to measure against, the
caveat that qualifies it, and — only sometimes — an action. It composes `VerdictBadge` for
the marker, so the verdict is a glyph and a word rather than a colour.

Use it when the reader's next question is "why?" A surface that only announces an outcome
doesn't need this; a surface that has to justify one does.

#### Named for the shape, not the subject

`DecisionCard` is named for its shape — verdict, figures by kind, contrast figure, caveat,
conditional action — and not for any particular thing a product puts in it. That shape is
a quote, an eligibility result, or a risk assessment just as readily as it is a
recommendation, which is why the name says "decision" and not something narrower.

The same reasoning drives `kind` on a figure. It renders as `data-kind` rather than
resolving to a class from a fixed enum, so a product can group its figures — costs,
coverage, timing, whatever it actually tracks — and style those groups from its own
stylesheet, without the system having to learn the product's vocabulary or grow a union
type every time a product invents a category.

#### The footer guarantee

When `action` is absent, `DecisionCard` renders **no `.ds-decision__foot` element at all**
— not a disabled button, not a hidden one, nothing. This is a product guarantee, not a
style choice, and it has its own test in the package.

The reason is blunt. A decision surface that can render a "pay now" control under a "do
not buy" verdict is one CSS bug away from taking a user's money against its own advice,
and a disabled button is exactly that bug waiting for a stylesheet to lose. One override,
one stray `disabled={false}`, one screen reader that ignores `hidden`, and the control is
live again. The only way to be certain that can't happen is for the element not to exist —
so a negative verdict is structurally incapable of offering a payment control.

`closing` is what carries the last word instead. It renders in the body, above where a
footer would have been, so a card that recommends against something still ends on a
sentence rather than trailing off. Pass `closing` on every negative verdict; it's the
replacement for the button you're not shipping.

If you need a control near a "no" — "remind me later," "see other options" — put it
outside the card, where it can be labelled for what it actually does and can't inherit the
card's authority.

#### Heading level

`headline` renders as a real heading element, not a styled paragraph — it is the card's
title in the document outline, so a screen reader's heading navigation has to be able to
find it. There is no single correct level for an arbitrary outline, so `headingLevel` is
exposed rather than hardcoded: leave the default (`headingLevel={2}`, an `<h2>`) for a card
sitting under the page's own `<h1>`, and pass `headingLevel={3}` for one inside an `<h2>`
section. An out-of-range value falls back to 2 rather than crashing the tree.

The range starts at 2 where `Accordion`'s starts at 1. An accordion can legitimately be the
only thing on a page; a card that claimed the document's `<h1>` would be claiming to be the
page. The type ramp is carried by the class, so every level looks identical and only the
outline changes.

#### Props

#### Accessibility

- `headline` is a real `<h2>`–`<h6>` (see "Heading level" above), so the card has a title in
  the document outline and heading navigation lands on it.
- The figures render as a real `<dl>`: each figure's `label` is a `<dt>` and its `value` a
  `<dd>`, so the pairing holds without the grid.
- Figures are keyed by `kind` and `label` together, so the same label can appear under two
  different kinds without a key collision.
- `total` and `contrast` render as paragraphs rather than more `<dl>` entries — they're a
  summation and a comparison, not further items of the same list.
- The verdict marker comes from `VerdictBadge`: its glyph is `aria-hidden` and
  `verdictLabel` is the accessible text. Write it as the verdict in words.
- The card itself has no role and no live region. If a verdict updates in place, announce
  that from wherever your product owns status messages.
- **Keyboard:** only the node you pass as `action` is focusable. When there's no action
  there's nothing to tab to, which is the intended outcome, not an oversight.
- The ref forwards to the outer `<div>`.

Do:
- Pass closing on every negative verdict — it is what replaces the missing footer.
- Give the reader the contrast figure; a number with nothing to measure against persuades nobody.
- State the caveat that would change the verdict, in the caveat slot.
- Use kind to group figures your product already groups, and style them from your own stylesheet.

Don't:
- Pass a disabled button as action to "grey out" an offer — omit action instead.
- Reintroduce a footer with a wrapper element that renders whether or not there is an action.
- Put a payment control outside the card and style it to look like it belongs to a "no" verdict.
- Use it for a plain summary with no judgement in it; that is Card or StubCard.

#### Product theming

`DecisionCard` inherits the product token layer through the `VerdictBadge` it composes:
the verdict fills and foregrounds read `--product-verdict-*` with a fallback to the
matching system status token. The convention is documented in
`docs/agents/product-token-layer.md`, and the fallback keeps it optional — a product that
declares nothing gets the system palette.

#### Related

Machine-readable record: /r/decision-card.json

### EmptyState (molecules)

Placeholder for empty data — title, description, icon, and action slot.

Import: `import { EmptyState } from '@elirobinson/react/components/molecules/EmptyState';`
Styles: @elirobinson/react/styles/molecules/EmptyState.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| action | `ReactNode` | no | — | — |
| description | `string` | no | — | — |
| icon | `ReactNode` | no | — | — |
| title | `string` | no | — | — |

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `EmptyState` wherever a list, table, or search result would normally render rows
and currently has none — a fresh account with no data yet, or a filtered view that
matched nothing. It's `Table`'s own empty-rows branch under the hood.

It's not a loading indicator — while data is in flight, use `Skeleton`. And it's not a
system message about something that went wrong — an error belongs in `Alert`.

#### With icon and action

`icon` and `action` are both optional. An action gives the reader a way out of the empty
state — clear a filter, create the first item — instead of leaving them at a dead end.

#### Props

#### Accessibility

- Renders a plain `<div>` with no ARIA role — it's a content placeholder, not a live
  region or an alert.
- `title` renders as a `<p>`, not a heading element. If the empty state is the main
  content of a section that needs a heading in the outline, add your own heading
  alongside it rather than relying on `title`.
- `icon` renders exactly what you pass, with no automatic `aria-hidden` — mark decorative
  icons `aria-hidden="true"` yourself, the way the demo above does.
- `action` is a plain slot — usually a `Button` — and keeps whatever accessible name and
  keyboard behavior that control already has.
- The ref forwards to the outer `<div>`.

Do:
- Say what happened and, when there's a way forward, give an action for it — "No results — clear filters."
- Match the tone to the situation: a fresh empty list reads differently than a filtered-to-zero one.
- Mark decorative icons aria-hidden yourself.
- Reuse the same EmptyState across a table and its windowed VirtualTable sibling — the placeholder logic is identical.

Don't:
- Use EmptyState for a loading placeholder — reach for Skeleton while data is in flight.
- Use EmptyState to report an error — that belongs in Alert, with recovery guidance.
- Leave title blank and lean on description alone; title is the one line every empty state needs.
- Bury the action below the fold in a tall empty region — keep it close to the message.

#### Related

Machine-readable record: /r/empty-state.json

### FormField (molecules)

Label, hint, and error wrapper for controls that don't wire their own accessibility.

Import: `import { FormField } from '@elirobinson/react/components/molecules/FormField';`
Styles: @elirobinson/react/styles/molecules/FormField.css (included in styles.css)
Also accepts all `Omit<HTMLAttributes<HTMLDivElement>, 'children'>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| htmlFor | `string` | yes | — | — |
| label | `string` | yes | — | — |
| error | `string` | no | — | — |
| hint | `string` | no | — | — |
| required | `boolean` | no | — | — |

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `FormField` when you're labelling a control that doesn't wire its own label, hint,
and error — a plain `<input>`, a native `<select>`, a third-party widget. It owns the
`<label>` and message markup, and hands the control a bundle of accessibility props
(`aria-describedby`, `aria-invalid`, `aria-required`) through a render prop.

**Never wrap `Input` or `Textarea` in `FormField`.** Both already render their own label
and message region — nesting them produces two labels for one control. Reach for
`FormField` specifically when the control underneath doesn't do that wiring itself.

#### With an error

`error` and `hint` are mutually exclusive in the rendered output — when both are set,
the error wins and the hint is hidden. `required` adds a visible `*` next to the label
(hidden from screen readers, since `aria-required` on the control already says it).

#### Wrapping an arbitrary control

`FormField`'s render prop works with anything that accepts `aria-describedby`,
`aria-invalid`, and `aria-required` — not just `<input>`. Here it labels a native
`<select>`.

#### Props

#### Accessibility

- Renders a `<Label htmlFor={htmlFor}>` and calls `children` with a
  `{ 'aria-describedby', 'aria-invalid', 'aria-required' }` bundle — spread that bundle
  onto the control you render inside.
- `FormField` does **not** generate or set the child's `id` for you. You're responsible
  for giving the control an `id` that matches `htmlFor` — that's what makes clicking the
  label focus the field.
- `aria-describedby` is only set when `hint` or `error` is present; both share one
  generated id, since only one message renders at a time.
- The `*` appended to a `required` label is `aria-hidden="true"` — the accessible
  requirement signal is `aria-required="true"` on the control itself, not the asterisk.
- **Keyboard:** no custom behavior of its own — once the `id`/`htmlFor` pair is wired
  correctly, clicking the label focuses the control via native browser behavior.
- The ref forwards to the outer `<div>`.

Do:
- Keep the child id and htmlFor in sync by hand — FormField does not generate one for you.
- t need.",
    "Reach for FormField specifically for controls that don
- Write error text that says what to do, not just that something is wrong.

Don't:
- Nest Input or Textarea inside FormField — they already render their own label and message region.
- Set both hint and error and expect to see both — only error renders.
- Skip the id on the child control; without it the label has nothing to point to.
- Use required without also making the control itself enforce it — the asterisk is a visual cue, not validation.

#### Related

Machine-readable record: /r/form-field.json

### Pagination (molecules)

Page-button list with aria-current marking and 44px targets.

Import: `import { Pagination } from '@elirobinson/react/components/molecules/Pagination';`
Styles: @elirobinson/react/styles/molecules/Pagination.css (included in styles.css)
Also accepts all `Omit<HTMLAttributes<HTMLElement>, 'onChange'>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| onPageChange | `(page: number) => void` | yes | — | — |
| page | `number` | yes | — | — |
| pageCount | `number` | yes | — | — |

Constraints: no-barrel-imports, forward-ref, touch-target-primary, hit-area-no-overlap (see System constraints)

#### When to use it

Use `Pagination` for a page-by-page list or table where jumping straight to page 7
matters — a store catalog, a search results page. It renders one button per page with no
windowing, which is fine through the range most lists actually use; past a hundred or so
pages the button row gets long, so pull in `Table`'s own built-in pagination or a
windowed `VirtualTable`/`VirtualList` instead of raw `Pagination` at that scale.

#### Boundary states

Previous disables on page one, Next disables on the last page. `onPageChange` is never
called with an out-of-range value — clicking Previous on page one, for instance, simply
does nothing.

#### Props

#### Accessibility

- Renders a `<nav aria-label="Pagination">` wrapping a `<ul>` of page buttons plus
  Previous/Next buttons — pass your own `aria-label` to override the default if a page
  has more than one paginated region.
- The active page button gets `aria-current="page"`; every page button has an
  `aria-label` of `Page {n}` so its number reads correctly even without visible page
  context.
- Previous and Next carry `aria-label="Previous page"` / `"Next page"` and use the native
  `disabled` attribute at the boundaries — a screen reader announces them as
  unavailable, not just visually dimmed.
- **Keyboard:** every button (Previous, each page, Next) is a native `<button>` in
  normal tab order. There's no roving tabindex and no arrow-key navigation between
  pages — `Tab` walks through them one at a time, same as any other button row.
- This is a primary control, so every button keeps the 44×44px touch target minimum.
- The ref forwards to the outer `<nav>`.

Do:
- Keep page and pageCount in sync with your actual data — Pagination does not fetch or slice anything itself.
- Pair it with a loading state on the list below so a page change reads as a swap, not a jump.
- Let onPageChange scroll the list back into view if the page content is long.
- Reach for windowed pagination once the page count climbs into the hundreds.

Don't:
- Render Pagination for a list short enough to fit on one page.
- t wired.",
    
- ,
    "Reimplement Table

#### Related

Machine-readable record: /r/pagination.json

### Rating (molecules)

Star rating — read-only by default, interactive when given a change handler.

Import: `import { Rating } from '@elirobinson/react/components/molecules/Rating';`
Styles: @elirobinson/react/styles/molecules/Rating.css (included in styles.css)
Also accepts all `Omit<HTMLAttributes<HTMLDivElement>, 'role'>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| value | `number` | yes | — | — |
| max | `number` | no | 5 | — |
| onValueChange | `((value: number) => void)` | no | — | — |

Constraints: no-barrel-imports, forward-ref, touch-target-dense, hit-area-no-overlap (see System constraints)

#### When to use it

`Rating` switches its own mode based on whether you pass `onValueChange`: omit it and
you get a read-only star display for showing an existing score (a recipe card, a
testimonial); pass it and the stars become interactive buttons for collecting one. You
don't choose the mode explicitly — the prop you pass decides it.

#### Interactive

#### Props

#### Accessibility

- **Read-only mode** (no `onValueChange`): renders `role="img"` on the outer element with
  `aria-label="{value} out of {max} stars"` — a screen reader hears the whole rating as
  one static image-like value, not a list of individual stars.
- **Interactive mode** (`onValueChange` passed): each star is a native
  `<button type="button">` with `aria-label="Rate {n} out of {max} stars"` and
  `aria-pressed` reflecting whether that star is filled.
- `value` is clamped to the `0`–`max` range before it's used in the accessible label, so
  an out-of-range value (negative, or above `max`) never produces a nonsensical
  announcement.
- **Keyboard:** in interactive mode, each star button is independently focusable — `Tab`
  moves star to star, `Enter` and `Space` activate whichever one has focus. There's no
  arrow-key traversal between stars; this is a row of buttons, not a slider.
- Star buttons follow dense inline sizing (MUI/shadcn scale), not the 44px
  primary-control minimum.
- The ref forwards to the outer element in both modes.

Do:
- Omit onValueChange for a rating you're only displaying — it gets you the cheaper role="img" markup.
- t easily count filled icons.",
    
- ,
    

Don't:
- t be able to change, like an aggregate average.",
    
- ,
    
- ,
    

#### Related

Machine-readable record: /r/rating.json

### RuleLink (molecules)

Ink-underline arrow link for marketing pages.

Import: `import { RuleLink } from '@elirobinson/react/components/molecules/RuleLink';`
Styles: @elirobinson/react/styles/molecules/RuleLink.css (included in styles.css)
Also accepts all `AnchorHTMLAttributes<HTMLAnchorElement>` props.

(no props of its own beyond inherited HTML attributes)

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `RuleLink` for the ink-underline arrow link that closes out a marketing section —
"View all guides," "See what I build." It's a real `<a>` with an arrow glyph appended, not
a button dressed up as a link — reach for it anywhere a `Button` would be the wrong
semantic because the action is navigation, not a command.

#### In a list

RuleLink reads well stacked as a set of section links — a services page footer, a set of
"jump to" pointers.

#### Props

#### Accessibility

- Renders a native `<a>` with a trailing arrow `<svg aria-hidden="true">` — the arrow is
  purely decorative, so a screen reader reads only the link text.
- Accepts all standard anchor attributes (`href`, `target`, `rel`, and so on) since it
  inherits `AnchorHTMLAttributes<HTMLAnchorElement>` — always pass a real `href`.
- **Keyboard:** native anchor behavior — `Tab` focuses it, `Enter` follows the link.
  There's no `Space`-to-activate, matching how every other link on the page behaves.
- The ref forwards to the underlying `<a>` element.

Do:
- Write the label as a destination, not a verb — "View all guides," not "Click here."
- Always give it a real href so middle-click and cmd-click work.
- Use it to close out a section on a marketing or content page.
- Keep the label short enough that the arrow reads as a natural continuation.

Don't:
- t navigate — submitting, opening a dialog — that
- Pair it with an onClick that prevents default navigation; that breaks the "it's just a link" contract.
- s what Breadcrumb is for.",
    

#### Related

Machine-readable record: /r/rule-link.json

### SearchField (molecules)

Search input with a built-in dense clear button.

Import: `import { SearchField } from '@elirobinson/react/components/molecules/SearchField';`
Styles: @elirobinson/react/styles/molecules/SearchField.css (included in styles.css)
Also accepts all `Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'onChange' | 'value' | 'defaultValue'>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| defaultValue | `string` | no | — | — |
| onValueChange | `((value: string) => void)` | no | — | — |
| value | `string` | no | — | — |

Constraints: no-barrel-imports, forward-ref, touch-target-dense, hit-area-no-overlap (see System constraints)

#### When to use it

Use `SearchField` for an inline filter — a table toolbar, a list you want to narrow as
you type. It's an `<input type="search">` with a built-in clear button, nothing more. For
filtering that also opens a list of matching options to pick from, use `Combobox`
instead; `SearchField` never renders a popup.

Like `Input`, it supports both patterns: pass `value`/`onValueChange` to drive it from
your own state (as in the filtering example below), or `defaultValue` and let it manage
its own state uncontrolled.

#### Controlled, filtering a list

#### Props

#### Accessibility

- `SearchField` doesn't render its own `<label>` — unlike `Input`, it has no `label`
  prop. Give it an accessible name yourself with `aria-label` (as every demo on this page
  does) or `aria-labelledby`, or wrap it in `FormField` if you want a visible label plus
  hint/error text.
- The underlying element is a native `<input type="search">`, which browsers and screen
  readers expose with the `searchbox` role automatically.
- The clear button only renders once there's a value, carries
  `aria-label="Clear search"`, and returns focus to the input after clearing — so
  clearing never strands keyboard focus.
- The clear button follows dense inline sizing (MUI/shadcn scale), not the 44px
  primary-control minimum.
- **Keyboard:** standard text-input behavior — type to filter, `Tab` reaches the clear
  button when it's present, `Enter`/`Space` activates it. There's no `Escape`-to-clear
  shortcut wired in.
- The ref forwards to the real `<input>` element, not the wrapping `<div>` — calling
  `ref.current.focus()` works directly. `Combobox` and `CommandPalette` both depend on
  this.

Do:
- Always give it an aria-label or aria-labelledby — it has no visible label of its own.
- Debounce the filtering logic in onValueChange for anything more expensive than an in-memory array filter.
- Show a "no results" message in the list below rather than leaving it silently empty.

Don't:
- re different components with different label handling.",
    "Expect a popup of matching options — that
- Rely on Escape to clear the field; wire your own keydown handler if you want that.
- s dense hit area when laying out tight toolbar spacing — verify it doesn

#### Related

Machine-readable record: /r/search-field.json

### SegmentedControl (molecules)

Radio-style option group with arrow-key navigation and 44px targets.

Import: `import { SegmentedControl } from '@elirobinson/react/components/molecules/SegmentedControl';`
Styles: @elirobinson/react/styles/molecules/SegmentedControl.css (included in styles.css)
Also accepts all `Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'role'>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| onValueChange | `(value: string) => void` | yes | — | — |
| options | `SegmentedControlOption[]` | yes | — | — |
| value | `string` | yes | — | — |

Constraints: no-barrel-imports, forward-ref, touch-target-primary, hit-area-no-overlap (see System constraints)

#### When to use it

Use `SegmentedControl` for a small, mutually exclusive set of view or mode options —
Day/Week/Month, List/Grid — where exactly one is always selected and switching is
instant. It's semantically a radio group in a horizontal row, not a set of tabs: `Tabs`
pairs each option with its own content panel, while `SegmentedControl` just reports which
option is picked and leaves what happens next to you.

#### Driving other content

The selected value is ordinary state — use it to switch what renders below the control,
the way a view toggle usually works.

#### Props

#### Accessibility

- Renders `role="radiogroup"` on the outer element and `role="radio"` with
  `aria-checked` on each option — the same pattern a native radio group uses, just laid
  out horizontally.
- Uses roving tabindex: only the selected option (or the first one, if none is selected)
  is a tab stop; the rest are `tabIndex={-1}`. `Tab` moves into and out of the whole
  group in one stop, not option by option.
- **Keyboard:** `ArrowRight`/`ArrowDown` moves to the next option, `ArrowLeft`/`ArrowUp`
  to the previous, both wrapping at the ends; `Home` and `End` jump to the first and
  last option. Unlike `Tabs`, moving with arrow keys also selects — that's the
  radio-group convention this component follows.
- Clicking an option selects it directly, independent of keyboard focus.
- This is a primary control, so every option keeps the 44×44px touch target minimum.
- The ref forwards to the outer `role="radiogroup"` element.

Do:
- Keep it to two to five options — past that it stops reading as a single control.
- Use it when exactly one option is always selected; there's no "none selected" state.
- Pair short, parallel labels — Day/Week/Month, not one short label next to one long sentence.
- Let arrow-key movement select immediately, matching native radio-group behavior.

Don't:
- s Tabs.",
    "Use it for a single on/off choice — that
- Shrink the touch target below 44px for a denser look; density comes from the visible control, not the hit area.
- Mix it up with RadioGroup for a long vertical list of options — SegmentedControl is for a short horizontal set.

#### Related

Machine-readable record: /r/segmented-control.json

### Stepper (molecules)

Ordered-list progress indicator for multi-step flows.

Import: `import { Stepper } from '@elirobinson/react/components/molecules/Stepper';`
Styles: @elirobinson/react/styles/molecules/Stepper.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLOListElement>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| activeStep | `number` | yes | — | — |
| steps | `StepperStep[]` | yes | — | — |

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `Stepper` to show progress through a fixed, linear, multi-step flow — checkout,
onboarding, a multi-page form. `activeStep` is 1-indexed: a step is complete when its
number is below `activeStep`, active when it equals `activeStep`, and upcoming
otherwise. It's a display component only — it doesn't make steps clickable and it
doesn't manage which step you're on; your flow's own state drives `activeStep`.

For a continuous percentage rather than discrete named steps, use `Progress` instead.

#### Through a flow

#### Props

#### Accessibility

- Renders a native `<ol>` with one `<li>` per step — the ordered list itself conveys
  sequence, independent of any visual styling.
- The active step's `<li>` gets `aria-current="step"`.
- The step indicator (a number or a `✓` for completed steps) is **not** hidden from
  screen readers — it's announced along with the label, so a completed step reads as
  something like "check mark, Account" rather than silently showing just "Account."
- **Keyboard:** none — `Stepper` renders no interactive elements, so there's nothing to
  tab to. If you need clickable steps (jump back to a previous one), you'll need to
  build that affordance yourself; the component doesn't invent it.
- The ref forwards to the outer `<ol>`.

Do:
- Keep step labels to one or two words — "Payment," not "Enter your payment details."
- s content is rendered.",
    
- ,
    

Don't:
- s a progress display, not navigation.",
    
- ,
    
- ,
    "Reach for Stepper when a simple percentage is all you need — that

#### Related

Machine-readable record: /r/stepper.json

### StubCard (molecules)

A summary that reads as a ticket stub: a body column beside a perforated stub column.

Import: `import { StubCard } from '@elirobinson/react/components/molecules/StubCard';`
Styles: @elirobinson/react/styles/molecules/StubCard.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| items | `StubCardItem[]` | yes | — | — |
| stubLabel | `string` | yes | — | — |
| stubValue | `string` | yes | — | — |
| footnote | `string` | no | — | — |
| stubCaption | `string` | no | — | — |
| title | `string` | no | — | — |

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

`StubCard` is a summary that reads as a ticket stub: a body column of labelled details
beside a perforated stub column carrying the one figure that matters. It's built for the
moment before a user commits — the confirmation step where they check what they're about
to do against what they meant to do.

The split is the point. Everything the reader needs to verify goes in the body; the single
number they'll remember goes in the stub. If your summary has two equally important
figures, it isn't a stub — use `Card`.

#### The perforation

The tear line between the two columns is a dashed `--border-control`, not the decorative
`--border`. That's a deliberate distinction: `--border` is a faint seam meant to be felt
rather than read, and this line carries meaning — it says the stub detaches, which is the
entire reason the layout has two columns. A line that means something gets the 3:1 edge
token, the same one a control's boundary uses.

Below roughly 30rem the stub tears off the bottom instead of the side, and the perforation
moves with it.

#### Props

#### Accessibility

- The body's details render as a real `<dl>`, with each `label` a `<dt>` and each `value`
  a `<dd>`, so the pairing survives without visual layout.
- `items` is keyed by `label`, so labels within one card must be unique. Two rows called
  "Date" are a React key collision as well as an ambiguous summary.
- The stub column is plain text, not a heading — it's the emphasised figure in a summary,
  not a section title, and marking it up as one would put a stray entry in the document
  outline.
- Nothing here is interactive: `StubCard` renders no buttons and no links. The control the
  user presses to commit belongs below the card, where it can be labelled with what it
  actually does.
- **Keyboard:** none of its own.
- The ref forwards to the outer `<div>`.

Do:
- Put the figure the user is confirming — the amount, the date, the count — in the stub.
- Keep item labels short and unique; they are the keys as well as the copy.
- Use footnote for the one caveat that belongs with the summary, not a paragraph.
- Show it immediately before the commit control, not after the fact.

Don't:
- Use it as a general content card — that is Card.
- Put two competing figures in the stub column; it holds one.
- Style the perforation with the decorative border token; it would drop below 3:1.
- Nest interactive controls inside it and expect the layout to make room.

#### Product theming

`StubCard` draws only system tokens — surface, border, type, spacing — so it inherits a
product's theme without reading the `--product-*` layer itself. It sits comfortably beside
components that do; the convention is documented in `docs/agents/product-token-layer.md`,
and every read there falls back to a system token.

#### Related

Machine-readable record: /r/stub-card.json

### VerdictBadge (molecules)

A decision marker that states its verdict as a glyph and a word, never by colour alone.

Import: `import { VerdictBadge } from '@elirobinson/react/components/molecules/VerdictBadge';`
Styles: @elirobinson/react/styles/molecules/VerdictBadge.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLSpanElement>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| label | `string` | yes | — | — |
| verdict | `"go" \| "no" \| "hold"` | yes | — | — |
| glyph | `ReactNode` | no | — | — |

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

`VerdictBadge` marks a judgement: `go`, `no`, or `hold`. Use it where a surface has come
to a conclusion and the reader needs to see which one before reading anything else — the
head of a `DecisionCard`, a row in a results table, a summary at the top of a report.

Colour is never the only signal. The badge always draws a glyph **and** a word, so the
verdict survives greyscale, a colour-blind reader, and a theme switch. A marker that
signalled by fill alone would fail SC 1.4.1 (Use of Color), and this is a marker whose
whole job is to be unambiguous.

#### Not Badge

`Badge` is a label — a category, a status word, a count. It has no icon slot and no state
that reads as a decision in both themes, so a "verdict" built from `Badge` ends up being
carried by its fill colour alone. That's the failure mode this component exists to close.
Reach for `Badge` when you're tagging something, and `VerdictBadge` when you're
concluding something.

`glyph` overrides the default mark if a product has its own; `label` is always the
product's word.

#### Props

#### Accessibility

- The glyph is `aria-hidden="true"` on purpose. `✓`, `✕` and `◑` are punctuation-class
  characters: a screen reader may skip them silently or read them as something unhelpful,
  and which of those happens varies by reader and by verbosity setting. The glyph is the
  sighted channel only.
- `label` is therefore the accessible text, and it's required. The meaning never depends
  on a character a screen reader might drop.
- Write the label as the verdict itself — "Worth it," "Skip it" — not as a restatement of
  the colour or the glyph. It's the only thing a screen reader hears.
- Each verdict's fill and foreground are a measured pair, so the word clears contrast on
  its own tint in both themes.
- **Keyboard:** none — the badge renders a non-interactive `<span>`. If a verdict needs to
  be clickable, wrap it in your own control.
- The ref forwards to the outer `<span>`.

Do:
- Let the label carry the verdict in words, since that is what a screen reader reads.
- Keep the same label wording for the same verdict across a list, so it scans.
- Use hold for a conditional answer rather than inventing a fourth verdict.
- Pair it with the reasoning nearby — a verdict with no figures behind it is a guess.

Don't:
- Replace the glyph with something that only means anything in colour.
- Use it as a category tag; that is Badge.
- Write a label like "Green" that describes the styling instead of the decision.
- Rely on the glyph reaching a screen reader — it is hidden, deliberately.

#### Product theming

Each verdict fill and foreground reads a `--product-verdict-*` variable with a fallback to
the matching system status token, so a product can own its verdict palette without forking
the token set or hardcoding a literal a contrast gate can't follow. The convention is
documented in `docs/agents/product-token-layer.md`; declare none of it and the system
status colours apply.

#### Related

Machine-readable record: /r/verdict-badge.json

### Accordion (organisms)

Expandable sections with configurable heading levels.

Import: `import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@elirobinson/react/components/organisms/Accordion';`
Styles: @elirobinson/react/styles/organisms/Accordion.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLDivElement> & AccordionSharedProps` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| defaultValue | `string \| (readonly string[] & string) \| ((string \| number \| readonly string[]) & string[])` | no | — | — |
| headingLevel | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | no | 3 | Heading level (1-6) that wraps each trigger, per the WAI-ARIA accordion
pattern. There is no single correct default for an arbitrary document
outline, so this is exposed rather than hardcoded — a consumer nesting
an Accordion under an `<h2>` section should pass `headingLevel={3}` (the
default) while one nesting it directly under the page `<h1>` should pass
`headingLevel={2}`. Defaults to 3, the common case (accordion under a
page section heading). |
| onValueChange | `((value: string) => void) \| ((value: string[]) => void)` | no | — | — |
| type | `"multiple" \| "single"` | no | single | — |
| value | `string \| string[]` | no | — | — |

#### AccordionItem

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| value | `string` | yes | — | — |
| defaultValue | `string \| (readonly string[] & string) \| ((string \| number \| readonly string[]) & string[])` | no | — | — |
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

#### AccordionTrigger

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| defaultValue | `string \| (readonly string[] & string) \| ((string \| number \| readonly string[]) & string[])` | no | — | — |
| onClick | `MouseEventHandler<HTMLButtonElement>` | no | — | — |
Also accepts all `Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'id' | 'onClick' | 'aria-expanded' | 'aria-controls'>` props.

#### AccordionContent

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| defaultValue | `string \| (readonly string[] & string) \| ((string \| number \| readonly string[]) & string[])` | no | — | — |
Also accepts all `Omit<HTMLAttributes<HTMLDivElement>, 'id' | 'role' | 'aria-labelledby'>` props.

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `Accordion` for content that's fine collapsed by default — FAQs, settings groups,
secondary detail the reader can opt into rather than has to read. `type="single"` is right
when opening one section implies you're done with the others (an FAQ, a set of mutually
exclusive options); `type="multiple"` is right when a reader might want two sections open at
once to compare them.

Don't use it as a substitute for real page structure. If every "section" is content someone
always needs, put it directly on the page — collapsing it just adds a click.

#### Multiple sections open at once

#### Controlled

Pass `value` and `onValueChange` to drive the open section from outside — useful when
something else on the page (a link, a search result) needs to jump to a specific section.

#### Heading level

There's no single correct heading level for an arbitrary document outline, so `headingLevel`
is exposed rather than hardcoded. Nest an accordion under an `<h2>` page section and leave the
default (`headingLevel={3}`, an `<h3>` per trigger); nest it directly under the page's own
`<h1>` and pass `headingLevel={2}`. An out-of-range value falls back to 3 rather than crashing
the tree.

#### Props

#### Accessibility

- Follows the WAI-ARIA accordion pattern: each `AccordionTrigger` renders a real `<button>`
  wrapped in a heading tag (`headingLevel`, default `h3`).
- The trigger carries `aria-expanded` and `aria-controls`; the matching `AccordionContent`
  carries `id` and `aria-labelledby` pointing back at the trigger. All of it is computed
  internally — `id`/`aria-expanded`/`aria-controls`/`role`/`aria-labelledby` are omitted from
  the public prop types so a consumer can't silently clobber the wiring via a spread.
- A collapsed section's content isn't hidden with CSS — it isn't rendered at all. Tab order and
  screen reader traversal skip it entirely rather than landing on invisible text.
- **Keyboard:** `Tab`/`Shift+Tab` move between triggers, since every trigger is already a
  naturally focusable `<button>` in document order. `Enter`/`Space` toggle the focused trigger
  — native button behavior, nothing re-implemented. Arrow-key navigation between headers is
  intentionally not implemented: per the WAI-ARIA pattern it's optional for accordions (unlike
  tabs, which uses a single roving tab stop and requires it), so there's nothing broken here to
  fix.
- No `Escape` handling — accordions don't have an escape-to-collapse convention, and none is
  added here.

Do:
- Set headingLevel to match where the accordion sits in your page outline.
- Use type="single" for mutually exclusive content and type="multiple" when sections can be compared side by side.
- Give every AccordionItem a stable, unique value.
- Let content unmount when collapsed rather than hiding it with CSS — the built-in behavior already does this.

Don't:
- s click/keyboard only, by design.",
    
- ,
    
- ,
    

#### Related

Machine-readable record: /r/accordion.json

### Combobox (organisms)

Filterable single-select combobox with a virtualized listbox popup.

Import: `import { Combobox } from '@elirobinson/react/components/organisms/Combobox';`
Styles: @elirobinson/react/styles/organisms/Combobox.css (included in styles.css)

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| label | `string` | yes | — | Accessible label for the combobox input (also its accessible name). |
| onValueChange | `(value: string) => void` | yes | — | — |
| options | `ComboboxOption[]` | yes | — | — |
| className | `string` | no | — | — |
| value | `string` | no | — | — |

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `Combobox` when the option set is long enough that typing to filter beats scanning or
scrolling. It's a single-select, filterable field — type a few characters and the list narrows
to matches; arrow through them and pick one.

For a short, fixed list (ten or so options), a plain `Select` is less to build and there's
nothing worth filtering. And this isn't a general autocomplete-anything field: it only accepts
one of the `options` you pass in, not arbitrary free text.

#### Filtering a long list

The listbox is virtualized — it renders only the rows currently in view, not every option in
the array, so a list of hundreds stays as responsive as a list of ten. Try typing "drill 3" or
arrowing all the way to the bottom.

#### Props

#### Accessibility

- Implements the WAI-ARIA combobox-with-listbox pattern using `aria-activedescendant`, not the
  focus-moves-into-the-list model. The input carries `role="combobox"`,
  `aria-haspopup="listbox"`, `aria-expanded`, `aria-controls` (the listbox id),
  `aria-autocomplete="list"`, and `aria-activedescendant` pointing at whichever option is
  currently highlighted.
- DOM focus never leaves the input — the highlighted option is communicated purely by id
  reference. Options themselves are `tabIndex={-1}` and use `onMouseDown` preventDefault so
  clicking one never steals focus away from the input.
- **Keyboard:** `ArrowDown`/`ArrowUp` open the list if it's closed, or move the highlight by
  one option, clamped at both ends — the highlight stops at the first/last option rather than
  wrapping around. `Enter` selects the currently highlighted option (not always the first) and
  closes the list. `Escape` closes the list without changing the selected value.
  Typing any character re-opens the list if it was closed.
- Clicking outside the control closes the list (the outside-click listener is only attached
  while it's open).
- A query with no matches renders a labeled, empty listbox with "No matches" text rather than
  nothing at all — `aria-controls` always resolves to a real element, open or empty.
- The highlighted option is scrolled into view automatically as it moves past the edge of the
  virtualized window, so keyboard navigation never highlights something that's scrolled out of
  sight.

Do:
- Give every option a stable value distinct from its label.
- Pair it with a real accessible name via the required label prop.
- Trust the built-in virtualization for long option lists instead of pre-slicing options yourself.
- Keyboard-test Arrow/Enter/Escape, not just click-through — the highlight model depends on it.

Don't:
- Move DOM focus into the listbox yourself — the whole pattern depends on focus staying on the input.
- Pass duplicate values across options — the active-option lookup assumes one match.
- s nothing to filter.",
    

#### Related

Machine-readable record: /r/combobox.json

### CommandPalette (organisms)

Dialog-based command list with search filtering and keyboard-shortcut hints.

Import: `import { CommandPalette } from '@elirobinson/react/components/organisms/CommandPalette';`
Styles: @elirobinson/react/styles/organisms/CommandPalette.css (included in styles.css)

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| commands | `CommandPaletteCommand[]` | yes | — | — |
| onOpenChange | `(open: boolean) => void` | yes | — | — |
| open | `boolean` | yes | — | — |
| className | `string` | no | — | — |

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Reach for `CommandPalette` when there are enough actions or destinations that a keyboard-first
search beats hunting through menus — bound to a shortcut like `⌘K`, it's there for the users
who'd rather never touch the mouse. If you only have three or four actions, a `DropdownMenu`
is less machinery for the same result.

It's built on `Dialog`, so opening it already blocks the rest of the page. It's not the right
container for something that should stay visible alongside what the reader is browsing — that's
`Popover`'s job.

#### Binding a keyboard shortcut

The component only renders the palette — it doesn't own a global shortcut. Wire your own
document-level listener to open it, same as most real command palettes.

#### Props

#### Accessibility

- Renders as a genuine modal `<dialog>` via `Dialog`/`DialogContent` — not a positioned `<div>`
  imitating one. A `DialogTitle` ("Command palette") is always rendered, wiring up the dialog's
  accessible name through `aria-labelledby`.
- On open, focus moves to the search input automatically. It's the one place in this component
  where focus is managed explicitly, rather than left to the browser.
- Uses the same `aria-activedescendant` pattern as `Combobox` (the two share a hook): DOM focus
  stays on the search input at all times, and the highlighted command is conveyed purely by id
  reference via `aria-activedescendant`.
- **Keyboard:** `ArrowDown`/`ArrowUp` move the highlight by one command, clamped at both ends
  (no wraparound). `Enter` runs the currently highlighted command — not just the first — and
  closes the palette. `Escape` closes it without running anything.
- Every re-open resets the search query and the highlighted command back to the top; nothing is
  sticky across opens.
- Filtering narrows the list live as you type; no matches renders a plain "No matching
  commands" row rather than an empty list.
- Keyboard-shortcut hints (`shortcut`) render as real `<kbd>` elements next to each command.
  They're a visual hint only — the component doesn't bind the shortcut itself.

Do:
- Wire your own document-level keydown listener (e.g. ⌘K) to open it.
- Give every command a stable, unique id and a working onSelect.
- Keep commands limited to what’s actually valid right now — it filters on every keystroke.
- Show the real shortcut as shortcut hints, and also bind it for real elsewhere.

Don't:
- Nest another modal inside the palette — it’s already a native <dialog> with showModal(); stacking another on top fights the browser’s own modal handling.
- Rely on the shortcut hints to actually trigger the command — they’re display-only <kbd> tags.
- Pass a huge, unmemoized commands array on every render — it’s re-filtered on every keystroke.
- Use it as your only navigation — it’s a keyboard-first accelerator, not a replacement for a visible nav.

#### Related

Machine-readable record: /r/command-palette.json

### DatePicker (organisms)

Popover date grid using the ARIA grid pattern.

Import: `import { DatePicker } from '@elirobinson/react/components/organisms/DatePicker';`
Styles: @elirobinson/react/styles/organisms/DatePicker.css (included in styles.css)

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| label | `string` | yes | — | Accessible label for the trigger input (also its accessible name). |
| onValueChange | `(date: Date) => void` | yes | — | — |
| className | `string` | no | — | — |
| defaultOpen | `boolean` | no | false | Renders with the calendar already open. Uncontrolled, like the same prop
on Popover, DropdownMenu, Dialog and Sheet: it seeds the initial state and
then stops mattering, so the picker still opens and closes on its own.
There is no controlled `open` counterpart — after the first render the
picker owns its own open state. |
| value | `Date` | no | — | — |

Constraints: no-barrel-imports, forward-ref, touch-target-dense, hit-area-no-overlap (see System constraints)

#### When to use it

Use `DatePicker` when someone is choosing a single specific day — a season start date, a
session, a deadline — and seeing the calendar grid actually helps (today, the weekday, how far
out it is). For a date range, or heavy typed-date entry like a birthdate years in the past, a
plain text input with format validation is often faster: this picker has no keyboard grid
navigation and no month/year jump, so getting to a far-off date means clicking "Next month"
repeatedly.

#### Starting empty

`value` is optional — leave it `undefined` for a field with nothing selected yet. There's no
`defaultValue`: the displayed value always comes straight from the `value` prop, so
`onValueChange` has to actually update your state for a click to visibly select a day.

#### Starting open

`defaultOpen` renders the calendar already open. It is uncontrolled — it seeds the initial
state and then stops mattering, so the field still toggles on click and still closes on
selection or an outside click. There is no controlled `open` prop to pair it with.

Reach for it when the calendar is the point of the step rather than one field among many — a
booking flow whose only question is "which day?" — and when a screenshot or a design review
needs to show the grid rather than the closed field. The popover is positioned absolutely, so
it reserves no space: give the surrounding layout the height the open calendar needs, or it
will paint over what follows.

One caveat if you prerender: today's date is read when the component renders, so a statically
generated page bakes in whichever day the build ran and keeps showing it until the first
client re-render. On a server-rendered open calendar, either mount it on the client or pick a
month the marker cannot land in.

#### Props

#### Accessibility

- The calendar uses the WAI-ARIA grid pattern: `role="grid"` (labeled with the visible month
  and year), a leading `role="row"` of seven `role="columnheader"` weekday labels, then one
  `role="row"` per week with `role="gridcell"` per day. Every week row always has exactly 7
  gridcells — leading/trailing blanks before the 1st and after the last day are real cells
  with `aria-disabled="true"` (not `aria-hidden`), specifically so the row stays structurally
  valid rather than short a cell.
- The weekday labels (`Sun`–`Sat`) are what let a screen reader announce which column a day
  falls in, and what lets a sighted reader tell the columns apart without inferring it from
  the run of blanks before the 1st. They are formatted from `Date` with an explicit `en-US`
  locale, the same one the month label and the field's displayed value use.
- The selected day's gridcell carries `aria-selected="true"` (and only that one); today's date
  gets `aria-current="date"` on its button. These are independent — "selected" and "today" can
  be different days, or the same one.
- **Keyboard support is partial**, and it's worth being precise about the gap: every day is a
  real, individually focusable `<button>`, so `Tab`/`Shift+Tab` walk through the visible
  month's days in order and `Enter`/`Space` activate the focused one — but there's no roving
  tabindex and no `ArrowLeft`/`ArrowRight`/`ArrowUp`/`ArrowDown` grid navigation, and no
  `Escape` to close the calendar. Plan keyboard testing around Tab and Enter/Space, not the
  full ARIA grid keyboard convention.
- Clicking the (read-only) text input toggles the calendar open or closed. Clicking a day calls
  `onValueChange` and closes the calendar. Clicking anywhere outside the control closes it too.
- "Previous month"/"Next month" have explicit `aria-label`s and correctly roll over year
  boundaries in both directions.
- The popover is positioned with plain CSS directly below the input — there's no
  viewport-collision handling, so give it room to render below the field.

Do:
- Store the value from onValueChange in state you control — the field is fully controlled, with no internal fallback.
- Give it room below the input — the popover always opens downward with no flip-to-fit logic.
- Use it for a single, nearby date where seeing the calendar actually helps.
- Pair it with a real label — it becomes the trigger input’s accessible name.

Don't:
- Expect Escape to close the calendar, or arrow keys to move between days — neither is implemented.
- Use it for a date far from today (a birth year, say) — there’s no month/year jump, only Prev/Next.
- Type directly into the field — it’s read-only by design; selection happens through the grid.
- Reach for it when you need a date range — this picker is single-date only.

#### Related

Machine-readable record: /r/date-picker.json

### Dialog (organisms)

Modal dialog built on the native dialog element.

Import: `import { Dialog, DialogHeader, DialogTitle, DialogDescription, DialogFooter, DialogTrigger, DialogContent, DialogClose } from '@elirobinson/react/components/organisms/Dialog';`
Styles: @elirobinson/react/styles/organisms/Dialog.css (included in styles.css)

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| defaultOpen | `boolean` | no | false | — |
| onOpenChange | `((open: boolean) => void)` | no | — | — |
| open | `boolean` | no | — | — |

#### DialogHeader

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

#### DialogTitle

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLHeadingElement>` props.

#### DialogDescription

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLParagraphElement>` props.

#### DialogFooter

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

#### DialogTrigger

(no props of its own beyond inherited HTML attributes)
Also accepts all `ButtonHTMLAttributes<HTMLButtonElement>` props.

#### DialogContent

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLDialogElement>` props.

#### DialogClose

(no props of its own beyond inherited HTML attributes)
Also accepts all `ButtonHTMLAttributes<HTMLButtonElement>` props.

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `Dialog` when something needs to fully interrupt the page — confirming a destructive
action, collecting the minimum info needed to continue, a message that has to be dismissed
before anything else happens. It's built on the real `<dialog>` element, so the modality (focus
trap, Escape-to-close, blocking the rest of the page) comes from the browser, not from custom
JavaScript.

For content that's useful but skippable — a hint, a filter panel, extra detail on click — use
`Popover` instead. Nothing about it blocks the page.

#### Controlled

Open a dialog from outside without rendering a `DialogTrigger` at all — pass `open` and
`onOpenChange` and drive it from wherever the action originates, such as a row action or a
destructive-confirmation flow.

#### Props

#### Accessibility

- Built on the native `<dialog>` element via `showModal()`/`close()` — not a custom-built
  modal. The browser supplies the modal semantics, the focus trap, and the top-layer stacking.
- `aria-labelledby` and `aria-describedby` point at fixed ids generated once per `Dialog`,
  wired to `DialogTitle` and `DialogDescription` respectively. Always render a `DialogTitle` —
  it's the dialog's accessible name. `DialogDescription` is optional, but the `aria-describedby`
  reference exists whether or not you render one.
- **Keyboard:** `Escape` closes the dialog through the native `<dialog>` cancel/close event —
  genuine browser behavior, not a custom keydown handler. `Tab`/`Shift+Tab` are trapped inside
  the dialog automatically by the browser's own modal focus management while it's open.
- Initial focus is also native `showModal()` behavior — the browser focuses the first
  focusable element inside the dialog (or the dialog itself if there isn't one) the moment it
  opens. Nothing in this component manages focus manually.
- Clicking the backdrop closes the dialog: a click handler compares `event.target` against the
  `<dialog>` element itself (not `.ds-dialog__inner`), since a native `<dialog>`'s backdrop
  region is the element's own box outside its content.
- `DialogTrigger` and `DialogClose` are both plain `<button type="button">`s with no extra
  keyboard behavior beyond the native button contract (`Enter`/`Space` activate).

Do:
- Always render a DialogTitle — its id is hardcoded into aria-labelledby.
- s native modality instead of layering your own overlay div on top of it.",
    
- ,
    

Don't:
- Render DialogContent outside a Dialog provider — it throws.
- Skip DialogDescription when the dialog needs supporting context — aria-describedby points at a fixed id whether you render one or not.
- Nest a second <dialog> inside — CommandPalette is the example of doing this right: one native modal at a time.
- Use Dialog for lightweight, non-blocking content — reach for Popover when nothing needs to interrupt the page.

#### Related

Machine-readable record: /r/dialog.json

### DropdownMenu (organisms)

Keyboard-navigable action menu anchored to a trigger.

Import: `import { DropdownMenu, DropdownMenuContent, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger, DropdownMenuItem } from '@elirobinson/react/components/organisms/DropdownMenu';`
Styles: @elirobinson/react/styles/organisms/DropdownMenu.css (included in styles.css)

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| defaultOpen | `boolean` | no | false | — |
| onOpenChange | `((open: boolean) => void)` | no | — | — |
| open | `boolean` | no | — | — |

#### DropdownMenuContent

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| align | `"start" \| "center" \| "end"` | no | — | `'start'` lines the panel's left edge up with the trigger's and gives it
the trigger's width as a minimum — the menu/listbox shape. `'end'` is the
same shape mirrored: the panel's *right* edge is pinned to the trigger's,
which is what a trigger near the right edge of the viewport needs.
`'center'` centres it on the trigger and leaves the width to the content,
which is what a tooltip wants. Default `'start'`. |
| side | `"top" \| "bottom"` | no | — | Which edge of the trigger the panel hangs from. Default `'bottom'`. |
Also accepts all `HTMLAttributes<HTMLDivElement> & Pick<AnchoredOverlayContentProps, 'side' | 'align'>` props.

#### DropdownMenuLabel

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| inset | `boolean` | no | — | — |
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

#### DropdownMenuSeparator

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

#### DropdownMenuTrigger

(no props of its own beyond inherited HTML attributes)
Also accepts all `ButtonHTMLAttributes<HTMLButtonElement>` props.

#### DropdownMenuItem

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| closeOnSelect | `boolean` | no | — | Whether choosing this item closes the menu. Defaults to `true` for an
ordinary item, and to `false` when `type="submit"` — closing unmounts the
portal during the click, which cancels the form submission the click was
for. Set it explicitly to override either default. |
| inset | `boolean` | no | — | — |
Also accepts all `ButtonHTMLAttributes<HTMLButtonElement>` props.

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `DropdownMenu` for a set of actions anchored to a trigger — row actions in a table, a "…"
overflow menu, a view switcher. It's action-oriented: items are `role="menuitem"` and run a
handler, they don't navigate. If every item should actually change the URL, use `NavigationMenu`
or plain links instead — a `role="menuitem"` on a link tells assistive tech the wrong thing
about what activating it does.

#### Aligning items with inset

`inset` on `DropdownMenuLabel`/`DropdownMenuItem` adds left padding so plain text lines up with
sibling items that have a leading marker — a checkmark on the current selection, in this case.

#### Submitting a form from an item

An item that submits a form — a sign-out button running a server action, say — must not close
the menu as part of the click that submits it. Closing is a discrete state update React flushes
synchronously, still inside the click dispatch: the portal unmounts before the browser reaches
the click's default action, React has already suppressed the browser's own submission so that it
can run the form's `action` itself, and no live fiber is left to run it against. The result is an
item that looks like it does nothing at all.

So `DropdownMenuItem` reads its own `type`: an item with `type="submit"` does not close on
select, and everything else still does.

```tsx
<DropdownMenuContent>
  <form action={signOutAction}>
    <DropdownMenuItem type="submit">Sign out</DropdownMenuItem>
  </form>
</DropdownMenuContent>
```

The menu then stays open until the action navigates away, or until you close it yourself once
the action resolves. `closeOnSelect` overrides the default in either direction —
`closeOnSelect={false}` keeps an ordinary item's menu open (a toggle the user may want to flip
more than once), and `closeOnSelect` on a submit item closes it anyway, which is only correct
when the submission does not need the form to survive the click.

#### Props

#### Accessibility

- `DropdownMenuContent` renders `role="menu"`, portaled to `document.body`; each
  `DropdownMenuItem` is `role="menuitem"`. The trigger carries `aria-haspopup="menu"`,
  `aria-expanded`, and `aria-controls`.
- `Escape` closes the menu from anywhere on the page — a document-level listener, active only
  while the menu is open. Clicking anywhere outside the trigger or the menu content also closes
  it.
- Opening the menu does **not** move focus into it — clicking or activating the trigger leaves
  DOM focus on the trigger button itself. Arrow-key/Home/End navigation only takes over once a
  menu item already has focus (for example, after tabbing to one).
- **Keyboard, once a menu item has focus:** `ArrowDown`/`ArrowUp` move focus between items and
  wrap around at both ends (`ArrowDown` past the last item goes to the first, and vice versa —
  unlike Combobox/CommandPalette's clamped, non-wrapping model, since this menu moves real DOM
  focus rather than tracking an `aria-activedescendant`). `Home`/`End` jump to the first/last
  item. `Tab` closes the menu and lets focus continue to whatever's next in the page, rather
  than trapping it.
- `DropdownMenuSeparator` renders `role="separator"` with `aria-orientation="horizontal"`.
- Content is positioned with fixed coordinates computed from the trigger's bounding rect,
  recalculated on scroll and resize while the menu is open, so the menu follows its trigger.
- A menu that doesn't fit below its trigger flips above it, and one that overruns the right
  edge pins its right edge to the trigger's instead — the `bottom`/`start` you get by default
  are preferences, not guarantees. Each axis flips at most once per open and never flips back,
  so a menu can't oscillate while you scroll. `side` and `align` on `DropdownMenuContent` set
  the preferred side.
- A menu that fits on neither side is shifted rather than shrunk: it keeps its width and
  slides along the axis until it is back inside the viewport, so its items never reflow into
  whatever space is left beside a pinned edge. It stops being edge-aligned with its trigger,
  which is the price. The width it keeps has a floor — `.ds-dropdown__content` sets
  `--anchored-min-width: 180px`, and the positioner keeps the larger of that and the trigger's
  width. A menu taller than the viewport is the one case no offset rescues: it takes a
  `max-height` of the viewport and scrolls its own items.
  See [`useAnchoredPosition`](/components/hooks#useanchoredposition).

Do:
- Group related items under a DropdownMenuLabel and separate groups with DropdownMenuSeparator.
- Keep item labels as short verb phrases — the menu is for actions, not longform text.
- Give the trigger real content (icon and/or label) — aria-haspopup and aria-expanded are already wired.
- Test with Tab specifically — since initial focus stays on the trigger, keyboard flows depend on Tab order reaching an item.

Don't:
- Put a link where an action belongs — items are buttons that run a handler, not anchors that navigate.
- Rely on hover to open it — activation is click/keyboard only, with no hover-intent timer.
- Put a destructive action next to routine ones without a separator.
- Assume the first item gets focus automatically on open — it doesn’t.

#### Related

Machine-readable record: /r/dropdown-menu.json

### NavigationMenu (organisms)

Always-rendered nested link list with current-page marking.

Import: `import { NavigationMenu } from '@elirobinson/react/components/organisms/NavigationMenu';`
Styles: @elirobinson/react/styles/organisms/NavigationMenu.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLElement>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| items | `NavigationMenuItem[]` | yes | — | — |
| currentPath | `string` | no | — | — |

Constraints: no-barrel-imports, forward-ref, touch-target-primary, hit-area-no-overlap (see System constraints)

#### When to use it

Use `NavigationMenu` for a site's real navigation — every item renders as a genuine `<a>`, so
it works with middle-click, cmd-click, and JavaScript disabled. It supports one level of nested
links (a section with sub-pages), but the nested items are always rendered inline, not hidden
behind a hover or click. If you need a menu that opens and closes on demand, that's
`DropdownMenu`, not this.

#### Without a current page

`currentPath` is optional. When it's omitted, or when it matches nothing in `items`, no item is
marked current — none gets `aria-current`.

#### Section labels

`href` is optional. Omit it when a group's title is a heading rather than a page —
"Foundations" above a list of foundation pages — and the item renders as an inert
`<span>` instead of an `<a>`: not focusable, not a navigation target, never marked
current. The label also names its nested list through `aria-labelledby`, so a screen
reader announces "Foundations, list, 7 items" on descending into the group.

Don't reach for the group's first child href to satisfy the type. That makes the header
match `currentPath` whenever the child is open, so the header renders as the current page
alongside it and a second `aria-current="page"` appears in the tree.

#### Props

#### Accessibility

- Renders a `<nav>` landmark wrapping a plain, always-rendered nested `<ul>`/`<li>`/`<a>` tree
  — not a disclosure widget. Nothing is collapsed, hidden, or toggled.
- Every item with an `href` is a real `<a href>`, so `Tab`/`Shift+Tab` already walk the entire
  tree, including nested items, in document order — zero custom key handling. An item without
  an `href` is a `<span>` label, so it's skipped by `Tab` — there's nothing there to activate.
- The item matching `currentPath` gets `aria-current="page"`; every other item has the
  attribute omitted entirely (not set to `"false"`). Nothing is marked current if
  `currentPath` matches nothing.
- Deliberately has **no** `Escape` handling and **no** `aria-expanded`/`aria-controls` anywhere
  — there's no toggleable submenu here to escape out of or expand. That's an explicit design
  choice, not an oversight: if you need a collapsible or flyout submenu, this isn't that
  component.
- Nested items render inside their parent `<li>` as their own `<ul>`, so a screen reader
  announces "list, N items" once at the top level and again on descending into a nested group,
  rather than one flattened list.
- A nested list under a hrefless label is named after that label via `aria-labelledby`, so the
  group announces as "Foundations, list, N items". A nested list under a link parent stays
  unnamed — the link is a destination, not a title for the list beneath it.

Do:
- Pass real, working hrefs — this is a navigation list, not a menu of actions.
- Omit href on a group title that names its children but isn’t a page of its own.
- Keep currentPath in sync with the router so aria-current always matches what’s on screen.
- Nest one level deep in practice — the recursive items field supports more, but three-plus levels are hard to scan visually.

Don't:
- Use it for a flyout or disclosure submenu that opens on click or hover — reach for DropdownMenu for that toggle behavior.
- Attach onClick handlers that prevent navigation — every link should be genuinely middle-click-able.
- Give a section header its first child’s href — the header then renders as current whenever that child is open.
- Expect aria-expanded or collapse behavior — nested items are always rendered and always in the tab order.

#### Related

Machine-readable record: /r/navigation-menu.json

### Popover (organisms)

Anchored floating panel with outside-click and Escape dismissal.

Import: `import { Popover, PopoverContent, PopoverTrigger } from '@elirobinson/react/components/organisms/Popover';`
Styles: @elirobinson/react/styles/organisms/Popover.css (included in styles.css)

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| defaultOpen | `boolean` | no | false | — |
| onOpenChange | `((open: boolean) => void)` | no | — | — |
| open | `boolean` | no | — | — |

#### PopoverContent

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| align | `"start" \| "center" \| "end"` | no | — | `'start'` lines the panel's left edge up with the trigger's and gives it
the trigger's width as a minimum — the menu/listbox shape. `'end'` is the
same shape mirrored: the panel's *right* edge is pinned to the trigger's,
which is what a trigger near the right edge of the viewport needs.
`'center'` centres it on the trigger and leaves the width to the content,
which is what a tooltip wants. Default `'start'`. |
| side | `"top" \| "bottom"` | no | — | Which edge of the trigger the panel hangs from. Default `'bottom'`. |
Also accepts all `HTMLAttributes<HTMLDivElement> & Pick<AnchoredOverlayContentProps, 'side' | 'align'>` props.

#### PopoverTrigger

(no props of its own beyond inherited HTML attributes)
Also accepts all `ButtonHTMLAttributes<HTMLButtonElement>` props.

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `Popover` for content that's genuinely optional to see — extra detail, a small set of
filters, a short form — anchored to whatever triggered it. Nothing about it blocks the page: no
focus trap, no modal backdrop, background content stays fully interactive. If dismissing it
needs to be unmissable, or it needs to hold focus, that's a `Dialog`, not a `Popover`.

#### Controlled, with a manual dismiss

There's no `PopoverClose` — unlike `Dialog`, closing programmatically means calling
`onOpenChange(false)` yourself from inside the content.

#### Props

#### Accessibility

- `PopoverContent` renders `role="dialog"`, portaled to `document.body`. This is a
  **non-modal** dialog role: nothing calls `showModal()`, there's no focus trap, and the rest
  of the page stays interactive — the opposite of `Dialog`.
- `Escape` closes it from anywhere (a document-level listener, the same `useEscapeKey` hook
  `DropdownMenu` uses), and clicking outside the trigger or content closes it too.
- No initial-focus management: opening the popover doesn't move DOM focus into
  `PopoverContent`. Focus stays wherever it was — typically the trigger, since activating it
  doesn't blur it. If your content includes interactive elements a fully keyboard-driven flow
  depends on, move focus there yourself, or rely on the user tabbing in.
- No built-in close affordance: there's no `PopoverClose` subcomponent. Closing it from inside
  the content means calling `onOpenChange(false)` yourself.
- Content is positioned with fixed coordinates computed from the trigger's bounding rect,
  the same anchoring mechanism `DropdownMenu` uses — recalculated on scroll and resize while
  the popover is open, so the content follows its trigger.
- Content that doesn't fit below its trigger flips above it, and content that overruns the
  right edge pins its right edge to the trigger's instead — the `side` and `align` you pass to
  `PopoverContent` are preferences, not guarantees. Each axis flips at most once per open and
  never flips back, so it can't oscillate while you scroll.
- Content that fits on neither side is shifted rather than shrunk: it keeps its width and
  slides along the axis until it is back inside the viewport, so it never reflows into whatever
  space is left beside a pinned edge. It stops being edge-aligned with its trigger, and may
  overlap it, but it doesn't narrow. Content taller than the viewport takes a `max-height` of
  the viewport and scrolls instead, since no offset makes that fit. Unlike `DropdownMenu`,
  `PopoverContent` sets no `min-width` of its own, so the trigger's width is the only floor —
  give your content `--anchored-min-width` if it needs a wider one.
  See [`useAnchoredPosition`](/components/hooks#useanchoredposition).

Do:
- Use Popover for supplementary, non-blocking content — a hint, a filter panel, a short form.
- Wire your own dismiss control inside PopoverContent when the content needs an explicit close action.
- Keep content lightweight — nothing here traps focus, so a long or complex form is a sign you actually want Dialog.

Don't:
- Use it for anything that must block interaction with the rest of the page — reach for Dialog, an actual native modal.
- t; test keyboard flows accordingly.",
    

#### Related

Machine-readable record: /r/popover.json

### Select (organisms)

Native select with label, hint, and error wiring.

Import: `import { Select } from '@elirobinson/react/components/organisms/Select';`
Styles: @elirobinson/react/styles/atoms/field.css (included in styles.css)
Also accepts all `SelectHTMLAttributes<HTMLSelectElement>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| label | `string` | yes | — | — |
| error | `string` | no | — | — |
| hint | `string` | no | — | — |

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `Select` when the options are plain text and few enough to scan — roughly under twenty.
It renders a native `<select>`, so you get the platform's picker, keyboard support, and
typeahead for free, on every device, without a line of extra code.

Reach for `Combobox` instead once the list needs search-as-you-type, or an option needs more
than a label — an icon, a description, a secondary line. Reach for `RadioGroup` when there
are only two to four choices and showing them all at once beats hiding them behind a click.

#### Hint, error, and disabled

`hint` and `error` share one line under the field — passing both shows only the error,
with `aria-invalid` set on the `<select>` and the message announced immediately.

#### Props

#### Accessibility

- Renders a native `<select>` wired to a real `<label>` via `htmlFor`/`id` — no ARIA
  substitute needed for the label relationship.
- `error` sets `aria-invalid="true"` on the `<select>` and renders with `role="alert"`, so
  assistive tech announces it as soon as it appears. It also takes over the description
  slot from `hint` — the two never show at once.
- `hint` and `error` are wired through `aria-describedby`, merged with any
  `aria-describedby` you pass in yourself rather than overwriting it.
- **Keyboard:** entirely native. `Tab` focuses the control, `Enter`/`Space`/`Down Arrow`
  open the option list, arrow keys move through it, and typing jumps to a matching option.
  None of this is reimplemented — it's the browser's own `<select>` behavior, which is why
  it also gets the OS-native picker UI on mobile for free.
- The ref forwards to the underlying `<select>` element.

Do:
- Pass a real label string every time — it is required, and renders as a genuine <label>.
- Use hint for supporting context and error for validation — error automatically replaces the hint so they never stack.
- Trust the native option list for anything under about twenty items.
- Read the value off the native change event, the same as any uncontrolled <select>.

Don't:
- Reach for Select when options need icons, descriptions, or search — use Combobox instead.
- Build a custom-styled dropdown on top of a hidden <select> — the native picker is the accessible one.
- Rely on placeholder-only labelling; an empty or missing label leaves the field unannounced.
- Show a validation error without also setting the field to error — the message and the state should move together.

#### Related

Machine-readable record: /r/select.json

### Sheet (organisms)

Edge drawer built on the native dialog element.

Import: `import { Sheet, SheetHeader, SheetTitle, SheetDescription, SheetFooter, SheetTrigger, SheetContent, SheetClose } from '@elirobinson/react/components/organisms/Sheet';`
Styles: @elirobinson/react/styles/organisms/Sheet.css (included in styles.css)

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| defaultOpen | `boolean` | no | false | — |
| onOpenChange | `((open: boolean) => void)` | no | — | — |
| open | `boolean` | no | — | — |

#### SheetHeader

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

#### SheetTitle

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLHeadingElement>` props.

#### SheetDescription

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLParagraphElement>` props.

#### SheetFooter

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

#### SheetTrigger

(no props of its own beyond inherited HTML attributes)
Also accepts all `ButtonHTMLAttributes<HTMLButtonElement>` props.

#### SheetContent

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| side | `"left" \| "right" \| "top" \| "bottom"` | no | right | — |
Also accepts all `HTMLAttributes<HTMLDialogElement>` props.

#### SheetClose

(no props of its own beyond inherited HTML attributes)
Also accepts all `ButtonHTMLAttributes<HTMLButtonElement>` props.

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `Sheet` for a task that needs more room than a `Popover` but shouldn't take over the
whole screen — filters, a detail panel, a settings drawer. It's built on the native
`<dialog>` element, so the focus trap, the backdrop, and Escape-to-close all come from the
browser instead of a hand-rolled implementation.

Reach for `Dialog` instead when the content itself is the task and centering it is the
point — a confirmation, a form that should block the rest of the page. A `Sheet` stays
anchored to an edge, which reads as "secondary to what's behind it" even while it's open.

#### Sides

`SheetContent` takes a `side` — `left`, `right`, `top`, or `bottom`. `right` is the default,
shown above.

#### Props

#### Accessibility

- `SheetContent` calls the native `showModal()` when it opens, so it inherits the browser's
  own focus trap, `::backdrop`, and background inerting — none of that is reimplemented.
- **Keyboard:** `Escape` closes the sheet. That's native `<dialog>` behavior (it fires a
  `cancel` then `close` event), which `Sheet` listens for and turns into `onOpenChange(false)`
  — no keydown handler needed.
- Clicking the backdrop — the `<dialog>` element itself, outside the inner content — also
  closes the sheet.
- `SheetTitle` and `SheetDescription` supply the ids `SheetContent` points `aria-labelledby`
  and `aria-describedby` at. Always render a `SheetTitle`, even visually hidden — the
  reference is unconditional, so a sheet without one is a dialog with no accessible name.
- `SheetClose` renders a real `<button type="button">` with a "Close" fallback label when
  you don't pass children.

Do:
- Render a SheetTitle inside SheetHeader every time, even if you hide it visually.
- Drive visibility with the open/onOpenChange controlled pair.
- Pick side to match the content — top or bottom for something short and wide, left or right for anything list-like.
- Pair SheetClose with an explicit confirm action in SheetFooter so Cancel and the primary action are both one click away.

Don't:
- Mix defaultOpen with the controlled open prop — pick uncontrolled (defaultOpen) or controlled (open/onOpenChange), not both.
- s content — close the first before opening another.",
    
- ,
    

#### Related

Machine-readable record: /r/sheet.json

### Table (organisms)

Paginated data table backed by `@tanstack/react-table`'s row models.

For large row counts, use `VirtualTable` instead — windowing and pagination
are two strategies for the same problem, so neither component combines them.

Import: `import { Table } from '@elirobinson/react/components/organisms/Table';`
Styles: @elirobinson/react/styles/organisms/Table.css (included in styles.css)
Also accepts all `TableElementProps & TableBaseProps<T>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| columns | `ColumnDef<T, unknown>[]` | yes | — | — |
| data | `T[]` | yes | — | — |
| emptyMessage | `string` | no | — | Title shown by the EmptyState row when there are no rows to display. |
| filterable | `boolean` | no | — | Shows a built-in global filter input above the table, wired to TanStack's filtered row model. |
| filterPlaceholder | `string` | no | — | Accessible label / placeholder for the built-in filter input. |
| pageSize | `number` | no | — | Rows per page. |

Constraints: no-barrel-imports, forward-ref (see System constraints)

Columns sort by clicking their header — that's on by default for every column with an
`accessorKey`, no extra prop required. Pagination appears automatically once the row count
passes `pageSize`.

#### When to use it

Use `Table` when the data fits in pages — a results list, an order history, anything a
reader might reasonably want to jump to "page 3 of 6" on. It's built on
`@tanstack/react-table`'s real row models, so sorting, filtering, and pagination all read
from the same computed row set instead of three separate, driftable pieces of state.

For a few hundred rows or more where paging feels like busywork, reach for `VirtualTable`
instead. Windowing and pagination solve the same problem — too many rows to put in the DOM
at once — so `Table` deliberately doesn't try to do both.

#### Filtering

`filterable` adds a global text filter above the table, wired to TanStack's
`getFilteredRowModel()`. `filterPlaceholder` becomes both the placeholder text and the
input's accessible name.

#### Empty state

`emptyMessage` renders through `EmptyState` in place of the row set — this fires both for
genuinely empty `data` and for a filter that matches nothing.

#### Props

#### Accessibility

- Sortable column headers render as a native `<button>` inside the `<th>`, and the `<th>`
  itself carries `aria-sort` (`ascending` / `descending` / `none`) reflecting the live sort
  state.
- The filter input is `type="search"` with `aria-label` set from `filterPlaceholder`.
- The pagination footer — only present once there's more than one page — is a `nav`
  landmark labeled "Pagination", with `Previous page` / `Next page` buttons that disable
  themselves at the edges and `aria-current="page"` on the active page number.
- **Keyboard:** everything is a real `<button>` or `<input>`, so `Tab` reaches sort
  headers, the filter field, and pagination controls in document order, and `Enter`/`Space`
  activates a focused one. None of it is reimplemented.
- The empty state renders as a single cell with `colSpan` across every visible column,
  rather than a row of empty cells — a screen reader hits one coherent message, not a row
  it has to parse as data.

Do:
- Give every column a stable accessorKey so sorting and cell rendering read from the exact same field.
- Set filterPlaceholder to something specific ("Filter orders") — it doubles as the input's accessible name.
- Write an emptyMessage for the actual context ("No orders yet") instead of leaving the generic default.

Don't:
- Reach for Table once a dataset runs past a few hundred rows with no natural stopping point — use VirtualTable instead.
- Assume data.length tells you whether the table is empty — after filtering, the visible row model can be empty while data still has rows.
- s job.",
    

#### Related

Machine-readable record: /r/table.json

### Tabs (organisms)

Tab set with roving focus and an ink underline active state.

Import: `import { Tabs, TabsList, TabsTrigger, TabsContent } from '@elirobinson/react/components/organisms/Tabs';`
Styles: @elirobinson/react/styles/organisms/Tabs.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| defaultValue | `string \| number \| readonly string[]` | no | — | — |
| onValueChange | `((value: string) => void)` | no | — | — |
| value | `string` | no | — | — |

#### TabsList

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| defaultValue | `string \| number \| readonly string[]` | no | — | — |
Also accepts all `Omit<HTMLAttributes<HTMLDivElement>, 'role'>` props.

#### TabsTrigger

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| value | `string` | yes | — | — |
| defaultValue | `string \| number \| readonly string[]` | no | — | — |
| onClick | `MouseEventHandler<HTMLButtonElement>` | no | — | — |
Also accepts all `Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'value' | 'id' | 'role' | 'onClick' | 'aria-selected' | 'aria-controls' | 'tabIndex'>` props.

#### TabsContent

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| value | `string` | yes | — | — |
| defaultValue | `string \| number \| readonly string[]` | no | — | — |
Also accepts all `Omit<HTMLAttributes<HTMLDivElement>, 'id' | 'role' | 'aria-labelledby'>` props.

Constraints: no-barrel-imports (see System constraints)

#### When to use it

Use `Tabs` to switch between views that share the same context — different cuts of one
dataset, sections of one guide, steps in a self-contained flow. Inactive panels don't just
hide: `TabsContent` returns `null` when it isn't the active tab, so anything with local
state inside it unmounts and resets when you navigate away and back.

Reach for `Accordion` instead when the sections aren't mutually exclusive — a reader might
want two open at once. Reach for a real page or route once the content is substantial
enough that someone would want to bookmark or share a link straight to one section.

#### Controlled

Pass `value` and `onValueChange` when something outside the tablist needs to read or drive
the active tab — here, external Back/Next buttons step through the same tabs.
`defaultValue` is still required by the type even in controlled mode; pass the same initial
value you gave your own state.

#### Disabled tab

A disabled `TabsTrigger` can't take focus, so arrow-key navigation skips over it — and if
it happens to be the active tab, the tablist's single tab stop moves to the first
focusable trigger instead.

#### Props

#### Accessibility

Implements the WAI-ARIA tabs pattern: `role="tablist"` on `TabsList`, `role="tab"` on each
`TabsTrigger` (with `aria-selected` and `aria-controls`), `role="tabpanel"` on
`TabsContent` (with `aria-labelledby` pointing back at its tab).

- **Roving tabindex:** exactly one trigger is in the page's tab order at a time — normally
  the active one — everything else carries `tabIndex={-1}`.
- **Keyboard:** `Tab` moves focus into and out of the tablist. `ArrowRight`/`ArrowDown` move
  to the next trigger, `ArrowLeft`/`ArrowUp` to the previous, both wrapping past the ends.
  `Home` jumps to the first trigger, `End` to the last. Arrow keys only move focus — they do
  not select. `Enter` and `Space` activate whichever trigger currently has focus.
- Disabled triggers are skipped entirely by arrow navigation and can never hold the tab
  stop; if the active trigger is disabled, ownership falls back to the first focusable one.
- Two independent `Tabs` instances on the same page keep separate tablists — arrow
  navigation never crosses from one into the other.

Do:
- Match TabsTrigger and TabsContent value props exactly — that pairing wires aria-controls and aria-labelledby together.
- Use value and onValueChange when something outside the tablist needs to read or drive the active tab.
- Keep trigger labels to a word or two — TabsList wraps once labels get long.
- Give a disabled tab a reason in its own label ("Basketball (sold out)") since arrow navigation will silently skip past it.

Don't:
- s preventDefault() to block the tab switch — TabsTrigger always calls setActiveTab after your handler runs.",
    
- ,
    
- ,
    

#### Related

Machine-readable record: /r/tabs.json

### Toast (organisms)

Aria-live notification system — Toaster region plus a useToast dispatcher.

Import: `import { Toast, Toaster, ToastTitle, ToastDescription, ToastAction, useToast } from '@elirobinson/react/components/organisms/Toast';`
Styles: @elirobinson/react/styles/organisms/Toast.css (included in styles.css)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| onDismiss | `(() => void)` | no | — | — |
| variant | `"default" \| "success" \| "warning" \| "danger" \| "info"` | no | default | — |

#### Toaster

(no props of its own beyond inherited HTML attributes)

#### ToastTitle

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

#### ToastDescription

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

#### ToastAction

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLButtonElement>` props.

Constraints: no-barrel-imports, forward-ref (see System constraints)

Mount one `Toaster` near the root of your app, then call `useToast()` from anywhere inside
it to dispatch. `Toaster` renders nothing visible on its own — it owns the toast queue and
portals the viewport to the end of `<body>`.

#### When to use it

Use `Toast` to confirm that something the reader just did worked, or didn't — a save, a
send, a payment. It's not for anything the reader needs to act on right now: a toast clears
itself after five seconds by default, so it's the wrong place for an error that blocks the
next step. Put that in the page instead, where it stays until it's fixed.

#### Variants

`variant` covers `default`, `success`, `warning`, `danger`, and `info` — pass it straight
through `toast({ ..., variant })`.

#### Composing a toast with an action

`toast()` only takes `title`, `description`, `variant`, and `duration` — there's no slot
for a custom action button. When you need one (an "Undo", a link to the affected record),
compose `Toast`, `ToastTitle`, `ToastDescription`, and `ToastAction` directly instead of
going through `useToast()`. Composed this way it renders in place, not through the portal,
so it shows up wherever you put it — here, inline in the demo stage.

#### Props

#### Accessibility

- `Toaster`'s viewport carries `aria-live="polite"` and `aria-relevant="additions"`, so a
  screen reader announces each new toast without interrupting whatever the reader is doing.
- Each `Toast` also has `role="status"` — a live region in its own right, harmless
  alongside the viewport's `aria-live`.
- The dismiss button gets a built-in `aria-label="Dismiss notification"` automatically; you
  don't supply one.
- Toasts auto-dismiss after `duration` (5000ms by default). Pass `duration: 0` to keep one
  on screen until the reader, or your code, dismisses it.
- The viewport is portaled to `document.body` and fixed to the bottom-right corner — it
  renders outside wherever in the DOM you called `toast()` from, including outside the demo
  stage above.
- `Toaster` skips its portal on the server and first client render (via the package's
  `useHasMounted` hook), so it server-renders cleanly in Next.js and Remix — no client-only
  boundary needed. Toasts only exist after an interaction, so nothing is lost.
- Nothing moves focus when a toast appears. A reader mid-task is never interrupted; a
  `ToastAction`, when present, is just a normal button already in the page's tab order.

Do:
- Mount exactly one Toaster near the root of the app, and call useToast() from any descendant.
- Keep title short and put detail in description — they render as a heading and a supporting line, not one paragraph.
- Set variant to match what actually happened instead of leaving every toast at the default.
- Pass duration: 0 for a toast that reports something the reader must notice, like a failed payment.

Don't:
- Call useToast() outside a Toaster — it throws on purpose rather than silently doing nothing.
- Use a toast for something the reader has to act on immediately — it disappears on its own by default.
- s data shape has no slot for one; compose Toast directly instead.",
    

#### Related

Machine-readable record: /r/toast.json

### Tooltip (organisms)

Hover- and focus-triggered tooltip anchored to its trigger.

Import: `import { Tooltip, TooltipContent, TooltipTrigger } from '@elirobinson/react/components/organisms/Tooltip';`
Styles: @elirobinson/react/styles/organisms/Tooltip.css (included in styles.css)

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| delayDuration | `number` | no | — | — |

#### TooltipContent

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLDivElement>` props.

#### TooltipTrigger

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLSpanElement>` props.

Constraints: no-barrel-imports, forward-ref (see System constraints)

#### When to use it

Use `Tooltip` for a short, supplementary label — what an icon button does, an abbreviation
spelled out, a truncated value's full text. It's not for anything the reader needs to read
reliably: it only shows on hover or keyboard focus, so it never reaches a touch-only visitor
and it's gone the moment focus moves on.

If the content matters enough that someone should be able to read it without hovering, put
it in the page instead. If it needs to stay open while the reader interacts with it — a
form, a list of actions — use `Popover`.

#### Labeling an icon button

A tooltip is a bonus for sighted mouse and keyboard users — it doesn't replace the
accessible name an icon-only `Button` still needs on its own `aria-label`.

#### Props

#### Accessibility

- `TooltipTrigger` wraps its child in a `<span>` carrying `aria-describedby` pointed at the
  tooltip content's id — wrap a real interactive element (a button, a link) inside it so
  there's something to hover or focus in the first place.
- **Keyboard:** opens on native focus, closes on blur. There's no separate keyboard path to
  keep in sync with hover — focusing the wrapped element opens the tooltip the same way
  hovering it does.
- No `Escape` handling — pressing it does not close the tooltip. Moving focus or the
  pointer away is the only way to dismiss it.
- `TooltipContent` renders through a portal to `document.body` and only mounts while open —
  it isn't hidden with CSS, so there's nothing sitting in the DOM to tab into while closed.
- Position is fixed: centered under the trigger, a few pixels below it. There's no
  side/alignment prop to place it anywhere else.
- A tooltip with no room below its trigger flips above it. It does not flip horizontally:
  centering is symmetric, so there is no opposite edge to pin instead. A tooltip that would
  overrun a side edge is shifted back inside the viewport instead, keeping its width — so it
  stops being centred on its trigger rather than reflowing its text into whatever space is
  left. See [`useAnchoredPosition`](/components/hooks#useanchoredposition).

Do:
- Wrap a genuinely focusable element in TooltipTrigger — a button, a link, an input — so keyboard users can reach it at all.
- Give icon-only buttons their own aria-label even inside a Tooltip — the tooltip supplements it, it does not replace it.
- Keep TooltipContent to a short phrase — it is a label, not a place for instructions someone needs to act on.
- Use it only for information that is genuinely optional — the layout should still make sense if the tooltip never appears.

Don't:
- Put interactive content — a link, a button — inside TooltipContent; it disappears the moment focus or the pointer leaves the trigger, before a reader could reach it.
- Rely on a tooltip to convey something required for the task — touch-only visitors will never see it.
- Expect Escape to close it — nothing listens for that key here; move focus or the pointer instead.
- Wrap plain, non-focusable text in TooltipTrigger and expect Tab to reach it.

#### Related

Machine-readable record: /r/tooltip.json

### VirtualList (organisms)

Windowed list that only renders the rows currently within (or near) its
viewport, backed by `@tanstack/react-virtual`. Intended to be composed by
`Table` (opt-in `virtualize` prop) and `Combobox` (long option lists) —
see the props above for what those consumers need: `height` (container
height), `estimateSize` (row height estimate), `overscan`, and
`renderItem` (render an arbitrary item by index).

The forwarded ref resolves to a {@link VirtualListHandle}, not the scroll
container element.

Import: `import { VirtualList } from '@elirobinson/react/components/organisms/VirtualList';`
Styles: @elirobinson/react/styles/organisms/VirtualList.css (included in styles.css)
Also accepts all `Omit<HTMLAttributes<HTMLDivElement>, 'children'>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| estimateSize | `(index: number) => number` | yes | — | Estimated size (px) of the row at `index`, used before it has been
measured. Required by the underlying virtualizer even for fixed-height
rows — pass a constant function (e.g. `() => 40`) in that case. |
| height | `number` | yes | — | Fixed height (px) of the scrollable viewport. |
| items | `T[]` | yes | — | The full, un-windowed list of items to virtualize. |
| renderItem | `(item: T, index: number) => ReactNode` | yes | — | Renders the item at `index`. Only called for rows in the current window. |
| overscan | `number` | no | — | Extra rows to render outside the visible viewport, above and below. |

Constraints: no-barrel-imports, forward-ref (see System constraints)

200 rows, but scroll and check the DOM — only the rows near the viewport actually render.

#### When to use it

Use `VirtualList` when you have hundreds or thousands of items and rendering every one to
the DOM would make scrolling stutter. It only renders the rows currently within, or just
outside, its viewport. `Combobox` already uses it internally for long option lists, and
`VirtualTable` uses it for windowed table rows — reaching for it directly usually means a
plain list, not a table (grab `VirtualTable` for that).

If the list rarely runs past a few dozen items, skip it — a plain `.map()` is simpler, and
the fixed-height viewport plus row-measurement bookkeeping cost more than they save at that
size.

#### Scrolling to a row

The forwarded ref does not resolve to the scroll container element. A row currently outside
the window has no DOM node to scroll to, so the ref exposes a `VirtualListHandle` with
`scrollToIndex` instead — backed by the underlying virtualizer's own measurements, not
manual `scrollTop` math.

#### Props

#### Accessibility

- Renders a plain scrollable `<div>` (`overflow: auto`) with no ARIA role of its own — it
  doesn't add list semantics (`role="list"`/`"listitem"`) on your behalf. `VirtualTable`
  layers `role="table"`/`"row"`/`"cell"` on top for that reason; do the same if your content
  needs it.
- **Keyboard:** scrolling is native. The container is a real scrollable element, so once
  something inside it has focus, arrow keys, Page Up/Down, and the mouse wheel or trackpad
  all move it through the browser's own scroll handling — nothing custom is layered on top.
- Rows outside the current window aren't hidden, they don't exist in the DOM yet. Don't rely
  on find-in-page (Cmd/Ctrl+F) to reach one, or hold a ref to a specific row's element — call
  `scrollToIndex` to bring it into range first.
- `estimateSize` is required even for uniform rows — pass a constant function like
  `() => 40`. Once a row renders, its real measured height replaces the estimate.

Do:
- Always pass an explicit height — the viewport needs a fixed size for the virtualizer to know how many rows fit.
- Use scrollToIndex from the ref to jump to a row, instead of hand-rolled scrollTop math.
- Keep renderItem cheap — it runs for every row in the current window on every scroll frame.
- Pass a larger overscan (5-10) if tall rows make scrolling look like content is popping in.

Don't:
- Expect the ref to be a DOM node — it resolves to a VirtualListHandle with scrollToIndex, not an element you can call .focus() or .scrollTo() on.
- Nest VirtualList inside another scrollable container without its own fixed height — two independent scroll regions fighting each other is confusing to use.
- Reach for it under a few dozen items — a plain .map() is simpler and the bookkeeping is not worth it.
- Assume Cmd/Ctrl+F will find text in a row that has not rendered yet — virtualized rows outside the window are not in the DOM.

#### Related

Machine-readable record: /r/virtual-list.json

### VirtualTable (organisms)

Data table that windows its rows instead of paginating them, for large row
counts. Same column model, sorting, and filtering as `Table`; use that one
when pagination is the better fit.

Import: `import { VirtualTable } from '@elirobinson/react/components/organisms/VirtualTable';`
Styles: @elirobinson/react/styles/organisms/VirtualTable.css (included in styles.css)
Also accepts all `TableElementProps & TableBaseProps<T>` props.

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| columns | `ColumnDef<T, unknown>[]` | yes | — | — |
| data | `T[]` | yes | — | — |
| emptyMessage | `string` | no | — | Title shown by the EmptyState row when there are no rows to display. |
| filterable | `boolean` | no | — | Shows a built-in global filter input above the table, wired to TanStack's filtered row model. |
| filterPlaceholder | `string` | no | — | Accessible label / placeholder for the built-in filter input. |
| height | `number` | no | — | Fixed viewport height (px) for the windowed body. |
| overscan | `number` | no | — | Rows to render outside the visible viewport, above and below. |
| rowHeight | `number` | no | — | Estimated/actual row height (px) for the virtualizer. |

Constraints: no-barrel-imports, forward-ref (see System constraints)

200 rows, sortable headers, no pagination — scroll and only the rows near the viewport are
in the DOM.

#### When to use it

Use `VirtualTable` for a dataset large enough that pagination feels like busywork —
thousands of rows someone wants to scroll and sort through directly, not click through in
chunks of ten. It shares `Table`'s column model, sorting, and filtering; the only thing
that changes is how the rows reach the screen — only the ones near the viewport are ever
rendered.

Reach for `Table` instead once pagination is the more natural fit — search results, an
order history someone might want to link straight to "page 3" of. Windowing and pagination
solve the same DOM-size problem two different ways, so `VirtualTable` doesn't also
paginate.

#### Filtering

Same `filterable` and `filterPlaceholder` props as `Table`, running against the same
TanStack `getFilteredRowModel()`.

#### Empty state

#### Props

#### Accessibility

- Builds its own ARIA grid instead of a literal `<table>`: `role="table"` on the root (with
  `aria-colcount`), `role="row"` on each row, `role="columnheader"` for headers, `role="cell"`
  for body cells. This is deliberate — the windowed rows render as absolutely positioned
  `<div>`s, and a `<tbody>` full of non-`<tr>` children is invalid HTML that browsers hoist
  out during parsing, so a real `<table>` would silently break.
- Sortable headers are the same clickable `<button>` as `Table`, and the header cell carries
  `aria-sort` reflecting the live sort state.
- The filter input is the same `type="search"` with `aria-label` set from
  `filterPlaceholder`.
- **Keyboard:** header sort buttons and the filter input are real, focusable elements
  reached by `Tab` in document order, same as `Table`. Scrolling the windowed body is native
  scroll behavior — there's no roving grid navigation moving focus cell to cell; `Tab` plus
  scrolling is how you move through it.
- The header row and the scrolling body share the same computed `grid-template-columns`, so
  columns can't drift out of alignment between them.

Do:
- Set an explicit height and a rowHeight close to the real rendered row height — a mismatch shows up as jumpy scrolling while rows settle into their measured size.
- Use filterable for a first-pass narrow, same as Table.
- Reach for it once row count runs into the thousands and pagination would mean dozens of pages.
- Keep cell content to a single line — cells clip with an ellipsis rather than wrap, since a fixed row height is what makes virtualization possible.

Don't:
- Expect arrow-key cell navigation — there is none; this is a scrollable grid, not a spreadsheet widget.
- Switch between VirtualTable and Table for the same dataset depending on size — pick one per use case so the interaction pattern stays predictable.
- Add more columns than fit your narrowest supported width without checking — columns share the width equally with no built-in horizontal scroll.
- Query a literal table/tr/td element in tests or styles — there is not one; query by role instead.

#### Related

Machine-readable record: /r/virtual-table.json

## Hooks

### useActiveDescendant

Import: `import { useActiveDescendant } from '@elirobinson/react/hooks/useActiveDescendant';`

The `aria-activedescendant` half of the WAI-ARIA combobox/listbox pattern:
DOM focus stays on the input at all times and the "highlighted" option is
conveyed purely by id reference.

Owns one invariant that is easy to get wrong in two different places, which
is why it lives here rather than in each widget: the highlighted index must
always be inside the current option range. Filtering shrinks that range out
from under a previously-valid index, and an unclamped index hands
`aria-activedescendant` a dangling id — visually fine, silently broken for
assistive tech.

Note that the clamp is applied twice, deliberately. The *derived*
`activeIndex` is clamped so the rendered output is always valid, and
`moveActive` clamps the stored value again *before* applying its delta. Only
clamping the derived value leaves the raw state parked above the valid range,
where a single arrow key moves it from (say) 5 to 4 — both of which still
clamp to 1, so the highlight appears stuck until the user presses the key
enough times to walk back into range.

### useAnchoredPosition

Import: `import { useAnchoredPosition } from '@elirobinson/react/hooks/useAnchoredPosition';`

Positions a floating panel against its trigger with `position: fixed`, and
keeps it there while the page scrolls or the window resizes.

Geometry is written straight to the node's inline style rather than held in
state: this runs in a layout effect, before paint, so the panel never shows
up in the wrong place first. The fourth argument accepts a bare side for the
common case (`'top'` / `'bottom'`) or an options object.

A panel that does not fit on the side it asked for flips to the opposite one
— `bottom` to `top`, `start` to `end` — provided the opposite side has room.
Each axis flips at most once per open and never flips back, so the panel
cannot chase a threshold it is sitting on; `align: 'center'` is symmetric and
never flips. A panel that fits on *neither* side is shifted instead: it keeps
its width and slides along the axis until it is inside the viewport, so it
stops being edge-aligned with its trigger, and may overlap it, but it is
never narrowed into the room left beside a pinned edge and never reflows.
Only a panel taller than the viewport fits at no offset at all; that one
takes a `max-height` of the viewport and scrolls its own content.

(The docs site renders the three paragraphs above and stops, so anything
a consumer has to know belongs there rather than here.)

Shifting rather than clamping is the decision #195 asked for, and it is
decided by what a clamp would do: a `position: fixed` panel with no width is
shrink-to-fit, so capping its width does not crop it — it reflows the
content and wraps the labels, which is the squeeze #180 reported and reads
as a styling bug rather than a positioning one. Moving the panel sidesteps
the overflow-versus-wrap tradeoff entirely; the width floor `minWidthFor`
writes survives a shift untouched, because a shift resizes nothing. Unlike
the flip it is never latched — see `shiftIntoView` for why it does not need
to be, and why recomputing it on every reposition cannot walk the panel
across the screen. The one thing it cannot rescue horizontally is a panel
wider than the viewport, which is left flush against the edge it was pinned
to and overflows the other, because narrowing it is exactly what the floor
exists to prevent.

The shift is measured from the panel's rendered box, and the pass is ordered
so that box is worth measuring — see the `position: fixed` written ahead of
the read. Every offset it then writes leaves the panel room for the width it
measured, so a panel placed by this hook is not squeezed into wrapping by
where it was put. What it cannot see is a panel that resizes itself while it
is open: nothing observes that, and it is corrected on the next scroll or
resize like everything else here.

### useClickOutside

Import: `import { useClickOutside } from '@elirobinson/react/hooks/useClickOutside';`

Calls back when a pointer-down lands outside the given refs — the dismissal half of every overlay.

### useDisclosure

Import: `import { useDisclosure } from '@elirobinson/react/hooks/useDisclosure';`

Open/closed state for a component that has to work both ways round: a
consumer either passes `open` and owns the value, or passes neither and lets
the component own it, seeded by `defaultOpen`.

`open` resolves to the controlled prop whenever there is one and to internal
state otherwise, and `setOpen` writes internal state only in the
uncontrolled case while always reporting through `onOpenChange` — so a
controlled consumer never ends up fighting a second copy of the truth.

`setOpen` keeps one identity for the component's lifetime; the current
`onOpenChange` is read from a ref at call time. That matters because the
dismissal hooks (`useClickOutside`, `useEscapeKey`) take a callback as a
dependency, and callers write that callback inline.

### useEscapeKey

Import: `import { useEscapeKey } from '@elirobinson/react/hooks/useEscapeKey';`

Calls back on Escape keydown while enabled — shared dismissal behavior for overlays.

### useHasMounted

Import: `import { useHasMounted } from '@elirobinson/react/hooks/useHasMounted';`

Reports `false` on the server and during the first client render, then `true`
once the component has mounted in a browser.

Gate anything that reads a browser global *during render* on this — in this
package that means `createPortal(…, document.body)`, which otherwise throws
`ReferenceError: document is not defined` when a Next.js or Remix consumer
server-renders the tree. Effects and event handlers do not need it: neither
runs on the server.

Returning `false` for the first client render (rather than checking
`typeof document` directly) is what keeps hydration clean — the client's
initial output has to match the server's, so both must skip the portal and
the content appears on the commit that follows.

### useRovingFocus

Import: `import { useRovingFocus } from '@elirobinson/react/hooks/useRovingFocus';`

Arrow/Home/End traversal for a composite widget that exposes a single tab
stop (a "roving tabindex"): Tab moves into the widget, arrows move within
it.

Both axes are accepted because the same widget can be laid out either way
and a user should not have to guess which; movement wraps at both ends,
per the WAI-ARIA authoring practices for tabs and radio groups.

Only the traversal is shared. What a move *means* differs by widget — tabs
move focus without selecting, radio-style groups select as they move — so
that decision stays with the caller in `onNavigate`.

## Patterns

These are recipes composed from the primitives above — they are NOT importable components.

# Header

The site header is a recipe, not an import — compose it from primitives. It's the one place the
brand sanctions a blur: 92% white with `backdrop-filter` once content scrolls beneath it.

Prototyped in `design-system-docs/ui_kits/marketing/` and shown live in Storybook under
**Patterns/Marketing**.

## Ingredients

[Button](/components/button) for the CTA, the wordmark, plain links, and tokens for
everything else.

## Recipe

```tsx
import { Button } from '@elirobinson/react/components/atoms/Button';

export function SiteHeader({ active }: { active: string }) {
  const items = ['Home', 'Portfolio', 'Store', 'Services', 'About'];
  return (
    <header className="header">
      <a href="/" className="header__wordmark" aria-label="Miltinson home">
        Miltinson<span className="header__dot">.</span>
      </a>
      <nav className="header__nav" aria-label="Primary">
        {items.map((item) => (
          <a
            key={item}
            href="#"
            className="header__link"
            aria-current={active === item ? 'page' : undefined}
          >
            {item}
          </a>
        ))}
        <Button variant="primary" size="sm">
          Hire me
        </Button>
      </nav>
    </header>
  );
}
```

```css
.header {
  position: sticky;
  top: 0;
  z-index: var(--z-sticky);
  display: flex;
  align-items: center;
  justify-content: space-between;
  height: 64px;
  padding: 0 var(--gutter);
  background: oklch(100% 0 0 / 0.92);
  backdrop-filter: blur(8px);
  border-bottom: 1px solid var(--border);
}

.header__wordmark {
  font-weight: var(--fw-semibold);
  font-size: var(--fs-xl);
  color: var(--fg);
  text-decoration: none;
}

.header__dot {
  color: var(--accent);
}

.header__nav {
  display: flex;
  align-items: center;
  gap: var(--space-6);
}

.header__link {
  font-size: var(--fs-sm);
  color: var(--fg-2);
  text-decoration: none;
  /* nav items are primary controls — keep the 44px target */
  padding: var(--space-3) 0;
}

.header__link:hover,
.header__link[aria-current='page'] {
  color: var(--fg);
}

.header__link[aria-current='page'] {
  font-weight: var(--fw-medium);
}
```

## Rules

- **Height 64px, sticky, always visible.** No hide-on-scroll tricks.
- **One CTA at most**, `size="sm"` so it sits inside the 64px band.
- **Active link:** ink + medium weight — not amber; amber in the header belongs to the
  wordmark dot alone.
- Nav links keep a 44px vertical hit area via padding.
- On small screens, collapse nav items behind a [Sheet](/components/sheet)-based menu
  rather than shrinking tap targets.

# Footer

The footer is pure ink — `--bg-inverse`, white type, mono microcopy. The wordmark's period is the
only color at rest.

Prototyped in `design-system-docs/ui_kits/marketing/HeaderFooter.jsx`.

## Recipe

```tsx
export function SiteFooter() {
  return (
    <footer className="footer">
      <div className="footer__top">
        <div>
          <p className="footer__wordmark">
            Miltinson<span className="footer__dot">.</span>
          </p>
          <p className="footer__tagline">Builder · Consultant · Founder</p>
        </div>
        <nav className="footer__nav" aria-label="Footer">
          <a href="/portfolio">Portfolio</a>
          <a href="/store">Store</a>
          <a href="/services">Services</a>
          <a href="/about">About</a>
        </nav>
      </div>
      <p className="footer__meta">
        © 2026 Miltinson Technologies — practical tech, honestly built.
      </p>
    </footer>
  );
}
```

```css
.footer {
  background: var(--bg-inverse);
  color: var(--fg-inverse);
  padding: var(--space-8) var(--gutter) var(--space-7);
  margin-top: var(--space-12);
}

.footer__top {
  display: flex;
  justify-content: space-between;
  align-items: flex-start;
  gap: var(--space-7);
  padding-bottom: var(--space-6);
  border-bottom: 1px solid var(--border-inverse);
}

.footer__wordmark {
  font-weight: var(--fw-semibold);
  font-size: var(--fs-2xl);
  margin: 0;
}

.footer__dot {
  color: var(--accent);
}

.footer__tagline {
  font-family: var(--font-mono);
  font-size: var(--fs-2xs);
  letter-spacing: var(--tr-caps);
  text-transform: uppercase;
  color: oklch(100% 0 0 / 0.55);
  margin-top: var(--space-3);
}

.footer__nav {
  display: flex;
  gap: var(--space-6);
}

.footer__nav a {
  color: var(--fg-inverse);
  font-size: var(--fs-sm);
}

.footer__nav a:hover {
  color: var(--accent-ink-inverse);
}

.footer__meta {
  font-family: var(--font-mono);
  font-size: var(--fs-xs);
  color: var(--fg-inverse-3);
  margin: var(--space-6) 0 0;
}
```

## Rules

- Hairlines on dark use `--border-inverse` (12% white) — never `--border`, which
  disappears on ink.
- Link hover shifts to `--accent-ink-inverse` — the brand color tuned for the inverted
  band, which follows the theme when the band flips. A fixed ramp step does not: the docs
  eyebrow was `--signal-400` and measured 2.07:1 the moment the band turned white.
- Mono microcopy for the tagline and legal line; body sans for nothing-else-down-here.
- The dot-grid texture is allowed here at 8% opacity, but the plain ink block is the
  default.

# Hero

Heroes invert: an ink block with white type, an amber-accented display line, and at most two
actions. The dot-grid texture at 8% opacity is the only decoration allowed on top.

## Recipe

```tsx
import { Button } from '@elirobinson/react/components/atoms/Button';
import { Eyebrow } from '@elirobinson/react/components/atoms/Eyebrow';

export function Hero() {
  return (
    <section className="hero">
      <Eyebrow className="hero__eyebrow">Builder. Consultant. Founder.</Eyebrow>
      <h1 className="hero__title">
        Practical tech, honestly built<span className="hero__dot">.</span>
      </h1>
      <p className="hero__lead">
        I'm Eli Robinson — I build software, teach AI, and create resources for coaches.
      </p>
      <div className="hero__actions">
        <Button variant="accent" size="lg">
          See the work
        </Button>
        <Button variant="ghost" size="lg" className="hero__ghost">
          Get in touch
        </Button>
      </div>
    </section>
  );
}
```

```css
.hero {
  background: var(--bg-inverse);
  color: var(--fg-inverse);
  padding: var(--space-13) var(--gutter);
  /* 8% white dots — the one sanctioned texture */
  background-image: radial-gradient(oklch(100% 0 0 / 0.08) 1px, transparent 1px);
  background-size: 24px 24px;
}

.hero__eyebrow {
  /* The band's own readable brand color. A fixed ramp step does not flip when
     the band does — --signal-400 on a band that turns white measures 2.07:1. */
  color: var(--accent-ink-inverse);
}

.hero__title {
  font-family: var(--font-display);
  font-weight: var(--fw-semibold);
  font-size: clamp(48px, 7vw, var(--fs-8xl));
  line-height: var(--lh-tight);
  letter-spacing: var(--tr-tight);
  margin: var(--space-4) 0 var(--space-5);
  max-width: 14em;
}

.hero__dot {
  color: var(--accent);
}

.hero__lead {
  font-size: var(--fs-xl);
  line-height: var(--lh-relaxed);
  color: var(--fg-inverse-2);
  max-width: var(--container-md);
  margin: 0 0 var(--space-7);
}

.hero__actions {
  display: flex;
  gap: var(--space-4);
}
```

## Rules

- **Display type uses `clamp()`** so the headline survives translation and narrow
  screens.
- **The period is part of the sentence** — end the display line with an amber dot, the
  wordmark's signature move.
- **Two actions maximum:** one accent, one quiet. Never two ambers.
- **No gradients, no imagery meshes.** If the hero needs an image, it's a real
  photograph — warm, slightly desaturated — in a 16:10 block beside the copy on a 7–5
  split, not behind it.
- Light-hero variant: same structure on `--bg` with `--fg` type; keep the amber dot.

# Sidebar

The app-shell sidebar composes [NavigationMenu](/components/navigation-menu) inside a sticky
column — the docs site you're reading uses exactly this recipe.

## Recipe

```tsx
import { NavigationMenu } from '@elirobinson/react/components/organisms/NavigationMenu';

export function AppSidebar({ currentPath }: { currentPath: string }) {
  return (
    <div className="shell">
      <aside className="shell__sidebar">
        <NavigationMenu
          aria-label="Application"
          currentPath={currentPath}
          items={[
            { label: 'Dashboard', href: '/dashboard' },
            {
              label: 'Guides',
              href: '/guides',
              items: [
                { label: 'Drafts', href: '/guides/drafts' },
                { label: 'Published', href: '/guides/published' },
              ],
            },
            { label: 'Orders', href: '/orders' },
            { label: 'Settings', href: '/settings' },
          ]}
        />
      </aside>
      <main className="shell__main">{/* page content */}</main>
    </div>
  );
}
```

```css
.shell {
  display: grid;
  grid-template-columns: 260px minmax(0, 1fr);
  gap: var(--space-10);
  max-width: var(--container-2xl);
  margin: 0 auto;
  padding: var(--space-8) var(--gutter);
}

.shell__sidebar {
  position: sticky;
  top: calc(64px + var(--space-6)); /* header height + breathing room */
  align-self: start;
  max-height: calc(100vh - 64px - var(--space-8));
  overflow-y: auto;
}

@media (max-width: 960px) {
  .shell {
    grid-template-columns: minmax(0, 1fr);
  }
  .shell__sidebar {
    display: none; /* move nav into a Sheet-triggered menu */
  }
}
```

## Rules

- **260px wide, sticky below the header**, scrolling independently when tall.
- `NavigationMenu` marks the current page with `aria-current` — pass the live pathname.
- Nav items are primary controls: keep their 44px hit height when restyling.
- Under 960px, don't shrink the sidebar — replace it with a [Sheet](/components/sheet)
  menu from the top bar.
- Section labels (if you add them above groups) are mono uppercase eyebrows, not
  headings. Add them as items with no `href` — a header carrying its first child's href
  renders as the current page whenever that child is open.

# Top bar

The app top bar pairs orientation (breadcrumb) with tools (search, actions, account). It's the
working-surface sibling of the marketing [header](/patterns/header) — same 64px band, busier
contents.

## Recipe

```tsx
import { Avatar } from '@elirobinson/react/components/atoms/Avatar';
import { Button } from '@elirobinson/react/components/atoms/Button';
import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbSeparator,
} from '@elirobinson/react/components/molecules/Breadcrumb';
import { SearchField } from '@elirobinson/react/components/molecules/SearchField';

export function TopBar() {
  return (
    <div className="top-bar">
      <Breadcrumb>
        <BreadcrumbList>
          <BreadcrumbItem>
            <BreadcrumbLink href="/guides">Guides</BreadcrumbLink>
          </BreadcrumbItem>
          <BreadcrumbSeparator />
          <BreadcrumbItem>
            <BreadcrumbLink current>Practice planning</BreadcrumbLink>
          </BreadcrumbItem>
        </BreadcrumbList>
      </Breadcrumb>
      <div className="top-bar__tools">
        <SearchField aria-label="Search guides" placeholder="Search…" />
        <Button size="sm">New guide</Button>
        <Avatar alt="Eli Robinson" fallback="ER" size="sm" />
      </div>
    </div>
  );
}
```

```css
.top-bar {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: var(--space-6);
  height: 64px;
  padding: 0 var(--space-6);
  border-bottom: 1px solid var(--border);
  background: var(--bg);
}

.top-bar__tools {
  display: flex;
  align-items: center;
  gap: var(--space-3);
}
```

## Rules

- **Breadcrumb on the left, tools on the right.** The page `h1` lives in the content,
  not the bar.
- One primary action (`size="sm"`), everything else quiet.
- The search field stays compact; a full-screen command experience belongs to
  [CommandPalette](/components/command-palette) on `⌘K`.
- `SearchField` has no visible-label prop — in a bar like this, give it an
  `aria-label`; anywhere a visible label fits, prefer one.
- The current page is a `BreadcrumbLink` with `current` — it renders as static text
  with `aria-current="page"`, not a link. Separators are explicit
  `BreadcrumbSeparator` elements.

# Form layout

Single column, 720px measure, labeled controls stacked with consistent rhythm, actions at the end.
The form atoms carry their own label and error wiring — the pattern's job is spacing and order.

## Recipe

```tsx
import { useState } from 'react';

import { Button } from '@elirobinson/react/components/atoms/Button';
import { Checkbox } from '@elirobinson/react/components/atoms/Checkbox';
import { Input } from '@elirobinson/react/components/atoms/Input';
import { Textarea } from '@elirobinson/react/components/atoms/Textarea';
import { Select } from '@elirobinson/react/components/organisms/Select';

export function ContactForm() {
  const [topic, setTopic] = useState('consulting');

  return (
    <form className="form" onSubmit={(event) => event.preventDefault()}>
      <h2>Get in touch</h2>
      <p>Tell me what you need and I'll get back to you within 24 hours.</p>

      <Input label="Name" name="name" autoComplete="name" required />
      <Input
        label="Email"
        name="email"
        type="email"
        autoComplete="email"
        hint="I reply from eli@miltinsons.com — add it to your contacts."
        required
      />
      <Select
        label="What do you need?"
        name="topic"
        value={topic}
        onChange={(event) => setTopic(event.target.value)}
      >
        <option value="consulting">AI consulting</option>
        <option value="support">Tech support</option>
        <option value="coaching">Coaching guides</option>
      </Select>
      <Textarea label="The details" name="details" rows={5} />
      <Checkbox label="Send me the occasional practical update — no spam" name="updates" />

      <div className="form__actions">
        <Button type="submit">Send message</Button>
        <Button type="button" variant="ghost">
          Cancel
        </Button>
      </div>
    </form>
  );
}
```

```css
.form {
  display: flex;
  flex-direction: column;
  gap: var(--space-5);
  max-width: var(--container-md);
}

.form__actions {
  display: flex;
  gap: var(--space-3);
  padding-top: var(--space-3);
  border-top: 1px solid var(--border);
}
```

## Rules

- **One column.** Two-column forms trade scanning speed for error rates; don't.
- **`Input`, `Textarea`, and `Select` require their `label` prop** — there is no
  unlabeled variant, on purpose. For a control that doesn't wire its own labeling
  (a third-party date picker, say), wrap it in [FormField](/components/form-field) —
  and never wrap `Input` in `FormField`, which would render two labels.
- **Errors inline via the `error` prop**, which also sets `aria-invalid` and wires
  `aria-describedby`. On submit failure, move focus to the first invalid control.
- **Hints before errors:** if a rule can be stated up front ("at least 8 characters"),
  put it in `hint` instead of springing it as an error.
- **Primary action first (left), quiet actions after.** The submit button stays
  enabled — a disabled submit hides the error instead of showing it.
- `autoComplete` attributes on identity fields; the browser filling forms correctly is
  an accessibility feature.

# Data display

Numbers first, then the records behind them: a stat-card row above a data table. Numerals are mono
with tabular figures — everything that compares must line up.

## Stat cards

`StatCard` is a composition, not an export — a bordered card with a mono figure and an
eyebrow label:

```tsx
import { Card, CardContent } from '@elirobinson/react/components/molecules/Card';

export function StatCard({
  label,
  value,
  delta,
}: {
  label: string;
  value: string;
  delta?: string;
}) {
  return (
    <Card>
      <CardContent className="stat-card">
        <p className="stat-card__label">{label}</p>
        <p className="stat-card__value">{value}</p>
        {delta && <p className="stat-card__delta">{delta}</p>}
      </CardContent>
    </Card>
  );
}
```

```css
.stat-card__label {
  font-family: var(--font-mono);
  font-size: var(--fs-xs);
  letter-spacing: var(--tr-caps);
  text-transform: uppercase;
  color: var(--fg-3);
  margin: 0 0 var(--space-2);
}

.stat-card__value {
  font-family: var(--font-mono);
  font-size: var(--fs-3xl);
  font-weight: var(--fw-semibold);
  font-variant-numeric: tabular-nums;
  margin: 0;
}

.stat-card__delta {
  font-family: var(--font-mono);
  font-size: var(--fs-sm);
  color: var(--status-success-fg);
  margin: var(--space-1) 0 0;
}
```

Lay them out in an asymmetric grid — a 2fr card for the headline number beats four
equal boxes.

## The records

Below the stats, reach for [Table](/components/table) — paginated, sortable,
filterable — or [VirtualTable](/components/virtual-table) once row counts get into the
thousands. Both take the same TanStack `ColumnDef` columns, so switching later is a
rename. Wire the empty case to [EmptyState](/components/empty-state) — Table renders
one automatically via `emptyMessage`.

```tsx
import { Table } from '@elirobinson/react/components/organisms/Table';
import type { ColumnDef } from '@elirobinson/react/components/organisms/Table';

type Order = { id: string; guide: string; amount: string; date: string };

const columns: ColumnDef<Order>[] = [
  { accessorKey: 'id', header: 'Order' },
  { accessorKey: 'guide', header: 'Guide' },
  { accessorKey: 'amount', header: 'Amount' },
  { accessorKey: 'date', header: 'Date' },
];

export function OrdersTable({ orders }: { orders: Order[] }) {
  return (
    <Table
      data={orders}
      columns={columns}
      pageSize={10}
      emptyMessage="No orders yet — share your store link."
    />
  );
}
```

## Rules

- **Mono numerals with `tabular-nums`** anywhere numbers stack: stats, amounts,
  quantities.
- **Zebra rows use `--bg-subtle`**, hairline row dividers use `--border` — never both
  heavier.
- **Right-align numeric columns**, left-align text; headers match their column.
- Deltas: `--status-success` up, `--status-danger` down, plain `--fg-3` for flat — and
  the sign travels with the number ("+12%"), color is never the only signal.
- An empty table is a first-run experience, not an error — give the
  [EmptyState](/components/empty-state) a next step.

## Voice

The voice pack in force (pack: miltinson). Prop tables and tokens make a page
correct; a voice pack makes it sound like a particular product. This one is the
default this system ships, not a rule of the system — a product declares its own
with `ds init --voice` and this section follows it.

The brand source of truth is design-system-docs/ in this repo; consumers receive the shipped subset through @elirobinson/ai-patterns.

How Miltinson copy is written. Read this before writing for the brand.

### Voice

- **The voice is Miltinson Technologies.** Whether that reads as one person — _"I'm Eli Robinson — I build software, teach AI…"_ — or as a company depends on what the product is, and both are the brand: the same name covers a personal site and a company product. Pick the person from the product, not from a rule, and hold it. The failure is a surface that switches partway through, not a surface that chose "we".
- **Reader is "you."** Direct address, no buffer.
- **Confident but unguarded.** _"No jargon, no judgment — just practical solutions."_ The brand admits the field is full of nonsense and explicitly opts out.

### Tone (in order of weight)

1. **Practical** — "no-fluff", "what's actually useful", "saves you real time"
2. **Honest** — calls out hype, "no contracts required", transparent pricing ("From $150/hr")
3. **Warm** — patient, "trusted hand", reassuring about non-technical readers
4. **Quietly confident** — never flexes credentials, lets the work speak

### Casing & punctuation

- **Sentence case** for headings ("Featured Apps", "Coaching Guides", "Need help with AI or tech?"). Never ALL CAPS for body content.
- **Title Case** is reserved for product/proper names ("Kids Recipes", "AI Consulting", "Tech Support") and the tagline ("Builder. Consultant. Founder.").
- **Periods inside the wordmark.** "Miltinson." with a period — it's part of the mark.
- **Em-dashes** as the favored break: _"I'm Eli Robinson — I build software…"_, _"No jargon, no judgment — just practical solutions."_ Use them.
- **Oxford commas:** yes, when present.
- **Pricing always prefixed with "From"** — "From $150/hr". Never list a single firm number; this signals starting point, not ceiling.

### Words to use

build, ship, practical, honest, no-fluff, hands-on, real, useful, trusted, patient, clear, simple, fun, interactive, no contracts, get started, get in touch, follow-up, what's actually useful

### Words to avoid

synergy, leverage, unlock, empower, robust, cutting-edge, revolutionary, world-class, seamless, frictionless, reimagine, AI-powered (used flatly), 10x, ninja, rockstar

### Emoji

- **Sparingly.** The site uses ✓ as a checklist bullet inside service tier lists. That's it. No 🚀 🎉 ⚡, no decorative emoji in body copy or headings.
- When a small mark is needed (checkmark, arrow), prefer a Lucide SVG icon. ✓ is acceptable as a fallback in plain-text contexts.

### Sample copy snippets (real, from the site — use as anchors)

- _"Builder. Consultant. Founder."_
- _"I'm Eli Robinson — I build software, teach AI, and create resources for coaches."_
- _"Practical, no-fluff guides written for sports coaches."_
- _"Clear, patient tech help for individuals and small businesses who need a trusted hand."_
- _"Tell me what you need and I'll get back to you within 24 hours."_

### Generated taglines (write more in this style)

- "Practical tech, honestly built."
- "Built by hand. Shipped on purpose."
- "Tools that earn their keep."
- "AI help without the hype."

### Brand artifacts

- README.md — design-system-docs
- SKILL.md — Agent skill entry point
- miltinson.voice.json — Voice pack
- styles.css — Aggregate stylesheet [repo-only — not in the published package]
- assets/logo-lockup.svg — logo-lockup.svg
- assets/logo-mark.svg — logo-mark.svg
- assets/logo-wordmark-dark.svg — logo-wordmark-dark.svg
- assets/logo-wordmark.svg — logo-wordmark.svg
- assets/pattern-dotgrid.svg — pattern-dotgrid.svg
- guidelines/brand-marks.html — Marks & lockup [repo-only — not in the published package]
- guidelines/brand-texture.html — Texture [repo-only — not in the published package]
- guidelines/brand-voice.html — Voice [repo-only — not in the published package]
- guidelines/brand-wordmark.html — Wordmark [repo-only — not in the published package]
- guidelines/colors-anchor.html — Anchor / Forest [repo-only — not in the published package]
- guidelines/colors-data.html — Data & charts [repo-only — not in the published package]
- guidelines/colors-ink.html — Ink scale [repo-only — not in the published package]
- guidelines/colors-palettes.html — Palettes [repo-only — not in the published package]
- guidelines/colors-signal.html — Signal / Amber [repo-only — not in the published package]
- guidelines/colors-status.html — Status [repo-only — not in the published package]
- guidelines/colors-surfaces.html — Semantic surfaces [repo-only — not in the published package]
- guidelines/colors-text.html — Text colours [repo-only — not in the published package]
- guidelines/focus.html — Focus & states [repo-only — not in the published package]
- guidelines/motion.html — Motion [repo-only — not in the published package]
- guidelines/radii.html — Radii [repo-only — not in the published package]
- guidelines/shadows.html — Shadows [repo-only — not in the published package]
- guidelines/spacing-in-use.html — Spacing in use [repo-only — not in the published package]
- guidelines/spacing-scale.html — Spacing scale [repo-only — not in the published package]
- guidelines/type-body.html — Body [repo-only — not in the published package]
- guidelines/type-display.html — Display [repo-only — not in the published package]
- guidelines/type-headings.html — Headings [repo-only — not in the published package]
- guidelines/type-mono.html — Mono & eyebrow [repo-only — not in the published package]
- guidelines/type-weights.html — Weights [repo-only — not in the published package]
- components/ai/ai.card.html — AI surfaces [repo-only — not in the published package]
- components/molecules/decision-surfaces.card.html — Decision surfaces [repo-only — not in the published package]
- slides/CloserSlide.html — Miltinson · Closer slide [repo-only — not in the published package]
- slides/ContentSlide.html — Miltinson · Content slide [repo-only — not in the published package]
- slides/index.html — Miltinson · Slides index [repo-only — not in the published package]
- slides/QuoteSlide.html — Miltinson · Quote slide [repo-only — not in the published package]
- slides/TitleSlide.html — Miltinson · Title slide [repo-only — not in the published package]
- patterns/email/newsletter.html — Email template — newsletter.html [repo-only — not in the published package]
- patterns/invoice/invoice.html — Invoice & receipt — invoice.html [repo-only — not in the published package]
- patterns/invoice/receipt.html — Invoice & receipt — receipt.html [repo-only — not in the published package]
- patterns/social-carousel/carousel.html — Social carousel template — carousel.html [repo-only — not in the published package]
- ui_kits/docs/index.html — Docs / Guide UI Kit
- ui_kits/marketing/index.html — Marketing UI Kit (components: Header, Footer, Hero, FeaturedApps, FeatureBand, ServicesBand)
- ui_kits/mobile/index.html — Mobile UI Kit (components: PhoneFrame, BrowseScreen, PracticeScreen)
- ui_kits/webapp/index.html — Web App UI Kit (components: Sidebar, TopBar, StatCard, ProjectsTable)