# Echo UI

> A neo-skeuomorphic React component library you install into your own source tree with `npx echo-ui-cli`. Molded caps in recessed wells, emissive readouts, real press travel. Motion (GSAP) and sound (zero-dep WebAudio synth) are first-class token families alongside color and type.

> IMPORTANT: The Base UI package is `@base-ui/react` (per-component imports, e.g. `@base-ui/react/dialog`), NOT `@base-ui-components/react` (the old name). Training data may be stale.

## Accessibility

Accessibility is part of the grammar, not a review step. Echo guarantees WCAG 2.2 AA, and these are the parts a consumer can still get wrong:

- Every control needs a name. `Switch`, `Checkbox`, `Slider`, `Segmented`, `Select`, `RadioGroup` and `Progress` take `aria-label` (or `aria-labelledby` pointing at visible text); `Field`, `Textarea` and `OtpField` take a visible `label`. Without one they do not compile.
- An icon-only `HardwareButton` (`iconOnly`) needs `aria-label`: it has no text to read.
- Forms: put the help text in `description` and the problem in `error`, both on the field. They are linked to the input and set `aria-invalid` for you. Never signal an error with colour or a red border alone.
- Announcements: mount `<Toaster>` once and call `toast()` from `useToast()`. A message rendered into the page when it happens is usually never announced.
- Sign-in: `Field` with `autoComplete` (`email`, `current-password`), and `OtpField` for a one-time code — it allows pasting, which people rely on.
- State is never colour alone: Echo has one accent, and its components already carry state in shape and words. Do not add a red for danger; use `AlertDialog`, which asks before anything destructive.
- Do not remove a focus ring, shrink a target below 24×24px, or set `aria-hidden` on something focusable.

## Components

