@handamade/psi-react 0.20.0 → 0.22.0

package/docs/MenuItem.md

@@ -45,5 +45,5 @@ This component has no `--psi-menu-item-*` tokens — its styling binds scale tok
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/MenuSeparator.md

@@ -32,5 +32,5 @@ This component has no `--psi-menu-separator-*` tokens — its styling binds scal
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/NavBar.md

@@ -9,7 +9,9 @@ Top navigation bar with brand, nav-link, and trailing-action slots.
 |---|---|---|---|---|
 | `brand` | `ReactNode` | — | no | Brand slot (wordmark / logo link), leading edge. |
 | `actions` | `ReactNode` | — | no | Trailing actions slot (theme switch, CTA). |
-| `children` | `ReactNode` | — | no | Nav links. |
+| `children` | `ReactNode` | — | no | Nav links. The `<nav>` renders only when there are children, so a bar with a brand and actions and no links has no empty landmark (D88). |
+| `navLabel` | `string` | — | no | Accessible name of the links' `<nav>` (its `aria-label`). Rest props land on the `<header>`, so this is the only way to label the `<nav>` (D88). |
+| `fluid` | `boolean` | false | no | Lay the row out at full width: it drops `psi-container` (the centred max-width column) and keeps the `--psi-gutter` side padding. For an application header over a full-width frame (D88). |
 | `ref` | `Ref<HTMLElement>` | — | no | Forwarded ref to the header element. |
 | `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
 
@@ -28,5 +30,5 @@ Override `--psi-navbar-*` custom properties at any scope; interactive states der
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/NavGroup.md

@@ -0,0 +1,40 @@
+<!-- Generated by emit-docs.ts — do not edit. -->
+# NavGroup
+
+A collapsible group of `NavItem`s in a `NavTree` (D88). Controlled-only, like `Tabs` (D67): `open` and `onOpenChange` are required and nothing is remembered. Renders a native `<button aria-expanded aria-controls>` over a `<ul>` that is `hidden` when closed, so the items leave the layout and the accessibility tree while `aria-controls` keeps naming an element. The chevron turns with the state and is `aria-hidden`: the label and `aria-expanded` carry the meaning.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `label` | `ReactNode` | — | yes | The group's visible label, such as "Reports". |
+| `open` | `boolean` | — | yes | Whether the group's items are shown. Controlled. |
+| `onOpenChange` | `(open: boolean) => void` | — | yes | Called with the next state when the button is pressed. The group never changes `open` itself. |
+| `children` | `ReactNode` | — | yes | `NavItem`s of the group. |
+| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+
+## Keyboard & assistive tech
+
+| Keys | Behavior |
+|---|---|
+| Enter / Space | Activates the group's native button, which asks the parent to open or close the group through onOpenChange. |
+
+Controlled-only: open and onOpenChange are required and the group never changes its own state. Renders a <button type="button"> with aria-expanded and aria-controls naming its <ul>, which carries `hidden` when closed, so the links leave the layout and the accessibility tree while aria-controls still resolves. The chevron is aria-hidden and turns on a duration token; the label and aria-expanded carry the meaning.
+
+## Theming
+
+Override `--psi-nav-tree-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).
+
+
+
+## Rules
+
+- One accent per visual group; everything else neutral or ghost.
+- danger only for actions with real consequences.
+- Sizes are px numbers (24|32|40|48), never S/M/L.
+- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.
+- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
+- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
+- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
+- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/NavItem.md

