@pienter/ui 0.2.0

package/CONVENTIONS.md

@@ -0,0 +1,1499 @@
+# `@pienter/ui` Authoring Conventions
+
+This document codifies how to author components and utilities in `packages/ui/`. Read it before starting any component task. If a needed convention is missing, escalate to the maintainer rather than improvise.
+
+The architectural decisions behind these conventions live in the OpenSpec change `component-library-shadcn-baseline` (see `openspec/changes/component-library-shadcn-baseline/design.md`). This file is the working reference for contributors; the design doc is the rationale.
+
+---
+
+## BEM block & element naming
+
+Component CSS uses **BEM-lite**:
+
+- **Block**: `pui-` prefix + kebab-case component name. One block per component, declared in the component's CSS file.
+- **Element**: `<block>__<element>` — child parts within the block (separator `__`).
+- **Modifiers**: do **not** use `--` BEM modifiers. Variants, sizes, and runtime states are expressed via `data-*` attributes on the block (see next section). Reasons: keeps the class list short, lets us toggle states from JS without touching `class`, and matches shadcn's pattern.
+
+**Worked example — Button**:
+
+```css
+@layer components {
+    .pui-btn {
+        /* block */
+    }
+    .pui-btn__spinner {
+        /* element */
+    }
+    .pui-btn[data-variant='primary'] {
+        /* variant via data-attribute */
+    }
+    .pui-btn[data-state='loading'] {
+        /* runtime state via data-attribute */
+    }
+}
+```
+
+---
+
+## Component module paths
+
+Implementation modules live under a singular role category and retain a
+colocated module folder:
+
+```text
+components/<category>/<module>/
+```
+
+The categories are `action`, `display`, `feedback`, `form`, `layout`,
+`navigation`, and `overlay`. Cross-module implementation imports use these
+categorized paths. Package consumers use the explicit flat exports instead,
+for example `@pienter/ui/components/Button.vue` or
+`@pienter/ui/components/Button.astro`. Category paths, colocated CSS, and
+private helpers are not public package entrypoints.
+
+## Multi-component-per-directory exception
+
+Components may co-locate in a single directory when they form a **tightly-coupled visual sibling family** sharing one CSS file. The directory name reflects the shared visual concept, not a single component name.
+
+Current consumers:
+
+- `components/display/avatar/` — `Avatar` + `AvatarStack` (the stack is a visual layout for grouping avatars; stack styling lives in `avatar.css` alongside the avatar visual)
+- `components/form/select/` — `Select` + `Segmented` (the segmented control is a tab-like single-select visual; shares form-primitive scaffolding with Select; will be retrofit in Phase 4)
+- `components/action/button/` — `Button` + `IconButton` (the icon-only control is a square button. `button.css` shares the base/variant/size/state/focus rules across both via a `.pui-btn, .pui-icon-btn` selector group; a `.pui-btn`-only block holds the label, link variant, block layout, and loading fade that must not reach the icon button; a `.pui-icon-btn` rule adds the square box)
+
+Rules:
+
+- The shared CSS file MUST be named after the shared visual concept (`avatar.css`, `select.css`)
+- All co-located components MUST be in the same Astro tier
+- Each component file has a separate flat public import (`@pienter/ui/components/Avatar.vue` and `@pienter/ui/components/AvatarStack.vue`)
+- Each component still has its own entry in the directory's `AUDIT.md`
+- New components SHOULD live in their own directory unless they meet the tightly-coupled-visual-sibling-family bar (i.e., this exception isn't a default — it's earned)
+
+This exception is the directory-shape analogue to the form-primitive shared-scaffold exception (see "Form-primitive wrapper" archetype): both accept a single shared resource (CSS file or BEM block) across multiple component files because duplicating it would invite drift.
+
+---
+
+## CSS layer & token rules
+
+All component CSS rules SHALL be wrapped in `@layer components { … }` so they
+participate in the documented layer cascade (`reset, base, layout, components, utilities`).
+
+All values referencing color, spacing, typography, radii, strokes, and shadows
+SHALL use design tokens via `var(--…)` — no hardcoded hex, rgb, rem, or px
+literals.
+
+**Permitted literal escape hatches** (cases where no scale token applies):
+
+- decorative widths on small visual elements (e.g., spinner ring border, accent
+  underlines) where the value is intrinsic to the element rather than scaled
+- transition durations and timing functions
+
+If a needed value isn't covered by a token _and_ isn't on this escape-hatch
+list, add a token to `0-settings/` rather than hardcoding.
+
+---
+
+## `data-*` attribute conventions
+
+Variants and runtime states live on `data-*` attributes on the block element, never on class names.
+
+| Attribute          | Purpose                                                                                                                                                    | Example values                                                                        |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `data-variant`     | Visual variant (mutually exclusive within a component)                                                                                                     | `primary`, `secondary`, `ghost`, `danger`, `link`                                     |
+| `data-size`        | Sizing scale (mutually exclusive)                                                                                                                          | `sm`, `md` (Button/IconButton); `sm`/`md`/`lg` (Icon); other components add their own |
+| `data-animation`   | Continuous decorative animation on the block                                                                                                               | `spin` (Icon)                                                                         |
+| `data-tone`        | Semantic tone for non-variant components (Alert, Badge, Toast)                                                                                             | `brand`, `success`, `warning`, `danger`                                               |
+| `data-block`       | Block-level layout flag (boolean)                                                                                                                          | `'true'` or absent                                                                    |
+| `data-state`       | Runtime state controlled by code or controller                                                                                                             | `loading`, `open`, `closed`, `checked`, `indeterminate`                               |
+| `data-status`      | Derived semantic status for form primitives (validation outcome)                                                                                           | `error`, `success`                                                                    |
+| `data-layout`      | Form-primitive scaffold layout selector — lives on `.pui-field`; flips between stacked label-above (default) and compact inline control-left + label-right | `stacked` (default; attribute may be omitted), `inline`                               |
+| `data-orientation` | Layout direction for grouped controls (RadioGroup items, future SegmentedControl, etc.) — lives on the group container                                     | `vertical` (default for RadioGroup), `horizontal`                                     |
+
+The example values listed for each attribute are non-exhaustive — components add states as needed (e.g. `expanded`, `selected`, `active` for upcoming Disclosure, Tabs, Sidebar). New values follow the same kebab-case rule and live on the same attribute family.
+
+**`data-state` vs `data-status`** — both attributes describe how a component
+"is right now," but they have different sources:
+
+- `data-state` is **runtime UI state** — owned by code or a controller, driven
+  by interaction (`loading` while a request is in flight, `open`/`closed` for a
+  disclosure, `checked`/`indeterminate` for a toggle). It usually changes in
+  response to user input or async work.
+- `data-status` is **derived semantic status** — owned by validation /
+  form-orchestration logic, computed from props. `error` means "this field
+  failed validation" (typically derived from a non-empty `errors` array);
+  `success` means "this field passed and we want to surface that" (an explicit
+  prop, not auto-derived).
+
+A single component MAY carry both: a TextInput can be `data-state="loading"`
+(busy) AND `data-status="error"` (validation failed) at once.
+
+### Boolean attributes — only-when-truthy
+
+For any boolean prop emitted as a `data-*` or `aria-*` attribute, render the
+attribute _only when the prop is truthy_, never with a literal `'false'`:
+
+```vue
+:data-block="block ? 'true' : undefined" :aria-busy="loading ? 'true' :
+undefined"
+```
+
+CSS targets the truthy presence (`[data-block='true']`, `[aria-busy='true']`).
+Avoids `data-block="false"` polluting the DOM and matching unintended selectors.
+
+**Conventions**:
+
+- `data-state` is reserved for _runtime_ state (loading, open/closed, checked). Static visual choice belongs on `data-variant` or `data-size`.
+- Values are kebab-case strings; never booleans or numbers.
+
+**Worked example — Button in loading state**:
+
+```html
+<button
+    class="pui-btn"
+    data-variant="primary"
+    data-size="md"
+    data-state="loading"
+    aria-busy="true"
+    disabled
+>
+    <span class="pui-btn__spinner" aria-hidden="true"></span>
+    Saving…
+</button>
+```
+
+---
+
+## Component archetypes
+
+Each component fits one of a small set of authoring archetypes. Archetypes are locked as they are encountered in Phase 1.
+
+### Native-element-wrapper
+
+A component that wraps a single native HTML element (`<button>`, `<input>`, `<a>`, `<select>`, etc.) with class + `data-*` + ARIA wiring. The wrapper adds variant/size/state mapping but does not synthesize behavior — keyboard and form semantics come from the underlying native element.
+
+**Authoring checklist for native-element wrappers**:
+
+- [ ] Renders the underlying native element directly (`<button>`, `<input>`,
+      `<select>`, `<a>`, etc.); no `<div role="…">` simulations.
+- [ ] Variant/size/visual props map to `data-*` attributes on the element.
+- [ ] `disabled` flows to the native attribute when supported. For elements
+      that don't support native `disabled` (`<a>`), use
+      `aria-disabled="true"` AND `tabindex="-1"` AND `pointer-events: none`
+      in CSS so the element is fully inert.
+- [ ] If polymorphic via a single prop (e.g., Button's `href` toggles
+      `<button>`/`<a>`), conditionally drop attributes that don't apply
+      (`type`, `disabled`) and use ARIA equivalents on the alternate branch.
+- [ ] Loading state: emit `disabled` (or `aria-disabled` + `tabindex="-1"`
+      for `<a>`) AND `aria-busy="true"` AND `data-state="loading"` AND a
+      visually-rendered spinner element with `aria-hidden="true"`.
+- [ ] Forwards arbitrary attributes via `...rest` (Astro) / inheritAttrs
+      (Vue) so consumers can attach `id`, `name`, event listeners, ARIA
+      labels.
+
+**Worked example — Button**: see `packages/ui/components/action/button/`. Polymorphic `<button>`/`<a>` via `href`, variants/size/block/state on `data-*`, loading state via `aria-busy` + `data-state="loading"` + `<span class="pui-btn__spinner">` element.
+
+### Form-primitive wrapper
+
+A component that wraps a single native form control (`<input>`, `<textarea>`,
+`<select>`, grouped `<input type="radio">`, etc.) plus the surrounding label,
+hint, and error-list — i.e. the visible label, the optional helper text under
+the field, and the validation messages that appear after submit. Form
+primitives extend the native-element-wrapper archetype with **shared
+label / hint / error scaffolding** and the ARIA wiring that ties them to the
+control.
+
+**Shared scaffold — explicit BEM exception**: form primitives wrap their
+control in a `pui-field` element that hosts the label, hint, and error list. The
+control itself uses a per-element block name (`pui-input`, `pui-textarea`,
+`pui-select`, `pui-checkbox`, …). This is an **explicit exception** to the
+"block matches component name" rule: the scaffold styles (label typography,
+hint colour, status-driven recolour) are reused by every form primitive, so
+duplicating them under per-component blocks (`v-text-input__label`,
+`pui-textarea__label`, `pui-select__label`, …) would produce 10+ identical
+declarations and invite drift. The trade-off — that the wrapper class doesn't
+match the component file name — is accepted in exchange for one source of
+truth for field chrome.
+
+`<fieldset>` is the wrapper for grouped controls (RadioGroup is the
+v1 reference; future Checkbox-group variants would follow the same
+shape) where a single legend describes multiple inputs; everything
+else (TextInput, Textarea, Select, Switch, Checkbox-singular, NumberField,
+DateInput) uses `<div class="pui-field">` with a single `<label>`. See the
+RadioGroup audit (`components/form/radio-group/AUDIT.md`) for the worked example — `<fieldset
+class="pui-field" role="radiogroup">` with `<legend class="pui-field__label">`
+above the rendered options, hint and errors below.
+
+**Authoring checklist for form-primitive wrappers**:
+
+- [ ] Wrapper renders `<div class="pui-field">` (or `<fieldset class="pui-field">`
+      with `<legend class="pui-field__label">` for grouped controls like
+      RadioGroup).
+- [ ] Label uses `<label class="pui-field__label" for={inputId}>` (or `<legend>`
+      for a fieldset wrapper) with `for` matching the control's `id`.
+- [ ] If `id` is not consumer-provided, generate via
+      `generateId('<prefix>')` from `@pienter/ui/utils/a11y/id`, where
+      `<prefix>` is the bare native-element name (`'input'`, `'textarea'`,
+      `'select'`, `'checkbox'`); for grouped controls use the role
+      (`'radiogroup'`). Derive `${inputId}-hint` and `${inputId}-errors`
+      from the same base.
+- [ ] Hint renders as `<p class="pui-field__hint" id={hintId}>` only when the
+      `hint` prop is set. Omit the element entirely when absent.
+- [ ] Errors render as `<ul class="pui-field__hint" id={errorsId}
+role="alert">` with one `<li>` per error message, only when errors are
+      present. Omit the element entirely when the errors array is empty.
+    - `role="alert"` (which carries implicit `aria-live="assertive"` and
+      `aria-atomic="true"`) is appropriate for submit-time validation messages
+      that arrive as a batch. For live/as-you-type validation — out of scope
+      for v1 — use `role="status"` or `aria-live="polite"` instead, to avoid
+      interrupting the user mid-keystroke. When live validation lands, this
+      rule is reopened.
+- [ ] Control element receives `aria-invalid="true"` (string, per the
+      boolean-attr-only-when-truthy rule) when errors are present; omit the
+      attribute when not.
+- [ ] Control element receives `aria-describedby` listing hint and/or errors
+      IDs (space-separated when both); omit the attribute entirely when
+      neither exists. Order: hint first, errors second. Hint-first matches a
+      "context, then problem" reading flow for screen-reader users; do not
+      reorder per-component.
+- [ ] Visual status lives on `data-status` on the wrapper (`pui-field`), not on
+      `data-state`. CSS targets `.pui-field[data-status='error'] .pui-input`
+      etc. so the same selector pattern works across every form primitive.
+      `data-status` is derived: if a `status` prop is set, use it; otherwise
+      derive `error` from a non-empty errors array.
+- [ ] Forwards remaining attributes onto the control element (Astro: `...rest`,
+      Vue: `inheritAttrs` defaults), so consumers can attach `name`,
+      `autocomplete`, `inputmode`, event listeners, ARIA labels, etc.
+
+    **Declared props are stripped from `$attrs`** — when a Vue component
+    declares a prop (e.g., `disabled`, `name`, `value`), Vue removes it from
+    `$attrs` before the `v-bind="$attrs"` spread. Re-bind explicitly on the
+    control element (`:disabled="disabled"`, `:name="name"`) to flow the
+    typed prop through. Order matters: bind `$attrs` first, then explicit
+    props — explicit bindings win, which is what we want.
+
+- [ ] Compact form primitives (Switch, Checkbox, individual Radio items) use
+      `data-layout="inline"` on the `pui-field` wrapper to flip the layout to
+      control-left + label-right. Everything else (label association via
+      `for`/`id`, hint/error rendering, ARIA wiring, `aria-describedby`
+      joining, status-driven recolour) stays unchanged. The DOM source order
+      under `data-layout="inline"` is **control first, label second** so the
+      `<label for>` association is read in left-to-right order, and the
+      `pui-field__hint` elements remain after the label so a single CSS rule
+      (`grid-column: 1 / -1`) drops them onto a row below the control + label.
+
+**Worked example — TextInput**: see `packages/ui/components/form/text-input/`. The
+wrapper is `<div class="pui-field" data-status>`, the label is
+`<label class="pui-field__label" for>`, the control is `<input class="pui-input">`,
+hint and errors are `<p|ul class="pui-field__hint" id>`. `aria-invalid="true"`
+emitted only on error; `aria-describedby` joins hint and error IDs with a
+space when both exist.
+
+**Worked example — Switch (inline layout)**: see
+`packages/ui/components/form/switch/`. The wrapper is
+`<div class="pui-field" data-layout="inline" data-status>`, the control is
+`<input class="pui-switch" type="checkbox" role="switch">` rendered FIRST in
+DOM order, the label is `<label class="pui-field__label" for>` rendered
+second, and hint/errors render below the row spanning both columns. ARIA
+wiring (`aria-checked`, `aria-invalid`, `aria-describedby`) follows the
+same shape as TextInput.
+
+**Worked example — RadioGroup (grouped controls)**: see
+`packages/ui/components/form/radio-group/`. The wrapper is
+`<fieldset class="pui-field" role="radiogroup" data-status>`, the label is
+`<legend class="pui-field__label">`, the inner control region is a
+`<div class="pui-radio-group" data-orientation>` containing one
+`<label class="pui-radio-group__item">` per option (each label wraps its own
+native `<input type="radio" class="pui-radio">`), and hint/errors render
+inside the fieldset around the items. The outer field layout is stacked
+(legend above, items below) — `data-layout="inline"` does NOT apply at
+this level; per-item inline layout lives on `.pui-radio-group__item` via
+`display: inline-flex`. Per-radio uses the **label-wrapping pattern**
+(label wraps input) rather than `<label for>` association — the option's
+short string label sits directly inside the wrapping label element. ARIA:
+`aria-invalid` and `aria-describedby` land on the fieldset (group-level);
+each input carries always-emit `aria-checked="true|false"`.
+
+**pui-field scaffold CSS — co-located with TextInput for now**: the shared
+`.pui-field`, `.pui-field__label`, `.pui-field__hint`, and
+`.pui-field[data-layout='inline']` rules live in
+`packages/ui/components/form/text-input/text-input.css` because TextInput was
+the first form-primitive consumer. Per-control element rules
+(`.pui-input`, `.pui-switch`, etc.) live in their own component CSS. **When
+the fifth form-primitive ships** (Checkbox, RadioGroup, Select, Textarea,
+NumberField, DateInput will push that count over), extract the
+`pui-field*` rules to `packages/ui/styles/4-components/form-field.css` so
+the scaffold isn't tied to one component's filename. The `data-layout`
+documentation in this file points consumers at the scaffold regardless
+of where the file lives.
+
+### Pure-markup with slots
+
+Locked during Phase 1 alongside Card (2026-05-03). A component that renders
+styled markup with **no behavior, no controller, no native form semantics**.
+Variants drive visual style via `data-variant` / `data-tone`; content flows
+in through slots (default and/or named). The component is essentially a
+named CSS chunk wrapped in a framework primitive so consumers don't have to
+remember the wrapper class.
+
+**Authoring checklist for pure-markup components**:
+
+- [ ] Renders a single block element (or a minimal nested structure when the
+      component has distinct semantic regions — e.g. an Empty illustration
+      slot above body content).
+- [ ] Default slot for the primary content area. Named slots only when the
+      component has 2+ ordered regions whose layout the component owns —
+      see "Slot vs prop conventions" below.
+- [ ] Variants and tones expressed via `data-variant` or `data-tone` per the
+      locked rules; no per-variant class names.
+- [ ] No JS — no controllers, no event listeners, no reactive state. If a
+      pure-markup component grows behavior (loading, dismiss, expand), it
+      graduates to one of the other archetypes and the audit entry is updated.
+- [ ] No ARIA roles **unless the component carries semantic meaning the
+      markup doesn't already convey**. Card has no role (it's a styled
+      `<div>`); Alert has `role="alert"` because its purpose is to surface
+      dynamic, attention-worthy messages. Don't add roles speculatively.
+- [ ] If the CSS publishes element classes (`<block>__<element>`) for
+      consumer use **inside** the slot content (Card's `pui-card__title`,
+      `pui-card__eyebrow`, etc.), document those classes in the audit entry
+      as **public API**. Renaming or removing them is a breaking change.
+- [ ] Vue uses the default `inheritAttrs: true` (the wrapper IS the only
+      element) so consumer-supplied `id`, `class`, `aria-*`, and event
+      listeners land on the wrapper. Astro spreads `...rest` on the wrapper
+      to the same effect.
+
+**Worked example — Card**: see `packages/ui/components/layout/card/`. Renders a
+single `<div class="pui-card" data-variant>` with a default slot. Variants
+on `data-variant` (`bordered`, `brand`, `muted`); no ARIA role; no
+controller. Public child classes — `pui-card`, `pui-card__eyebrow`,
+`pui-card__title`, `pui-card__body`, `pui-card__meta`, `pui-card__footer` — are
+applied by consumers to their own markup inside the slot.
+
+### Hybrid API (data + slots)
+
+Locked during Phase 1 alongside Sidebar (2026-05-03). A component that
+mixes a **data-driven, a11y-critical region** (e.g. Sidebar's navigation
+menu) with **decorative or contextual regions** driven by named slots
+(e.g. `#brand`, `#footer`). The a11y wiring — active-state derivation,
+ARIA attributes, keyboard navigation, roving tabindex — lives once
+inside the component and is not opt-out-able by consumers.
+
+This is the canonical archetype for "data-driven menu surfaces" — any
+future component that has a repetitive list of links/items where each
+item must carry consistent ARIA + keyboard behavior follows this
+pattern. Sidebar is the v1 reference; future Menubar / NavigationMenu
+(deferred) would adopt the same shape.
+
+**Authoring checklist for hybrid-API components**:
+
+- [ ] One **driver-data prop** with a typed shape. When entries can vary
+      structurally (link vs group vs section heading), the type is a
+      **discriminated union** keyed on a `type` field. Place the union
+      in a colocated `types.ts` (`components/<category>/<module>/types.ts`) and
+      re-export it from the component file so consumers import one
+      symbol.
+- [ ] **Named slots for non-driver regions** only — `#brand`, `#footer`,
+      `#actions`, etc. Each slot is a documented region with a fixed
+      DOM placement and appears in the component's audit entry. The
+      driver-data region's items can NOT be replaced via slot — doing
+      so would break the centralized a11y wiring.
+- [ ] A11y wiring is owned by the component and consistent across every
+      data-driven entry: active-state derivation, `aria-current`,
+      `aria-expanded`, roving tabindex, keyboard arrow navigation,
+      `role` choice. Consumers cannot opt out of any of this — they
+      provide data, the component renders the right ARIA.
+- [ ] Active-state is **derived**, not pre-marked on items. The
+      component takes an active-key prop (e.g. Sidebar's `:active-href`,
+      Tabs' `:model-value`) and applies the active styling/ARIA
+      internally. Consumers do not pass `active: true` on individual
+      items.
+- [ ] Recursion (when items can nest, e.g. Sidebar groups) is handled
+      inside the component — the consumer always passes a single flat
+      `items` array, even when items are deep trees. In Vue this is
+      typically an internal recursive `<SidebarItemRender>` component
+      that is **not exported** (private to the parent file). In Astro
+      it is a recursive `.astro` component (see worked Sidebar example
+      below) — also private.
+- [ ] State that the consumer might want to control (collapsed/expanded
+      shell, drawer open/closed, expanded group set) flows through
+      props + `v-model` / `update:*` events; runtime state is owned by
+      a controller (per the Stateful-component archetype).
+
+**Worked example — Sidebar**: see `packages/ui/components/navigation/sidebar/`.
+Hybrid: `:items` drives the menu (with the `link | group | section`
+discriminated union from `sidebar/types.ts`); `#brand` and `#footer`
+slots cover decorative regions. Active-state derived from
+`:active-href` via the hierarchical-match algorithm (below). The
+recursive item rendering lives in a private `SidebarItemRender.vue`
+(Vue) and `SidebarItemRender.astro` (Astro). Runtime state — desktop
+collapse, mobile drawer, per-group expand — owned by `mountSidebar`
+in `controllers/sidebar.ts`.
+
+### Form orchestration
+
+Locked during Phase 2 alongside Form (2026-05-03). Form is the **orchestrator**: it does not render a control of its own. Its job is to wire submit handling, run client-side validators, render error chrome (top-level summary + per-field), apply success state, and coordinate the submit busy lifecycle. The form-primitive wrappers (TextInput, Textarea, Switch, Checkbox, RadioGroup, Select, NumberField, DateInput) are the **fields**; Form orchestrates them.
+
+**Layered split** — three layers, locked per design D13:
+
+1. **Shared primitives** (used by both Vue and Astro):
+    - `utils/validation/rules.ts` — pure validators (`isRequired`, `isEmail`, `minLength`, …).
+    - `utils/validation/form.ts:validateFormData(formData, validators)` — runs validators against `FormData`, returns `Record<string, string[]>`. Pure, framework-agnostic.
+    - `utils/validation/form.ts:normalizeFieldErrors(map)` — normalizes the `string | string[]` per-field shape from `FormSubmitResponse` to `string[]`.
+    - `utils/a11y/focus.ts:focusFirstInvalid(formEl)` — DOM-imperative focus helper.
+    - `utils/a11y/live-region.ts:announce(text, priority)` — DOM-imperative announcement.
+2. **Astro form controller** — `controllers/form.ts:mountForm(el, config) → teardown`. Full imperative orchestration: intercept submit, run validators, render per-field + summary errors, set `aria-busy`, await `onSubmit`, map response to UI, focus first invalid + announce. Astro's only orchestration path.
+3. **Vue Form orchestration** — lives **inside `Form.vue`** using Vue reactive idioms (refs, watch effects, computed). Calls the shared primitives directly. Does **NOT** wrap `mountForm` — wrapping an imperative DOM controller from Vue fights Vue's data flow (controller mutates the DOM, Vue patches it back, race conditions ensue).
+
+**Why two implementations**: forcing a single shared controller means either (a) Vue wraps imperative DOM (loses reactive benefits), or (b) primitives become so abstract they're not really doing the work. Layered split keeps each implementation idiomatic while sharing the expensive parts (validators, focus management, announcement) and the response contract.
+
+**Consumer responsibility — Vue vs Astro**:
+
+| Concern                     | Vue (`Form.vue`)                                                                                | Astro (`mountForm`)                                                                               |
+| --------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| Per-field error display     | Consumer wires `:errors` on each form-primitive child from `props.fieldErrors[name]`            | Controller writes per-field errors into the field's `pui-field__hint` element automatically       |
+| `aria-busy` during submit   | Consumer flips `:busy` prop on `<Form>` after async submit completes                            | Controller sets/removes `aria-busy` automatically                                                 |
+| Status message              | Consumer sets `:status-message` prop on `<Form>`                                                | Controller renders `statusMessage` from response automatically                                    |
+| Server `errors` (top-level) | Consumer sets `:errors` prop on `<Form>`                                                        | Controller renders `response.errors` automatically                                                |
+| Throw vs `{ ok: false }`    | Consumer's submit handler runs in parent; throwing is the consumer's exception-handling concern | Controller catches `onSubmit` throws and translates to `{ ok: false, errors: ['Submit failed'] }` |
+
+**Error display rules**:
+
+- Per-field errors land in the form-primitive's `pui-field__hint role="alert"` element, set `aria-invalid="true"` on the control, set `data-status="error"` on the wrapper. Vue: consumer wires `:errors` on each form-primitive child (typical Vue data flow). Astro: `mountForm` mutates the `pui-field` wrapper imperatively, marking the injected error list with `data-pui-form-errors="true"` so a future re-run can clear it without touching consumer-supplied static error markup.
+- Top-level errors (`response.errors[]` or consumer-supplied `:errors` prop) land in `.pui-form__error-summary` at the top of the form, with `role="alert"` and `aria-live="assertive"`.
+- Success: `statusMessage` renders inside `.pui-form__status` with `aria-live="polite"`, and is also announced via the global ARIA live region by the shared `announce()` primitive.
+
+**Submit lifecycle**:
+
+1. `submit` event → `event.preventDefault()`. Read `FormData`.
+2. Run client-side validators. If any fail: render field errors, set `aria-invalid` on each invalid control, focus first invalid, announce error count assertively. Do NOT call `onSubmit`. (Vue emits `validation-error` for telemetry.)
+3. If validation passes: clear errors, set `aria-busy="true"` on form, disable submit button, call `await onSubmit(data)` (Vue: emit `submit`; Astro: await `config.onSubmit`).
+4. After `onSubmit` returns: clear `aria-busy`, re-enable submit. Map response — `ok: false` → render server `fieldErrors` + top-level `errors`, focus first invalid, announce; `ok: true` → render `statusMessage`, announce politely.
+
+**Disable propagation**: when Form's `busy` is `true`, child form-primitives do NOT auto-disable. The Form-level busy state controls the submit button only. Disabling other fields/buttons inside the form (e.g. a "Cancel" button) is the consumer's call — a Form-wide busy state shouldn't block dismiss affordances.
+
+**Astro consumer pattern (locked)**: `Form.astro` renders chrome only. The consumer mounts `mountForm` from a `<script>` block colocated with the form markup. This is intentional: `validators` (functions) and `onSubmit` (async function) cannot be passed as Astro props. The consumer-writes-the-mount-script pattern is verbose but explicit, and matches how real product surfaces will wire up server-driven validation + redirect handling.
+
+**Worked example — Form**: see `packages/ui/components/form/form/` and `packages/ui/utils/controllers/form.ts`. Vue uses reactive refs + watch effects; Astro uses `mountForm` from a consumer `<script>` block. Both consume the placeholder `FormSubmitResponse` shape and call the shared `focusFirstInvalid`, `announce`, and `validateFormData` primitives.
+
+### Active-href hierarchical-match algorithm
+
+Locked during Phase 1 alongside Sidebar (2026-05-03). The canonical
+algorithm for deriving "is this nav item active?" from a current URL
+path (`activeHref`) and an item's target path (`itemHref`).
+
+```
+isActive(activeHref, itemHref):
+  if activeHref is empty/null → false
+  if itemHref === '/' → return activeHref === '/'      // root special-case
+  if activeHref === itemHref → true                    // exact match
+  if activeHref starts with (itemHref + '/') → true    // hierarchical
+  otherwise → false
+```
+
+**Worked examples**:
+
+| activeHref           | itemHref         | match? | rationale                                  |
+| -------------------- | ---------------- | ------ | ------------------------------------------ |
+| `/admin/members`     | `/admin/members` | yes    | exact                                      |
+| `/admin/members/123` | `/admin/members` | yes    | hierarchical (`/admin/members/` prefix)    |
+| `/admin/members-old` | `/admin/members` | no     | path-boundary check rejects substring-only |
+| `/admin/members`     | `/`              | no     | root special-case                          |
+| `/`                  | `/`              | yes    | root exact                                 |
+
+**Group active-state**: a group item is active when _any_ of its
+descendant items (recursively) is active. Sidebar uses this to expand
+the matching group on mount and to highlight the group header.
+
+**Edge cases — out of scope for v1**, documented for future:
+
+- Trailing slashes are NOT normalized (`/admin/members/` vs
+  `/admin/members` are treated as different). Consumers that may emit
+  trailing slashes should normalize before passing to `:active-href`.
+- Query strings and hash fragments are NOT stripped. If `activeHref =
+'/admin/members?filter=active'`, no item href without that query
+  matches. Strip in the consumer for now; revisit if real surfaces
+  start to need server-driven querystring-aware activation.
+- Case sensitivity follows JS string comparison (case-sensitive).
+
+This algorithm lives in the Sidebar component (not in `utils/`) for
+v1 because it has no other consumer; promote to a shared util when
+Breadcrumb / Tabs / Pagination / DropdownMenu need the same matching
+(Phase 3+).
+
+---
+
+## Slot vs prop conventions
+
+Locked during Phase 1 alongside Card (2026-05-03). Rules apply across every
+component, not only the pure-markup tier.
+
+### When to use a default slot
+
+Use a single default slot for the primary content area when the slot's
+content is "whatever the consumer wants" — rich markup, other components,
+arbitrary structure. Examples: Card body, Modal body, Alert content,
+AlertDialog body, Sheet body, Sidebar item content via `link.label` markup
+(deferred to Sidebar audit).
+
+### When to use named slots
+
+Use named slots when the component has **2+ distinct semantic regions** AND
+the component itself owns the **layout and ordering** of those regions —
+i.e. the consumer can't simply concatenate them inside a default slot
+because the component places each in a fixed DOM position. Examples:
+
+- Modal's `#footer` (placed below the body, inside the dialog content,
+  styled as the action bar)
+- Nav's `#actions` (placed at the trailing edge of the navbar)
+- Sidebar's `#brand` and `#footer` (header / footer regions of the layout
+  shell, deferred to Sidebar)
+- AlertDialog's actions slot (deferred to Phase 4)
+
+Each named slot is a **documented region with its own DOM placement** and
+appears in the component's audit entry alongside its purpose.
+
+### When to use props for content
+
+Use a prop when the content is a **single short string with no rich markup
+in v1**. Examples: TextInput's `label`, `hint`, `placeholder`; Modal's
+`title`, `subtitle`; AlertDialog's `title`, `description`, `confirmLabel`,
+`cancelLabel`. Strings with no semantic structure → props. Anything that
+might want a `<strong>` or a link inside it → slot.
+
+### Don't mix prop + slot for the same region
+
+Avoid pairing a `:title` prop AND a `#title` slot for the same logical
+region. Pick one and commit to it. Convention:
+
+- If the region is **always** a single string in observed consumer usage →
+  prop (`<Modal title="Confirm">`).
+- If a real consumer needs rich markup → switch the prop to a slot in a
+  deliberate change. Don't ship the dual-API "prop falls back to slot"
+  pattern; it doubles the surface and obscures intent.
+
+### Documented child classes — Card's pattern
+
+When a pure-markup component's default slot accepts rich consumer markup
+AND the component publishes element classes (`pui-card__title`,
+`pui-card__eyebrow`, etc.) for consumers to apply within their own markup,
+those classes are **public API**. Document them in the component's audit
+entry next to the slot description. Consumers write
+`<h3 class="pui-card__title">…</h3>` inside `<Card>`'s slot; the class names
+are stable across versions and renaming them is a breaking change.
+
+This pattern is the **flat-API equivalent** of shadcn-style compound
+subcomponents. Where shadcn writes `<CardTitle>` (a separately-imported
+React component), we write `<h3 class="pui-card__title">` inside a single
+`<Card>` slot. The styling reach is the same; the import surface is one
+component instead of seven.
+
+### Slots are templating, not subcomponents
+
+Named slots accept arbitrary markup or other components. They never require
+importing separately-named subcomponents (no `<CardHeader>` siblings, no
+`<DialogTrigger>` imports). This restates the flat-API rule from D2 and
+applies it to slot wiring: consumer code only ever imports the parent
+component.
+
+### Vue `inheritAttrs` default by archetype
+
+- **Pure-markup with slots** (Card, Empty, Skeleton, Alert, Badge): no
+  inner element to forward to. Use the default `inheritAttrs: true` so
+  consumer-supplied `id`, `class`, `aria-*`, and event listeners land on
+  the wrapper.
+- **Native-element wrapper** (Button): the wrapper IS the native element.
+  Default `inheritAttrs: true` is correct — attrs land on the `<button>` /
+  `<a>` directly.
+- **Form-primitive wrapper** (TextInput): the rendered tree has a wrapper
+  (`pui-field`) AND an inner control (`<input>`). Set `inheritAttrs: false`
+  and `v-bind="$attrs"` on the inner element so consumer attrs reach the
+  control, not the chrome wrapper.
+- **Stateful component** (Modal): the rendered tree is a single mount
+  element (`<dialog class="pui-modal">`) that is both the wrapper and the
+  surface. Set `inheritAttrs: false` and `v-bind="$attrs"` on the
+  `<dialog>` so consumer-supplied `id`, `class`, `aria-*`, and event
+  listeners land on the dialog itself rather than on Vue's auto-merged
+  fallthrough target. The same pattern applies to AlertDialog and Sheet
+  when they land.
+
+---
+
+## Controller mount-on-element pattern
+
+Locked during Phase 1 alongside Modal (2026-05-03). Stateful components (Modal,
+AlertDialog, Sheet, Toast, Popover, Tooltip, DropdownMenu, Combobox, Command,
+Accordion, Collapsible, plus per-input controllers — NumberField, TagsInput,
+InputOTP, Slider, Sidebar) are wired through a controller in
+`packages/ui/utils/controllers/`. The controller owns the runtime state
+machine; the framework (Vue or an Astro `<script>` block) acts as the trigger
+source.
+
+### Default signature — teardown-only
+
+For controllers whose lifecycle is mount → teardown without runtime
+imperative methods (e.g., `controllers/form.ts:mountForm`,
+per-input mounts), the canonical signature is:
+
+```ts
+export function mount<Name>(element: HTMLElement, config?: <Config>): () => void
+```
+
+The returned function tears down all listeners, observers, and DOM mutations
+introduced by the controller. Astro components invoke from a `<script>`
+block; Vue components invoke from `onMounted` and call the teardown from
+`onBeforeUnmount`.
+
+### Stateful-component signature — control object
+
+For stateful components with imperative open/close (or show/hide / expand)
+methods — Modal, AlertDialog, Sheet, Toast, Popover, Tooltip, DropdownMenu,
+Combobox, Accordion, Collapsible — the controller returns a **control
+object** instead of a bare teardown function:
+
+```ts
+interface DialogControl {
+    open(): void;
+    close(): void;
+    isOpen(): boolean;
+    teardown(): void;
+}
+
+export function mountDialog(
+    element: HTMLElement,
+    config?: DialogConfig,
+): DialogControl;
+```
+
+The control object collapses the dialog's state machine to a single source of
+truth. Frameworks call `control.open()` / `control.close()` and observe the
+controller-owned `data-state` attribute; they do not duplicate the state
+machine in reactive props. This avoids the dual-state-machine problem where
+Vue's `props.open` and a controller's internal state desync after a slow
+async transition.
+
+The framework's reactive prop is the **trigger source** — it tells the
+controller "I want to be open now"; the controller is the **state machine** —
+it owns the focus trap, scroll lock, portal placement, and the rendered
+`data-state`. The `onClose` callback closes the loop on user-initiated
+close (Escape, backdrop click): the controller invokes `onClose`, the
+framework reflects it back through its prop / `update:modelValue`, and the
+prop watcher then calls `control.close()` — single source of truth in the
+framework's reactive layer, single source of truth in the controller's
+imperative layer, no duplication.
+
+`teardown()` is mandatory on every control object — it must release
+listeners, focus traps, scroll locks, restore portaled DOM, and null all
+internal references. Calling `teardown()` while `isOpen()` is `true` MUST
+internally call `close()` first so resources don't leak.
+
+### Singleton-style exception
+
+When a controller manages a single global resource (e.g., the Toast queue
+with one global ARIA live region), the module MAY additionally export a
+module-level API (`toast.show()`, `toast.dismiss()`). Use sparingly and
+document the exception here when added.
+
+### When to share a controller vs write a new one
+
+Controllers are SHARED when component variants differ only in
+**configuration** — role, persistent flag, initial focus target, ARIA
+attributes set via `setAttribute`. Modal and AlertDialog (Phase 4) share
+`mountDialog` because the difference is `{ role: 'alertdialog', persistent:
+true, initialFocus: 'cancel' }`.
+
+Controllers are SEPARATE when components differ in **geometry, focus rules,
+or trigger semantics**:
+
+- Popover, Tooltip, DropdownMenu → their own `mountPopover` (anchor-positioned,
+  no scroll lock, no focus trap unless a modal popover, click-outside
+  dismisses by default)
+- Combobox → its own `mountCombobox` (input + listbox composition, typeahead,
+  ARIA combobox pattern)
+- Accordion + Collapsible → share a `mountDisclosure` (expand/collapse pair)
+- Sidebar drawer → `mountSidebar` (the panel is `<nav>`, not `<dialog>`,
+  so it can't share `mountDialog`; see "Use native APIs where applicable"
+  below)
+
+Sheet is NOT in this list — it shares `mountDialog` with Modal +
+AlertDialog. All three render `<dialog>` and only differ in CSS
+geometry (Sheet anchors to a side instead of centering). The controller
+mechanics are identical.
+
+Listed mapping (locked):
+
+- `mountDialog` → Modal, AlertDialog, Sheet (all `<dialog>`-based; see "Use
+  native APIs where applicable" below — Sheet's slide-side geometry is a
+  CSS concern, the controller mechanics are identical)
+- `mountPopover` → Popover, Tooltip, DropdownMenu, HoverCard (all
+  Popover-API-based; deferred to Phase 4)
+- `mountCombobox` → Combobox, Command (search palette)
+- `mountDisclosure` → Accordion, Collapsible
+- `mountSidebar` → Sidebar (its own controller — desktop layout-shell
+  collapse, mobile drawer overlay, per-group expand, and roving-tabindex
+  keyboard nav are all Sidebar-specific geometry/focus-rule concerns; v1
+  owns its group expand/collapse inline and may compose into
+  `mountDisclosure` later)
+- `mountToast` → Toast (with module-level singleton API per the
+  singleton-exception rule)
+- `mountForm` → Form (Astro orchestration only; Vue uses reactive
+  idioms inside `Form.vue` and does not wrap the controller per D13).
+  Signature: `mountForm(formEl, { validators?, onSubmit?, onResult? })`
+  → teardown. Owns submit interception, client-side validation
+  kickoff, per-field + top-level error rendering, `aria-busy` lifecycle
+  management, `focusFirstInvalid` + `announce` calls, and the
+  `FormSubmitResponse` → UI mapping.
+- per-input controllers (each its own file, non-stateful
+  teardown-only signature per the canonical NumberField pattern):
+    - `mountNumberField` → NumberField
+      (`controllers/number-field.ts`). Signature:
+      `mountNumberField(wrapperEl, { onChange? })` → teardown.
+    - `mountTagsInput` → TagsInput (`controllers/tags-input.ts`).
+      Signature: `mountTagsInput(wrapperEl, { initialTags?,
+onChange?, maxTags?, separators? })` → teardown.
+    - `mountInputOTP` → InputOTP (`controllers/otp.ts`). Signature:
+      `mountInputOTP(wrapperEl, { pattern?, onChange? })` →
+      teardown.
+    - `mountSlider` → Slider (`controllers/slider.ts`). Signature:
+      `mountSlider(trackEl, { min?, max?, step?, initialValue?,
+disabled?, onChange? })` → teardown. Note: mounts on the
+      inner `.pui-slider` track element, not the outer `.pui-field`
+      scaffold (matching NumberField's mount-on-inner pattern).
+
+**Form primitives with NO controller** (markup-only with native
+semantics): TextInput, Textarea (planned), Select (planned),
+**Switch**, **Checkbox**, **RadioGroup**. RadioGroup is the
+worked example of a grouped form primitive that does NOT need a
+controller — native `<input type="radio">` elements with a shared
+`name` provide arrow-key keyboard nav, single-selection, and
+Tab-focuses-selected for free; Radix's roving-tabindex
+implementation exists because Radix uses
+`<button role="radio">` rather than the native input. See the
+RadioGroup audit (`components/form/radio-group/AUDIT.md`) for the full rationale.
+
+**Press-button family with NO controller** (markup-only,
+`<button aria-pressed>`-driven): **Toggle** (single press-button),
+**ToggleGroup** (multi-select press-button group), **Segmented**
+(single-select press-button group). Each native `<button>` is
+independently tabbable and independently activatable via
+Enter / Space; pressed state is owned by the consumer (`v-model`)
+and surfaced via always-emit `aria-pressed="true"|"false"`. None
+of the three uses roving tabindex — the pattern is reserved for
+single-focus-per-group controls (RadioGroup arrow-key navigation,
+Tabs roving) where one item represents the entire group's focus
+target. Multi-select press-button groups (ToggleGroup) and
+Segmented's tab-like single-select are both "every button is
+independently tabbable" by design, mirroring how shadcn /
+ToggleGroup degrades to standard button focus when not wrapping
+Radix's primitive.
+
+**When two NON-`<dialog>` overlay controllers duplicate "modal mode"
+mechanics — extract**: this rule applies only to overlays that don't use
+the native `<dialog>` element. With `<dialog>`, the browser already
+provides the modal mechanics (focus trap, Escape, top-layer rendering),
+so `mountDialog` (Modal, AlertDialog, Sheet) is structurally a thin
+wrapper and there is no shared "modal mode" body to extract.
+
+Sidebar's drawer (`controllers/sidebar.ts`) implements its own
+modal-overlay mechanics manually because the panel is a `<nav>`
+landmark rather than a `<dialog>` (see "Use native APIs where
+applicable" below): focus trap on the panel, ref-counted scroll lock
+on body, capture trigger before mount + restore on dismiss,
+ARIA-promotion (`role="dialog"` + `aria-modal="true"` + `aria-label`)
+while open. Today this duplication exists in exactly one place
+(Sidebar). When **a second non-`<dialog>` overlay** lands with the
+same mechanics — Toast's auto-dismissing mode is a candidate, if it
+ends up needing them — review whether to extract a shared
+`utils/a11y/modal-mode.ts` primitive:
+`enterModalMode(panel, { onEscape, restoreFocusTo, ariaLabel }) → exitModalMode()`.
+One consumer is implementation; two is duplication; three is a pattern.
+
+### Use native APIs where applicable
+
+Modern HTML provides native overlay primitives that reduce hand-rolled
+focus traps, portals, and escape-key handling. Use them where they fit:
+
+| Overlay archetype                                          | Native API                                                                                       | Examples                                                                                                                                                                                                                                                                                                                            |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Modal, alert dialog, sheet                                 | `<dialog>` + `showModal()` / `close()`                                                           | Modal, AlertDialog, Sheet (slide-side variants of the dialog primitive)                                                                                                                                                                                                                                                             |
+| Anchored popover, tooltip, dropdown menu, combobox listbox | Popover API (`popover` attribute + `showPopover()` / `hidePopover()`)                            | Popover, Tooltip, DropdownMenu, Combobox                                                                                                                                                                                                                                                                                            |
+| Navigation drawer, sidebar                                 | **Manual**                                                                                       | Sidebar drawer is `<nav>`, not `<dialog>` — keep manual `inert` / focus-trap mechanics. The semantic landmark is more important than the modal mechanics.                                                                                                                                                                           |
+| Toast                                                      | **Manual** — `<ol class="pui-toast-region">` with `aria-live="polite"` and `aria-atomic="false"` | Toasts are non-modal status notifications. The visual layer is a fixed-position `<ol>` (lazy-created by `controllers/toast.ts`); auto-dismiss + queue are owned by the singleton. The Popover API was considered and rejected: it requires a single element, but the toast region holds N siblings whose lifetimes are independent. |
+
+**What native APIs give us (free)**: top-layer rendering (escapes any
+ancestor stacking context / overflow), focus trap (`Tab` cycles within
+the dialog while open), Escape dismiss (fires a `cancel` event whose
+default closes the dialog), `::backdrop` overlay pseudo-element, `[open]`
+state reflection, focus restoration to the trigger on close.
+
+**What we still wire manually**: body scroll lock (browsers don't lock —
+keep `utils/dom/scroll-lock.ts:lockScroll()`), backdrop click dismiss
+for `<dialog>` (the browser doesn't auto-close — detect via
+`event.target === el` since `<dialog>` IS the backdrop element),
+persistent variants (suppress the `cancel` event with
+`event.preventDefault()`), `role="alertdialog"` for AlertDialog (set
+via `setAttribute`), our `data-state="open|closed"` reflection
+convention (so CSS selectors continue working consistently).
+
+The `mountDialog` / `mountPopover` / `mountSheet` controllers stay as
+the public surface — they own the manual pieces above and standardize
+the controller archetype across components — but their internals lean
+on the native APIs rather than rebuilding them. `mountDialog` in
+particular is a thin wrapper over `<dialog>.showModal()` /
+`<dialog>.close()`.
+
+### Astro: hoisted vs inline script
+
+Two patterns for post-render JS in Astro components:
+
+**Hoisted module script** (`<script>` block at bottom of `.astro`, no
+`is:inline`): Astro hoists, dedupes, and bundles. Runs once per page
+load. Use this when many instances of the component can render per
+page (NumberField is the v1 example — its `data-pui-number-field`
+selector mounts the controller on every instance) — the dedupe
+wins. The script uses `document.querySelectorAll([data-…])` to find
+all instances and applies behavior to each.
+
+**Inline script** (`<script>` block in or co-located with markup,
+typically `is:inline`): runs verbatim in DOM order. Use this when
+the component is essentially singleton per page (Modal, Sidebar) and
+needs per-instance state via the `_<controllerName>` expando pattern.
+
+Both patterns ARE compatible with the `_<controllerName>` expando rule
+when stateful behavior is needed; the choice is about deduplication and
+script-payload economy.
+
+### Stateful-component archetype
+
+Parallel to native-element-wrapper and form-primitive wrapper, stateful
+components share a common authoring shape.
+
+**Authoring checklist for stateful components**:
+
+- [ ] Controller in `packages/ui/utils/controllers/<name>.ts` returns a
+      control object `{ open / close / isOpen / teardown }` (or the
+      equivalent imperative pair for non-open/close components, e.g.
+      Disclosure's `expand / collapse / isExpanded / teardown`).
+- [ ] Component template renders the wrapper element as the **mount point**
+      with `data-state="closed"` (or equivalent neutral state) as the
+      static initial value. The controller flips `data-state` at runtime;
+      CSS targets `data-state` selectors only — no class-toggling for state.
+- [ ] Framework component captures a ref to the wrapper element and calls
+      `mount<Name>(el, config)` in `onMounted` (Vue) or in a `<script>`
+      block that runs after DOM is parsed (Astro). The control object is
+      stored on the framework instance (Vue: `let control` in setup; Astro:
+      `(el as any)._<name>` so consumer scripts can reach it).
+- [ ] Framework component watches its reactive `open` (or equivalent) prop
+      and forwards changes to the controller via `control.open()` /
+      `control.close()`. The framework prop is the trigger; the controller
+      owns runtime side-effects.
+- [ ] Framework component supplies an `onClose` (or equivalent
+      user-requested-state-change) callback to the controller. The callback
+      reflects the user intent back into framework state via emit /
+      `update:modelValue`; the framework's prop-watcher then calls
+      `control.close()`.
+- [ ] `onBeforeUnmount` (Vue) / before navigation (Astro) calls
+      `control.teardown()` so listeners, traps, scroll locks, and portaled
+      DOM are released even if `close()` was never called.
+- [ ] **Native APIs first**. `<dialog>`-based overlays (Modal, AlertDialog,
+      Sheet) get top-layer rendering, focus trap, and Escape dismissal
+      from the browser. Popover-API-based overlays (Popover, Tooltip,
+      DropdownMenu, Combobox listbox) get top-layer + light dismiss.
+      The controller layers on body scroll lock, backdrop-click
+      dismissal, persistent suppression, `data-state` reflection, and
+      any role override (`role="alertdialog"`). See "Use native APIs
+      where applicable" below for the full table.
+- [ ] Non-`<dialog>` overlays (Sidebar drawer — the panel is a `<nav>`
+      landmark) use `utils/a11y/focus.ts:createFocusTrap` for the focus
+      trap. If a future overlay needs to portal out of its parent's
+      stacking context, add a portal helper at that point — none ships
+      currently because `<dialog>`-based overlays escape stacking via
+      the native top-layer and the Sidebar drawer stays inline. Vue's
+      `<Teleport>` is intentionally NOT used should portaling be added —
+      both frameworks share one mechanism for one mental model.
+- [ ] Components requiring body-scroll lock use `utils/dom/scroll-lock.ts`.
+      The lock is reference-counted so nested overlays don't release each
+      other prematurely.
+- [ ] Controllers managing manual focus traps (the non-`<dialog>` case)
+      use `utils/a11y/focus.ts:createFocusTrap`. They are also
+      responsible for capturing the trigger before focus moves and
+      restoring focus to it on close. `<dialog>`-based controllers
+      delegate both to the browser; a backup focus restore runs only
+      when the browser fails to restore (rare — e.g. the trigger was
+      removed from the DOM mid-open).
+
+**Locked decisions (Modal, 2026-05-03)** — these apply to every stateful
+overlay component that follows:
+
+- **Native `<dialog>` element**: Modal renders a single `<dialog
+class="pui-modal">` element that is both the surface and the backdrop
+  source (the backdrop is the `::backdrop` pseudo-element). The browser
+  provides top-layer rendering, focus trap, Escape dismissal (via the
+  `cancel` event), `[open]` reflection, and focus restoration to the
+  trigger on close. AlertDialog (Phase 4) and Sheet (Phase 4) reuse
+  the same controller — only their CSS geometry differs.
+- **Portal target**: not applicable. `<dialog>.showModal()` renders
+  in the native top-layer, which already escapes any ancestor stacking
+  context or `overflow: hidden`. There is no portal helper involved.
+- **Scroll-lock policy**: the body's `overflow` is set to `hidden` and
+  `padding-right` is increased by the scrollbar width to prevent layout
+  shift. The lock is reference-counted across all open overlays.
+  Browsers do NOT lock body scroll for `<dialog>` automatically, so the
+  controller still owns this.
+- **`data-state` lifecycle**: `closed` (static initial) → `open` (controller
+  flips on `open()`) → `closed` (controller flips on `close()`). The
+  `[open]` attribute is set by the browser via `showModal()`/`close()`;
+  `data-state` is set by the controller in parallel so CSS selectors
+  consistent with the locked convention keep working. Animated
+  enter/exit transitions drive off the `data-state` selector pairs in
+  CSS; the `opening` / `closing` intermediate states are deferred to
+  per-component as needed (Modal v1 has none — see Modal audit
+  out-of-scope on `@starting-style`).
+- **Initial focus**: `<dialog>.showModal()` auto-focuses the first
+  focusable child (or the element with `[autofocus]`) by default. On
+  top of that, the controller's `initialFocus` config can override:
+  `'cancel'` focuses the element marked `[data-dialog-cancel]`,
+  `HTMLElement` focuses an explicit element, `'first'` and `null`
+  defer to the browser. A `[data-dialog-initial-focus]` element
+  inside the dialog ALWAYS wins over the configured value (consumer
+  override). On `close()`, the browser restores focus to the trigger
+  (`document.activeElement` at the time `showModal()` was called); a
+  manual backup runs only when the browser fails to restore.
+- **Outside-click semantics**: clicks land on the `<dialog>` element
+  itself when the user clicks the `::backdrop` (children clicks bubble
+  through with `target` = the inner content). The controller checks
+  `event.target === el` to detect a backdrop click. Persistent dialogs
+  (AlertDialog, future) skip this dismissal entirely.
+- **Escape key**: when not persistent, Escape fires the native `cancel`
+  event whose default action is `el.close()`. The controller forwards
+  the close intent through `onClose` so the framework's reactive prop
+  stays authoritative. Persistent dialogs call `event.preventDefault()`
+  on the `cancel` event to suppress the default close.
+- **Astro `_<controllerName>` expando**: the control object is exposed on
+  the `<dialog>` element via a property named after the controller (not
+  the component): `_dialog` for `mountDialog` (used by Modal,
+  AlertDialog, and Sheet), `_popover` for `mountPopover`, etc.
+  Consumers reach the API via
+  `document.getElementById('<id>')._dialog.open()`. The TypeScript cast
+  `(el as any)._dialog` is the v1 pattern; a typed helper
+  `getController<T>(el, key)` may land in `utils/dom/` later.
+
+### Worked example — Modal
+
+The full-fat reference. See `packages/ui/components/overlay/modal/` and
+`packages/ui/utils/controllers/dialog.ts` for the actual code.
+
+```ts
+// packages/ui/utils/controllers/dialog.ts
+export interface DialogControl {
+    open(): void;
+    close(): void;
+    isOpen(): boolean;
+    teardown(): void;
+}
+
+export interface DialogConfig {
+    role?: 'dialog' | 'alertdialog'; // default: 'dialog' (browser default for <dialog>)
+    persistent?: boolean; // default: false; suppresses cancel default + backdrop click
+    initialFocus?: 'first' | 'cancel' | HTMLElement | null; // default: 'first' (defers to native showModal())
+    onClose?: () => void; // user-requested close (Escape or backdrop click)
+}
+
+export function mountDialog(
+    el: HTMLDialogElement,
+    config?: DialogConfig,
+): DialogControl;
+```
+
+**Vue consumer** (full pattern):
+
+```vue
+<template>
+    <dialog
+        ref="rootRef"
+        v-bind="$attrs"
+        class="pui-modal"
+        data-state="closed"
+        data-pui-modal
+        :aria-labelledby="titleId"
+    >
+        <h2 :id="titleId">{{ title }}</h2>
+        <slot />
+    </dialog>
+</template>
+
+<script setup lang="ts">
+import { ref, watch, onMounted, onBeforeUnmount } from 'vue';
+import {
+    mountDialog,
+    type DialogControl,
+} from '@pienter/ui/utils/controllers/dialog.js';
+
+defineOptions({ inheritAttrs: false });
+
+const props = defineProps<{
+    open: boolean;
+    title: string;
+    persistent?: boolean;
+}>();
+const emit = defineEmits<{ 'update:open': [boolean]; close: [] }>();
+
+const rootRef = ref<HTMLDialogElement | null>(null);
+let control: DialogControl | null = null;
+
+onMounted(() => {
+    control = mountDialog(rootRef.value!, {
+        persistent: props.persistent,
+        onClose: () => {
+            emit('update:open', false);
+            emit('close');
+        },
+    });
+    if (props.open) control.open();
+});
+
+watch(
+    () => props.open,
+    (v) => (v ? control?.open() : control?.close()),
+);
+
+onBeforeUnmount(() => {
+    control?.teardown();
+    control = null;
+});
+</script>
+```
+
+**Astro consumer** (open-by-default or trigger-driven via `_dialog`):
+
+```astro
+---
+const { id, open, persistent, title } = Astro.props;
+---
+<dialog
+  id={id}
+  class="pui-modal"
+  data-state="closed"
+  data-pui-modal
+  data-persistent={persistent ? 'true' : undefined}
+  data-open-initially={open ? 'true' : undefined}
+  aria-labelledby={`${id}-title`}
+>
+  <h2 id={`${id}-title`}>{title}</h2>
+  <slot />
+</dialog>
+
+<script>
+  import { mountDialog } from '@pienter/ui/utils/controllers/dialog.js';
+  document.querySelectorAll<HTMLDialogElement>('dialog[data-pui-modal]').forEach((el) => {
+    if ((el as any)._dialog) return;
+    const control = mountDialog(el, {
+      persistent: el.dataset.persistent === 'true',
+    });
+    (el as any)._dialog = control;
+    if (el.dataset.openInitially === 'true') control.open();
+  });
+</script>
+```
+
+**Astro consumer page — opening from a trigger button**:
+
+```astro
+<button onclick="document.getElementById('demo-modal')._dialog.open()">
+  Open
+</button>
+<Modal id="demo-modal" title="Confirm" persistent={false}>
+  <p>Body text.</p>
+</Modal>
+```
+
+The `_dialog` consumer pattern is the v1 contract for Astro — each Modal
+exposes its control object as a property on the wrapper element so consumer
+scripts can reach it. A future iteration may add declarative
+`data-modal-trigger="<id>"` button wiring; deferred for v1.
+
+### Vue API decisions
+
+- **`v-model:open`** is the public surface (Vue 3.4+). Implementations may
+  use `defineModel<boolean>('open')` (Vue 3.6+) or the explicit
+  `props: { open } + emit('update:open', boolean)` pair — both produce the
+  same v-model semantics. The library currently uses the explicit
+  `props + emit` pair for consistency with the existing Phase 1 components
+  (Choice, TextInput, Switch, etc.); migrate when a future change refreshes
+  all components together.
+- A separate `@close` event is emitted alongside `update:open(false)` so
+  consumers can hook close-specific side effects without watching the
+  v-model.
+- `inheritAttrs: false` on the wrapper, `v-bind="$attrs"` on the dialog
+  content, mirroring TextInput.
+
+---
+
+## ARIA attribute conventions
+
+Locked during Phase 1 alongside Modal + Card (2026-05-03). When to use
+static ARIA vs reactive bindings, and how each framework expresses the two
+shapes.
+
+### Static ARIA — write the attribute literally
+
+When the value is **template-time constant** — known at render and never
+changes — write the attribute statically on the element. No reactive
+binding. Examples:
+
+```vue
+<!-- Modal dialog content -->
+<div role="dialog" aria-modal="true">…</div>
+```
+
+```astro
+<ul role="list" aria-label="Breadcrumbs">…</ul>
+```
+
+This is the common case for `role`, `aria-modal`, `aria-label` (when the
+label is a literal string), and `aria-orientation`.
+
+### Reactive ARIA bindings (Vue) — `:aria-*`
+
+When the value depends on **props or runtime state**, use Vue's reactive
+binding syntax:
+
+```vue
+<input
+    :aria-invalid="hasErrors ? 'true' : undefined"
+    :aria-describedby="describedBy"
+    :aria-busy="loading ? 'true' : undefined"
+/>
+
+<button :aria-disabled="isDisabled ? 'true' : undefined">…</button>
+
+<div :aria-labelledby="titleId">…</div>
+```
+
+The pattern matches the **boolean-attr-only-when-truthy** rule above: emit
+`'true'` (string) when the prop / state is truthy, otherwise `undefined`
+so Vue drops the attribute entirely. Never emit the literal string
+`'false'`.
+
+### Astro ARIA — template expressions
+
+Astro doesn't have reactivity but its template-expression syntax handles
+the same conditional shape:
+
+```astro
+<input
+  aria-invalid={hasErrors ? 'true' : undefined}
+  aria-describedby={describedBy}
+/>
+
+<div aria-labelledby={`${id}-title`}>…</div>
+```
+
+The only difference from Vue is the syntax sigil (`{}` vs `:`). The
+`undefined`-drops-attribute behavior is identical. Consumer-supplied
+dynamic ARIA values land via the `...rest` spread on the appropriate
+element (the wrapper for pure-markup; the inner control for form
+primitives).
+
+### Boolean ARIA values — strings, not literals
+
+Per the boolean-attr-only-when-truthy rule, emit `'true'` (the string)
+only when the underlying boolean prop is truthy; **omit the attribute
+entirely** otherwise. Never emit `'false'`. CSS that targets ARIA boolean
+state writes `[aria-busy='true']`, `[aria-invalid='true']`,
+`[aria-disabled='true']`, `[aria-expanded='true']`, etc.
+
+**Disambiguation — native HTML booleans vs ARIA boolean strings**:
+native HTML boolean attributes (`disabled`, `readonly`, `required`,
+`checked`, `selected`) follow framework boolean-prop semantics — bind
+the boolean directly (`:disabled="x"` in Vue, `disabled={x}` in Astro);
+the framework renders the bare attribute when truthy and drops it when
+falsy. ARIA boolean attributes (`aria-busy`, `aria-invalid`,
+`aria-disabled`) take the _string_ `'true'` and the only-when-truthy
+idiom (`x ? 'true' : undefined`). Do not pass a raw boolean to an
+`aria-*` binding — Astro will stringify `false` to the literal
+`"false"`, which fails the rule. For `aria-expanded`, `aria-checked`,
+`aria-pressed`, and `aria-selected`, see Always-emit ARIA exceptions
+below — they require explicit `'true'`/`'false'`.
+
+**Always-emit exceptions** — a small set of ARIA attributes carry
+meaning in BOTH their `'true'` and `'false'` states (the absent state
+means something different — typically "not applicable" rather than
+"explicitly false"). For these, emit the string `'true'` or `'false'`
+literally; do NOT omit when falsy:
+
+- `aria-expanded` on a disclosure trigger / group toggle — absent means
+  "not a disclosure"; `'false'` means "is a disclosure, currently
+  collapsed". Used by Sidebar group toggles and any future
+  Disclosure-pattern component.
+- `aria-checked` on `role="switch"` or `role="checkbox"` /
+  `role="radio"` controls — absent means "not a check-style control";
+  `'false'` means "is a check-style control, currently unchecked".
+  Used by Switch, Checkbox, and RadioGroup items. v1 Checkbox emits
+  the binary `'true'` / `'false'` only; the tri-state `'mixed'`
+  branch is reserved for a future tri-state consumer (e.g., a
+  "select all" data-table header) and re-enters the rule unchanged.
+- `aria-pressed` on a toggle button (`role="button"` with toggled
+  state) — same shape; `'false'` means "is a toggle button, currently
+  not pressed". Used by the future press-button Toggle (Phase 4).
+- `aria-selected` on listbox / option / tab items — absent means "not
+  a selectable item"; `'false'` means "is selectable, currently not
+  selected".
+
+For these four, the binding shape is `:aria-<name>="x ? 'true' :
+'false'"` (Vue) or `aria-<name>={x ? 'true' : 'false'}` (Astro). Native
+elements with intrinsic role semantics provide some of this for free
+(e.g. `<input type="checkbox">` carries implicit `checked` state) — but
+when the role is set explicitly (`role="switch"` on a checkbox-backed
+input), the matching ARIA attribute MUST also be set explicitly so AT
+reads the role-state pair consistently.
+
+### ARIA ownership — template vs controller
+
+For stateful components (Modal, AlertDialog, Sheet, Popover, Disclosure),
+some ARIA attributes are owned by the **template** (template-time data —
+heading IDs, label strings, role choice when fixed) and some by the
+**controller** (runtime state — `aria-modal` set during open, `data-state`
+mirrored to ARIA semantics where applicable). Each controller's audit
+entry documents which ARIA attributes it owns; everything else is the
+framework template's responsibility. For Modal:
+
+- Template: `aria-labelledby` (heading ID is template-time).
+- Browser: `role="dialog"` (the implicit role for `<dialog>`) and
+  `aria-modal` (set implicitly when `showModal()` is called) — no
+  template or controller wiring needed.
+- Controller: `role` override only — `mountDialog` calls
+  `setAttribute('role', 'alertdialog')` for AlertDialog. Modal v1
+  doesn't override and inherits the browser default.
+
+### Prefer `aria-labelledby` over `aria-label` when a visible label exists
+
+When the labelling element is already in the DOM (the dialog title `<h2>`,
+the field's `<label>`), point at it with `aria-labelledby="<id>"` rather
+than duplicating the same string in `aria-label`. This avoids the two
+copies drifting apart and keeps a single source of truth for the visible
+label.
+
+`aria-label` is the right call only when there's no visible label
+(icon-only buttons, search input without a sibling label, decorative
+landmarks).
+
+---
+
+## `:focus-visible` rule
+
+Every interactive component renders a consistent keyboard-focus ring:
+
+```css
+.pui-<block > :focus-visible {
+    outline: 3px solid var(--outline-clr-base);
+    outline-offset: 2px;
+}
+```
+
+- Use `:focus-visible`, not `:focus` — mouse clicks on a button SHOULD NOT show the ring.
+- Token-only — never hardcode the color or width.
+- Apply on the focusable element. For native-element wrappers that's the wrapper itself; for composite components (Tabs, RadioGroup) it's the focusable child (e.g., `.pui-tabs__trigger:focus-visible`).
+- Do not remove the ring in a `:focus { outline: 0 }` reset — let it default and override only via `:focus-visible`.
+
+---
+
+## Astro tier mapping
+
+Components ship Astro implementations only when listed in this tier. SPA-only interactive components are Vue-only; Astro consumers needing them render the Vue version as an Astro island via `client:visible`.
+
+| Tier                         | Components                                                                                                                                            | Astro?                                                |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| Static markup                | Card, Badge, Alert, Avatar, Avatar-stack, Breadcrumb, Empty, Icon, Skeleton, Spinner, Separator, Progress, Label                                      | Yes — pure `.astro`, no JS                            |
+| Form primitives              | Button, TextInput, Textarea, Form, Checkbox, RadioGroup, Switch, Select, NumberField, DateInput, TagsInput, InputOTP, Slider                          | Yes — JS via controllers where needed                 |
+| Marketing-needed interactive | Modal, AlertDialog, Toast                                                                                                                             | Yes — `controllers/dialog.ts`, `controllers/toast.ts` |
+| Layout                       | Navbar, Sidebar, Table                                                                                                                                | Yes — Table's sort ships as links, so still no JS     |
+| SPA-only interactive         | Tabs, Pagination, Segmented, Toggle (press), ToggleGroup, Popover, Tooltip, DropdownMenu, Combobox, Command, Sheet, Accordion, Collapsible, DataTable | **Vue-only**                                          |
+
+Table sort is deliberately not in the Vue-only row. Sorting a table is a
+navigation, not SPA state (ADR 0005), so the Astro tier renders each sortable
+header as an `<a>` pointing at the URL that column would produce next — same
+`aria-sort`, same chevron glyph, same asc → desc → unsorted cycle as the Vue
+tier's `<button>`, and no JavaScript. What stays Vue-only is `DataTable`, the
+data-driven wrapper: it renders rows from a reactive array and owns selection
+state, neither of which a static page has.
+
+---
+
+## shadcn / Radix commit pins
+
+_Pinned 2026-05-03. Update both together as a separate, intentional change._
+
+- **shadcn/ui**: [`7865621397708917369251d67029ad920e390a38`](https://github.com/shadcn-ui/ui/tree/7865621397708917369251d67029ad920e390a38) — 2026-04-30
+- **Radix Primitives**: [`22473d16404bfd446305db5b6c9308aece99fdec`](https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec) — 2026-02-13
+
+Per-component briefs cite specific source paths under these SHAs. Subagents read the pinned references, not `main`.
+
+---
+
+## Per-component audits
+
+Each component keeps its own audit next to its source, so a decision and the
+code it governs move in the same diff. Add an entry when you add a component;
+follow the shape of an existing one.
+
+| Component    | Audit                                                                                      |
+| ------------ | ------------------------------------------------------------------------------------------ |
+| Accordion    | [`components/layout/accordion/AUDIT.md`](./components/layout/accordion/AUDIT.md)           |
+| Alert        | [`components/feedback/alert/AUDIT.md`](./components/feedback/alert/AUDIT.md)               |
+| AlertDialog  | [`components/overlay/alert-dialog/AUDIT.md`](./components/overlay/alert-dialog/AUDIT.md)   |
+| Avatar       | [`components/display/avatar/AUDIT.md`](./components/display/avatar/AUDIT.md)               |
+| AvatarStack  | [`components/display/avatar/AUDIT.md`](./components/display/avatar/AUDIT.md)               |
+| Badge        | [`components/display/badge/AUDIT.md`](./components/display/badge/AUDIT.md)                 |
+| Breadcrumb   | [`components/navigation/breadcrumb/AUDIT.md`](./components/navigation/breadcrumb/AUDIT.md) |
+| Button       | [`components/action/button/AUDIT.md`](./components/action/button/AUDIT.md)                 |
+| Card         | [`components/layout/card/AUDIT.md`](./components/layout/card/AUDIT.md)                     |
+| Checkbox     | [`components/form/checkbox/AUDIT.md`](./components/form/checkbox/AUDIT.md)                 |
+| Collapsible  | [`components/layout/collapsible/AUDIT.md`](./components/layout/collapsible/AUDIT.md)       |
+| Combobox     | [`components/form/combobox/AUDIT.md`](./components/form/combobox/AUDIT.md)                 |
+| Command      | [`components/overlay/command/AUDIT.md`](./components/overlay/command/AUDIT.md)             |
+| DataTable    | [`components/layout/table/AUDIT.md`](./components/layout/table/AUDIT.md)                   |
+| DateInput    | [`components/form/date-input/AUDIT.md`](./components/form/date-input/AUDIT.md)             |
+| DropdownMenu | [`components/overlay/dropdown-menu/AUDIT.md`](./components/overlay/dropdown-menu/AUDIT.md) |
+| Empty        | [`components/display/empty/AUDIT.md`](./components/display/empty/AUDIT.md)                 |
+| Form         | [`components/form/form/AUDIT.md`](./components/form/form/AUDIT.md)                         |
+| Icon         | [`components/display/icon/AUDIT.md`](./components/display/icon/AUDIT.md)                   |
+| IconButton   | [`components/action/button/AUDIT.md`](./components/action/button/AUDIT.md)                 |
+| InputOTP     | [`components/form/input-otp/AUDIT.md`](./components/form/input-otp/AUDIT.md)               |
+| Label        | [`components/form/label/AUDIT.md`](./components/form/label/AUDIT.md)                       |
+| Modal        | [`components/overlay/modal/AUDIT.md`](./components/overlay/modal/AUDIT.md)                 |
+| Navbar       | [`components/navigation/navbar/AUDIT.md`](./components/navigation/navbar/AUDIT.md)         |
+| NumberField  | [`components/form/number-field/AUDIT.md`](./components/form/number-field/AUDIT.md)         |
+| Pagination   | [`components/navigation/pagination/AUDIT.md`](./components/navigation/pagination/AUDIT.md) |
+| Popover      | [`components/overlay/popover/AUDIT.md`](./components/overlay/popover/AUDIT.md)             |
+| Progress     | [`components/feedback/progress/AUDIT.md`](./components/feedback/progress/AUDIT.md)         |
+| RadioGroup   | [`components/form/radio-group/AUDIT.md`](./components/form/radio-group/AUDIT.md)           |
+| Segmented    | [`components/form/select/AUDIT.md`](./components/form/select/AUDIT.md)                     |
+| Select       | [`components/form/select/AUDIT.md`](./components/form/select/AUDIT.md)                     |
+| Separator    | [`components/layout/separator/AUDIT.md`](./components/layout/separator/AUDIT.md)           |
+| Sheet        | [`components/overlay/sheet/AUDIT.md`](./components/overlay/sheet/AUDIT.md)                 |
+| Sidebar      | [`components/navigation/sidebar/AUDIT.md`](./components/navigation/sidebar/AUDIT.md)       |
+| Skeleton     | [`components/feedback/skeleton/AUDIT.md`](./components/feedback/skeleton/AUDIT.md)         |
+| Slider       | [`components/form/slider/AUDIT.md`](./components/form/slider/AUDIT.md)                     |
+| Spinner      | [`components/feedback/spinner/AUDIT.md`](./components/feedback/spinner/AUDIT.md)           |
+| Switch       | [`components/form/switch/AUDIT.md`](./components/form/switch/AUDIT.md)                     |
+| Table        | [`components/layout/table/AUDIT.md`](./components/layout/table/AUDIT.md)                   |
+| Tabs         | [`components/navigation/tabs/AUDIT.md`](./components/navigation/tabs/AUDIT.md)             |
+| TagsInput    | [`components/form/tags-input/AUDIT.md`](./components/form/tags-input/AUDIT.md)             |
+| Textarea     | [`components/form/textarea/AUDIT.md`](./components/form/textarea/AUDIT.md)                 |
+| TextInput    | [`components/form/text-input/AUDIT.md`](./components/form/text-input/AUDIT.md)             |
+| Toast        | [`components/feedback/toast/AUDIT.md`](./components/feedback/toast/AUDIT.md)               |
+| Toggle       | [`components/action/toggle/AUDIT.md`](./components/action/toggle/AUDIT.md)                 |
+| ToggleGroup  | [`components/action/toggle-group/AUDIT.md`](./components/action/toggle-group/AUDIT.md)     |
+| Tooltip      | [`components/overlay/tooltip/AUDIT.md`](./components/overlay/tooltip/AUDIT.md)             |
+
+## Form submit response contract
+
+_Placeholder shape — subject to change when ts-sdk publishes the canonical response shape. The symmetry requirement (same shape consumed by Vue `Form.vue` and Astro `controllers/form.ts:mountForm`) is locked; the shape itself is provisional and will be migrated together when ts-sdk lands._
+
+Both the Vue `Form.vue` and the Astro `controllers/form.ts:mountForm` SHALL accept the same submit response shape, mapping server validation errors, success messages, and redirect signals through identical contracts. Drift between the two implementations is treated as a defect.
+
+```ts
+// packages/ui/utils/validation/form.ts
+export interface FormSubmitResponse {
+    /** Whether the submit succeeded. */
+    ok: boolean;
+    /** Per-field errors keyed by field `name`. Single string or array of strings. */
+    fieldErrors?: Record<string, string | string[]>;
+    /** Top-level errors not tied to a specific field. */
+    errors?: string[];
+    /** Success/status message to announce via aria-live. */
+    statusMessage?: string;
+    /**
+     * Optional post-submit redirect URL — orchestration does NOT
+     * auto-navigate; the value is just stored on the response for the
+     * consumer to act on.
+     */
+    redirect?: string;
+}
+```
+
+**Mapping rules — both frameworks**:
+
+- `ok: true` clears all errors, renders `statusMessage` in `.pui-form__status`, and announces it politely.
+- `ok: false` renders `errors` in `.pui-form__error-summary`, applies `fieldErrors` to the matching form-primitive wrappers (per-field error list inside `pui-field__hint role="alert"` + `aria-invalid="true"` on the control), focuses the first invalid field via `focusFirstInvalid`, and announces the error count assertively.
+- `redirect` is a passive value — orchestration does NOT navigate; consumers act on it inside their `onResult` / `@submit` callback.
+
+**Field error normalization**: `fieldErrors[name]` MAY be a single string or an array of strings. Orchestration normalizes to `string[]` via the shared `normalizeFieldErrors` helper before applying to the DOM.
+
+```ts
+// Server APIs commonly send fieldErrors as `string` for single errors
+// and `string[]` for multiple. Use `normalizeFieldErrors` to coerce to
+// the canonical `Record<string, string[]>` shape:
+import { normalizeFieldErrors } from '@pienter/ui/utils/validation';
+
+const response = await api.submit(data);
+const normalized = normalizeFieldErrors(response.fieldErrors);
+// Now safe to .map() and .length-check every entry.
+```
+
+---
+
+## RTL approach
+
+_Deferred unless a component explicitly needs it. Captured here when it does._
+
+---
+
+## ARIA live region
+
+A single global ARIA live region is mounted lazily by the first `announce(text, priority)` call from `utils/a11y/live-region.ts`. Components SHALL NOT create per-component live regions; SHALL use `announce()` for dynamic state-change announcements.
+
+---
+
+## Component audit table
+
+One row per module directory under `packages/ui/components/<category>/`. Where a directory ships multiple components (e.g. `avatar/` ships `Avatar` + `AvatarStack`; `select/` ships `Select` + `Segmented`) the row summarises the primary component and the co-located `AUDIT.md` carries the detail. "Last audited" is the date this table was last refreshed in full; a component's `AUDIT.md` may carry an older date if untouched since.
+
+Pinned upstream SHAs used across the table:
+
+- shadcn-ui/ui: `7865621397708917369251d67029ad920e390a38` (apps/v4 New York v4 registry, captured 2026-05-03)
+- radix-ui/primitives: `22473d16404bfd446305db5b6c9308aece99fdec` (captured 2026-05-03)
+
+| Component     | shadcn URL                                                                                                                        | shadcn SHA                               | Radix-Vue URL                                                                                                                       | Radix-Vue SHA                              | Last audited |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------ |
+| accordion     | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/accordion.tsx       | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/accordion/src                   | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+| alert         | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/alert.tsx           | 7865621397708917369251d67029ad920e390a38 | n/a — no headless dep (Radix has no Alert primitive; `role="alert"` is native)                                                      | n/a                                        | 2026-05-27   |
+| alert-dialog  | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/alert-dialog.tsx    | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/alert-dialog/src                | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+| avatar        | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/avatar.tsx          | 7865621397708917369251d67029ad920e390a38 | https://www.radix-ui.com/primitives/docs/components/avatar                                                                          | n/a — referenced docs page, not source pin | 2026-05-27   |
+| badge         | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/badge.tsx           | 7865621397708917369251d67029ad920e390a38 | n/a — no headless dep (Badge is pure markup)                                                                                        | n/a                                        | 2026-05-27   |
+| breadcrumb    | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/breadcrumb.tsx      | 7865621397708917369251d67029ad920e390a38 | n/a — no headless dep (semantic `<nav>` + `<ol>`)                                                                                   | n/a                                        | 2026-05-27   |
+| button        | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/button.tsx          | 7865621397708917369251d67029ad920e390a38 | n/a — no headless dep (native `<button>`/`<a>`)                                                                                     | n/a                                        | 2026-05-27   |
+| card          | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/card.tsx            | 7865621397708917369251d67029ad920e390a38 | n/a — no headless dep (Card is pure markup)                                                                                         | n/a                                        | 2026-05-27   |
+| checkbox      | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/checkbox.tsx        | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/blob/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/checkbox/src/checkbox.tsx       | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+| collapsible   | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/collapsible.tsx     | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/collapsible/src                 | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+| combobox      | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/combobox.tsx        | 7865621397708917369251d67029ad920e390a38 | n/a — Radix does not ship a Combobox primitive                                                                                      | n/a                                        | 2026-05-27   |
+| command       | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/command.tsx         | 7865621397708917369251d67029ad920e390a38 | n/a — Radix does not ship a Command primitive                                                                                       | n/a                                        | 2026-05-27   |
+| date-input    | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/date-picker.tsx     | 7865621397708917369251d67029ad920e390a38 | n/a — Radix does not publish a DatePicker primitive                                                                                 | n/a                                        | 2026-05-27   |
+| dropdown-menu | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/dropdown-menu.tsx   | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/dropdown-menu/src               | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+| empty         | Bespoke — shadcn does not ship an Empty / EmptyState component; internal design, manual a11y review                               | Bespoke                                  | n/a — no headless dep (Empty is pure markup)                                                                                        | n/a                                        | 2026-05-27   |
+| form          | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/form.tsx            | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/blob/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/form/src/form.tsx               | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+| icon          | Bespoke — shadcn does not ship a generic Icon component; internal design, manual a11y review                                      | Bespoke                                  | n/a — no headless dep                                                                                                               | n/a                                        | 2026-05-27   |
+| input-otp     | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/input-otp.tsx       | 7865621397708917369251d67029ad920e390a38 | n/a — Radix does not publish an OTP primitive                                                                                       | n/a                                        | 2026-05-27   |
+| label         | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/label.tsx           | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/label/src                       | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+| modal         | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/dialog.tsx          | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/dialog/src                      | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+| navbar        | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/navigation-menu.tsx | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/navigation-menu                 | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+| number-field  | Bespoke — shadcn/ui v4 has no dedicated NumberField component; internal design referencing WAI spinbutton pattern                 | Bespoke                                  | n/a — Radix does not publish a Number primitive                                                                                     | n/a                                        | 2026-05-27   |
+| pagination    | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/pagination.tsx      | 7865621397708917369251d67029ad920e390a38 | n/a — no headless dep (Pagination is semantic links)                                                                                | n/a                                        | 2026-05-27   |
+| popover       | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/popover.tsx         | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/popover/src                     | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+| progress      | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/progress.tsx        | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/blob/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/progress/src/progress.tsx       | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+| radio-group   | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/radio-group.tsx     | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/blob/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/radio-group/src/radio-group.tsx | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+| select        | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/select.tsx          | 7865621397708917369251d67029ad920e390a38 | n/a — v1 uses native `<select>`; Segmented co-located in this directory references the toggle-group Radix entry below               | n/a                                        | 2026-05-27   |
+| separator     | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/separator.tsx       | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/separator/src                   | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+| sheet         | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/sheet.tsx           | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/dialog/src                      | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+| sidebar       | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/sidebar.tsx         | 7865621397708917369251d67029ad920e390a38 | n/a — no headless dep (Radix has no Sidebar primitive; item-shape API is bespoke)                                                   | n/a                                        | 2026-05-27   |
+| skeleton      | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/skeleton.tsx        | 7865621397708917369251d67029ad920e390a38 | n/a — no headless dep (Skeleton is pure CSS)                                                                                        | n/a                                        | 2026-05-27   |
+| slider        | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/slider.tsx          | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/blob/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/slider/src/slider.tsx           | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+| switch        | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/switch.tsx          | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/blob/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/switch/src/switch.tsx           | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+| table         | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/table.tsx           | 7865621397708917369251d67029ad920e390a38 | n/a — no headless dep (semantic `<table>`)                                                                                          | n/a                                        | 2026-05-27   |
+| tabs          | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/tabs.tsx            | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/tabs/src                        | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+| tags-input    | Bespoke — shadcn/ui v4 has no dedicated TagsInput; internal design referencing combobox + chip patterns                           | Bespoke                                  | n/a — Radix does not publish a TagsInput primitive                                                                                  | n/a                                        | 2026-05-27   |
+| text-input    | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/input.tsx           | 7865621397708917369251d67029ad920e390a38 | n/a — no headless dep (native `<input>`)                                                                                            | n/a                                        | 2026-05-27   |
+| textarea      | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/textarea.tsx        | 7865621397708917369251d67029ad920e390a38 | n/a — no headless dep (native `<textarea>`)                                                                                         | n/a                                        | 2026-05-27   |
+| toast         | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/sonner.tsx          | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/toast/src                       | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+| toggle        | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/toggle.tsx          | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/toggle/src                      | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+| toggle-group  | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/toggle-group.tsx    | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/toggle-group/src                | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+| tooltip       | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/tooltip.tsx         | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/tooltip/src                     | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |