# Miltinson Design System — full corpus

> Miltinson Design System — tokens, React 19 components, and AI patterns for Miltinson Technologies products. 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/*, styles.css, tokens.css, tokens.json, tokens-data, patterns, contracts).
- **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 — buttons, pagination items, segmented-control options, nav items — have a minimum 44x44px touch target. 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. Check: The computed hit area of each primary control is at least 44x44px.
- **touch-target-dense** — Dense inline affordances — a chip's remove glyph, a search field's clear button, rating stars, calendar day cells — follow shadcn/MUI-scale sizing rather than 44px. Reference: MUI Chip is 32px tall (24px small) with a 22px (16px small) delete icon; shadcn Badge is ~20px tall with 12px icons. Check: Dense affordances match the shadcn/MUI reference scale instead of the 44px rule.
- **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.
- **tier-boundary** — Components live under packages/react/src/components/<tier>/. If a component renders into a portal, traps focus, or manages open/closed state across multiple sub-elements, it is an organism. If it is assembled from 2+ atoms with no such orchestration, it is a molecule. Otherwise it is an atom. Check: The component's directory (atoms | molecules | organisms) matches the boundary rule for its behavior.

UI contracts: minimum touch target 44x44 (scoped — see touch-target-dense), 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 (from @elirobinson/tokens/tokens.css)

- `--ink-0: #ffffff` — pure white
- `--ink-50: oklch(98.4% 0.002 247)` — off-white surface
- `--ink-100: oklch(96.2% 0.003 247)` — hairline backgrounds
- `--ink-200: oklch(92.8% 0.004 247)` — dividers
- `--ink-300: oklch(86% 0.005 247)` — borders
- `--ink-400: oklch(70% 0.006 247)` — disabled / placeholder
- `--ink-500: oklch(55% 0.008 247)` — tertiary text
- `--ink-600: oklch(42% 0.01 247)` — secondary text
- `--ink-700: oklch(30% 0.01 247)` — high-contrast secondary
- `--ink-800: oklch(20% 0.01 247)` — near-black surfaces
- `--ink-900: oklch(12% 0.008 247)` — deep surface
- `--ink-950: oklch(6% 0.006 247)` — card on dark
- `--ink-1000: #000000` — pure black
- `--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)`
- `--status-success: oklch(62% 0.16 155)`
- `--status-warning: oklch(78% 0.16 85)`
- `--status-danger: oklch(58% 0.22 25)`
- `--status-info: oklch(60% 0.13 240)`
- `--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)` — default hairline
- `--border-strong: var(--ink-300)` — emphasized
- `--border-inverse: oklch(100% 0 0 / 0.12)` — on dark
- `--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)` — disabled
- `--fg-inverse: var(--ink-0)` — on dark
- `--fg-on-signal: var(--ink-1000)` — text on lime
- `--accent: var(--signal-500)` — Miltinson Amber
- `--accent-hover: var(--signal-400)`
- `--accent-press: var(--signal-600)`
- `--accent-fg: var(--ink-1000)`
- `--accent-tint: var(--signal-50)` — very-light amber backgrounds
- `--anchor: var(--anchor-500)` — Miltinson Forest
- `--anchor-hover: var(--anchor-400)`
- `--anchor-press: var(--anchor-600)`
- `--anchor-fg: var(--ink-0)`
- `--anchor-tint: var(--anchor-50)`
- `--focus-ring: var(--ink-1000)` — high-contrast focus, ink-on-bg
- `--link: var(--ink-1000)`
- `--link-hover: var(--signal-700)`
- `--link-visited: var(--ink-700)`
- `--status-success: var(--anchor-500)`
- `--status-warning: var(--signal-600)`
- `--font-sans: 'Geist', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif`
- `--font-display: 'Geist', ui-sans-serif, system-ui, -apple-system, sans-serif`
- `--font-mono: '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, 4vw)`
- `--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 — used as a signal, never a fill. Every value on this page is read live from
`@elirobinson/tokens/tokens.css`; the swatches and contrast ratios below cannot drift from what
the package ships.

## 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, success states, and the earnest surfaces
  (coaching guides). It anchors; it doesn't shout.
- **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 — text uses `--signal-700` and darker.

## 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`) fails AA as text on white — which is exactly why button labels
use `--accent-fg` (ink on amber, 8.7:1) and text links only shift to amber's dark step
(`--signal-700`) on hover. `--status-warning` passes at large sizes only; pair it with
an icon or keep warning text at `--fg` with a warning-colored border.

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

## 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 magic number is a bug
waiting for a redesign.

## The scale

## How the scale gets used

- **Generous vertical rhythm.** Major sections on landing pages breathe —
  `--space-13` (128px) between them. Cramped sections read as clutter, not density.
- **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: a pill
button reads as a different brand.

## Shadows

The scale is deliberately restrained. Default cards take `--shadow-sm` — a hairline
tint that reads as paper, not levitation. `--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

Calm and purposeful. Motion here confirms what happened — it never performs. 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.

## Feel it

## 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.** The content is the show.
- **`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

Accessibility is a foundation here, not a review step. The tokens, the components, and the brand
rules are all shaped by it — if you build with the system's defaults, you inherit most of this for
free.

## 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 — this is the system's most misunderstood policy:

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

### 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 one action I most want taken.
- **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 | — | — |
| defaultValue | `string \| number \| readonly string[]` | no | — | — |
| onValueChange | `((value: string) => void)` | no | — | — |
| value | `string` | no | — | — |

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

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

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

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

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

| 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 | `"single" \| "multiple"` | 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, @elirobinson/react/styles/organisms/VirtualList.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, @elirobinson/react/styles/organisms/Dialog.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 | — | — |
| 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.

#### Props

#### Accessibility

- The calendar uses the WAI-ARIA grid pattern: `role="grid"` (labeled with the visible month
  and year), one `role="row"` per week, and `role="gridcell"` per day. Every 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 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, DialogTrigger, DialogHeader, DialogTitle, DialogDescription, DialogFooter, DialogClose, DialogContent } 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 | — | — |

#### DialogTrigger

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

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

#### DialogClose

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

#### DialogContent

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLDialogElement>` 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

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLDivElement>` 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 |
| --- | --- | --- | --- | --- |
| 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.

#### 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 when the menu opens (not on every scroll or resize).

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

(no props of its own beyond inherited HTML attributes)
Also accepts all `HTMLAttributes<HTMLDivElement>` 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 — calculated once when it opens, not
  re-measured on scroll or resize.

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, SheetTrigger, SheetHeader, SheetTitle, SheetDescription, SheetFooter, SheetClose, SheetContent } 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 | — | — |

#### SheetTrigger

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

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

#### SheetClose

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

#### SheetContent

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| side | `"left" \| "right" \| "top" \| "bottom"` | no | right | — |
Also accepts all `HTMLAttributes<HTMLDialogElement>` 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, @elirobinson/react/styles/organisms/table/core.css (included in styles.css)

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| columns | `ColumnDef<T>[]` | 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 `getFilteredRowModel()`. |
| 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.

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)

| 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, @elirobinson/react/styles/organisms/VirtualList.css, @elirobinson/react/styles/organisms/table/core.css (included in styles.css)

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| columns | `ColumnDef<T>[]` | 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 `getFilteredRowModel()`. |
| 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';`

Fixed-position layout for a floating panel relative to its trigger, above or below, kept inside the viewport.

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

### 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. It's the most recognizable
Miltinson surface after the wordmark, and it's deliberately quiet.

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(--signal-400);
}

.footer__meta {
  font-family: var(--font-mono);
  font-size: var(--fs-xs);
  color: var(--ink-400);
  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 `--signal-400` — the lighter amber step keeps AA on black.
- 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 {
  color: var(--signal-400);
}

.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(--ink-300);
  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);
  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.