@@ -0,0 +1,40 @@
+<!-- Generated by emit-docs.ts — do not edit. -->
+# NavItem
+
+One entry of a `NavTree` (D88): an `<li>` that styles the single anchor inside it. Router apps pass their own link as the child, so it keeps its `href` and handlers; with `current`, `NavItem` clones it to add `aria-current="page"` (D93), as `Menu` clones its trigger. `href` is for plain links and for presets, where the compose tree can hold only manifest components and a raw `<a>` is not one. The current page is never marked by colour alone: medium weight, a raised surface and a bar at the inline start.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `children` | `ReactNode` | — | yes | Without `href`: one anchor, your router's link. With `href`: the link's text. |
+| `href` | `string` | — | no | Render the anchor yourself (D88), for a plain link or a preset: the `<li>` holds `<a href>` with `children` as its text. Router apps leave it out and pass their own link as the child, so the link keeps its own handlers. |
+| `current` | `boolean` | — | no | Mark the link as the current page (`aria-current="page"`): on the anchor `href` renders, or on the single element you pass as a child (D93). Without `current`, a child's own `aria-current` is left alone, so a router that marks its active link keeps working. |
+| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+| `ref` | `Ref<HTMLLIElement>` | — | no | Forwarded ref to the `<li>`. |
+
+## Keyboard & assistive tech
+
+| Keys | Behavior |
+|---|---|
+| Enter | Follows the link inside it (native anchor behavior); the link is the consumer's router link. |
+
+An <li> that styles the one anchor inside it. Router apps pass their own link as the child; current clones it with aria-current="page" (D93), and without current the child keeps its own aria-current; with href the NavItem renders the anchor itself (for plain links and presets) and current sets aria-current="page" on it. The current page is marked by weight, a raised surface and an inline-start bar, never by colour alone, and the focus ring is drawn inset on the anchor.
+
+## Theming
+
+Override `--psi-nav-tree-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).
+
+
+
+## Rules
+
+- One accent per visual group; everything else neutral or ghost.
+- danger only for actions with real consequences.
+- Sizes are px numbers (24|32|40|48), never S/M/L.
+- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.
+- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
+- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
+- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
+- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/NavTree.md

@@ -0,0 +1,39 @@
+<!-- Generated by emit-docs.ts — do not edit. -->
+# NavTree
+
+A navigation tree (D88): a `<nav aria-label>` around a `<ul>` of `NavItem`s and `NavGroup`s. Native elements only — *Tab* moves through the group buttons and the links of open groups; there is no roving focus and no `role="menu"` or `role="tree"`, because site navigation is a list of links, not a widget. Router-agnostic: pass your router's link inside each `NavItem`, with `aria-current="page"` on the current one.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `aria-label` | `string` | — | yes | Accessible name of the navigation landmark, such as "Main". Required: an app has more than one `<nav>` (a header's, a sidebar's), and an unnamed one is indistinguishable from the rest. Declared here rather than inherited so docgen keeps it in the manifest (D60). |
+| `children` | `ReactNode` | — | yes | `NavItem`s and `NavGroup`s — each renders an `<li>`. |
+| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+| `ref` | `Ref<HTMLElement>` | — | no | Forwarded ref to the `<nav>`. |
+
+## Keyboard & assistive tech
+
+| Keys | Behavior |
+|---|---|
+| Tab / Shift+Tab | Moves through the group buttons and the links of open groups in document order. There is no roving focus and no arrow-key model: it is a list of links, not a menu or a tree widget. |
+
+A native <nav> around a <ul>, named by the required aria-label (an app has more than one navigation landmark). No role="menu" or role="tree" is used (D88). Router-agnostic: the consumer passes its router's link inside each NavItem.
+
+## Theming
+
+Override `--psi-nav-tree-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).
+
+
+
+## Rules
+
+- One accent per visual group; everything else neutral or ghost.
+- danger only for actions with real consequences.
+- Sizes are px numbers (24|32|40|48), never S/M/L.
+- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.
+- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
+- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
+- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
+- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/Pagination.md

@@ -29,5 +29,5 @@ This component has no `--psi-pagination-*` tokens — its styling binds scale to
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/Panel.md

@@ -35,5 +35,5 @@ Override `--psi-panel-*` custom properties at any scope.
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/Select.md

@@ -37,5 +37,5 @@ Override `--psi-select-*` custom properties at any scope; interactive states der
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/Skeleton.md

