@godxjp/ui 19.1.0 → 19.2.0

package/docs/FRAME-COVERAGE-LEDGER.md

@@ -0,0 +1,123 @@
+# Frame-coverage ledger (issue #163)
+
+`preview/frame-coverage.ledger.json` is the machine-readable preview **contract**: it links every public export and compound subcomponent to a frame, and declares — per contract dimension — whether an executed case proves it, whether nothing proves it, or whether it cannot exist here.
+
+> **UNTESTED IS NOT A PASS.** The absence of a demonstrated state must never be read as support.
+> A frame rendering successfully proves the hand-picked example, nothing more.
+
+- Schema: [`frame-coverage.ledger.schema.json`](../frame-coverage.ledger.schema.json)
+- Standard: [`FRAME-COVERAGE-STANDARD.md`](./FRAME-COVERAGE-STANDARD.md)
+- Generator: `pnpm gen:frame-coverage-ledger` → `scripts/gen-frame-coverage-ledger.mjs`
+- Gate: `pnpm check:frame-coverage-ledger` → `scripts/check-frame-coverage-ledger.mjs`
+- Shared registry: `scripts/frame-coverage-contract.mjs`
+- Consumed by the MCP: `get_frame_coverage`, and appended to every `get_component` response
+
+## The three verdicts
+
+| Verdict          | Meaning                                                                         |
+| ---------------- | ------------------------------------------------------------------------------- |
+| `covered`        | An **executed** case proves this dimension. Never inferred, never hand-written. |
+| `untested`       | No executed case. **This is not a pass** — report it to users as UNTESTED.      |
+| `not-applicable` | The dimension cannot exist for this export, **with a written reason**.          |
+
+Cells are stored compactly and the reason is single-sourced in `policy.dimensions`:
+
+```
+untested
+not-applicable:api-manifest      # the generated TypeScript surface has no such prop
+not-applicable:reviewed          # a human waiver in policy.notApplicable, with a written reason
+covered:prop-evidence:variant    # every literal branch of `variant` has resolvable evidence
+covered:declared-case:<caseId>   # a reviewed entry in `cases`
+```
+
+## The 14 contract dimensions
+
+| Dimension        | Axis          | Applicable when                                   | Promoted by   |
+| ---------------- | ------------- | ------------------------------------------------- | ------------- |
+| `variants`       | visual        | the API exposes `variant`                         | prop evidence |
+| `tones`          | visual        | the API exposes `tone`                            | prop evidence |
+| `sizes`          | visual        | the API exposes `size`                            | prop evidence |
+| `shapes`         | visual        | the API exposes `shape`                           | prop evidence |
+| `density`        | visual        | the API exposes `density`                         | prop evidence |
+| `ownership`      | ownership     | a controlled/uncontrolled pair or `setApi` exists | declared case |
+| `states`         | state         | a disabled/readOnly/loading/error/… prop exists   | declared case |
+| `async`          | async         | always                                            | declared case |
+| `responsive`     | responsive    | always                                            | declared case |
+| `rtl`            | international | always                                            | declared case |
+| `contentStress`  | contentStress | always                                            | declared case |
+| `keyboard`       | accessibility | always                                            | declared case |
+| `accessibleName` | accessibility | always                                            | declared case |
+| `reducedMotion`  | preferences   | always                                            | declared case |
+
+**Applicability is derived from the real TypeScript surface** (`component-api-manifest.json`), not declared by hand — so `not-applicable:api-manifest` carries a machine-verified reason and is re-derived on every CI run. A component that GAINS a `variant` prop automatically flips that dimension from N/A to UNTESTED; it cannot rot into a false N/A.
+
+`async` is deliberately universal and never auto-N/A: per [FRAME-COVERAGE.md](./FRAME-COVERAGE.md) a blanket primitive-default not-applicable hides async-capable controls and is forbidden.
+
+## The two promotion routes
+
+**Prop evidence (automatic).** Only for the five strictly prop-shaped dimensions, where "every branch has a rendered case" _is_ the contract. `component-case-evidence.json` must enumerate every literal branch of the union and reference at least one evidence file that resolves on disk — it is already fail-closed via `pnpm audit:component-cases`. This proves the visual branch matrix **only**; it never proves responsive, RTL, keyboard, async or assistive-technology behaviour.
+
+**Declared case (reviewed).** Everything behavioural. Add an entry to the ledger's `cases` array:
+
+```jsonc
+{
+  "id": "button-responsive-matrix",
+  "export": "Button",
+  "dimensions": ["responsive"],
+  "frame": "docs/general/button/index.tsx",
+  "case": "Responsive — label truncation across the width matrix",
+  "evidence": ["src/components/general/__tests__/button.responsive.test.tsx"],
+  "viewports": [320, 375, 390, 768, 1024, 1280, 1440, 1920],
+  "verifiedBy": "your-name",
+  "verifiedIn": "https://github.com/godx-jp/godxjp-ui/pull/…",
+  "verifiedAt": "2026-07-30T00:00:00Z",
+}
+```
+
+Then run `pnpm gen:frame-coverage-ledger`. Every field must resolve: the frame file must exist, every evidence path must exist inside the repository, `verifiedIn` must be HTTPS and `verifiedAt` must be an ISO-8601 UTC timestamp. A `responsive` case must list **every** required width, and for an export flagged `embeddable` it must also list every container width.
+
+You cannot hand-write a verdict. The gate recomputes every cell from the evidence and fails on any mismatch:
+
+```
+Button.responsive: ledger says "covered:declared-case:invented" but the evidence
+recomputes to "untested" — a verdict cannot be hand-written
+```
+
+## Viewport baseline
+
+```
+320  375  390  768  1024  1280  1440  1920
+```
+
+Container widths for embeddable exports: `240 320 480 640 960`.
+
+The executed geometry sweep (`pnpm check:frame-geometry`, `scripts/frame-geometry.mjs`) is recorded in `policy.sweeps.geometry` from its shrink-only baseline: **36 frame×width failures across 12 frames**, concentrated at 320 (12), 375 (11), 390 (10) and 768 (3) — matching the ~30 the issue reported. That sweep was **not re-executed** when this ledger was authored (it needs Chromium plus a built preview), so it is recorded with its `recordedAt` date and treated as evidence of _known overflow_, never as evidence of responsive coverage. `responsive` stays UNTESTED everywhere.
+
+## The ratchet
+
+| Rule                                            | Direction                                         |
+| ----------------------------------------------- | ------------------------------------------------- |
+| per-export `covered`                            | may only **rise**                                 |
+| per-export reasoned `not-applicable`            | may only **fall**                                 |
+| total `covered`                                 | may only **rise**                                 |
+| `baseline.knownMissingFrames`                   | may only **shrink**                               |
+| geometry overflow / clipped-control failures    | may only **shrink**                               |
+| frames carrying axe violations                  | may only **shrink**                               |
+| `policy.viewports.required` / `containerWidths` | may not be trimmed                                |
+| `policy.dimensions[].promotion`                 | may not be weakened                               |
+| `policy.knownGaps`                              | may be resolved, never deleted or waived          |
+| `policy.runtimeGates`                           | may not be deleted or unwired from `package.json` |
+
+`pnpm gen:frame-coverage-ledger --reset-baseline` re-mints the floor from current reality — the same deliberate escape hatch as `frame-geometry.mjs --update-baseline`. Use it when introducing the ledger, or after a reviewed public-API change legitimately turns a dimension into a reasoned N/A.
+
+## Known gaps
+
+The issue's "Initial known gaps to encode" are locked in code (`KNOWN_GAPS` in `scripts/frame-coverage-contract.mjs`) and mirrored into `policy.knownGaps`: Button, Card, Card subcomponents, EmptyState, Progress, Carousel, DataTable, Charts and the Timeline/TreeList/PasswordStrength locale stress. They cannot be deleted, and they cannot be waived through `policy.notApplicable` — they must be **covered** or stay **UNTESTED**.
+
+## Current state — read this before quoting coverage
+
+Snapshot at the time this ledger was introduced (run `pnpm check:frame-coverage-ledger` for the live figures — they move as the public surface moves):
+
+- **273** public exports / compound subcomponents, **272** of which reach a frame (`layout/legal-document-shell` is mid-flight and recorded in `baseline.knownMissingFrames`) - **3822** dimension cells: **6 covered · 2141 UNTESTED · 1675 reasoned not-applicable** - the 6 covered cells are branch matrices promoted from `component-case-evidence.json`: `Button.variants/sizes/shapes`, `Form.density`, `QrCode.sizes`, `Tabs.variants` — nothing else in the entire library is proven by an executed case - **0** exports are fully classified across all 14 dimensions - **0** declared cases; **9/9** known gaps still open - `responsive`, `rtl`, `keyboard`, `accessibleName`, `reducedMotion`, `async` and `contentStress` are **UNTESTED for every single export** — 0/273 each
+
+Coverage is therefore **0.2%**. The contract, the gate, the ratchet and the MCP exposure are done; authoring the ~3800 frame cases is the epic that remains.

