@instruments/materia-ui 0.1.0

package/agent-docs.md

@@ -0,0 +1,2104 @@
+# @instruments/materia-ui - agent guidance
+
+<!-- GENERATED by scripts/generate-agent-docs.mjs - DO NOT EDIT.
+     Author `@bestPractice` JSDoc tags on public exports; regenerate with
+     `pnpm generate:agent-docs`. -->
+
+Do and don't guidance for coding agents, one section per component, taken from `@bestPractice` JSDoc tags. It ships in the package, so an agent in an app can read it at `node_modules/@instruments/materia-ui/agent-docs.md`.
+
+## Rules
+
+- Reach for a component before writing markup. Find one here or in `@instruments/materia-ui/data/docs-manifest`, and import it from the path under its heading. There is no root barrel.
+- Never invent a prop. Use only props in the component's types or the docs manifest. If what you need doesn't exist, say so rather than guessing.
+- Style with the system's vocabulary: `tone`, `emphasis`, `size` and the theme's classes. No raw colours and no arbitrary values such as `mt-[13px]`.
+- Import icons through `Icon` and primitives through these components, never from `lucide-react` or `@base-ui/react` directly.
+- Check your work with the `materia-ui-lint` class scanner (`--all` for every rule). The Oxlint preset is `@instruments/materia-ui/lint/oxlint`.
+
+Documented components: 196
+
+## AccordionRoot
+
+`@instruments/materia-ui/components/accordion`
+
+Collapsible panel container that wraps Base UI Accordion, supporting one (default) or several (`multiple`) open items. Works controlled (`value`) or uncontrolled (`defaultValue`); compose with AccordionItem, AccordionTrigger, and AccordionContent. Values are always arrays of item `value`s.
+
+- Leave `multiple` off for one-at-a-time panels or set it to allow several open at once; `value`/`defaultValue` are arrays either way, and an open item can always be closed again.
+- Reach for `Collapsible` instead when there is a single expandable region - `Accordion` is for a set of grouped items keyed by `value`.
+- Children must be `AccordionItem`s (each with `AccordionTrigger`/`AccordionContent`); the item's `value` is what `value`/`defaultValue` match against.
+
+## Alert
+
+`@instruments/materia-ui/components/alert`
+
+Callout banner for important messages, composed with `AlertTitle` and `AlertDescription`.
+
+Lay out as a two-column grid: a direct-child `<svg>` is auto-detected and given its own icon column, otherwise the text spans full width. Renders `role="alert"` so screen readers announce it; `tone="danger"` recolours the text and description for error states.
+
+- Use `Alert` for a persistent inline message block; a transient, auto-dismissing notification is a toast (`Toaster` and `toast()` from `components/toast`).
+- Compose `AlertTitle` / `AlertDescription` as children and render a direct-child `<svg>` for the auto-detected icon column; `tone="danger"` recolours for errors.
+- It renders `role="alert"`, so AT announces it on mount - keep it a notice, not a container for heavy interactive UI.
+
+## AlertDialog
+
+`@instruments/materia-ui/components/alert-dialog`
+
+Modal confirmation dialog that interrupts the user for a decision that can't be dismissed by clicking outside - use for destructive or irreversible actions. Open state is controlled (`open`) or uncontrolled (`defaultOpen`); compose with AlertDialogTrigger and AlertDialogContent.
+
+- Use `AlertDialog` only for a confirm / warn / destructive decision (Cancel + Action); a general modal form or details view is a `Dialog`.
+- Route every destructive confirmation here, never a plain `Dialog` - unlike `Dialog` it won't dismiss on outside-click / Esc, so the choice stays deliberate.
+- Give the destructive `AlertDialogAction` `tone="danger"` and keep the safe escape as `AlertDialogCancel`.
+
+## Anchor
+
+`@instruments/materia-ui/components/anchor`
+
+Inline text link - a styled `<a>` with a token underline, an offset, and the shared focus ring. `variant="muted"` sits quietly in body copy until hovered. Pass a framework link to `render` (e.g. `next/link`) to keep client-side navigation. RSC-safe.
+
+- Anchor is for text links, whether inside prose or standing alone (a caption, an index row, a footer link); for a button-shaped navigation action give `Button` a `render` link instead.
+- Compose routers via `render` (`<Anchor render={<Link href="…" />}>…</Anchor>`) - never nest a raw `<a>` inside Anchor's own `<a>`.
+- Add `icon` or `suffixIcon` (as on `Button`) for an arrow or external-link cue; the icon sits outside the underline and wraps with the text, and is decorative, so the link text must still name the destination.
+- Use `variant="muted"` inside dense copy so the underline stays quiet; the default variant stands out from the surrounding text.
+- Use `variant="plain"` where the link is already set apart by its position, such as a caption under a tile or a row in an index; keep an underline on links inside running text.
+
+## AnimatedNumber
+
+`@instruments/materia-ui/components/animated-number`
+
+Animated number that counts up like an odometer.
+
+A faithful port of Motion+'s `AnimateNumber`: each digit is a full 0–9 column that rolls through the intermediate numerals to its new value (a FLIP spring on `y`), the leading digit rolls up from zero as magnitude grows, and section widths animate so proportional fonts stay aligned. Formatting (grouping, fraction digits, currency, sign) comes from `Intl.NumberFormat`; the token `duration` / `easing` drive the timing, or pass `transition` for a bespoke curve/spring. Use `prefix` / `suffix` for units and currency so they align with the digits and fold into the single screen-reader announcement.
+
+- Needs `ReducedMotionProvider` in the app tree - it supplies the LazyMotion `domMax` features the digit roll and layout animations require, and its `reducedMotion="user"` makes the number snap to its final value for users who ask for less motion.
+- Use `prefix`/`suffix` for units and currency (`$`, `/10`), not sibling text nodes - they're layout-animated with the digits and folded into the one screen-reader announcement.
+- Reach for the `duration`/`easing` tokens over a raw `transition` - token timing keeps it in step with the rest of the motion system; drop to `transition` only for bespoke springs.
+
+## AspectRatio
+
+`@instruments/materia-ui/components/aspect-ratio`
+
+Constrains its content to a fixed width-to-height ratio, sizing itself to the available width with CSS `aspect-ratio`; drop a single child (image, video, iframe, or a plain element) inside and size it to fill the framed box.
+
+- Give it exactly one child and let it fill - set the media to `size-full object-cover`; `AspectRatio` sizes to the available width and derives height from `ratio`.
+- Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+
+## AttributeCard
+
+`@instruments/materia-ui/compositions/attribute-card`
+
+AttributeCard UI component. Import from "@instruments/materia-ui/compositions/attribute-card".
+
+- Use `AttributeCard` for a single label + prominent value stat tile (a KPI/metric); for many key/value pairs about one entity reach for `DescriptionList` instead.
+- Pass a Lucide component to `icon` (e.g. `RulerIcon`), not a rendered `<Icon/>` - it is handed to the internal `Icon` at a fixed `sm` size.
+- This is a preset composition of `Card`; restyle via the surrounding layout rather than reaching inside - for a bespoke layout compose `Card`/`CardContent` directly.
+
+## AvatarRoot
+
+`@instruments/materia-ui/components/avatar`
+
+Container for a user or entity avatar; compose an `AvatarImage` and `AvatarFallback` inside, and the fallback shows automatically when the image is missing or fails to load.
+
+- Always render an `AvatarFallback` child - it is what shows while the image loads and when `src` is missing or errors; an image-only avatar renders empty on failure.
+- Give `AvatarImage` a meaningful `alt`; the visual is decorative only when the fallback initials already convey the identity.
+- Keep the default `radius="full"` for people; use a squared `radius` for brand/entity logos so they read as objects, not users.
+
+## Badge
+
+`@instruments/materia-ui/components/badge`
+
+Display-only pill for contextual metadata - status, category, or counts. Pass `label`+`value` for a split badge; compose `BadgeDot`/`BadgeButton` as children.
+
+- Badge is display-only - never attach `onClick`; use `Tag` (interactive) or wrap a `Button`.
+- For a notification count use `mode="count"` (circular, tabular figures), not `radius="full"` + manual classes.
+- A standalone count needs an `accessibleLabel` ("3 unread"); inside an icon-only trigger, mark the badge `aria-hidden` and fold the count into the trigger's `aria-label`.
+- A badge overlapping a corner of another surface takes `ring` so a 2px `background`-coloured ring separates it from what's beneath; set it only where the badge truly overlaps, and the page surface should be `background`.
+
+## BorderBeam
+
+`@instruments/materia-ui/components/border-beam`
+
+A soft rotating "border beam" shimmer used to draw attention to an element before the user interacts with it.
+
+Two usage shapes:
+
+1. Wrapper - pass `children` and the beam wraps them in a relative box.
+2. Overlay - render without children inside an existing relative parent.
+
+Honours `prefers-reduced-motion` (renders nothing - a static ring would be louder than the animated sweep it's meant to replace). When `visible` flips to `false`, the beam fades out then unmounts so its rAF loop stops.
+
+- Animate the `--border-beam-angle` custom property (as the source does), never `rotate` the masked ring - a rotated box swings its mask outside a wide pill's bounds and renders as a stray streak, not a border orbit.
+- Requires `ReducedMotionProvider`; under reduced motion it renders nothing (a static ring would read louder than the sweep it replaces), so don't add your own fallback border.
+- Use it as an attention / "try me" cue on an idle surface, not a loading state - content placeholders want `Skeleton`, and a periodic liveness flick wants `Shine`.
+
+## Box
+
+`@instruments/materia-ui/components/box`
+
+The escape hatch: a raw host element with a `className`, still checked for tokens-only classes. Box renders the chosen {@link LayoutElement} with no layout opinions of its own (no margin, width, or padding, unlike Container), so it suits decorative wrappers that a styled primitive would visually break. Reach for it only when no styled primitive fits; the `className` you pass is governed by the same tokens-only scan as everything else. RSC-safe.
+
+- `Box` renders the chosen element with no layout opinions (no margin/width/padding, unlike `Container`); use it as a neutral wrapper when a styled primitive would interfere.
+- Use `as="span"` for a decorative inline wrapper; reach for `Box` only when no styled primitive fits - its `className` is still checked for tokens-only classes.
+- `as` and `render` are mutually exclusive (`render` wins, dev-warned); `as` draws from the closed layout vocabulary.
+- Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+
+## Breadcrumb
+
+`@instruments/materia-ui/components/breadcrumb`
+
+Navigation landmark for a breadcrumb trail; renders a labelled `<nav>`.
+
+- When the trail sits directly above the page heading, stop at the last navigable ancestor and let the heading name the current page. Use `BreadcrumbCurrent` only when no adjacent heading supplies that context.
+- Render router links via `<BreadcrumbLink render={<Link href="…" />}>` with a framework `<Link>` - the bare default is an `<a>`.
+- Collapse overflow with `BreadcrumbEllipsis` hosting a menu of the hidden crumbs, rather than dropping items silently.
+
+## Button
+
+`@instruments/materia-ui/components/button`
+
+Button styled by a tone × emphasis grammar: `tone` sets the semantic colour (neutral / brand / danger) and `emphasis` sets the visual weight (solid / soft / outline / ghost / transparent / link). Any pairing is valid - there is no fixed "primary/secondary" list; those looks are expressed as tone × emphasis pairs.
+
+An icon-only button (an `icon-*` size, or `icon` with no children) requires an `aria-label`; a dev-only console warning fires when it is missing. With `render`, styling and icon/dot decorations are applied to the element you pass in.
+
+- Express weight with `tone`×`emphasis`, not a `variant` prop - there is no "primary/secondary"; e.g. the destructive confirm is `tone="danger"`.
+- Icon-only buttons MUST have an `aria-label` (a dev warning fires otherwise).
+- Use `render` to render a link element (e.g. `render={<Link href="…" />}`) rather than nesting a button inside an anchor.
+- `loading` keeps the button focusable while it blocks presses, so focus stays put across a submit; a plain `disabled` button leaves the tab order.
+- Reach for `emphasis="ghost"`/`"link"` in toolbars/headers - they carry `data-edge-comp` so containers can pull them flush to the edge.
+
+## ButtonGroup
+
+`@instruments/materia-ui/components/button-group`
+
+Combines related buttons into a single visual unit. Also composes with Input, Select, and DropdownMenu; `dividers` defaults on for the segmented variant.
+
+- Use `ButtonGroup` to visually join related `Button`s (plus `Input`/`Select`/`DropdownMenu`); for one/many _selection_ state reach for `ToggleGroup`.
+- The `segmented` variant owns the border/background/shadow and defaults `dividers` on, while `joined` (default) lets each child draw its own - don't mix the two.
+
+## Calendar
+
+`@instruments/materia-ui/components/calendar`
+
+Date picker built on react-day-picker, styled with the shared button variants; supports `single`, `multiple`, and `range` selection via the `mode` prop. Accepts all DayPicker props. `showOutsideDays` defaults to `true`.
+
+- Set `mode` explicitly (`single` | `multiple` | `range`) - the selection value shape and `onSelect` signature change with it; a `range` handler never fires in `single` mode.
+- Restrict selectable dates with react-day-picker matchers (`disabled`/`hidden`/`startMonth`/`endMonth`), not by filtering after the user clicks.
+- Use `Calendar` for an inline date grid; for a compact click-to-open date field, wrap it in a `Popover` behind a `Button`/`Input` trigger.
+
+## Card
+
+`@instruments/materia-ui/components/card`
+
+Card container with optional border and variant-based background.
+
+- Compose structure with `CardHeader`/`CardContent`/`CardFooter` rather than raw padded divs - the root supplies the gap rhythm and drops its bottom padding when a footer is present, via `data-slot` selectors.
+- Set `inset` on the `Card` (not on its parts) to change the padding around header and content; `inset="none"` gives a card with no padding or gaps for a `Table` or code block. "Flush" covers header and content only: `CardFooter` keeps its own 16px padding whatever the inset.
+- Pass `shadow={false}` when stacking cards on a `muted`/shaded canvas - colour contrast separates them and per-card shadows read as noise.
+- For a full-bleed media/CTA panel use an editorial composite (`EditorialCard`), not `Card` - `Card` is a neutral padded container, not a marketing surface.
+
+## CardGrid
+
+`@instruments/materia-ui/compositions/card-grid`
+
+Responsive `@container` list that lays cards out in rows. The default `wrap` layout is a wrapping flex row whose items resize at the ProductCard small/medium/full breakpoints via the `@container/card-grid` query name; `layout="fill"` is a grid whose columns stretch to fill each row.
+
+- Render `CardGridItem` children so each card is a list item under this `<ul>` - wrapping arbitrary elements loses the list semantics.
+- Use `layout="fill"` wherever the grid's width changes with the page (a docked panel, a collapsing sidebar): fixed widths leave a ragged gap at the right edge, fill columns don't. Keep `CardGridRows` on the default, as its row widths come from the fixed metrics.
+- Give the loading grid the same `layout` and `minItemSize` as the loaded one, so skeletons and cards share columns and nothing reflows when data lands.
+
+## CardGridItem
+
+`@instruments/materia-ui/compositions/card-grid`
+
+A single cell within `CardGrid`, rendered as a list item. In the default `wrap` layout it carries the responsive widths: a fluid 2-up (`w-[calc((100%-1rem)/2)]`) below a 500px container, then fixed `w-44` / `@[800px]/card-grid:w-52` / `@[1200px]/card-grid:w-68`, tuned to the ProductCard small/medium/full breakpoints. In a `fill` grid the column track sizes it instead.
+
+- Keep this as the direct child of `CardGrid` so the list semantics stay intact; put the actual card inside it.
+
+## CardGridRows
+
+`@instruments/materia-ui/compositions/card-grid`
+
+Renders a list of pre-chunked rows, each as its own `CardGrid`, with an optional `renderAfterRow` slot (e.g. an expanded detail panel) beneath each row. Row widths are derived from `metrics` so callers can align that slot.
+
+- Chunk items with `chunkIntoRows` (using `calculateColumns`) before passing `rows`; provide a stable `getItemKey` (and `getRowKey` where rows reorder) so React reconciliation stays correct.
+
+## CardGridSkeletonItem
+
+`@instruments/materia-ui/compositions/card-grid`
+
+Loading placeholder for a single `CardGrid` cell.
+
+It renders ONE skeleton and lets the skeleton read the cell it lands in. Choosing here on `@container/card-grid` was choosing on the wrong signal: the grid's phone tier is a fluid 2-up, so a 460px container renders 222px cards - the card's main arm - while the grid query still read "small".
+
+- Render one `CardGridSkeletonItem` per expected card while data loads, inside the same `CardGrid` - this keeps list semantics and column widths stable across the loading→loaded transition.
+
+## Carousel
+
+`@instruments/materia-ui/components/carousel`
+
+Embla-backed carousel that shares scroll state and controls with its parts (CarouselContent, CarouselPrevious/Next, CarouselDots) via context - they must render inside it.
+
+- Render `CarouselContent`/`CarouselItem`/`CarouselPrevious`/`CarouselNext`/`CarouselDots` only inside `Carousel` - they read scroll state from context and throw ("must be used within a Carousel") outside it.
+- Set `slidesToShow` to show multiple items at once (it drives each item's `flex-basis`); don't fake a multi-item view with CSS widths on `CarouselItem`.
+- Tune scroll behaviour via `opts` (Embla options like `loop`/`align`) and enable `wheelScroll`/`freeScroll` deliberately - free-scroll drops snap points, so pass `slideCount` if the dots miscount.
+- Give a descriptive `aria-label` when the region isn't self-evidently "Carousel" (e.g. `"Product images"`).
+
+## Center
+
+`@instruments/materia-ui/components/center`
+
+Center centres its children both vertically and horizontally using flexbox.
+
+**Important:** Children that use CSS Grid with `fr` units must define their own width (e.g., `w-96`, `max-w-md`). This is because `fr` units require a defined container width to calculate available space, but flex items without explicit width use intrinsic sizing - creating a circular dependency where the grid collapses to minimum content width.
+
+- `Center` centres a single child on both axes; grid children using `fr` units need an explicit width (e.g. `w-96`) or they collapse to min-content.
+- `as`/`render` are mutually exclusive (`render` wins, dev-warned); use `inline` to center inline-level content without breaking the text flow.
+- Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+
+## Chart
+
+`@instruments/materia-ui/components/chart`
+
+Responsive frame for a recharts chart. Wraps recharts' `ResponsiveContainer`, provides the `config` (series keys → label / icon / colour) to every descendant `ChartTooltipContent` / `ChartLegendContent`, and injects a `--color-<key>` CSS variable per series so recharts marks can be coloured with `fill="var(--color-desktop)"`. Pass a single recharts chart element as the child. It is dimensionless - set the aspect / height with `className` (defaults to `aspect-video`).
+
+- Colour every series through `config` (`{ desktop: { label, color } }`) and reference `var(--color-<key>)` on the marks - never hardcode a hex on a `Bar` / `Line`; that keeps light/dark theming and the legend/tooltip swatches in sync.
+- Reach for `Chart` only to render a recharts data visualization; for a static value + delta use `Stat`, and for a progress bar use `Progress`.
+
+## Checkbox
+
+`@instruments/materia-ui/components/checkbox`
+
+Renders a checkbox input with support for checked, unchecked, and indeterminate states.
+
+- A bare `Checkbox` has no label - pair it with a `Label` (`htmlFor`) or use `CheckboxField`, which wires `id`/`htmlFor`/`aria-describedby` for you.
+- Set the mixed state via the `indeterminate` prop; `checked` stays a boolean.
+- Controlled use needs `checked` + `onCheckedChange` together; passing only `checked` freezes the box - use `defaultChecked` for uncontrolled.
+- For a selectable card or a label+description row, reach for `CheckboxCardGroup`/`CheckboxField` instead of hand-laying-out around `Checkbox`.
+
+## CheckboxCardGroup
+
+`@instruments/materia-ui/components/checkbox-card`
+
+Multi-select group of `CheckboxCard`s presented as interactive cards. Shares size, indicator, icon, and checked state with its items via context. With `checkedValues` it is a Base UI `CheckboxGroup` (`role="group"`) that owns which cards with a `value` are checked.
+
+- Use `CheckboxCardGroup` for multi-select cards and `RadioCardGroup` for single-select - a checkbox group lets any number be on at once.
+- Set `size`/`icon`/`indicatorSide`/`showIndicator` once on the group; every `CheckboxCard` reads them from context - don't repeat them per item.
+- To control the set, give each card a `value`, drive `checkedValues` (a `string[]`) and toggle inside `onCheckedChange(value, checked)`; without `checkedValues` each card keeps its own `checked`/`defaultChecked`.
+- Each card is one tab stop and toggles with Space; checkboxes don't rove, so Tab (not the arrow keys) moves between cards.
+
+## CheckboxField
+
+`@instruments/materia-ui/components/checkbox-field`
+
+Checkbox paired with a label and optional description in a Base UI `Field`, which associates the label with the checkbox and links the description through `aria-describedby`; forwards checkbox state props to the underlying Checkbox.
+
+- Use `CheckboxField` for a single labelled checkbox - its `Field` wires the label and `aria-describedby` you'd otherwise hand-roll around a bare `Checkbox`.
+- Put helper text in `description` (linked via `aria-describedby`), not a separate sibling element the screen reader won't announce with the control.
+- `size` accepts only `"xs"`/`"sm"`; for a full selectable card use `CheckboxCardGroup`, and render one `CheckboxField` per option for a set.
+
+## Code
+
+`@instruments/materia-ui/components/code`
+
+Monospace code - inline `<code>` by default (a muted, rounded chip sized to surrounding text), or a scrollable `<pre><code>` block when `block` is set. Token-styled and RSC-safe.
+
+- Use inline `Code` for identifiers/values in a sentence and `block` for multi-line snippets - `Kbd` is for keyboard keys, not code.
+- `block` renders `<pre><code>` that scrolls horizontally; add `whitespace-pre-wrap` via `className` only when wrapping beats scrolling (long prose-like messages).
+
+## Collapsible
+
+`@instruments/materia-ui/components/collapsible`
+
+Expand/collapse container that reveals its CollapsibleContent when open. Controlled via `open`/`onOpenChange` or uncontrolled via `defaultOpen`.
+
+- Use `Collapsible` for a single expand/collapse region; reach for `Accordion` when you have a set of grouped items where selecting one can close the others.
+- Compose `CollapsibleTrigger` + `CollapsibleContent` inside it - a bare child won't expand.
+- Drive it uncontrolled with `defaultOpen`; only lift to `open`/`onOpenChange` when external state must sync (e.g. persisting the open panel).
+
+## ColorPalette
+
+`@instruments/materia-ui/compositions/color-palette`
+
+Stacked colour palette in the style of the Dropbox brand site: a row of overlapping, bottom-anchored square cards cropped to 16:9. Hovering or focusing a card smoothly raises it and reveals a search action that deep-links into the colours search page.
+
+The component renders only the swatch row - no card, heading, or CTA chrome. Compose those around it (a `<section>`, a title, a sample button wired to `onSelectedIdsChange`) when a surface calls for them.
+
+Cards can be flat colours, gradients, or images (see ColorPaletteItem). Image cards need a `searchHex` to be clickable.
+
+With `selectable`, clicking anywhere on a card toggles it in and out of the selection instead of linking out; selected cards keep a check visible at rest, and the selection surfaces through `onSelectedIdsChange`.
+
+- Describe cards as `items` (`kind: "color" | "gradient" | "image"`), not hand-built markup - the component owns the overlap, hover-raise, and deep-link-to-search behaviour.
+- Give every `image` card a `searchHex`, otherwise it can't be searched or selected - flat colours and gradients derive theirs automatically.
+- Pass `renderLink` (e.g. wrapping `next/link`) for client-side nav - the built-in links are plain `<a>`; the callback must return a single anchor element.
+
+## ColorWheel
+
+`@instruments/materia-ui/components/color-wheel`
+
+Concentric saturation/lightness pad + hue arc picker.
+
+- `ColorWheel` is fully controlled - own the `ColorWheelValue` (`{h,s,l}`) and set it from `onChange`; it stores nothing internally, so dropping the update freezes the picker.
+- Values are HSL (`h` 0–360, `s`/`l` 0–100), not hex - convert at your storage boundary; a hex string won't position the handles.
+- `onChange` fires on every pointer drag and arrow-key step - throttle persistence/network writes downstream rather than reacting to each intermediate value.
+
+## Combobox
+
+`@instruments/materia-ui/components/combobox`
+
+Searchable select: a button trigger opening a filterable option list in a popover. Works controlled (`value` + `onValueChange`) or uncontrolled; supports virtualisation for large lists.
+
+- Use `Combobox` when the user filters/searches a long list; use `Select` for a short closed list, or a domain variant like `CountryCombobox` for known sets.
+- `onValueChange` fires with `""` when the current selection is toggled off - treat empty string as "cleared", not as a real value.
+- For lists in the hundreds+, pass `virtualization={{ enabled: true }}` so only visible rows mount instead of every option.
+- Provide `items` as `{ label, value }[]` - the visible text comes from `label` while selection is tracked by `value`.
+
+## Command
+
+`@instruments/materia-ui/components/command`
+
+The inline command palette: a search field filtering a keyboard-navigable list, built on Base UI Autocomplete in inline mode. The list is always open; typing filters the entries and the first match is highlighted, so `Enter` activates it. Import from "@instruments/materia-ui/components/command".
+
+- For a ⌘K overlay use `CommandDialog` - `Command` alone is the inline, non-floating palette container.
+- Pass the entries as `items`, or as titled `groups`, and render them with a function child of `CommandList`; filtering only sees those entries, so items written as static JSX are not filtered.
+- Act on a choice with `CommandItem`'s `onClick`, which fires for a pointer click and for `Enter` on the highlighted item.
+- A plain click-triggered action menu is `DropdownMenu`; a remembered selection is `Combobox`.
+
+## CommandDialog
+
+`@instruments/materia-ui/components/command`
+
+CommandDialog wraps `Command` in a dialog, with screen-reader-only title and description for accessibility. Focus moves to the search field on open and returns to the trigger on close.
+
+Import from "@instruments/materia-ui/components/command".
+
+- Close the dialog from each `CommandItem`'s `onClick` once its action has run - choosing an item does not close it by itself.
+- Pass `filter={null}` to list the entries unfiltered, for example when the application filters them itself.
+
+## Container
+
+`@instruments/materia-ui/components/container`
+
+Container centres page content within a max-width and applies the canonical horizontal gutter. It is the RSC-safe page-shell primitive: pair it with `Section` for vertical rhythm, or pass `space` to fold the band into one node.
+
+Import from "@instruments/materia-ui/components/container".
+
+- `Container` constrains width and applies the page gutter; `Section` is the full-bleed vertical-rhythm band - nest a `Container` inside a `Section` when content must be both padded and centred.
+- Fold a single band into one node with `space` (its `py`) instead of nesting a `Section`; pass `fluid` to drop the max-width.
+
+## ContextMenu
+
+`@instruments/materia-ui/components/context-menu`
+
+Menu of actions or options, opened by right-clicking (or long-pressing) its trigger surface. Supports nested submenus, checkbox/radio items, separators, and keyboard shortcuts. Open state is uncontrolled by default; pass `onOpenChange` to observe it.
+
+- Use `ContextMenu` for a right-click / long-press menu on a surface; a menu opened by clicking a button or trigger is a `DropdownMenu`.
+- Wrap the target region in `ContextMenuTrigger` so the whole surface is right-clickable; use `ContextMenuCheckboxItem` / `ContextMenuRadioGroup` for stateful rows.
+
+## CookieBanner
+
+`@instruments/materia-ui/compositions/cookie-banner`
+
+Cookie consent banner: a title and description beside a stack of actions. Lays itself out from its own width (a container query), stacking the copy above the buttons when narrow and setting them side by side when wide.
+
+- The app places and sizes it (e.g. `fixed inset-x-4 bottom-4 max-w-3xl`); it has no intrinsic width, so a fixed corner without a width collapses it.
+- Only wire the actions you support: Reject and Cookie settings render only when `onReject` / `onSettings` are passed.
+- It records nothing. Store the visitor's choice in the handlers and stop rendering the banner once they have made it.
+
+## CountryCombobox
+
+`@instruments/materia-ui/components/country-combobox`
+
+Specialized combobox for country selection Uses ISO 3166-1 alpha-2 country codes from countries-list package Automatically handles country code/name conversion
+
+- Feed `value` an ISO alpha-2 code (`"US"`) or a full country name (`"United States"`) - both resolve - but `onValueChange` always returns the code.
+- Don't pass `items`; `CountryCombobox` supplies the full country list itself. For a non-country searchable list, use the base `Combobox`.
+
+## CountrySelect
+
+`@instruments/materia-ui/components/country-select`
+
+Country selector with flag display.
+
+Controlled: `value` (ISO 3166-1 alpha-2) drives the selection and `onChange` reports the newly chosen code. A native `<select>` overlays the flag so the picker keeps native keyboard and mobile behaviour. A divider on its trailing edge shows only when it sits inside an input (`PhoneInput` or `InputGroup`).
+
+- `CountrySelect` is the flag + native-`<select>` picker for a known country list; when users need type-to-filter, use `CountryCombobox` instead.
+- It is controlled-only - pass `value` (ISO 3166-1 alpha-2) and an `onChange`; there is no uncontrolled/`defaultValue` mode.
+- Give each option an alpha-2 `value` (e.g. `"US"`) so the overlaid flag resolves; a globe placeholder shows when the code is empty/unknown.
+
+## DataGrid
+
+`@instruments/materia-ui/compositions/data-grid`
+
+Root of the DataGrid compound: merges caller layout/loading props over sensible defaults and provides the context consumed by the table parts.
+
+Requires a TanStack `table` instance (throws without one). Applies `initialColumnPinning` once on mount and auto-enables column pinning for it.
+
+- Reach for `DataGrid` (not `Table`) when you need sorting, filtering, column pinning/visibility, or pagination - `Table` is a plain styled HTML table with no data model.
+- Pass a `useTable` instance as `table` - `DataGrid` throws "requires the `table` prop" without one; column defs and row model live on that instance, not on `DataGrid` props.
+- Render the satellite parts (`DataGridTable`, `DataGridPagination`, `DataGridColumnHeader/Filter/Visibility`) inside `DataGrid` - they read the table + layout from its context and break outside it.
+- Enable features through `tableLayout` (`columnsPinnable`, `columnsResizable`, `columnsVisibility`, …) rather than styling rows manually; set `initialColumnPinning` to pin on mount.
+
+## DataGridColumnFilter
+
+`@instruments/materia-ui/compositions/data-grid-column-filter`
+
+Faceted multi-select filter for a DataGrid column, built on Base UI Combobox in `multiple` mode with the search field inside the popup. The trigger summarises the selection; the popup lists options with live facet counts and a clear action.
+
+- For a DataGrid, prefer marking the column `meta: { filter: true }` and building the table with `useDataGridTable`: its header and `PageToolbarTableFilters` then filter it from one state. Use this only for a standalone filter outside that route.
+- Pass the TanStack `column` instance (not a column id) - counts come from `column.getFacetedUniqueValues()`, so wire `getFacetedUniqueValues`/`getFacetedRowModel` into the table for live facet counts.
+- Supply `options` (label/value/icon) explicitly; the filter renders those choices, it does not derive them from the data - omitted values won't be filterable.
+- Use this for a discrete multi-select facet; it stores an array filter value, so pair it with a column filter fn that matches array membership.
+- The typed search survives each pick, so several matches can be ticked from one query; it resets when the popup closes.
+
+## DataGridColumnHeader
+
+`@instruments/materia-ui/compositions/data-grid-column-header`
+
+Interactive column header for a `DataGrid`: click to cycle sorting, or open the dropdown to sort, pin, move, and toggle column visibility. Reads DataGrid context, so it must render inside a `DataGrid` provider.
+
+- Render inside a `DataGrid` - it calls `useDataGrid()` and throws outside the provider; use it as a column def's `header`, not standalone.
+- The pin/move/visibility controls only appear when the matching `tableLayout` flags (`columnsPinnable`/`columnsMovable`/`columnsVisibility`) are enabled on `DataGrid` - a missing menu item usually means the flag is off, not a bug.
+- Pass a human `title` (and optional `icon`); it is the accessible label for the sort/menu trigger and the moved-column announcement.
+
+## DataGridColumnVisibility
+
+`@instruments/materia-ui/compositions/data-grid-column-visibility`
+
+Dropdown of checkbox items that show/hide the hideable columns of a TanStack Table.
+
+Only lists columns with an accessor that report `getCanHide()`, labelling each from `columnDef.meta.headerTitle` (falling back to the column id). Toggling a column keeps the menu open so several can be flipped at once.
+
+- Pass the TanStack `table` instance directly (this part does NOT read DataGrid context) plus a `trigger` element rendered via `render` - supply your own `Button`, it renders none.
+- Only accessor columns reporting `getCanHide()` appear; set `enableHiding: false` on a column def to keep it always-visible and out of this menu.
+- Label each column via `columnDef.meta.headerTitle` - the menu falls back to the raw column `id` when it's missing.
+
+## DataGridFilterableHeader
+
+`@instruments/materia-ui/compositions/data-grid`
+
+Unified column header for DataGrid columns. Combines sorting, filtering, search, and tag pills in a single popover.
+
+- Sort-only columns render a plain button with sort toggle.
+- Filter columns open a popover with optional search, facet checkboxes, and sort commands.
+- Tag columns add dismissible pills above the facet list via `showSelectedTags`.
+
+A column whose `header` is plain text gets this automatically: sortable columns sort from it, and `meta.filter` columns filter from it. Render it yourself only from a custom `header` function.
+
+- Prefer a plain-text `header` plus `meta.filter` over rendering this by hand; the table then wires it, and `PageToolbarTableFilters` shows the same choices as chips.
+
+## DataGridPagination
+
+`@instruments/materia-ui/compositions/data-grid-pagination`
+
+Pagination footer for a DataGrid: a rows-per-page select, a range summary, and page navigation. Reads pagination state from the surrounding DataGrid context, so it must be rendered inside a DataGrid provider whose table has a pagination row model.
+
+- Render inside a `DataGrid` whose `table` has `paginatedRowModel: createPaginatedRowModel()` wired - it reads `table.state.pagination` from context and throws outside the provider.
+- For server-side paging, drive the table with `manualPagination` + `pageCount` and a controlled `pagination` state; the range summary uses `recordCount`, so pass the true total, not the page length.
+- Configure page-size choices via `sizes` (not by restyling the select), and localise the range text through the `info` template.
+
+## DataGridTable
+
+`@instruments/materia-ui/compositions/data-grid-table`
+
+Renders the virtualised header and body rows for a DataGrid.
+
+Consumes the surrounding DataGrid context, so it must live inside a DataGrid provider and shell. Rows are windowed with `@tanstack/react-virtual`.
+
+- Render inside `DataGrid` (and its shell) - it calls `useDataGrid()` for the table and layout and throws outside the provider; it takes no `table` prop of its own.
+- Sorting and filtering come from the column definitions: a plain-text `header` sorts on click, and `meta: { filter: true }` adds a values menu. Build the table with `useDataGridTable` and pair it with `PageToolbarTableFilters` / `PageToolbarTableSort` above the grid; all of them share one state.
+- Rows are virtualised, so give each a stable `rowHeight` via `tableLayout` (expanded rows use `expandedRowHeight`) - variable, unmeasured heights make the window jump.
+- Use `DataGridTable` for a data-driven grid; for a small static table with hand-authored `<TableRow>`s reach for `Table` instead - no virtualisation or TanStack instance needed.
+
+## defaultRenderImage
+
+`@instruments/materia-ui/compositions/product-card`
+
+Default image renderer: a plain `<img>` that fills its positioned parent.
+
+- In Next.js apps pass `renderImage` wrapping `next/image` - this default skips Next's image optimisation and responsive srcset.
+
+## DeliveryBanner
+
+`@instruments/materia-ui/compositions/delivery-banner`
+
+Full-width strip counting down to today's delivery cut-off and naming where samples will be delivered. Green while there is time, red once less than `urgentWithin` remains.
+
+- Pass `deadline` from the server's cut-off; the banner only counts down and never decides when delivery closes.
+- Give it `onLocationClick` when the address can be changed, so the location becomes a button rather than inert text.
+- Place it full width directly under the header; it switches to its compact layout from its own width, not the viewport's.
+
+## DescriptionDetails
+
+`@instruments/materia-ui/components/description-list`
+
+The `<dd>` value of a description item; with `clampLines` it truncates and reveals a More/Less toggle once the content overflows. Import from "@instruments/materia-ui/components/description-list".
+
+- Values are end-aligned by default so they line up against the terms; set `align="start"` for long prose values, where a ragged left edge is hard to read.
+
+## DescriptionList
+
+`@instruments/materia-ui/components/description-list`
+
+A `<dl>` that lays out term/description pairs in a grid. Import from "@instruments/materia-ui/components/description-list".
+
+- Fill it with `DescriptionItem` rows (each a `DescriptionTerm` + `DescriptionDetails`) - it renders a real `<dl>`, so keep the `dt`/`dd` semantics rather than nesting raw divs.
+- Use this for read-only key/value metadata about one entity; for tabular rows of many records reach for `Table` or `DataGrid` instead.
+- Turn on `showSeparators` when items are visually dense; leave it off inside a bordered `Card` where the container already frames them.
+
+## Dialog
+
+`@instruments/materia-ui/components/dialog`
+
+Root component for a modal dialog. Manages open/closed state and accessibility. Import from "@instruments/materia-ui/components/dialog".
+
+- Use `Dialog` for a centred blocking modal (form, details, footer actions); a destructive confirm is `AlertDialog`, an anchored non-blocking panel is `Popover`.
+- A panel that slides in from a screen edge is a `Sheet` (or `Drawer` for a drag-to-dismiss bottom sheet), not a `Dialog`.
+- Always render a `DialogTitle` (wrap in `sr-only` if visually hidden) so the modal is announced; `DialogContent` uses the 36px `--radius-modal` corner.
+
+## DialogContent
+
+`@instruments/materia-ui/components/dialog`
+
+Centred modal panel. Renders its own portal and scrim overlay, so it does not need to be wrapped in `<DialogPortal>` or `<DialogOverlay>` - place it directly inside `<Dialog>`. Outside-press and Escape dismissal are handled on the root: read `eventDetails.reason` in `Dialog`'s `onOpenChange` and call `eventDetails.cancel()` to veto one. Import from "@instruments/materia-ui/components/dialog".
+
+- Use `size="viewport"` for a dialog that holds a whole view (a product quick view, a large preview); it sets only the geometry, so lay the panel out as a column with a scrolling body yourself or compose `QuickView`.
+
+## DocumentList
+
+`@instruments/materia-ui/compositions/document-list`
+
+Composable list for displaying files and documents with icons, titles, metadata, and actions; supports optional multi-select via `selectable`. Import from "@instruments/materia-ui/compositions/document-list".
+
+- Fill it with `DocumentListItem` children - the root is a `<ul>` provider; each item's `value` is what `value`/`defaultValue` selection matches against.
+- Set `selectable` to reveal per-item checkboxes and drive selection via `value`/`onValueChange` (a `string[]`) - don't add your own checkboxes.
+- Use this for files/documents with icon + metadata + actions; for a generic single-line row reach for `Item`/`ItemGroup`, and for tabular columns use `Table`.
+
+## DocumentListCheckbox
+
+`@instruments/materia-ui/compositions/document-list`
+
+Checkbox that automatically connects to DocumentList selection. Must be placed inside a DocumentListItem with a value prop, or provide a value prop directly.
+
+- Give each checkbox an `aria-label` naming its document, or use `aria-labelledby` to reference the visible DocumentListTitle.
+
+## Dot
+
+`@instruments/materia-ui/components/dot`
+
+Dot component for indicating status, colour, or presence. Uses semantic design token variants by default, with optional custom colour override.
+
+- Use `Dot` for a bare colour/status indicator with no text; if you need a label or count, reach for `Badge` (or `BadgeDot`), and for a removable/interactive chip use `Tag`.
+- Prefer the semantic `tone` (`success`/`warning`/`danger`/…) over a raw `color` so the dot tracks theme tokens; reserve `color` for swatches outside the palette.
+- The dot is decorative - pair it with visible text or an `aria-label`; colour alone doesn't convey status to assistive tech.
+
+## DotMatrixLoader
+
+`@instruments/materia-ui/components/dot-matrix-loader`
+
+Intent-specific dotted SVG glyph for agent status slots (a prompt bar's leading icon, a working stack, an operation bubble).
+
+- Pick a glyph by intent from `DOT_MATRIX_LOADERS` - don't invent ad-hoc names. Map product actions → names in one place.
+- Pass `settled` when the op finished but narration is still on screen, so the slot stays in character without spinning forever.
+
+## Drawer
+
+`@instruments/materia-ui/components/drawer`
+
+Root component for a drawer (mobile-friendly slide-up panel). Manages open/closed state; `swipeDirection` sets the edge it slides from and the direction that dismisses it (`"down"` for a bottom drawer, the default). Pass `container` to portal the drawer (and its scrim) into a bounded element instead of the document body - used by the mobile-nav overlay to scope the drawer to its own layer. Import from "@instruments/materia-ui/components/drawer".
+
+- Drawer is the touch-first slide-up panel - reach for `Sheet` for desktop side panels and `Dialog` for centred modals.
+- Always render a `DrawerTitle` inside `DrawerContent` (sr-only if visually hidden) - the underlying primitive uses it for `aria-labelledby`.
+- Pass `container` to scope the drawer and its scrim to a bounded element instead of the viewport (the mobile-nav overlay pattern).
+
+## DrawerContent
+
+`@instruments/materia-ui/components/drawer`
+
+Sliding panel body - renders its own portal and scrim overlay, so drop it directly under `Drawer` without composing `DrawerPortal`/`DrawerOverlay`.
+
+Bottom slide-up by default, with a drag handle unless `showHandle={false}`. For another edge, set `swipeDirection` on `Drawer` and position the panel with `className`. Positioning is viewport-fixed by default. When `Drawer` receives a bounded `container`, content and scrim switch to `absolute` so they stay inside that surface. The radius/border classes are plain (not direction-gated) so consumers can cancel them with `rounded-none` / `border-t-0` via tailwind-merge - full-screen sheets rely on this.
+
+- Always render a `DrawerTitle` (use `sr-only` if visually hidden) - it provides the panel's `aria-labelledby`.
+- For full-screen sheets, cancel the corner with `className="rounded-none border-t-0"` and pass `showHandle={false}`.
+- To scope the drawer to a bounded element (not the viewport), pass `container` to the `Drawer` root; the content and scrim are `absolute` so they stay within it.
+
+## DropdownMenu
+
+`@instruments/materia-ui/components/dropdown-menu`
+
+Menu of actions or options, opened from a trigger. Supports nested submenus, checkbox/radio items, separators, and keyboard shortcuts. Open state is uncontrolled by default; pass `open`/`onOpenChange` to control it.
+
+- Use `DropdownMenu` for a menu opened by clicking a trigger; a right-click / long-press menu is a `ContextMenu`.
+- It's an actions / options menu, not a form control - to choose a value use `Select` (styled) or `Combobox` (searchable), not menu rows.
+- Reach for `DropdownMenuCheckboxItem` / `DropdownMenuRadioItem` for stateful rows; `DropdownMenuContent` portals to the body.
+
+## EasingCurve
+
+`@instruments/materia-ui/components/easing-curve`
+
+A static visualisation of a cubic-bézier easing curve, drawn as an SVG bézier inside a unit box - time runs left→right, progress runs bottom→top. The solid stroke inherits `currentColor` (set the SVG's text colour via `className`); the optional dotted diagonal is the linear baseline the curve bends away from. Sizing is entirely `className`-driven, so the same primitive serves a tiny preview and a full row. The DS home for easing SVGs - the app never draws raw `<svg>`.
+
+- Render easing previews through `EasingCurve`, never a hand-rolled `<svg>` - it's the design-system home for curve visualisations (consistent unit box, baseline, stroke).
+- Colour the curve with a `text-*` class (it strokes `currentColor`) and size it purely via `className` - the same primitive scales from a tiny preview to a full row.
+- Always pass a meaningful `title` - it becomes the SVG `<title>`, the curve's only accessible name.
+
+## EditorialCard
+
+`@instruments/materia-ui/compositions/editorial-card`
+
+Renders an editorial content card in one of several layout variants, composing imagery, title, and subtitle into a single linkable promotional tile.
+
+- Match the media prop to `variant`: `ticker`/`stack` consume `images[]` (stack uses the first three), while `media` uses `imageSrc`/`videoSrc` - passing the wrong one renders empty media.
+- Pass `renderImage` (wrapping `next/image`) in Next.js - the default is a plain `<img>` and skips Next optimisation; give `media` images a meaningful `alt`.
+- Set `href` to make the whole card a single link (it wraps in an `<a>`); don't nest additional links/buttons inside - use `EditorialCard` for promo tiles, plain `Card` for neutral content.
+
+## Empty
+
+`@instruments/materia-ui/components/empty`
+
+Empty state root container.
+
+- Use `Empty` for "no data / nothing here"; a failure the user can retry is an `ErrorState` (which composes `Empty`), so don't hand-roll a retry empty.
+- Compose `EmptyHeader` › `EmptyMedia` + `EmptyTitle` + `EmptyDescription`, and put the call-to-action in `EmptyActions`.
+
+## EmptyState
+
+`@instruments/materia-ui/compositions/empty-state`
+
+Generic empty state, composed on `Empty`. Replaces the per-feature "nothing here" implementations with one flat-props preset: an icon (or custom media), a title, optional description, and optional actions.
+
+- Use `EmptyState` for "no data / nothing here"; a failure the user can retry is an `ErrorState` (which also composes `Empty`), so don't hand-roll a retry empty.
+- Set `level` to keep the document outline gapless where you place it - a full-page empty near an `h2` wants `level="3"`, but a nested one may need `"4"`.
+
+## ErrorBoundary
+
+`@instruments/materia-ui/components/error-boundary`
+
+Generic error boundary that prevents a crashing subtree from taking down the rest of the page. Reporting is delegated to `onError` (no hardcoded logging), and recovery is available through `reset` on a render-prop `fallback`.
+
+- `ErrorBoundary` catches render crashes in a subtree - pair it with an `ErrorState` in `fallback` to show the failure; it renders nothing by default.
+- It logs nothing itself - wire telemetry through `onError`, and offer recovery via the render-prop `fallback`'s `reset` callback.
+
+## ErrorState
+
+`@instruments/materia-ui/compositions/error-state`
+
+Generic error state, composed on `Empty`. Replaces the five per-feature "something went wrong" implementations with one primitive: an icon, a title, an optional message, and an optional retry action.
+
+- `ErrorState` renders a failure UI (icon / title / message / retry) but does not catch errors - wrap the throwing subtree in an `ErrorBoundary` and render this in its `fallback`.
+- Pass `retry` to show the retry button (omit it to hide); it's built on `Empty`, so `layout` / `minHeight` props pass straight through.
+
+## ExpandableText
+
+`@instruments/materia-ui/components/expandable-text`
+
+Long copy clamped to a fixed height that fades out at the cut, with a More/Less toggle that animates it open. The toggle only appears when the content actually overflows.
+
+- Use it for secondary prose such as a product description or a review; keep headings and anything the reader must see outside it.
+- Set `collapsedHeight` in rem to a whole number of lines at the text's line height, so the cut lands between lines.
+- Reach for `Collapsible` when the hidden part is separate content behind a labelled trigger rather than the rest of one passage.
+
+## ExpandButton
+
+`@instruments/materia-ui/components/expand-button`
+
+Small square toggle button for expand/collapse actions; shows Plus when collapsed and Minus when expanded, and reflects state via `aria-expanded`. Import from "@instruments/materia-ui/components/expand-button".
+
+This is an icon-only control, so pass an `aria-label` (or `aria-labelledby`) describing the action (e.g. "Expand row") - without it screen readers announce an unlabelled button.
+
+- Always pass an `aria-label` (e.g. "Expand row") - it's icon-only, so without one screen readers announce an unlabelled button.
+- Drive the icon and `aria-expanded` with the `expanded` prop; set `expandedIcon`/`collapsedIcon` only to override the default Minus/Plus pair.
+
+## FadeOverlay
+
+`@instruments/materia-ui/components/fade-overlay`
+
+Fades a decorative overlay (a border beam, a shine sweep, …) in and out with `visible`, keeping it MOUNTED through its fade-out exit so the overlay's animation rAF loop survives until the fade completes - then unmounts it. Honours `prefers-reduced-motion` by rendering nothing but `children` (a static decorative band would read louder than the animation it replaces).
+
+Use as a wrapper (pass `children`) or a bare overlay (omit them). This is the shared exit-animation lifecycle that backs `BorderBeam` and `Shine`.
+
+- Reach for `FadeOverlay` to fade a decorative overlay in/out - it keeps the overlay mounted through its fade-out so the animation's rAF loop survives, then unmounts it; don't hand-roll that lifecycle.
+- It's the shared engine behind `BorderBeam` and `Shine` - prefer those named components for their specific looks; drop to `FadeOverlay` directly only for a new overlay effect.
+- Needs `ReducedMotionProvider`; under reduced motion it renders only `children` (a static band would read louder than the animation), so the overlay doesn't appear.
+
+## Field
+
+`@instruments/materia-ui/components/field`
+
+Flexible field container (Base UI `Field.Root`) that arranges label and content in various orientations. Its parts wire themselves to the control: `FieldLabel` gets `htmlFor`, and `FieldDescription`/`FieldError` join the control's `aria-describedby`.
+
+- Set `invalid` on the `Field`, not on each control - it sets `aria-invalid` on the field's `Input`/`InputGroupInput`/`Textarea` and turns the `FieldLabel` destructive.
+- Compose the documented parts (`FieldLabel`, `FieldContent`, `FieldError`, `FieldDescription`) around one control - the label's `htmlFor` and the control's `aria-describedby` are wired for you, so there are no ids to pass.
+- Use `orientation="responsive"` for a label-beside-control that collapses to stacked on mobile, rather than duplicating the field per breakpoint.
+
+## FileUploadDropzone
+
+`@instruments/materia-ui/compositions/file-upload`
+
+FileUploadDropzone - A drag-and-drop zone for file uploads. Use with the useFileUpload hook for full functionality.
+
+- `FileUploadDropzone` is presentational - wire it to the `useFileUpload` hook for the actual file input, drag state, and file list; it stores nothing itself.
+- Forward the hook's `handleDragEnter/Leave/Over/Drop` and drag state into `dragging` so the drag styling matches the real drop-target state.
+- Keep `title`/`description` (accepted types, size limit) accurate - they are the zone's only affordance copy; override the whole body via `children` when needed.
+
+## Flex
+
+`@instruments/materia-ui/components/flex`
+
+Flexbox container with token-driven direction, alignment, justification, wrapping, and gap.
+
+Layout props (`direction`, `justify`, `align`, `wrap`, `gap`) accept a single value or a per-breakpoint responsive object like `{ base: "column", md: "row" }`; set `responsiveMode` to `"container"` to resolve breakpoints against the nearest container instead of the viewport.
+
+- `Flex` exposes full flexbox (`direction`/`justify`/`align`/`wrap`) and defaults to a row; for a simple gapped column reach for `Stack`, for a wrapping cluster `Group`.
+- Every layout prop takes a responsive object like `{ base: "column", md: "row" }`; set `responsiveMode="container"` to resolve breakpoints against the nearest container.
+- `as` and `render` are mutually exclusive (`render` wins, dev-warned); `as` draws from the closed layout vocabulary, so `as="button"` is a type error (use `Button`).
+- Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+
+## FolderTile
+
+`@instruments/materia-ui/compositions/folder-tile`
+
+Animated folder button showing a fanned preview of up to three materials, an opening flap, selected styling, and an optional hover action slot.
+
+Visual state is derived from `materials` unless `state` is set; the folder leans open on hover (`openOnHover`) or when forced open as a drop target (`open`). All motion collapses to instant under reduced-motion preferences.
+
+- Only the first three `materials` render in the fan; pass `itemCount` when the real total differs, otherwise the count shows `materials.length`.
+- Supply `renderImage` in Next.js so previews go through `next/image` - the default renders plain `<img>` from each material's `src`/`alt`.
+- Drive drag-and-drop drop-target styling with `open` (forces the open look without revealing the action); use `selected`+`showSelectedState` for selection, not manual classes.
+- `FolderTile` is itself the button - pass `name`/`onClick` and button props directly; don't wrap it in another `<button>`/`<a>`.
+
+## GalleryImage
+
+`@instruments/materia-ui/components/gallery`
+
+Gallery image that handles variant changes with crossfade. Shows old image + shimmer while new image loads, then crossfades.
+
+Framework-agnostic: uses a render prop to let you provide any image component.
+
+- In Next.js pass a `children` render prop wrapping `next/image` and thread its `src`+`className` through - the default renderer is a plain `<img>` that skips Next optimisation.
+- When you omit `children`, `alt` is required (a dev warning fires otherwise); pass `alt=""` to mark the image decorative. `alt` is ignored once a render prop supplies its own image.
+- Drive variant switches by changing `src` - that triggers the built-in crossfade + shimmer; don't unmount/remount `GalleryImage` per variant or you lose the transition.
+- Position `GalleryImage` inside a `relative` container with fixed dimensions - the surfaces are `absolute inset-0`, so an unsized parent collapses to zero height.
+
+## Grid
+
+`@instruments/materia-ui/components/grid`
+
+CSS Grid layout with configurable columns, gaps, and alignment; `columns`, the gaps and the alignment props accept a responsive object keyed by breakpoint. Compose column spans with `GridCol` children.
+
+- `Grid` gives full 2-D control - compose `GridCol` children with `span`/start/order; if you only need equal-width responsive columns, `SimpleGrid` is lighter.
+- `columns`, `gap`, and alignment each accept a per-breakpoint object; `responsiveMode="container"` resolves them against the nearest container query.
+- For a grid whose tracks come from its own className or its children (`grid-cols-[...]`, `grid-flow-col`), pass `columns="none"`: it emits no column classes and no default alignment. `"none"` is a whole value, not a breakpoint key. `inline` (a boolean) renders `inline-grid`.
+- `as` and `render` are mutually exclusive (`render` wins, dev-warned); `as` draws from the closed layout vocabulary, so `as="button"` is a type error (use `Button`).
+- Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+
+## GridCol
+
+`@instruments/materia-ui/components/grid`
+
+A column within a `Grid` that sets its span, start position, and order; each of these accepts a responsive object keyed by breakpoint.
+
+- `as` and `render` are mutually exclusive (`render` wins, dev-warned); `as` draws from the closed layout vocabulary.
+- Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+
+## Group
+
+`@instruments/materia-ui/components/group`
+
+Horizontal flex container for grouping related elements with consistent spacing.
+
+- `Group` is a horizontal cluster of related controls (buttons, chips) that can `wrap`; for a vertical stack use `Stack`, for full flex control use `Flex`.
+- Control horizontal distribution with `position` (its justify prop) and vertical alignment with `align`; both `gap` and `wrap` accept per-breakpoint objects.
+- `as` and `render` are mutually exclusive (`render` wins, dev-warned); `as` draws from the closed layout vocabulary, so `as="button"` is a type error (use `Button`).
+- Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+
+## Heading
+
+`@instruments/materia-ui/components/heading`
+
+Renders a semantic heading element with configurable level and size. `size` names a type role and accepts responsive values: `size={{ base: "heading-sm", md: "heading-lg" }}`.
+
+- Set `level` (`h1`–`h6`) for the document outline and `size` for visual scale independently - don't pick a tag just to get a size; a small-looking heading can still be an `h2`.
+- Keep one `h1` per page and don't skip levels for styling; use `size` (responsive-capable) to make a lower-level heading look larger.
+
+## HotspotIndicator
+
+`@instruments/materia-ui/components/hotspot-indicator`
+
+Animated hotspot dot (outer ring + inner dot) for marking locations on images.
+
+Positioned absolutely by percentage (`centerX`/`centerY`), so it needs a positioned parent. Hover and active states are controlled by the parent via `hovered`/`active` - the dot grows and the ring pulses in response.
+
+- Place it inside a `position: relative` parent - it positions itself absolutely by `centerX`/`centerY` percentages, so it lands wrong in a static-flow container.
+- State is parent-controlled: pass `hovered`/`active` (plus `onMouseEnter`/`onClick`) - the dot grows and the ring pulses only in response; it tracks nothing itself.
+- Always pass `label` - it's the button's `aria-label` and the hotspot's only accessible name; also mount `ReducedMotionProvider` so the pulse honours the OS motion setting.
+
+## HoverCard
+
+`@instruments/materia-ui/components/hover-card`
+
+Hover-triggered popover for supplementary content (previews, profile cards). Controlled via `open`/`onOpenChange`, or uncontrolled via `defaultOpen`; `HoverCardTrigger`'s `delay`/`closeDelay` (ms) tune the hover-in / hover-out timing.
+
+- Use `HoverCard` for rich hover content (preview, profile card); a one-line hint is a `Tooltip`, a click-opened panel is a `Popover`.
+- It opens on hover / focus only - never hide essential actions or content a touch / keyboard-only user can't otherwise reach behind it.
+- Tune the trigger's `delay`/`closeDelay` (ms) instead of adding your own timers; `HoverCardContent` portals to the body.
+
+## Icon
+
+`@instruments/materia-ui/components/icon`
+
+Renders the given icon as a decorative SVG - always `aria-hidden` and non-focusable, with a fixed 1.5 stroke width.
+
+- Route every lucide/SVG glyph through `Icon` (`<Icon icon={ArrowRight} />`), never the raw component - it fixes the `1.5` stroke and size scale so icons stay consistent.
+- `Icon` is always `aria-hidden` + non-focusable - pair it with visible text or give the interactive parent an `aria-label`; never rely on it to name a control.
+- Size with the `size` token (`"sm"`,`"lg"`…), not `className="size-6"` - the scale maps to the shared `ComponentSize` steps other components align to.
+
+## IconBox
+
+`@instruments/materia-ui/components/icon-box`
+
+Renders an icon inside a styled surface box - for empty states, feature highlights, and status indicators. Icon size defaults to the box size. Import from "@instruments/materia-ui/components/icon-box".
+
+- Reach for `IconBox` for a framed-icon surface (empty states, feature highlights) instead of wrapping `Icon` in a hand-styled `div` - it owns the size→radius and box→icon-size pairings.
+- Set colour via `tone`, not a hex/`bg-*` className - `tone` carries the paired surface+foreground tokens, including the dark-mode variants.
+- Let `iconSize` default from the box `size`; override only when the glyph must break the built-in `BOX_TO_ICON_SIZE` ratio.
+
+## IconCard
+
+`@instruments/materia-ui/components/icon-card`
+
+A selectable card pairing an icon over a label, for option pickers such as property-type or category choices; renders a native button and forwards its props.
+
+- `IconCard` is itself a native `<button>` - wire `selected`/`onClick` and drive a single-select group in state; don't nest it in another button or anchor.
+- Pass a Lucide component to `icon` (e.g. `HomeIcon`), not a rendered element `<HomeIcon />` - it is handed to the internal `Icon` for consistent sizing/stroke.
+- Use `IconCard` for compact icon-over-label option pickers (property type, category); for a content container with header/body reach for `Card`, and for a settings row use `SettingsCard`.
+
+## IconMorph
+
+`@instruments/materia-ui/components/icon-morph`
+
+Icon with blur-crossfade morph animation between icon changes.
+
+Drop-in replacement for Icon when you need animated transitions. The icon stays in place while crossfading with a blur effect.
+
+- Change `morphKey` whenever `icon` changes (e.g. play↔pause) - the crossfade is keyed off it, so a stale key swaps the new glyph in with no morph.
+- Use it as the animated drop-in for `Icon`; for a plain static glyph stay on `Icon` and skip the extra `AnimatePresence`/motion cost.
+- Needs `ReducedMotionProvider` for the blur-crossfade to run and honour reduced motion; like `Icon` it renders `aria-hidden`, so name the control elsewhere.
+
+## IdentifiedSurfaceFrame
+
+`@instruments/materia-ui/components/identified-surface`
+
+High-contrast brackets and disclosure frame for an object identified inside an image or document. Resting corners preserve the evidence geometry; highlight and active states reveal the complete frame and compact label.
+
+- Position this over the exact identified bounds inside a relative container; inflate the bounds outside this component when the source geometry is smaller than a comfortable pointer target.
+- Pair it with a real button or link. This component is deliberately pointer-transparent and carries no interaction semantics of its own.
+
+## Input
+
+`@instruments/materia-ui/components/input`
+
+Simple standalone input field (Base UI `Input`). Inside a Field it is the field's control: the FieldLabel targets it, FieldDescription/FieldError describe it, and it inherits the field's invalid state (`aria-invalid`). `hasError` forces error styling and `aria-invalid` on a standalone input. For inputs with icons, addons, or buttons, use InputGroup.
+
+- For icons, addons, prefixes, or trailing buttons use `InputGroup`, not `Input` plus manually absolute-positioned decorations.
+- Inside a `Field`, let invalid state cascade - omit `hasError`; pass `hasError` only to force error styling on a standalone `Input`. An invalid `Field` keeps `aria-invalid` on its control even with `hasError={false}`.
+- Give every `Input` an associated label - inside a `Field` a `FieldLabel` targets it with no ids to wire; standalone, point a `Label`'s `htmlFor` at its `id`. A placeholder is not an accessible name.
+- `size` defaults to `"xl"` (48px); pass a responsive object like `{ base: "sm", md: "xl" }` rather than swapping components per breakpoint.
+
+## InputCard
+
+`@instruments/materia-ui/components/input-card`
+
+Primitive selectable card used as the base for RadioCard and CheckboxCard.
+
+Purely presentational - the parent owns `selected` and click handling. Selection and disabled states are exposed as `data-selected`/`data-disabled` for styling.
+
+- `InputCard` is a presentational primitive - the parent owns `selected` and click handling; for real form semantics use `RadioCardGroup`/`CheckboxCardGroup`, which build on it.
+- Drive the selected look via the `selected` prop (it sets `data-selected` + the primary tint), not by appending your own active classes.
+- Use `render` to project the card styling onto a real interactive element (e.g. a `<label>` wrapping an input) when you need native selection behaviour.
+
+## InputGroup
+
+`@instruments/materia-ui/components/input-group`
+
+Composition container for inputs with addons, icons, and buttons. Distributes size/radius/disabled to its children via context, and inherits invalid state from an ancestor Field unless `hasError` is set explicitly. Import from "@instruments/materia-ui/components/input-group".
+
+- Compose with the `InputGroup*` parts (`InputGroupInput`, `InputGroupIcon`, `InputGroupAddon`, `InputGroupButton`) - a raw `<input>` won't receive the shared size/radius/disabled context.
+- Set `size`/`radius`/`disabled` once on `InputGroup`; children inherit them via context, so don't re-set them per child.
+- Inside a `Field` the group inherits invalid state and its `InputGroupInput`/`InputGroupTextarea` becomes the field's control (labelled, described, `aria-invalid`) - pass `hasError` only to force error styling and `aria-invalid` independently.
+
+## InputOTP
+
+`@instruments/materia-ui/components/input-otp`
+
+One-time password input component for verification codes.
+
+- Set `length` to the code length and render exactly that many `InputOTPSlot`s - slots take their position from their order in the tree, so there is no `index` prop.
+- Drive it controlled with `value`/`onValueChange` (a plain string), or react to `onValueComplete` once the string reaches full `length`.
+- Characters are filtered by `validationType` (`"numeric"` by default; `"alpha"`, `"alphanumeric"` and `"none"` are also available) - pass `"alphanumeric"` for codes that contain letters.
+- Split slots into `InputOTPGroup`s with an `InputOTPSeparator` between them for visual grouping only - it does not change the underlying value.
+
+## Item
+
+`@instruments/materia-ui/components/item`
+
+Item is a standalone component for displaying a single piece of content. Use with ItemContent, ItemTitle, ItemDescription, etc. for structured content.
+
+- Structure content with `ItemContent`/`ItemTitle`/`ItemDescription` (plus `ItemMedia`/`ItemActions`) rather than raw divs - the compound parts carry the gap and truncation rhythm.
+- Wrap a set of items in `ItemGroup` and set the look via its `variant` (`divided`/`separated`/`grouped`) - `Item` adapts automatically, so avoid re-styling borders/backgrounds per item.
+- Use `render` to make the whole item a link/button (e.g. `render={<Link href="…" />}`); the item's children become the link's content.
+- Reach for `Item` for generic single rows; for files/documents use `DocumentList`, and for term/value metadata use `DescriptionList`.
+
+## Kbd
+
+`@instruments/materia-ui/components/kbd`
+
+Keyboard key indicator for displaying keyboard shortcuts.
+
+- Wrap multi-key chords in `KbdGroup` and set `size` on the group - children inherit it via context, so you size the combo once.
+- It renders a semantic `<kbd>`; reserve it for keyboard keys/shortcuts, not as a generic small-label chip (that's `Badge`).
+
+## Label
+
+`@instruments/materia-ui/components/label`
+
+Renders an accessible label element that can be associated with form controls.
+
+- Point `htmlFor` at the control's `id` so clicking the label focuses/toggles it; a `Label` with no association is just styled text.
+- For checkbox/radio rows and fields, prefer `CheckboxField`/`FieldLabel`/`RadioGroupItem`, which generate the `id`/`htmlFor` pairing for you.
+
+## LoadingState
+
+`@instruments/materia-ui/compositions/loading-state`
+
+LoadingState is a full-region blocking loading indicator: a centred spinner (optionally labelled) filling a minimum height.
+
+Prefer `SkeletonText`/`SkeletonRow` for in-place loading inside content that's already on screen - reach for `LoadingState` only when the whole region has nothing else to show yet.
+
+- Reserve `LoadingState` for a whole region / page with nothing to show yet; for in-place loading over existing layout prefer `Skeleton`, and a small inline spinner is `Spinner`.
+- Pass `label` to name the live region for AT; it already renders `aria-live="polite"` with a default "Loading" name, so don't add your own status role.
+
+## LocationInput
+
+`@instruments/materia-ui/components/location-input`
+
+Location autocomplete input with a dropdown of suggestions for city or address search. The geocoder is injected: pass `search` (query to suggestions) and `resolve` (suggestion to full `Location`). Queries are debounced by 300ms and start at two characters.
+
+- `search` and `resolve` are required - the component has no built-in geocoder. Wrap your provider (Google Places, Mapbox, your own API) in those two functions.
+- `search` may reject; the dropdown then shows no suggestions. Return `null` from `resolve` to ignore a selection.
+- Pick `mode="city"` vs `"address"` to scope the geocoding; drive it controlled via the `Location` `value` + `onChange` (which also fires on clear).
+
+## Logo
+
+`@instruments/materia-ui/components/logo`
+
+Brand mark. Renders the Material Bank logo by default; pass `mark` (and `label`) to show your own. Uses currentColor for fill, so colour can be controlled via text-* classes.
+
+- Recolour the mark with a `text-*` class - it fills from `currentColor`; passing `fill`/a hex defeats the single-source colour and breaks dark-mode inheritance.
+- Size with the `size` preset (`sm`–`xl`), not a `className` width/height - presets keep the mark on the shared `ComponentSize` scale.
+- Don't add your own `aria-label`/`role` - `Logo` already ships `role="img"` + "Material Bank" (change the name with `label`); wrap it in a link only when you need a click target.
+- To use your own brand, pass `mark` as SVG shapes in a 48x48 viewBox filled with `currentColor`, and a matching `label` - don't wrap or overlay the default mark.
+
+## MarqueeText
+
+`@instruments/materia-ui/components/marquee-text`
+
+A clipped single-line label that becomes a hover-triggered marquee when its text is wider than the clip box, and stays a plain truncated label when it fits. On overflow it renders a duplicate `aria-hidden` copy and scrolls the pair for a seamless loop; a `ResizeObserver` on both the clip box and the text node re-measures on resize and on content change, setting `--marquee-duration` / `--marquee-shift`.
+
+Extracted from `product-card-category`'s `CategoryLabel`.
+
+- The scroll is gated on a `.group` ancestor's hover (the `.animate-marquee` utility runs only under `.group:hover`, plus a `data-play="running"` escape hatch) - a lone `MarqueeText` will not animate on its own hover. Wrap it in a `.group` element (typically the hoverable card) to trigger the reveal.
+- It only scrolls when the text overflows; short text that fits stays a static clipped label with no duplicate copy and no animation.
+- Honours `prefers-reduced-motion` automatically via the shared `.animate-marquee` utility, which disables the animation.
+
+## MediaFrame
+
+`@instruments/materia-ui/components/media-frame`
+
+A rounded clip frame for media (image or video). Establishes a `relative overflow-hidden` positioning context and clips its single child to a rounded corner - but it is a dumb box: it does NOT size or cover-fill the child. Give it one media child with `size-full object-cover` (identical contract to `AspectRatio`). Radius, size, and positioning all come from the `className` you pass (`rounded-2xl`, `size-full`, `absolute inset-0`, …) - there is no `radius` prop.
+
+Extracted from the product-card and editorial-card media frames; available to any composition that needs a rounded overflow-clip layer.
+
+- MediaFrame is a dumb clip box - it does not size or cover-fill the child; give it one media child with `size-full object-cover`, like AspectRatio.
+- Set radius, size, and positioning through `className` (`rounded-3xl`, `size-full`, `absolute inset-0`) - there is no `radius` prop.
+- Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+- Set `edge` to frame photography with an inset hairline that stays above the media; do not fake it with a border or an inset shadow on the frame, which the media hides.
+- Reach for `raised` only when the frame sits on the same fill as its surface; in a dense row the edge already separates it.
+
+## MediaFrameEmbed
+
+`@instruments/materia-ui/components/media-frame`
+
+An embedded document (an `<iframe>`) as `MediaFrame` media: borderless, block-level and lazy-loaded by default. Size and any scaling come from the caller - pass a device-sized `style` and a `transform` to preview a page at a real viewport inside a smaller plate.
+
+- A decorative preview belongs inside an `inert` wrapper with the real link beside it, so keyboard and screen-reader users never land inside the embedded page.
+- Always give `title` a name that says what the document is; it is the frame's only accessible name.
+
+## MegaMenu
+
+`@instruments/materia-ui/compositions/mega-menu`
+
+A header's full-width menu of catalogue sections: a trigger in the header opens a sheet beneath the shell's chrome, over a dimmed sidebar and page. It opens on a press, not on hover; Escape, a press on the page or choosing a link closes it, and focus returns to the trigger. Modal by default, so the page behind it is blocked and does not scroll. Import from "@instruments/materia-ui/compositions/mega-menu".
+
+- Use it in a shell whose chrome is lifted (`Sidebar header`, the fixed `SidebarLayoutHeader`): the panel fills the window from the top, beneath the chrome, so the brand row, search and actions stay on top of it.
+- Keep it to navigation. Every entry is a `MegaMenuLink`, which closes the menu as it navigates; actions belong in a `DropdownMenu`.
+
+## Menubar
+
+`@instruments/materia-ui/components/menubar`
+
+Horizontal application menu bar (File / Edit / View). Wraps Base UI Menubar; compose with MenubarMenu for each top-level menu. Open state belongs to each MenubarMenu (`open`/`onOpenChange`); the bar itself has no open-menu value.
+
+- Reserve `Menubar` for a persistent desktop app menu bar; a single click menu is `DropdownMenu`, a right-click menu is `ContextMenu`.
+- Give each top-level label its own `MenubarMenu`, and control a menu's open state on that `MenubarMenu` (`open`/`onOpenChange`) rather than on the bar.
+
+## MenuItem
+
+`@instruments/materia-ui/components/menu-item`
+
+A standalone menu item component for use in popovers, sheets, and custom menus. This is the base component that DropdownMenuItem and other menu items build upon.
+
+- `MenuItem` is the standalone base for custom menus (popovers, sheets); inside a `DropdownMenu` / `ContextMenu` use that family's `*Item` for built-in roving focus.
+- Pass glyphs via the `icon` / `dot` / `avatar` / `kbd` / `suffixIcon` props, not as children - with `render` they render around `children`, which is the label only.
+
+## MobileNavigationAppHeader
+
+`@instruments/materia-ui/compositions/mobile-navigation`
+
+Fixed top app bar for the mobile shell; hidden from `hideFrom` up.
+
+- Inside a `SidebarProvider` frame pass `hideFrom="md"`: the sidebar switches to its desktop rail at md, so the bar should hand over at the same width rather than overlap the rail between md and lg.
+- Set `surface` to the colour of the page under the bar - `card` when the phone's whole screen is the content card (an inset sidebar frame), `background` on a flat (`variant="sidebar"`) frame's page, `muted` on the grey canvas - so content scrolls under it without a seam.
+
+## MobileNavigationHeaderAction
+
+`@instruments/materia-ui/compositions/mobile-navigation`
+
+Fixed-size pill icon button sized for the mobile app bar - 40px tall / 56px wide, so the bar stays visually light at phone widths without becoming a literal white island in dark mode. The tap target is the 40×56 pill itself: a hit-area pseudo-element can't extend it - the Button's `soft` variant is `overflow-hidden` (which clips its own pseudo-elements), and the bar's `gap-1` between pills is too tight for outward extension without overlapping neighbours.
+
+Pass short `children` (a count, say) beside the `icon` and the pill widens from its 56px minimum to fit them, keeping the same height.
+
+- Keep children to a few characters, such as a cart count, and give the action an `aria-label` that says what the number means.
+
+## MobileNavigationRoot
+
+`@instruments/materia-ui/compositions/mobile-navigation`
+
+Full-screen fixed overlay that hosts the mobile navigation; hidden from `lg` up.
+
+Carries modal-dialog semantics: focus is trapped inside the overlay while it is mounted, cycles with Tab, and returns to the trigger once it unmounts. Pressing Escape invokes `onClose`. The accessible name defaults to "Navigation menu" and can be overridden via `aria-label`.
+
+Renders an `m.div`, so consumers can drive enter/exit motion (e.g. a slide) by passing `initial`/`animate`/`exit`/`transition` and wrapping in `AnimatePresence`. With no motion props it renders statically. Horizontal overflow is clipped (`overflow-x-clip`) so a nested drill-in view sliding off-screen never spawns a horizontal scrollbar; vertical content still scrolls.
+
+- Wire `onClose` to your open-state setter - the overlay traps focus and fires it on Escape, but you own mounting/unmounting.
+- It's `role="dialog"`+`aria-modal` and hidden from `lg` up, so pair it with a desktop nav rather than showing both at once.
+- Override the default "Navigation menu" accessible name via `aria-label` when the drawer's purpose is more specific.
+
+## MonthYearPicker
+
+`@instruments/materia-ui/components/month-year-picker`
+
+MonthYearPicker allows selecting a month and year, or choosing "Beyond" / "I'm not sure". Auto-advances to the next step when both month and year are selected.
+
+- `value` is a union - a `Date`, `"beyond"`, or `"unsure"` - so branch on the string sentinels in `onChange` before treating it as a date.
+- Enable the "I'm not sure" escape hatch with `showUnsure` (off by default); `"unsure"`/`"beyond"` only ever arrive when their toggles are shown.
+- Bound the range with `yearsAhead` (from the current year); it auto-advances and commits once both month and year are chosen, so don't add your own "next" control.
+
+## MorphDialog
+
+`@instruments/materia-ui/components/morph-dialog`
+
+Root of a dialog that morphs open from its trigger via a shared-element layout animation - the trigger and the dialog card share a `layoutId`, so Motion tweens position, size, radius, and shadow between them.
+
+Controlled when `open` is passed, otherwise uncontrolled. Provides context to the trigger, content, title, and description parts.
+
+- Reach for `MorphDialog` only when the modal should animate out of its trigger element (shared-layout); a plain centred modal is a `Dialog`.
+- Pass the trigger's `borderRadius` / `boxShadow` via `style` (not `className`) on `MorphDialogTrigger` so Motion can correct their distortion during the morph.
+- Render a `MorphDialogTitle` (use `visuallyHidden` if needed) for the accessible name; mount `ReducedMotionProvider` at the app root since it animates via `m.*`.
+
+## NativeSelect
+
+`@instruments/materia-ui/components/native-select`
+
+Styled wrapper around a real native `<select>`, so it stays controlled and accessible through standard select props (`value`/`defaultValue`/`onChange`) and keeps the platform's keyboard and mobile picker behaviour.
+
+- `NativeSelect` wraps a real `<select>` - use standard `value`/`defaultValue`/`onChange` and `NativeSelectOption`/`NativeSelectOptGroup` children, not `Select` parts.
+- Reach for `NativeSelect` when the native mobile picker and zero-JS behaviour matter; use `Select` when you need custom-rendered option content or styling.
+- It has no built-in label - associate a `Label` via `htmlFor`/`id` for an accessible name.
+
+## NavigationMenu
+
+`@instruments/materia-ui/components/navigation-menu`
+
+Horizontal site navigation whose entries can open dropdown panels of links or rich content. Wraps Base UI NavigationMenu Root; compose with NavigationMenuList and NavigationMenuItem. Which entry is open is uncontrolled by default; pass `value`/`onValueChange` to control it.
+
+- Reserve `NavigationMenu` for site/section navigation with panels; a click actions menu is `DropdownMenu`, a desktop app menu bar is `Menubar`, and simple in-page routed tabs are `TabNavigation`.
+- Keep it uncontrolled unless you must drive it; leave `viewport` on unless you render your own `NavigationMenuViewport` (e.g. to place a `NavigationMenuIndicator` in it).
+
+## PageHeader
+
+`@instruments/materia-ui/compositions/page-header`
+
+Canonical page header - the top of a page, beneath the app's own header. Pass its parts and it lays them out: a breadcrumb or back link, the title with optional media, a count or badge and a subtitle, the page's actions, and a switcher beneath between views of what the page shows. Every part but the title is optional, and a row with nothing in it is not rendered. It says what the page is; the controls that narrow or order a list sit in a `PageToolbar` beneath it.
+
+- Pass `title` and the parts the page has rather than composing rows by hand; the header owns wrapping, truncation and spacing, so every page reads the same.
+- A count belongs in `meta` or `subtitle`, never in the title text; a back link belongs in `breadcrumb`, never in `actions`.
+- `nav` switches between views of the thing the page shows (a pill `TabNavigation` of routes). Type switchers, filters, sort and view belong in a `PageToolbar`, each once.
+- Set `layout="stacked"` and wrap each row in `PageHeaderRow` for multi-row headers; the default `"single"` wraps only when a narrow viewport needs to protect the title or actions.
+- `PageHeader` is the sub-header below the app `HeaderBar`, not the app chrome itself - use `SidebarProvider` with `SidebarInset` or `HeaderBar` for the top-level frame; its `sticky` offset assumes that header is present.
+
+## PageHeaderLead
+
+`@instruments/materia-ui/compositions/page-header`
+
+Primary content slot for a `PageHeader`. Stacks location context such as a breadcrumb above the page title while keeping the whole group aligned with the header actions.
+
+- Keep the current page out of a breadcrumb when the adjacent `PageHeaderTitle` already names it.
+
+## PageToolbar
+
+`@instruments/materia-ui/compositions/page-toolbar`
+
+A page's filter and view bar. It sits beneath the page header and holds to the top of the window, under the app's header, while the page scrolls: the filters on one side, scrolling sideways when there are more than fit, and the sort and view controls on the other. At rest it reads as part of the page; once it is holding, a hairline separates it from the content passing beneath. Import from "@instruments/materia-ui/compositions/page-toolbar".
+
+- Place it straight after the `PageHeader`, in the column that holds the page's content; the title scrolls away and the toolbar stays.
+- Order the leading side the same on every page: `PageToolbarFiltersButton` first, in the `button` slot so it holds still carrying the applied count; then `PageToolbarApplied`, the filters in force with Clear all; then the suggestions.
+- Applied filters always lead, so they never scroll out of view behind suggestions. Pressing a suggestion moves it into the applied group; it is never shown twice.
+- When a filter rail holds the facets, the toolbar still shows what the rail has applied, with no suggestions after it (`separator={false}`).
+- Each facet appears once. A `SegmentedControl` when the facet splits the set and one part is viewed at a time (its counts sum to the total); `PageToolbarFilter` chips when several combine. Never both for the same facet.
+- Keep the actions to `PageToolbarSort`, which names the current order, and a view toggle. Page actions such as export belong in the `PageHeader`.
+
+## Pagination
+
+`@instruments/materia-ui/components/pagination`
+
+Standalone pagination component. Works with any data source - not coupled to react-table.
+
+- Drive it as a controlled control - pass `page`+`totalPages` and update state in `onPageChange`; it holds no internal page state.
+- It is data-source agnostic (not coupled to react-table); for grid paging use the DataGrid's own pagination parts instead.
+- Signal an in-flight jump with `loadingPage={n}` so only that button spins; leave a11y labels to the component (each control is pre-labelled).
+
+## PhoneInput
+
+`@instruments/materia-ui/components/phone-input`
+
+Phone number input with an integrated country selector, built on react-phone-number-input; emits E.164-formatted values via `onChange`.
+
+- `onChange` emits an E.164 string (e.g. `+15550000000`) or `undefined` while the number is incomplete/cleared - store that shape, don't reformat the raw text yourself.
+- Set `defaultCountry` (ISO alpha-2, default `"US"`) for the initial calling code; the integrated country selector then lets users switch.
+- Validate the emitted E.164 value (e.g. via react-phone-number-input's `isValidPhoneNumber`) rather than regex-matching the display text.
+
+## Pill
+
+`@instruments/materia-ui/components/pill`
+
+Pill - internal base component for pill-shaped UI elements.
+
+This is a noop: it applies shared variant styling and renders children. Not intended for direct use in application code. Use Badge (presentational) or Tag (interactive) instead.
+
+- Don't reach for `Pill` in app code - it's the shared styling base; use `Badge` for display-only labels/counts and `Tag` for interactive (clickable/dismissible) chips.
+- `Pill` is presentation-only and has no button semantics or dismiss/click handling - those live on `Tag`; adding `onClick` here yields a non-accessible pseudo-button.
+
+## PixelLoader
+
+`@instruments/materia-ui/components/pixel-loader`
+
+Compact pixel-grid loader with shimmer label.
+
+- Use for inline chat / agent waits. Prefer ThinkingLoader when you have narrated steps; ThinkingOrb for avatar-scale state; DotMatrixLoader for prompt-bar intent glyphs.
+
+## Popover
+
+`@instruments/materia-ui/components/popover`
+
+Root component for a popover (non-modal floating panel). Manages open/closed state.
+
+- Use `Popover` for an anchored non-blocking panel dismissed on outside-click / Esc; a page-blocking modal is a `Dialog`, a menu of actions is a `DropdownMenu`.
+- It's non-modal by default (`modal={false}`) so the page stays interactive - pass `modal` only when you must trap focus and block the background.
+- `PopoverContent` portals to the body; anchor to a non-trigger element with its `anchor` prop.
+
+## PopoverBackdrop
+
+`@instruments/materia-ui/components/popover`
+
+Scrim behind a modal popover, portalled to the body. A press on it closes the popover. Render it alongside `PopoverContent`; position it with `className` when it should leave part of the page, such as a fixed header, uncovered.
+
+- Pair it with `modal` on `Popover`: the scrim says the page is blocked, and only a modal popover blocks it.
+
+## ProductCard
+
+`@instruments/materia-ui/compositions/product-card`
+
+Shared ProductCard component.
+
+This is a presentational component that accepts handlers via props for app-specific behaviour (sidepanels, stores, navigation).
+
+- In Next.js apps pass `renderImage` wrapping `next/image` and `linkAs={Link}` - the defaults are a plain `<img>` and `<a>`.
+- Cart UI renders only when a `renderAddToCart` slot is provided; keep `dragAdapter` referentially stable (module-level constant).
+
+## ProductCardProvider
+
+`@instruments/materia-ui/compositions/product-card`
+
+Context provider for ProductCard. Manages variant selection and provides product data + render seams to children. App-specific behaviour (navigation, cart, drag) is injected via props.
+
+- Pass `renderImage` wrapping `next/image` in Next.js apps - the default renderer is a plain `<img>` and skips Next's optimisation.
+- Keep `dragAdapter` referentially stable (a module-level constant) - an inline factory remounts the image subtree and drops the drag ref mid-drag.
+
+## ProductSpecificationsSelector
+
+`@instruments/materia-ui/compositions/product-specifications-selector`
+
+Renders the stack of variant/filter selector fields for a product so a product configuration can be refined interactively.
+
+The component renders only the field stack - no card, heading, or CTA chrome. Compose those around it (a `Card`, your own title) when a surface calls for a titled panel.
+
+- Drive it as a controlled component: it renders from `filters` and emits `onFilterChange(key, value)` - it holds no internal filter state, so persist the value and feed it back.
+- It renders nothing when there are no `variantOptions` dimensions and no `siblings` with images - supply `siblings`/`siblingsWithAttributes` so single-colourway products still show a fallback thumbnail.
+- Pass `renderImage` (wrapping `next/image`) in Next.js; the default is a plain `<img>`. The component ships bare - wrap it in a `Card` with your own heading when a panel is wanted.
+
+## Progress
+
+`@instruments/materia-ui/components/progress`
+
+Linear progress bar showing completion from 0 to 100; pass `value={null}` for an indeterminate (empty) track. Built on Base UI Progress for accessible semantics.
+
+- Use `Progress` for determinate 0–100 completion (`value={null}` for an indeterminate track); position in a stepped flow is `ProgressDots`.
+- For a ring instead of a bar use `ProgressCircle` - it needs an explicit `label` for its native `<progress>` accessible name.
+
+## ProgressDots
+
+`@instruments/materia-ui/components/progress-dots`
+
+Step progress indicator driven by `current`: completed steps and the current step render as expanded pills, pending steps as small dots. Passing `onDotClick` makes dots interactive step-navigation targets; `labels` surface as hover tooltips.
+
+- Use `ProgressDots` for position in a short stepped flow (wizard, carousel); continuous 0–100 completion is `Progress`.
+- Pass `onDotClick` only when steps are navigable - it turns each dot into a focusable button; `labels` surface as hover tooltips.
+- Mount `ReducedMotionProvider` at the app root - the dots animate via `m.*` (LazyMotion).
+
+## PromptPanel
+
+`@instruments/materia-ui/compositions/prompt-panel`
+
+Floating panel root - a shadowed card that prompts the user to pick an action or describe one. Compose it with `PromptPanelHeader` and `PromptPanelBody` (which stacks `PromptPanelOption`/`PromptPanelFreeform` rows); use `PromptPanelStage` around the body to animate between steps.
+
+- Pass `title` (or an explicit `aria-label`) - the panel is a `role="dialog"` surface floating over other content, so it needs an accessible name of its own.
+- Wrap step transitions in `PromptPanelStage`, not a hand-rolled page swap - it owns the page-slide choreography and the reduced-motion fallback.
+
+## PromptPanelFreeform
+
+`@instruments/materia-ui/compositions/prompt-panel`
+
+The "write your own" row inside a `PromptPanel` - a bordered input for freeform text (leading icon + field + trailing `Kbd`). The row keeps the same border treatment whether focused or not; the inner `<input>` is outline-free so focus never adds a second frame.
+
+- Pair it with `usePromptPanelKeyboard` for the full digit/Enter/Escape/Backspace contract - this component alone only submits on Enter.
+- Leave `placeholder` agent/consumer-supplied copy - don't hardcode "Type your own answer here" at call sites that need different phrasing.
+
+## PromptPanelHeader
+
+`@instruments/materia-ui/compositions/prompt-panel`
+
+Header section of a `PromptPanel`: an optional leading back button and a centred title. Laid out on a three-column grid (`1fr auto 1fr`) so the title stays perfectly centred whether or not the back button is present. The leading slot always reserves `icon-sm` (`size-8`) space so header height does not shift when `showBack` toggles between steps.
+
+- Keep the title short - it has no truncation affordance beyond `truncate`, and the panel is a fixed `w-96`.
+
+## PromptPanelOption
+
+`@instruments/materia-ui/compositions/prompt-panel`
+
+Selectable option row inside a `PromptPanel` - a leading `Kbd` shortcut digit and a label. Full-width, borderless until hover (muted wash), and keyboard selectable via `usePromptPanelKeyboard`'s digit contract.
+
+- Number `shortcut`s 1–9 in row order - `usePromptPanelKeyboard` maps digit keys to that same index.
+- Drive `highlighted` from roving keyboard focus (e.g. arrow-key navigation), not from `:hover` - hover is handled for you.
+
+## PromptPanelStage
+
+`@instruments/materia-ui/compositions/prompt-panel`
+
+Page-slide stage for `PromptPanel` step transitions. Two stacked pages crossfade with an 8px horizontal slide and 3px blur; `data-page` on the container picks the active page. Forward (`direction={1}`) lands on page 2 (enter from the right, exit left); back (`direction={-1}`) lands on page 1 (enter from the left, exit right). Height snaps to the active page - no layout/height morph. Under `prefers-reduced-motion`, CSS disables the transition so the flip is instant. Each page stacks its children with `gap="xs"` (8px).
+
+- Track `direction` alongside `stepKey` in the parent's step state - going deeper is `1`, going back is `-1`; the stage can't infer it from the key alone.
+- Put freeform (and header) inside the stage page for multi-step flows so they participate in the page-slide; a freeform sibling outside Stage stays static and flashes when stage height snaps.
+
+## QuantityControl
+
+`@instruments/materia-ui/components/quantity-control`
+
+A compact quantity control on Base UI `NumberField`: the quantity is a number field that Arrow Up/Down step by one, and the buttons repeat while held. Shows a trash icon when quantity is at minimum and `onRemove` is set, minus icon otherwise.
+
+- Pass `onRemove` when hitting the minimum should delete the item - the decrement button then swaps to a trash icon; without it, decrement just stops at `min`.
+- It's controlled - pass the current `value` and update it in `onIncrement`/`onDecrement`, which fire once per step for clicks, arrow keys and each repeat of a held button. Typing a number is not supported.
+- Tab focuses the quantity itself (the stepper buttons are skipped, as in any number field), announced by its `label`. In a list of lines, pass a `label` naming the item so each field is told apart.
+
+## QuickView
+
+`@instruments/materia-ui/compositions/quick-view`
+
+A centred, near-full-screen dialog that previews one item, typically a product, without leaving the page: a header with the item's name, a muted scrolling body and a footer for its actions. Controlled: the application decides what is shown and when it opens. Escape and a backdrop press close it, and focus returns to the control that opened it, even when a pointer press opened it without focusing that control. Import from "@instruments/materia-ui/compositions/quick-view".
+
+- Keep the last viewed item in state after closing, so the panel does not empty while it animates out.
+- Put the item's name in `QuickViewHeader`; it is the dialog's accessible name.
+- Offer a way to the full page in the header's `actions` - a quick view previews, it does not replace the detail page.
+- A panel that docks beside the page (a cart) is a `Sidepanel`, not a quick view.
+
+## QuickViewDetails
+
+`@instruments/materia-ui/compositions/quick-view`
+
+The details column: a stack of flat cards on the body's muted surface. It is its own container, so cards adapt to the column's width rather than the dialog's. Import from "@instruments/materia-ui/compositions/quick-view".
+
+- Fill it with `Card shadow={false}` sections - the item's name and main action first, then specifications - so they stand forward of the muted body without a shadow each.
+
+## QuickViewLayout
+
+`@instruments/materia-ui/compositions/quick-view`
+
+The quick view's two columns, mirroring a product page: media on the left, details on the right, from md up; stacked below md. Place a `QuickViewMedia` and a `QuickViewDetails` inside `QuickViewBody`. Import from "@instruments/materia-ui/compositions/quick-view".
+
+- Key the layout by the item's id, so swapping items inside an open quick view remounts its images instead of showing the previous bitmap while the next loads.
+
+## Radio
+
+`@instruments/materia-ui/components/radio`
+
+Individual radio button. Must be used within a RadioGroup.
+
+- A `Radio` only works inside a `RadioGroup` (it renders a Base UI `Radio.Root`) - the group owns selection; a standalone `Radio` won't toggle.
+- Give every `Radio` a unique `value` and pair it with a `Label` - or use `RadioGroupItem`, which bundles the radio and its wired label.
+- For selectable-card options rather than plain dots, use `RadioCardGroup`.
+
+## RadioCardGroup
+
+`@instruments/materia-ui/components/radio-card`
+
+Radio group whose options are full-size selectable cards (Base UI RadioGroup). Each `RadioCard` is itself the radio, so the group is one tab stop and the arrow keys move the selection between cards.
+
+Shares `size`/`icon`/`indicatorSide`/`showIndicator` with every `RadioCard` through context, so set them once here. Controlled via `value`/`onValueChange`, uncontrolled via `defaultValue`; `layout` picks a stacked grid or an inline wrap.
+
+- Use `RadioCardGroup` for single-select cards and `CheckboxCardGroup` for multi-select - a radio group enforces exactly one choice.
+- Set `size`/`icon`/`indicatorSide`/`showIndicator` once on the group; each `RadioCard` reads them from context - don't repeat per item.
+- Drive selection with `value`/`onValueChange` (controlled) or `defaultValue` (uncontrolled); use `layout="inline"` for a wrapping row instead of the stacked grid.
+- Label the group (e.g. `aria-label` or a `Field` with a `FieldLabel`) - Tab lands on the selected card and the arrow keys move between cards.
+
+## RadioGroup
+
+`@instruments/materia-ui/components/radio-group`
+
+Container for a group of radio buttons. Manages single selection state.
+
+- Use `RadioGroup` for one choice among a small closed set; for many searchable options use `Select`/`Combobox`, and for on/off use `Switch`/`Checkbox`.
+- Drive selection with `value` + `onValueChange` (controlled) or `defaultValue` (uncontrolled) - don't set both on the same group.
+- Prefer `RadioGroupItem` (radio + wired `Label`) over hand-pairing `Radio` and `Label`; it auto-generates the `id`/`htmlFor` link.
+
+## ReducedMotionProvider
+
+`@instruments/materia-ui/components/motion-config`
+
+App-level motion provider. Place once in each app's root layout to cover all animated descendants. It does two things:
+
+1. `MotionConfig` respects the user's `prefers-reduced-motion` OS setting.
+2. `LazyMotion` loads the animation feature bundle (`domMax`) as one shared, code-split chunk, so
+
+- Mount `ReducedMotionProvider` once in each app's root layout, wrapping everything - every
+- It's required app-side, not inside
+- Rely on it (not per-component code) for reduced motion: its `MotionConfig reducedMotion="user"` honours the OS setting for all descendants.
+
+## RequirementItem
+
+`@instruments/materia-ui/components/requirement-item`
+
+Displays a requirement item with a check/x icon indicating met/unmet status. Useful for password requirements, form validation lists, etc.
+
+- Use one `RequirementItem` per rule in a checklist (password/validation criteria); drive `met` from live validation so the check/x icon updates as the user types.
+- Render several in a vertical list and give it an accessible grouping (e.g. `aria-live` region) so screen readers announce requirements flipping to met.
+- Reach for `RequirementItem` for pass/fail checklist rows; for a generic list row use `Item`, and for form field errors use the field's own error message.
+
+## ResizablePanelGroup
+
+`@instruments/materia-ui/components/resizable`
+
+Container that lays out resizable panels along a single axis.
+
+Wraps `react-resizable-panels` `Group`, exposing shadcn's `direction` prop (mapped to the library's `orientation`). Compose with `ResizablePanel` children separated by `ResizableHandle`.
+
+- Compose `ResizablePanel` children separated by `ResizableHandle` - a handle between panels is what makes them draggable.
+- Set the axis with `direction` (`horizontal`/`vertical`); it maps to the library's `orientation`, which is intentionally not exposed.
+
+## Scrim
+
+`@instruments/materia-ui/components/scrim`
+
+A directional gradient overlay that darkens one edge of its container, fading to transparent - used to keep light-on-image text (captions, labels, stats) legible over a photo.
+
+Place inside a `position: relative` ancestor. Purely decorative: renders `aria-hidden` and ignores pointer events.
+
+- `Scrim` is a decorative gradient for text-over-image legibility, not a modal backdrop - dialog / sheet dimming is built into those components.
+- Place it inside a `position: relative` ancestor; it renders `aria-hidden` and ignores pointer events, so it never blocks the content beneath.
+
+## ScrollArea
+
+`@instruments/materia-ui/components/scroll-area`
+
+Scrollable container with custom design-system scrollbars. `children` are placed inside a Base UI viewport, so give the root (or `viewportClassName`) an explicit height/width for scrolling to engage. Import from "@instruments/materia-ui/components/scroll-area".
+
+- Give the root (or `viewportClassName`) an explicit height/width - without a bounded size the content never overflows and the custom scrollbar never engages.
+- `ScrollArea` renders its own `ScrollBar`; reach for `ScrollBar` directly only when hand-composing a Base UI scroll area.
+- Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+
+## ScrollFade
+
+`@instruments/materia-ui/components/scroll-fade`
+
+A gradient fade overlay for scroll containers. Place inside a relatively positioned container to indicate more content.
+
+- Drop `ScrollFade` inside a `position: relative` scroll container instead of hand-writing a gradient - it renders the masked scrim for you (it's `aria-hidden`, purely decorative).
+- Match `theme` to the container's actual background (`card`/`popover`/…) - the scrim fades to that colour, so a mismatch leaves a visible seam.
+- Set `position` (`start`/`end`) and `orientation` to the edge with hidden content - `end`+`vertical` is the common "more below" bottom fade.
+
+## ScrollFrame
+
+`@instruments/materia-ui/components/scroll-frame`
+
+A scrolling region that shows where there is more: each edge fades only while content runs on past it, and optional buttons step through it. Adapted from
+
+- Reach for `ScrollFrame` whenever a strip or a panel can overflow - a row of filters, a list in a fixed-height card. Plain `ScrollArea` gives no sign that anything is hidden.
+- Give a vertical frame a bounded height (`className="h-80"`); a horizontal one needs only a bounded width, which a flex child with `min-w-0` already has.
+- Match `fadeTheme` to the surface behind the frame (`card` inside a Card). Over an image or a blur, use `fadeMode="mask"` instead.
+- For a horizontal strip used with a mouse, add `dragScroll` and `controls`; both stand aside on touch screens, and each control hides at the end it points to.
+
+## SearchInput
+
+`@instruments/materia-ui/components/search-input`
+
+Search input over InputGroup: a search icon, a built-in clear button that appears once the field has a value, and an optional keyboard-shortcut hint shown while it's empty. Pass `suggestions` for an animated "Try: …" placeholder that cycles while the field is empty. Import from "@instruments/materia-ui/components/search-input".
+
+- Use `SearchInput` for search/filter fields - it supplies the search icon, a clear button, and (via `shortcutHint`) a `Kbd` hint; don't rebuild these on a plain `Input`.
+- `onChange` receives the next string on every keystroke and on clear (not a DOM event) - pass `value` for controlled use or `defaultValue` for uncontrolled.
+- Pass cycling placeholder ideas via `suggestions` (which suppresses the static `placeholder`); `shortcutHint` shows only while empty and is swapped for the clear button once the field has a value.
+- Pill (`radius="full"`) at the 48px `xl` default is the search signature - so leave both defaults alone in standard search/filter placements; pass `size` explicitly for compact embedded contexts (popovers, table headers).
+
+## Section
+
+`@instruments/materia-ui/components/section`
+
+Section is a full-width vertical-rhythm band. Unlike `Container` it does not constrain width - use it for full-bleed padded regions, and nest a `Container` inside when the content should also be centred. RSC-safe.
+
+Import from "@instruments/materia-ui/components/section".
+
+- `Section` is full-width (padding only, no max-width) - nest a `Container` inside when content should also be centred; use `Container` alone when you just need the width cap.
+- Tune vertical rhythm with `space` (its `py`, default `base`); `as`/`render` are mutually exclusive with `render` winning (dev-warned).
+
+## SectionHeader
+
+`@instruments/materia-ui/compositions/section-header`
+
+A generic section header: an optional eyebrow label, a `Heading` title, an optional muted description, and an optional right-aligned actions slot. Typography is delegated to `Heading` and `Text`; the `data-slot` hooks (`section-header-eyebrow` / `-body` / `-actions`) let adopters retune spacing without forking the component.
+
+- Renders a `<header>`, which is a `banner` landmark only when it is a direct child of `<body>`. It is built for nested/section use - don't render more than one page-level `SectionHeader` directly under `<body>`, or you'll create duplicate `banner` landmarks.
+- Set `level` for the document outline and `size` for visual scale independently - a visually small header can still be an `h2`. Use `reserveEyebrowSpace` to keep an eyebrow-less header aligned beside sibling headers that have an eyebrow.
+- Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+
+## SegmentedControl
+
+`@instruments/materia-ui/components/segmented-control`
+
+A single-select, always-one-selected control that switches between a small set of visible options - a view or mode switcher rendered as a pill of segments. Built on Base UI ToggleGroup (single-select) but kept permanently selected: re-clicking the active segment never clears it.
+
+Compose it from {@link SegmentedControlItem}s; shared `size` / `fullWidth` / active state flow to them through context. Controlled via `value`, or uncontrolled via `defaultValue`. Items scroll horizontally with a trailing fade hint when they overflow.
+
+- One value is always selected - the active segment cannot be deselected; for deselectable or multi-select sets reach for ToggleGroup.
+- Switching visible content panels is Tabs; navigating URLs is TabNavigation - SegmentedControl is an input that selects a value or mode.
+- Icon-only items must carry an `aria-label`.
+
+## Select
+
+`@instruments/materia-ui/components/select`
+
+Root of the select - an accessible listbox built on Base UI that owns open state and the chosen value; drive it with `value`/`onValueChange` (controlled) or `defaultValue` (uncontrolled).
+
+- `Select` is only the state root - compose `SelectTrigger`, `SelectValue`, `SelectContent`, and `SelectItem`s inside it or nothing renders.
+- Use `Select` to pick one option from a short closed list; when users need type-to-filter, use `Combobox` instead.
+- Drive it with `value` + `onValueChange` (controlled) or `defaultValue` (uncontrolled), and give it an accessible name via the trigger (`Field`/`Label`).
+- Pass `items` (a value-to-label map or `{ value, label }[]`) so the trigger shows the selected label even before the popup has mounted.
+
+## Separator
+
+`@instruments/materia-ui/components/separator`
+
+Visual rule dividing content sections, horizontally or vertically.
+
+Renders a Base UI `Separator` (`role="separator"`). Pass `aria-hidden` when the rule is purely decorative and should stay out of the accessibility tree.
+
+- It is announced as a separator by default - pass `aria-hidden` when the rule is purely decorative.
+- For an inline rule set `orientation="vertical"` and give it an explicit height (e.g. `className="h-6"`) - a vertical separator has no intrinsic length.
+
+## SettingsCard
+
+`@instruments/materia-ui/compositions/settings-card`
+
+Vercel-style settings card with a per-card save action. Each card represents a cohesive group of related settings; pair rows inside it with `SettingsRow` for the standard label/description/control layout.
+
+- Fill it with `SettingsRow` children for the standard label/description/control layout; use `SettingsCard` for grouped form settings, not `Card`, when you want the built-in per-card save footer.
+- The footer only renders when `onSave` is passed, and the Save button is gated on `dirty` (and disabled while `loading`) - wire form dirty state through, or the button stays disabled.
+- Give each card one cohesive group of settings with its own save; don't nest multiple `SettingsCard`s or share one across unrelated sections.
+
+## Sheet
+
+`@instruments/materia-ui/components/sheet`
+
+Root component for a sheet (side panel). Manages open/closed state and accessibility. Import from "@instruments/materia-ui/components/sheet".
+
+- Use `Sheet` for a simple edge panel holding a focused form / settings; a drag-to-dismiss bottom sheet is a `Drawer`, and nested panels are a `Sidepanel`.
+- Set the entry edge via `SheetContent` `side`; always render a `SheetTitle` (wrap in `sr-only` if hidden) so the panel is announced.
+
+## Shimmer
+
+`@instruments/materia-ui/components/shimmer`
+
+Animated shimmer effect for text. Creates a gradient sweep animation.
+
+Variants:
+
+- `"light"` (default): muted foreground → muted highlight (dark text on light bg)
+- `"dark"`: gray-400 → foreground (darker sweep on light bg)
+- `"inverted"`: white text on dark backgrounds
+- `"metallic"`: chrome text for dark surfaces, with a slow champagne-to-steel sheen and a pause between sweeps
+
+- Reach for `Shimmer` for in-progress _text_ (a "Thinking…"/"Analyzing" sweep); `Shine` is an occasional attention flick on a surface, and `Skeleton` is a layout-shaped content placeholder.
+- `children` must be a plain string - the sweep is a `bg-clip-text` gradient sized from character count, so element children won't clip correctly.
+- Under reduced motion every variant renders its static base with no sweep. For finite "thinking" states set `repeat` (e.g. `repeat={2}`) rather than leaving the default infinite loop running.
+- `variant="metallic"` is built for dark surfaces only - on a light background the chrome ramp loses contrast. Its own `duration` and `repeatDelay` defaults apply only when you pass neither.
+- To sweep several lines in step, pass them one shared `progress` motion value (0-100) and drive it yourself; a Shimmer given `progress` never animates on its own.
+
+## Shine
+
+`@instruments/materia-ui/components/shine`
+
+A subtle diagonal specular sweep for drawing attention to interactive surfaces. Unlike a skeleton shimmer, Shine runs as an occasional flick with rest between passes - one quick highlight every few seconds - so it reads as "this surface is alive" rather than "content is loading".
+
+Pass `playOnce` for a single entrance sweep (then it fades out).
+
+Two usage shapes:
+
+1. Wrapper - pass `children` and Shine wraps them in a relative box.
+2. Overlay - render without children inside an existing relative parent.
+
+Uses `mix-blend-mode: soft-light` so the highlight harmonizes with the underlying colour instead of painting pure white.
+
+Honours `prefers-reduced-motion` - renders nothing when motion is reduced (a static band would read as a permanent artefact, not a cue). When `visible` flips to `false`, the sweep fades out then unmounts so its rAF loop stops.
+
+- Use `Shine` for a periodic "this surface is alive" flick on an interactive element - not for loading; a continuous text sweep is `Shimmer` and a content placeholder is `Skeleton`.
+- Use `playOnce` for entrance choreography that should not loop.
+- Either pass `children` (Shine wraps them in a relative box) or render it bare inside an existing `position: relative` parent - otherwise the sweep has nothing to overlay.
+- Needs `ReducedMotionProvider`; under reduced motion it renders nothing (a static band would look like a permanent artefact), so don't rely on it as persistent decoration.
+
+## Sidebar
+
+`@instruments/materia-ui/compositions/sidebar`
+
+The sidebar shell. Reads open/collapsed state from {@link useSidebar}, so it must render inside a {@link SidebarProvider}.
+
+Adapts by viewport and `collapsible`: an animated docked shell on desktop, a slide-in `Sheet` on mobile, or a static column when `collapsible="none"`.
+
+- Render `Sidebar` inside a `SidebarProvider` - it reads open/collapsed state from `useSidebar` and cannot work outside one.
+- Choose `collapsible` deliberately: `offcanvas` slides fully away, `icon` shrinks to a rail, `none` is a static column that never adapts to the mobile `Sheet`.
+
+## SidebarInset
+
+`@instruments/materia-ui/compositions/sidebar`
+
+The content column beside the sidebar, and the page's single `<main>` landmark: it carries the skip-link target id and is focusable so the link can move focus here. Put your page `<header>` and content inside it, as in shadcn's sidebar blocks. In a `height="fill"` provider it scrolls internally (make the header `sticky top-0`).
+
+`min-w-0` (not `w-full`) is essential: without it flex's default `min-width: auto` stops the column shrinking below its content, so a wide child pushes the page past the sidebar and creates horizontal overflow. With `variant="inset"` the column becomes a rounded card.
+
+Pass `render={<div />}` (and your own `id`) when the page already owns its `<main>`, as in an embedded demo. A dev warning fires when more than one `<main>` is on the page. Import from "@instruments/materia-ui/compositions/sidebar".
+
+- Render exactly one `SidebarInset` per page; for a second content region use a plain `<div>`.
+
+## SidebarLayoutHeader
+
+`@instruments/materia-ui/compositions/sidebar`
+
+The desktop (md+) top header beside the sidebar. Fixed by default, its left offset animating to track the sidebar's width; pass `position="sticky"` to put it in flow inside `SidebarInset`, where it shares the content column's gutter and edges with no measurement. Compose `SidebarLayoutHeaderSearch` and `SidebarLayoutHeaderActions` inside it.
+
+- Prefer `position="sticky"` with `gutter` inside `SidebarInset`: search, page heading and content then share one left edge, and a docked `SidebarPanel` gutter pushes the header's actions clear of the panel without any offset plumbing.
+- In a `variant="inset"` sidebar frame the sticky bar takes `--sidebar-inset-header-height` (the header height less the card's top and bottom gap), so search and the sidebar's brand row share a centre line; don't re-pad it to match.
+- Pair a sticky header with `SidebarInset offset="app-bar"` so only the mobile app bar is cleared; `offset="header"` is for the fixed header.
+
+## SidebarMenuButton
+
+`@instruments/materia-ui/compositions/sidebar`
+
+The primary interactive row of a sidebar menu - a leading icon plus label, optional suffix icon and keyboard-shortcut hint.
+
+Collapses to icon-only when the sidebar collapses (swapping in `collapsedIcon` /`collapsedContent` and revealing the `tooltip`), unless `forceExpanded`. Reads collapsed state from {@link useSidebar}; pass `render` to render a `<Link>` or other element as the button.
+
+- In an icon-collapsible sidebar use `size="xl"`: the icon rail is sized for an `xl` row, so its collapsed square centres on the rail and the icon stays put as the sidebar folds.
+
+## SidebarPanel
+
+`@instruments/materia-ui/compositions/sidebar`
+
+A flex-item region beside `SidebarInset`, in two variants. `inline` is an in-flow sticky column that renders your content beside `SidebarInset`; `gutter` is an empty width-animated spacer that reserves room for a docked overlay (e.g. a `modal={false}` Sidepanel) - it drops its children and is `aria-hidden`, so the panel _is_ the reservation with no app state crossing into the design system. Place it as a sibling of `SidebarInset` inside `SidebarProvider`; `SidebarInset`'s `flex-1 min-w-0` absorbs the remaining width. Styles itself off the provider's `data-height`, so it stays a server component. Import from "@instruments/materia-ui/compositions/sidebar".
+
+- Pair a `gutter` with a docked, `modal={false}` Sidepanel driven by the same `open` state; keep `open` true through the Sidepanel's exit animation so the reservation holds until it leaves.
+- A `gutter` reserves room from `lg`, where `SidepanelContent` turns from a full-bleed overlay into the floating card; keep any panel you dock into it on the same breakpoint.
+- A `gutter` needs a row context: `SidebarProvider` lays out as a row, so a panel placed beside `SidebarInset` sits on its right.
+- Render at most one panel per side; use `side` to keep left/right reservations independent.
+
+## SidepanelContent
+
+`@instruments/materia-ui/components/sidepanel`
+
+Main content area of the sidepanel. Includes portal and overlay automatically.
+
+- `width="default"`: Fixed 440px width, inset from edges with rounded corners
+- `width="full"`: Full viewport coverage with safe area padding (mobile-first)
+
+When `nestedOpen` is true, the panel shifts left and scales down to create a stacking effect (only applies to default width).
+
+On open, a keyboard user lands on the panel's first control; a pointer, touch or programmatic open focuses the panel itself, so no focus ring shows on first paint. Pass `initialFocus` to choose otherwise.
+
+- Open the panel from a `SidepanelTrigger` where you can: Base UI then knows a keyboard opened it and moves focus to the first control. Opened from app state, it focuses the panel surface, which still announces the panel's name.
+- Name the panel once: render a visible `SidepanelTitle`, or pass `title` when the design has no visible heading.
+
+## SidepanelRoot
+
+`@instruments/materia-ui/components/sidepanel`
+
+Root component for a sidepanel. Wraps Base UI Dialog.Root.
+
+- Reach for `Sidepanel` when you need nested sub-panels or a non-modal panel (`modal={false}`) that leaves the page interactive; a single focused edge panel is a `Sheet`.
+- Compose nested panels with `SidepanelNestedRoot`, and always render a `SidepanelTitle` for the accessible name.
+
+## SidepanelScroll
+
+`@instruments/materia-ui/components/sidepanel`
+
+The scrolling region between a `SidepanelHeader` and `SidepanelFooter`: takes the remaining height of `SidepanelBody`, scrolls on its own and carries the panel's standard inset, so header and footer stay put while it moves.
+
+- Put exactly one `SidepanelScroll` inside `SidepanelBody`, between the header and footer, rather than a hand-rolled `flex-1 overflow-y-auto` div.
+
+## SidepanelTitle
+
+`@instruments/materia-ui/components/sidepanel`
+
+Title element for the sidepanel, and the panel's accessible name. While it is mounted, `SidepanelContent` drops the name it would otherwise take from its `title` prop, so the panel is announced with one title.
+
+- Render one visible `SidepanelTitle` per panel; without one, pass `SidepanelContent` a `title` so the panel still has a name.
+
+## SimpleGrid
+
+`@instruments/materia-ui/components/simple-grid`
+
+Equal-width column grid built on CSS Grid.
+
+`cols` and `gap` accept a single value or a per-breakpoint responsive object like `{ base: 1, md: 3 }`; set `responsiveMode` to `"container"` to resolve breakpoints against the nearest container instead of the viewport.
+
+- `SimpleGrid` lays out equal-width columns - set `cols` (responsive, e.g. `{ base: 1, md: 3 }`); when you need column spans or ordering, step up to `Grid`.
+- Set `xGap`/`yGap` for different column and row spacing; each overrides the `gap` shorthand on its own axis.
+- `as` and `render` are mutually exclusive (`render` wins, dev-warned); `as` draws from the closed layout vocabulary, so `as="button"` is a type error (use `Button`).
+- Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+
+## SiteFooter
+
+`@instruments/materia-ui/compositions/site-footer`
+
+The page's closing panel: a pitch on one side, the site's links in columns on the other, and a bar beneath for the legal line and social links. It sits on the page gutter as one rounded, sunk surface, so it reads as the end of the page rather than another section of it. Import from "@instruments/materia-ui/compositions/site-footer".
+
+- Render it after the page's `<main>`, not inside it, so it stays the page's own footer landmark.
+- Keep it to a lead, one nav and one bar. Four columns of a few links each is the shape it is set for.
+
+## Skeleton
+
+`@instruments/materia-ui/components/skeleton`
+
+Skeleton loader component for showing loading states. Displays animated placeholder with a shimmer gradient sweep.
+
+- Prefer `Skeleton` over a spinner for content areas - a layout-stable placeholder that mirrors the final shape avoids reflow when data lands.
+- Size it with `className` (`h-*` / `w-*`); use `variant="light"` on white / `bg-background` surfaces where the default grey is too dark.
+
+## SocialIcon
+
+`@instruments/materia-ui/components/social-icon`
+
+Draws a social network's mark in the surrounding text colour, on the same size scale as `Icon`. Without a `label` it is `aria-hidden`; with one it becomes an image with that accessible name.
+
+- Set `label` only when the icon stands alone, such as inside an icon-only link; beside visible text leave it off so the mark is hidden from assistive tech.
+- The mark paints with `currentColor`, so colour it with a text-colour class on the icon or a parent (`className="text-muted-foreground"`), not a brand fill.
+- Size with the `size` token (`"sm"`, `"lg"`…), not `className="size-6"`; it shares the `Icon` scale so a mark lines up with the icons around it.
+
+## Space
+
+`@instruments/materia-ui/components/space`
+
+Spacer component for adding fixed width or height gaps in layouts.
+
+- Reach for `Space` only for a fixed one-off gap between siblings; consistent spacing across many children belongs on a `Stack`/`Flex`/`Group` `gap` instead.
+
+## Spinner
+
+`@instruments/materia-ui/components/spinner`
+
+Loading spinner component. Animated circular indicator for async operations.
+
+- Use `Spinner` for small inline / action loading (inside a `Button`, next to text); a blocking full region is `LoadingState`, a layout placeholder is `Skeleton`.
+- A bare `Spinner` carries no accessible name - wrap it in a labelled live region (e.g. `LoadingState`) when it's the sole loading signal.
+
+## Stack
+
+`@instruments/materia-ui/components/stack`
+
+Flex container for arranging children in a line with consistent spacing.
+
+Layout props (`direction`, `align`, `justify`, `gap`) accept a single value or a per-breakpoint responsive object like `{ base: "column", md: "row" }`; set `responsiveMode` to `"container"` to resolve breakpoints against the nearest container instead of the viewport. Stacks vertically by default.
+
+- `Stack` is a gapped one-axis line, vertical by default - use `HStack`/`VStack` to lock direction; for full flexbox control (`justify`/`wrap`) reach for `Flex`.
+- `as` and `render` are mutually exclusive (`render` wins, dev-warned); `as` draws from the closed layout vocabulary, so `as="button"` is a type error (use `Button`).
+- Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+
+## Stagger
+
+`@instruments/materia-ui/components/stagger`
+
+Orchestrates staggered entrance animations for child `StaggerItem` components. Uses Motion's `stagger()` for `delayChildren` internally.
+
+- Wrap `StaggerItem` children (not raw elements) - `Stagger` only drives the `hidden`→`visible` variant orchestration; the items own their actual entrance animation.
+- Tune rhythm with `stagger` (gap between items) and `delay` (lead-in) on the parent, rather than hand-setting per-child transition delays.
+- Needs `ReducedMotionProvider` in the tree so the orchestrated entrance both runs and honours the reduced-motion setting.
+
+## Stepper
+
+`@instruments/materia-ui/components/stepper`
+
+Root stepper component that manages step state
+
+- Give each step a `StepperItem` child in order - progress is derived from child index, so conditionally rendering steps shifts the fill.
+- Control completion via `value`/`onValueChange` (or uncontrolled `defaultValue`); the fill reaches only the last _completed_ step, not the current one.
+
+## StreamingText
+
+`@instruments/materia-ui/components/streaming-text`
+
+Progressive streaming answer with settle-gated chrome.
+
+- Drive `tokens` from real stream deltas - don't fake a word clock in product code. Showcase demos may animate.
+
+## SubNavigation
+
+`@instruments/materia-ui/components/sub-navigation`
+
+Vertical secondary navigation for page subsections and settings-like layouts; the `<nav>` landmark wrapping a {@link SubNavigationList} of links.
+
+- Reach for `SubNavigation` for a vertical in-page section/settings menu; horizontal router tabs are `TabNavigation`, the app-chrome shell is `Sidebar`.
+- Fill it with a `SubNavigationList` of links - it already renders the `<nav>` landmark, so don't nest it inside another `<nav>`.
+
+## SuccessTickRipple
+
+`@instruments/materia-ui/components/success-tick-ripple`
+
+Celebration tick - a green medallion that drops in with a spring rebound while three radial-gradient rings ripple outward from its centre and a residual mint glow settles on the upper edges of the parent container.
+
+Layout contract:
+
+- The component renders a `position: absolute; inset: 0` ripple field plus the medallion (in normal flow). The ripple field attaches to the nearest positioned ancestor - wrap this component in a parent that is `position: relative` and `overflow: hidden` to bound the celebration. The medallion's centre is the visual impact point.
+
+Tuning:
+
+- Override `--tick-impact-x` / `--tick-impact-y` on the parent to move the ripple origin (defaults to 50% / 50% of the parent).
+
+Animations are CSS-only and run once on mount. `prefers-reduced-motion` collapses to the final settled state and hides the ripple.
+
+- Wrap `SuccessTickRipple` in a `position: relative; overflow: hidden` parent - the ripple field is absolutely positioned and bleeds past an unbounded container.
+- It's decorative (`aria-hidden`) unless you pass `aria-label`, which exposes it as an `img`; animations are CSS-only and already collapse under `prefers-reduced-motion`.
+
+## Swatch
+
+`@instruments/materia-ui/components/swatch`
+
+Low-level visual swatch primitive for colours, gradients, and images - shaped as a **chip** (`circle`/`pill`) or a **tile** (square material/image card). A thin façade dispatching on `kind` to the internal chip and tile renderers, which share fill resolution and contrast handling.
+
+Chips paint the darkening overlay on every fill and draw the double-ring selection pattern; tiles use tiered radius, border, ring and shadow, `children` > `src` > `color` precedence, and no darkening overlay.
+
+- Feed fills through `color`/`background`/`colors`, never a hex in `className`/`style` - the props drive the contrast-aware text colour, selection ring, and darkening overlay.
+- Reach for `Swatch` for a selectable colour/gradient/material chip or tile; a tiny non-interactive status marker is `Dot`, and a display-only status/category label is `Badge`.
+- For a gradient or image chip fill pass `light` - auto contrast detection (`isLightColor`) only reads solid colours, so overlaid icons/labels lose legibility without it.
+
+## SwatchFan
+
+`@instruments/materia-ui/compositions/swatch-fan`
+
+A fanned stack of {@link Swatch} tiles: a fixed three-card editorial fan or an interactive N-tile splay.
+
+Pass 3 `items` with `interaction="breathe"` for the editorial fan (Figma geometry, `variant` spread/stack, white 3px mount via `bordered`); pass N `items` with `interaction="hover-fan"` for the interactive splay-on-hover with pointer tilt. `bordered={false}` swaps the white mount for the 1px hairline tile.
+
+- Feed 3 items for the `breathe`/`none` card engine - its Figma geometry, z-order, and `variant` morphing are built around a fixed left/center/right trio; the hover-fan engine is the N-tile path.
+- Needs `ReducedMotionProvider`; it already collapses the mount fan-out, hover nudge, and splay under reduced motion (snapping to the settled frame), so don't gate the interaction yourself.
+- `bordered` is the mount-as-a-prop: `true` = white 3px card mount, `false` = 1px hairline - don't hand-roll either border in a wrapper.
+
+## SwatchGroup
+
+`@instruments/materia-ui/components/swatch-group`
+
+Row of selectable circular color/image swatches with single-select behaviour, built on Base UI RadioGroup. Selection is controlled via `value` + `onValueChange`, or uncontrolled via `defaultValue`. When `icon` is set the selected swatch shows that icon instead of the default selection ring.
+
+- Drive selection with `value`+`onValueChange` (or `defaultValue`), not per-swatch `onClick` - it's a Base UI `RadioGroup`, so it already handles roving focus and arrow-key selection.
+- Choose `SwatchGroup` when you want radio semantics + keyboard a11y; reach for `SwatchSelector` only for a lighter controlled row without the RadioGroup roles.
+- Set `icon` (e.g. `Check`) on the group to swap the selection ring for a glyph on the chosen swatch, rather than styling items individually.
+
+## SwatchSelector
+
+`@instruments/materia-ui/components/swatch-selector`
+
+Row of selectable color/image swatches with controlled single selection, built on Base UI ToggleGroup: the row is one tab stop and the arrow keys move between swatches.
+
+Shares the selected `value`, `onValueChange`, and `size` with its {@link SwatchSelectorItem} children through context.
+
+- Pair `SwatchSelector` with `SwatchSelectorItem` children - it shares `value`/`onValueChange`/`size` through context, so items need no individual wiring.
+- Prefer `SwatchGroup` when the row is a single-choice form control needing radio roles and form submission; `SwatchSelector` is a row of pressed-state toggle buttons.
+- Pressing the selected swatch again keeps it selected and does not call `onValueChange`.
+- Selection is controlled - pass `value` and update it from `onValueChange`; there is no internal fallback state to fall back on.
+
+## Switch
+
+`@instruments/materia-ui/components/switch`
+
+Renders a toggle switch for boolean on/off states.
+
+- Use `Switch` for an instantly-applied on/off setting; use `Checkbox` for opt-ins confirmed by a submit, and `RadioGroup` for mutually-exclusive choices.
+- Controlled use needs `checked` + `onCheckedChange`; with only `checked` the switch won't move - use `defaultChecked` for uncontrolled.
+- `Switch` has no built-in label - associate a `Label` via `htmlFor`/`id` so the toggle has an accessible name.
+
+## Table
+
+`@instruments/materia-ui/components/table`
+
+Semantic `<table>` primitive, wrapped in a horizontally scrollable container so wide tables overflow rather than break layout. Compose with the exported `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`, `TableFooter`, and `TableCaption` parts.
+
+- Use `Table` for a small, static, hand-authored table; reach for `DataGrid` once you need sorting, filtering, pagination, column pinning/visibility, or row virtualisation - `Table` has no data model.
+- Include a `TableCaption` describing the table's contents - it is the accessible name screen readers announce for the `<table>`.
+- Compose real `TableHeader`/`TableBody`/`TableRow`/`TableHead`/`TableCell` parts (semantic `thead`/`tbody`/`th`/`td`); don't fake rows with styled divs or you lose the table semantics.
+
+## TabNavigation
+
+`@instruments/materia-ui/components/tab-navigation`
+
+Provides shared context (variant, size, fullWidth) to its tab links for router-based navigation. Import from "@instruments/materia-ui/components/tab-navigation". Shares styling with the Tabs component.
+
+- Use `TabNavigation` when each tab is a route/URL (it renders a `<nav>` of links); for in-page panels that swap without navigating, use `Tabs`.
+- It shares the Tabs look via context but defaults to `variant="line"`; mark the active link yourself (e.g. router `aria-current`) - there's no Base UI value tracking here.
+
+## Tabs
+
+`@instruments/materia-ui/components/tabs`
+
+Tabbed content switcher (Base UI Tabs) that composes `TabsList` / `TabsTrigger` / `TabsContent`.
+
+Provides shared `variant`/`size`/`fullWidth` through context so the parts stay in sync, and tracks the active value to drive the sliding `TabsIndicator`. Controlled via `value`/`onValueChange`, uncontrolled via `defaultValue`.
+
+- Reach for `Tabs` to swap in-page panels via `TabsContent`; when each tab is a route, use `TabNavigation` instead (renders links, no panels).
+- Compose `TabsList`/`TabsTrigger`/`TabsContent` - shared `variant`/`size`/`fullWidth` flow through context, so set them on `Tabs`, not each trigger.
+
+## Tag
+
+`@instruments/materia-ui/components/tag`
+
+Tag - An interactive pill component for selection, filtering, and multi-select scenarios.
+
+Uses shared pill styling (identical to Badge) with interactive capabilities: dismissibility, click handling, and keyboard support.
+
+The outer element is polymorphic based on interactivity:
+
+- `onClick` provided: `<button>`
+- `onDismiss` only: `<div>` with dismiss `<button>`
+- Both: `<div>` with separate selection and dismiss `<button>` elements
+- Neither: `<span>` (presentational)
+
+- Choose `Tag` when the chip is interactive (selection/filter/dismiss); for a display-only status label or count use `Badge`, and for a bare colour dot use `Dot`.
+- Pass `onClick` for selection and `onDismiss` for removal. When both are provided they render as sibling buttons inside one visual chip; don't wrap Tag in another button.
+- With both actions, HTML attributes (including the accessible name and selected state) apply to the selection button; `className` and `style` style the outer chip.
+- Set at most one leading visual - `loading` > `imageUrl` > `dot` > `icon` (in that precedence); pass a Lucide component to `icon` (not `<Icon/>`), and `imageUrl` renders a circular `<img alt="">`, so keep it decorative.
+- When `onDismiss` is set, Backspace/Delete also removes the tag while it's focused - don't bind your own conflicting key handler.
+
+## TagSelector
+
+`@instruments/materia-ui/compositions/tag-selector`
+
+TagSelector - A multi-select tag component with search, create, edit, delete, and reorder capabilities.
+
+- The CRUD affordances are gated - `onCreateTag`/`onEditTag`/`onDeleteTag`/`onReorder` do nothing unless you also set the matching `allowCreate`/`allowManage`/`allowReorder` flag.
+- `value`/`onChange` carry the selected `TagData[]` and are required - `TagSelector` is controlled; supply the full option set via `tags`.
+- A custom `trigger` render-prop is passed to `PopoverTrigger` as `render`, so return a single element that forwards its ref/props (e.g. a `Button`).
+- Use `singleSelect` when only one tag may be chosen; for a fixed, non-editable list prefer `Combobox`/multi-`Select` and reserve `TagSelector` for managing the tag set itself.
+
+## Text
+
+`@instruments/materia-ui/components/text`
+
+The typography primitive for body copy - renders a `<p>` (or any element via `as` or `render`). Ships without a line-length cap; add `max-w-prose` at the call site for long-form prose. `size` names a type role, defaults to `paragraph-sm` and accepts responsive values: `size={{ base: "paragraph-sm", md: "paragraph-lg" }}`.
+
+- `as` is a closed text-only vocabulary - use `as="span"` for inline copy; `as="div"`/`as="label"` are type errors (use `Box` for wrappers, `Label` for form labels).
+- `as` and `render` are mutually exclusive (`render` wins, dev-warned); Text ships without a line-length cap - add `max-w-prose` at the call site for long-form prose.
+
+## Textarea
+
+`@instruments/materia-ui/components/textarea`
+
+Renders a textarea element for multi-line text input (Base UI `Field.Control` rendering a `<textarea>`). Inside a Field it is the field's control: the FieldLabel targets it, FieldDescription/FieldError describe it, and it inherits the field's invalid state.
+
+- Inside a `Field`, let invalid state cascade like `Input` - omit `hasError`; pass it only to force error styling on a standalone `Textarea`.
+- It auto-grows with content (`field-sizing-content`); set `rows` for an initial height rather than pinning height via CSS.
+- Give it a label - inside a `Field` a `FieldLabel` targets it with no ids to wire; standalone, point a `Label`'s `htmlFor` at its `id`. A placeholder is not an accessible name.
+
+## ThinkingLoader
+
+`@instruments/materia-ui/components/thinking-loader`
+
+LLM-style "labor illusion" loader with blur conveyor animations and shimmer text effect.
+
+Supports both controlled mode (parent drives `currentStep`) and uncontrolled mode (auto-cycles through steps based on `interval`).
+
+- Drive `ThinkingLoader` with `currentStep` (controlled) to reflect real progress, or omit it to auto-cycle `steps` on `interval` for a labor-illusion loader.
+- It already renders an `aria-live="polite"` region announcing each step - don't wrap it in another status role. Mount `ReducedMotionProvider` since it animates via `m.*`.
+
+## ThinkingOrb
+
+`@instruments/materia-ui/components/thinking-orb`
+
+Dotted thought-orb for AI & agent status.
+
+- Use size `64` for chat-avatar / panel status; use `20` for inline text-adjacent cues. They are separate designs, not a scale factor.
+- Prefer `theme="auto"` so the orb follows `data-theme` / system preference; pin `dark` or `light` only when the surrounding surface is fixed.
+- Pass a specific `aria-label` when the state text is not otherwise announced (e.g. next to a ThinkingLoader that already speaks).
+
+## ThinkingTrace
+
+`@instruments/materia-ui/compositions/thinking-trace`
+
+Expandable agent thinking / tool / search trace, driven by real agent state.
+
+While `streaming` is `true` the trace is open, shows every row it is given and shimmers `activeLabel`. When it turns `false` the trace collapses to `doneLabel`; rows stay mounted and the header re-expands them. A manual toggle of the header pins expansion until the component unmounts.
+
+- Pair above streaming answers in chat. Use ThinkingLoader when you only need a one-line narrated header without an expandable timeline.
+
+## TimeSlotPicker
+
+`@instruments/materia-ui/components/time-slot-picker`
+
+A grid of time slots where exactly one can be chosen, such as appointment times beside a `Calendar` (Base UI RadioGroup).
+
+Each slot is a radio, so arrow keys move the selection and `name` submits the chosen value with a form. Slots reflow into as many equal columns as fit; the picker sets no outer padding.
+
+- Pass slot values already formatted for display, or give each slot a `label` - the picker does no time parsing or 12/24-hour formatting.
+- Name the group with `aria-label` or `aria-labelledby`; screen readers announce it before the first slot.
+- Use `TimeSlotPicker` for a fixed set of offered times; for any time the user types, use `Input type="time"`.
+
+## Toaster
+
+`@instruments/materia-ui/components/toast`
+
+Renders the toasts queued with `toast()`: light bordered cards on the neutral popover surface, each with a per-type coloured icon and a close button, stacked at the bottom centre by default. Built on Base UI Toast.
+
+- Use toasts for transient, auto-dismissing notifications; a persistent inline message is an `Alert`.
+- Mount `<Toaster />` exactly once near the app root, then fire toasts with `toast()` from `@instruments/materia-ui/components/toast` - don't render a `Toaster` per view.
+- Press F6 to move focus into the toasts; hovering or focusing the stack pauses dismissal and fans it open.
+
+## Toggle
+
+`@instruments/materia-ui/components/toggle`
+
+Two-state pressable button (on/off) built on Base UI Toggle, with an optional icon alongside the label.
+
+Pass `icon` with no children to get a square icon-only toggle (auto-detected and sized to match its height); pass both for an icon + label. Controlled via `pressed`/`onPressedChange`, uncontrolled via `defaultPressed`.
+
+Inside a `ToggleGroup` it is the group's item, as in Base UI: give it a `value`, and it takes the group's `size`, `radius`, `variant` and layout in place of its own. An icon-only toggle needs an `aria-label`; a dev warning fires without one.
+
+- One independent on/off is a `Toggle`; a mutually-exclusive or multi-select set is `ToggleGroup` with `Toggle`s inside it; an instantly-applied setting is `Switch`.
+- Pass `icon` with no children for a square icon-only toggle (auto-sized); with a label, order it via `iconPlacement`.
+
+## ToggleGroup
+
+`@instruments/materia-ui/components/toggle-group`
+
+A literal group of {@link Toggle}s: several two-state pressable buttons that share one selection, laid out `joined` (a seamless segmented row), `separated`, or `wrap`ped. Built on Base UI ToggleGroup - by default one item is pressed at a time (radio-like), `multiple` makes it checkbox-like; `value` is always an array. The `Toggle`s inside take `size` / `radius` / `variant` from the group through context.
+
+- An always-one-selected mode switcher is `SegmentedControl`, not `ToggleGroup` - reach here for multi-select toolbars and deselectable choice chips.
+- `layout="wrap"` + `required` (without `multiple`) is the wizard choice-chip recipe.
+- Put plain `Toggle`s inside, each with a `value`, as Base UI does.
+- Icon-only toggles need an `aria-label` (a dev warning fires otherwise).
+
+## Tooltip
+
+`@instruments/materia-ui/components/tooltip`
+
+Root component for a tooltip. Wraps TooltipProvider automatically.
+
+- Keep `TooltipContent` a short, non-interactive label - no buttons or links inside; for rich or actionable hover content use `HoverCard`.
+- The trigger must be focusable (a button / link, or `render` onto one) or keyboard and AT users never see the tip.
+- Share one `TooltipProvider` to tune `delay` / skip-delay for a group; `Tooltip` wraps its own provider, so you only need it for grouping.
+
+## usePromptPanelKeyboard
+
+`@instruments/materia-ui/compositions/prompt-panel`
+
+Keyboard contract for a `PromptPanel`'s freeform input: digit keys 1–9 select an option by index (only while the input is empty), Enter submits the freeform text (only while non-empty), Escape dismisses, and Backspace on an empty input navigates back a step. Never steals keys mid-sentence - every branch except Escape is gated on the input's empty state, so once the user starts typing, digits/Backspace fall through to normal text entry.
+
+- Attach the returned `onKeyDown` directly to the panel's freeform input rather than re-implementing this contract - `PromptPanelFreeform` forwards unrecognised props straight to its `<input>`.
+
+## VariantSelector
+
+`@instruments/materia-ui/compositions/variant-selector`
+
+A flexible variant selector that supports both single and multiple selection modes. Renders card-style items that can display images or colours. Single mode is a Base UI RadioGroup and multiple mode a Base UI ToggleGroup, so either way the set is one tab stop and the arrow keys move between items.
+
+- Fill it with `VariantSelectorItem` children - they read selection from context; `value`/`defaultValue` matches each item's `value`.
+- `mode` is a discriminated prop: `"single"` renders a `role="radiogroup"` and gives `onValueChange` a `string`, `"multiple"` renders a `<fieldset>` of pressed-state toggles and a `string[]` - keep `value`/`defaultValue` types matching the mode.
+- `defaultValue` is uncontrolled: the selector tracks later picks itself. Pass `value` with `onValueChange` to control it.
+- Use `VariantSelector` for image/colour swatch pickers; for a labelled icon-over-text option grid use `IconCard`, and for plain radio/checkbox lists use `RadioGroup`/`Checkbox`.
+
+## VergeRoot
+
+`@instruments/materia-ui/components/verge`
+
+The container a `VergeSlot` listens to: a row, a card, a list item. It has no appearance of its own, only the hover and focus state its slots read. Wrap the whole row, not just the controls, so the reveal answers to the user pointing at the row.
+
+Adapted from
+
+- Wrap the whole row in `VergeRoot`, not just the controls, so hovering or tabbing anywhere in the row reveals them.
+- A nested `VergeRoot` does not isolate its slots: hovering an outer row also reveals an inner row's controls.
+- `as` and `render` are mutually exclusive (`render` wins, dev-warned); use `as="li"` inside a real list.
+
+## VergeSlot
+
+`@instruments/materia-ui/components/verge`
+
+A reserved slot whose controls rest hidden and reveal on hover, on focus within the row, and always on touch (`pointer: coarse`). The slot holds its space throughout, so nothing shifts.
+
+The slot hides with opacity, never `display: none` or `visibility: hidden`, so its controls stay in the tab order: focus arriving on one is what reveals it. `pointer-events` is off at rest so the mouse cannot click a control it cannot see. An open menu or popover inside the slot holds it revealed.
+
+Used outside a `VergeRoot` it renders permanently visible rather than permanently hidden, because an unreachable control is the worse failure.
+
+Adapted from
+
+- Keep controls visually small and give them a 44 by 44 pixel hit area on coarse pointers; the slot reserves space but does not own the controls' hit area.
+- Use `slots` only to align controls into a column across rows with different counts; otherwise let the children size the slot.
+- Do not use `visible` to say a row matters more; a control drawn on every row at rest is furniture.
+
+## VisuallyHidden
+
+`@instruments/materia-ui/components/visually-hidden`
+
+Hides content visually while keeping it in the accessibility tree - for screen-reader-only labels and captions that must not take up layout space. RSC-safe.
+
+- Use for screen-reader-only text (e.g. a link's full context) - for icon-only `Button`s prefer the `aria-label` prop the component already requires.
+- Never hide interactive or focusable content inside it - sighted keyboard users would tab into something they cannot see.
+
+## VoicePill
+
+`@instruments/materia-ui/components/voice`
+
+The composer's send/voice control, morphing across a single `<button>`. A dumb, fully props-driven atom: it owns no timers, audio, or permissions - a parent drives every transition through `state`, `level`, and `elapsedMs`.
+
+States: `idle` shows the `Mic` (empty-composer control); `typing` swaps instantly to `ArrowUp`; `arming` gives a brief pre-listen pulse; `listening` widens the pill and crossfades (with a masking blur) to a live waveform plus a `tabular-nums` timer; `finalizing` freezes the bars and contracts faster than it expanded; `error` shakes once (or, under reduced motion, pulses a destructive tint). Carries a glass sheen so `idle` reads as a plain primary pill.
+
+- Keep this dumb - drive every transition from the parent through `state`/`level`/`elapsedMs`; it owns no timers, audio, or permissions.
+- Pass `label` per state (the parent decides the copy, e.g. "Voice input" vs "Stop dictation") so screen readers announce the current action; never hardcode it here.
+- Feed `level` from a real RMS meter while `listening` - a dead-flat waveform reads as a crashed mic; the atom floors and undulates the bars, but only live level makes it look alive.