@@ -0,0 +1,50 @@
+<!-- Generated by emit-docs.ts — do not edit. -->
+# Skeleton
+
+A loading placeholder. It is not a live region: it renders no `role` and no `aria-live`, and it is always `aria-hidden="true"`, so assistive tech skips it entirely. Put `aria-busy` on the region the skeleton stands for — that is what tells a screen reader the content is coming. Its width fills the container; size the container, not the skeleton. The pulse is an opacity animation that stops under `prefers-reduced-motion: reduce` (D86).
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `variant` | `"text" \| "block"` | text | no | `text` renders `lines` stacked bars; `block` one box. |
+| `lines` | `number` | 1 | no | Number of text lines; the last of several is shorter. Text only. |
+| `size` | `24 \| 32 \| 40 \| 48` | 40 | no | Height of a block, from the size scale. Block only. |
+| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+| `ref` | `Ref<HTMLDivElement>` | — | no | Forwarded ref to the underlying `<div>`. |
+
+## Keyboard & assistive tech
+
+| Keys | Behavior |
+|---|---|
+
+
+Not a live region: it renders no role and no aria-live, and it is always aria-hidden="true", so assistive tech skips it entirely. Put aria-busy="true" on the region the skeleton stands for (a table body, a card, a list) and remove it when the content arrives; that, not the skeleton, is what tells a screen reader the content is loading. Not focusable. The pulse is an opacity animation that stops under prefers-reduced-motion: reduce, because zeroing the duration of an infinite alternating animation flickers instead of stopping (D86).
+
+## Theming
+
+Override `--psi-skeleton-*` custom properties at any scope.
+
+## Variant guidance
+
+- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.
+- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.
+- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.
+- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.
+- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.
+- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.
+- **danger** — Destructive action. Delete, remove, disconnect.
+- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.
+- **success | warning** — Status communication (Tag only). Status badges, labels.
+
+## Rules
+
+- One accent per visual group; everything else neutral or ghost.
+- danger only for actions with real consequences.
+- Sizes are px numbers (24|32|40|48), never S/M/L.
+- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.
+- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
+- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
+- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
+- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/SkipLink.md

@@ -0,0 +1,40 @@
+<!-- Generated by emit-docs.ts — do not edit. -->
+# SkipLink
+
+A link to the page's main content, invisible until it takes keyboard focus and then fixed at the inline-start top corner on a surface, drawing the shared focus ring (D88). Render it first in the document. No script: native fragment navigation moves focus to a target that is focusable, so the next *Tab* continues from inside it. `AppShell`'s `main` is one (`tabIndex={-1}`); a bare `<main>` is not, so give it one. A modal `Dialog` makes the rest of the document inert, so the link never needs to beat one. A `ToastRegion` is on the native top layer, which paints above everything whatever its `z-index`: do not place one at `top-start` (its default is `bottom-end`) in an app with a skip link, or it covers the focused link.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `href` | `string` | — | yes | Fragment of the element to skip to, such as `"#main"`. The target must be focusable (`tabIndex={-1}` is enough), or focus does not move. |
+| `children` | `ReactNode` | — | yes | Visible text, such as "Skip to content". |
+| `ref` | `Ref<HTMLAnchorElement>` | — | no | Forwarded ref to the anchor. |
+| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+
+## Keyboard & assistive tech
+
+| Keys | Behavior |
+|---|---|
+| Tab | Takes focus and becomes visible at the inline-start top corner, drawing the shared focus ring. Put it first in the document so it is the first tab stop. |
+| Enter | Follows the fragment href: focus moves to the target, and the next Tab continues from inside it. |
+
+A native anchor, visually hidden until it is focused (:focus-visible) and with no script (D88). Fragment navigation moves focus only to a focusable target, so the element named by href must be focusable: tabIndex={-1} is enough, and AppShell's main has it. A modal Dialog makes the link inert, so it never needs to beat one. A ToastRegion is on the native top layer and paints over the focused link whatever its z-index: do not place one at top-start in an app with a skip link.
+
+## Theming
+
+Override `--psi-skip-link-*` custom properties at any scope.
+
+
+
+## Rules
+
+- One accent per visual group; everything else neutral or ghost.
+- danger only for actions with real consequences.
+- Sizes are px numbers (24|32|40|48), never S/M/L.
+- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.
+- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
+- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
+- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
+- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/Switch.md

