@godxjp/ui 31.31.7 → 32.0.0

package/docs/DEVELOPMENT.md

@@ -1,269 +0,0 @@
-# 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 — scope the checks to the DIFF
-
-> **Read §5.0 before you run anything.** This section was rewritten after the owner watched a
-> two-file change take six minutes of gates and asked, correctly, _"bản chất chỉ sửa rất ít, check
-> diff đéo được hay sao? có phải release đâu mà run hết thế?"_ — it is not a release, so stop
-> running a release's worth of checks.
-
-### 5.0 MEASURE FIRST, THEN COMPLAIN — the real cost table
-
-Every number below was measured on this repo, on an M-series Mac, warm. **Measure again before you
-believe them; a cost you assumed is how you end up optimising the wrong thing.**
-
-| command                    | cost            | scope                                      |
-| -------------------------- | --------------- | ------------------------------------------ |
-| `check:token-tiers`        | **0.2s**        | whole repo                                 |
-| `audit`                    | **0.5s**        | whole repo (~600 files)                    |
-| `typecheck:docs`           | **0.7s**        | whole `docs/` program                      |
-| `typecheck`                | **1.3s**        | whole `src/` program                       |
-| `build`                    | **1.5s**        | whole package                              |
-| `preview:build`            | **1.9s**        | whole preview                              |
-| `lint`                     | **12.9s**       | whole repo                                 |
-| **`check:frame-overflow`** | **52s** (was 339s before it was parallelised, gh#851) | **199 frames x 2 viewports, in a browser** |
-
-**The lesson is the opposite of the intuition.** "Typecheck the whole system" sounds wasteful and
-costs **1.3 seconds** — typescript-7 is the native compiler, there is nothing to save there, and
-scoping it to changed files would cost more in ceremony than it saves in wall clock. Meanwhile the
-one command that _does_ cost real time is the browser sweep, and it is the one that looks innocent
-in a shell script.
-
-`check:frame-overflow` alone was **~96% of the wall clock** of a full local pass. It ran all 398
-navigations down a SINGLE page, in series. It now runs a pool of one page per core (capped at 8):
-**339s -> 52.3s, 6.5x**, byte-identical output, and a planted overflow is still caught at both
-viewports by both. `FRAME_CONCURRENCY=1` restores the serial run for debugging.
-
-> **Never argue about the cost of a gate you have not timed.** Time it:
-> `st=$(date +%s); pnpm <gate> >/dev/null 2>&1; echo $(( $(date +%s) - st ))s`
-
-### 5.1 What to run, by what you touched
-
-Find the row that matches your diff. Run that row. Do not run the rows below it.
-
-| you changed                        | run                                                                                              | why                                                       |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
-| a `.css` file only                 | `audit` · `check:token-tiers` · the component's own tests · `check:frame-overflow --only <slug>` | no TS changed, so `typecheck` has nothing to say          |
-| a `.tsx`/`.ts` in `src/`           | `typecheck` · `lint` · `audit` · that group's tests                                              | 1.3s + 12.9s, both worth it                               |
-| a file in `docs/`                  | `typecheck:docs` · `audit` · `check:example-imports`                                             | `typecheck` covers `src/`, not `docs/`                    |
-| a token in `src/tokens/`           | + `check:token-tiers` · `src/tokens/__tests__` · `pnpm regen` twice (gh#847)                     | frozen tier tables go stale instantly                     |
-| a public export / prop             | + `pnpm ship:surface`                                                                            | 8 stacked generators; the list is derived, not remembered |
-| anything that moves LAYOUT         | `check:frame-overflow --only <slug>` while you work; the FULL sweep once, before the PR          | 17.5s vs 339s                                             |
-| opening the PR / cutting a release | the full sweep, `verify:ci:static`, the full suite in CI                                         | the only place "run everything" is right                  |
-
-### 5.2 `--only` — the diff-scoped browser sweep
-
-Added in gh#851 for exactly this. The sweep had no filter at all: 199 frames or nothing.
-
-```bash
-pnpm check:frame-overflow --only table                       # 9 frames,  17.5s
-pnpm check:frame-overflow --only '/^data-entry-(switch|segmented)/'   # 3 frames
-pnpm check:frame-overflow                                    # all 199,   52s
-```
-
-Measured: `--only table` is **17.5s against the full sweep's 52.3s**. Both matter — the pool cut
-the full sweep 6.5x, and `--only` cuts what is left to the frames a diff can actually reach.
-
-Two guards, both deliberate:
-
-- **`--only` refuses `--update-baseline`.** A partial sweep does not know whether the frames it
-  skipped are still clean, and recording that as the whole truth is how a baseline stops meaning
-  anything. Rebaselining needs the full sweep.
-- **Its success line says `PARTIAL, not a release gate`** and prints how many frames it skipped, so
-  a filtered green can never be pasted into a PR as if it were the real thing.
-
-### 5.3 The commands, for reference
-
-```bash
-pnpm lint                 # eslint — self-contained flat config                    12.9s
-pnpm typecheck            # tsc --noEmit over src/                                  1.3s
-pnpm typecheck:docs       # tsc --noEmit over docs/                                 0.7s
-pnpm audit                # godxjp-ui-audit — 0 errors for touched files            0.5s
-pnpm check:mcp-sync       # MCP registry <-> library export drift guard
-pnpm vitest run src/components/<group>/__tests__ --maxWorkers=2   # ONLY what you touched
-pnpm check:frame-overflow --only <slug>   # the frames your change can reach       ~18s
-pnpm check:frame-overflow                 # all 199 — pre-PR and CI only             52s
-pnpm preview:build        # integration test: examples + docs must build            1.9s
-pnpm test                 # FULL suite — CI only, never from an agent loop
-pnpm check:frame-axe      # WCAG 2.2 AA over every frame — LOCAL ONLY, never in CI (FRAME-A11Y-CI.md)
-```
-
-`pnpm verify` and `pnpm verify:release` run these together (verify:release also builds) — **both include the full suite, so both belong to CI.** Locally, run them at most once immediately before opening a PR, never inside an edit loop and never while other agents are working on the same machine. 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.
-
-### Reproducing one screen at one width — the frame routes
-
-Three gates and every bug report start here, so the addressing is written down rather than guessed
-(godx-jp/id#639 burned three attempts on `?frame=…`, which is not a thing):
-
-```
-pnpm preview                                  # :6008
-http://localhost:6008/isolate/<id>            # the demo ALONE, at the real viewport — measure here
-http://localhost:6008/frame/<id>              # the same demo inside the device-preset chrome
-```
-
-`<id>` is the demo's path under `docs/`, minus `.tsx`, with `/` turned into `-`:
-`docs/layout/topbar.tsx` → `layout-topbar`, `docs/data-entry/date-picker.tsx` → `data-entry-date-picker`.
-A file may override it with a `slug` in its frontmatter. Both routes accept
-`?dir=rtl&density=compact&theme=dark&locale=ja`; `/frame/**` additionally takes `?preset=`/`?w=`/`?h=`/`?zoom=`.
-
-For an axe measurement at a given width, drive `/isolate/<id>` with Playwright at that viewport —
-that is what `scripts/topbar-collision-visual.mjs` and the other `test:visual:*` gates do.
-
-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 (**local only, never in CI**) + geometry + coverage gates.
-- **`godx-ui-component-placement`** skill — decide whether a component belongs here.

package/docs/FRAME-A11Y-CI.md

@@ -1,287 +0,0 @@
-# Per-frame accessibility — `check:frame-axe` (LOCAL ONLY)
-
-One ruler, run in the repository that owns the CSS — **on a developer machine, never in CI/CD.**
-
-> **Owner's standing rule (2026-09-17): axe must not run in any GitHub Actions workflow.** It is a
-> local measurement only. gh#643 had wired it into `ci-browser.yml` (four shards on every merge) and
-> `ci-browser-full.yml` (nightly); both jobs are removed. `check:gate-coverage` lists
-> `check:frame-axe` as EXEMPT with this reason, so its absence from the workflows is a declaration,
-> not a dead gate. **Do not re-wire it into a workflow.** The file keeps its historical name so
-> existing links still resolve.
-
-## Why it exists (gh#643)
-
-`scripts/visual-audit.mjs` carries **eight** rules. A consumer's nightly runs `@axe-core/playwright`
-with **68**. Six of our eight are design-language opinions with no axe equivalent —
-`oversaturated-accent`, `sibling-card-gap`, `row-content-starved`, `emoji-rendered`,
-`alert-controls-misplaced`, `css-layers-missing` — and a design system **should** own those. The
-other sixty (names, roles, `aria-*`, contrast, focus order, target size) were checked **nowhere in
-this repository**, and only in a consumer that cannot fix the CSS, because the CSS is here.
-
-gh#639 is what that costs. A topbar shipped; every gate here said green; `target-size` failed in
-`godx-jp/id`'s nightly at 320px. And our own `target-size-min` could not have caught it at any
-threshold — it measures a **painted box**, and that failure was an **obscured** target (axe:
-`partiallyObscured`, 8×28). Two rulers, and the disagreement only ever surfaces downstream.
-
-## What it does
-
-```bash
-pnpm check:frame-axe                       # every frame, 3 viewports
-pnpm check:frame-axe -- --update           # rewrite the baseline
-pnpm check:frame-axe -- --scope=showcase   # the 30 whole-page frames only, 30s
-pnpm check:frame-axe -- /isolate/layout-topbar   # one route, while fixing
-```
-
-|           |                                                                                   |
-| --------- | --------------------------------------------------------------------------------- |
-| tool      | `@axe-core/playwright`                                                            |
-| tags      | `wcag2a` · `wcag2aa` · `wcag21aa` · `wcag22aa` — **the consumer's set, verbatim** |
-| routes    | every `/isolate/<id>` in `window.__STORY_MANIFEST__` + every `/showcase/<id>`     |
-| viewports | 1440×900 · 375×667 · **320×568**                                                  |
-| states    | as rendered, **plus** one overlay OPEN on the routes that declare `data-axe-open` |
-
-320 is not decoration: it is WCAG 2.2 SC 1.4.10's reflow width, it is the width the consumer's
-nightly runs, and it is the width gh#639 failed at while 390 passed.
-
-Showcases are included on purpose. They are the only frames here shaped like a real screen — a whole
-page, a landmark tree, a focus order — which is precisely the class the component frames cannot
-reach and the consumer has been carrying alone.
-
-## The overlay scope — opening the thing before measuring it
-
-A menu, dialog, listbox or popover that is closed at rest **paints nothing**. Every axe rule whose
-condition only exists while one is open was therefore outside this gate's field of view, not passing
-it. The gate shipped in 24.1.0 without this half; it is back (gh#643 item 4), rebuilt from the
-version #492 deleted.
-
-A demo opts in **declaratively**, from the demo itself:
-
-```tsx
-// the trigger, when it forwards DOM props
-<DialogTrigger asChild>
-  <Button data-axe-open size="sm">仕訳新規作成</Button>
-</DialogTrigger>
-
-// the region that owns it, when the component renders its own trigger
-<CardContent data-axe-open>
-  <FormField id="status" label="状態"><Select … /></FormField>
-</CardContent>
-
-// right-click, for the gesture nothing else reaches
-<Button data-axe-open="contextmenu" variant="outline">…</Button>
-```
-
-What the gate then does, per route/viewport, **after** the default-state scan (opening an overlay is
-destructive to the state that scan measures):
-
-1. Take the **first** `[data-axe-open]` on the page. No declaration ⇒ the route skips this entirely
-   and costs nothing.
-2. Press **Escape** up to three times while any overlay is mounted. Several demos deliberately
-   render one open at rest (`popover`'s anchored panel, `dropdown-menu`'s `defaultOpen` card), and a
-   modal one makes the rest of the page unreachable. Dismissing first also makes the measurement a
-   real **closed → open** transition rather than whatever the demo happened to leave mounted.
-3. Resolve the click target: the declaring element itself when it matches
-   `button, [role=button], [role=combobox], [role=menuitem], a[href], summary`, otherwise the first
-   such control inside it. (`Select` and `DatePicker` own their trigger DOM and forward no `data-*`
-   to it — hence the declare-on-the-region form. `DatePicker`'s combobox `<input>` is what opens the
-   calendar, and it is what gets pressed.)
-4. Click (or right-click), then wait until **one more** overlay is mounted
-   (`[data-radix-popper-content-wrapper], [role=dialog], [role=alertdialog], [role=menu],
-[role=listbox]`) — never a bare timer.
-5. Scan again, and key the rows `@<viewport>+open`:
-
-```
-/isolate/data-entry-select-matrix @1440+open aria-required-children
-```
-
-**A declaration whose overlay never opens is a gate FAILURE**, recorded as `overlay-did-not-open`
-and red on the spot. A broken declaration otherwise reads exactly like a clean frame, which is the
-one thing this scope exists to prevent.
-
-**Routes declaring an open step today — 7 declared, 7 open:** `data-entry-select`,
-`data-entry-select-matrix`, `data-entry-date-picker`, `data-display-popover`,
-`navigation-dropdown-menu`, `feedback-dialog`, `feedback-sheet`. (The old `navigation-context-menu`
-frame is gone — `ContextMenu` was folded into `DropdownMenu trigger={["contextMenu"]}` in v23 — so
-the right-click gesture is declared on that card of `navigation-dropdown-menu` instead.)
-
-### What it found, and the proof it has teeth
-
-**`aria-required-children`, CRITICAL, on `/isolate/data-entry-select-matrix` at all three
-viewports.** `SelectSeparator` rendered react-aria's `<Separator>`, i.e. `role="separator"`, as a
-direct child of the viewport's `role="listbox"`. ARIA 1.2 lets a `listbox` own `option` and `group`
-and nothing else. Fixed in `src/components/data-entry/select.tsx` — the divider is decoration over a
-structure the two `SelectGroup`s already announce, so it now renders `aria-hidden` with no role.
-`menu` **does** own `separator`, so `DropdownMenuSeparator` is correct as it stands. Regression test:
-`src/components/data-entry/__tests__/select-groups.test.tsx`.
-
-The control run is the part worth keeping. On the **same defective build**:
-
-| declarations | result                                                                      |
-| ------------ | --------------------------------------------------------------------------- |
-| removed      | ✓ green, `0 route(s) opened a declared overlay`                             |
-| present      | ✗ red, 3 × `aria-required-children` on `@1440+open / @375+open / @320+open` |
-
-A `data-axe-open` on a `Button` that opens nothing turns the gate red with three
-`overlay-did-not-open` rows, one per viewport.
-
-**The original 2026-09 proof no longer reproduces, and the reason matters more than the proof.** That
-commit disabled `src/components/general/inert-background.ts` and watched `aria-hidden-focus` go red
-on `select`, `dropdown-menu` and `context-menu`. Disabling it today changes nothing measurable:
-these overlays are **react-aria-components**, not Radix: react-aria inerts the background itself —
-`#root` plus three focus sentinels carry `inert` the moment a listbox opens, with no `aria-hidden`
-anywhere on them. Stripping every `inert` attribute immediately before the scan still leaves the
-page clean and `aria-hidden-focus` in axe's `passes` bucket, because that rule needs an
-`aria-hidden` ancestor to fire at all. No `src/` component imports `useInertHiddenBackground` any
-more; the only importer is the Radix parity fixture
-`src/components/data-entry/__tests__/radix-select.fixture.tsx`. So `inert-background.ts` is dead
-for `Select` and `DropdownMenu`, and the overlay scope's value is no longer the rule it was built
-for.
-
-Be careful with the stronger version of that claim, because the first draft of this paragraph made
-it and it is false: `data-aria-hidden` is **not** absent from the built preview. The `aria-hidden`
-npm package ships inside the `command` chunk (`cmdk`'s dependency tree), so the marker exists in
-the bundle even though no first-party overlay sets it. What is measured above is the narrow claim —
-`Select` and `DropdownMenu` background-inert via `inert`, not `aria-hidden` — not a repo-wide
-absence. It is still the rule class: `aria-required-children` is the same
-shape, and nothing else here could see it.
-
-### What is still outside this scope, stated rather than hidden
-
-- Only the **first** declaration per route is exercised. A route with several distinct overlays is
-  measured on one of them.
-- Only **one step deep**: submenus, an overlay opened from inside another, and the state after a
-  selection are not reached.
-- **Keyboard opening is not exercised** — the gate clicks. A trigger that opens on click but not on
-  `Enter`/`Space` passes.
-- The overlay's **focus trap and focus order** are not asserted; axe cannot see a JS focus trap.
-
-## What it found on its first run — and what came of it
-
-54 rows, **159 violation nodes**, on code that passed every other gate in this repository. Fixing
-them took it to **12 rows / 19 nodes**, and then to **0**:
-
-| rule                    | first run | now | what it was                                                                                                                              |
-| ----------------------- | --------: | --: | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `color-contrast`        |        62 |   0 | text under 4.5:1 (SC 1.4.3)                                                                                                              |
-| `target-size`           |        28 |   0 | under 24×24 (SC 2.5.8) — `Carousel` dots, `SearchInput`'s clear button, `Attachments`' file input                                        |
-| `aria-prohibited-attr`  |        21 |   0 | `Badge`'s `aria-label` on a `generic` div — the name was dropped by every screen reader                                                  |
-| `button-name`           |        18 |   0 | **`Select`'s trigger is `role="combobox"`, which cannot be named by its contents** — every unlabelled Select shipped a nameless combobox |
-| `aria-valid-attr-value` |        18 |   0 | `aria-controls` pointing at ids that do not exist                                                                                        |
-| `aria-conditional-attr` |        12 |   0 | `aria-expanded` on a `<tr>`, which only a `treegrid` row may carry                                                                       |
-
-Four of those were LIBRARY defects, not demo slips — `Badge`, `Select`, `Carousel`, `SearchInput` —
-and the fifth produced a new vocabulary member: `tone="inherit"` on `Text` / `Heading` / `Title` /
-`Activity` / `Separator`, because every other tone is an absolute token and there was no way to put
-text on a coloured surface without fighting it.
-
-The `target-size` rows are the sharpest point about two rulers. Our own `target-size-min` was
-running on those same frames and reporting them clean, because it measures a painted box. And the
-fix axe wants is not the fix the standard wants: a centred `::after` genuinely makes the target
-24×24 — `docs/MEASUREMENT-CONTRACT.md` records that under `expanders` — but axe reads
-`getBoundingClientRect()`, which cannot see a pseudo-element. Both fixes were tried; the boxes had
-to grow.
-
-## The last twelve rows, and what each one turned out to be
-
-The table above is what the sweep found; this is what the remaining 12 rows / 19 nodes turned out
-to be once each was measured rather than reasoned about. The rows are kept, with the verdict this
-file used to carry quoted back, because four of the five were wrong: two had no diagnosis at all
-and two had one the measurement contradicted — and in both of those the guess pointed AWAY from
-this package.
-
-| rows | what                                                                                                   | the measurement, and where it was fixed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| ---: | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-|    3 | `foundation-colors` · `--success-foreground` on `--success`, `--attention-foreground` on `--attention` | Called "a PALETTE decision, an owner-level call". It was not the palette: the FILL was fine and the INK was wrong. Two of the light theme's eight fills carried a near-white ink their own lightness cannot support (2.19:1 / 3.32:1) while the sibling `--warning` had always used the near-black one on the equally pale 山吹, and the DARK theme already flipped both. `src/tokens/foundation.css`: ink only — success 2.19 → **7.08**, attention 3.32 → **4.68**. Guarded by `__tests__/status-fill-contrast.test.ts`.                                                                                                                           |
-|    3 | `case6-agency-handy` · a SELECTED `ToggleGroupItem` paints `--foreground` over `--primary`             | "Cause not yet found." Found, with `CSS.getMatchedStylesForNode`: the demo wrote `text-[var(--font-size-xs)]`, and Tailwind v4 reads a bare `var()` in `text-*` as a COLOUR — it compiled to `color: var(--font-size-xs)` in the UTILITIES layer, an invalid colour that clobbered the component's own `color: hsl(var(--primary-foreground))` in `components` and left the trigger inheriting the page ink. The component rule was right all along. Demo fix (`text-[length:var(…)]`, 10 sites in `docs/`), plus the count pill: the hand-rolled `Text` at `opacity-70` measured 2.15:1 and `ToggleGroupItem`'s own `count` prop inverts to 6.32:1. |
-|    3 | `table-view-tabs` · a `Tab`'s `aria-controls` points at a `tabpanel` that is never rendered            | A LIBRARY defect, and the composition is published: `Tabs` / `TabsList` / `TabsTrigger` are three separate exports, nothing in their types asks for a fourth, and the attribute could not be overridden (`withDomProps` puts RAC's props after the caller's). `TabsContent` now registers its value and a trigger claims a panel only when one is declared. No new public prop. `__tests__/tabs-panel-reference-643.test.tsx`.                                                                                                                                                                                                                       |
-|    2 | `futurelastic-web` @320/@375 · white ghost buttons read as 1.01:1                                      | "Probably a false positive." It was not. The tenant's `.fl-navbar-inner` was a fixed-height flex row with no wrap, so at 320 its content ran to **x=569.6 inside a 320px nav** — the links painted outside the navbar's own box, over the page behind it. A WCAG 2.2 SC 1.4.10 reflow failure reported by the contrast rule, because that is what an overflowing element looks like from the outside. Demo CSS + `Flex wrap`.                                                                                                                                                                                                                        |
-|    1 | `table-bulk-actions` @375 · `target-size`                                                              | "Not yet diagnosed." The left cluster carried `min-w-0 flex-1` — "squeeze me to nothing" — over children that refuse to shrink, so its box shrank to 113.6px while its content ran to x=462 and painted 一括承認 (264.6→360.2) under 解除 (272.3→341.0), leaving 19.2×30.2 unobscured against SC 2.5.8's 24×24. Demo: `wrap`, and no `min-w-0`.                                                                                                                                                                                                                                                                                                      |
-
-Two of the five were library defects and three were genuine demo slips — a different split from the
-first sweep, where four of five were the library's. Which is the point of writing the number down
-next to each one: "it is the demo" and "it is the palette" are both cheap to say and neither
-survived a measurement here.
-
-## The baseline is a debt ledger, not an allowlist
-
-The package did not start compliant, and a gate that fails the whole build on its first day gets
-deleted rather than obeyed. `frame-axe-baseline.json` records what was already failing when the gate
-landed, keyed one row per `(route, viewport, rule)`:
-
-```
-"/isolate/layout-topbar @320 target-size": { "count": 2, "help": "…" }
-```
-
-The gate fails on a key that is **not** in the baseline, and on a baselined key whose `count`
-**grows**. A key that stops firing is reported so it can be dropped.
-
-- **Delete rows as you fix them.** `--update` rewrites the file; the diff is the review.
-- **Never add a row by hand to turn a red build green.** That is the one move this file exists to
-  make visible.
-
-## What this gate does NOT do — stated, not hidden
-
-The gate deleted in #492 did three things this one does not. One is now back; two are still gaps:
-
-1. ~~**No overlay scope.**~~ Restored — see [the overlay
-   scope](#the-overlay-scope--opening-the-thing-before-measuring-it) above.
-2. **No chrome/component split.** The old gate held the preview toolbar to zero violations and
-   allowlisted the component scope separately. `/isolate/**` renders the demo alone, so there is
-   little chrome to separate — but `/showcase/**` is scanned whole.
-3. **No per-rule severity.** Every WCAG-tagged rule is treated alike.
-
-## Determinism
-
-Two consecutive sweeps of identical code first disagreed on five `color-contrast` rows: a fade-in
-caught mid-flight renders text at partial opacity and axe scores whatever it finds. A gate that
-disagrees with itself gets ignored, so each page is pinned before the scan —
-`reducedMotion: "reduce"`, an injected stylesheet zeroing every animation and transition duration,
-and `document.fonts.ready` (web fonts change glyph geometry, which changes which boxes overlap,
-which changes what `color-contrast` resolves a background to). Two sweeps after that: identical.
-
-## Cost
-
-|                                       |                                                                                     |
-| ------------------------------------- | ----------------------------------------------------------------------------------- |
-| full sweep                            | **2m14s** locally, with the overlay scope — 215 routes × 3 viewports                |
-| sequential                            | ~55 min — the three viewport passes run concurrently, which is the whole difference |
-| showcase only (`--scope=showcase`)    | ~30s                                                                                |
-| one route (`pnpm check:frame-axe /isolate/…`) | seconds — the loop to use while fixing                                      |
-
-The overlay pass is bounded by declaration: only the 7 declaring routes pay it (21 extra scans plus
-their open steps), and no `/showcase/**` route declares one, so `--scope=showcase` is unchanged by it.
-
-## Where it runs: your machine
-
-**Never in CI/CD** — see the rule at the top. The procedure:
-
-```bash
-pnpm build && pnpm preview:build        # the STATIC preview — not `pnpm dev` / `pnpm preview`
-pnpm check:frame-axe                    # full sweep; must end with 0 baselined entries, 0 nodes
-pnpm check:frame-axe /isolate/<frame>   # one route, while fixing
-```
-
-Run it before a PR that touches markup, ARIA, focus behaviour or colour, and commit what it writes —
-`audit-evidence/frame-axe/results.json` and, only when a full sweep genuinely changed it,
-`frame-axe-baseline.json`.
-
-**The static preview, not the dev server.** Against the vite dev server the sweep produces 1–3
-spurious `route-did-not-render` / `axe-did-not-run` rows on different routes each run — 30s
-`page.goto` timeouts while three viewport contexts hammer an on-demand-transforming server. Each is
-clean alone. The static build does not do this.
-
-**`--shard=i/n` and `--scope=` are for splitting a LOCAL run**, e.g. across two terminals. Two guards
-hold for both: `--update` refuses under either (a partial run would rewrite the ledger from a fraction
-of the frames and delete the rest), and the "no longer fires" report is suppressed on a partial run
-(every other partition's rows would read as fixed). Regenerate the baseline from a full sweep only.
-
-### What leaving CI costs, stated rather than discovered
-
-A regression is now caught when someone runs this, not on merge. Nothing in the pipeline will turn
-red on a new `aria-*` defect, a nameless button or a sub-24px target. That is the trade the rule
-makes, and the only thing that closes it is the local run above actually happening before a PR.
-
-## Related
-
-- [FRAME-COVERAGE-STANDARD.md](./FRAME-COVERAGE-STANDARD.md) — which frames must exist at all.
-- [DEVELOPMENT.md](./DEVELOPMENT.md) §5 — the `/isolate/<id>` · `/frame/<id>` addressing.