package/docs/FRAME-COVERAGE-REPORT.md

@@ -0,0 +1,140 @@
+# Frame coverage report
+
+> Generated by `scripts/frame-coverage.mjs` (issue #163). Do not edit by hand — run `pnpm check:frame-coverage`.
+> Standard: [FRAME-COVERAGE-STANDARD.md](./FRAME-COVERAGE-STANDARD.md). A missing dimension is **UNTESTED**, never a pass.
+
+- Public components: **124**
+- With ≥1 frame: **124** · zero-frame: **0**
+- Fully covered (every contract axis declared): **0**
+
+## Per-component contract axes
+
+Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
+
+| Component | Frame | visua | state | owner | conte | respo | inter | acces | prefe | async |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| PageContainer | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| Flex | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| ResponsiveGrid | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| AppShell | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| AuthShell | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| CenteredShell | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Sidebar | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Topbar | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| MasterDetail | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| SplitPane | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| ErrorSurface | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| LegalDocumentShell | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Breadcrumb | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Button | ✓ | ✓ | · | · | · | · | · | · | · | · |
+| Text | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| Heading | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| Logo | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| Reveal | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Activity | ✓ | · | N/A | N/A | · | · | · | · | · | · |
+| DataTable | ✓ | ✓ | · | · | · | · | · | · | · | · |
+| Card | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| CardContent | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| StatCard | ✓ | N/A | N/A | · | · | · | · | · | · | · |
+| ServiceLauncherCard | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Badge | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| ListRow | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| CredentialReveal | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| QrCode | ✓ | ✓ | N/A | · | · | · | · | · | · | · |
+| Descriptions | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| EmptyState | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| Progress | ✓ | ✓ | N/A | · | · | · | · | · | · | · |
+| CodeBlock | ✓ | · | N/A | N/A | · | · | · | · | · | · |
+| Prose | ✓ | · | N/A | N/A | · | · | · | · | · | · |
+| Timeline | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| Table | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| DataState | ✓ | N/A | · | N/A | · | · | · | · | · | · |
+| InfiniteQueryState | ✓ | N/A | · | N/A | · | · | · | · | · | · |
+| Form | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| FormField | ✓ | N/A | · | N/A | · | · | · | · | · | · |
+| FormErrors | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Input | ✓ | ✓ | · | · | · | · | · | · | · | · |
+| NumberInput | ✓ | ✓ | · | · | · | · | · | · | · | · |
+| SearchInput | ✓ | N/A | · | · | · | · | · | · | · | · |
+| Select | ✓ | N/A | · | · | · | · | · | · | · | · |
+| Switch | ✓ | ✓ | · | · | · | · | · | · | · | · |
+| Textarea | ✓ | ✓ | · | · | · | · | · | · | · | · |
+| Label | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Checkbox | ✓ | N/A | · | · | · | · | · | · | · | · |
+| RadioGroup | ✓ | N/A | · | · | · | · | · | · | · | · |
+| MonthPicker | ✓ | N/A | · | · | · | · | · | · | · | · |
+| MonthRangePicker | ✓ | N/A | · | · | · | · | · | · | · | · |
+| DatePicker | ✓ | N/A | · | · | · | · | · | · | · | · |
+| Dialog | ✓ | N/A | N/A | · | · | · | · | · | · | · |
+| AlertDialog | ✓ | ✓ | · | · | · | · | · | · | · | · |
+| AlertDialogRoot | ✓ | N/A | N/A | · | · | · | · | · | · | · |
+| Sheet | ✓ | N/A | N/A | · | · | · | · | · | · | · |
+| Alert | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| Banner | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| SkeletonTable | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Toaster | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Tabs | ✓ | ✓ | N/A | · | · | · | · | · | · | · |
+| Pagination | ✓ | N/A | · | · | · | · | · | · | · | · |
+| DropdownMenu | ✓ | N/A | N/A | · | · | · | · | · | · | · |
+| Steps | ✓ | ✓ | N/A | · | · | · | · | · | · | · |
+| Toolbar | ✓ | N/A | · | N/A | · | · | · | · | · | · |
+| AppProvider | ✓ | · | · | · | · | · | · | · | · | · |
+| formatDate | ✓ | · | · | · | · | · | · | · | · | · |
+| TimePicker | ✓ | N/A | · | · | · | · | · | · | · | · |
+| DateRangePicker | ✓ | N/A | · | · | · | · | · | · | · | · |
+| Cascader | ✓ | N/A | · | · | · | · | · | · | · | · |
+| TreeSelect | ✓ | N/A | · | · | · | · | · | · | · | · |
+| Transfer | ✓ | N/A | · | · | · | · | · | · | · | · |
+| Upload | ✓ | ✓ | · | · | · | · | · | · | · | · |
+| UploadCropDialog | ✓ | · | · | · | · | · | · | · | · | · |
+| ColorPicker | ✓ | N/A | · | · | · | · | · | · | · | · |
+| Slider | ✓ | N/A | · | · | · | · | · | · | · | · |
+| Calendar | ✓ | N/A | · | N/A | · | · | · | · | · | · |
+| Command | ✓ | N/A | N/A | · | · | · | · | · | · | · |
+| CheckboxGroup | ✓ | N/A | · | · | · | · | · | · | · | · |
+| Radio | ✓ | N/A | · | · | · | · | · | · | · | · |
+| Popover | ✓ | N/A | N/A | · | · | · | · | · | · | · |
+| ScrollArea | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Collapsible | ✓ | N/A | · | · | · | · | · | · | · | · |
+| TreeList | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Tooltip | ✓ | N/A | N/A | · | · | · | · | · | · | · |
+| PrefetchLink | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Avatar | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| Separator | ✓ | · | N/A | N/A | · | · | · | · | · | · |
+| Skeleton | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Toggle | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| ToggleGroup | ✓ | ✓ | · | · | · | · | · | · | · | · |
+| AspectRatio | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| Accordion | ✓ | N/A | · | · | · | · | · | · | · | · |
+| HoverCard | ✓ | N/A | N/A | · | · | · | · | · | · | · |
+| PasswordInput | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| PasswordStrength | ✓ | N/A | N/A | · | · | · | · | · | · | · |
+| InputOTP | ✓ | N/A | · | N/A | · | · | · | · | · | · |
+| Rating | ✓ | N/A | · | · | · | · | · | · | · | · |
+| TagInput | ✓ | N/A | · | · | · | · | · | · | · | · |
+| ContextMenu | ✓ | N/A | N/A | · | · | · | · | · | · | · |
+| Menubar | ✓ | N/A | N/A | · | · | · | · | · | · | · |
+| NavigationMenu | ✓ | N/A | N/A | · | · | · | · | · | · | · |
+| ResizablePanel | ✓ | N/A | · | N/A | · | · | · | · | · | · |
+| Carousel | ✓ | N/A | N/A | · | · | · | · | · | · | · |
+| AppSettingPicker | ✓ | N/A | · | · | · | · | · | · | · | · |
+| Field | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| LineChart | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| BarChart | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| CompactBarTrend | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| AreaChart | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| PieChart | ✓ | ✓ | N/A | N/A | · | · | · | · | · | · |
+| CommandPalette | ✓ | N/A | · | · | · | · | · | · | · | · |
+| TwoFactorSetup | ✓ | N/A | · | · | · | · | · | · | · | · |
+| AuthDivider | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| AuthFooter | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| AuthIdentity | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| AccountChip | ✓ | N/A | · | N/A | · | · | · | · | · | · |
+| AuthAccountSummary | ✓ | N/A | · | N/A | · | · | · | · | · | · |
+| AuthStack | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
+| OrgSwitcher | ✓ | N/A | · | · | · | · | · | · | · | · |
+| FilterBar | ✓ | N/A | · | N/A | · | · | · | · | · | · |
+| PermissionMatrix | ✓ | N/A | · | N/A | · | · | · | · | · | · |
+| BranchScopePicker | ✓ | N/A | · | · | · | · | · | · | · | · |
+| ServiceRolePanel | ✓ | N/A | · | · | · | · | · | · | · | · |
+

package/docs/FRAME-COVERAGE-STANDARD.md

@@ -0,0 +1,65 @@
+# Frame coverage standard
+
+`/frame/**` is an executable public-contract suite, not a gallery of happy-path screenshots. A component is not covered merely because one example renders. Missing cases are `UNTESTED`, never implicitly passing.
+
+## Required layers
+
+Every public component and compound subcomponent must be represented at all three layers:
+
+1. **Isolated contract** — its own props, states, content and interaction.
+2. **Composition contract** — the components it is designed to contain or be contained by.
+3. **Journey contract** — transitions across loading, success, empty, validation, error and recovery.
+
+Hooks and non-visual helpers do not need a standalone visual frame, but their observable states must appear in the frame of the component that consumes them.
+
+## Isolated contract dimensions
+
+Each applicable dimension must have a runnable case. Mark a dimension `N/A` only with a reason.
+
+| Dimension      | Required cases                                                                           |
+| -------------- | ---------------------------------------------------------------------------------------- |
+| Visual         | every `variant`, `tone`, `size`, `shape`, density and spacing mode                       |
+| State          | default, disabled, read-only, loading, empty, error, success and selected/current        |
+| Ownership      | controlled, uncontrolled and reset behavior                                              |
+| Content stress | empty, long Japanese/Vietnamese, large numbers, missing and invalid data                 |
+| Responsive     | 320, 375, 390, 768, 1024, 1280, 1440 and 1920 px; container-width cases when embeddable  |
+| International  | English, Japanese, Vietnamese and RTL stress where direction affects layout/keys         |
+| Accessibility  | accessible name, helper/error association, keyboard, focus order/return and live regions |
+| Preferences    | 200% zoom, coarse touch, reduced motion and forced/high contrast where applicable        |
+| Async          | loading, reject, retry, cancel, stale/background refresh and offline when applicable     |
+
+Do not invent props solely for a demo. A missing required capability is documented as `UNTESTED` and linked to an issue.
+
+## Composition matrix
+
+| Composition                                   | Required journey                                                                              |
+| --------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `FormField ×` every form control              | label, helper, required, client/server error, disabled/read-only and reset                    |
+| `Form × Dialog/Sheet`                         | open, validate, submit, pending, server error, success, close and focus return                |
+| `DataState × DataTable × Pagination`          | prerequisite, initial loading, data, empty, background refresh, error/retry and page boundary |
+| `Toolbar × filters × Tabs × DataTable`        | long filters, clear, no results, narrow container and keyboard traversal                      |
+| `Card × Skeleton/EmptyState/Alert`            | one owning surface; no nested-card or oversized section state                                 |
+| `AppShell × Sidebar × Topbar × PageContainer` | desktop, tablet and mobile navigation with focus restoration                                  |
+| `Provider × locale/timezone/density/theme`    | controlled changes, persistence callback, RTL and long localized content                      |
+| `Carousel/Tabs/Menu × containing surface`     | focus, escape, arrows, collision, touch and reduced motion                                    |
+
+Add a composition whenever components share state, accessible relationships, layout ownership, focus ownership or async lifecycle. Pairwise coverage is sufficient unless a defect only emerges in a larger canonical journey.
+
+## Example-writing rules
+
+1. One case answers one contract question and has a descriptive visible heading.
+2. Use real public imports; never reproduce component internals in the example.
+3. Keep deterministic data and time; never depend on a live API.
+4. Show the control that changes a state when the contract is controlled.
+5. Error and empty cases retain recovery/navigation actions when the product pattern requires them.
+6. Avoid decorative wrapper cards. The component that owns the surface owns the single border.
+7. Long-content and locale cases use meaningful strings, not repeated lorem ipsum.
+8. Accessibility assertions target computed name, description, error, role, state and focus behavior.
+9. Screenshots supplement interaction assertions; they never replace them.
+10. A frame source declares its covered contract dimensions in the coverage ledger.
+
+## CI rules
+
+Coverage reports distinguish `PASS`, `FAIL`, `UNTESTED` and `N/A`. Only an executed assertion can produce `PASS`.
+
+These rules are enforced by `pnpm check:frame-coverage-ledger` against [`preview/frame-coverage.ledger.json`](../preview/frame-coverage.ledger.json).

package/docs/FRAME-COVERAGE.md

@@ -0,0 +1,29 @@
+# Frame coverage ledger
+
+`frame-coverage.json` is the policy input. `pnpm check:frame-coverage` discovers public visual exports from component barrels, resolves each owning `/frame/<id>` source, and emits the expanded export-by-dimension ledger as JSON.
+
+The checker fails for missing frames, duplicate exports, malformed statuses, or unreasoned `untested`/`not-applicable` states. A compiled frame earns only `isolated: pass`; it does not prove responsive, RTL, accessibility, async, composition, or journey coverage.
+
+The ledger also tracks `props`, `touch`, and `screenReader` independently. Axe/DOM checks may earn `a11y: pass`, but they never imply that every prop is demonstrated, a coarse pointer works, or a real screen reader announces the intended name/state/change.
+
+## Component API evidence
+
+Route presence is not component prop coverage. `component-api-manifest.json` is generated from the actual TypeScript call signatures exported by every component barrel. It records owned props, selected inherited behavioral props, finite literal unions, and declaration sources.
+
+`component-case-evidence.json` is the only input allowed to promote `props` to `pass`. Each prop needs explicit cases and rendered/test evidence; every finite union branch must be listed. Missing, stale, or renamed props remain `untested` even when the owner page renders and passes Axe at every viewport.
+
+- `pnpm gen:component-api-manifest` after changing public component APIs;
+- `pnpm audit:component-cases` to print the exact missing component/prop/union branches;
+- `pnpm check:component-api-manifest` in CI to reject a stale API inventory.
+
+Inherited primitive behavior may be classified as pass-through only with a linked forwarding test; a nonempty prose string or the component name appearing in JSX is not evidence.
+
+Evidence references must resolve to repository files. Components promoted with `complete: true` are fail-closed: a newly added public prop, a missing literal-union branch, or a removed evidence file fails `audit:component-cases` in the static frame-contract CI job. Components without a complete evidence chain remain `untested`; partial owner-page maps never promote the export to `pass`.
+
+Add narrow per-export overrides only after evidence exists. Never convert a dimension to `pass` merely because a unit test or static demo exists.
+
+Async is intentionally `untested` by default. Every export must eventually be classified: execute its loading/error/retry/cancel/offline lifecycle, or mark it `not-applicable` with a component-specific reason. A blanket primitive-default `not-applicable` hides async-capable controls and is forbidden.
+
+## Accessibility evidence boundaries
+
+An `a11y: pass` in this ledger means the rendered frame passed automated axe checks plus the documented DOM/keyboard assertions. It does not claim testing with a real screen reader, braille display, voice control, switch control, or physical coarse-touch device. Those assistive-technology and hardware checks remain a separate manual evidence track and are currently `UNTESTED`, as also recorded in `display-runtime-evidence.json`.

package/docs/PROPS-REGISTRY.md

@@ -0,0 +1,61 @@
+# Props Registry
+
+Source of truth: `src/props/registry.ts`
+
+```ts
+import {
+  VOCABULARY_REGISTRY,
+  COMPONENT_PROP_REGISTRY,
+  PROP_ALIASES_FORBIDDEN,
+} from "@godxjp/ui/props/registry";
+```
+
+## Vocabulary props (atomic)
+
+<!-- Generated from registry — update registry.ts when adding types -->
+
+| Name                | Category    | File                | Description                             |
+| ------------------- | ----------- | ------------------- | --------------------------------------- |
+| `TitleProp`         | content     | content.prop.ts     | Primary heading                         |
+| `SubtitleProp`      | content     | content.prop.ts     | Page secondary line                     |
+| `DescriptionProp`   | content     | content.prop.ts     | Dialog/empty body                       |
+| `ExtraProp`         | content     | content.prop.ts     | Page top-right actions                  |
+| `FooterProp`        | content     | content.prop.ts     | Page bottom bar                         |
+| `PageDensityProp`   | layout      | layout.prop.ts      | Page spacing scale                      |
+| `TableDensityProp`  | layout      | layout.prop.ts      | Table row height                        |
+| `GapProp`           | layout      | layout.prop.ts      | Shared layout gap                       |
+| `ButtonVariantProp` | interaction | interaction.prop.ts | Button style                            |
+| `ButtonSizeProp`    | interaction | interaction.prop.ts | Button size                             |
+| `BreadcrumbProp`    | navigation  | navigation.prop.ts  | Breadcrumb trail                        |
+| `ColumnDefProp`     | data        | data.prop.ts        | Table column def                        |
+| …                   |             |                     | See `VOCABULARY_REGISTRY` for full list |
+
+## Component props (composite)
+
+| Name                | Group        | Vocabulary used                                                             |
+| ------------------- | ------------ | --------------------------------------------------------------------------- |
+| `PageContainerProp` | layout       | TitleProp, SubtitleProp, ExtraProp, FooterProp, BreadcrumbProp, DensityProp |
+| `ButtonProp`        | general      | ButtonVariantProp, ButtonSizeProp, AsChildProp                              |
+| `DataTableProp`     | data-display | ColumnDefProp, TableDensityProp, SortStateProp                              |
+| `DialogConfirmProp` | feedback     | OpenProp, TitleProp, DescriptionProp, HandlerProp, PendingProp              |
+| `EmptyStateProp`    | data-display | IconProp, TitleProp, DescriptionProp, ActionProp                            |
+| …                   |              | See `COMPONENT_PROP_REGISTRY`                                               |
+
+## Before adding a new prop
+
+1. Search this file and `PROPS-VOCABULARY.md`
+2. Run `grep -r "YourConcept" packages/ui/src/props/`
+3. Reuse vocabulary type if concept exists
+4. If new: add to vocabulary → component prop → registry → docs → story
+
+## Forbidden duplicates
+
+| Informal name                    | Canonical                               |
+| -------------------------------- | --------------------------------------- |
+| `description` (pages)            | `subtitle` → `SubtitleProp`             |
+| `description` (dialogs)          | `DescriptionProp`                       |
+| `actions` (header)               | `extra` → `ExtraProp`                   |
+| `density` (ambiguous)            | `PageDensityProp` or `TableDensityProp` |
+| `gap` (component subset)         | `GapProp` with documented subset        |
+| `onClear`                        | `OnClearFiltersProp`                    |
+| `loading` / `pending` on actions | `PendingProp`                           |

package/docs/PROPS-VOCABULARY.md

@@ -0,0 +1,100 @@
+# Props Vocabulary
+
+Atomic prop types live in `src/props/vocabulary/`. Every type name ends with **`Prop`**.
+
+Import: `import type { TitleProp, GapProp } from "@godxjp/ui/props/vocabulary"`
+
+---
+
+## Shared
+
+| Type               | Value                         | Used for                  |
+| ------------------ | ----------------------------- | ------------------------- |
+| `ClassNameProp`    | `string`                      | Root class override       |
+| `ChildrenProp`     | `ReactNode`                   | Child slot                |
+| `IdProp`           | `string`                      | DOM / form id             |
+| `OpenProp`         | `boolean`                     | Dialog/Sheet/Popover open |
+| `OnOpenChangeProp` | `(open: boolean) => void`     | Panel open state change   |
+| `HandlerProp`      | `() => void \| Promise<void>` | Confirm / retry callbacks |
+| `PendingProp`      | `boolean`                     | Loading / in-flight       |
+| `RequiredProp`     | `boolean`                     | Required field            |
+| `DisabledProp`     | `boolean`                     | Disabled control          |
+| `LabelProp`        | `ReactNode`                   | Generic label             |
+| `HelperProp`       | `ReactNode`                   | Input hint text           |
+| `ErrorProp`        | `ReactNode`                   | Validation error          |
+| `PlaceholderProp`  | `string`                      | Input placeholder         |
+| `AsChildProp`      | `boolean`                     | Radix polymorphism        |
+
+## Content slots
+
+| Type               | Semantics                            | Do NOT confuse with |
+| ------------------ | ------------------------------------ | ------------------- |
+| `TitleProp`        | Primary heading                      | —                   |
+| `SubtitleProp`     | Line under title on **pages**        | `DescriptionProp`   |
+| `DescriptionProp`  | Body copy in dialogs / empty states  | `SubtitleProp`      |
+| `ExtraProp`        | Top-right page actions (Ant `extra`) | `ActionsProp`       |
+| `FooterProp`       | Bottom page action bar               | —                   |
+| `ActionProp`       | Empty state CTA                      | `ExtraProp`         |
+| `ActionsProp`      | Toolbar button group                 | `ExtraProp`         |
+| `IconProp`         | `LucideIcon` component               | —                   |
+| `ConfirmLabelProp` | Dialog confirm button text           | —                   |
+| `CancelLabelProp`  | Dialog cancel button text            | —                   |
+
+## Layout & density
+
+| Type               | Values                              | Scope                                                          |
+| ------------------ | ----------------------------------- | -------------------------------------------------------------- |
+| `PageDensityProp`  | `compact \| default \| comfortable` | **PageContainer** subtree                                      |
+| `GapProp`          | `xs \| sm \| md \| lg \| xl`        | `<Flex gap>` (row) and `<Flex direction="col" gap>` (vertical) |
+| `TableDensityProp` | `compact \| comfortable`            | **DataTable** rows only                                        |
+
+> **Critical:** `PageDensityProp` ≠ `TableDensityProp`. Never use bare `density` in new APIs.
+
+## Interaction variants
+
+| Type                 | Values                                                                     |
+| -------------------- | -------------------------------------------------------------------------- |
+| `ButtonVariantProp`  | `default \| destructive \| outline \| secondary \| ghost \| link`          |
+| `ButtonSizeProp`     | `default \| sm \| lg \| icon`                                              |
+| `ConfirmVariantProp` | `default \| destructive`                                                   |
+| `ToneProp`           | `default \| success \| warning \| destructive \| info \| muted \| neutral` |
+| `SortDirectionProp`  | `asc \| desc`                                                              |
+| `ColumnAlignProp`    | `left \| center \| right`                                                  |
+| `SortStateProp`      | `{ key: string; direction: SortDirectionProp }`                            |
+
+## Navigation
+
+| Type                 | Shape                               |
+| -------------------- | ----------------------------------- |
+| `BreadcrumbItemProp` | `{ label: LabelProp; to?: string }` |
+| `BreadcrumbProp`     | `BreadcrumbItemProp[]`              |
+| `TitleProp`          | primary heading text                |
+
+## Data collections
+
+| Type                       | Purpose                 |
+| -------------------------- | ----------------------- |
+| `ColumnDefProp<T>`         | DataTable column        |
+| `GetRowIdProp<T>`          | Row ID extractor        |
+| `OnRowClickProp<T>`        | Row navigation          |
+| `SelectedIdsProp`          | `Set<string>` selection |
+| `OnSelectChangeProp`       | Selection handler       |
+| `OnTableDensityChangeProp` | Table density handler   |
+| `OnSortChangeProp`         | Sort handler            |
+| `OnSearchChangeProp`       | Debounced search        |
+| `OnClearFiltersProp`       | Toolbar clear           |
+| `HasActiveFiltersProp`     | Show clear button       |
+
+## Forbidden aliases
+
+See `PROP_ALIASES_FORBIDDEN` in `@godxjp/ui/props/registry`:
+
+| Don't use                     | Use instead                                        |
+| ----------------------------- | -------------------------------------------------- |
+| bare `description` on pages   | `SubtitleProp`                                     |
+| bare `description` in dialogs | `DescriptionProp`                                  |
+| `actions` on page header      | `ExtraProp`                                        |
+| bare `density`                | `PageDensityProp` or `TableDensityProp`            |
+| component-specific gap unions | `GapProp` or documented `Extract`/`Exclude` subset |
+| `onClear`                     | `OnClearFiltersProp`                               |
+| `loading` on buttons          | `PendingProp`                                      |

package/docs/README.md

@@ -0,0 +1,60 @@
+# @godxjp/ui Documentation
+
+| Doc                                          | Purpose                                                                                                                                      |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| [CONSUMER-RULES.md](./CONSUMER-RULES.md)     | **Start here if you build an app with @godxjp/ui** — the ten rules the audit enforces (styles entry, layout owners, real primitives, tokens) |
+| [DEVELOPMENT.md](./DEVELOPMENT.md)           | **Contributor guideline** — role/boundary, architecture, how to add/extend, verify                                                           |
+| [COMPONENTS.md](./COMPONENTS.md)             | Component catalog by Ant Design group                                                                                                        |
+| [PROPS-VOCABULARY.md](./PROPS-VOCABULARY.md) | Atomic prop types (`*Prop` suffix)                                                                                                           |
+| [PROPS-REGISTRY.md](./PROPS-REGISTRY.md)     | Machine-readable registry + forbidden aliases                                                                                                |
+| [DATETIME.md](./DATETIME.md)                 | **Mandatory** `formatDate` — all date/time display                                                                                           |
+| [SPACING.md](./SPACING.md)                   | Golden ratio (φ) macro spacing — PageContainer sections, Flex gap, Card rhythm                                                               |
+| [FORMS.md](./FORMS.md)                       | **Mandatory** react-hook-form + Zod 4                                                                                                        |
+| [TESTING.md](./TESTING.md)                   | **Mandatory** Vitest per component                                                                                                           |
+| [FRAME-A11Y-CI.md](./FRAME-A11Y-CI.md)       | Per-frame axe a11y + geometry + coverage CI gates — how to run/regenerate locally                                                            |
+| [../README.md](../README.md)                 | Setup, workspace wiring, theme                                                                                                               |
+
+## Preview
+
+```bash
+cd packages/ui
+pnpm preview          # http://localhost:6008
+pnpm preview:build    # static site → preview/dist/
+```
+
+### Preview doc format
+
+```
+docs/
+  primitives/              ← sidebar group (folder name → title)
+    README.md              ← optional group intro
+    data-display/
+      README.md
+      overview.tsx         ← 1 story = 1 demo (default export)
+      overview.md          ← optional story docs (YAML frontmatter: title, layout)
+      _shared.ts           ← prefix _ = not a story
+```
+
+- **Navigation** = folder tree; leaves = `.tsx` files (not `README.md`, not `_*.tsx`).
+- **Live demo** = `export default function Demo()` from the `.tsx` file.
+- **Imports** = `@godxjp/ui/{data-display,layout,general,…}` — same public paths as app code (`FORMS.md`). **Not** `@/components/…` (internal dev alias only).
+- **Code panel** = same `.tsx` file raw — no duplicate `parameters.docs.source.code`.
+- **Story docs** = optional same-name `.md` beside the demo (tiếng Việt): giới thiệu, khi nào dùng, import, props (hiển thị / hành động / DOM). Regenerate: `pnpm docs:sync-primitives`.
+- Component preview examples live in `examples/**/*.preview.tsx`.
+
+## Props folder layout
+
+```
+src/props/
+├── vocabulary/     ← atomic reusable concepts (TitleProp, GapProp, …)
+├── components/     ← per-component interfaces (PageContainerProp, ButtonProp, …)
+├── registry.ts     ← canonical catalog — check before adding new props
+└── index.ts        ← public export @godxjp/ui/props
+```
+
+## Naming rules
+
+1. **Vocabulary** (atomic): `{Concept}Prop` — e.g. `TitleProp`, `PageDensityProp`
+2. **Component** (composite): `{Component}Prop` — e.g. `PageContainerProp`, `ButtonProp`
+3. **Never** define prop interfaces inline in component `.tsx` files
+4. **Always** check `registry.ts` + `PROP_ALIASES_FORBIDDEN` before inventing a name