@@ -33,5 +33,5 @@ Override `--psi-switch-*` custom properties at any scope.
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/Tab.md

@@ -36,5 +36,5 @@ This component has no `--psi-tab-*` tokens — its styling binds scale tokens on
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/TabList.md

@@ -37,5 +37,5 @@ This component has no `--psi-tab-list-*` tokens — its styling binds scale toke
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/TabPanel.md

@@ -35,5 +35,5 @@ This component has no `--psi-tab-panel-*` tokens — its styling binds scale tok
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/Table.md

@@ -34,5 +34,5 @@ Override `--psi-table-*` custom properties at any scope; interactive states deri
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/TableBody.md

@@ -1,7 +1,7 @@
 <!-- Generated by emit-docs.ts — do not edit. -->
 # TableBody
 
-`<tbody>` wrapper.
+`<tbody>` wrapper. Remaining attributes land on it (D85) — `aria-busy` while a page of rows loads, say.
 
 ## Props
 
@@ -9,6 +9,7 @@
 |---|---|---|---|---|
 | `children` | `ReactNode` | — | yes | The body TableRows. |
 | `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+| `ref` | `Ref<HTMLTableSectionElement>` | — | no | Forwarded ref to the `<tbody>`. |
 
 ## Theming
 
@@ -25,5 +26,5 @@ This component has no `--psi-table-body-*` tokens — its styling binds scale to
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/TableCaption.md

@@ -0,0 +1,39 @@
+<!-- Generated by emit-docs.ts — do not edit. -->
+# TableCaption
+
+`<caption>` — the table's name, above it, and an optional detail line (D85). It names the table for assistive tech, which an `aria-label` on the `Table` would also do, but a caption is visible. A token-paged list has no page numbers to land on, so after a page change the consumer moves focus here: give it `tabIndex={-1}`, put the range in `detail`, and call `focus()` on the ref. The ring is the shared one (D82), drawn inside the caption's box. Remaining attributes land on the element.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `children` | `ReactNode` | — | yes | The name line — what the table lists. Also the table's accessible name. |
+| `detail` | `ReactNode` | — | no | An optional second line: the range shown, say — "Rows 51–100 of more than 100,000". |
+| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+| `ref` | `Ref<HTMLTableCaptionElement>` | — | no | Forwarded ref to the `<caption>`, so focus can be moved to it. |
+
+## Keyboard & assistive tech
+
+| Keys | Behavior |
+|---|---|
+| Tab | Not a tab stop. With tabIndex={-1} the consumer moves focus to it after a page change, and the shared ring is drawn inside the caption. |
+
+Renders <caption>, which names the table for assistive tech and is visible, unlike an aria-label on Table. Put the range in `detail` ("Rows 51–100 of more than 100,000") so that moving focus to the caption after a token-paged page change reads the new range (D85). Remaining attributes land on the element.
+
+## Theming
+
+This component has no `--psi-table-caption-*` tokens — its styling binds scale tokens only, so there is nothing component-scoped to override. Theme changes reach it through the semantic tokens of its children and surroundings.
+
+
+
+## Rules
+
+- One accent per visual group; everything else neutral or ghost.
+- danger only for actions with real consequences.
+- Sizes are px numbers (24|32|40|48), never S/M/L.
+- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.
+- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
+- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
+- Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
+- Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/TableCell.md

@@ -1,15 +1,18 @@
 <!-- Generated by emit-docs.ts — do not edit. -->
 # TableCell
 
-`<td>`. `numeric` means right-aligned *and* tabular — a column that aligns but whose digits jitter between rows defeats the purpose.
+`<td>`, or `<th scope="row">` with `rowHeader`. `numeric` means right-aligned *and* tabular — a column that aligns but whose digits jitter between rows defeats the purpose. Remaining attributes land on the cell (D85).
 
 ## Props
 
 | Prop | Type | Default | Required | Description |
 |---|---|---|---|---|
 | `numeric` | `boolean` | — | no | Right-aligns and renders tabular figures (D62). |
+| `colSpan` | `number` | — | no | Columns the cell spans — an empty-state row spanning the table (D85). |
+| `rowHeader` | `boolean` | — | no | Renders `<th scope="row">` instead of `<td>`: the cell that names its row, an identifier say, so a screen reader reads it with every cell in the row (D85). Styled as a cell, at medium weight. |
 | `children` | `ReactNode` | — | no | Cell content. |
 | `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+| `ref` | `Ref<HTMLTableCellElement>` | — | no | Forwarded ref to the cell element. |
 
 ## Theming
 
