@godxjp/ui 19.1.0 → 19.2.0

package/docs/DEVELOPMENT.md

@@ -0,0 +1,173 @@
+# Development Guideline — `@godxjp/ui`
+
+How to work **on** the design system (not just with it). If you only consume the framework from the app, read [the ten consumer rules](./CONSUMER-RULES.md) instead — this file is for people **editing `packages/godx-ui/`**.
+
+---
+
+## 0. What this package IS — and the boundary it must keep
+
+`@godxjp/ui` is **the** UI framework for every godx surface (admin, agency portal, handheld). It is shared, versioned infrastructure: one change here ripples to every screen and every consumer. Two consequences:
+
+1. **Editing it needs explicit session permission** — the hard gate in [CLAUDE.md](../CLAUDE.md) (MANDATORY: read the component skill before touching UI). Treat the package as off-limits by default. 2. **It is generic and presentational only.** The framework knows about _tokens, layout, accessibility, and interaction_ — never about the app's data, routes, language files, or business rules.
+
+### The hard boundary — consumer-layer concerns MUST NOT leak in
+
+A component in this package may **not** import or assume any of the following. These belong to the **consumer** (the app), which composes framework primitives around them:
+
+| ❌ Never inside `packages/godx-ui/`                              | ✅ Where it belongs                                                 |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------- |
+| App i18n — `useTranslation`, `t()`, `resources/js/i18n`          | App passes already-translated strings in as props                   |
+| Inertia — `router`, `usePage`, `<Form>`, `@inertiajs/*`          | App wires navigation/submit; pass `onClick`/`href`/`onSubmit` props |
+| Wayfinder routes — `@/routes`, `@/actions`, `.url()`             | App resolves the URL, passes a plain string                         |
+| Business entities / domain logic (Item, Packing, shipment rules) | App-level component in `resources/js/components/**`                 |
+| App copy / labels / placeholder text baked into the component    | Comes in via props; framework ships no product wording              |
+| Raw colors / hex / `hsl(...)` literals, `dark:` overrides        | Semantic tokens (`var(--…)`, `bg-primary`, …) — see §3              |
+| A consumer's theme values redefined inside a component           | Theme lives in `src/tokens/` (the framework default ships it)       |
+
+> **Litmus test:** if a component can't render in a Storybook-style preview with
+> plain props and zero app context, it does **not** belong in this package. Keep it
+> app-level (`resources/js/components/admin/…`) and have it _compose_ framework
+> primitives. See the **`godx-ui-component-placement`** skill for the full decision.
+
+The framework ships its **own theme** (colors, fonts, type scale, wa-iro palette) in `src/tokens/foundation.css`, so consumers import `@godxjp/ui/styles` and need **zero** extra theme config. Do not push theme decisions back onto the consumer.
+
+---
+
+## 1. Architecture — the layers, bottom-up
+
+```
+src/tokens/        Design tokens (the single source of values)
+  foundation.css   :root + .dark — colors, fonts, type scale, spacing, radius, wa-iro
+  primitives/*.css Per-domain primitive tokens (card, table, control, badge, …)
+  base.css         Coordinates the token layer
+src/styles/        CSS that styles components by [data-slot] + density.css (the density knob)
+  index.css        Entry: @import fontsource → tailwindcss → @theme (token→utility map) → layout css
+src/components/    React components, grouped (data-display, data-entry, layout, …)
+src/props/         Prop type system — vocabulary/ (atomic) + components/ + registry.ts
+src/lib/           cn(), control-styles, variants — shared helpers
+examples/          *.preview.tsx — Storybook-style stories (preview app)
+docs/primitives/   <component>/index.tsx demo + examples/ + generated .md
+preview/           The preview app (vite) on :6008 that renders examples + docs
+```
+
+**Token → utility flow:** a value is defined once as a CSS var in `tokens/foundation.css` (e.g. `--primary`), mapped to a Tailwind utility in the `@theme` block of `styles/index.css` (`--color-primary: hsl(var(--primary))`), and consumed as `bg-primary` / `hsl(var(--primary))`. Never skip a layer with a literal.
+
+### The component pattern — markup emits slots, CSS owns styling
+
+Components render semantic structure and `data-slot` / `data-*` flags; **the spacing, padding, and chrome live in `src/styles/*-layout.css`**, keyed on those slots. This keeps density and theming centralized.
+
+```tsx
+// component: emits slots + flags only
+<div data-slot="card" data-variant={variant} data-density={density} />
+```
+
+```css
+/* styles/card-layout.css: owns the look */
+[data-slot="card"] {
+  border: 1px solid hsl(var(--card-border));
+  border-radius: var(--card-radius);
+}
+[data-slot="card"][data-density="tight"] {
+  --card-space-inset: var(--space-3);
+}
+```
+
+Prefer this over hardcoding Tailwind padding inside the component. Use Tailwind utility classes for **one-off layout** (flex/grid/gap), not for re-theming.
+
+### Density
+
+One knob — `.ui-density-{compact,default,comfortable}` in `styles/density.css` — retunes `--phi-unit`, control heights, and table row heights together. Components read the resulting tokens; never branch on density in component JS.
+
+### The `ui/` layer
+
+`src/components/ui/*` are thin **re-exports** of the canonical implementation (`export * from "../data-display/card"`). They exist for shadcn-style import paths. Edit the canonical file under its group; the `ui/` path follows automatically.
+
+---
+
+## 2. Adding or changing a component (after you have §0 permission)
+
+Work in this order; only advance when the previous step genuinely can't express the need:
+
+1. **Use** an existing primitive. 2. **Compose** primitives (Card + FormField + Flex…). 3. **Extend** an existing component — add a prop/slot (e.g. `labelAddon`, `accent`). Prefer this: one more prop beats one more component. 4. **Create** a new component — last resort.
+
+Document the decision (which promotion criteria it met) so review can check it — see [COMPOSITION-VS-COMPONENT.md](./COMPOSITION-VS-COMPONENT.md).
+
+---
+
+## 3. Rules for framework code
+
+- **Semantic tokens only.** No raw hex / `rgb()` / `hsl()` literals, no palette utilities (`bg-blue-500`), no `dark:` overrides — tokens adapt automatically. Structural literals (a `3px` accent stripe, `1px` borders) are fine; _color/size scale_ values come from tokens. - **No app coupling** (the §0 boundary table above). - **Props live in `src/props/`** — atomic concepts in `vocabulary/`, per-component interfaces in `components/`. Check `registry.ts` + `PROP_ALIASES_FORBIDDEN` before inventing a prop name.
+
+---
+
+## 4. Every component change ships its story + docs
+
+A change isn't done until its documentation reflects it:
+
+1. **Preview story** — `examples/<group>/<Component>.preview.tsx` (Storybook-style). New props get a story (see `examples/data-display/Card.preview.tsx`: Surfaces / Density / AccentEdges). 2. **Docs demo** — `docs/primitives/<group>/<component>/index.tsx` shows the new capability; `examples/` holds focused per-feature demos. 3. **Regenerate props docs** — `pnpm docs:sync-primitives` regenerates the `.md` from source. Run it after prop changes so the tables stay accurate.
+
+> Docs are mid-migration to the `<component>/index.tsx (+ examples/)` shape. Do **not**
+> resurrect flat `docs/primitives/<component>.tsx` demos — they were dead orphans and
+> were removed.
+
+---
+
+## 5. Verify before finishing
+
+```bash
+pnpm lint                 # eslint — self-contained flat config
+pnpm typecheck            # tsc --noEmit
+pnpm test                 # vitest per component
+pnpm preview:build        # integration test: examples + docs must build
+pnpm audit                # godxjp-ui-audit — 0 errors for touched files
+pnpm check:mcp-sync       # MCP registry ↔ library export drift guard
+```
+
+`pnpm verify` and `pnpm verify:release` run these together (verify:release also builds). It needs `pnpm exec playwright install chromium` once locally; see [FRAME-A11Y-CI.md](./FRAME-A11Y-CI.md) for how to run/scope it, read the evidence, and regenerate its baseline after an accessibility fix.
+
+All gates are **self-contained** — no internal/external tooling package required. The eslint, prettier, and vitest setup live in the package (`eslint.config.js`, `prettier.config.mjs`, `vitest.config.ts`, `src/test/`), so a fresh checkout can lint/type-check/test without anything beyond the declared devDependencies.
+
+The app side additionally runs **`npm run ui:audit`** (the design-system linter) and must report 0 errors for touched files.
+
+---
+
+## 6. Releasing — the lib and its MCP, in lockstep
+
+This repo publishes **two packages** that must agree: `@godxjp/ui` (the browser component library, root `package.json`) and `@godxjp/ui-mcp` (the Node MCP server that tells agents how to use it, `mcp/`).
+
+### The lockstep contract (issue #140)
+
+A consumer that installs `@godxjp/ui@16.10.x` but points its agent at `@godxjp/ui-mcp@16.7.x` gets prop/token/pattern guidance for a build it never installed. To make that impossible, the two packages carry **mutual, machine-readable compatibility metadata**:
+
+- root `package.json` → `"godxUiMcp": "<mcp version>"` — the catalog version this library ships with.
+- `mcp/package.json` → `"version"` (identical to the library) **and** `"godxUiCompatibility": "<maj>.<min>.x"` — the UI minor this catalog describes.
+- the MCP exposes it at runtime: `serverInfo.version` == package version, the `godx-ui://compatibility` resource, and the `check_compatibility` tool (an agent calls it with the app's installed `@godxjp/ui` version to get a match/mismatch verdict).
+
+- **Lockstep guard** (`pnpm check:mcp-lockstep` → `scripts/check-release-lockstep.mjs`) — asserts ui.version == mcp.version, ui.godxUiMcp == mcp.version, and mcp.godxUiCompatibility covers the UI version. Any split fails CI. - **Catalog drift guard** (`pnpm check:mcp-sync` / `check:mcp-orphans`) — every component the MCP catalogs must still be a real library export, and vice-versa. - **Packed-artifact guard** (`release-integrity` CI, step 4) — packs both tarballs and re-asserts lockstep on the **packed** manifests, i.e. the bytes that would actually ship.
+
+### Coordinated release (`pnpm release`)
+
+```bash
+pnpm release --ui minor --mcp sync   # bump ui, republish mcp at the SAME new version — the norm
+pnpm release --mcp sync              # mcp-only fix at the current ui version
+```
+
+`--ui <bump>` **requires** `--mcp sync` (the tool refuses a ui-only release) so the two packages can never split. On a bump the tool refreshes both compatibility fields, runs `verify:release` (incl. all three guards) before publishing the lib, `npm publish`es each package, re-runs the lockstep check as a final fail-closed gate, then commits the version bumps.
+
+### Recovery from a partial publish
+
+If a run publishes `@godxjp/ui` but the `@godxjp/ui-mcp` publish fails (npm hiccup, expired token), the two are momentarily split on npm. Recover:
+
+1. Fix the cause (e.g. re-auth `npm whoami`), keep the working tree at the just-published version. 2. Re-run **only** the MCP half at that same version: `pnpm --dir mcp build && npm --prefix mcp version <ui-version> --allow-same-version && npm --prefix mcp publish --access public`. 3.
+
+npm versions are immutable, so you can never "fix" a bad published version in place — you can only publish the matching partner at the same number, or move both forward with a fresh `pnpm release --ui patch --mcp sync`. Never hand-publish one package and forget the other.
+
+---
+
+## See also
+
+- [README](../README.md) — overview, component groups, consumer setup.
+- [CONSUMER-RULES.md](./CONSUMER-RULES.md) — the ten rules every consumer follows (the audit enforces them).
+- `docs/TOKENS.md`, `docs/SPACING.md`, `docs/PROPS-VOCABULARY.md`, `docs/PROPS-REGISTRY.md`.
+- [FRAME-A11Y-CI.md](./FRAME-A11Y-CI.md) — per-frame axe a11y + geometry + coverage CI gates.
+- **`godx-ui-component-placement`** skill — decide whether a component belongs here.

package/docs/FORMS.md

@@ -0,0 +1,143 @@
+# Forms — react-hook-form + Zod 4 (mandatory)
+
+All forms in admin apps **must** use:
+
+| Package               | Version | Role                 |
+| --------------------- | ------- | -------------------- |
+| `react-hook-form`     | ^7.76   | Form state           |
+| `zod`                 | ^4.4    | Schema validation    |
+| `@hookform/resolvers` | ^5.2    | `zodResolver` bridge |
+
+Import from `@godxjp/ui/form` — **never** call `useForm()` without `zodResolver`.
+
+## Quick start
+
+```tsx
+import { z } from "zod";
+import { useZodForm, FormRoot, FormFieldControl } from "@godxjp/ui/form";
+import { Input } from "@godxjp/ui/data-entry";
+import { Button } from "@godxjp/ui/general";
+
+const schema = z.object({
+  name: z.string().min(1, "Bắt buộc"),
+  email: z.string().email("Email không hợp lệ"),
+});
+
+type Values = z.infer<typeof schema>;
+
+export function CreateCustomerForm({ onSubmit }: { onSubmit: (v: Values) => void }) {
+  const form = useZodForm(schema, { defaultValues: { name: "", email: "" } });
+
+  return (
+    <FormRoot form={form} onSubmit={onSubmit}>
+      <FormFieldControl name="name" label="Tên" required>
+        {(field) => <Input {...field} value={String(field.value ?? "")} />}
+      </FormFieldControl>
+      <FormFieldControl name="email" label="Email" required>
+        {(field) => <Input {...field} type="email" value={String(field.value ?? "")} />}
+      </FormFieldControl>
+      <Button type="submit">Lưu</Button>
+    </FormRoot>
+  );
+}
+```
+
+## API
+
+| Export             | Prop type                                 | Purpose                                |
+| ------------------ | ----------------------------------------- | -------------------------------------- |
+| `useZodForm`       | `ZodSchemaProp` + `UseZodFormOptionsProp` | Hook — injects zodResolver             |
+| `FormRoot`         | `FormRootProp`                            | FormProvider + `<form onSubmit>`       |
+| `FormFieldControl` | `FormFieldControlProp`                    | Controller + FormField + error display |
+
+## Forbidden
+
+- ❌ `useForm()` without Zod resolver
+- ❌ `useState` for form field values in admin pages
+- ❌ Manual validation with `if (!email.includes('@'))`
+- ❌ Yup, Valibot, or other schema libraries
+- ❌ Uncontrolled forms without schema
+
+## App dependencies
+
+Each app `package.json` must include:
+
+```json
+{
+  "dependencies": {
+    "react-hook-form": "^7.76.0",
+    "zod": "^4.4.3",
+    "@hookform/resolvers": "^5.2.2"
+  }
+}
+```
+
+Peer-enforced by `@godxjp/ui`.
+
+## Server error bags — `Form errors` + `FormField name` + `<FormErrors />`
+
+Server-driven forms (Inertia's `useForm`) return a Laravel error bag whose keys may include
+**hidden/derived fields** (`action_mode`, `page`, a source-record id) that no visible field can
+display — without a summary the submit fails silently. Pass the WHOLE bag once and let fields
+claim their own keys:
+
+```tsx
+import { Form, FormErrors, FormField, Input } from "@godxjp/ui/data-entry";
+import { useForm } from "@inertiajs/react";
+
+const form = useForm({ customer_nm: "", action_mode: "regist" });
+
+<Form asChild layout="horizontal" labelWidth={140} errors={form.errors}>
+  <form onSubmit={submit}>
+    <FormErrors />
+    <FormField name="customer_nm" label="顧客名" required>
+      <Input
+        value={form.data.customer_nm}
+        onChange={(e) => form.setData("customer_nm", e.target.value)}
+      />
+    </FormField>
+  </form>
+</Form>;
+```
+
+- A `FormField name="…"` resolves its message from `errors[name]` automatically (an explicit
+  `error` prop wins; a `string[]` entry surfaces its FIRST message — `$errors->first()`), and
+  **claims** the key.
+- `<FormErrors />` renders only the **unclaimed** remainder as a destructive `Alert`
+  (`role="alert"`, localized default title) — and nothing when every entry is claimed.
+- Never hand-filter the bag per page; that except-list is exactly what this mechanism removes.
+- `FormFieldControl` forwards its `name`, so `FormRoot` + adapter fields claim their keys too;
+  give `<FormErrors errors={form.errors} />` the bag explicitly when there is no surrounding
+  `Form errors`.
+
+### Sibling Forms — one bag over several Card+Form sections
+
+An edit screen split into several sibling `Card` + `Form` sections still has ONE server bag.
+Wrap the region in `FormErrorsProvider` instead of passing `errors` to each Form — a Form
+**without** its own `errors` joins the surrounding registry, so claims from every section
+subtract from the same `<FormErrors />`:
+
+```tsx
+import { Form, FormErrors, FormErrorsProvider, FormField, Input } from "@godxjp/ui/data-entry";
+
+<FormErrorsProvider errors={form.errors}>
+  <FormErrors />
+  <Card>
+    <Form layout="horizontal" labelWidth={170}>
+      <FormField name="customer_nm" label="顧客名">
+        …
+      </FormField>
+    </Form>
+  </Card>
+  <Card>
+    <Form layout="horizontal" labelWidth={170}>
+      <FormField name="mail_subject" label="件名">
+        …
+      </FormField>
+    </Form>
+  </Card>
+</FormErrorsProvider>;
+```
+
+A nested Form **with** its own `errors` starts a new registry that shadows the provider — its
+claims and messages stay inside it (use this for an embedded sub-form with a separate bag).

package/docs/FRAME-A11Y-CI.md

@@ -0,0 +1,267 @@
+# Per-frame accessibility & coverage CI
+
+They render every catalog frame in real Chromium and hold the line on accessibility, responsive geometry and contract coverage. Static checks (`audit:examples`, source regexes) cannot see rendered colour/layout/ARIA — these gates do.
+
+## The three gates
+
+| Script                        | `pnpm`                 | Drives                                                                          | Blocking?                                                                |
+| ----------------------------- | ---------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `scripts/check-frame-axe.mjs` | `check:frame-axe`      | axe over **every frame** at desktop 1440×900 + mobile-sm 375×667                | **Preview-chrome: yes.** Component/demo: allowlisted (regression = fail) |
+| `scripts/frame-geometry.mjs`  | `check:frame-geometry` | overflow + clipped-control sweep across **320·375·390·768·1024·1280·1440·1920** | Allowlisted (regression = fail)                                          |
+| `scripts/frame-coverage.mjs`  | `check:frame-coverage` | component-inventory ↔ frame ↔ contract-axis cross-check (browser-free)          | Report-only (`--strict` fails on any zero-frame component)               |
+
+`check:frame-geometry` works identically for responsive overflow (see its own header comment); `check:frame-coverage` is covered briefly at the end and fully in [FRAME-COVERAGE-STANDARD.md](./FRAME-COVERAGE-STANDARD.md).
+
+### What geometry counts as a "clipped control"
+
+A control the **user cannot bring into the frame** — not merely one whose box currently sticks out. Everything inside a deliberately scrollable surface sticks out by design (a `DataTable`'s `.ui-data-table-scroll` at 320px, a `FilterBar overflow="scroll"` strip, a tabs list), and those controls are reachable: a control entirely out of the scrollport is scrolled fully in the moment it takes keyboard focus, and a partially visible one keeps its focus ring on screen (Chromium's `CenterIfNeeded` focus alignment does not move a partially visible target — browser behaviour, and still inside 2.4.7 / 2.4.11 AA). So an out-of-frame focusable is re-probed: the sweep scrolls **only** its user-scrollable ancestors (computed `overflow: auto|scroll|overlay` that actually has scroll room — never `hidden`/`clip`, which no user can scroll) and re-measures.
+
+## Why a per-frame gate, not the old hand-picked checks
+
+- `check:contrast` (`scripts/check-contrast.mjs`) — a hand-picked set of ~6 pages checked for WCAG-AA text contrast. It never saw the other ~100 component frames. - `audit:examples` (`pnpm audit docs`) — a static source-regex linter. It can catch a hard-coded hex value but cannot see what actually renders: computed contrast, DOM landmark structure, focus order, or anything a Radix portal produces at runtime.
+
+## Chrome vs component: two independently-tracked scopes
+
+`check:frame-axe` runs axe **twice** per frame/viewport:
+
+- **Preview chrome** = the zoom / dimension **toolbar** (`.demo-block-toolbar`, `preview/src/demo-block.tsx`). We own this. It **must be 0** — a chrome violation fails the build.
+
+## The component allowlist — and how it shrinks to zero
+
+`scripts/frame-axe.baseline.json` is the allowlist of **pre-existing** component violations, keyed `frame → [axe-rule-id]` — the **set of violation types** still firing on each frame (union across desktop + mobile). We key on rule _presence_, not exact node counts, because axe counts jitter run-to-run as a Radix portal (Dialog/Popover/Sheet) opens or closes — an exact-count gate would be flaky. `--update-baseline` unions **two passes** by default (`AXE_RUNS`) so an intermittently-mounted overlay is captured.
+
+- **fails** if a frame gains a rule **not** in its baseline set (a genuinely new violation type);
+- **passes** rule sets equal to or a subset of baseline, printing exactly what remains (nothing hidden);
+
+The baseline can **only shrink**.
+
+```sh
+git pull                                   # get the merged component fixes
+pnpm check:frame-axe --update-baseline     # re-snapshot: rule sets only shrink
+git add scripts/frame-axe.baseline.json && git commit -m "chore(a11y): tighten frame-axe baseline"
+```
+
+There is **no blanket suppression**: a documented axe false positive would be an explicit per-rule entry with a comment, never a mute.
+
+`0` chrome violations, `0` regressions. See [Remaining baseline debt](#remaining-baseline-debt--the-12-frames) below for exactly what's left and the path to zero.
+
+## Running it locally
+
+### Prerequisites
+
+`playwright` and `@axe-core/playwright` are **optional peers** — `check:frame-axe` detects a missing/unbuilt peer and skips with a warning instead of failing the build (so a browser-less environment, e.g. a docs-only contributor, never gets blocked). To actually run it:
+
+```sh
+pnpm install
+pnpm exec playwright install chromium        # local dev — downloads Playwright's managed Chromium
+# CI uses: pnpm exec playwright install --with-deps chromium (adds OS-level deps)
+```
+
+`frame-harness.mjs` looks for a Chromium binary at `PLAYWRIGHT_CHROMIUM_EXECUTABLE`, defaulting to a **CI-only** path (`/opt/pw-browsers/chromium-1228/chrome-linux64/chrome`). That path won't exist on a laptop — when it's absent the harness falls back to Playwright's own managed browser (from `playwright install` above), so a plain local checkout works without setting anything.
+
+### Commands
+
+| Command                                             | What it does                                                                                      |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `pnpm check:frame-axe`                              | The gate: 1 pass over every frame × 2 viewports, compares to the baseline, exits non-zero on fail |
+| `AXE_FRAMES_LIMIT=8 pnpm check:frame-axe`           | Quick local smoke — only the first 8 frames (manifest order)                                      |
+| `pnpm check:frame-axe --format json`                | Machine-readable result on stdout (same exit-code semantics) — no colored human report            |
+| `pnpm check:frame-axe --update-baseline`            | Regenerate the allowlist (2-pass union by default) — see below                                    |
+| `AXE_RUNS=3 pnpm check:frame-axe --update-baseline` | More union passes, for a component with flaky portal timing                                       |
+| `pnpm check:frame-axe http://localhost:6008`        | Point at an already-running preview instead of building+serving one                               |
+
+If no preview server answers at the base URL (`http://localhost:6008` by default), the script builds one itself: `pnpm preview:build` then serves the static output with `vite preview` (`ensurePreviewServer` in `scripts/frame-harness.mjs`) — deterministic and stable under a long headless sweep, unlike the dev server's per-request recompilation. If a `pnpm preview` dev server (or a remote base) is already reachable, it's reused as-is and never rebuilt.
+
+### Reading the output
+
+Terminal report (human mode) has two blocks:
+
+```
+Preview-chrome axe (blocking — must be 0):
+  ✓ 0 chrome violations across all 107 frame(s).
+
+Component/demo axe (allowlisted — baseline may only shrink):
+  47 component violation node(s) remaining across 12 frame(s).
+  ✓ no new component violation types (rule-set within baseline).
+```
+
+- A **red `✗ <rule>`** under chrome is always blocking.
+- A **red `✗ N NEW violation-type(s) not in baseline`** under component means a frame gained a
+  rule the baseline didn't have — that's the actual CI failure mode for a component regression.
+- A **yellow `↓ shrink hint`** means a baseline rule no longer fires anywhere it's listed — free
+  baseline tightening available via `--update-baseline`.
+
+### Evidence JSON
+
+Every non-`--update-baseline` run writes `audit-evidence/frame-axe/frame-axe-results.json`
+(gitignored — a CI artifact, uploaded by `frame-a11y.yml` under the `frame-axe-evidence` name).
+Shape:
+
+```jsonc
+{
+  "generatedAt": "2026-07-13T00:45:34.614Z",
+  "base": "http://localhost:6008",
+  "summary": {
+    "status": "ok", // "ok" | "fail"
+    "frames": 107,
+    "viewports": ["desktop", "mobile"],
+    "chromeViolations": 0, // total chrome violation NODE count
+    "componentViolations": 47, // total component violation NODE count (reporting only)
+    "componentRegressions": 0, // rules present now but not in the baseline
+    "infrastructureErrors": 0, // frames that failed to load / axe crashed
+  },
+  "chrome": {/* rule → { impact, nodes, frames: ["<frameId>@<viewport>", …] } */},
+  "componentCurrent": {/* frameId → viewport → ruleId → node count, this run */},
+  "regressions": [/* { frame, rule } — new rules, the actual gate failure */],
+  "shrinkHints": [/* { frame, rule } — baseline rules that no longer fire */],
+  "infraErrors": [/* { frame, viewport, message } */],
+  "results": [/* per-frame { id, viewports: { desktop: { chrome, component }, mobile: {…} } } */],
+}
+```
+
+Node counts are recorded for triage but are **not** what the gate compares — the gate compares
+rule _presence_ per frame (`currentRules` vs `baseline.component[frame]`), because node counts
+jitter with portal open/close timing (see "The component allowlist" above). The evidence file does
+**not** carry the underlying axe `nodes[].any[].data` (e.g. the exact contrast ratio or CSS
+selector) — `scan()` in `check-frame-axe.mjs` only keeps `{ id, impact, nodes: v.nodes.length }`.
+To see the raw axe payload for a specific violation while triaging, run `@axe-core/playwright`
+directly against `http://localhost:6008/frame/<id>` in a small throwaway script, or use the
+Playwright Inspector / browser devtools with the `axe-core` extension against the same URL.
+
+### Regenerating / shrinking the baseline after a component fix
+
+1. Fix the root cause in the component (or the docs demo, if the violation is demo-content-only —
+   see the categories below for which is which).
+2. `pnpm check:frame-axe --update-baseline` — re-snapshots every frame's current rule set (2-pass
+   union). Frames that are now clean are **removed** from the JSON entirely; frames whose rule set
+   shrank keep only what still fires.
+3. `git diff scripts/frame-axe.baseline.json` — confirm the diff is a **strict shrink** (no rule
+   should reappear on a frame that previously didn't have it — if one does, you introduced a new
+   violation, not fixed an old one).
+4. Commit the baseline alongside the fix in the same PR.
+
+`AXE_FRAMES_LIMIT` + `--update-baseline` together only touch the frames actually run — the merge
+logic in `check-frame-axe.mjs` overwrites `runFrameIds` and leaves every other frame's baseline
+entry untouched, so a scoped re-snapshot (e.g. after fixing just `Select`) never silently drops
+unrelated frames from the allowlist.
+
+## Violation categories & how each was root-caused (reference)
+
+The original #157 audit's 101-frame baseline collapsed to 12 through structural fixes, not
+whack-a-mole per-frame patches. Each category below is a pattern — recognize it the next time a
+new frame trips the same rule.
+
+| Category                                   | axe rule(s)                                                                     | Root cause                                                                                                                                                                                                                                                                                                                                                                                            | Fix pattern                                                                                                                                                                                                                                                                                                                                                                                         |
+| ------------------------------------------ | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Heading order**                          | `heading-order`                                                                 | Every docs demo nests `PageContainer`'s `<h1>` directly around sibling `<Card>` sections whose `CardTitle` defaulted to `level={3}` (`<h3>`) — skipping `<h2>` (91 frames).                                                                                                                                                                                                                           | AST codemod bumped every **top-level** `CardTitle` to `level={2}`; nested Card-in-Card titles correctly kept the `h3` default (`CardTitle`'s own jsdoc already documents this contract). Commit `030e82a`.                                                                                                                                                                                          |
+| **Landmark — main**                        | `landmark-one-main`, `landmark-no-duplicate-main`, `landmark-main-is-top-level` | `preview/src/frame-main.tsx` hardcoded a `<main>` around every frame. A story that renders its own page shell (`AppShell`/`AuthShell`, which already emit their own `<main>`) got a nested/duplicate main. Story metadata can't disambiguate — every catalog entry defaults to `layout: "fullscreen"` regardless of content.                                                                          | `FrameLandmark` (`preview/src/frame-main.tsx`) detects it **after mount**: `useLayoutEffect` checks `node.querySelector('main, [role="main"]')` — stays a plain `<div>` if the subtree already owns a main, otherwise renders the real `<main>` **tag** itself (not `role="main"` — several axe landmark checks walk ancestors by native tag name, not computed role). Commit `030e82a`, `281c8d4`. |
+| **Landmark — banner (chrome)**             | `landmark-no-duplicate-banner`                                                  | The demo toolbar was a candidate `<header>`, which resolves to an implicit `banner` landmark whenever the rendered story also provides its own (`AppShell` demos).                                                                                                                                                                                                                                    | `demo-block.tsx`'s toolbar is a plain `<div className="demo-block-toolbar">`, never a `<header>` — it's preview chrome, not page banner content (see the comment right above it in the file).                                                                                                                                                                                                       |
+| **Landmark — uniqueness**                  | `landmark-unique`                                                               | `Pagination`, `Breadcrumb` (standalone + `PageContainer`'s built-in slot), and `Carousel` each hardcoded ONE localized `aria-label` with no override. Fine for a real screen (one instance); the component-gallery docs stack several instances of the same component on one page, so same-role + same-name landmarks become indistinguishable in a screen-reader landmark list (WCAG 2.4.1 / 1.3.1). | Added an `aria-label` override prop (`PaginationProp`, `BreadcrumbProps`, `PageContainer`'s `breadcrumbAriaLabel`); every repeated docs instance now passes a distinguishing label. Also fixed `PageContainer`'s breadcrumb slot to route its label through `t()` instead of a hardcoded English `"Breadcrumb"` literal (an i18n-contract bug found in the same pass). Commit `741ccf5`.            |
+| **Scrollable region focusable**            | `scrollable-region-focusable`                                                   | An `overflow: auto`/`overflow-x: auto` container was in the tab order for mouse users but unreachable by keyboard (WCAG 2.1.1). Hit three places: `.demo-block-canvas`/`.demo-block-frame` (the preview harness's own scroll wrappers), and the `Table` primitive's/`DataTable`'s/`ScrollArea`'s overflow wrappers.                                                                                   | Add `tabIndex={0}` to the scrolling element — **no `role="region"`**: a landmark role there would break `landmark-*-is-top-level` for any story that renders its own regions (e.g. `AppShell` demos). See the inline comments in `demo-block.tsx` (`.demo-block-canvas`) and `src/components/data-display/table.tsx`. Commits `030e82a`, `8675570`.                                                 |
+| **List semantics**                         | `listitem`                                                                      | `docs/data-display/list-row.tsx` rendered two `<ListRow as="li">` siblings directly inside `CardContent` (a plain `<div>`) — axe requires an `<li>`'s parent to actually be a list container (`ul`/`ol`/`role="list"`). `ListRow`'s own jsdoc already documents `as="li"` for "when the rows are a semantic list" — the demo just hadn't supplied the wrapping list it implied.                       | Wrap the `<li>` rows in a real `<ul>` in the demo. Commit `30d22f1`.                                                                                                                                                                                                                                                                                                                                |
+| **Accessible name — button**               | `button-name`                                                                   | A `<button>` (native or a `SelectTrigger`) with no discernible text (WCAG 4.1.2).                                                                                                                                                                                                                                                                                                                     | Case-by-case: give the control real text, an `aria-label`, or route it through `FormField` (see below). Remaining `button-name` entries all trace to the `SelectTrigger`/`DataSelect` prop-forwarding gap fixed by #177 — see [Remaining baseline debt](#remaining-baseline-debt--the-12-frames).                                                                                                   |
+| **Accessible name — form control / label** | (implicit via `FormField` wiring, WCAG 1.3.1/4.1.2)                             | A control inside `FormField` was named only via `aria-labelledby`, which some AT/axe paths don't resolve as reliably as a direct name.                                                                                                                                                                                                                                                                | `FormField` (`src/components/data-entry/form-field.tsx`) now **also** injects a redundant `aria-label` mirroring the visible label text (when it's plain text), alongside its existing `aria-labelledby` wiring — belt-and-suspenders, only when the child hasn't already set its own `aria-label`. Commit `8675570`.                                                                               |
+| **Accessible name — dialog**               | `aria-dialog-name` / `aria-hidden-focus`                                        | A `role="dialog"` (Popover in `modal` mode) needs a discernible name; a modal Popover **shown open at rest** in a demo (`Popover modal defaultOpen`) also puts Radix's `aria-hide` on everything outside the portal, which can hide the page's own `<main>`/`<h1>` from the accessibility tree scan.                                                                                                  | Label the titled/modal Popover demos with `aria-label` on `PopoverContent`. The `aria-hidden-focus`/`landmark-one-main`/`page-has-heading-one` combination on an **open-at-rest modal demo** is the deferred exception — see below. Commit `8675570`.                                                                                                                                               |
+| **Color contrast**                         | `color-contrast`                                                                | `Calendar`'s selected-day ghost `<button>` kept dark text on the blue fill through hover/focus (insufficient contrast on the selected date).                                                                                                                                                                                                                                                          | Force `text-primary-foreground` on the day `<button>` through hover/focus states. Commit `8675570`. Some `color-contrast` entries remain on `text-muted-foreground` small text — tracked, not yet fixed (see below and [color-extensibility.md](./roadmap/color-extensibility.md)).                                                                                                                 |
+| **Stray heading from empty state**         | `heading-order`                                                                 | `DataTable`'s built-in empty state rendered its "no rows" message as an `<h3>` (`EmptyState`'s default `titleAs`), injecting a heading into the outline for a state message, not a section.                                                                                                                                                                                                           | `DataTable`'s empty state now renders `titleAs="p"` (plain text) — `EmptyState`/`CardTitle` both expose `titleLevel`/`titleAs` (`level`/`as` for `CardTitle`) precisely so callers can pick outline position without changing visual size. Commit `8675570`.                                                                                                                                        |
+
+## Remaining baseline debt — the 12 frames
+
+As of `frame-axe.baseline.json` (`generatedAt: 2026-07-13`), 12 frames still carry an allowlisted
+component violation. Grouped by root cause (per the tracking note in commit `8675570`):
+
+| Frame(s)                                                                                | Rule(s)                                                          | Why it's still open                                                                                                                                                                                                                                                                                                                                                                                                                               | Path to zero                                                                                                                                                                                                                                                                                                                                            |
+| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data-entry-select`, `data-entry-select-matrix`, `feedback-sheet`, `navigation-toolbar` | `button-name` (+ `feedback-sheet` also `color-contrast`)         | All four demos use `Select`/`SelectTrigger`. `#177` (merged, commit `1ef05be`) shipped the `DataSelect` prop/aria-forwarding + `SelectTrigger showIndicator` fix this was tracked against, but the axe baseline was **not re-verified/re-snapshotted** against `main` after that PR merged.                                                                                                                                                       | Run `pnpm check:frame-axe --update-baseline` on current `main`; if `#177` closed the underlying gap, these 4 entries drop out automatically. If any remain, re-triage against the current `SelectTrigger`/`FormField` DOM.                                                                                                                              |
+| `navigation-tabs`                                                                       | `color-contrast`                                                 | `#176` (merged, commit `78c1c3b`) fixed `Tabs`' scrollable-overflow + disabled-fallback selection; the `color-contrast` entry here was tracked against that same PR but likewise **not re-verified** since.                                                                                                                                                                                                                                       | `pnpm check:frame-axe --update-baseline` after confirming the fix; re-triage if it persists.                                                                                                                                                                                                                                                            |
+| `data-entry-transfer`, `feedback-sheet`                                                 | `color-contrast`                                                 | Both demos use `text-muted-foreground` on small text (`transfer.tsx:83,101,121`, `sheet.tsx:226`). This is the same **default-theme contrast tradeoff** already tracked in [`docs/roadmap/color-extensibility.md`](./roadmap/color-extensibility.md) — resolving it is a brand-colour decision (darken the token or add a dedicated `--text-muted` variant), deliberately deferred pre-release rather than shipped as an unflagged palette shift. | Land the token decision in `color-extensibility.md`, then re-run `--update-baseline`.                                                                                                                                                                                                                                                                   |
+| `data-entry-calendar`                                                                   | `landmark-unique`                                                | `Calendar` wraps `react-day-picker` (`^10.0.1`), which renders its **own internal `<nav>`** for month navigation inside every `DayPicker` instance. The docs demo renders 4 `Calendar` instances on one page (each with a distinguishing container `aria-label`, but the _nested_ `nav` isn't currently overridable through this wrapper's `classNames` config) — 4 identical unnamed `nav` landmarks on one page.                                | Needs either upstream `react-day-picker` support for a per-instance nav label, or wrapping its nav slot with a custom, labelled replacement in `src/components/data-entry/calendar.tsx`.                                                                                                                                                                |
+| `layout-split-pane`                                                                     | `landmark-unique`                                                | `SplitPane` (`src/components/layout/split-pane.tsx`) renders a bare `<aside className="ui-split-pane-aside">` with **no `aria-label` prop at all**. `docs/layout/split-pane.tsx` renders 4 `SplitPane` instances on one page → 4 identical unnamed `complementary` landmarks.                                                                                                                                                                     | Add an `aria-label`/`asideAriaLabel` override prop to `SplitPane`, same pattern as `Pagination`/`Breadcrumb` (commit `741ccf5`), then give each docs instance a distinguishing label.                                                                                                                                                                   |
+| `data-display-popover`                                                                  | `aria-hidden-focus`, `landmark-one-main`, `page-has-heading-one` | `docs/data-display/popover.tsx` (line ~198) renders `<Popover modal defaultOpen>` — a modal Popover **shown open at rest** so the demo illustrates the modal behavior without a click. Radix's modal mode `aria-hide`s everything outside the portal while open, which hides the frame's own `<main>`/`<h1>` from axe's accessibility-tree scan (and leaves focusable content behind the hidden boundary).                                        | Either stop shipping this specific demo `defaultOpen` (illustrate modal-ness a different way, e.g. a screenshot/GIF or a "click to open" note) or accept it as a **known, deliberate** demo-only artifact of showing a Radix modal-trap mid-interaction and add a per-rule documented exception (not a blanket mute) once the maintainers decide which. |
+| `layout-resizable-panel`                                                                | `scrollable-region-focusable`                                    | `docs/layout/resizable-panel.tsx:72` — a demo panel with an inline `style={{ overflowY: "auto" }}`, added directly in the doc content, not through a primitive that already carries the `tabIndex={0}` fix.                                                                                                                                                                                                                                       | Add `tabIndex={0}` to that panel's `<div>` in the docs demo (same fix pattern as `.demo-block-canvas`/`Table`, just not yet applied to this hand-rolled demo wrapper).                                                                                                                                                                                  |
+| `navigation-breadcrumb`                                                                 | `scrollable-region-focusable`                                    | `docs/navigation/breadcrumb.tsx:89,95` — two `<pre className="overflow-x-auto">` code-snippet blocks rendered directly in the demo body (not the footer "View code" panel, which is disabled in frame mode).                                                                                                                                                                                                                                      | Add `tabIndex={0}` to the `<pre>` elements in the docs demo.                                                                                                                                                                                                                                                                                            |
+| `navigation-pagination`                                                                 | `scrollable-region-focusable`                                    | This one is a **real component gap**, not docs-only: `.ui-pagination-list` (`src/styles/layout.css`, the `#153`/`#165` no-wrap pagination CSS) sets `overflow-x: auto` so the page-number strip scrolls instead of wrapping to a second line — but `PaginationContent`'s `<ul>` (`src/components/navigation/pagination.tsx`) never received a `tabIndex={0}` to match.                                                                            | Add `tabIndex={0}` to `PaginationContent`'s `<ul>` in `pagination.tsx` (mirrors the `Table`/`ScrollArea` fix), then `--update-baseline`.                                                                                                                                                                                                                |
+
+Overall rule histogram across the 12 frames: `button-name` ×4, `color-contrast` ×3,
+`scrollable-region-focusable` ×3, `landmark-unique` ×2, `aria-hidden-focus` ×1,
+`landmark-one-main` ×1, `page-has-heading-one` ×1 (the last three all on the same
+`data-display-popover` frame).
+
+**Fastest path to a fully green baseline:** re-run `pnpm check:frame-axe --update-baseline` on
+current `main` first (it's plausible `#176`/`#177` already closed 5 of the 12 entries and nobody's
+re-snapshotted since) — then tackle the remaining `SplitPane`/`Calendar` landmark props, the two
+docs-only `tabIndex` additions, the one real `pagination.tsx` `tabIndex` fix, the muted-foreground
+token decision, and finally decide the modal-Popover-at-rest exception.
+
+## Infra frame modes (issue #163)
+
+Any `/frame/<id>` accepts query params (implemented in `preview/src/frame-main.tsx`) so a route can
+be exercised across contract axes without editing per-component example content:
+
+| Param     | Values                                  | Effect                                                    |
+| --------- | --------------------------------------- | --------------------------------------------------------- |
+| `dir`     | `ltr` \| `rtl`                          | flips logical CSS for the whole subtree (global RTL mode) |
+| `density` | `compact` \| `default` \| `comfortable` | drives `AppProvider` density                              |
+| `theme`   | `light` \| `dark`                       | drives `AppProvider` theme                                |
+| `locale`  | `ja` \| `vi` \| `en` \| `ar` …          | drives `AppProvider` locale (BCP-47)                      |
+
+Example: `/frame/data-entry-select?dir=rtl&density=compact&theme=dark`.
+
+`check:frame-axe` itself always runs the default chrome (`ltr`/`default`/`light`/`ja`) — these
+params are for manual/exploratory testing (e.g. checking a component under RTL + dark in a real
+browser), not currently swept by the automated gate.
+
+## Coverage tracker
+
+`check:frame-coverage` reads the public inventory (`mcp/src/data/components.ts`), the frames that
+exist (`docs/` tsx), and the declared ledger (`preview/frame-coverage.ledger.json`), then emits
+`docs/FRAME-COVERAGE-REPORT.md` + `audit-evidence/frame-coverage/coverage.json`. Every contract axis
+is `covered` / `N/A:<reason>` / **`UNTESTED`** — a missing axis is never a silent pass. Those axes
+are rolled up from the 14 contract dimensions the ledger tracks per export.
+
+`check:frame-coverage-ledger` is the enforcing gate: it regenerates the ledger from the real public
+surface, recomputes every dimension from the evidence, and fails on regression (coverage falling, a
+new export with no frame, a weakened viewport matrix, a growing geometry/axe baseline). Dimension
+totals climb toward full coverage (the #163 exit criterion). See
+[FRAME-COVERAGE-LEDGER.md](./FRAME-COVERAGE-LEDGER.md) and
+[FRAME-COVERAGE-STANDARD.md](./FRAME-COVERAGE-STANDARD.md).
+
+## Adding a new component/frame without regressing the gate
+
+Before opening a PR that adds or meaningfully changes a `/frame/**` example:
+
+1. **Give every top-level `Card` a `CardTitle level={2}`** when the frame sits directly under a
+   `PageContainer` (`<h1>`) — nested Card-in-Card titles keep the `h3` default. Skipping this
+   reintroduces `heading-order`.
+2. **Don't hand-roll a scroll container.** If a demo needs `overflow: auto`/`overflow-x: auto`,
+   add `tabIndex={0}` to the scrolling element and do **not** add `role="region"` (that turns it
+   into a landmark and can trip `landmark-*-is-top-level` for stories with their own regions).
+   Prefer reusing `Table`/`DataTable`/`ScrollArea`, which already carry this.
+3. **Stacking more than one instance of a landmark-owning component** (`Pagination`, `Breadcrumb`,
+   `SplitPane`'s `aside`, custom `<nav>`/`<aside>`/`<section aria-label>`) **on one page** — give
+   each instance a distinguishing `aria-label` (use the `aria-label`/`breadcrumbAriaLabel` override
+   props already on `Pagination`/`Breadcrumb`/`PageContainer` where they exist), or the frame trips
+   `landmark-unique`.
+4. **`<li>` needs a real list parent.** `ListRow as="li"` (or any bare `<li>`) must be inside a
+   `<ul>`/`<ol>`/`role="list"` container, never a plain `<div>`.
+5. **Every interactive control needs a discernible name.** Route form controls through `FormField`
+   (it injects both `aria-labelledby` and a redundant `aria-label`); give icon-only buttons/triggers
+   an explicit `aria-label`.
+6. **A `role="dialog"` (Popover `modal`, custom dialogs) needs a name**, and avoid shipping a demo
+   with a **modal** dialog `defaultOpen`/open-at-rest unless you've checked what it hides from the
+   rest of the page (see the `data-display-popover` entry above) — prefer "click to open."
+7. **Run the gate before pushing:** `pnpm exec playwright install chromium` (once) then
+   `AXE_FRAMES_LIMIT=<n> pnpm check:frame-axe` scoped to your new/changed frame(s), or the full
+   `pnpm check:frame-axe` if you have time. A brand-new frame with **zero** violations needs no
+   baseline entry at all — it's only added if you're knowingly landing a pre-existing violation
+   that a follow-up will fix (and even then, prefer fixing it before merge).
+8. If you do land a frame with a tracked violation, add it to `scripts/frame-axe.baseline.json` via
+   `--update-baseline` (never hand-edit the JSON) and note _why_ + the follow-up issue in the PR
+   description — the baseline file's own `note` field explains it may only shrink from here.
+9. Register the case you authored in `preview/frame-coverage.ledger.json` so
+   `check:frame-coverage-ledger` stops reporting that dimension `UNTESTED`. You **cannot** hand-write
+   a verdict — add an entry to the ledger's `cases` array (frame path + case heading + resolvable
+   evidence paths + reviewer + HTTPS review link + ISO timestamp) and run
+   `pnpm gen:frame-coverage-ledger`; the gate recomputes every cell from that evidence and rejects
+   any verdict it cannot reproduce. See [FRAME-COVERAGE-LEDGER.md](./FRAME-COVERAGE-LEDGER.md) and
+   [FRAME-COVERAGE-STANDARD.md](./FRAME-COVERAGE-STANDARD.md).