- [Modal](https://echo-ui.com/e/modal.json): Base UI Dialog (focus trap, Esc, scroll-lock, a11y) skinned as an Echo device panel. motion.summon enter, GSAP exit that completes before unmount, sound.transition on open.
- [Menu](https://echo-ui.com/e/menu.json): Base UI Menu (typeahead, roving focus, submenu timing, checkbox/radio items) skinned as an Echo floating panel — the Select's molded cap trigger and the same lit dot for what is on. sound.transition on open, sound.select on item commit. Exports ContextMenu for the right-click case.
- [Sheet](https://echo-ui.com/e/sheet.json): A molded chassis panel that slides in from an edge — the console side panel and the mobile nav. Built on Base UI's Drawer, so it carries swipe-to-dismiss and a backdrop that tracks the swipe. sound.transition on open.
- [AlertDialog](https://echo-ui.com/e/alert-dialog.json): A destructive confirm. Modal covers the structure; this is the semantics — role=alertdialog, a required description, and no dismissal by clicking away. sound.caution on open, sound.error on a destructive confirm. Severity is the deep end of the accent ramp, never an imported red.
- [HardwareButton](https://echo-ui.com/e/hardware-button.json): The molded tactile button: a cap in a recessed well with real press travel + sound. primary/neutral/ghost, sm/md/lg, icon slots, icon-only, loading, engraved. Built on semantic vars + useTactile.
- [Popover](https://echo-ui.com/e/popover.json): Base UI Popover (anchoring, focus, dismiss, a11y) skinned as an Echo panel. useGsapPresence summon-in / GSAP exit before unmount; sound.select on open.
- [Tooltip](https://echo-ui.com/e/tooltip.json): Base UI Tooltip (hover/focus, delay, a11y) skinned as a compact molded chip. Same useGsapPresence bridge as Modal/Popover.
- [Select](https://echo-ui.com/e/select.json): Base UI Select (typeahead, keyboard, a11y) skinned as an Echo dropdown — a molded cap trigger and a floating panel with a lit dot on the selected option. CSS fade/scale; sound.select on change.
- [Command](https://echo-ui.com/e/command.json): The command palette as a dot-matrix readout — the query line is the LcdChip's recessed screen well with an emissive caret and a scanline wash. Base UI Autocomplete for the input and listbox semantics, Base UI Dialog for the frame. Cmd/Ctrl+K by default; matches hidden keywords as well as labels.
- [Tabs](https://echo-ui.com/e/tabs.json): Base UI Tabs (roving focus, arrow-key nav, a11y) marked with the library's one "you are here": a 2px lit rail slides under the open tab, over a hairline baseline. Labels stay on the chassis. sound.select on change. Compound API.
- [Accordion](https://echo-ui.com/e/accordion.json): Base UI Accordion (keyboard, a11y, height measurement) skinned as molded device panels that expand. Click sound on toggle; height animates via CSS. Compound API.
- [Switch](https://echo-ui.com/e/switch.json): Base UI Switch (role=switch, keyboard, a11y) with a hardware-toggle skin — a molded thumb sliding in a recessed track — and a click sound on toggle.
- [Checkbox](https://echo-ui.com/e/checkbox.json): Base UI Checkbox (keyboard, indeterminate, a11y) with a molded box skin that fills accent and shows a check when set. Select sound on change.
- [Slider](https://echo-ui.com/e/slider.json): Base UI Slider (keyboard, drag, track-press, a11y) with a recessed rail + molded knob and a scrubbing tick sound on each step.
- [Segmented](https://echo-ui.com/e/segmented.json): A hardware segmented selector — molded uppercase segments in a recessed well, the active one on the lit primary cap. A radiogroup value selector (roving focus, arrow-key select, select sound), distinct from Tabs which switches content panels.
- [Field](https://echo-ui.com/e/field.json): A text input sunk into a recessed well. The inner edge lights in the accent on focus; a mono eyebrow label and an optional machine (mono) value voice.
- [Textarea](https://echo-ui.com/e/textarea.json): Field's recessed well, multi-line and autosizing. The height is measured from the browser's own layout rather than counted from newlines, so it stays right when lines wrap and when the container resizes.
- [Badge](https://echo-ui.com/e/badge.json): A small molded/LCD status label: neutral, accent, lcd, outline. Static; composes var(--echo-*).
- [Kbd](https://echo-ui.com/e/kbd.json): A molded keycap for keyboard hints. Uses the <kbd> element; composes var(--echo-*).
- [Divider](https://echo-ui.com/e/divider.json): A panel seam — a hairline with a faint light lip. Horizontal or vertical; role=separator.
- [StatTile](https://echo-ui.com/e/stat-tile.json): A recessed LCD readout: a glowing value over a machine label in a dark well. Static; composes var(--echo-*).
- [Chart](https://echo-ui.com/e/chart.json): StatTile's dot-matrix language applied to a series: a column per sample, cells lit from the bottom, in the recessed screen well LcdChip and Progress use. Quantises to whole cells by construction — a readout, not a charting library.
- [AppShell](https://echo-ui.com/e/app-shell.json): The app frame: a molded chassis rail, a sticky sidebar, and the content between them. Slots, not props. Ships the skip link by construction and derives the sidebar's sticky offset from the rail's height.
- [Panel](https://echo-ui.com/e/panel.json): The two halves of the device material law as a container: raised molded plastic (things you touch) or a recessed dark screen (things you read).
- [Progress](https://echo-ui.com/e/progress.json): A discrete LED cell meter in a recessed strip — filled cells are lit accent LEDs with a bloom. Steppy by construction; role=progressbar.
- [Loader](https://echo-ui.com/e/loader.json): Three accent LEDs breathing in sequence — the device thinking. role=status; reduced motion holds the dots steady.
- [StatusDot](https://echo-ui.com/e/status-dot.json): A tiny LED — lit accent with a bloom, or dead plastic gray. Decorative (aria-hidden) unless given a label.
- [Toast](https://echo-ui.com/e/toast.json): A raised glass notification slab with a status LED — lit accent when active. Presentational (role=status); queueing stays in the consumer.
- [LcdChip](https://echo-ui.com/e/lcd-chip.json): An inline recessed LCD readout — a glowing accent value beside a machine label, sunk into a dark well. The chip form of StatTile.
- [LedKey](https://echo-ui.com/e/led-key.json): A molded pill key with an indicator LED that breathes while lit. The latching sibling of HardwareButton — for a key whose own state is part of the answer.
- [EngravedPlate](https://echo-ui.com/e/engraved-plate.json): A paper-coloured metal plate with text cut into it and rivets at the edges — the one non-emissive readout. For a fact fixed to the device, where LcdChip is for a live value.
- [Textures](https://echo-ui.com/e/textures.json): The grain law as composable overlays: Dither, Noise, Halftone, Scanlines, plus GrainField and Textured. Inline SVG tiles, no asset files; decorative and pointer-events-free.
- [ShaderField](https://echo-ui.com/e/shader-field.json): The live brand field — a WebGL domain-warped fbm gradient sampled from the accent ramp, blooming toward the cursor. Reduced motion draws one static frame; no WebGL falls back to a CSS gradient.
- [RadioGroup](https://echo-ui.com/e/radio-group.json): One choice from a small set, as molded selector caps with a pip that lights accent when chosen. Base UI owns roving focus and arrow-key selection.
- [OTP field](https://echo-ui.com/e/otp-field.json): The one-time code a sign-in asks for, as a row of lit digit windows. Built on Base UI's OTP Field: paste fills the row, arrow keys and Backspace walk it, and autocomplete="one-time-code" lets a phone offer the code.
- [NumberField](https://echo-ui.com/e/number-field.json): A machined readout between two molded step caps, with the label doubling as a drag-to-scrub handle. Base UI owns typing, arrow keys, step sizes, and clamping.
- [Avatar](https://echo-ui.com/e/avatar.json): A person or device as a molded disc — image in a well, or initials engraved into the plastic when there is no image or it fails to load.
- [Tag](https://echo-ui.com/e/tag.json): A label the user applied, optionally removable. Badge reports what the system knows; Tag is a small plate that can be peeled off.
- [CountBadge](https://echo-ui.com/e/count-badge.json): A number worth noticing — the lit sibling of Badge. Disappears at zero, caps its face at max while still announcing the true count.
- [Skeleton](https://echo-ui.com/e/skeleton.json): The shape of content that has not arrived: a recess with a slow sheen. aria-hidden by default; one label announces the wait for the whole region.
- [Banner](https://echo-ui.com/e/banner.json): A persistent inline message strip for a condition that is still true. Severity by luminance and a tone pip, not by hues the seed does not own.
- [EmptyState](https://echo-ui.com/e/empty-state.json): Nothing here, and what to do about it — a quiet recess with the way forward built into the API.
- [Table](https://echo-ui.com/e/table.json): Rows of data in a recessed screen well. Real table semantics, a required caption, tabular figures for numbers, and a scroll region that keyboard users can reach.
- [Breadcrumb](https://echo-ui.com/e/breadcrumb.json): Where you are in the hierarchy, as an engraved trail. Labelled nav around an ordered list; the current page is text with aria-current, not a link.
- [Pagination](https://echo-ui.com/e/pagination.json): Molded number caps with the current page lit. The window never elides a single page and never changes width as you page through.
- [Steps](https://echo-ui.com/e/steps.json): How far through a sequence you are, as LED stations on a wire. aria-current on the current station; the done state reaches screen readers as words, not colour.
- [Auth screen](https://echo-ui.com/e/auth.json): Sign-in and its 2FA step as a front panel: a nameplate, recessed wells to type into, one lit cap to commit. Proves the first-press moment.
- [Settings screen](https://echo-ui.com/e/settings.json): The entire control set at rest, as labelled rows. Proves that the control language coheres across fifteen controls and that the sound design survives rapid input.
- [Console screen](https://echo-ui.com/e/console.json): A device dashboard as a front panel: AppShell, six StatTile readouts, an LED level matrix, a takes Table and Pagination. Proves density and data at scale.
- [Chat screen](https://echo-ui.com/e/chat.json): One conversation as a front panel: Avatar + StatusDot header, a message log, a Loader typing indicator, and a Textarea composer with one lit Send cap. Proves the material language survives running text.
- [Theme Engine](https://echo-ui.com/e/theme.json): createEchoTheme(seed) — OKLCH derivation turning a ~6-value seed into the full semantic-role set, with dual { css, values } output and WCAG-AA contrast guardrails. The token foundation every Echo component depends on.
- [Sound Engine](https://echo-ui.com/e/sound.json): SoundProvider + zero-dep WebAudio SynthBackend. Sound tokens are serializable synth recipes; lazy AudioContext, persisted mute, per-play jitter, blur guard, and reduced-motion coupling.
- [Motion Tokens](https://echo-ui.com/e/motion.json): GSAP motion tokens (duration + ease as serializable data), each with an optional reduced-motion collapse variant. Glass moves smooth; pixels move steppy.
- [useTactile](https://echo-ui.com/e/use-tactile.json): The fusion primitive: binds motion (GSAP) + sound per interaction phase, with pointer/keyboard parity and prefers-reduced-motion collapse. Accepts token names or raw GSAP vars / sound recipes as an escape hatch.
- [useGsapPresence](https://echo-ui.com/e/use-gsap-presence.json): The GSAP-exit bridge (implemented once, reused by every Base UI wrapper): controls open state + actionsRef so the exit animation completes before Base UI unmounts. Runs the enter on mount.

## Tokens

- Color roles: --echo-surface, --echo-cap, --echo-cap-highlight, --echo-cap-shadow, --echo-well, --echo-accent, --echo-accent-highlight, --echo-accent-pressed, --echo-accent-glow, --echo-primary-cap-top, --echo-primary-cap-mid, --echo-primary-cap-base, --echo-accent-fill-top, --echo-accent-fill-base, --echo-lcd, --echo-lcd-glow, --echo-text, --echo-text-dim, --echo-seam
- Sound: tap, press, release, select, transition, notify, caution, error, celebrate
- Motion: press, pop, summon, breath, settle, glitch, flood, drain

## Setup

Set the project up once with `npx echo-ui-cli init`. It installs `echo-ui-core`, writes `echo.json`, `echo-lock.json` and `echo-theme.css`, and prints the lines to paste. It never edits your files, and `add` refuses to run before it.

```sh
npx echo-ui-cli init
```

Components render with no colour until the theme is on the page. `init` writes `echo-theme.css` into the Echo folder — import it once from your global CSS or your root layout (or call `createEchoTheme().css` from `echo-ui-core/theme` to build it at runtime). Give the page a dark ground (`body { background: var(--echo-well); color: var(--echo-text); }`), and wrap the app in `SoundProvider` from `echo-ui-core/sound` — without it every component is silent.

Echo components are client components. In the Next.js App Router, a file that passes them a function (`onSave`, `onSubmit`, `onClick`) must start with `"use client"`.

## Install

```sh
npx echo-ui-cli add <component>
```

Echo is a REGISTRY, not an npm component package. Components are installed with `npx echo-ui-cli add <component>` and then live in the consumer's own source tree, importing each other by relative path inside one Echo folder. Never suggest `npm install` for a component. The one npm package is `echo-ui-core`, the grammar they all import (theme, sound, motion, tactile, presence).

Cross-component dependencies resolve automatically. Consume only Layer-3 semantic vars (`var(--echo-*)`) in your own CSS; theme by passing a seed to `createEchoTheme`.

## Conformance

Every component is tested against WCAG 2.2 AA: axe, keyboard, focus-visible, forced-colors, target-size, reflow — and each item's `/e/` record carries the same block. Not covered: screen-reader: not yet verified by a person.

---

# Full component reference

## Modal (`echo-modal`)

Base UI Dialog (focus trap, Esc, scroll-lock, a11y) skinned as an Echo device panel. Enter uses motion.summon; exit is a GSAP tween that completes before unmount via useGsapPresence + actionsRef. sound.transition on open.

*Feel:* A device panel that rises out of a dimmed room, and sinks back the way it came.

- Type: registry:component
- npm deps: gsap, @base-ui/react, echo-ui-core
- Install: `npx echo-ui-cli add modal`

### Usage

```tsx
import { HardwareButton } from "@/echo/hardware-button";
import { Modal } from "@/echo/modal";

<Modal
  trigger={<HardwareButton>Settings</HardwareButton>}
  title="Settings"
  description="Tune the device."
>
  <p>Body content…</p>
</Modal>
```

### Composition

```text
Modal
```

### Examples

**Basic modal** — A trigger plus title/description/body.

```tsx
<Modal
  trigger={<HardwareButton>Settings</HardwareButton>}
  title="Settings"
  description="Tune the device."
>
  <p>Body content…</p>
</Modal>
```

**With footer actions** — Footer for confirm/cancel.

```tsx
<Modal trigger="Delete" title="Are you sure?" footer={<HardwareButton variant="primary">Confirm</HardwareButton>} />
```

### Accessibility

- Base UI Dialog: `role="dialog"` and `aria-modal`, named by `title` and described by `description`.
- Focus moves into the panel, stays there while it is open, and returns to the trigger when it closes. The page behind cannot scroll.
- Escape or a click on the backdrop closes it.

### Motion & sound

- Motion tokens: `summon`
- Reduced motion: The panel fades in and out without moving; the backdrop fades faster.
- Sound: `transition` when it opens.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `trigger` | `ReactNode` | — | What opens the modal. An element (e.g. a HardwareButton) becomes the trigger itself; text is wrapped in a plain trigger. |
| `title` | `ReactNode` | — | The dialog title — also its accessible name. Always pass one. |
| `description` | `ReactNode` | — | One line under the title, announced with it. |
| `footer` | `ReactNode` | — | Actions row under the body, e.g. confirm and cancel buttons. |
| `size` | `"sm" | "md" | "lg"` | "md" |  |
| `showClose` | `boolean` | true |  |
| `defaultOpen` | `boolean` | false |  |
| `container` | `unknown` | — | Where the popup mounts; defaults to <body>. Pass an element inside a scoped theme so the popup wears that theme, not the :root one. |

### Anti-patterns
- Do not add a CSS transition to the popup — GSAP owns its transform/opacity; a CSS transition will fight it.
- Do not skip actionsRef when animating exit with JS — Base UI can't detect GSAP and will unmount too early.
- The package is `@base-ui/react`, not `@base-ui-components/react` (agents have stale training data).

## Menu (`echo-menu`)

Base UI Menu (typeahead, roving focus, submenu timing, checkbox/radio item semantics) skinned as an Echo floating panel — the Select's molded cap trigger and the same lit dot for what is on. Two sounds: transition when the panel arrives, select when an item commits. Exports ContextMenu from the same item for the right-click case. Compound API.

*Feel:* A short list that drops from its button; each choice clicks like a key.

- Type: registry:component
- npm deps: @base-ui/react, echo-ui-core
- Install: `npx echo-ui-cli add menu`

### Usage

```tsx
import { Menu } from "@/echo/menu";

<Menu>
  <Menu.Trigger>Actions</Menu.Trigger>
  <Menu.Content>
    <Menu.Item onClick={rename}>Rename</Menu.Item>
    <Menu.Separator />
    <Menu.Item onClick={archive}>Archive</Menu.Item>
  </Menu.Content>
</Menu>
```

### Composition

```text
Menu
  Menu.Trigger
  Menu.Content
    Menu.Item
    Menu.LinkItem
    Menu.CheckboxItem
    Menu.RadioGroup
      Menu.RadioItem
    Menu.Group
      Menu.GroupLabel
    Menu.Separator
    Menu.SubmenuTrigger
ContextMenu
  ContextMenu.Content
```

### Examples

**Dropdown** — Content wraps Base UI's Portal, Positioner and Popup in one.

```tsx
<Menu>
  <Menu.Trigger>Actions</Menu.Trigger>
  <Menu.Content>
    <Menu.Item onClick={rename}>Rename</Menu.Item>
    <Menu.Item onClick={duplicate}>Duplicate</Menu.Item>
    <Menu.Separator />
    <Menu.Item onClick={archive}>Archive</Menu.Item>
  </Menu.Content>
</Menu>
```

**Your own trigger** — render swaps the default cap for any component, keeping the menu wiring.

```tsx
<Menu.Trigger render={<HardwareButton>Actions</HardwareButton>} />
```

**Checkable items** — The lit dot marks what is on — the same indicator Select uses.

```tsx
<Menu.CheckboxItem checked={grid} onCheckedChange={setGrid}>
  Show grid
</Menu.CheckboxItem>
```

**Right-click menu** — Same panel, same items; the Trigger is the region, not a button.

```tsx
<ContextMenu>
  <ContextMenu.Trigger className="track">…</ContextMenu.Trigger>
  <ContextMenu.Content>
    <ContextMenu.Item onClick={split}>Split at playhead</ContextMenu.Item>
  </ContextMenu.Content>
</ContextMenu>
```

### Accessibility

- Base UI Menu: the trigger is a button with `aria-haspopup`; the list is a `menu` of `menuitem`s, with `menuitemcheckbox` and `menuitemradio` for the marked items.
- Arrow keys move through items, typing jumps to a match, Enter or Space activates, Escape closes and returns focus to the trigger.
- `ContextMenu` opens on right-click and on long-press; give the same actions another way in too, since neither is discoverable.

### Motion & sound

- Motion tokens: `--echo-duration-glide`
- Reduced motion: The list appears with a short fade and does not slide.
- Sound: `transition` when it opens.
- Sound: `select` when an item is chosen.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `Content.side` | `"top" | "right" | "bottom" | "left"` | "bottom" | Preferred side of the trigger. Flips automatically when there is no room. |
| `Content.align` | `"start" | "center" | "end"` | "start" | Alignment along that side. A menu hangs off its trigger, so start is the default. |
| `Content.sideOffset` | `number` | 8 | Gap between trigger and panel, in px. |
| `Content.container` | `unknown` | — | Where the panel mounts; defaults to <body>. Pass an element inside a scoped theme so the panel wears that theme, not the :root one. |

### Anti-patterns
- Do not use a Menu as navigation for a whole site — it hides every destination behind a press. A menu is for ACTIONS on the thing you already have; a nav is a list you can see.
- Never put the destructive action adjacent to the routine one in the same group. Separate it, or better, send it through an AlertDialog — a menu item fires on the first click, with no second chance.
- Do not reach for a Menu when the choice sets a value — that is Select, which reports the current value in its trigger. A Menu trigger says what it does, not what is chosen.
- Do not nest more than one submenu level. Base UI will happily render it; a person will not find it.

## Sheet (`echo-sheet`)

A molded chassis panel that slides in from an edge — the console side panel and the mobile nav. Built on Base UI's Drawer, so it carries swipe-to-dismiss and a backdrop that tracks the swipe rather than a Dialog translated sideways. sound.transition on open. Compound API.

*Feel:* A panel that slides in from the edge and can be swiped back out.

- Type: registry:component
- npm deps: @base-ui/react, echo-ui-core
- Install: `npx echo-ui-cli add sheet`

### Usage

```tsx
import { Sheet } from "@/echo/sheet";

<Sheet>
  <Sheet.Trigger>Channels</Sheet.Trigger>
  <Sheet.Content title="Channels" description="Pick an input to monitor.">
    …
  </Sheet.Content>
</Sheet>
```

### Composition

```text
Sheet
  Sheet.Trigger
  Sheet.Content
    Sheet.Close
```

### Examples

**Side panel** — Defaults to the right edge, swiping right to dismiss.

```tsx
<Sheet>
  <Sheet.Trigger>Channels</Sheet.Trigger>
  <Sheet.Content title="Channels" description="Pick an input to monitor.">
    …
  </Sheet.Content>
</Sheet>
```

**Mobile nav** — From the left, where a hamburger button lives.

```tsx
<Sheet side="left">
  <Sheet.Trigger>Menu</Sheet.Trigger>
  <Sheet.Content title="Navigate">…</Sheet.Content>
</Sheet>
```

**Bottom sheet** — Swipes down. Good for a one-handed action list on a phone.

```tsx
<Sheet side="bottom"><Sheet.Content title="Export">…</Sheet.Content></Sheet>
```

### Accessibility

- Base UI Drawer: a modal dialog named by `title` and described by `description`.
- Focus is trapped inside while open and returns to the trigger when it closes. Escape or a click on the backdrop closes it.
- Swiping it away is a touch extra; every way of closing it also works from the keyboard.

### Motion & sound

- Motion tokens: `--echo-duration-pop`
- Reduced motion: The panel and backdrop fade instead of sliding.
- Sound: `transition` when it opens.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `side` | `"left" | "right" | "top" | "bottom"` | "right" | Edge the sheet is pinned to AND the direction it swipes away — one decision, so they cannot drift apart. |
| `Content.title` | `unknown` | **required** | Accessible name for the panel. A drawer without one is an unlabelled region. |
| `Content.description` | `unknown` | **required** | What the panel is for, under the title. |
| `Content.showClose` | `boolean` | true | Show the corner close control. |
| `Content.container` | `unknown` | — | Where the panel mounts; defaults to <body>. Pass an element inside a scoped theme so the panel wears that theme, not the :root one. |

### Anti-patterns
- Always pass a title. Without one the panel is an unlabelled region, and a screen-reader user is dropped into content with no idea what opened.
- Do not put a form that needs a confirm-or-cancel decision in a Sheet — a sheet can be swiped away mid-edit by design. That is a Modal, which cannot.
- Do not stack sheets. A second sheet over the first leaves no way back except dismissing both, and the swipe gesture becomes ambiguous.
- Do not use a Sheet where a Popover would do. A sheet takes the whole edge of the screen and a backdrop; a small anchored panel does not need either.

## AlertDialog (`echo-alert-dialog`)

A destructive confirm. Modal covers the structure; this is the semantics — role=alertdialog, a required description, and no dismissal by clicking away, so the question has to be answered. Its own sound: caution (the one rough waveform) on open, error on a destructive confirm. Severity reads as the deep end of the accent ramp, never an imported red.

*Feel:* A warning that has to be answered: a rough buzz on arrival, and Cancel under your finger first.

- Type: registry:component
- npm deps: @base-ui/react, echo-ui-core
- Install: `npx echo-ui-cli add alert-dialog`

### Usage

```tsx
import { AlertDialog } from "@/echo/alert-dialog";
import { HardwareButton } from "@/echo/hardware-button";

<AlertDialog
  trigger={<HardwareButton>Erase takes</HardwareButton>}
  title="Erase all takes?"
  description="Twelve recordings will be removed. This cannot be undone."
  confirmLabel="Erase"
  onConfirm={erase}
/>
```

### Composition

```text
AlertDialog
```

### Examples

**Erase confirm** — Name the action in the button, state the consequence above it.

```tsx
<AlertDialog
  trigger={<HardwareButton>Erase takes</HardwareButton>}
  title="Erase all takes?"
  description="Twelve recordings will be removed. This cannot be undone."
  confirmLabel="Erase"
  onConfirm={erase}
/>
```

**A serious but non-destructive decision** — destructive={false} keeps the modality and drops the heavy cap and the sound.

```tsx
<AlertDialog
  title="Publish to the public registry?"
  description="Anyone will be able to install this item."
  confirmLabel="Publish"
  destructive={false}
  onConfirm={publish}
/>
```

### Accessibility

- `role="alertdialog"`, named by `title` and described by `description`, so a screen reader announces a decision, not a panel.
- Clicking outside does not dismiss it — it has to be answered.
- Cancel comes first in the tab order, so a reflexive Enter never confirms the destructive action.
- Focus is trapped while it is open and returns to the trigger afterwards.

### Motion & sound

- Motion tokens: `--echo-duration-glide`, `--echo-duration-swap`
- Reduced motion: It appears in place with a short fade, and its buttons no longer move when pressed.
- Sound: `caution` when it opens.
- Sound: `error` when a destructive action is confirmed; nothing when a non-destructive one is.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `trigger` | `unknown` | **required** | Element or text that opens the dialog. |
| `title` | `unknown` | **required** | The decision, phrased as a question. |
| `description` | `unknown` | **required** | What happens if they say yes. Required — a confirm without its consequence has already decided for the user. |
| `children` | `unknown` | **required** | Extra detail between the description and the answers. |
| `confirmLabel` | `string` | "Confirm" | Name the ACTION ("Erase", "Discard"), never "OK" — the label is the last thing read before it happens. |
| `cancelLabel` | `string` | "Cancel" |  |
| `destructive` | `boolean` | true | Defaults TRUE: this component exists for the destructive case, so the dangerous spelling is not the quiet one. |
| `onConfirm` | `function` | — | Fired when the confirming answer is pressed. |
| `onCancel` | `function` | — |  |
| `open` | `boolean` | — | Controlled open state. |
| `defaultOpen` | `boolean` | — |  |
| `onOpenChange` | `function` | — |  |
| `container` | `unknown` | — | Where the dialog mounts; defaults to <body>. Pass an element inside a scoped theme so the dialog wears that theme, not the :root one. |

### Anti-patterns
- Never label the confirming answer "OK" or "Yes". By the time someone reads the button they have often stopped reading the prose — the label has to say what will happen.
- Do not use an AlertDialog for anything reversible. It blocks the whole screen and cannot be dismissed by clicking away; spend that interruption only on decisions that cannot be undone. For a reversible action, act and offer an undo in a Toast.
- Do not put the destructive answer first in the DOM. Cancel comes first so it is what Tab reaches and what a reflex Enter confirms.
- Never restate the title in the description. The title is the question; the description is the consequence. If the description only rephrases the question, the user has been told nothing.
- Do not import a red. Severity here is the deep end of the accent ramp so it survives a reseed — a hardcoded #d00 is the one thing that will not relight.

## HardwareButton (`echo-hardware-button`)

A molded cap in a recessed well with real press travel and sound. primary/neutral/ghost, sm/md/lg, icon slots, loading, engraved. Press feel and sound come from useTactile; plastic color from createEchoTheme.

*Feel:* A molded cap in a recessed well: it travels down under your finger with a click, then springs back.

- Type: registry:component
- npm deps: gsap, echo-ui-core
- Install: `npx echo-ui-cli add hardware-button`

### Usage

```tsx
import { HardwareButton } from "@/echo/hardware-button";

<HardwareButton variant="primary" onClick={save}>
  Save
</HardwareButton>
```

### Composition

```text
HardwareButton
```

### Examples

**Primary record button** — The one place hardware turns accent.

```tsx
<HardwareButton variant="primary" onClick={record}>Record</HardwareButton>
```

**Icon-only, accessible** — Always give icon-only buttons an aria-label.

```tsx
<HardwareButton iconOnly aria-label="Play" icon={<PlayIcon />} />
```

**Loading** — Loading disables interaction and shows the dot pulse.

```tsx
<HardwareButton loading>Saving</HardwareButton>
```

### Accessibility

- A native `<button>`, or an `<a>` when `href` is set, so focus, Enter and Space work as they always do.
- Space and Enter give the same press travel and sound as a pointer.
- `iconOnly` has no visible text: give it an `aria-label`.
- `loading` sets `aria-busy` and disables the button; the label stays in the accessibility tree underneath the dots.
- `engraved` lowers the label's contrast well below AA. Use it only where the label is not the only thing saying what the button does.

### Motion & sound

- Motion tokens: `press`, `pop`
- Reduced motion: The cap does not travel, the hover glint stops, and the loading dots hold still.
- Sound: `press` on the way down, `release` on the way up.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `id` | `string` | — | The element's id, so a <label for> or an aria-describedby can reach it. |
| `name` | `string` | — | The field's name in a form submission, and the key react-hook-form registers. |
| `disabled` | `boolean` | false |  |
| `required` | `boolean` | — |  |
| `readOnly` | `boolean` | — |  |
| `autoFocus` | `boolean` | — | Focus this control when it mounts. One per page, at most. |
| `onBlur` | `function` | — | Fired on focus loss. react-hook-form validates onTouched and onBlur with it. |
| `onFocus` | `function` | — | Fired when the control takes focus. |
| `onKeyDown` | `function` | — | Keyboard handling you own — Enter to send, Escape to clear. Runs before Echo's. |
| `onClick` | `function` | — |  |
| `type` | `string` | — | "button" (default), "submit" or "reset". |
| `form` | `string` | — | The id of the form this button submits, when it sits outside it. |
| `value` | `string` | — | Submitted with the form when this button is the one pressed. |
| `title` | `string` | — | The browser's own hover tooltip. Never the accessible name. |
| `onPointerDown` | `function` | — | Runs before Echo's own tactile handler, so the sound lands with the finger. |
| `onPointerUp` | `function` | — |  |
| `variant` | `"primary" | "neutral" | "ghost"` | "neutral" |  |
| `size` | `"sm" | "md" | "lg"` | "md" |  |
| `icon` | `ReactNode` | — | Leading icon (a ReactNode). |
| `trailingIcon` | `ReactNode` | — | Trailing icon (a ReactNode). |
| `iconOnly` | `boolean` | false | Square cap with no text, so it needs aria-label or aria-labelledby: without one it's a type error. |
| `loading` | `boolean` | false |  |
| `engraved` | `boolean` | false | Debossed label carved into the cap. Buys the carved look at a real cost: 1.13-1.87:1 on a neutral cap, ~1.05-1.3:1 on a primary one, against AA's 4.5:1. Use only where the label is not the only thing telling you what the control does. Unsupported with variant="primary", and warns in development. |
| `caption` | `string` | — |  |
| `href` | `string` | — | Renders the cap as a link (<a href>) with the same material, press and sound. Use it whenever the button navigates. |
| `target` | `string` | — | With `href`: where to open the link, e.g. "_blank". |
| `rel` | `string` | — | With `href`: the link relationship, e.g. "noopener". |

### Anti-patterns
- Never ship an icon-only button without an aria-label — there is no accessible name otherwise.
- Do not set `transform` on the cap in CSS — useTactile/GSAP owns transform; you'll fight the press.
- Do not hardcode plastic colors; the cap composes var(--echo-*) so retheming works.
- Engraved labels need contrast headroom — avoid on sm ghost buttons.

## Popover (`echo-popover`)

Base UI Popover (anchoring, focus, dismiss, a11y) skinned as an Echo panel. Same useGsapPresence bridge as Modal (summon enter, GSAP exit before unmount), sound.select on open.

*Feel:* A small glass panel anchored to its button, holding more than a tooltip can.

- Type: registry:component
- npm deps: gsap, @base-ui/react, echo-ui-core
- Install: `npx echo-ui-cli add popover`

### Usage

```tsx
import { HardwareButton } from "@/echo/hardware-button";
import { Popover } from "@/echo/popover";

<Popover trigger={<HardwareButton>Info</HardwareButton>} title="Details">
  <p>Anchored content.</p>
</Popover>
```

### Composition

```text
Popover
```

### Examples

**Basic** — A trigger with a titled panel.

```tsx
<Popover trigger={<HardwareButton>Info</HardwareButton>} title="Details">
  <p>Anchored content.</p>
</Popover>
```

### Accessibility

- Base UI Popover: the trigger is a button that toggles a dialog-like popup, named by `title`.
- Focus moves into the popup when it opens. Escape or a click outside closes it and returns focus to the trigger.
- Unlike a Tooltip it is reachable by touch and can hold interactive content.

### Motion & sound

- Motion tokens: `summon`
- Reduced motion: It fades in and out without moving.
- Sound: `select` when it opens.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `trigger` | `ReactNode` | — | What opens the popover. An element becomes the trigger itself; text is wrapped in a plain trigger. |
| `title` | `ReactNode` | — | Heading inside the popover, and its accessible name. |
| `side` | `"top" | "right" | "bottom" | "left"` | "bottom" |  |
| `align` | `"start" | "center" | "end"` | "center" |  |
| `sideOffset` | `number` | 8 |  |
| `container` | `unknown` | — | Where the popup mounts; defaults to <body>. Pass an element inside a scoped theme so the popup wears that theme, not the :root one. |

### Anti-patterns
- Do not add a CSS transition to the popup — GSAP owns its transform/opacity.
- Do not use a Popover where a Tooltip fits (hover hints) — Popover takes focus and traps dismissal.
- The package is `@base-ui/react`, not `@base-ui-components/react`.

## Tooltip (`echo-tooltip`)

Base UI Tooltip (hover/focus, delay, a11y) skinned as a compact molded chip. Same useGsapPresence bridge as Modal/Popover; no sound.

*Feel:* A quiet label that appears after a moment of hovering, and never makes a sound.

- Type: registry:component
- npm deps: gsap, @base-ui/react, echo-ui-core
- Install: `npx echo-ui-cli add tooltip`

### Usage

```tsx
import { HardwareButton } from "@/echo/hardware-button";
import { Tooltip } from "@/echo/tooltip";

<Tooltip trigger={<HardwareButton>Record</HardwareButton>}>
  Start a new take
</Tooltip>
```

### Composition

```text
Tooltip
```

### Examples

**Hint** — Wrap any focusable trigger.

```tsx
<Tooltip trigger={<HardwareButton iconOnly aria-label="Record" icon={<RecIcon />} />}>Record</Tooltip>
```

### Accessibility

- Base UI Tooltip: shown on hover after `delay` (400ms by default) and on keyboard focus; Escape hides it.
- It describes its trigger — it never replaces the trigger's own name. An icon-only button still needs its `aria-label`.
- Touch has no hover: never put the only copy of important information in a tooltip.

### Motion & sound

- Motion tokens: `summon`
- Reduced motion: It fades in and out without moving.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `trigger` | `ReactNode` | — | The element the tooltip describes. An element becomes the trigger itself, so it keeps its own role and name. |
| `side` | `"top" | "right" | "bottom" | "left"` | "top" |  |
| `sideOffset` | `number` | 8 |  |
| `delay` | `number` | 400 |  |
| `container` | `unknown` | — | Where the popup mounts; defaults to <body>. Pass an element inside a scoped theme so the popup wears that theme, not the :root one. |

### Anti-patterns
- Never put essential or interactive content in a Tooltip — it is hover/focus-transient and not reachable by touch.
- Do not add sound to tooltips; they fire constantly.
- The package is `@base-ui/react`, not `@base-ui-components/react`.

## Select (`echo-select`)

Base UI Select (typeahead, keyboard, a11y) skinned as an Echo dropdown — a molded cap trigger and a floating panel with a lit dot on the selected option. CSS fade in and out (Base UI Select cannot hold a node for a GSAP exit); sound.select on change.

*Feel:* A molded dropdown whose list unfolds from the cap.

- Type: registry:component
- npm deps: @base-ui/react, echo-ui-core
- Install: `npx echo-ui-cli add select`

### Usage

```tsx
import { Select } from "@/echo/select";

<Select
  aria-label="Session length"
  defaultValue="25"
  options={[
    { value: "25", label: "25 minutes" },
    { value: "50", label: "50 minutes" },
  ]}
/>
```

### Composition

```text
Select
```

### Examples

**Basic** — Options as {value,label}.

```tsx
<Select aria-label="Session length" defaultValue="25" options={[{ value: "25", label: "25 minutes" }, { value: "50", label: "50 minutes" }]} />
```

### Accessibility

- Base UI Select: the trigger opens a listbox. Arrow keys move, typing jumps to a matching option, Enter or Space chooses, Escape closes.
- Name it with `aria-label` or `aria-labelledby`.
- Focus returns to the trigger when the list closes.

### Motion & sound

- Motion tokens: `--echo-duration-glide`, `--echo-duration-swap`
- Reduced motion: The list appears with a short fade and does not slide.
- Sound: `select` when an option is chosen.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `id` | `string` | — | The element's id, so a <label for> or an aria-describedby can reach it. |
| `name` | `string` | — | The field's name in a form submission, and the key react-hook-form registers. |
| `disabled` | `boolean` | — |  |
| `required` | `boolean` | — |  |
| `readOnly` | `boolean` | — |  |
| `autoFocus` | `boolean` | — | Focus this control when it mounts. One per page, at most. |
| `onBlur` | `function` | — | Fired on focus loss. react-hook-form validates onTouched and onBlur with it. |
| `onFocus` | `function` | — | Fired when the control takes focus. |
| `onKeyDown` | `function` | — | Keyboard handling you own — Enter to send, Escape to clear. Runs before Echo's. |
| `options` | `object[]` | **required** | The choices. `value` is what you get back; `label` is what is shown. |
| `value` | `string` | — | Controlled value. |
| `defaultValue` | `string` | — | Uncontrolled initial value. |
| `onValueChange` | `function` | — | Fired with the newly selected value. |
| `placeholder` | `string` | "Select…" | Shown while nothing is selected. |
| `aria-label` | `string` | — | Names the trigger. This or aria-labelledby is required: leaving both out is a type error. |
| `aria-labelledby` | `string` | — | Id of the visible label, when there is one. |
| `container` | `unknown` | — | Where the list mounts; defaults to <body>. Pass an element inside a scoped theme so the list wears that theme, not the :root one. |

### Anti-patterns
- Give the Select an accessible name (aria-label or aria-labelledby).
- Do not use a Select for a handful of peer views — that is Tabs/Segmented; Select is for many options.
- The package is `@base-ui/react`, not `@base-ui-components/react`.

## Command (`echo-command`)

The command palette as a dot-matrix readout: the query line is the LcdChip's recessed screen well, in the LCD voice, with an emissive caret and a scanline wash. Base UI Autocomplete for the input, filtering and listbox semantics; Base UI Dialog for the frame, because a palette is summoned to the middle of the screen rather than anchored to anything. Cmd/Ctrl+K by default; matches on hidden keywords as well as labels.

*Feel:* A dot-matrix command line that drops over the screen: type, arrow down, Enter.

- Type: registry:component
- npm deps: @base-ui/react, echo-ui-core
- Install: `npx echo-ui-cli add command`

### Usage

```tsx
import { Command } from "@/echo/command";

<Command
  groups={[
    {
      label: "Navigate",
      items: [{ id: "docs", label: "Go to docs", run: () => openDocs() }],
    },
  ]}
/>
```

### Composition

```text
Command
```

### Examples

**A palette** — Grouped commands, each with an action. Cmd/Ctrl+K opens it.

```tsx
<Command
  groups={[
    { label: "Navigate", items: [
      { id: "docs", label: "Go to docs", hint: "G then D", run: () => router.push("/docs") },
    ] },
    { label: "Take", items: [
      { id: "rec", label: "Start recording", keywords: ["arm", "capture"], run: record },
    ] },
  ]}
/>
```

**Hidden keywords** — What people TYPE is rarely what the command is called.

```tsx
const deleteTake: CommandItem = {
  id: "delete",
  label: "Delete take",
  keywords: ["trash", "remove", "bin"],
  run: del,
};
```

**The app owns the hotkey** — shortcut={null} unbinds it; drive `open` yourself.

```tsx
<Command shortcut={null} open={open} onOpenChange={setOpen} groups={groups} />
```

### Accessibility

- Opens with ⌘K on Apple devices and Ctrl+K elsewhere. `shortcut` changes the key; `shortcut={null}` unbinds it so your app can own it.
- A modal dialog: focus moves to the search input and stays inside until it closes. Escape closes it.
- Arrow keys move through the results and Enter runs the highlighted one; the input keeps focus throughout, as a combobox should.
- A `disabled` item stays listed but cannot run.

### Motion & sound

- Motion tokens: `--echo-duration-swap`, `--echo-duration-glitch`
- Reduced motion: The palette appears in place with a short fade instead of sliding in.
- Sound: `transition` when it opens.
- Sound: `select` when an item runs.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `groups` | `object[]` | **required** | Grouped commands. Groups keep their order; items are filtered within them, and a group that empties is dropped. |
| `open` | `boolean` | — | Controlled open state. |
| `onOpenChange` | `function` | — |  |
| `shortcut` | `string` | "k" | Global hotkey, with Cmd on Apple and Ctrl elsewhere. Pass null for no binding. |
| `placeholder` | `string` | "Type a command…" |  |
| `emptyMessage` | `unknown` | **required** | Shown when nothing matches. Say what would help, not just 'no results'. |
| `onRun` | `function` | — | Fired with the item that ran, after the palette closes. |
| `container` | `unknown` | — | Where the palette mounts; defaults to <body>. Pass an element inside a scoped theme so the palette wears that theme, not the :root one. |

### Anti-patterns
- Never ship a palette as the ONLY way to reach something. It is an accelerator for people who already know the command exists; anything reachable only by typing its name is unreachable to everyone else.
- Do not put destructive commands in it without a confirm. A palette is optimised for Enter on the first highlighted row — which is exactly how someone erases their work by typing three letters and committing to muscle memory. Send those through an AlertDialog.
- Do not skip `keywords`. Users type the word for the thing, not the label you chose; a palette that only matches its own labels feels broken the first time someone searches 'trash' for 'Delete'.
- Do not render two palettes with the same shortcut on one page. Both will answer the keystroke. Pass shortcut={null} to all but one.
- Do not use it as a Select. It does not hold a value — it runs an action and forgets. If the choice should be remembered and shown, that is Select.

## Tabs (`echo-tabs`)

Base UI Tabs (roving focus, arrow-key nav, a11y) marked with the library's one "you are here": a 2px lit rail slides under the open tab, over a hairline baseline. Labels stay on the chassis. sound.select on change. Compound API.

*Feel:* Picking a tab slides a thin lit rail under its label with a soft click; the other labels stay quiet on the chassis.

- Type: registry:component
- npm deps: @base-ui/react, echo-ui-core
- Install: `npx echo-ui-cli add tabs`

### Usage

```tsx
import { Tabs } from "@/echo/tabs";

<Tabs defaultValue="meter">
  <Tabs.List aria-label="Track view">
    <Tabs.Tab value="meter">Meter</Tabs.Tab>
    <Tabs.Tab value="log">Log</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel value="meter">Levels</Tabs.Panel>
  <Tabs.Panel value="log">History</Tabs.Panel>
</Tabs>
```

### Composition

```text
Tabs
  Tabs.List
    Tabs.Tab
  Tabs.Panel
```

### Examples

**Basic** — List of tabs + matching panels.

```tsx
<Tabs defaultValue="a">
  <Tabs.List>
    <Tabs.Tab value="a">Meter</Tabs.Tab>
    <Tabs.Tab value="b">Log</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel value="a">…</Tabs.Panel>
  <Tabs.Panel value="b">…</Tabs.Panel>
</Tabs>
```

### Accessibility

- Renders the ARIA tabs pattern: `Tabs.List` is a `tablist`, each `Tabs.Tab` a `tab` with `aria-selected`, each `Tabs.Panel` a `tabpanel` labelled by its tab.
- Arrow keys move focus between tabs and wrap at the ends; Enter or Space opens the focused tab. Pass `activateOnFocus` to `Tabs.List` to open tabs as focus moves.
- Name the list: `aria-label` on `Tabs.List`, or `aria-labelledby` pointing at a visible heading.
- The open tab is marked by a lit rail and full-strength label text, not by colour alone.

### Motion & sound

- Motion tokens: `--echo-duration-sweep`, `--echo-duration-swap`
- Reduced motion: The rail jumps to the new tab instead of sliding.
- Sound: `select` when the open tab changes. Silent without a `SoundProvider`.

### Anti-patterns
- Every Tabs.Tab needs a matching Tabs.Panel with the same value.
- Do not put many tabs in a segmented control — it is for a few peer views, not navigation.

## Accordion (`echo-accordion`)

Base UI Accordion (keyboard, a11y, height measurement) skinned as molded device panels that expand. Click sound on toggle; height animates via CSS. Compound API.

*Feel:* Ruled rows that fold open under their heading with a soft tap.

- Type: registry:component
- npm deps: @base-ui/react, echo-ui-core
- Install: `npx echo-ui-cli add accordion`

### Usage

```tsx
import { Accordion } from "@/echo/accordion";

<Accordion>
  <Accordion.Item value="signal">
    <Accordion.Trigger>Signal</Accordion.Trigger>
    <Accordion.Panel>Input gain, routing and monitoring.</Accordion.Panel>
  </Accordion.Item>
</Accordion>
```

### Composition

```text
Accordion
  Accordion.Item
    Accordion.Trigger
    Accordion.Panel
```

### Examples

**Basic** — Items with a trigger and a panel each.

```tsx
<Accordion multiple={false}>
  <Accordion.Item value="a">
    <Accordion.Trigger>Signal</Accordion.Trigger>
    <Accordion.Panel>…</Accordion.Panel>
  </Accordion.Item>
</Accordion>
```

### Accessibility

- Base UI Accordion: each trigger is a button inside a heading, with `aria-expanded` and `aria-controls` pointing at its panel.
- Enter or Space opens and closes; arrow keys move between triggers.
- One panel open at a time by default; pass `multiple` to allow several.

### Motion & sound

- Motion tokens: `--echo-duration-glide`, `--echo-duration-sweep`
- Reduced motion: Panels open and close at once; the chevron turns without animating.
- Sound: `tap` when a panel opens or closes.

### Anti-patterns
- Do not animate the panel with a soft ease on pixel/LCD content inside — the panel height is glass-smooth, but LCD children stay steppy.
- The prop is `multiple` (Base UI 1.x), NOT `openMultiple` (the old RC name) — a wrong name silently falls through to the DOM and React warns. Default is multiple={false}, one panel open at a time; pass multiple to allow several.

## Switch (`echo-switch`)

Base UI Switch (role=switch, keyboard, a11y) with a hardware-toggle skin — a molded thumb sliding in a recessed track — and a click sound on toggle.

*Feel:* A hardware toggle: the thumb slides across its track with a small tap.

- Type: registry:component
- npm deps: @base-ui/react, echo-ui-core
- Install: `npx echo-ui-cli add switch`

### Usage

```tsx
import { Switch } from "@/echo/switch";

<Switch aria-label="Monitor" defaultChecked />
```

### Composition

```text
Switch
```

### Examples

**Basic** — Uncontrolled toggle.

```tsx
<Switch aria-label="Airplane mode" defaultChecked />
```

**Controlled** — Drive it from state.

```tsx
<Switch checked={on} onCheckedChange={setOn} aria-label="Power" />
```

### Accessibility

- Base UI Switch: `role="switch"` with `aria-checked`. Space toggles it.
- The track carries no text — name it with `aria-label`, or `aria-labelledby` pointing at a visible label.
- On and off differ by the thumb's position, not by colour alone.

### Motion & sound

- Motion tokens: `--echo-duration-glide`
- Reduced motion: The thumb jumps to its new side instead of sliding.
- Sound: `tap` each time it toggles.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `id` | `string` | — |  |
| `name` | `string` | — | Identifies the field when a form is submitted. |
| `disabled` | `boolean` | — |  |
| `required` | `boolean` | — |  |
| `readOnly` | `boolean` | — |  |
| `autoFocus` | `boolean` | — | Focus this control when it mounts. One per page, at most. |
| `onBlur` | `function` | — | Fired on focus loss. react-hook-form validates onTouched and onBlur with it. |
| `onFocus` | `function` | — | Fired when the control takes focus. |
| `onKeyDown` | `function` | — | Keyboard handling you own — Enter to send, Escape to clear. Runs before Echo's. |
| `checked` | `boolean` | — | Controlled state. |
| `defaultChecked` | `boolean` | — | Uncontrolled initial state. |
| `onCheckedChange` | `function` | — | Fired with the new state. The click sound plays before it, so this never has to make noise itself. |
| `aria-label` | `string` | — | The switch's name; the track carries no text. This or aria-labelledby is required: leaving both out is a type error. |
| `aria-labelledby` | `string` | — | Id of the visible label, when there is one. |

### Anti-patterns
- Always give a Switch an accessible name (aria-label or aria-labelledby) — the track has no text.
- Do not use a Switch for actions that need confirmation; it toggles immediately.

## Checkbox (`echo-checkbox`)

Base UI Checkbox (keyboard, indeterminate, a11y) with a molded box skin that fills accent and shows a check when set. Select sound on change.

*Feel:* A small molded key that latches down with a click.

- Type: registry:component
- npm deps: @base-ui/react, echo-ui-core
- Install: `npx echo-ui-cli add checkbox`

### Usage

```tsx
import { Checkbox } from "@/echo/checkbox";

<Checkbox aria-label="Loop playback" defaultChecked />
```

### Composition

```text
Checkbox
```

### Examples

**Basic** — Uncontrolled with a label.

```tsx
<label><Checkbox aria-label="Agree" /> I agree</label>
```

**Indeterminate** — Tri-state parent.

```tsx
<Checkbox indeterminate aria-label="Select all" />
```

### Accessibility

- Base UI Checkbox: `role="checkbox"` with `aria-checked`, which is `mixed` when `indeterminate`. Space toggles it.
- Name it with `aria-label` or `aria-labelledby`.
- Checked draws a check and indeterminate a dash, so the states differ by shape, not only by colour.

### Motion & sound

- Motion tokens: `--echo-duration-swap`
- Reduced motion: The mark appears without a transition.
- Sound: `select` each time it changes.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `id` | `string` | — |  |
| `name` | `string` | — | Identifies the field when a form is submitted. |
| `disabled` | `boolean` | — |  |
| `required` | `boolean` | — |  |
| `readOnly` | `boolean` | — |  |
| `autoFocus` | `boolean` | — | Focus this control when it mounts. One per page, at most. |
| `onBlur` | `function` | — | Fired on focus loss. react-hook-form validates onTouched and onBlur with it. |
| `onFocus` | `function` | — | Fired when the control takes focus. |
| `onKeyDown` | `function` | — | Keyboard handling you own — Enter to send, Escape to clear. Runs before Echo's. |
| `checked` | `boolean` | — | Controlled state. |
| `defaultChecked` | `boolean` | — | Uncontrolled initial state. |
| `indeterminate` | `boolean` | — | Mixed state — some but not all of a group is set. |
| `onCheckedChange` | `function` | — | Fired with the new state. The select sound plays before it. |
| `aria-label` | `string` | — | The box's name. This or aria-labelledby is required (a type error otherwise). Inside a <label>, point aria-labelledby at the label's text. |
| `aria-labelledby` | `string` | — | Id of the visible label, when there is one. |

### Anti-patterns
- Give every Checkbox an accessible name (a wrapping <label> or aria-label).
- Do not swap accent for other colors — accent is the one saturated fill.

## Slider (`echo-slider`)

Base UI Slider (keyboard, drag, track-press, a11y) with a recessed rail + molded knob and a scrubbing tick sound on each step — very hardware.

*Feel:* A fader in a recessed rail that ticks once for every step it crosses.

- Type: registry:component
- npm deps: @base-ui/react, echo-ui-core
- Install: `npx echo-ui-cli add slider`

### Usage

```tsx
import { Slider } from "@/echo/slider";

<Slider defaultValue={40} aria-label="Volume" />
```

### Composition

```text
Slider
```

### Examples

**Basic** — 0–100, ticks per step.

```tsx
<Slider defaultValue={40} aria-label="Volume" />
```

**Stepped** — Coarser steps tick louder in the hand.

```tsx
<Slider min={0} max={10} step={1} aria-label="Level" />
```

**Small** — For dense rows — a mixer strip, an inline setting.

```tsx
<Slider size="sm" defaultValue={30} aria-label="Send" />
```

### Accessibility

- The thumb holds a range input: arrow keys move one step, Page Up and Page Down a large step, Home and End go to the ends.
- `aria-label` or `aria-labelledby` is passed to the thumb, which is what a screen reader focuses. The rail has no text of its own.
- The value is announced by the input as it changes.

### Motion & sound

- Sound: `tap` once per step as the value changes — dragging across ten steps ticks ten times.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `id` | `string` | — | The element's id, so a <label for> or an aria-describedby can reach it. |
| `name` | `string` | — | The field's name in a form submission, and the key react-hook-form registers. |
| `disabled` | `boolean` | false |  |
| `required` | `boolean` | — |  |
| `readOnly` | `boolean` | — |  |
| `autoFocus` | `boolean` | — | Focus this control when it mounts. One per page, at most. |
| `onBlur` | `function` | — | Fired on focus loss. react-hook-form validates onTouched and onBlur with it. |
| `onFocus` | `function` | — | Fired when the control takes focus. |
| `onKeyDown` | `function` | — | Keyboard handling you own — Enter to send, Escape to clear. Runs before Echo's. |
| `min` | `number` | 0 |  |
| `max` | `number` | 100 |  |
| `step` | `number` | 1 |  |
| `value` | `number` | — | Controlled value. |
| `defaultValue` | `number` | 50 |  |
| `onValueChange` | `function` | — | Called with the new value on every step (value, eventDetails). |
| `size` | `"sm" | "md"` | "md" | md is the fader; sm is the dense-row slider (6px rail, 20px knob). |
| `aria-label` | `string` | — | The accessible name. The rail carries no text, so this or aria-labelledby is required (a type error otherwise). It lands on the thumb, which owns the hidden range input. |
| `aria-labelledby` | `string` | — | Id of a visible label, instead of aria-label. |

### Anti-patterns
- Give the slider an accessible name (aria-label) — the rail carries no text.
- Do not set a tiny step on a wide range if sound is on; the ticks turn into a buzz.

## Segmented (`echo-segmented`)

A hardware segmented selector — molded uppercase segments in a recessed well, the active one on the lit primary cap. A radiogroup value selector (roving focus, arrow-key select, select sound), distinct from Tabs which switches content panels. Composes var(--echo-*).

*Feel:* A row of molded keys where exactly one stays pressed in.

- Type: registry:component
- npm deps: @base-ui/react, echo-ui-core
- Install: `npx echo-ui-cli add segmented`

### Usage

```tsx
import { Segmented } from "@/echo/segmented";

<Segmented aria-label="Mode" options={["Focus", "Break", "Rest"]} />
```

### Composition

```text
Segmented
```

### Examples

**One segment off** — A disabled segment is skipped by the arrow keys.

```tsx
<Segmented aria-label="Output" options={["Line", { label: "Optical", disabled: true }, "Phones"]} />
```

**Basic** — Uncontrolled, first option selected.

```tsx
<Segmented aria-label="Mode" options={["Focus", "Break", "Rest"]} />
```

**Controlled** — Drive the index from state.

```tsx
<Segmented aria-label="Mode" options={modes} value={i} onValueChange={setI} />
```

### Accessibility

- A `radiogroup` of `radio` options with `aria-checked`.
- Arrow keys move the selection and follow the reading direction (right-to-left needs Base UI's `DirectionProvider`); Home and End jump to the first and last enabled segment. Disabled segments are skipped.
- Built on Base UI's RadioGroup: with no segment selected (or `value` out of range), the first enabled one still takes the tab stop.
- Name the group with `aria-label` or `aria-labelledby` — the segments' own labels do not say what they choose between.

### Motion & sound

- Motion tokens: `--echo-duration-swap`
- Reduced motion: The pressed segment changes without a transition.
- Sound: `select` when the choice changes.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `id` | `string` | — | The element's id, so a <label for> or an aria-describedby can reach it. |
| `name` | `string` | — | The field's name in a form submission, and the key react-hook-form registers. |
| `disabled` | `boolean` | — | Disables every segment. For one, see `options`. |
| `required` | `boolean` | — |  |
| `readOnly` | `boolean` | — |  |
| `autoFocus` | `boolean` | — | Focus this control when it mounts. One per page, at most. |
| `onBlur` | `function` | — | Fired on focus loss. react-hook-form validates onTouched and onBlur with it. |
| `onFocus` | `function` | — | Fired when the control takes focus. |
| `onKeyDown` | `function` | — | Keyboard handling you own — Enter to send, Escape to clear. Runs before Echo's. |
| `options` | `string | object[]` | **required** | Segment labels, in order. Short — a segment is a cap, not a sentence. Pass `{ label, disabled: true }` to switch one segment off. |
| `value` | `number` | — | Selected INDEX (controlled), not the label. |
| `defaultValue` | `number` | 0 | Selected index for the uncontrolled case. |
| `onValueChange` | `function` | — | Fired with the newly selected index. |
| `aria-label` | `string` | — | Names the radiogroup. This or aria-labelledby is required: leaving both out is a type error. |
| `aria-labelledby` | `string` | — | Id of the visible label, when there is one. |

### Anti-patterns
- Give the group an accessible name (aria-label / aria-labelledby) — the segments carry no group text.
- Use Tabs, not Segmented, when each choice reveals a different panel of content.

## Field (`echo-field`)

A text input sunk into a recessed well. The inner edge lights in the accent on focus; a mono eyebrow label and an optional machine (mono) value voice. Composes var(--echo-*).

*Feel:* A recessed well you type into; its edge lights while it has focus.

- Type: registry:component
- npm deps: @base-ui/react, echo-ui-core
- Install: `npx echo-ui-cli add field`

### Usage

```tsx
import { Field } from "@/echo/field";

<Field label="Name" placeholder="Ada Lovelace" />
```

### Composition

```text
Field
```

### Examples

**Basic** — Labelled text input.

```tsx
<Field label="Name" placeholder="Ada Lovelace" />
```

**Machine voice** — Mono value for codes/timers.

```tsx
<Field label="Session code" placeholder="000-000" mono />
```

**Controlled** — Drive it from state.

```tsx
<Field label="Query" value={q} onValueChange={setQ} />
```

**Help text and an error** — Both are linked to the input. The error shows while `error` is set; clear it when the value is fixed.

```tsx
<Field
  label="Email"
  type="email"
  autoComplete="email"
  description="We only use it to send the session link."
  error={valid ? undefined : "Enter an email address, like ada@example.com."}
  value={email}
  onValueChange={setEmail}
/>
```

### Accessibility

- `label` renders a real `<label>` tied to the input. With no visible label, pass `aria-label` or `aria-labelledby`.
- A native `<input>`; `type` passes through, so `email`, `password` and `search` keep their keyboard and autofill behaviour.
- A placeholder is not a label — it disappears as soon as someone types.
- `description` and `error` are linked with `aria-describedby`, and `error` sets `aria-invalid`, through Base UI's Field. The error is words plus a square pip, never colour alone.
- Set `autoComplete` on a field that asks for the user's own information (`email`, `name`, `current-password`), so autofill works and the purpose is machine-readable (WCAG 1.3.5).

### Motion & sound

- Motion tokens: `--echo-duration-swap`
- Reduced motion: Only the focus edge's colour fades in; nothing moves, so it stays.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `id` | `string` | — |  |
| `name` | `string` | — | Identifies the field when a form is submitted. |
| `disabled` | `boolean` | — |  |
| `required` | `boolean` | — | Marks the field required, for the browser and assistive tech. |
| `readOnly` | `boolean` | — |  |
| `autoFocus` | `boolean` | — | Focus this control when it mounts. One per page, at most. |
| `onBlur` | `function` | — | Fired on focus loss. react-hook-form validates onTouched and onBlur with it. |
| `onFocus` | `function` | — | Fired when the control takes focus. |
| `onKeyDown` | `function` | — | Keyboard handling you own — Enter to send, Escape to clear. Runs before Echo's. |
| `placeholder` | `string` | — | A hint, never a substitute for the label. |
| `autoComplete` | `string` | — | What the value is, for autofill: "email", "current-password", "one-time-code". Set it on any field asking for the user's own information (WCAG 1.3.5). |
| `inputMode` | `string` | — | Which on-screen keyboard a phone offers: "numeric", "email", "tel", … |
| `maxLength` | `number` | — |  |
| `minLength` | `number` | — |  |
| `pattern` | `string` | — | A regular expression the value must match for the field to be valid. |
| `label` | `string` | — | Visible eyebrow label; also the input's accessible name. A field needs label, aria-label or aria-labelledby: leaving all three out is a type error. |
| `value` | `string` | — | Controlled value. |
| `defaultValue` | `string` | — | Uncontrolled initial value. |
| `onValueChange` | `function` | — | Fired with the input's new string value. |
| `mono` | `boolean` | false | Render the value in the machine (mono) voice — codes, timers, serials. |
| `type` | `string` | "text" | Native input type. |
| `description` | `unknown` | — | Help text under the field, linked to the input so a screen reader reads it after the name. |
| `error` | `string` | — | What's wrong, in words. While set, the field is invalid: the message shows with a square pip, is linked to the input, and the input gets aria-invalid. Clear it when fixed. |
| `aria-label` | `string` | — | Used only when `label` is omitted; a visible label wins. |
| `aria-labelledby` | `string` | — | Used only when `label` is omitted. |
| `aria-describedby` | `string` | — | Ids of other text that describes the field, read after its own description and error. |

### Anti-patterns
- Don't show an error as a red border or colour alone. Pass `error` with words that say what to fix; that's what gets read out.
- The lit focus edge is the one accent; do not tint the well or the text with it.

## Textarea (`echo-textarea`)

Field's recessed well, multi-line and autosizing. The height is measured from the browser's own layout rather than counted from newlines, so it stays right when lines wrap and when the container resizes. Same well, same focus glow, same eyebrow label as Field.

*Feel:* A deeper well that grows with what you write, then scrolls inside itself.

- Type: registry:component
- npm deps: @base-ui/react, echo-ui-core
- Install: `npx echo-ui-cli add textarea`

### Usage

```tsx
import { Textarea } from "@/echo/textarea";

<Textarea label="Session note" placeholder="What happened in this take?" />
```

### Composition

```text
Textarea
```

### Examples

**Autosizing note** — Grows with the content; three rows to start.

```tsx
<Textarea label="Session note" placeholder="What happened in this take?" />
```

**Capped growth** — Grows to eight rows, then scrolls inside the well.

```tsx
<Textarea label="Log" mono maxRows={8} defaultValue={log} />
```

**Fixed height** — autosize={false} keeps it exactly `rows` tall.

```tsx
<Textarea label="Notes" autosize={false} rows={6} />
```

**Help text and an error** — Linked to the textarea, like Field's.

```tsx
<Textarea
  label="Session note"
  description="Kept with the take."
  error={note ? undefined : "Write a note before saving."}
  value={note}
  onValueChange={setNote}
/>
```

### Accessibility

- `label` renders a real `<label>` tied to the textarea; otherwise pass `aria-label` or `aria-labelledby`.
- `description` and `error` are linked with `aria-describedby`, and `error` sets `aria-invalid`, through Base UI's Field.
- A native `<textarea>`: every text-editing key works. Past `maxRows` it scrolls, and it is already focusable, so the scroll is reachable by keyboard.

### Motion & sound

- Motion tokens: `--echo-duration-swap`
- Reduced motion: The well's focus transition is removed.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `id` | `string` | — | The element's id, so a <label for> or an aria-describedby can reach it. |
| `name` | `string` | — | Identifies the field when a form is submitted. |
| `disabled` | `boolean` | — |  |
| `required` | `boolean` | — |  |
| `readOnly` | `boolean` | — |  |
| `autoFocus` | `boolean` | — | Focus this control when it mounts. One per page, at most. |
| `onBlur` | `function` | — | Fired on focus loss. react-hook-form validates onTouched and onBlur with it. |
| `onFocus` | `function` | — | Fired when the control takes focus. |
| `onKeyDown` | `function` | — | Keyboard handling you own — Enter to send, Escape to clear. Runs before Echo's. |
| `placeholder` | `string` | — | A hint, never a substitute for the label. |
| `autoComplete` | `string` | — | What the value is, for autofill and assistive tech — "email", "one-time-code". WCAG 1.3.5. |
| `inputMode` | `string` | — | Which on-screen keyboard a phone offers: "numeric", "email", "tel", … |
| `maxLength` | `number` | — |  |
| `minLength` | `number` | — |  |
| `pattern` | `string` | — | A regular expression the value must match for the field to be valid. |
| `label` | `string` | — | Visible eyebrow label; also the accessible name. A textarea needs label, aria-label or aria-labelledby: leaving all three out is a type error. |
| `value` | `string` | — | Controlled value. |
| `defaultValue` | `string` | — | Uncontrolled initial value. |
| `onValueChange` | `function` | — | Fired with the new string value. |
| `mono` | `boolean` | false | Machine (mono) voice — logs, patch notes, codes. |
| `autosize` | `boolean` | true | Grow to fit the content instead of scrolling. |
| `rows` | `number` | 3 | Rows shown before it grows; the fixed height when autosize is off. |
| `maxRows` | `number` | — | Stop growing here and scroll. Rows, not pixels. |
| `description` | `unknown` | — | Help text under the textarea, linked to it so a screen reader reads it after the name. |
| `error` | `string` | — | What's wrong, in words. While set, the message shows with a square pip, is linked to the textarea, and the textarea gets aria-invalid. |
| `aria-label` | `string` | — | Used only when `label` is omitted; a visible label wins. |
| `aria-labelledby` | `string` | — | Used only when `label` is omitted. |

### Anti-patterns
- Do not use a Textarea for one line of text. The taller well promises more room than the field wants, and people write to fill it. That is Field.
- Do not set a `height` on the input. Autosize writes that property every time the value changes, so anything you set is overwritten on the next keystroke — cap it with maxRows instead.
- Do not re-enable the resize grip while autosize is on. Dragging it sets an inline height the next measurement throws away, which reads as the handle being broken.
- Always pass a label. A recessed well with a placeholder looks labelled and is not — the placeholder vanishes the moment anyone types.

## Badge (`echo-badge`)

A small molded/LCD status label. neutral (plastic), accent (the lit primary cap), lcd (glowing screen text), outline. Static; consumes var(--echo-*).

*Feel:* A small molded pill, or a glowing LCD readout, stuck to whatever it describes.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add badge`

### Usage

```tsx
import { Badge } from "@/echo/badge";

<Badge>New</Badge>
```

### Composition

```text
Badge
```

### Examples

**Status** — Default neutral plastic pill.

```tsx
<Badge>New</Badge>
```

**LCD count** — Glowing screen readout.

```tsx
<Badge variant="lcd">12</Badge>
```

### Accessibility

- Plain text in a `<span>` — a screen reader reads it as part of the surrounding content, with no role of its own.
- Make the text say the whole thing (“3 new”, not a bare “3”) when the badge is read out of context.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `variant` | `"neutral" | "accent" | "lcd" | "outline"` | "neutral" |  |
| `size` | `"sm" | "md"` | "md" |  |

### Anti-patterns
- Do not use accent Badges for non-primary emphasis — accent is the one saturated color; overuse dilutes it.
- Do not hardcode colors; the badge recolors with the theme.

## Kbd (`echo-kbd`)

A molded keycap for keyboard hints — a tiny cap that never presses. Uses the <kbd> element.

*Feel:* A tiny keycap that never presses — it shows which key to reach for.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add kbd`

### Usage

```tsx
import { Kbd } from "@/echo/kbd";

<Kbd>⌘</Kbd> <Kbd>K</Kbd>
```

### Composition

```text
Kbd
```

### Examples

**Shortcut** — Show a key.

```tsx
<Kbd>⌘</Kbd> <Kbd>K</Kbd>
```

### Accessibility

- A native `<kbd>` element.
- Symbols like ⌘ and ⌥ are read inconsistently by screen readers; where it matters, say the shortcut in words nearby too.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `children` | `unknown` | **required** | The key legend — one key per cap, so ⌘ and K are two Kbds, not one. |

### Anti-patterns
- Do not use Kbd for interactive buttons — it is a label; use HardwareButton for actions.

## Divider (`echo-divider`)

A panel seam — a hairline with a faint light lip. Horizontal or vertical; role=separator.

*Feel:* The one seam in the library: a dark groove with a faint lit lip.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add divider`

### Usage

```tsx
import { Divider } from "@/echo/divider";

<Divider />
```

### Composition

```text
Divider
```

### Examples

**Horizontal** — Between stacked sections.

```tsx
<Divider />
```

**Vertical** — Between inline items (needs a flex parent).

```tsx
<Divider orientation="vertical" />
```

### Accessibility

- `role="separator"` with `aria-orientation`, so it marks a real boundary between groups.
- For a purely visual rule inside one group, use CSS instead — a separator a screen reader announces should separate something.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" | "vertical"` | "horizontal" | Sets both the seam direction and aria-orientation. |

### Anti-patterns
- Vertical dividers need a parent with a defined height (e.g. a flex row) or they collapse.

## StatTile (`echo-stat-tile`)

A recessed LCD readout: a glowing value over a machine label, seated in a dark well. Static; consumes var(--echo-*).

*Feel:* One number on an emissive screen, with its unit and what it measures engraved underneath.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add stat-tile`

### Usage

```tsx
import { StatTile } from "@/echo/stat-tile";

<StatTile value="42" unit="ms" label="Latency" />
```

### Composition

```text
StatTile
```

### Examples

**Metric** — Value + unit + label.

```tsx
<StatTile value="42" unit="ms" label="Latency" />
```

### Accessibility

- `role="group"` named by `label`, so the value, unit and label are read together as one reading.
- It does not announce changes. For a value that updates live and matters, announce significant changes separately.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `value` | `string` | **required** | The readout value. |
| `unit` | `string` | — |  |
| `glow` | `boolean` | true | Emissive accent value. Quiet the routine tiles and light the one being watched — six lit readouts side by side make the accent mean 'a number' rather than 'this one'. |
| `label` | `string` | **required** | Machine label; also the group's accessible name. |

### Anti-patterns
- Do not leave every tile glowing on a dashboard. The accent marks the one reading that matters; a row of six lit tiles marks nothing. Pass glow={false} to the rest.
- Never animate the value with a smooth ease — LCD/pixel elements move steppy (motion.glitch), not glassy.
- Always pass a label; it is the tile's accessible name.

## Chart (`echo-chart`)

StatTile's dot-matrix language applied to a series: a column per sample, cells lit from the bottom, in the same recessed screen well LcdChip and Progress use. Values quantise to whole cells by construction — steppiness is the data model, not a style. No axes, no gridlines, no tooltips, no smoothing: it is a readout, not a charting library.

*Feel:* A dot-matrix readout of recent values — a device's screen, not a charting library.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add chart`

### Usage

```tsx
import { Chart } from "@/echo/chart";

<Chart data={levels} label="Input level, last 60 seconds" />
```

### Composition

```text
Chart
```

### Examples

**Level over time** — The default bar matrix. Always name what it measures.

```tsx
<Chart data={levels} label="Input level, last 60 seconds" caption="input" />
```

**A single trace** — line lights only the value's cell per column.

```tsx
<Chart data={temps} variant="line" rows={9} label="Core temperature" />
```

**Fixed scale** — Pass max so the matrix does not rescale as data arrives.

```tsx
<Chart data={percent} min={0} max={100} label="Buffer fill" />
```

### Accessibility

- One `role="img"` named by `label` and a summary: how many samples, the range, and the last value.
- Pass `summary` to say what the shape means (“rising steadily”); the default only states the numbers.
- When the numbers themselves matter, put them in a Table as well — a picture of data is not the data.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `data` | `number[]` | **required** | The series, oldest first. Empty renders an unlit matrix. |
| `label` | `string` | **required** | What is being measured. Required — it is the accessible name, and a chart nobody can read is a decorative rectangle. |
| `variant` | `"bar" | "line"` | "bar" | bar lights from the bottom up; line lights only the value's cell. |
| `rows` | `number` | 7 | Matrix height in cells. More cells is finer, not smoother. |
| `max` | `number` | — | Scale ceiling. Defaults to the largest value present. |
| `min` | `number` | 0 | Scale floor. |
| `summary` | `string` | — | Replaces the generated accessible description. |
| `caption` | `string` | — | Machine label under the matrix. |

### Anti-patterns
- Do not use this when the values matter more than the shape. It quantises to whole cells, so a reader can see a trend and cannot read a number — put the number in an LcdChip or a StatTile beside it.
- Never omit `label`. Without it the matrix is an unnamed image, and the entire series is invisible to anyone not looking at the screen.
- Do not let the scale float when new samples arrive. Without `max`, the ceiling is the largest value present, so the whole chart rescales the moment a peak lands and the history appears to shrink — pass a fixed max for anything live.
- Do not reach for this when you need axes, hit-testing or tooltips. It is a device readout; a real chart is a different job and a different library.
- Do not animate the cells between values. A screen readout does not ease smoothly — it steps, which is why the quantisation lives in the data rather than in the CSS.

## AppShell (`echo-app-shell`)

The app frame: a molded chassis rail lit from the key angle, a sticky sidebar, and the content between them. Slots, not props — the shell owns the layout, you own the contents. Ships the skip link by construction rather than as an option, and derives the sidebar's sticky offset from the rail's height so the two cannot drift. Below 900px the sidebar column is removed rather than stacked; pair it with a Sheet.

*Feel:* The chassis the whole app sits in: a top rail, a lit sidebar, and a screen for the content.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add app-shell`

### Usage

```tsx
import { AppShell } from "@/echo/app-shell";

<AppShell>
  <AppShell.Rail brand={<Wordmark />}>
    <a href="/docs">Docs</a>
  </AppShell.Rail>
  <AppShell.Sidebar label="Components">{nav}</AppShell.Sidebar>
  <AppShell.Content>{children}</AppShell.Content>
</AppShell>
```

### Composition

```text
AppShell
  AppShell.Rail
  AppShell.Sidebar
  AppShell.Content
```

### Examples

**The frame** — Rail, sidebar, content. The skip link comes with it.

```tsx
<AppShell>
  <AppShell.Rail brand={<Wordmark />}>
    <a href="/docs">Docs</a>
  </AppShell.Rail>
  <AppShell.Sidebar label="Components">{nav}</AppShell.Sidebar>
  <AppShell.Content>{children}</AppShell.Content>
</AppShell>
```

**No sidebar** — For a screen that is all content.

```tsx
<AppShell bare>
  <AppShell.Rail brand={<Wordmark />} />
  <AppShell.Content>{children}</AppShell.Content>
</AppShell>
```

**Retuned metrics** — Both are custom properties, and the sidebar offset follows the rail.

```tsx
<AppShell
  style={{ "--echo-shell-rail-h": "64px", "--echo-shell-side-w": "280px" } as React.CSSProperties}
>
  …
</AppShell>
```

### Accessibility

- Real landmarks: the rail is a `<header>` with a `<nav>`, the sidebar a `<nav>` named by `label`, the content a `<main>`.
- A skip link to the content comes first on every page. It is not optional.
- `embedded` (for a shell shown inside another page) drops the skip link and turns the landmarks into plain elements, because a page gets one `<main>`.
- Put `aria-current="page"` on the link to the current page; the shell draws the lit rail from it, so the mark and the announcement cannot disagree.
- Focus is scrolled clear of the rail rather than under it (WCAG 2.4.11), from `scroll-margin-block-start` derived from `--echo-shell-rail-h` — so retuning the rail moves the offset with it. If you nest an `overflow` container inside Content, pad the document scrollport too: WebKit does not carry an element’s scroll-margin out through a nested scrollport.

### Motion & sound

- Motion tokens: `--echo-duration-swap`
- Reduced motion: Only colour changes on hover and selection; nothing moves.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `bare` | `boolean` | false | Drop the sidebar column — for screens that are all content, where an empty rail is a margin pretending to be navigation. |
| `embedded` | `boolean` | false | This shell is INSIDE another one (a preview, an embedded editor frame). Drops the skip link and demotes the landmarks — a page gets one <main>. Never set it on the shell that owns the page. |
| `Rail.brand` | `unknown` | **required** | The wordmark end: a logo, a product name, a home link. |
| `Rail.label` | `string` | "Main" | Landmark name for the rail's nav. |
| `Sidebar.label` | `string` | **required** | Landmark name. Required — 'navigation' twice on one page tells a screen-reader user nothing. |

### Anti-patterns
- Do not stack the sidebar above the content on a phone. It pushes every screen down by half a viewport and turns the nav into something you scroll past; below 900px the column is removed and the same list belongs in a Sheet behind a rail toggle.
- Never give the rail nav and the sidebar the same landmark name. Two navs called 'navigation' are two identical doors to a screen-reader user.
- Do not set the sidebar's sticky offset by hand. It is derived from --echo-shell-rail-h; hardcoding it leaves a dead band at the top of every sidebar the day the rail's height changes.
- Do not put page content in the Rail. It is sticky and it is a landmark — anything that scrolls away belongs in Content.
- Do not nest a shell inside another without `embedded`. AppShell.Content IS the page's <main>, and a second one is an axe violation — which is how the docs site's own preview of this component failed the suite.

## Panel (`echo-panel`)

The two halves of the device material law as a container: raised molded plastic (things you touch) or a recessed dark screen (things you read). Consumes var(--echo-*).

*Feel:* Either raised molded plastic you can set things on, or a recessed dark screen you look into.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add panel`

### Usage

```tsx
import { Panel } from "@/echo/panel";

<Panel>Settings</Panel>
```

### Composition

```text
Panel
```

### Examples

**Card** — Raised plastic card.

```tsx
<Panel>Settings</Panel>
```

**Screen** — Recessed LCD well for readouts.

```tsx
<Panel variant="screen"><StatTile value="42" label="Latency" /></Panel>
```

### Accessibility

- A plain `<div>` with no role — it groups visually, not semantically. Give it a heading inside, or a landmark around it, when the grouping matters to a screen reader.
- `variant="screen"` is a dark ground: its content must use the text roles, which are contrast-checked against it.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `variant` | `"raised" | "screen"` | "raised" | raised = molded plastic card; screen = recessed dark LCD well. |

### Anti-patterns
- Never put raised controls directly on another raised Panel without a well — plastic sits in recesses, not on plateaus.
- Never give the screen variant a light background; the LCD field is always dark, whatever the seed.

## Progress (`echo-progress`)

A discrete LED cell meter in a recessed strip — filled cells are lit accent LEDs with a bloom. Steppy by construction; consumes var(--echo-*).

*Feel:* A segmented meter that fills cell by cell, like an LED bar graph.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add progress`

### Usage

```tsx
import { Progress } from "@/echo/progress";

<Progress value={0.65} aria-label="Upload progress" />
```

### Composition

```text
Progress
```

### Examples

**Upload meter** — Value is a 0..1 fraction.

```tsx
<Progress value={0.65} aria-label="Upload progress" />
```

### Accessibility

- `role="progressbar"` with `aria-valuenow` from 0 to 100; `value` is a fraction from 0 to 1.
- Name it with `aria-label` — the cells carry no text.
- It does not announce each change. For a long task, say when it finishes somewhere that does (a Toast or a live Banner).

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `value` | `number` | 0.5 | Fraction filled, 0..1. |
| `cells` | `number` | 14 | Number of LED cells. |
| `aria-label` | `string` | — | What is filling up ("Upload", "Battery"). This or aria-labelledby is required: leaving both out is a type error. |
| `aria-labelledby` | `string` | — | Id of a visible label, instead of aria-label. |

### Anti-patterns
- Never tween the fill smoothly — LEDs snap on cell by cell (steppy motion), they don't slide.
- Never use it as a slider; it is read-only output. For input, use Slider.

## Loader (`echo-loader`)

Three accent LEDs breathing in sequence — the device thinking. role=status; reduced motion holds the dots steady. Consumes var(--echo-*).

*Feel:* Three dots pulsing in turn — the device is thinking.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add loader`

### Usage

```tsx
import { Loader } from "@/echo/loader";

<Loader label="Saving" />
```

### Composition

```text
Loader
```

### Examples

**Default** — Inline loading indicator.

```tsx
<Loader />
```

**Small** — Fits inside a button or chip.

```tsx
<Loader dot={6} label="Saving" />
```

### Accessibility

- `role="status"` named by `label`, so it is announced when it appears.
- Remove it as soon as the work is done — it is announced when it appears, and a loader left on screen says the wait is still going.

### Motion & sound

- Reduced motion: The dots stop pulsing and hold at a steady glow.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `dot` | `number` | 9 | Dot diameter in px. |
| `label` | `string` | "Loading" | Accessible status text. |

### Anti-patterns
- Never spin it — Echo has no spinners; the device pulses, it doesn't rotate.
- Never stack Loader with skeletons in the same region; pick one loading voice per surface.

## StatusDot (`echo-status-dot`)

A tiny LED socket, filled and blooming or hollow and dead. State is carried by fill-vs-hollow and by a 5.25:1 luminance step, not by hue, so it survives protan/deuteran/tritan and greyscale. Requires `label` or `decorative`. Consumes var(--echo-*).

*Feel:* A tiny LED: lit, or dead.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add status-dot`

### Usage

```tsx
import { StatusDot } from "@/echo/status-dot";

<StatusDot on={false} label="Offline" />
```

### Composition

```text
StatusDot
```

### Examples

**With text** — Adjacent text carries the state, so say so.

```tsx
<StatusDot on decorative /> Recording
```

**Standalone** — The dot is the only signal.

```tsx
<StatusDot on={false} label="Offline" />
```

### Accessibility

- With `label`, it is `role="img"` named by the label — use that when the dot is the only signal.
- With `decorative`, it is hidden from assistive technology — use that when the text next to it already says the state.
- One of the two is required; an unlabelled dot warns in development.
- On and off differ by shape and brightness, not only by colour.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `on` | `boolean` | true | Filled, lit socket vs dead, hollow one. |
| `label` | `string` | — | Accessible name for the state (e.g. "Online"). Required unless `decorative` is set. |
| `decorative` | `boolean` | — | Adjacent visible text already states the state, so the dot is hidden from assistive tech. Exactly one of `label` or `decorative` is required — a dot that has neither signals nothing to anybody. |

### Anti-patterns
- Never encode more than on/off — an LED has two states; for tones use Badge.
- Never leave a dot with neither `label` nor `decorative` — that is a state signalled to nobody.
- Never restore hue as the only state difference; the fill/hollow step is what survives colour-vision deficiency.

## Toast (`echo-toast`)

A raised glass notification slab with a status LED, and the toaster that announces it. Mount <Toaster> once around the app and call toast() from useToast(): the toaster's live region is on the page before anything is said, so every toast is announced. Built on Base UI's Toast. Consumes var(--echo-*).

*Feel:* A glass slab with a status LED that confirms, quietly, that something happened.

- Type: registry:component
- npm deps: @base-ui/react, echo-ui-core
- Install: `npx echo-ui-cli add toast`

### Usage

```tsx
import { Toaster, useToast } from "@/echo/toast";

// Once, around the app:
function App({ children }: { children: React.ReactNode }) {
  return <Toaster>{children}</Toaster>;
}

// Anywhere inside it:
function SaveButton() {
  const toast = useToast();
  return <button onClick={() => toast({ title: "Saved" })}>Save</button>;
}
```

### Composition

```text
Toaster → toasts from useToast()
```

### Examples

**Announce something** — Mount the toaster once, then raise toasts from anywhere inside it.

```tsx
function SaveButton() {
  const toast = useToast();
  return <HardwareButton onClick={() => toast({ title: "Saved", body: "Draft stored locally" })}>Save</HardwareButton>;
}

<Toaster>
  <SaveButton />
</Toaster>
```

**Something is live** — `active` lights the LED, for an event that is happening.

```tsx
toast({ title: "Recording", tone: "active", timeout: 0 })
```

**The slab alone** — For showing one on a page. It announces nothing.

```tsx
<Toast title="Saved" body="Draft stored locally" />
```

### Accessibility

- The toaster is a live region named “Notifications”, on the page before any toast, so each toast is announced when it arrives. A status created together with its text often isn't, which is why the slab alone announces nothing.
- Toasts are polite by default. `priority: "high"` interrupts; keep it for what can't wait.
- Each toast has a “Dismiss notification” button. Toasts stay 6 seconds by default; for anything people must act on, use `timeout: 0` or don't use a toast.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `title` | `string` | **required** | Headline of the notification. |
| `body` | `string` | — | Secondary line. |
| `tone` | `"info" | "active"` | "info" | Echo's one status vocabulary, the subset a toast slab can express. active lights the LED accent — for something happening, not decoration. info is the plain slab. |

### Anti-patterns
- Don't mount a second toaster for each screen; one around the app announces everything.
- Never put the only copy of something important in a toast. It leaves; give people a way to find it again.
- Never keep an `active` toast on screen after the event ends; the LED means live, not important.

## LcdChip (`echo-lcd-chip`)

An inline recessed LCD readout: a glowing accent value next to a machine label, sunk into a dark well. The chip form of StatTile — use it inline in a row of controls; use StatTile when the readout is a dashboard cell.

*Feel:* A small emissive screen set into the panel, reading one value.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add lcd-chip`

### Usage

```tsx
import { LcdChip } from "@/echo/lcd-chip";

<LcdChip value="07:42" label="Uptime" />
```

### Composition

```text
LcdChip
```

### Examples

**Readout** — Glowing value with a machine label.

```tsx
<LcdChip value="07:42" label="Uptime" />
```

**Unlit** — Cream text — for a value that is present but not live.

```tsx
<LcdChip value="--" label="Signal" glow={false} />
```

**In a well** — Chips read as one instrument cluster inside a screen Panel.

```tsx
<Panel variant="screen"><LcdChip value="128" label="BPM" /><LcdChip value="A♯" label="Key" /></Panel>
```

### Accessibility

- `role="group"` named by `label`, so the value is read with what it is.
- The screen face is tabular: digits keep their width as the value changes.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `value` | `string` | **required** | The readout — digits, a duration, a count. |
| `label` | `string` | **required** | Machine label beside the value; also the accessible name. |
| `glow` | `boolean` | true | Emissive accent value. false renders plain cream text. |

### Anti-patterns
- Never put an LcdChip on a raised surface without a well — an emissive readout floating on plastic breaks the material law; nest it in a Panel variant="screen" or the chassis.
- Never animate the value with a smooth ease — screens step. Use motion.glitch or swap the text outright; glass moves smooth, pixels move steppy.
- Never pass a long sentence as value — the LCD face is tabular digits and short codes, not prose.

## LedKey (`echo-led-key`)

A molded pill key with an indicator LED that breathes while lit. The latching sibling of HardwareButton: use it when the key's own state is part of the answer (armed, monitoring, recording), not for a command that fires and forgets.

*Feel:* A molded key with an indicator LED that breathes while it is lit.

- Type: registry:component
- npm deps: gsap, echo-ui-core
- Install: `npx echo-ui-cli add led-key`

### Usage

```tsx
import { LedKey } from "@/echo/led-key";

<LedKey lit={armed} aria-pressed={armed} onClick={() => setArmed(!armed)}>
  Arm
</LedKey>
```

### Composition

```text
LedKey
```

### Examples

**Latching key** — A key that toggles its own state says so with aria-pressed — the LED is then the visual half of the same fact.

```tsx
<LedKey lit={armed} aria-pressed={armed} onClick={() => setArmed(!armed)}>Arm</LedKey>
```

**Reporting something else** — When the LED reports what the device is doing rather than the key's own state, litLabel is what carries it to a screen reader.

```tsx
<LedKey lit={recording} litLabel="Recording">Rec</LedKey>
```

**Idle** — Unlit is dead plastic — the same two-state LED as StatusDot.

```tsx
<LedKey>Snooze +5</LedKey>
```

**A row of keys** — Keys read as one transport when they share a well row.

```tsx
<div style={{ display: "flex", gap: 12 }}><LedKey lit litLabel="Recording">Rec</LedKey><LedKey>Play</LedKey></div>
```

### Accessibility

- A native `<button>`: Enter and Space press it, with the same travel and sound as a pointer.
- For an on/off key, pass `aria-pressed` alongside `lit` so the state is announced.
- `litLabel` adds visually hidden text for what the lit LED means (“Recording”) — the LED alone is only colour.

### Motion & sound

- Motion tokens: `press`, `pop`
- Reduced motion: The key does not travel, and the lit LED stops breathing and holds steady.
- Sound: `press` on the way down, `release` on the way up.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `id` | `string` | — | The element's id, so a <label for> or an aria-describedby can reach it. |
| `name` | `string` | — | The field's name in a form submission, and the key react-hook-form registers. |
| `disabled` | `boolean` | — |  |
| `required` | `boolean` | — |  |
| `readOnly` | `boolean` | — |  |
| `autoFocus` | `boolean` | — | Focus this control when it mounts. One per page, at most. |
| `onBlur` | `function` | — | Fired on focus loss. react-hook-form validates onTouched and onBlur with it. |
| `onFocus` | `function` | — | Fired when the control takes focus. |
| `onKeyDown` | `function` | — | Keyboard handling you own — Enter to send, Escape to clear. Runs before Echo's. |
| `onClick` | `function` | — |  |
| `type` | `string` | — | "button" (default), "submit" or "reset". |
| `form` | `string` | — | The id of the form this button submits, when it sits outside it. |
| `value` | `string` | — | Submitted with the form when this button is the one pressed. |
| `title` | `string` | — | The browser's own hover tooltip. Never the accessible name. |
| `onPointerDown` | `function` | — | Runs before Echo's own tactile handler, so the sound lands with the finger. |
| `onPointerUp` | `function` | — |  |
| `children` | `string` | **required** | The key's legend — machine-cased in the skin. |
| `lit` | `boolean` | false | Light the LED and breathe it. False is dead plastic. |
| `litLabel` | `string` | — | What the lit LED means, announced as visually hidden text. For a key that toggles its own state, use aria-pressed instead. |

### Anti-patterns
- Never let the LED be the only carrier of state — pass litLabel (or aria-pressed when the key toggles itself) so the lit key announces what it means; a colour is not a message.
- Never pass both aria-pressed and litLabel — one says the key is on, the other says the device is; using both leaves a screen reader with two answers to one question.
- Never use LedKey for a fire-and-forget command (Save, Send, Delete). An LED promises a state that persists after the press; HardwareButton is the cap for actions.
- Never render more than one lit key to mean one exclusive choice — that is a Segmented or a RadioGroup, which say so structurally.

## EngravedPlate (`echo-engraved-plate`)

A paper-coloured metal plate with text cut into it and rivets at the edges — the one non-emissive readout in the library. Use it for a fact fixed to the device (a serial, a balance, a rating); use LcdChip for a value that updates while you watch.

*Feel:* A riveted metal nameplate with the words cut into it.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add engraved-plate`

### Usage

```tsx
import { EngravedPlate } from "@/echo/engraved-plate";

<EngravedPlate>Model 002</EngravedPlate>
```

### Composition

```text
EngravedPlate
```

### Examples

**Plate** — Debossed machine text on paper-coloured metal.

```tsx
<EngravedPlate>Owed 4</EngravedPlate>
```

**Screwed on off-true** — A few degrees of tilt reads as a real part, not a label.

```tsx
<EngravedPlate tilt={-5}>Model 002</EngravedPlate>
```

**Flush** — Without rivets the plate reads as inlaid rather than bolted.

```tsx
<EngravedPlate rivets={false}>Serial 4417</EngravedPlate>
```

### Accessibility

- Plain text; the rivets are `aria-hidden`.
- Engraving lowers contrast on purpose. Use it for names and labels that are also said elsewhere, not for the only copy of something someone needs to read.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `children` | `string` | **required** | The engraving. Short — a plate is stamped, not written on. |
| `tilt` | `number` | 0 | Rotation in degrees, as if screwed on slightly off-true. |
| `rivets` | `boolean` | true | Rivets at the plate's short edges. |

### Anti-patterns
- Never animate the text or swap it on a timer — a plate is stamped once. A value that changes belongs on an LcdChip or a StatTile.
- Never put a sentence on it. The engraving is a few machine-cased words; longer copy on paper-coloured metal reads as a sticky note.
- Never override the text colour with your own hex — the engraving is var(--echo-accent-pressed) precisely so it stays legible on paper after a reseed.

## Textures (`echo-textures`)

The grain law as composable overlays: Dither (ordered Bayer), Noise (film grain), Halftone, Scanlines, plus GrainField (the brand surface) and Textured (the default stack). Nothing in Echo is ever a flat fill — and a dither or grain pass is the cure for the banding that large soft gradients show on the dark chassis. All tiles are generated as inline SVG data-URIs, so there are no asset files to copy. Every overlay is aria-hidden and pointer-events: none.

*Feel:* Print and screen grain — dither, noise, halftone, scanlines — laid over a surface so it reads as a made object.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add textures`

### Usage

```tsx
import { Panel } from "@/echo/panel";
import { Textured } from "@/echo/textures";

<Textured>
  <Panel>Settings</Panel>
</Textured>
```

### Composition

```text
Textured
Dither
Noise
Halftone
Scanlines
GrainField
```

### Examples

**De-band a gradient** — The overlay fills the nearest positioned ancestor, so give it one.

```tsx
<div style={{ position: "relative" }}><Hero /><Dither opacity={0.18} /></div>
```

**Product whisper** — A panel gets grain, not a full treatment.

```tsx
<Textured dither={false}><Panel>Settings</Panel></Textured>
```

**Brand field** — The marketing surface; blooms in whatever the seed accent is.

```tsx
<GrainField tone="accent" style={{ minHeight: 320 }}><h1>Echo UI</h1></GrainField>
```

**Screen register** — Scanlines over a screen Panel, never over plastic.

```tsx
<Panel variant="screen"><Readout /><Scanlines gap={3} /></Panel>
```

### Accessibility

- Every overlay is decorative: `aria-hidden` and `pointer-events: none`, so it never reaches the accessibility tree or catches a click.
- Texture sits over content at low opacity. Check that text under it still meets contrast — the theme's guarantee is for the roles, not for what you lay on top of them.

### Motion & sound

- Reduced motion: Nothing moves: every texture is static.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `dither` | `boolean` | — | Textured only: include the dither layer. Default true. |
| `noise` | `boolean` | — | Textured only: include the noise layer. Default true. |
| `opacity` | `number` | — | Layer opacity; each texture ships its usual weight. |
| `blend` | `string` | — | CSS mix-blend-mode against the surface below (overlay, soft-light, multiply). |
| `fixed` | `boolean` | false | Pin to the viewport instead of the positioned ancestor. |
| `tone` | `"dark" | "light"` | — | Dither only — dark ink deepens the surface, light ink lifts it. |
| `scale` | `number` | — | Dither only — tile scale multiplier; 1 = a 16px tile. |
| `grain` | `"fine" | "coarse"` | — | Noise only — fine for surfaces, coarse for fields. |
| `size` | `number` | — | Noise only — tile size in px; larger reads softer. |
| `cell` | `number` | — | Halftone only — dot pitch in px. |
| `gap` | `number` | — | Scanlines only — line pitch in px. |

### Anti-patterns
- Never stack every texture at once — one structural texture (dither OR halftone) plus grain is the ceiling; more reads as a filter, not a material.
- Never put Scanlines or Halftone on a raised plastic surface — those are screen and print registers; plastic gets Noise.
- Never raise Noise above ~0.08 on a product surface; the loud grain (0.3+) belongs to GrainField and marketing only.
- Never give an overlay a positioned ancestor it does not have — an absolutely-filling texture with no relative parent escapes to the page. Textured and GrainField provide their own; bare overlays do not.
- Never animate a texture's opacity to signal state — texture is material, not feedback. Use StatusDot or Progress.

## ShaderField (`echo-shader-field`)

The live brand field: a WebGL domain-warped fbm gradient sampled from the accent ramp, blooming toward the cursor, with animated grain and TPDF debanding. Reads the accent ramp from the CSS it sits in (or from a pinned theme mirror), so it relights with the seed like every other surface. Reduced motion draws one static frame; no WebGL falls back to the wrapper's CSS gradient; the GL context is released on unmount.

*Feel:* A slow, glowing field in the accent colour that leans toward the cursor — ambient, never busy.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add shader-field`

### Usage

```tsx
import { ShaderField } from "@/echo/shader-field";

<div style={{ height: 420 }}>
  <ShaderField />
</div>
```

### Composition

```text
ShaderField
```

### Examples

**Hero background** — Decorative by default — give the wrapper a size.

```tsx
<div style={{ height: 420 }}><ShaderField /></div>
```

**Themed** — Pass a seeded theme mirror and the field follows the accent.

```tsx
const theme = createEchoTheme({ accent: "#2AA9A0" }).values;
<ShaderField theme={theme} />
```

### Accessibility

- Decorative by default (`aria-hidden`). Pass `label` only when the field carries meaning, and it becomes `role="img"` with that name.
- Without WebGL it draws a CSS gradient instead, so the space it occupies never goes blank.

### Motion & sound

- Reduced motion: It draws one still frame and stops: no animation loop, no cursor tracking.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `theme` | `unknown` | — | EchoTheme mirror (createEchoTheme().values) that pins the field colours. Omit it and the field follows the --echo-accent-* variables in scope, re-reading them when the page is reseeded. |
| `label` | `string` | — | Accessible name. Omit and the field is decorative (aria-hidden) — right for a background. |

### Anti-patterns
- Never put readable body text directly on the field — it moves and its contrast is not guaranteed. Put text on a Panel over it, or use GrainField, which carries an edge-darkening pass for exactly this.
- Never mount more than one or two ShaderFields on a page — each holds a live WebGL context and a rAF loop; browsers cap contexts, and a grid of them will drop frames on integrated GPUs.
- Never give it a `label` unless it genuinely carries meaning; a named background is noise in the a11y tree.
- Never reach for it as a page background behind an app — it is the marketing field. Product surfaces are the chassis plus a whisper of Noise.

## RadioGroup (`echo-radio-group`)

One choice from a small set: each option is a recessed hole beside its label, and the chosen one lights a pip inside its hole. Base UI owns roving focus, arrow-key selection, and form semantics; Echo owns the material. Compound API: RadioGroup with RadioGroup.Item children.

*Feel:* A row of pips, one lit — like the mode lamps on a front panel.

- Type: registry:component
- npm deps: @base-ui/react, echo-ui-core
- Install: `npx echo-ui-cli add radio-group`

### Usage

```tsx
import { RadioGroup } from "@/echo/radio-group";

<RadioGroup defaultValue="meter" aria-label="Panel mode">
  <RadioGroup.Item value="meter">Meter</RadioGroup.Item>
  <RadioGroup.Item value="log">Log</RadioGroup.Item>
</RadioGroup>
```

### Composition

```text
RadioGroup
  RadioGroup.Item
```

### Examples

**Pick a mode** — The group needs an accessible name; each item names itself.

```tsx
<RadioGroup defaultValue="meter" aria-label="Panel mode">
  <RadioGroup.Item value="meter">Meter</RadioGroup.Item>
  <RadioGroup.Item value="log">Log</RadioGroup.Item>
</RadioGroup>
```

**Stacked** — Vertical when the labels are long or the list is more than three.

```tsx
<RadioGroup orientation="vertical" defaultValue="a" aria-label="Output">…</RadioGroup>
```

### Accessibility

- Base UI RadioGroup: a `radiogroup` of `radio` items, each labelled by its own text.
- Tab enters the group at the checked item; arrow keys move the selection.
- Name the group with `aria-label` or `aria-labelledby`.

### Motion & sound

- Motion tokens: `--echo-duration-swap`
- Reduced motion: The pip lights without a transition.
- Sound: `select` when the choice changes.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `id` | `string` | — | The element's id, so a <label for> or an aria-describedby can reach it. |
| `name` | `string` | — | Identifies the field when a form is submitted. |
| `disabled` | `boolean` | false |  |
| `required` | `boolean` | — |  |
| `readOnly` | `boolean` | — |  |
| `autoFocus` | `boolean` | — | Focus this control when it mounts. One per page, at most. |
| `onBlur` | `function` | — | Fired on focus loss. react-hook-form validates onTouched and onBlur with it. |
| `onFocus` | `function` | — | Fired when the control takes focus. |
| `onKeyDown` | `function` | — | Keyboard handling you own — Enter to send, Escape to clear. Runs before Echo's. |
| `value` | `string` | — | Controlled selected value. |
| `defaultValue` | `string` | — | Uncontrolled initial value. |
| `onValueChange` | `function` | — | Fired with the newly selected value. |
| `orientation` | `"horizontal" | "vertical"` | "horizontal" | Lay the options out in a row or a stack. |

### Anti-patterns
- Never use a RadioGroup for two mutually exclusive states that are really on/off — that is a Switch. Radios are for three or more genuine alternatives.
- Never leave the group unnamed: pass aria-label or aria-labelledby to the group itself. Naming only the items tells a screen-reader user what the options are but never what the question was.
- Never wrap RadioGroup.Item in a <label> — the item already renders the role=radio button and takes its accessible name from its own children; a wrapping label associates with nothing and adds a second hit target that does not select.
- Never use it where only one option can ever be valid — a radio group that cannot be changed is a readout, so use an LcdChip or StatTile.

## OTP field (`echo-otp-field`)

The one-time code a sign-in asks for, as a row of lit digit windows — the Field's recessed well cut into six screens, in the LCD voice. Built on Base UI's OTP Field: a pasted code fills the row, arrow keys and Backspace walk it, and the phone can offer the code from an SMS. Composes var(--echo-*).

*Feel:* Six lit windows; a pasted code drops into them one character at a time.

- Type: registry:component
- npm deps: @base-ui/react, echo-ui-core
- Install: `npx echo-ui-cli add otp-field`

### Usage

```tsx
import { OtpField } from "@/echo/otp-field";

<OtpField label="Verification code" onComplete={submit} />
```

### Composition

```text
OtpField
```

### Examples

**Six digits** — The default.

```tsx
<OtpField label="Verification code" onComplete={submit} />
```

**Four digits** — Any length.

```tsx
<OtpField label="PIN" length={4} onComplete={unlock} />
```

**Wrong code** — `error` marks the group invalid and says what to do.

```tsx
<OtpField label="Verification code" value={code} onValueChange={setCode} error={wrong ? "That code has expired. Ask for a new one." : undefined} />
```

### Accessibility

- One labelled group, not six unlabelled boxes: the visible `label` names the whole row, and each window says which digit it is.
- `autocomplete="one-time-code"` is on by construction, so a phone offers the code from an SMS and password managers fill it (WCAG 3.3.8).
- Pasting the whole code fills the row — nobody has to retype it digit by digit.
- `description` and `error` are linked to the group with `aria-describedby`; `error` marks it invalid. The error is words plus a square pip, never colour alone.

### Motion & sound

- Motion tokens: `--echo-duration-swap`
- Reduced motion: Only the focus edge fades; nothing moves, so it stays.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `id` | `string` | — | The element's id, so a <label for> or an aria-describedby can reach it. |
| `name` | `string` | — | Identifies the code when a form is submitted. |
| `disabled` | `boolean` | — |  |
| `required` | `boolean` | — |  |
| `readOnly` | `boolean` | — |  |
| `autoFocus` | `boolean` | — | Focus this control when it mounts. One per page, at most. |
| `onBlur` | `function` | — | Fired on focus loss. react-hook-form validates onTouched and onBlur with it. |
| `onFocus` | `function` | — | Fired when the control takes focus. |
| `onKeyDown` | `function` | — | Keyboard handling you own — Enter to send, Escape to clear. Runs before Echo's. |
| `placeholder` | `string` | — | The greyed hint shown while the field is empty. Never a substitute for a label. |
| `autoComplete` | `string` | — | What the value is, for autofill and assistive tech — "email", "one-time-code". WCAG 1.3.5. |
| `inputMode` | `string` | — | Which on-screen keyboard a phone offers: "numeric", "email", "tel", … |
| `maxLength` | `number` | — |  |
| `minLength` | `number` | — |  |
| `pattern` | `string` | — | A regular expression the value must match for the field to be valid. |
| `label` | `string` | — | Visible eyebrow label; also the group's accessible name. An OTP field needs label, aria-label or aria-labelledby: leaving all three out is a type error. |
| `length` | `number` | 6 | How many digit windows. |
| `value` | `string` | — | Controlled value — the whole code, not one digit. |
| `defaultValue` | `string` | — | Uncontrolled initial code. |
| `onValueChange` | `function` | — | Fired with the code so far. |
| `onComplete` | `function` | — | Fired when the last window is filled. Where a sign-in screen submits. |
| `mask` | `boolean` | false | Hide the characters. For a secret, not for a one-time code. |
| `description` | `unknown` | — | Help text under the row, linked to the group. |
| `error` | `string` | — | What's wrong, in words. While set, the group is invalid and the message shows with a square pip. |
| `aria-label` | `string` | — | Used only when `label` is omitted; a visible label wins. |
| `aria-labelledby` | `string` | — | Used only when `label` is omitted. |

### Anti-patterns
- Don't use it for a password or anything long: it's for a short code, one character per window.
- Don't block pasting — it is how most people enter a code they were just sent.

## NumberField (`echo-number-field`)

A machined readout between two molded step caps — and the label above it is a scrub handle you drag left and right to dial the value. Base UI owns typing, arrow keys, alt/shift step sizes, clamping, and form semantics. Scrubbing is what makes this worth wrapping instead of using a plain number input.

*Feel:* A readout with two molded steppers; drag the label sideways to scrub it like a knob.

- Type: registry:component
- npm deps: @base-ui/react, echo-ui-core
- Install: `npx echo-ui-cli add number-field`

### Usage

```tsx
import { NumberField } from "@/echo/number-field";

<NumberField label="Tempo" defaultValue={120} min={40} max={240} />
```

### Composition

```text
NumberField
```

### Examples

**Bounded setting** — Label names the value; min/max clamp every interaction path.

```tsx
<NumberField label="Tempo" defaultValue={120} min={40} max={240} />
```

**Fine control** — Alt steps by smallStep, shift by largeStep — no extra props needed.

```tsx
<NumberField label="Gain" defaultValue={0} min={-24} max={24} step={1} smallStep={0.1} />
```

**Controlled** — value can be null while the input is mid-edit or empty.

```tsx
<NumberField label="Count" value={count} onValueChange={(v) => setCount(v ?? 0)} />
```

### Accessibility

- `label` names the input. The − and + steppers have their own labels.
- Arrow Up and Down change the value by `step`; with Shift by `largeStep`, with Alt by `smallStep`.
- Scrubbing by dragging the label is a pointer extra — everything it does is also possible from the keyboard.

### Motion & sound

- Motion tokens: `--echo-duration-press`
- Reduced motion: The steppers no longer move when pressed.
- Sound: `tap` once per whole step, however the value changed.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `id` | `string` | — | The element's id, so a <label for> or an aria-describedby can reach it. |
| `name` | `string` | — | The field's name in a form submission, and the key react-hook-form registers. |
| `disabled` | `boolean` | false |  |
| `required` | `boolean` | — |  |
| `readOnly` | `boolean` | false |  |
| `autoFocus` | `boolean` | — | Focus this control when it mounts. One per page, at most. |
| `onBlur` | `function` | — | Fired on focus loss. react-hook-form validates onTouched and onBlur with it. |
| `onFocus` | `function` | — | Fired when the control takes focus. |
| `onKeyDown` | `function` | — | Keyboard handling you own — Enter to send, Escape to clear. Runs before Echo's. |
| `placeholder` | `string` | — | The greyed hint shown while the field is empty. Never a substitute for a label. |
| `autoComplete` | `string` | — | What the value is, for autofill and assistive tech — "email", "one-time-code". WCAG 1.3.5. |
| `inputMode` | `string` | — | Which on-screen keyboard a phone offers: "numeric", "email", "tel", … |
| `maxLength` | `number` | — |  |
| `minLength` | `number` | — |  |
| `pattern` | `string` | — | A regular expression the value must match for the field to be valid. |
| `label` | `string` | **required** | Visible label, the scrub handle, and the input's accessible name. |
| `value` | `number` | — | Controlled value. |
| `defaultValue` | `number` | — | Uncontrolled initial value. |
| `onValueChange` | `function` | — | Called with the new value — which is null while the field is empty mid-edit, so do not assume a number. |
| `min` | `number` | — |  |
| `max` | `number` | — |  |
| `step` | `number` | 1 | Step for the caps, arrow keys, and scrubbing. |
| `largeStep` | `number` | 10 | Step while holding shift. |
| `smallStep` | `number` | 0.1 | Step while holding alt. |
| `decrementLabel` | `string` | "Decrease" | Accessible name for the − cap. |
| `incrementLabel` | `string` | "Increase" | Accessible name for the + cap. |

### Anti-patterns
- Never treat the value as always-numeric in a controlled setup — Base UI reports null while the input is empty or mid-edit. Coalesce it; do not render NaN into the readout.
- Never use this for a bounded value the user should feel out rather than name — that is a Slider. NumberField is for values worth typing exactly.
- Never remove the label: it is the input's accessible name AND the scrub handle. Without it the field is both unnamed and undraggable.
- Never hand the step caps to a screen reader unnamed. They ship as − and +, which read as punctuation; the decrementLabel and incrementLabel props exist so they announce as actions.

## Avatar (`echo-avatar`)

A person or device as a molded disc — the image seated in a well, or initials engraved into the plastic when there is no image or the image fails to load. The failure case is the whole point: a bare <img> with a broken URL leaves a hole, this falls back.

*Feel:* A round inset portrait, or initials on molded plastic, with an optional presence LED.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add avatar`

### Usage

```tsx
import { Avatar } from "@/echo/avatar";

<Avatar src="/ada.jpg" name="Ada Lovelace" />
```

### Composition

```text
Avatar
```

### Examples

**With an image** — name still required — it is the accessible name and the fallback source.

```tsx
<Avatar src="/ada.jpg" name="Ada Lovelace" />
```

**Initials only** — Derived from the first and last words.

```tsx
<Avatar name="Ada Lovelace" size="lg" />
```

**Presence** — A lit LED in the rim. Fill-vs-hollow carries the state, so it never rests on colour.

```tsx
<Avatar name="Ada Lovelace" status="live" />
```

**Device** — Override initials when the name is not a person.

```tsx
<Avatar name="Echo One, studio unit" initials="E1" />
```

### Accessibility

- `role="img"` named by `name` — with the status added (“Ada Lovelace, online”) when `status` is set.
- The image and initials inside are `aria-hidden`, so the name is read once.
- Presence is shown filled or hollow, not only by colour.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `src` | `string` | — | Image URL. Omit to render initials. |
| `name` | `string` | **required** | Who or what this is; also the accessible name. |
| `size` | `"sm" | "md" | "lg"` | "md" |  |
| `initials` | `string` | — | Override the derived initials, e.g. a device code. |
| `status` | `"live" | "idle"` | — | Presence LED in the rim: live is lit, idle is an empty socket. Appended to the accessible name. |
| `statusLabel` | `string` | — | Override the words announced for status. |

### Anti-patterns
- Never omit name to make it decorative — an avatar identifies someone, and an unnamed one is a hole in the a11y tree. If it is truly decorative, do not render an avatar.
- Never put the name in an adjacent <img alt> as well; the inner image is alt="" on purpose so the wrapper's label is announced once, not twice.
- Never use status for anything but presence. A lit LED on a person means they are there — not that they are selected, an admin, or new.
- Never stack avatars into an overlapping row without giving the group its own label and count — a pile of individually-named discs reads as noise.

## Tag (`echo-tag`)

A label the user applied — a category, a person, a filter — optionally removable. Distinct from Badge, which reports state the system knows. The material says which is which: a Badge is printed onto the chassis, a Tag is a small plate that can be peeled off.

*Feel:* A small applied label; the removable kind has its own tiny key.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add tag`

### Usage

```tsx
import { Tag } from "@/echo/tag";

<Tag onRemove={() => drop("Ambient")}>
  Ambient
</Tag>
```

### Composition

```text
Tag
```

### Examples

**Static** — A plain applied label.

```tsx
<Tag>Ambient</Tag>
```

**Removable** — Name the control per tag so a row of them is navigable.

```tsx
<Tag onRemove={() => drop("Ambient")}>Ambient</Tag>
```

### Accessibility

- With `onRemove`, the × is a real button named after the tag (“Remove Ambient”), so a row of tags doesn't read as a row of identical “Remove” buttons. Pass `removeLabel` when the tag's content isn't text.
- After a removal, move focus somewhere sensible — the next tag, or the input that adds tags.

### Motion & sound

- Motion tokens: `--echo-duration-tick`
- Reduced motion: The remove key no longer moves when pressed.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `children` | `string` | **required** | The label text. |
| `onRemove` | `function` | — | Render a remove control. Omit for a static tag. |
| `removeLabel` | `string` | — | Accessible name for the remove control. Defaults to "Remove" plus the tag's text ("Remove Loop"); pass one when the content isn't text. |

### Anti-patterns
- Never use a Tag for system state — status, counts, and severity are Badge. A tag that the user cannot have applied is a badge wearing the wrong material.
- Never give a tag with non-text content (an icon, an avatar) a remove control without `removeLabel`. It falls back to "Remove", and five of those are indistinguishable in a screen reader's element list.
- Never make the whole tag clickable for removal — a body that deletes on click has no safe place to press, and the tag stops being selectable text.

## CountBadge (`echo-count-badge`)

A number worth noticing — the lit sibling of Badge. Badge names a state; CountBadge counts a thing. It disappears at zero unless told otherwise, caps its face at max while still announcing the true count, and stays round at one digit.

*Feel:* A small counter pinned to a corner, capped so it never outgrows its spot.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add count-badge`

### Usage

```tsx
import { CountBadge } from "@/echo/count-badge";

<CountBadge count={7} label="unread messages" />
```

### Composition

```text
CountBadge
```

### Examples

**Unread count** — Announces as "7 unread messages".

```tsx
<CountBadge count={7} label="unread messages" />
```

**Capped** — Reads "127 unread messages" while showing "99+".

```tsx
<CountBadge count={127} label="unread messages" />
```

**On a control** — Anchor it yourself; the badge does not position itself.

```tsx
<span style={{ position: "relative" }}>
  <HardwareButton iconOnly aria-label="Inbox" icon={<Inbox />} />
  <CountBadge count={3} label="unread messages" />
</span>
```

### Accessibility

- `role="status"`, named by the real count and `label` (“127 unread messages”) even when the face shows “99+”.
- Being a status region, a change is announced politely.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `count` | `number` | **required** | The number itself. |
| `label` | `string` | **required** | What is counted, e.g. "unread messages". The name becomes "3 unread messages". |
| `max` | `number` | 99 | Cap the display; above it renders as `${max}+`. |
| `showZero` | `boolean` | false | Render at zero instead of returning null. |
| `variant` | `"accent" | "neutral"` | "accent" | A colour choice, not a status — which is why it is a variant and not a tone. |

### Anti-patterns
- Never pass a bare number as the label. "3" on its own is meaningless in a screen reader's element list — the label is what the number counts, not the number again.
- Never use it for a state with no quantity — an on/off or severity marker is a Badge or a StatusDot. A count of one is still a count; a count of "error" is not.
- Never render it at zero by default. A badge that says 0 draws the eye to nothing happening; that is what showZero is for, and it is rarely the right call.
- Never raise max to show a huge exact number in the face — a five-digit badge breaks the pill and the round-at-one-digit geometry. Cap it and let the accessible name carry the truth.

## Skeleton (`echo-skeleton`)

The shape of content that has not arrived: a recess in the chassis with a slow sheen crossing it. Every skeleton is aria-hidden by default — the wait is announced once, by the region that owns it, via the label prop. Reduced motion holds the sheen still rather than looping forever.

*Feel:* The shape of what is coming, with a slow sheen passing over it.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add skeleton`

### Usage

```tsx
import { Skeleton } from "@/echo/skeleton";

<Skeleton lines={3} label="Loading article" />
```

### Composition

```text
Skeleton
```

### Examples

**A paragraph** — The last line renders short, the way real text ends.

```tsx
<Skeleton lines={3} label="Loading article" />
```

**A media block** — Match the real element's box so nothing jumps on arrival.

```tsx
<Skeleton variant="block" height={180} />
```

**An avatar row** — One label on the region; the rest stay silent.

```tsx
<div role="status" aria-busy aria-label="Loading people">
  <Skeleton variant="circle" height={36} />
  <Skeleton width={140} />
</div>
```

### Accessibility

- With `label`, it is `role="status"` with `aria-busy`, and announces what is loading.
- Without a label its shapes are `aria-hidden`: use that when something else already says the region is loading.

### Motion & sound

- Reduced motion: The sheen stops; the shapes hold at a steady tone.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `variant` | `"text" | "block" | "circle"` | "text" |  |
| `width` | `string | number` | — | CSS width; numbers are px. |
| `height` | `string | number` | — | CSS height; numbers are px. |
| `lines` | `number` | 1 | Text lines; the last renders short. |
| `label` | `string` | — | Announce the wait. Pass ONCE per loading region, on the outermost skeleton. |

### Anti-patterns
- Never label every skeleton. A dozen boxes each announcing "Loading" is unusable; one busy region owns the wait and the rest are decoration.
- Never let a skeleton outlive its request. A skeleton that never resolves reads as a broken layout, not as pending — show an EmptyState or a Banner when the fetch fails.
- Never draw a skeleton in a shape the real content will not take. The entire value is that nothing moves when the data lands; a wrong-sized placeholder is worse than a spinner.
- Never use a skeleton for an action's progress — that is Loader or Progress. Skeletons stand in for CONTENT, not for work.

## Banner (`echo-banner`)

A persistent inline message strip. Toast is transient and reports what just happened; Banner stays and describes a condition still true. Built as a piece of the device: a molded strip, a status LED in a recessed well, and an LCD tag that names the tone. Severity is carried by the LED's shape and the tag's words rather than by red/amber/green — Echo has one accent, and inventing hues the seed does not own would break on a reseed.

*Feel:* A molded strip with an LED in a recessed well and an LCD tag that names the tone.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add banner`

### Usage

```tsx
import { Banner } from "@/echo/banner";

<Banner title="Offline mode" tone="warn">
  Changes sync when the device reconnects.
</Banner>
```

### Composition

```text
Banner
```

### Examples

**Standing condition** — Rendered with the page — ordinary content, no live region.

```tsx
<Banner title="Offline mode" tone="warn">Changes sync when the device reconnects.</Banner>
```

**Appeared in response** — live makes danger an alert and everything else a polite status.

```tsx
<Banner live tone="danger" title="Upload failed" onDismiss={retry}>The file exceeds the size limit.</Banner>
```

### Accessibility

- Silent by default. `live` makes it a live region: `role="alert"` for `tone="danger"`, `role="status"` for the rest.
- Only set `live` on a banner that appears in response to something; one that is on the page from the start should not announce.
- The tone is spelled out in the LCD tag (Info, Live, Warn, Error), not carried by colour alone.
- With `onDismiss`, a close button appears, named “Dismiss” plus the title (“Dismiss Offline mode”) unless you pass `dismissLabel`.

### Motion & sound

- Motion tokens: `--echo-duration-tick`
- Reduced motion: The dismiss button's hover change is instant.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `title` | `string` | **required** | The condition, stated plainly. |
| `children` | `string` | — | Supporting detail. |
| `tone` | `"info" | "active" | "warn" | "danger"` | "info" | Echo's one status vocabulary: info, active (happening now), warn, danger. |
| `icon` | `string` | — | Leading icon. Decorative — the title carries meaning. |
| `tag` | `string | false` | — | The LCD tag on the right. Defaults to the tone in words; false hides it. |
| `onDismiss` | `function` | — | Render a dismiss control. |
| `dismissLabel` | `string` | — | Name of the dismiss button. Defaults to "Dismiss" plus the title. |
| `live` | `boolean` | false | Announce when the banner appears dynamically. danger becomes an alert. |

### Anti-patterns
- Never set live on a banner that renders with the page. Announcing it on load interrupts the reader for something they were going to reach anyway; live is for banners that APPEAR.
- Never use a Banner for something that just happened and is already over — that is a Toast. A banner describes a condition that is still true.
- Never rely on tone alone to convey severity. The strip reads as "more urgent" by luminance, which is not a message; say the severity in the title.
- Never stack more than one or two banners. Three standing conditions at once means the screen has a structural problem that a fourth banner will not fix.

## EmptyState (`echo-empty-state`)

Nothing here, and what to do about it. Rendered as a quiet recess: the screen is on and working, there is simply nothing in it yet. The action slot is part of the API on purpose — an empty state without a way forward is a dead end.

*Feel:* A dark, quiet screen that says what will appear here, and how to make it appear.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add empty-state`

### Usage

```tsx
import { EmptyState } from "@/echo/empty-state";
import { HardwareButton } from "@/echo/hardware-button";

<EmptyState
  title="No recordings yet"
  description="Anything you capture on this device shows up here."
  action={<HardwareButton variant="primary">Start recording</HardwareButton>}
/>
```

### Composition

```text
EmptyState
```

### Examples

**First run** — Name the thing and offer the one action that fixes it.

```tsx
<EmptyState
  title="No recordings yet"
  description="Anything you capture on this device shows up here."
  action={<HardwareButton variant="primary">Start recording</HardwareButton>}
/>
```

**Filtered to nothing** — The way forward is undoing the filter, not creating data.

```tsx
<EmptyState title="No matches" description="No takes match this tag." action={<HardwareButton>Clear filters</HardwareButton>} />
```

### Accessibility

- The title is a paragraph, not a heading. If the empty region should be reachable by heading navigation, put it under one of your own.
- `icon` is decorative and `aria-hidden`; the title and description carry the meaning.
- When the state appears after an action (a search with no results), announce it — for example with a Toast — since focus stays where it was.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `title` | `string` | **required** | What is not here, stated plainly. |
| `description` | `string` | — | Why, or what to expect. |
| `icon` | `string` | — | Decorative mark above the title. |
| `action` | `string` | — | The way forward — usually one HardwareButton. |

### Anti-patterns
- Never ship an empty state with no action. If there is genuinely nothing the user can do, say why in the description — an unexplained blank reads as a bug.
- Never use it for a failure. A request that errored is a Banner with a retry; an empty state means the query worked and the answer was nothing.
- Never write the title as an apology ("Oops, nothing here!"). Say what is not there; the user is not owed a mood.
- Never use it while data is still loading — that is Skeleton. Showing "nothing here" before the fetch resolves tells the user something false.

## Table (`echo-table`)

Rows of data in a recessed screen well. A real <table> with a real <caption>, compound parts for head/body/row/cell, tabular figures for numeric cells, and a scroll container that is a labelled, focusable region so a wide table stays reachable by keyboard.

*Feel:* A readout ruled into rows — the numbers line up, the rules stay quiet.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add table`

### Usage

```tsx
import { Table } from "@/echo/table";

<Table caption="Recent takes">
  <Table.Head>
    <Table.Row>
      <Table.HeaderCell>Take</Table.HeaderCell>
      <Table.HeaderCell align="end">Length</Table.HeaderCell>
    </Table.Row>
  </Table.Head>
  <Table.Body>
    <Table.Row>
      <Table.Cell>Room tone</Table.Cell>
      <Table.Cell numeric>02:41</Table.Cell>
    </Table.Row>
  </Table.Body>
</Table>
```

### Composition

```text
Table
  Table.Head
    Table.Row
      Table.HeaderCell
  Table.Body
    Table.Row
      Table.HeaderCell
      Table.Cell
```

### Examples

**A readout** — Numeric cells align to the end (the right, in left-to-right text) and use tabular figures.

```tsx
<Table caption="Recent takes">
  <Table.Head>
    <Table.Row>
      <Table.HeaderCell>Take</Table.HeaderCell>
      <Table.HeaderCell align="end">Length</Table.HeaderCell>
    </Table.Row>
  </Table.Head>
  <Table.Body>
    <Table.Row>
      <Table.Cell>Room tone</Table.Cell>
      <Table.Cell numeric>02:41</Table.Cell>
    </Table.Row>
  </Table.Body>
</Table>
```

**Row headers** — scope="row" makes the leading cell a label for its row.

```tsx
<Table.HeaderCell scope="row">Input 1</Table.HeaderCell>
```

**Caption carried by the surrounding heading** — Hide it visually; it still names the table and its scroll region.

```tsx
<Table caption="Recent takes" hideCaption>…</Table>
```

### Accessibility

- A real `<table>` with a required `caption`. `hideCaption` hides it visually but keeps it as the table's name.
- The table sits in a scroll region named by the caption and reachable by Tab, so a wide table can be scrolled from the keyboard.
- Use `scope="row"` on a leading `HeaderCell` so each row is announced by its label.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `caption` | `string` | **required** | What the table is. Required; names both the table and its scroll region. |
| `hideCaption` | `boolean` | false | Hide the caption visually. It still names the table. |
| `striped` | `boolean` | false | Faint bands on alternate rows. For wide tables; the rules already separate rows. |

### Anti-patterns
- Never use a table for layout. These are real table semantics, and a screen reader will announce rows and columns for something that has neither.
- Never drop the caption to save space — use hideCaption. An uncaptioned table is an unlabelled grid of numbers to anyone not looking at it, and its scroll region loses its name too.
- Never remove the tabIndex from the scroll container. An overflow region that cannot take focus is unreachable by keyboard; a mouse hides the bug completely.
- Never mix numeric and text cells in one column and set numeric on only some — the column stops aligning, which is the entire reason to mark numbers at all.

## Breadcrumb (`echo-breadcrumb`)

Where you are in the hierarchy, as an engraved trail. A labelled nav around an ordered list; the last item is the current page, so it is not a link and carries aria-current. Separators are hidden from assistive tech — the list structure is the real separator.

*Feel:* A trail of engraved labels back up the hierarchy.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add breadcrumb`

### Usage

```tsx
import { Breadcrumb } from "@/echo/breadcrumb";

<Breadcrumb
  items={[
    { label: "Home", href: "/" },
    { label: "Device", href: "/device" },
    { label: "Settings" },
  ]}
/>
```

### Composition

```text
Breadcrumb
```

### Examples

**A path** — Root first; the last entry needs no href.

```tsx
<Breadcrumb items={[
  { label: "Home", href: "/" },
  { label: "Device", href: "/device" },
  { label: "Settings" },
]} />
```

**Custom separator** — Purely visual; it never reaches the a11y tree.

```tsx
<Breadcrumb separator="›" items={items} />
```

### Accessibility

- A `<nav>` named “Breadcrumb” around an ordered list, so position is announced (“2 of 3”).
- The last item is the current page: plain text with `aria-current="page"`, not a link.
- Separators are `aria-hidden`; the list carries the structure.

### Motion & sound

- Motion tokens: `--echo-duration-tick`
- Reduced motion: Link hover changes colour without a transition.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `items` | `object[]` | **required** | The trail, root first. The last item is the current page and needs no href. |
| `label` | `string` | "Breadcrumb" | Name for the nav landmark. |
| `separator` | `string` | "/" | Separator glyph. Decorative. |

### Anti-patterns
- Never link the last item to the current page. A link back to where you already are is a dead control, which is why the last entry renders as text with aria-current.
- Never use a breadcrumb for steps in a flow — a trail describes WHERE you are in a hierarchy, not HOW FAR you are through a sequence. That is Steps.
- Never truncate the middle of the trail with a bare ellipsis span. If a path is too long, collapse it into a control that can actually expand it; a dead ellipsis loses the path with no way back.
- Never rely on the separator to convey structure — it is aria-hidden, and it should be. The ordered list carries the meaning.

## Pagination (`echo-pagination`)

A row of molded number caps with the current page lit, inside a labelled nav. The window keeps the first and last page always reachable, never elides a single page behind a gap, and never changes width as you page through — a control that reflows under the cursor is how you misclick. The arithmetic is exported as paginationRange if you need it elsewhere.

*Feel:* A row of small keys; the current page is the one pressed in.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add pagination`

### Usage

```tsx
import { Pagination } from "@/echo/pagination";

<Pagination page={page} count={20} onPageChange={setPage} />
```

### Composition

```text
Pagination
```

### Examples

**Controlled** — The component owns no state; page is yours.

```tsx
<Pagination page={page} count={20} onPageChange={setPage} />
```

**Wider window** — More context either side of the current page.

```tsx
<Pagination page={page} count={120} siblings={2} onPageChange={setPage} />
```

**Named for its list** — Two paginations on one screen need distinguishable landmarks.

```tsx
<Pagination label="Takes pagination" page={page} count={9} onPageChange={setPage} />
```

### Accessibility

- A `<nav>` named by `label`. Two paginations on one page need different labels.
- Each page button is named “Page 3”, not “3”; the current one carries `aria-current="page"`.
- Previous and next are named “Previous page” and “Next page” (`previousLabel`, `nextLabel`) and are disabled at the ends. Gaps are `aria-hidden`.

### Motion & sound

- Motion tokens: `--echo-duration-press`
- Reduced motion: Keys no longer move when pressed.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `page` | `number` | **required** | 1-based current page. |
| `count` | `number` | **required** | Total number of pages. |
| `onPageChange` | `function` | **required** | Called with the requested page. |
| `siblings` | `number` | 1 | Pages shown either side of the current one. |
| `label` | `string` | "Pagination" | Name for the nav landmark. |
| `previousLabel` | `string` | "Previous page" |  |
| `nextLabel` | `string` | "Next page" |  |

### Anti-patterns
- Never render pagination for a list that fits on one page — count of 1 is a control that does nothing. Guard on count > 1 at the call site.
- Never label the page buttons with the bare number. They carry aria-label="Page 3" for a reason: a screen reader's element list full of "1 2 3" names nothing.
- Never make the ellipsis a control. It is aria-hidden here because announcing "ellipsis" between two numbers is noise, and a gap that expands on click is a different component.
- Never use it for infinite or unknown-length data. Pagination promises a last page; if you cannot name count, you want a load-more control instead.

## Steps (`echo-steps`)

How far through a sequence you are, as LED stations wired together: done stations stay lit but dim, the current one blooms, upcoming ones are dead plastic. An ordered list inside a labelled group, with aria-current on the current station and the done state stated in text — a colour is not a message.

*Feel:* Stations along a lit wire — how far you are through a sequence.

- Type: registry:component
- npm deps: echo-ui-core
- Install: `npx echo-ui-cli add steps`

### Usage

```tsx
import { Steps } from "@/echo/steps";

<Steps label="Setup" current={1} steps={["Connect", "Calibrate", "Done"]} />
```

### Composition

```text
Steps
```

### Examples

**Setup flow** — current is a 0-based index, so 1 means the second station.

```tsx
<Steps label="Setup" current={1} steps={["Connect", "Calibrate", "Done"]} />
```

**Finished** — Past the end marks every station complete.

```tsx
<Steps label="Setup" current={3} steps={["Connect", "Calibrate", "Done"]} />
```

### Accessibility

- A group named by `label` around an ordered list; the current station has `aria-current="step"`.
- Finished stations say so in text (`completeLabel`, “completed” by default), not only with a lit pip.
- Stations are not interactive; Steps shows progress, it does not navigate.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `steps` | `string[]` | **required** | Station labels, in order. |
| `current` | `number` | **required** | 0-based index of the current step. |
| `label` | `string` | **required** | Name for the group, e.g. "Setup". Required. |
| `completeLabel` | `string` | "completed" | Word appended for screen readers on finished steps. |

### Anti-patterns
- Never use Steps for navigation between arbitrary sections — it promises a sequence with a direction. Somewhere you can move around freely is Tabs.
- Never let the lit pip be the only signal that a step is done. It is why completeLabel exists: the state reaches a screen reader as words, not as a colour.
- Never render more than about five stations in a row — the labels collapse and the wire stops reading as progress. Long sequences want a count ("Step 3 of 12") instead.
- Never make the stations clickable without also handling the case where a later step is not yet reachable; a station that looks navigable and silently does nothing is worse than a plain indicator.

## Auth screen (`echo-auth`)

Sign-in and its 2FA step as a front panel: a nameplate, recessed wells to type into, one lit cap to commit. Proves the first-press moment — two fields and a button is the smallest screen where a component library either has a feel or does not. No backend: onSubmit hands you the credentials, onVerify the code.

*Feel:* The first press: two wells, one lit cap, and a panel that answers.

- Type: registry:block
- npm deps: echo-ui-core
- registry deps: @echo/echo-field, @echo/echo-otp-field, @echo/echo-hardware-button, @echo/echo-checkbox, @echo/echo-banner, @echo/echo-engraved-plate, @echo/echo-status-dot
- Install: `npx echo-ui-cli add auth`

### Usage

```tsx
import { AuthScreen } from "@/echo/auth";

<main>
  <AuthScreen
    onSubmit={async ({ email, password }) => {
      await signIn(email, password);
    }}
  />
</main>
```

### Composition

```text
AuthScreen
  EngravedPlate
  Field
  Checkbox
  HardwareButton
  Banner
```

### Examples

**Straight through** — Resolve and the screen is done; throw and the banner explains why.

```tsx
<AuthScreen
  onSubmit={async ({ email, password }) => {
    const res = await signIn(email, password);
    if (!res.ok) throw new Error("That email and password do not match.");
  }}
/>
```

**With a second factor** — Return "2fa" and the same panel becomes the code step.

```tsx
<AuthScreen
  onSubmit={async (c) => ((await signIn(c)).needsCode ? "2fa" : "done")}
  onVerify={(code) => verify(code)}
/>
```

### Accessibility

- A real `<form>`: Enter submits from any field. Fields have visible labels and `autoComplete` values (`email`, `current-password`, `one-time-code`), so autofill and password managers work.
- A failed sign-in shows a `live` danger Banner — announced as an alert because it appears in response to the press.
- The screen owns the page's `<h1>`. Inside another page, pass `embedded` and the title drops to `<h2>`.
- It renders no `<main>` of its own: put it inside your page's `<main>`, or the page has no main landmark.

### Motion & sound

- Sound: From its parts: `press` / `release` on the submit cap, `select` on the checkbox.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `embedded` | `boolean` | false | This screen is inside another page: it gives up the page's <h1> (the title drops to <h2>). Never set it on the screen that owns the page. |
| `product` | `string` | "ECHO ONE" | Name engraved on the plate. |
| `onSubmit` | `function` | — | Called with { email, password, trustDevice }. Return "2fa" to advance to the code step; throw to show the error banner with your message. |
| `onVerify` | `function` | — | Called with the six-digit code. |
| `forgotHref` | `string` | "#" | Where the forgot-password link goes. |

### Anti-patterns
- Do not embed this screen in another page without `embedded`. It owns the page's <h1>, so a preview or a marketing page that renders it ends up with two first-level headings, and a screen-reader user's outline of the page stops making sense.
- Never reveal which half was wrong. "That email and password do not match" is one message for both, because "no account with that email" tells an attacker which addresses are registered.
- Do not disable the submit cap until the form looks valid. It removes the press — the one thing this screen exists to demonstrate — and it hides the error until people have guessed what the form wants. Let them press and answer them.
- Do not put the 2FA code in a Field with type="number". Codes have leading zeros, and a number input eats them.
- Do not autofocus the email field on a page a person may have arrived at by scrolling. Stealing focus scrolls the screen out from under them.

## Settings screen (`echo-settings`)

The entire control set at rest — Switch, Slider, Select, RadioGroup, Segmented, Field, Textarea, NumberField, Checkbox, Toast — laid out as labelled rows. Proves two things one component page cannot: that the radii, densities and type scale cohere across fifteen controls, and that the sound design survives someone touching all of them in a row.

*Feel:* Fifteen controls at rest on one panel, all speaking the same material — touch them all in a row and it still sounds like one device.

- Type: registry:block
- npm deps: echo-ui-core
- registry deps: @echo/echo-switch, @echo/echo-slider, @echo/echo-select, @echo/echo-radio-group, @echo/echo-segmented, @echo/echo-field, @echo/echo-textarea, @echo/echo-number-field, @echo/echo-checkbox, @echo/echo-hardware-button, @echo/echo-toast, @echo/echo-divider, @echo/echo-kbd
- Install: `npx echo-ui-cli add settings`

### Usage

```tsx
import { SettingsScreen } from "@/echo/settings";

<main>
  <SettingsScreen onSave={(settings) => savePreferences(settings)} />
</main>
```

### Composition

```text
SettingsScreen
  Switch
  Slider
  Select
  RadioGroup
  Segmented
  Field
  Textarea
  NumberField
  Checkbox
  HardwareButton
  Toast
```

### Examples

**Persist on save** — The screen owns the form state; you get the whole object.

```tsx
<SettingsScreen onSave={(settings) => savePreferences(settings)} />
```

### Accessibility

- Each section is a `<section>` named by its heading; each row names its control from the row's label.
- Saving shows a Toast, which is already a polite status region — the screen does not wrap it in another.
- The screen owns the page's `<h1>`. Inside another page, pass `embedded` and every heading drops a level.
- It renders no `<main>` of its own: put it inside your page's `<main>`, or the page has no main landmark.

### Motion & sound

- Sound: From its parts — every control plays its own. Saving is batched behind one Save press, so the sounds never pile up.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `embedded` | `boolean` | false | This screen is inside another page: the title drops to <h2> and the section headings drop with it, so the outline stays contiguous. |
| `onSave` | `function` | — | Called with the whole settings object when Save is pressed. |

### Anti-patterns
- Do not wrap the Toast in your own aria-live region. It is already role="status"; nesting live regions is how one save gets announced twice. The container around it is for position only.
- Do not embed this screen in another page without `embedded`. It owns the page's <h1>, so a preview or a marketing page that renders it ends up with two first-level headings, and a screen-reader user's outline of the page stops making sense.
- Do not end-align controls under their own labels on a phone. The two-column row becomes two rows below 640px, and a full-width Field pushed right under its own label reads as a layout bug.
- Do not save on every change AND show a toast for each one. Twelve controls means twelve toasts and twelve sounds; batch behind an explicit Save, or save silently and say so once.
- Do not stretch every control to the same width. A Switch stretched to 19rem is a Switch with an 18rem hit target that does nothing — size by content and align the end edge instead.
- Do not use this screen's Row for a control that needs its label INSIDE it (NumberField, Field with its own eyebrow). Two labels for one control is two names in the accessibility tree.

## Console screen (`echo-console`)

A device dashboard as a front panel: AppShell, six StatTile readouts, an LED level matrix in a Panel, status lights, a takes Table and Pagination. Proves density and data at scale — whether the material language still holds when nothing on the screen has room.

*Feel:* A dense front panel: six readouts, a meter, a channel list — and the material still holds when nothing has room.

- Type: registry:block
- npm deps: echo-ui-core
- registry deps: @echo/echo-app-shell, @echo/echo-panel, @echo/echo-table, @echo/echo-stat-tile, @echo/echo-lcd-chip, @echo/echo-status-dot, @echo/echo-chart, @echo/echo-badge, @echo/echo-menu, @echo/echo-segmented, @echo/echo-engraved-plate, @echo/echo-pagination
- Install: `npx echo-ui-cli add console`

### Usage

```tsx
import { ConsoleScreen } from "@/echo/console";

<ConsoleScreen product="STUDIO A" takes={takes} levels={levels} channels={channels} />
```

### Composition

```text
ConsoleScreen
  AppShell
  EngravedPlate
  StatusDot
  Segmented
  Panel
  StatTile
  LcdChip
  Chart
  Table
  Badge
  Menu
  Pagination
```

### Examples

**With your own data** — Every list is a prop; the screen owns only which channel and page are selected.

```tsx
<ConsoleScreen product="STUDIO A" takes={takes} levels={levels} channels={channels} />
```

### Accessibility

- Built on AppShell, so it gets its landmarks and skip link.
- The selected channel carries `aria-current`, not only a lit rail.
- The readouts are named groups and the chart is an image with a spoken summary; the takes are a real table.
- The screen owns the page's `<h1>`. Inside another page, pass `embedded`: headings drop a level and AppShell drops its landmarks.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `embedded` | `boolean` | false | This screen is inside another page: the title drops to <h2> and AppShell drops its landmarks, so the page keeps one <h1> and one <main>. |
| `product` | `string` | "ECHO ONE" | Name on the rail and the plate. |
| `takes` | `object[]` | — | Table rows. Defaults to a demo session. |
| `levels` | `number[]` | — | Level history, oldest first, on a fixed 0..100 scale. |
| `channels` | `string[]` | — | Channels down the left rail. |

### Anti-patterns
- Do not embed this screen in another page without `embedded`. It owns the page's <h1>, so a preview or a marketing page that renders it ends up with two first-level headings, and a screen-reader user's outline of the page stops making sense.
- Do not let the level matrix rescale itself. Without a fixed `max` the ceiling is the largest value present, so a new peak silently shrinks all the history behind it — the one thing a live readout must not do.
- Do not report a take's state with the badge colour alone. The badge carries the word; colour alone is lost on anyone with a colour-vision deficiency, on a screen reader, and in greyscale.
- Do not put the session's destructive actions in the rail menu without a confirm. A menu item fires on the first click — send anything that discards a take through an AlertDialog.
- Do not add axes and tooltips to the Chart to make this feel more like a dashboard. It is a device readout; the moment it needs hit-testing, the screen wants a real charting library beside it, not a heavier Chart.

## Chat screen (`echo-chat`)

One conversation as a front panel: an Avatar and StatusDot header, a message log, a Loader typing indicator, and a Textarea composer with one lit Send cap. Proves that the material language survives running text — incoming messages get no container, yours sit in the composer's recessed well, and the only raised object is Send.

*Feel:* A conversation as a front panel: your words sit in a recessed well, theirs on the ground, and Send is the only raised thing.

- Type: registry:block
- npm deps: echo-ui-core
- registry deps: @echo/echo-avatar, @echo/echo-textarea, @echo/echo-hardware-button, @echo/echo-loader, @echo/echo-status-dot, @echo/echo-kbd
- Install: `npx echo-ui-cli add chat`

### Usage

```tsx
import { ChatScreen } from "@/echo/chat";

<main>
  <ChatScreen
    participant="Studio A"
    onSend={async (text) => {
      const res = await fetch("/api/chat", { method: "POST", body: text });
      return (await res.json()).reply;
    }}
  />
</main>
```

### Composition

```text
ChatScreen
  Avatar
  StatusDot
  Loader
  Textarea
  HardwareButton
```

### Examples

**Wired to your backend** — Resolve with the reply and it lands after the typing indicator.

```tsx
<ChatScreen
  participant="Studio A"
  onSend={async (text) => {
    const res = await fetch("/api/chat", { method: "POST", body: text });
    return (await res.json()).reply;
  }}
/>
```

### Accessibility

- The thread is `role="log"`, named “Conversation with …”: new messages are announced politely, in order.
- The typing indicator is its own status (a Loader), so the log does not announce “typing” as a message.
- Enter sends and Shift+Enter starts a new line; Enter during IME composition does not send.
- The screen owns the page's `<h1>`. Inside another page, pass `embedded` and the title drops to `<h2>`.
- It renders no `<main>` of its own: put it inside your page's `<main>`, or the page has no main landmark.

### Motion & sound

- Sound: From its parts: `press` / `release` on the Send cap.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `embedded` | `boolean` | false | This screen is inside another page: the title drops to <h2>, so the page keeps one <h1>. Never set it on the screen that owns the page. |
| `participant` | `string` | "Echo" | Who you are talking to — the header name and the avatar. |
| `subtitle` | `string` | "Session assistant" | Under the name: a role, a channel, a device. |
| `messages` | `object[]` | — | The thread so far, oldest first. Defaults to a demo conversation. |
| `onSend` | `function` | — | Called with the sent text. Return (or resolve to) the reply to show it after the typing indicator. |
| `replies` | `string[]` | — | Canned replies, cycled — used only without onSend. |

### Anti-patterns
- Do not put incoming messages in raised cards. Forty molded bubbles on one screen is forty competing controls; running text sits on the ground, and only Send is raised.
- Do not put the typing indicator inside the message log. role="log" announces every addition — an indicator in it is read out between every message.
- Do not scroll the page to the newest message. Scroll the thread; an embedded chat that moves the document it sits in is a bug in someone else's page.
- Do not send on Enter while an IME composition is active. That is the key a Japanese or Chinese typist presses to accept a word.
- Do not colour your messages with the accent. Accent is the lit Send cap; a thread of accent bubbles makes every message read as a button.

## Theme Engine (`echo-theme`)

createEchoTheme(seed) → { css, values }. One OKLCH derivation turns a ~6-value seed into the full semantic-role set. Users touch only the seed; components consume only the roles.

*Feel:* Pick one colour and the whole device relights around it — plastic, glow and screen stay the same material in a new hue.

- Type: core:module
- npm deps: echo-ui-core
- Install: `npm install echo-ui-core`

### Usage

```tsx
import { createEchoTheme } from "echo-ui-core/theme";

const { css } = createEchoTheme({ accent: "#1FA8A0" });
return <style>{css}</style>;
```

### Examples

**Default theme** — Inject the default device look at :root.

```tsx
const { css } = createEchoTheme();
// <style>{css}</style> or inject into document head
```

**Retheme by seed** — One color in, the whole device relights — no raspberry residue.

```tsx
const { css, values } = createEchoTheme({ accent: "#1FA8A0" });
```

**Scoped theme** — Scope variables to a class instead of :root.

```tsx
createEchoTheme({ accent: "#E8952A" }, { selector: ".amber-device" });
```

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `accent` | `string` | "#DE3B74" |  |
| `chassis` | `string` | "#26222B" |  |
| `paper` | `string` | "#F5EDE0" |  |
| `lcdTint` | `string` | — |  |
| `finish` | `number` | 0.5 |  |
| `radius` | `number` | 0.5 |  |
| `density` | `"compact" | "default" | "comfortable"` | "default" |  |
| `fontMachine` | `string` | "ui-sans-serif, system-ui, -apple-system, 'Segoe UI', sans-serif" |  |
| `fontSans` | `string` | "ui-sans-serif, system-ui, -apple-system, 'Segoe UI', sans-serif" |  |
| `fontMono` | `string` | "ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace" |  |
| `fontLcd` | `string` | "ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace" |  |

### Anti-patterns
- Never hardcode hex in component CSS — consume var(--echo-*) so themes propagate.
- Do not read the seed inside components; components see only Layer 3 roles.
- Do not bypass createEchoTheme to hand-write role values — you lose the WCAG-AA contrast guardrail.

## Sound Engine (`echo-sound`)

SoundProvider + SynthBackend. Sound tokens are serializable synth recipes (dry, short, hardware) rendered by a zero-dep WebAudio synth. Lazy AudioContext, persisted mute, per-play jitter, blur guard, reduced-motion coupling.

*Feel:* Dry, short clicks and chirps from a device — never notes from an instrument.

- Type: core:module
- npm deps: echo-ui-core
- Install: `npm install echo-ui-core`

### Usage

```tsx
import { SoundProvider } from "echo-ui-core/sound";

<SoundProvider>
  <App />
</SoundProvider>
```

### Examples

**Wrap the app** — Provide sound once near the root. The AudioContext is created lazily on first pointerdown.

```tsx
<SoundProvider>
  <App />
</SoundProvider>
```

**Play a token** — useSound().play resolves a token name to its recipe and jitters it.

```tsx
const { play } = useSound();
<button onPointerDown={() => play("press")} onPointerUp={() => play("release")} />
```

**Mute toggle** — muted is persisted to localStorage.

```tsx
const { muted, setMuted } = useSound();
<button onClick={() => setMuted(!muted)}>{muted ? "unmute" : "mute"}</button>
```

### Motion & sound

- Sound: Nine tokens: `tap`, `press`, `release`, `select`, `transition`, `notify`, `caution`, `error`, `celebrate`.
- Sound: Every play varies pitch by up to 3% and volume by up to 10%.
- Sound: Silent until the first pointer press, when muted, in a hidden or unfocused tab, and — by default — under reduced motion.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `backend` | `SoundBackend` | — | A SoundBackend to render recipes with. Defaults to the zero-dependency WebAudio SynthBackend; swap it to route sound elsewhere or silence it in tests. |
| `masterGain` | `number` | 0.5 | Conservative master gain, scales every recipe. |
| `muteOnReducedMotion` | `boolean` | true | Silence sound when the OS requests reduced motion. |

### Anti-patterns
- Never create an AudioContext at module scope — autoplay policy blocks it and it breaks SSR.
- Do not add reverb or long tails; recipes stay dry and short (a device, not an instrument).
- Do not ship audio-file assets as the default sound path — synth recipes are the default backend.

## Motion Tokens (`echo-motion`)

Eight named motion tokens carrying duration, GSAP ease, and an explicit reduced-motion collapse. The rulebook is one line — glass and light move SMOOTHLY (summon, flood, settle); pixel things move SNAPPY or STEPPY (press, pop, glitch). Pure data with no window or GSAP access at module scope, so it is safe to import anywhere.

*Feel:* Glass moves smooth, pixels move steppy: panels ease into place, screen readouts tick over in steps.

- Type: core:module
- npm deps: echo-ui-core, gsap
- Install: `npm install echo-ui-core`

### Usage

```tsx
import gsap from "gsap";
import { motion } from "echo-ui-core/motion";

const t = motion.summon;
gsap.to(panel, { opacity: 1, duration: t.duration / 1000, ease: t.ease });
```

### Examples

**Drive a tween** — Tokens are data; you pass them to GSAP yourself.

```tsx
const t = motion.summon;
gsap.to(el, { opacity: 1, duration: t.duration / 1000, ease: t.ease });
```

**Through useTactile** — The usual path — the token names the gesture, the hook resolves it.

```tsx
const { ref, handlers } = useTactile({ press: { motion: "press" }, release: { motion: "pop" } });
```

**Honour the collapse** — Every token declares what it becomes under reduced motion; never ignore it.

```tsx
const t = motion.summon;
const vars = reduced && t.reduced !== "none" ? { opacity: 1 } : { opacity: 1, scale: 1 };
```

### Motion & sound

- Motion tokens: `press`, `pop`, `summon`, `breath`, `settle`, `glitch`, `flood`, `drain`
- Reduced motion: Each token declares its own collapse: `summon` and `flood` fade in place; every other token stops moving.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `duration` | `number` | — | Duration in ms. Omitted for scrub-driven tokens. |
| `ease` | `string` | **required** | GSAP ease string. |
| `loop` | `boolean` | — | Looping idle animation. |
| `reduced` | `"none" | object` | — | How the token collapses under prefers-reduced-motion. Defaults to "none". |

### Anti-patterns
- Never put a soft material ease on a pixel element — an LCD or dot-matrix surface takes glitch (steps), never summon or settle. This is the single most legible motion mistake in the system.
- Never invent a duration inline. If a gesture needs timing the tokens do not cover, add a token and document it; scattered magic numbers are how a motion system dies.
- Never animate a token's transform under prefers-reduced-motion — read `reduced` and collapse to the fade (or to nothing) as the token instructs.
- Never use `drain` with a duration — it is scrub-driven, timed by the clock that owns it, which is why it ships no duration at all.

## useTactile (`use-tactile`)

Binds motion (GSAP) + sound per interaction phase. Returns { ref, handlers } to spread onto an element. Pointer and keyboard feel identical; motion collapses under prefers-reduced-motion.

*Feel:* One hook makes a custom control press, spring back and click like every built-in one.

- Type: core:module
- npm deps: echo-ui-core, gsap
- Install: `npm install echo-ui-core`

### Usage

```tsx
import { useTactile } from "echo-ui-core/tactile";

const { ref, handlers } = useTactile<HTMLButtonElement>({
  press: { motion: "press", sound: "press" },
  release: { motion: "pop", sound: "release" },
});
return <button ref={ref} {...handlers}>Record</button>;
```

### Examples

**Tactile button** — The canonical press/release pairing.

```tsx
const { ref, handlers } = useTactile({
  press:   { motion: "press", sound: "press" },
  release: { motion: "pop",   sound: "release" },
});
return <button ref={ref} {...handlers}>Record</button>;
```

**Escape hatch** — Pass raw GSAP vars / recipe objects instead of token names for full control.

```tsx
useTactile({ press: { motion: { rotation: -3, duration: 0.1 } } });
```

### Motion & sound

- Motion tokens: `press`, `pop`
- Reduced motion: Motion follows each token's own collapse; sound follows the SoundProvider, which mutes under reduced motion by default.
- Sound: Whatever each phase names — typically `press` on the way down and `release` on the way up. Space and Enter play the same as a pointer.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `press` | `object` | — |  |
| `release` | `object` | — |  |
| `hover` | `object` | — |  |
| `leave` | `object` | — |  |
| `focus` | `object` | — |  |
| `blur` | `object` | — |  |
| `activate` | `object` | — |  |

### Anti-patterns
- Do not re-implement keyboard handling on top of useTactile — Space/Enter parity is built in.
- Do not put a smooth material ease on pixel/LCD elements — use motion.glitch (steppy).
- Do not gate sound on reduced-motion here; the SoundProvider already couples them.

## useGsapPresence (`use-gsap-presence`)

The Bucket A exit bridge, implemented once and reused by every Base UI wrapper (Modal, Popover, Tooltip). Base UI can auto-detect a CSS transition before unmounting, but not a JS animation — so on close this hook asks Base UI to keep the node mounted, runs the GSAP exit, and calls unmount() itself when the tween finishes. It is Base-UI-agnostic: it only needs an actions object exposing unmount().

*Feel:* A popup leaves the way it arrived, instead of vanishing mid-animation.

- Type: core:module
- npm deps: echo-ui-core, gsap
- Install: `npm install echo-ui-core`

### Usage

```tsx
import type { RefObject } from "react";
import { Dialog } from "@base-ui/react/dialog";
import { useGsapPresence } from "echo-ui-core/presence";

const p = useGsapPresence();
return (
  <Dialog.Root
    open={p.open}
    onOpenChange={p.onOpenChange}
    actionsRef={p.actionsRef as RefObject<Dialog.Root.Actions | null>}
  >
    <Dialog.Portal>
      <Dialog.Popup ref={p.popupRef}>…</Dialog.Popup>
    </Dialog.Portal>
  </Dialog.Root>
);
```

### Examples

**Wire a Base UI Root** — Spread the three controlled props; attach popupRef to the animated popup. The hook types its actions as the one method it calls (`unmount`), so narrow them to the Root's own Actions type at the call site.

```tsx
const p = useGsapPresence();
<Dialog.Root
  open={p.open}
  onOpenChange={p.onOpenChange}
  actionsRef={p.actionsRef as React.RefObject<Dialog.Root.Actions | null>}
>
  <Dialog.Popup ref={p.popupRef}>…</Dialog.Popup>
</Dialog.Root>
```

**Different enter and exit** — Tokens name the timing at both ends.

```tsx
const p = useGsapPresence({ enter: "summon", exit: "glitch" });
```

### Motion & sound

- Motion tokens: `summon`
- Reduced motion: Enter and exit follow the tokens' collapse — `summon` becomes a fade — and the node still unmounts when it ends.

### Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `enter` | `string` | "summon" | Motion token for the enter timing. |
| `exit` | `string` | "summon" | Motion token for the exit timing. |
| `defaultOpen` | `boolean` | false | Initial open state. |
| `onOpened` | `function` | — | Called once the enter animation has started. |

### Anti-patterns
- Never rely on actionsRef alone to hold the element mounted — it does not. The exit only survives because onOpenChange calls details.preventUnmountOnClose(); drop that call and Base UI removes the node mid-tween.
- Never also put a CSS transition on the popup's transform or opacity. GSAP owns those properties here, and Base UI's transition auto-detection will race the tween. Transition the backdrop instead.
- Never use this with Base UI Select — its ChangeEventDetails has no preventUnmountOnClose, so there is nothing to hold the node. Select animates through [data-starting-style] / [data-ending-style] CSS instead.
- Never assert on role="dialog" to test the exit — Base UI drops the role immediately on close while the node is still animating. Target the popup element's class.