@@ -26,5 +29,5 @@ This component has no `--psi-table-cell-*` tokens — its styling binds scale to
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/TableHead.md

@@ -9,6 +9,7 @@
 |---|---|---|---|---|
 | `children` | `ReactNode` | — | yes | The header TableRow. |
 | `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+| `ref` | `Ref<HTMLTableSectionElement>` | — | no | Forwarded ref to the `<thead>`. |
 
 ## Theming
 
@@ -25,5 +26,5 @@ This component has no `--psi-table-head-*` tokens — its styling binds scale to
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/TableHeaderCell.md

@@ -11,6 +11,7 @@
 | `numeric` | `boolean` | — | no | Right-aligns and renders tabular figures (D62). |
 | `children` | `ReactNode` | — | no | Header label. |
 | `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+| `ref` | `Ref<HTMLTableCellElement>` | — | no | Forwarded ref to the `<th>`. |
 
 ## Theming
 
@@ -27,5 +28,5 @@ This component has no `--psi-table-header-cell-*` tokens — its styling binds s
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/TableRow.md

@@ -11,6 +11,7 @@
 | `selectLabel` | `string` | — | no | Accessible name for this row's selection checkbox. |
 | `children` | `ReactNode` | — | yes | The row's cells. |
 | `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+| `ref` | `Ref<HTMLTableRowElement>` | — | no | Forwarded ref to the `<tr>`. |
 
 ## Theming
 
@@ -27,5 +28,5 @@ This component has no `--psi-table-row-*` tokens — its styling binds scale tok
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/Tabs.md

@@ -7,7 +7,7 @@ Tab set root (D67) — holds no selection state of its own, following D50, D53 a
 
 | Prop | Type | Default | Required | Description |
 |---|---|---|---|---|
-| `value` | `string` | — | yes | Controlled selected tab, matched against each `Tab`/`TabPanel` value. |
+| `value` | `string` | — | yes | Controlled selected tab, matched against each `Tab`/`TabPanel` value. A value that matches no tab selects nothing, and the first enabled tab holds the list's tab stop (D93); development builds warn. |
 | `onValueChange` | `(value: string) => void` | — | yes | Fires with the newly selected value; the consumer flips `value`. |
 | `orientation` | `"horizontal" \| "vertical"` | horizontal | no | Axis of the tab list, which also picks the arrow keys. |
 | `children` | `ReactNode` | — | yes | A `TabList` and one `TabPanel` per tab. |
@@ -18,7 +18,7 @@ Tab set root (D67) — holds no selection state of its own, following D50, D53 a
 
 | Keys | Behavior |
 |---|---|
-| Tab | Enters the tab list at its selected tab (one stop for the whole list), then moves on to the active panel. |
+| Tab | Enters the tab list at its selected tab (one stop for the whole list), then moves on to the active panel. When value matches no tab, the first enabled tab holds the stop (the first tab if all are disabled) and none is selected; a selected disabled tab keeps the stop (D93). |
 
 Controlled-only (D67): value and onValueChange are required and Tabs never selects itself. Tab and TabPanel pair by string value, not index, so their source order need not match. Every panel renders and unselected ones carry `hidden`, so aria-controls always resolves and panel DOM state survives a switch.
 
@@ -37,5 +37,5 @@ Override `--psi-tabs-*` custom properties at any scope; interactive states deriv
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/Tag.md

@@ -47,5 +47,5 @@ Override `--psi-tag-*` custom properties at any scope.
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.

package/docs/Toast.md

@@ -1,7 +1,7 @@
 <!-- Generated by emit-docs.ts — do not edit. -->
 # Toast
 
-A single transient notification card (D64). Controlled and presentational: it holds no state, runs no timer, and never removes itself — `onDismiss` reports and the owner disposes, exactly as Dialog (D50) and Menu (D53) do. Toast does not carry its own `role`/`aria-live`. Politeness belongs to the two persistent wrappers inside ToastRegion, because a live region must pre-exist the content it announces; a role on the toast itself would reintroduce the mount-with-content problem one level down. Composed by hand with ToastRegion for full control, or driven by ToastProvider's queue.
+A single transient notification card (D64). Controlled and presentational: it holds no state, runs no timer, and never removes itself — `onDismiss` reports and the owner disposes, exactly as Dialog (D50) and Menu (D53) do. Toast does not carry its own `role`/`aria-live`. Politeness belongs to the two persistent wrappers inside ToastRegion, because a live region must pre-exist the content it announces; a role on the toast itself would reintroduce the mount-with-content problem one level down. `politeness` (D83) only tells the region which wrapper to use. Composed by hand with ToastRegion for full control, or driven by ToastProvider's queue.
 
 ## Props
 
@@ -11,6 +11,8 @@ A single transient notification card (D64). Controlled and presentational: it ho
 | `children` | `ReactNode` | — | yes | The message. |
 | `action` | `ReactNode` | — | no | Trailing affordance — a ghost Button (Undo, Retry, View). |
 | `onDismiss` | `(() => void)` | — | no | When provided, renders the dismiss button and calls this. Toast does not remove itself; the owner disposes. |
+| `politeness` | `"polite" \| "assertive"` | — | no | Which live wrapper ToastRegion routes this toast into (D83). Unset, the variant decides: neutral and success are polite, warning and danger assertive. Set it when the kind of event, not its tone, decides — the outcome of the user's own action may interrupt even when it succeeded. |
+| `statusLabel` | `string \| null` | — | no | The visually hidden status word (D83). A string replaces the default ("Success:", "Warning:", "Error:") — pass the translated word; `null` drops it. Unset keeps the default, and `neutral` has none. |
 | `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
 | `ref` | `Ref<HTMLDivElement>` | — | no | Forwarded ref to the underlying `<div>`. |
 
