@ultimat3/ui 1.0.0 → 1.1.0

package/CATALOG.md

@@ -0,0 +1,848 @@
+<!-- GENERATED by `bun run catalog` from packages/ui/src. Do not edit by hand. -->
+
+# @ultimat3/ui catalog
+
+Every component and every token, projected from source. Import all of it from `@ultimat3/ui`.
+
+46 components: `Alert` · `AppShell` · `Avatar` · `Badge` · `Breadcrumb` · `Button` · `Card` · `Checkbox` · `Container` · `DataTable` · `DateTime` · `Dialog` · `Divider` · `Drawer` · `EmptyState` · `ErrorState` · `Field` · `Form` · `Grid` · `IconButton` · `Image` · `Input` · `Link` · `LocaleSwitcher` · `Menu` · `Money` · `PageHeader` · `Pagination` · `Popover` · `Radio` · `RelativeTime` · `Section` · `Select` · `Skeleton` · `Spinner` · `Stack` · `Switch` · `Table` · `Tabs` · `Text` · `Textarea` · `ThemeToggle` · `ToastRegion` · `Toast` · `Toolbar` · `Tooltip`
+
+## Vocabulary
+
+One size scale, one tone scale, one variant scale — shared by every component that has them.
+
+| Scale | Values |
+|---|---|
+| `Size` | `sm` · `md` · `lg` |
+| `Tone` | `neutral` · `accent` · `success` · `warning` · `danger` · `info` |
+| `ButtonVariant` | `primary` · `secondary` · `ghost` · `link` |
+| `SpaceStep` | `0` · `1` · `2` · `3` · `4` · `5` · `6` · `8` · `10` · `12` · `16` |
+
+## Components
+
+### Alert
+
+Inline message bound to the page, not the viewport. `danger`/`warning` use `role="alert"` (assertive); the rest use `role="status"`, so an informational banner never interrupts what a screen-reader user is doing.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `title` | `string` | — | Already-translated heading. |
+| `children` | `JSX.Element` | yes |  |
+| `tone` | `Tone` | — |  |
+| `icon` | `JSX.Element` | — |  |
+| `onDismiss` | `(() => void)` | — | Provide both to make the alert dismissible; the label is the a11y name. |
+| `dismissLabel` | `string` | — |  |
+| `class` | `string` | — |  |
+
+### AppShell
+
+The page frame every app screen sits in: skip link, banner, navigation, main, contentinfo. Stateless on purpose — below `md` the sidebar becomes a band above the content instead of growing an open/closed flag, because an off-canvas menu is already `Drawer` and axiom 1 allows exactly one of those.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `children` | `JSX.Element` | yes | The page. Rendered inside the one `<main>`, which is the skip link's target. |
+| `header` | `JSX.Element` | — |  |
+| `sidebar` | `JSX.Element` | — | Rendered inside a `<nav>` landmark at the inline start. |
+| `footer` | `JSX.Element` | — |  |
+| `sidebarLabel` | `string` | — | Accessible name for the sidebar landmark. Defaults to the translated `ui.navigation`. |
+| `skipLabel` | `string` | — | Skip-link text. Defaults to the translated `ui.skip`. |
+| `sidebarWidth` | `string` | — | Sidebar track width at `md` and up. Any CSS length. |
+| `stickyHeader` | `boolean` | — | Keeps the header pinned while the main region scrolls. |
+| `class` | `string` | — |  |
+
+### Avatar
+
+Identity chip. An avatar image always carries intrinsic dimensions and an empty alt (the name is rendered as text or the accessible label), so it can never shift layout or duplicate the name to a screen reader.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `name` | `string` | yes | Already-localised display name. Drives initials and the accessible name. |
+| `src` | `string` | — |  |
+| `size` | `Size \| 'xs' \| 'xl'` | — |  |
+| `shape` | `'circle' \| 'rounded'` | — |  |
+| `status` | `'online' \| 'busy' \| 'offline'` | — | Presence ring; the meaning must also be conveyed in text nearby. |
+| `class` | `string` | — |  |
+
+### Badge
+
+Small status label. Tone maps straight onto the status colour roles so the same component is legible on both themes with no per-theme override.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `children` | `JSX.Element` | yes |  |
+| `tone` | `Tone` | — |  |
+| `size` | `Size` | — |  |
+| `variant` | `'soft' \| 'solid' \| 'outline'` | — |  |
+| `dot` | `boolean` | — | Renders a leading dot; pair with a tone that carries the meaning. |
+| `class` | `string` | — |  |
+
+### Breadcrumb
+
+Ancestor trail. The last item is the current page: rendered as text, never a link, and marked `aria-current="page"`. Separators are decorative CSS.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `items` | `readonly BreadcrumbItem[]` | yes |  |
+| `label` | `string` | — | Overrides the translated `ui.breadcrumb` landmark name. |
+| `class` | `string` | — |  |
+
+### Button
+
+The one button. Variants and tones are token-driven, so dark mode and RTL need no extra rules; `loading` keeps the label mounted to avoid a layout jump.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `children` | `JSX.Element` | yes | Visible label. Never hardcoded inside the component. |
+| `variant` | `ButtonVariant` | — |  |
+| `tone` | `Tone` | — |  |
+| `size` | `Size` | — |  |
+| `type` | `'button' \| 'submit' \| 'reset'` | — |  |
+| `disabled` | `boolean` | — |  |
+| `loading` | `boolean` | — | Blocks interaction and announces progress via `aria-busy`. |
+| `fullWidth` | `boolean` | — |  |
+| `iconStart` | `JSX.Element` | — |  |
+| `iconEnd` | `JSX.Element` | — |  |
+| `id` | `string` | — |  |
+| `class` | `string` | — |  |
+| `aria-label` | `string` | — |  |
+| `aria-controls` | `string` | — |  |
+| `aria-expanded` | `boolean` | — |  |
+| `onClick` | `JSX.EventHandlerUnion<HTMLButtonElement, MouseEvent>` | — |  |
+
+### Card
+
+Surface container. Elevation is a token rung, and because the shadow tokens are themed the same `elevation` reads correctly on light and dark.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `children` | `JSX.Element` | yes |  |
+| `header` | `JSX.Element` | — |  |
+| `footer` | `JSX.Element` | — |  |
+| `elevation` | `Elevation` | — |  |
+| `padding` | `SpaceStep` | — |  |
+| `interactive` | `boolean` | — | Adds hover affordance. Only use when the whole card is a link/button. |
+| `as` | `'div' \| 'article' \| 'section' \| 'li'` | — |  |
+| `class` | `string` | — |  |
+
+### Checkbox
+
+Native checkbox with a token-drawn indicator. The label element wraps the input, so the whole row is a hit target without a manual `for`/`id` pairing.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `label` | `string` | yes | Already-translated label. Required — an unlabelled checkbox is a bug. |
+| `id` | `string` | — |  |
+| `name` | `string` | — |  |
+| `value` | `string` | — |  |
+| `checked` | `boolean` | — |  |
+| `indeterminate` | `boolean` | — | Tri-state for "some children selected". Mirrored to `aria-checked`. |
+| `disabled` | `boolean` | — |  |
+| `required` | `boolean` | — |  |
+| `description` | `string` | — |  |
+| `class` | `string` | — |  |
+| `aria-describedby` | `string` | — |  |
+| `aria-invalid` | `boolean` | — |  |
+| `onChange` | `JSX.EventHandlerUnion<HTMLInputElement, Event>` | — |  |
+
+### Container
+
+Centred measure with a gutter. `margin-inline: auto` and `min()` mean one declaration covers every viewport and both writing directions.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `children` | `JSX.Element` | yes |  |
+| `size` | `ContainerSize` | — |  |
+| `gutter` | `SpaceStep` | — |  |
+| `as` | `'div' \| 'main' \| 'section' \| 'article' \| 'header' \| 'footer'` | — |  |
+| `class` | `string` | — |  |
+
+### DataTable
+
+Data-driven table: sortable headers, cursor pagination, and the four states a real list always has (loading, error, empty, data). The error state renders an UltimateError with the same code/cause/fix strings the terminal prints.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `caption` | `string` | yes |  |
+| `columns` | `readonly Column<Row>[]` | yes |  |
+| `rows` | `readonly Row[]` | yes |  |
+| `rowKey` | `(row: Row) => string` | yes |  |
+| `sort` | `SortState` | — |  |
+| `onSortChange` | `(sort: SortState \| undefined) => void` | — |  |
+| `loading` | `boolean` | — |  |
+| `error` | `unknown` | — | An UltimateError (or anything shaped like one) from the query. |
+| `onRetry` | `(() => void)` | — |  |
+| `emptyTitle` | `string` | — |  |
+| `emptyDescription` | `string` | — |  |
+| `nextCursor` | `string` | — | Opaque cursors from the query result; absent means no further page. |
+| `prevCursor` | `string` | — |  |
+| `onCursor` | `((cursor: string, direction: 'next' \| 'prev') => void)` | — |  |
+| `stickyHeader` | `boolean` | — |  |
+| `density` | `'comfortable' \| 'compact'` | — |  |
+| `skeletonRows` | `number` | — | Placeholder row count while loading. Match the usual page size. |
+| `class` | `string` | — |  |
+
+### DateTime
+
+Renders <time datetime="<ISO instant>"> with text formatted in the context time zone. The attribute is always the UTC instant so crawlers, tests, and other machines read the same value regardless of the viewer's zone.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `value` | `TimeInput` | yes |  |
+| `timeZone` | `TimeZone` | — | Overrides the context zone. Use for "in the venue's local time" displays. |
+| `locale` | `string` | — |  |
+| `dateStyle` | `DateStyle` | — |  |
+| `timeStyle` | `DateStyle` | — |  |
+| `format` | `DateTimeFormatter` | — |  |
+| `class` | `string` | — |  |
+
+### Dialog
+
+Modal built on native <dialog>: the platform gives us the top layer, the backdrop, inert background content, and Escape-to-close for free. We add the labelled heading, the close affordance, and body scroll locking.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `open` | `boolean` | yes |  |
+| `title` | `string` | yes | Already-translated title. Becomes the dialog's accessible name. |
+| `children` | `JSX.Element` | yes |  |
+| `footer` | `JSX.Element` | — |  |
+| `onClose` | `() => void` | yes |  |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'full'` | — |  |
+| `dismissOnBackdrop` | `boolean` | — | Clicking the backdrop closes. Turn off for destructive confirmations. |
+| `class` | `string` | — |  |
+
+### Divider
+
+A rule. Always an explicit `role="separator"` with an orientation; pass `label` to render a captioned separator, which is what a settings group actually needs.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `orientation` | `'horizontal' \| 'vertical'` | — |  |
+| `label` | `string` | — | Visible, already-translated caption rendered inside the rule. |
+| `class` | `string` | — |  |
+
+### Drawer
+
+Edge-anchored panel, also a native <dialog> so it inherits the top layer and inert background. `side` is logical (`inline-start`/`inline-end`), so a drawer pinned to the start edge lands on the right in an RTL locale automatically.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `open` | `boolean` | yes |  |
+| `title` | `string` | yes | Already-translated title. Becomes the drawer's accessible name. |
+| `children` | `JSX.Element` | yes |  |
+| `onClose` | `() => void` | yes |  |
+| `side` | `DrawerSide` | — |  |
+| `size` | `string` | — |  |
+| `footer` | `JSX.Element` | — |  |
+| `class` | `string` | — |  |
+
+### EmptyState
+
+The "nothing here yet" surface. Title and description arrive as already translated strings; the action slot takes a Button so there is one CTA shape.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `title` | `string` | — | Already-translated. Falls back to the `ui.empty` catalog key. |
+| `description` | `string` | — |  |
+| `icon` | `JSX.Element` | — |  |
+| `action` | `JSX.Element` | — |  |
+| `class` | `string` | — |  |
+
+### ErrorState
+
+Renders an UltimateError with the same three strings the terminal prints: code, cause, fix. Identical text in the CLI, the overlay, and `--json` is the whole point of the error contract — this component must not paraphrase.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `error` | `unknown` | yes | An UltimateError, or any thrown value; unknown values get X_INTERNAL text. |
+| `onRetry` | `(() => void)` | — |  |
+| `retryLabel` | `string` | — | Already-translated; falls back to the ui.* catalog keys. |
+| `showDocs` | `boolean` | — | Link the code to its docs page. On by default. |
+| `class` | `string` | — |  |
+
+### Field
+
+Label + hint + error, wired for a11y. Field owns the ids and hands them to the control through a render prop, so `aria-describedby` and `aria-invalid` can never drift out of sync with what is actually rendered.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `label` | `string` | yes | Already-translated label. Rendered as a real <label for>. |
+| `children` | `(control: FieldControl) => JSX.Element` | yes |  |
+| `hint` | `string` | — |  |
+| `error` | `string` | — | Present means invalid; the string is announced with the control. |
+| `required` | `boolean` | — |  |
+| `markOptional` | `boolean` | — | Appends a translated "(optional)" marker instead of marking required. |
+| `class` | `string` | — |  |
+
+### Form
+
+Form shell. Owns the one thing every form needs and always forgets: a top-of-form error summary that is focusable and announced on submit.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `children` | `JSX.Element` | yes |  |
+| `error` | `string` | — | Already-translated summary shown above the fields when submit fails. |
+| `errorTitle` | `string` | — | Already-translated heading for the error summary region. |
+| `actions` | `JSX.Element` | — |  |
+| `gap` | `SpaceStep` | — |  |
+| `method` | `'get' \| 'post'` | — |  |
+| `action` | `string` | — |  |
+| `novalidate` | `boolean` | — |  |
+| `class` | `string` | — |  |
+| `aria-label` | `string` | — |  |
+| `onSubmit` | `JSX.EventHandlerUnion<HTMLFormElement, SubmitEvent>` | — |  |
+
+### Grid
+
+Grid layout primitive. The default is an intrinsic responsive grid (`auto-fit` + `minmax`) so most layouts need no breakpoint at all.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `children` | `JSX.Element` | yes |  |
+| `columns` | `number` | — | Fixed track count. Omit for the intrinsic `auto-fit` behaviour. |
+| `minColumn` | `string` | — | Minimum track width for the intrinsic grid. |
+| `gap` | `SpaceStep` | — |  |
+| `rowGap` | `SpaceStep` | — |  |
+| `as` | `'div' \| 'ul' \| 'ol' \| 'section'` | — |  |
+| `class` | `string` | — |  |
+
+### IconButton
+
+A button whose only content is an icon, so `label` is mandatory: it becomes the accessible name and the tooltip. There is no unlabelled icon button.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `label` | `string` | yes | Required accessible name — also used as the native tooltip. |
+| `children` | `JSX.Element` | yes |  |
+| `variant` | `ButtonVariant` | — |  |
+| `tone` | `Tone` | — |  |
+| `size` | `Size` | — |  |
+| `disabled` | `boolean` | — |  |
+| `round` | `boolean` | — |  |
+| `id` | `string` | — |  |
+| `class` | `string` | — |  |
+| `aria-pressed` | `boolean` | — |  |
+| `aria-expanded` | `boolean` | — |  |
+| `aria-controls` | `string` | — |  |
+| `onClick` | `JSX.EventHandlerUnion<HTMLButtonElement, MouseEvent>` | — |  |
+
+### Image
+
+Zero-CLS image primitive: a plain <img>, no JS, no fetch, no client state.  The build-time half of the pipeline in `docs/idea/07-rendering-seo.md` — reading real dimensions, encoding AVIF/WebP renditions, the data-URI blur placeholder — is NOT here. This component emits exactly what it is handed and fabricates nothing: no variants it was not given, no dimensions it did not measure.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `src` | `string` | yes |  |
+| `alt` | `string` | yes | Required, with no default: an <Image> whose meaning is undescribed is a type error at the call site. Pass `alt=""` for a decorative image, deliberately. |
+| `variants` | `readonly ImageVariant[]` | — | Renditions to offer; the descriptors and their order are derived, not written. |
+| `sizes` | `string` | — | Layout width of the box, e.g. `(max-width: 700px) 100vw, 620px`. |
+| `priority` | `boolean` | — | The LCP image, at most one per route: eager, high fetch priority. |
+| `width` | `number` | — | Intrinsic dimensions, from the build step that measured them. Both or neither. |
+| `height` | `number` | — |  |
+| `class` | `string` | — |  |
+
+### Input
+
+Single-line text control. No `type="number"` convenience wrapper: numeric input uses `inputmode` + a text type so locale decimal separators survive.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `id` | `string` | — |  |
+| `name` | `string` | — |  |
+| `type` | `InputType` | — |  |
+| `value` | `string` | — |  |
+| `placeholder` | `string` | — |  |
+| `size` | `Size` | — |  |
+| `required` | `boolean` | — |  |
+| `disabled` | `boolean` | — |  |
+| `readonly` | `boolean` | — |  |
+| `autocomplete` | `string` | — |  |
+| `inputmode` | `'text' \| 'numeric' \| 'decimal' \| 'tel' \| 'email' \| 'url' \| 'search'` | — |  |
+| `maxlength` | `number` | — |  |
+| `prefix` | `JSX.Element` | — | Non-interactive adornments; keep them icons or units, never controls. |
+| `suffix` | `JSX.Element` | — |  |
+| `class` | `string` | — |  |
+| `aria-label` | `string` | — |  |
+| `aria-describedby` | `string` | — |  |
+| `aria-invalid` | `boolean` | — |  |
+| `onInput` | `JSX.EventHandlerUnion<HTMLInputElement, InputEvent>` | — |  |
+| `onChange` | `JSX.EventHandlerUnion<HTMLInputElement, Event>` | — |  |
+| `onBlur` | `JSX.EventHandlerUnion<HTMLInputElement, FocusEvent>` | — |  |
+
+### Link
+
+Anchor primitive. External links get `rel` hardening and a translated "opens in a new tab" hint automatically — never a bare `target="_blank"`.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `href` | `string` | yes |  |
+| `children` | `JSX.Element` | yes |  |
+| `external` | `boolean` | — |  |
+| `externalHint` | `string` | — | Announced suffix for external links; supply via `t()` at the call site. |
+| `underline` | `'always' \| 'hover' \| 'none'` | — |  |
+| `tone` | `'accent' \| 'inherit'` | — |  |
+| `id` | `string` | — |  |
+| `class` | `string` | — |  |
+| `aria-current` | `'page' \| 'step' \| 'true' \| false` | — |  |
+| `onClick` | `JSX.EventHandlerUnion<HTMLAnchorElement, MouseEvent>` | — |  |
+
+### LocaleSwitcher
+
+Locale picker. Option labels come from `Intl.DisplayNames` in each locale's own language (endonyms), so the list needs no translation catalog of its own.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `locales` | `readonly Locale[]` | yes |  |
+| `value` | `Locale` | — | Defaults to the context locale. |
+| `onLocaleChange` | `((locale: Locale) => void)` | — |  |
+| `hrefFor` | `((locale: Locale) => string)` | — | Render as links instead of a select, for a 0kb-JS `site/` route. |
+| `class` | `string` | — |  |
+
+### Menu
+
+Action menu: a trigger plus a `role="menu"` list with roving tabindex. Distinct from Select — a menu runs commands, it does not hold a form value.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `items` | `readonly MenuItem[]` | yes |  |
+| `open` | `boolean` | yes |  |
+| `onOpenChange` | `(open: boolean) => void` | yes |  |
+| `trigger` | `(control: { id: string; 'aria-haspopup': 'menu'; 'aria-expanded': boolean; 'aria-controls': string; }) => JSX.Element` | yes |  |
+| `label` | `string` | yes | Already-translated accessible name for the menu. |
+| `align` | `'start' \| 'end'` | — |  |
+| `class` | `string` | — |  |
+
+### Money
+
+Formats through @ultimat3/money using the locale and currency from context — never a process-wide default, never a float, never a hardcoded symbol.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `value` | `MoneyValue \| number` | yes | A Money value, or bare minor units in the context currency. |
+| `currency` | `string` | — | Overrides the context currency for bare-number values. |
+| `locale` | `string` | — | Overrides the context locale. Use only for side-by-side comparisons. |
+| `signed` | `boolean` | — | Colour negatives with the danger role, e.g. in a ledger. |
+| `options` | `FormatMoneyOptions` | — | Passed to @ultimat3/money: display, accounting, grouping, fractionDigits. |
+| `format` | `MoneyFormatter` | — |  |
+| `class` | `string` | — |  |
+
+### PageHeader
+
+The top of a screen: breadcrumbs, the page's one heading, a description, and the actions that belong to the page rather than to a row in it. Hand-rolled, this is where the heading level, the landmark and the action alignment go wrong; here it is one component with one shape.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `title` | `string` | yes | Already-translated page title. Rendered as the heading, once. |
+| `description` | `string` | — | Already-translated supporting line under the title. |
+| `actions` | `JSX.Element` | — | Trailing controls — a Button, a Toolbar. Wraps under the title on narrow viewports. |
+| `breadcrumbs` | `readonly BreadcrumbItem[]` | — |  |
+| `level` | `HeadingLevel` | — | Heading level. 1 by default: a screen has exactly one h1, and this is it. |
+| `media` | `JSX.Element` | — | Rendered before the title — an avatar, an icon, a status dot. |
+| `class` | `string` | — |  |
+
+### Pagination
+
+Cursor-first pagination — the only shape a Postgres-backed list should use. Numbered mode exists for prerendered archives where the total is known.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `nextCursor` | `string` | — | Opaque cursor for the following page; absent disables "next". |
+| `prevCursor` | `string` | — |  |
+| `onCursor` | `((cursor: string, direction: 'next' \| 'prev') => void)` | — |  |
+| `page` | `number` | — | Numbered mode: 1-based page and total. Ignored when cursors are present. |
+| `totalPages` | `number` | — |  |
+| `onPage` | `((page: number) => void)` | — |  |
+| `labelPrevious` | `string` | — | Already-translated; falls back to the ui.* catalog keys. |
+| `labelNext` | `string` | — |  |
+| `class` | `string` | — |  |
+
+### Popover
+
+Non-modal anchored panel. Positioning is CSS-only (a relatively positioned anchor plus logical insets), so there is no measure/reflow loop and the panel flips sides automatically under `dir="rtl"`.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `open` | `boolean` | yes |  |
+| `onOpenChange` | `(open: boolean) => void` | yes |  |
+| `trigger` | `(control: { id: string; 'aria-expanded': boolean; 'aria-controls': string; }) => JSX.Element` | yes | The anchor. Wire its onClick to `onOpenChange` in the caller. |
+| `children` | `JSX.Element` | yes |  |
+| `label` | `string` | yes | Already-translated accessible name for the panel. |
+| `placement` | `Placement` | — |  |
+| `align` | `'start' \| 'center' \| 'end'` | — |  |
+| `class` | `string` | — |  |
+
+### Radio
+
+Radio group. Rendered as a <fieldset>/<legend> so the group has a name, and as one native radio per option so arrow-key navigation is the platform's job.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `legend` | `string` | yes | Already-translated group label, rendered as the <legend>. |
+| `name` | `string` | yes |  |
+| `options` | `readonly RadioOption[]` | yes |  |
+| `value` | `string` | — |  |
+| `disabled` | `boolean` | — |  |
+| `required` | `boolean` | — |  |
+| `direction` | `'row' \| 'column'` | — |  |
+| `class` | `string` | — |  |
+| `aria-describedby` | `string` | — |  |
+| `onChange` | `JSX.EventHandlerUnion<HTMLInputElement, Event>` | — |  |
+
+### RelativeTime
+
+"3 minutes ago" with the absolute instant in both `datetime` and `title`, so hovering (or reading the DOM) always recovers the exact time.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `value` | `TimeInput` | yes |  |
+| `now` | `TimeInput` | — | Pass explicitly for SSR so server and client render the same string. |
+| `locale` | `string` | — |  |
+| `timeZone` | `TimeZone` | — |  |
+| `numeric` | `'always' \| 'auto'` | — |  |
+| `format` | `DateTimeFormatter` | — |  |
+| `class` | `string` | — |  |
+
+### Section
+
+A titled block inside a page. Exists so a screen's second-level structure is a labelled landmark with a real heading — `aria-labelledby` wired to the heading it renders — instead of a <div> with bold text, which is what an unassisted layout always becomes.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `children` | `JSX.Element` | yes |  |
+| `title` | `string` | — | Already-translated section title. Omit for an unlabelled grouping. |
+| `description` | `string` | — | Already-translated supporting line under the title. |
+| `actions` | `JSX.Element` | — | Controls that act on this section only. |
+| `level` | `HeadingLevel` | — | Heading level. 2 by default — the level under a PageHeader's h1. |
+| `as` | `'section' \| 'article' \| 'aside'` | — |  |
+| `class` | `string` | — |  |
+
+### Select
+
+Native <select>. Deliberately not a custom listbox: the platform control wins on mobile, on keyboard, and with screen readers.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `options` | `readonly SelectOption[]` | yes |  |
+| `id` | `string` | — |  |
+| `name` | `string` | — |  |
+| `value` | `string` | — |  |
+| `placeholder` | `string` | — | Rendered as a disabled first option, so it is never a submittable value. |
+| `size` | `Size` | — |  |
+| `required` | `boolean` | — |  |
+| `disabled` | `boolean` | — |  |
+| `class` | `string` | — |  |
+| `aria-label` | `string` | — |  |
+| `aria-describedby` | `string` | — |  |
+| `aria-invalid` | `boolean` | — |  |
+| `onChange` | `JSX.EventHandlerUnion<HTMLSelectElement, Event>` | — |  |
+
+### Skeleton
+
+Loading placeholder. Sized by the caller so the real content lands in the same box — a skeleton that changes size on load is just a slower layout shift.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `width` | `string` | — | CSS length; must match the real content's box to keep CLS at 0. |
+| `height` | `string` | — |  |
+| `shape` | `'text' \| 'block' \| 'circle'` | — |  |
+| `lines` | `number` | — | Repeat as stacked lines, e.g. a paragraph placeholder. |
+| `class` | `string` | — |  |
+
+### Spinner
+
+Indeterminate progress. `role="status"` plus a translated name, because a spinner with no accessible name is silence to a screen reader.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `size` | `Size` | — |  |
+| `label` | `string` | — | Overrides the translated `ui.loading` default. |
+| `decorative` | `boolean` | — | Hide from assistive tech when a parent already announces the busy state. |
+| `class` | `string` | — |  |
+
+### Stack
+
+Flex layout primitive. Gap comes from the space scale as a custom property, so there is no class per step, and `row` uses `flex-direction: row` — which the browser already mirrors under `dir="rtl"`.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `children` | `JSX.Element` | yes |  |
+| `direction` | `'row' \| 'column'` | — |  |
+| `gap` | `SpaceStep` | — |  |
+| `align` | `Align` | — |  |
+| `justify` | `Align` | — |  |
+| `wrap` | `boolean` | — |  |
+| `as` | `'div' \| 'ul' \| 'ol' \| 'nav' \| 'section' \| 'header' \| 'footer'` | — | Renders a semantic element instead of a div. |
+| `class` | `string` | — |  |
+
+### Switch
+
+Boolean toggle with immediate effect (as opposed to Checkbox, which is part of a form submit). `role="switch"` on a native checkbox keeps keyboard behaviour.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `label` | `string` | yes | Already-translated label. Required — the state alone is not a name. |
+| `checked` | `boolean` | — |  |
+| `id` | `string` | — |  |
+| `name` | `string` | — |  |
+| `disabled` | `boolean` | — |  |
+| `labelPosition` | `'start' \| 'end'` | — | Put the label before the track, e.g. in a settings row. |
+| `class` | `string` | — |  |
+| `aria-describedby` | `string` | — |  |
+| `onChange` | `JSX.EventHandlerUnion<HTMLInputElement, Event>` | — |  |
+
+### Table
+
+Presentational table. Owns two things every hand-rolled table gets wrong: a sticky header, and horizontal overflow contained inside the table's own scroll container so the page body never scrolls sideways.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `caption` | `string` | yes | Already-translated caption. Required: a table needs an accessible name. |
+| `children` | `JSX.Element` | yes |  |
+| `hideCaption` | `boolean` | — | Hide the caption visually while keeping it for assistive tech. |
+| `stickyHeader` | `boolean` | — |  |
+| `density` | `'comfortable' \| 'compact'` | — |  |
+| `striped` | `boolean` | — | Zebra striping. Off by default — a border is usually enough. |
+| `class` | `string` | — |  |
+
+### Tabs
+
+Tablist with roving tabindex: one Tab in the page tab order, arrows move between them, Home/End jump to the ends, and arrow direction follows `dir`.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `items` | `readonly TabItem[]` | yes |  |
+| `value` | `string` | yes | Selected tab id. Controlled — the caller owns the state. |
+| `onChange` | `(id: string) => void` | yes |  |
+| `label` | `string` | yes | Already-translated accessible name for the tablist. |
+| `orientation` | `'horizontal' \| 'vertical'` | — |  |
+| `class` | `string` | — |  |
+
+### Text
+
+Typography primitive. Tone is a foreground or status colour role, size and weight are keys of the type scale — so body copy, captions and inline status text come from one component and stay legible on both themes.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `children` | `JSX.Element` | yes |  |
+| `tone` | `TextTone` | — |  |
+| `size` | `TextSize` | — |  |
+| `weight` | `TextWeight` | — |  |
+| `as` | `'span' \| 'p' \| 'div' \| 'strong' \| 'em'` | — | Renders a semantic element instead of a span; `p` for flow text. `strong` and `em` carry meaning to assistive tech — `weight` and `tone` do not. |
+| `class` | `string` | — |  |
+
+### Textarea
+
+Multi-line text control. `field-sizing: content` grows the box natively where supported, with `rows` as the floor — no resize observer, no JS.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `id` | `string` | — |  |
+| `name` | `string` | — |  |
+| `value` | `string` | — |  |
+| `placeholder` | `string` | — |  |
+| `rows` | `number` | — |  |
+| `required` | `boolean` | — |  |
+| `disabled` | `boolean` | — |  |
+| `readonly` | `boolean` | — |  |
+| `maxlength` | `number` | — |  |
+| `autoGrow` | `boolean` | — |  |
+| `class` | `string` | — |  |
+| `aria-label` | `string` | — |  |
+| `aria-describedby` | `string` | — |  |
+| `aria-invalid` | `boolean` | — |  |
+| `onInput` | `JSX.EventHandlerUnion<HTMLTextAreaElement, InputEvent>` | — |  |
+| `onBlur` | `JSX.EventHandlerUnion<HTMLTextAreaElement, FocusEvent>` | — |  |
+
+### ThemeToggle
+
+Theme control. `toggle` flips light/dark; `select` also offers "system", which clears the stored choice so the OS takes over again. All strings come from the catalog, and the DOM work happens in theme.ts, never here.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `mode` | `'toggle' \| 'select'` | — |  |
+| `initial` | `Theme` | — | Server-render value; the effect corrects it on the client before paint. |
+| `env` | `ThemeEnv` | — | Injectable for tests and for non-DOM hosts. |
+| `class` | `string` | — |  |
+
+### ToastRegion
+
+Transient notification. ToastRegion is the single live region for the app; individual Toasts are its children, so announcements are not duplicated and the region exists before the first message (screen readers require that).
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `children` | `JSX.Element` | yes |  |
+| `label` | `string` | yes | Already-translated landmark name, e.g. "Notifications". |
+| `placement` | `'block-end-inline-end' \| 'block-start-inline-end' \| 'block-end-center'` | — |  |
+| `class` | `string` | — |  |
+
+### Toast
+
+Transient notification. ToastRegion is the single live region for the app; individual Toasts are its children, so announcements are not duplicated and the region exists before the first message (screen readers require that).
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `children` | `JSX.Element` | yes | Already-translated message. |
+| `title` | `string` | — |  |
+| `tone` | `Tone` | — |  |
+| `action` | `JSX.Element` | — |  |
+| `onDismiss` | `(() => void)` | — |  |
+| `dismissLabel` | `string` | — |  |
+| `class` | `string` | — |  |
+
+### Toolbar
+
+The control strip above a table or a list: filters and search at the inline start, actions at the inline end. `role="toolbar"` with the same roving-tabindex helper Tabs uses, so arrow keys move between controls and the strip costs one Tab stop instead of a dozen.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `children` | `JSX.Element` | yes | Leading controls — search, filters, a Select. |
+| `actions` | `JSX.Element` | — | Trailing controls, pushed to the inline end. |
+| `label` | `string` | yes | Already-translated accessible name. Required: an unnamed toolbar is an unnamed group. |
+| `surface` | `boolean` | — | Renders the strip on a raised, bordered surface. |
+| `class` | `string` | — |  |
+
+### Tooltip
+
+Supplementary hint, shown on hover AND on keyboard focus. CSS-only, so it costs no JS; the content is wired with `aria-describedby`, never `title`, because `title` is unreachable by keyboard and untranslatable by the platform.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `content` | `string` | yes | Already-translated hint text. Never the element's only accessible name. |
+| `children` | `(control: { 'aria-describedby': string }) => JSX.Element` | yes |  |
+| `placement` | `'block-start' \| 'block-end'` | — |  |
+| `class` | `string` | — |  |
+
+## Tokens
+
+Colour roles are the only colours that exist. Use them through SCSS (`t.role('accent')`) or
+CSS (`rgb(var(--color-accent) / 0.12)`); `colorRgb(theme, role)` resolves one for canvas,
+charts and email.
+
+### Colour roles
+
+| Role | Custom property |
+|---|---|
+| `bg` | `--color-bg` |
+| `bg-soft` | `--color-bg-soft` |
+| `surface` | `--color-surface` |
+| `surface-raised` | `--color-surface-raised` |
+| `fg` | `--color-fg` |
+| `fg-strong` | `--color-fg-strong` |
+| `fg-muted` | `--color-fg-muted` |
+| `line` | `--color-line` |
+| `scrim` | `--color-scrim` |
+| `accent` | `--color-accent` |
+| `accent-strong` | `--color-accent-strong` |
+| `accent-fg` | `--color-accent-fg` |
+| `success` | `--color-success` |
+| `success-soft` | `--color-success-soft` |
+| `success-fg` | `--color-success-fg` |
+| `warning` | `--color-warning` |
+| `warning-soft` | `--color-warning-soft` |
+| `warning-fg` | `--color-warning-fg` |
+| `danger` | `--color-danger` |
+| `danger-soft` | `--color-danger-soft` |
+| `danger-fg` | `--color-danger-fg` |
+| `info` | `--color-info` |
+| `info-soft` | `--color-info-soft` |
+| `info-fg` | `--color-info-fg` |
+
+### Space — `--space-*`
+
+| Token | Value |
+|---|---|
+| `0` | `0` |
+| `1` | `0.25rem` |
+| `2` | `0.5rem` |
+| `3` | `0.75rem` |
+| `4` | `1rem` |
+| `5` | `1.25rem` |
+| `6` | `1.5rem` |
+| `8` | `2rem` |
+| `10` | `2.5rem` |
+| `12` | `3rem` |
+| `16` | `4rem` |
+
+### Radius — `--radius-*`
+
+| Token | Value |
+|---|---|
+| `none` | `0` |
+| `sm` | `0.25rem` |
+| `md` | `0.5rem` |
+| `lg` | `0.75rem` |
+| `xl` | `1rem` |
+| `pill` | `999px` |
+| `full` | `50%` |
+
+### Font size — `--text-*`
+
+| Token | Value |
+|---|---|
+| `xs` | `clamp(0.75rem, 0.73rem + 0.1vw, 0.8125rem)` |
+| `sm` | `clamp(0.875rem, 0.85rem + 0.15vw, 0.9375rem)` |
+| `md` | `clamp(1rem, 0.96rem + 0.2vw, 1.0625rem)` |
+| `lg` | `clamp(1.125rem, 1.05rem + 0.35vw, 1.25rem)` |
+| `xl` | `clamp(1.375rem, 1.2rem + 0.7vw, 1.75rem)` |
+| `2xl` | `clamp(1.75rem, 1.4rem + 1.4vw, 2.5rem)` |
+| `3xl` | `clamp(2.25rem, 1.6rem + 2.6vw, 3.5rem)` |
+
+### Font weight — `--weight-*`
+
+| Token | Value |
+|---|---|
+| `normal` | `400` |
+| `medium` | `500` |
+| `semibold` | `600` |
+| `bold` | `700` |
+
+### Line height — `--leading-*`
+
+| Token | Value |
+|---|---|
+| `tight` | `1.2` |
+| `snug` | `1.35` |
+| `normal` | `1.55` |
+| `loose` | `1.75` |
+
+### Duration — `--duration-*`
+
+| Token | Value |
+|---|---|
+| `instant` | `0ms` |
+| `fast` | `120ms` |
+| `base` | `220ms` |
+| `slow` | `400ms` |
+| `slower` | `640ms` |
+
+### Easing — `--easing-*`
+
+| Token | Value |
+|---|---|
+| `out` | `cubic-bezier(0.16, 1, 0.3, 1)` |
+| `in` | `cubic-bezier(0.5, 0, 0.75, 0)` |
+| `in-out` | `cubic-bezier(0.65, 0, 0.35, 1)` |
+| `spring` | `cubic-bezier(0.34, 1.56, 0.64, 1)` |
+
+### Z-index — `--z-*`
+
+| Token | Value |
+|---|---|
+| `base` | `0` |
+| `raised` | `10` |
+| `sticky` | `100` |
+| `dropdown` | `200` |
+| `drawer` | `300` |
+| `dialog` | `400` |
+| `popover` | `500` |
+| `tooltip` | `600` |
+| `toast` | `700` |
+| `skip-nav` | `800` |
+
+### Breakpoints — `@include t.respond-to(<name>)`
+
+| Token | Value |
+|---|---|
+| `sm` | `480px` |
+| `md` | `768px` |
+| `lg` | `1024px` |
+| `xl` | `1280px` |
+| `2xl` | `1536px` |