@@ -21,7 +23,7 @@ A single transient notification card (D64). Controlled and presentational: it ho
 | Tab | Reaches the action and the dismiss button in DOM order. Esc is not a dismissal — a toast is not modal and traps nothing. |
 | Enter / Space | Activates the focused action or dismiss button. |
 
-Presentational and controlled (D64): onDismiss reports and the owner disposes; Toast never removes itself. It carries no role/aria-live of its own — politeness belongs to ToastRegion's two persistent wrappers. The variant's meaning is announced by a visually hidden status word ("Success:", "Warning:", "Error:"), never by colour and icon shape alone; the icon is aria-hidden. neutral has no status and gets no prefix. The dismiss button requires no props — it is labelled "Dismiss notification".
+Presentational and controlled (D64): onDismiss reports and the owner disposes; Toast never removes itself. It carries no role/aria-live of its own — politeness belongs to ToastRegion's two persistent wrappers. The variant's meaning is announced by a visually hidden status word ("Success:", "Warning:", "Error:"), never by colour and icon shape alone; the icon is aria-hidden. neutral has no status and gets no prefix. statusLabel replaces that word with a translated one, or drops it with null (D83). politeness tells ToastRegion which wrapper speaks the toast; unset, the variant decides. The dismiss button requires no props — it is labelled "Dismiss notification".
 
 ## Theming
 
@@ -48,5 +50,5 @@ Override `--psi-toast-*` custom properties at any scope.
 - Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
 - --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).
 - Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.
-- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field).
+- Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination ("Rows per page" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as="form" align="start" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).
 - Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group.