@godxjp/ui 19.1.0 → 19.3.1

package/docs/REGISTRY.md

@@ -0,0 +1,70 @@
+# Consuming @godxjp/ui through the shadcn registry
+
+## What is published, and what is not
+
+`@godxjp/ui` ships as an **npm package**. The components are imported, not copied:
+
+```ts
+import { DataTable, Cascader } from "@godxjp/ui/data-display";
+```
+
+The registry does **not** publish those components, and that is deliberate. A shadcn registry is a copy-paste channel — `shadcn add` writes files into your tree and you own them from then on. Copying 165 components would fork your copy from the package: you would stop receiving token fixes, a11y fixes and the guard discipline the library is built on, while carrying ~73k lines you did not write.
+
+What the registry publishes is the part the package cannot hand you on its own: **the design language**.
+
+| Item             | Type             | What you get                                                                   |
+| ---------------- | ---------------- | ------------------------------------------------------------------------------ |
+| `@godxjp/theme`  | `registry:theme` | The full token system — foundation scales, semantic roles, per-component knobs |
+| `@godxjp/styles` | `registry:style` | The stylesheets those tokens drive (only if you adopt godxjp markup too)       |
+
+`docs/showcase/acme-portal.tsx` is the proof this is the valuable half: an entire brand — gold and navy, Source Sans 3, a 14px radius, navy-tinted shadows — reproduced by **configuring tokens alone**, with no component edits and no new components.
+
+## Setup
+
+Add the namespace to your own `components.json`:
+
+```json
+{
+  "registries": {
+    "@godxjp": "https://godx-jp.github.io/godxjp-ui/registry/{name}.json"
+  }
+}
+```
+
+Then:
+
+```bash
+npx shadcn add @godxjp/theme
+```
+
+and import the token entry before your own overrides:
+
+```css
+@import "./styles/tokens/base.css";
+```
+
+## Re-theming
+
+Override roles at `:root`, or scope them per tenant:
+
+```css
+[data-tenant="acme"] {
+  --primary: 41 71% 53%;
+  --radius: 0.875rem;
+  --font-family-sans: "Source Sans 3", system-ui, sans-serif;
+}
+```
+
+Two rules the token system holds to, worth knowing before you override:
+
+This is what lets a scoped `[data-tenant]` or `.dark` override actually reach a portaled overlay. See `docs/TOKENS.md`.
+
+## Why not the components?
+
+If you want the components, install the package — that is the supported path and the one every guard, test and token in this repo is built around:
+
+```bash
+pnpm add @godxjp/ui
+```
+
+The registry exists for teams who already have their own shadcn components and want the godxjp design language on top of them.

package/docs/SPACING.md

@@ -0,0 +1,56 @@
+# Spacing & golden ratio (@godxjp/ui)
+
+Macro layout uses a **φ modular scale** (≈ 1.618). Reference: [NN/G — golden ratio in UI](https://www.nngroup.com/articles/golden-ratio-ui-design/).
+
+Implementation: `src/tokens/base.css` (values) · layout owners: `src/styles/*-layout.css` · full map: `docs/TOKENS.md`.
+
+## Rules for apps
+
+1. **Never** Tailwind `gap-*`, `space-*`, `p-*`, `m-*` for layout — the audit rejects them (`no-utility-spacing`, `no-utility-layout`). Rows are `<Flex>` (default `direction="row"`), stacks are `<Flex direction="col" gap>`, grids are `<ResponsiveGrid>`.
+2. **Page sections are spaced by `<PageContainer>` itself**: every direct child of the page body gets `--page-body-gap` (the section step, φ⁰) above it. Do not wrap the sections in a Flex just to space them; do not add margins.
+3. Inside a section: `<Flex direction="col" gap="md">` (φ⁰) for the default rhythm, `gap="lg"` (φ¹) / `gap="xl"` (φ²) for major blocks, `xs` / `sm` (4px grid) for control rows.
+4. Card rhythm is token-driven — do not override card padding in app CSS.
+
+## φ scale (one knob)
+
+| Token      | Formula             |
+| ---------- | ------------------- |
+| `--phi-n1` | unit ÷ φ            |
+| `--phi-0`  | unit (`--phi-unit`) |
+| `--phi-p1` | unit × φ            |
+| `--phi-p2` | unit × φ²           |
+
+`--phi-unit` steps up at `sm` breakpoint; density (`compact` / `comfortable`) retunes it on `PageContainer`.
+
+## Flex gap map
+
+| Prop       | Token    | Typical use           |
+| ---------- | -------- | --------------------- |
+| `xs`, `sm` | 4px grid | Tight form rows       |
+| `md`       | φ⁰       | Default sections      |
+| `lg`       | φ¹       | Dashboard blocks      |
+| `xl`       | φ²       | Page-level separation |
+
+## Card
+
+**Single owner:** `src/styles/card-layout.css` - all `[data-slot="card-*"]` padding. Components emit `data-slot` + modifier flags only (`data-banded`, `data-flush`, `data-tight`, `data-solo`, `data-separated`). Never Tailwind `p-*` / `px-*` on `Card*` in apps or previews.
+
+| Part                                              | Ratio                    | Role                                       |
+| ------------------------------------------------- | ------------------------ | ------------------------------------------ |
+| `--card-space-inset`                              | `--space-section-active` | Inline (start/end) inset                   |
+| `--card-space-shell-y`                            | `--card-space-inset`     | Block shell padding (first/last slot edge) |
+| `--card-space-body-y`                             | `--space-section-active` | Header↔body gap                            |
+| `--card-space-header-y` / `--card-space-footer-y` | `--space-stack-sm`       | Banded header + separated footer band      |
+
+| Component                 | Use                                                |
+| ------------------------- | -------------------------------------------------- |
+| `StatCard`                | KPI / stat tile (`solo` path)                      |
+| `CardContent solo`        | Body-only card (same padding as `StatCard`)        |
+| `CardContent flush tight` | Edge-to-edge table/tabs in card                    |
+| `ui-card-inset-x`         | Align nested cells to shell (tables in flush body) |
+
+See preview **Data Display → Card** for live examples.
+
+## MCP
+
+`get_pattern page-sections` (a page of Cards, spaced by the page) · `get_rule 40` (mobile-first spacing) · `list_audit_rules` (the spacing rules the CLI enforces).

package/docs/STANDARDS-vocabulary-tokens.md

@@ -0,0 +1,48 @@
+# Prop Vocabulary + Design Token Standards
+
+These rules are normative for @godxjp/ui 8.0.0. They mirror `debate/props-vocab-token-consistency/04-Decision.md`.
+
+1. Prop vocabulary: every exported `*Prop` type in `src/props/components/` MUST have exactly one `COMPONENT_PROP_REGISTRY` entry.
+2. Prop vocabulary: every public property in an exported component prop type MUST map to one `VOCABULARY_REGISTRY` entry or to a `local: true` registry record with a non-empty `reason`.
+3. Prop vocabulary: every vocabulary name referenced by `COMPONENT_PROP_REGISTRY[*].vocabulary` MUST exist in `VOCABULARY_REGISTRY`.
+4. Prop vocabulary: the same prop spelling, value kind, and semantic role used by two or more components MUST use one shared vocabulary entry.
+5. Prop vocabulary: `gap` MUST use the single shared `GapProp` on every layout primitive (`Flex`); there are NO per-component gap vocabularies, and none may be added to the registry.
+6. Prop vocabulary: primary heading text MUST use `TitleProp`; `PageTitleProp` MUST NOT be a canonical registry entry.
+7. Prop vocabulary: abstract controlled values MUST use `value?: ValueProp<T>`, `defaultValue?: DefaultValueProp<T>`, and `onValueChange?: OnValueChangeProp<T>`; `onChange` MAY be used only for DOM event handlers or explicitly local compatibility wrappers.
+8. Prop vocabulary: disclosure/open state MUST use `open?: OpenProp`, `defaultOpen?: DefaultOpenProp`, and `onOpenChange?: OnOpenChangeProp`.
+9. Prop vocabulary: semantic color/status intent MUST use `tone` with `ToneProp` or a documented status-specific subtype; `variant` MUST NOT include status-only values such as `success`, `warning`, `info`, or `neutral`.
+10. Prop vocabulary: public `size` values MUST use shared `SizeProp` names or a documented component-specific subset; aliases such as `small` MUST be renamed to the canonical shared value.
+11. Prop vocabulary: public density MUST use `DensityProp` when the component participates in page/subtree density; component-specific density subsets MUST be documented with a registry reason.
+12. Prop vocabulary: no new public `HandlerProp` use is allowed for named user events; command callbacks MUST have event-specific names such as `onConfirm`, `onRetry`, `onDismiss`, or `onValueChange`.
+13. Design tokens: package tokens MUST be organized into primitive, semantic, and component tiers.
+14. Design tokens: primitive tokens MUST define raw scales or palettes only; semantic tokens MUST alias primitives by UI role; component tokens MUST alias semantic or primitive tokens by component part/state.
+15. Design tokens: package CSS custom properties and Tailwind `@theme` exports MUST NOT contain app, customer, or business-domain nouns.
+16. Design tokens: `--tracking-*` and `--color-tracking-*` are forbidden in package source.
+17. Design tokens: component-scoped tokens MUST live in the component tier and use `--{component}-{part}-{property}` or `--{component}-{property}-{state}` naming consistently.
+18. Design tokens: Tailwind `@theme` color exports MUST reference package tokens; literal colors are allowed only when first registered as primitive or semantic tokens.
+19. Design tokens: public raw/decorative primitive exports are allowed only under documented neutral namespaces such as `wa-*` or `chart-*`; undocumented raw ramps such as public `gray-*`/`blue-*` exports are forbidden.
+20. Design tokens: dark mode MUST override semantic tokens by role; component-token dark overrides require a documented component contrast reason.
+21. Design tokens: density CSS MUST select token aliases and MUST NOT introduce new raw component dimensions when a token tier can hold the value.
+22. Control sizing: an interactive control's box height/width MUST resolve from the `--control-height` tier (or its official steps `--control-height-{xs,sm,lg}`). Primitives MUST NOT bake in a control size via a literal length (`height: 2rem`) or an ad-hoc `calc(var(--control-height) ± <len>)` — the named tier carries the density-aware value, and per-instance size changes are the app's call via the `size` prop / `className`. Enforced by `pnpm check:control-sizing`.
+
+Examples:
+
+```ts
+type SelectLikeProp<T = string> = {
+  value?: ValueProp<T>;
+  defaultValue?: DefaultValueProp<T>;
+  onValueChange?: OnValueChangeProp<T>;
+};
+```
+
+```tsx
+<Badge tone="success" variant="outline">
+  公開中
+</Badge>
+```
+
+```css
+@theme {
+  --color-chart-1: var(--chart-1);
+}
+```

package/docs/TESTING.md

@@ -0,0 +1,98 @@
+# Testing @godxjp/ui
+
+Every component **must** ship with a Vitest suite before merge.
+
+## Run
+
+```bash
+cd packages/ui
+pnpm test              # single run
+pnpm test:watch        # watch mode
+pnpm test:coverage     # v8 coverage report
+```
+
+## File location
+
+Co-locate tests next to components:
+
+```
+src/components/layout/page-container.tsx
+src/components/layout/__tests__/page-container.test.tsx
+src/form/use-zod-form.ts
+src/form/__tests__/use-zod-form.test.tsx
+```
+
+## Required coverage per component
+
+Each `*.test.tsx` must include:
+
+1. **Render** — component mounts without throw
+2. **Props** — key prop variations (variants, sizes, density, slots)
+3. **Interaction** — userEvent for clicks, typing, keyboard where applicable
+4. **A11y** — roles, labels, aria-\* attributes for form controls
+5. **Edge cases** — empty, error, loading, disabled states
+
+## Test utilities
+
+```tsx
+import { renderWithUi, screen, userEvent } from "@/test/render";
+```
+
+`renderWithUi` wraps `MemoryRouter` + `React.StrictMode` + **`RenderLoopGuard`** (fails fast on infinite re-render loops, default max 25 renders).
+
+```tsx
+// Optional: disable guard for stress tests
+renderWithUi(<HeavyChart />, { loopGuard: false });
+
+// Custom threshold
+renderWithUi(<Widget />, { loopGuard: { maxRenders: 40, label: "Widget" } });
+```
+
+Shared guard lives in `@godxjp/tooling/test` — apps import the same helper.
+
+Vitest setup (apps):
+
+```ts
+// vitest.setup.ts
+import "@godxjp/tooling/test/vitest.setup.react";
+import "@testing-library/jest-dom/vitest";
+```
+
+`testTimeout: 8000` — hung tests fail before blocking CI.
+
+## Render loop prevention (ESLint + test)
+
+| Layer                             | Catches                          |
+| --------------------------------- | -------------------------------- |
+| `react-hooks/exhaustive-deps`     | missing/unstable effect deps     |
+| `react-hooks/set-state-in-effect` | sync setState in effects         |
+| `RenderLoopGuard` in tests        | runaway re-renders during Vitest |
+
+Run `pnpm lint` before `pnpm test` — official React Compiler rules align with test guard.
+
+## Forms testing
+
+Form integration tests **must** use Zod 4 schemas:
+
+```tsx
+const schema = z.object({ email: z.string().email() });
+const form = useZodForm(schema);
+```
+
+Never test forms with raw `useState` — mirror production `FormRoot` + `FormFieldControl`.
+
+## CI gate
+
+`pnpm test` in `packages/ui` must pass with zero failures before any UI PR merges.
+
+## When tests fail
+
+Guard suites and fix playbooks:
+
+| Suite                    | File                                                          |
+| ------------------------ | ------------------------------------------------------------- |
+| Theme token audit        | `src/lib/__tests__/theme-tokens-audit.test.ts`                |
+| Theme axes integration   | `src/components/__tests__/theme-axes-integration.test.tsx`    |
+| formatDate / AppProvider | `src/lib/__tests__/format-date.test.ts`, `src/app/__tests__/` |
+
+**Full failure routing:** MCP tool `godxjp_ui_guide` topic=`testing-troubleshooting` or `godxjp_ui_verify` with `failureHint` from CI log (see `tools/godxjp-ui-mcp/`).

package/docs/TOKENS.md

@@ -0,0 +1,347 @@
+# Design tokens — single owner model (@godxjp/ui)
+
+Every visual dimension has **one canonical owner**. Apps never patch spacing, density, typography, or color ad hoc.
+
+## Architecture
+
+```
+src/tokens/base.css          ← token manifest; imports every base token file
+src/tokens/foundation.css    ← primitive color accents, typography, raw spacing, icon size, ratio, radius, shadow
+src/tokens/semantic/         ← semantic aliases by UI role
+  layout.css                 ← page/section/stack/inline tokens
+src/tokens/components/       ← component token files
+  control.css                ← control height + control padding
+  card.css                   ← Card component tokens
+  table.css                  ← Table component tokens
+  feedback.css               ← Dialog/Alert/EmptyState component tokens
+  badge.css                  ← Badge component tokens
+src/styles/
+  index.css                  ← @theme bridge (Tailwind ↔ tokens) + body defaults
+  density.css                ← .ui-density-* (PageContainer density prop)
+  layout.css                 ← Flex / Page / EmptyState
+  control.css                ← inputs, buttons height (--control-height)
+  card-layout.css            ← Card* slots
+  table-layout.css           ← Table + DataTable chrome
+  dialog-layout.css          ← Dialog* slots
+  alert-layout.css           ← Alert* slots + semantic variant colors
+  badge-layout.css           ← Badge spacing
+```
+
+**Components emit `data-slot` + flags. Layout CSS applies padding/margin/gap/font-size/color.**
+
+`base.css` is the single entry point. Primitive token files are split only for governance and audit; apps still import `@godxjp/ui/styles` once and override tokens in `theme.css`.
+
+## By concern
+
+### Color
+
+| Owner                                   | Rule                                                                |
+| --------------------------------------- | ------------------------------------------------------------------- |
+| `base.css` `:root` / `.dark`            | HSL components (`--primary`, `--destructive`, …)                    |
+| `index.css` `@theme`                    | Maps to Tailwind `bg-primary`, `text-muted-foreground`, …           |
+| App `theme.css`                         | Override `:root` only — never component CSS                         |
+| `alert-layout.css`, `control-styles.ts` | Semantic tones (`success`, `warning`, …) — never `text-emerald-600` |
+
+Default brand tokens use the GodX Agent Portal palette: navy primary, 朱 orange focus/accent, warm neutral surfaces. App or customer identity colors belong in the consuming app theme, not in package tokens.
+
+#### `--border` vs `--input` — decorative chrome vs control boundary (gh#315)
+
+These two look like synonyms and are not. Keep them apart:
+
+| Role       | What it draws                                                                                                                                                   | Contrast bar                                                                                                                                           |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--border` | Decorative chrome — table rules, card edges, section dividers, `<Separator>`                                                                                    | **None.** WCAG 2.2 SC 1.4.11 does not reach a divider; this system's dense JP grid depends on it staying quiet                                         |
+| `--input`  | The boundary that **is** the control — Input, Textarea, Select, outline Button, TagInput, composite date field, topbar search, and the Switch's unchecked track | **≥ 3:1** (SC 1.4.11 Non-text Contrast) against every surface a control sits on — page, card, popover, muted/secondary panel, striped and hovered rows |
+
+A field here has no fill of its own (`background: hsl(var(--background))`) and no shadow to speak of, so that 1px edge is the whole visual claim that you may type there. Current values: `30 7% 53%` light (3.47:1 on `--background`/`--card`, 3.18:1 on `--muted`) and `45 6% 47%` dark (4.22:1 on `--background`, 3.88:1 on `--card`/`--popover`, 3.17:1 on `--muted`).
+
+**Re-theming rule:** a service theme that retints neutrals must move these two **independently** — setting `--input: var(--border)` re-opens the bug. `src/tokens/__tests__/input-boundary-contrast.test.ts` recomputes the ratios from `foundation.css` and fails below 3:1, and fails outright if the two roles are given the same value again.
+
+The Switch's off-track borrows `--input` by default. If a service wants it quieter than the boundary role, override `--switch-unchecked-background` (component token, `initial`, call-site default `hsl(var(--input))`) rather than dragging `--input` back down — but whatever you set still owes 3:1 against the page and against the thumb (`--background`), or "off" stops being a visible state.
+
+### Typography
+
+| Owner               | Rule                                                                                            |
+| ------------------- | ----------------------------------------------------------------------------------------------- |
+| `base.css`          | `--font-size-xs` … `--font-size-2xl`, weights, line-heights                                     |
+| `layout.css`        | Page title/subtitle, empty-state title                                                          |
+| `card-layout.css`   | Banded header title override                                                                    |
+| `dialog-layout.css` | Dialog title/description                                                                        |
+| Components          | Use `text-sm`, `text-base` (wired to tokens) or `data-slot` CSS — never arbitrary `text-[14px]` |
+
+Runtime scale: app `theme.css` overrides → `--font-size-sm` on root.
+
+### Spacing / margin / gap
+
+| App API                           | Internal owner                             |
+| --------------------------------- | ------------------------------------------ |
+| `<Flex direction="col" gap="md">` | `layout.css` `.ui-flex-gap-md`             |
+| `<Flex gap="sm">`                 | `layout.css` `.ui-flex-gap-sm`             |
+| `<PageContainer>`                 | `layout.css` `.ui-page-*`                  |
+| `<Card>` slots                    | `card-layout.css`                          |
+| `<Table>` cells                   | `table-layout.css` `[data-slot="table-*"]` |
+
+**Apps:** no Tailwind `p-*`, `m-*`, `gap-*`, `space-*`.
+
+### Icon size (gh#326)
+
+Icon was the last geometric axis without a scale. Twenty-eight component tokens declared raw numbers, and between them they used exactly **nine values** — the vocabulary was already there, nobody had written it down. `foundation.css` now does:
+
+| Token             | rem        | px     |                             |
+| ----------------- | ---------- | ------ | --------------------------- |
+| `--icon-size-2xs` | `0.625rem` | **10** | presence dot on an avatar   |
+| `--icon-size-xs`  | `0.75rem`  | **12** | table sort caret, xs button |
+| `--icon-size-sm`  | `0.875rem` | **14** | `size="sm"` controls        |
+| `--icon-size-md`  | `1rem`     | **16** | **the default icon step**   |
+| `--icon-size-lg`  | `1.25rem`  | **20** | alert / launcher glyph      |
+| `--icon-size-xl`  | `1.5rem`   | **24** | upload tile, empty state    |
+| `--icon-size-2xl` | `2.25rem`  | **36** | StatCard medallion          |
+| `--icon-size-3xl` | `2.5rem`   | **40** | dropzone                    |
+| `--icon-size-4xl` | `3rem`     | **48** | empty-state box             |
+
+Type can sit between pixels because hinting and antialiasing carry it; a 1px-stroke glyph cannot — half a pixel of icon is a blurred icon. Every step is a whole pixel at the 16px root, and a service retunes a **step**, never a ratio.
+
+**Not `--scaling`-multiplied.** The scale is the crisp pixel list; density is opted into by the tokens that want it — `--control-icon-size: calc(var(--icon-size-md) * var(--scaling))`. Whether a given icon tracks density stays a per-token decision.
+
+#### Two tiers, and where the boundary sits
+
+|            | When                                         | How                                                                   |
+| ---------- | -------------------------------------------- | --------------------------------------------------------------------- |
+| **Tier 1** | the value appears in **more than one place** | it earns a step on the scale; a service retunes the step once         |
+| **Tier 2** | the value appears in **exactly one place**   | set that component's own token **at the call site** — never the scale |
+
+A system with only tier 1 turns every exception into a hack (`!important`, a global override, a forked stylesheet); a system with only tier 2 loses consistency. The 6px status dot is the proof case: it will never be on an icon scale, and it is a real need.
+
+```tsx
+// Tier 2 — one instance, one arbitrary value. No !important, no :root override, no fork.
+<DropdownMenuItem style={{ "--menu-icon-size": "6px" } as React.CSSProperties}>…</DropdownMenuItem>
+```
+
+```css
+/* Tier 2, the theme form — scope it, don't globalise it. */
+[data-tenant="acme"] [data-slot="alert-icon"] {
+  --alert-dismiss-icon-size: 0.375rem;
+}
+```
+
+An inline custom property wins by **inheritance proximity**, not specificity, so it beats the `:root` default without any weight games. What keeps the route open is that every icon rule in `src/styles` reads its token through `var()` with no baked literal — `src/tokens/__tests__/icon-size-scale.test.ts` asserts exactly that, and carries a shrink-only list of the rules that still bake a literal and are therefore unreachable from an app.
+
+The three left need tokens in `components/control.css` (`.ui-otp-separator-icon`) and `components/shell.css` (`.tb-icon-btn svg`, `.tb-chip-icon`). Note that `.tb-chip-icon`'s `1.125rem` is **not** a snap case even though 18px is off the scale: it is a whole pixel, and the box is a letter medallion (`display: grid`, `place-items: center`, a radius, `color: white`), not a stroked glyph — so it wants a `scale-exempt:` marker, not the nearest step. Off-scale and off-grid are different findings; decide each on what the icon actually is.
+
+**Before you add a step:** if a value is wanted in two places it belongs on the scale, and if it is wanted in one it does not. Adding a tenth step to serve a single call site is how a scale stops meaning anything.
+
+### Stroke and band height (gh#324)
+
+The census confirmed the number and rejected the diagnosis: **`width` is not one axis.** Three unrelated concerns wear the suffix.
+
+| concern                  | example                                      | verdict                      |
+| ------------------------ | -------------------------------------------- | ---------------------------- |
+| thickness of a line      | `--control-border-width: 1px`                | **one vocabulary** → a scale |
+| measure of a container   | `--dialog-width-default: 32rem`              | not a scale — tier 2         |
+| content width of a field | `--app-setting-picker-timezone-width: 14rem` | not a scale — tier 2         |
+
+`height` split the same way: a control, a table row, a menu item, a nav row and the app-shell top bar are one decision sharing one vocabulary; a chart plot's height and a popover's max-height are container measures chosen per surface. `size` and `offset` came out no-scale on the same test. **Naming a scale is the fix for an axis; declaring that an axis is _not_ one is the fix for the rest** — both verdicts, and the census behind them, live in `scripts/token-scale-bypass-rules.mjs` so the question is not re-asked every quarter.
+
+#### `--stroke-*` — the thickness of a painted line
+
+| Token               | px      |                                                         |
+| ------------------- | ------- | ------------------------------------------------------- |
+| `--stroke-hairline` | **1**   | every resting border, divider and rule                  |
+| `--stroke-sm`       | **1.5** | avatar presence stroke                                  |
+| `--stroke-md`       | **2**   | **the emphasis stroke** — focus rings, selected markers |
+| `--stroke-lg`       | **3**   | the open/focus ring on toggles                          |
+| `--stroke-xl`       | **4**   | Steps process ring                                      |
+| `--stroke-2xl`      | **6**   | the Card accent rail                                    |
+
+**Px, never rem.** A stroke is a _device_ line: its job is to read as one crisp rule at any type size, so it must not grow when the root font-size does. Every token that moved onto this scale was already `px` for that reason; a `rem` thickness (`--slider-track-height: 0.375rem`) is a different decision and stayed where it was. **Not `--scaling`-multiplied** either — `--scaling` is a density knob, and a 1px divider at 0.92px would blur rather than tighten.
+
+`--focus-ring-width` is now a member (`var(--stroke-md)`) rather than a parallel authority, so a high-contrast theme that wants every emphasis stroke at 3px sets one token.
+
+#### `--band-height-*` — the vertical extent of a horizontal band
+
+| Token               | rem       | px     |                                          |
+| ------------------- | --------- | ------ | ---------------------------------------- |
+| `--band-height-xs`  | `1.5rem`  | **24** | `--control-height-xs`                    |
+| `--band-height-sm`  | `1.75rem` | **28** | compact control / table row, file button |
+| `--band-height-md`  | `2rem`    | **32** | **the default control and row band**     |
+| `--band-height-lg`  | `2.25rem` | **36** | the canonical DXS auth control           |
+| `--band-height-xl`  | `2.75rem` | **44** | the WCAG 2.2 AA touch floor (rule #24)   |
+| `--band-height-2xl` | `3rem`    | **48** | the AppShell top bar                     |
+| `--band-height-3xl` | `3.5rem`  | **56** | the AppShell top bar on a coarse pointer |
+
+**This is not a replacement for `--control-height-*`, and the difference matters.** The control tier is a **runtime ladder**: it multiplies by `--scaling`, steps ±`--space-1` for `sm`/`lg`/`xs`, and `@media (pointer: coarse)` lifts the whole thing to the 44px tap floor. `--band-height-*` is the **static vocabulary the ladder is anchored on** — `--control-height-default: var(--band-height-md)` — exactly as `--font-size-base` anchors the type scale.
+
+> Point a band token at `--control-height-*` to "reuse a step" and you silently enrol it in
+> density **and** in the coarse-pointer growth. That is a geometry change, not a rename.
+> `--table-row-height-default` reads `var(--band-height-md)`, not `var(--control-height-default)`,
+> for precisely that reason.
+
+That trap had already been sprung once: `--card-service-launcher-icon-size` read `var(--control-height-lg)` — a control tier sizing an _icon_ box. Invisible at the desk and wrong on a phone, where the medallion inflated 36px → 48px while the glyph inside it stayed 20px. It is `calc(var(--icon-size-2xl) * var(--scaling))` now: right axis, same value on every density, and it stops growing on touch.
+
+#### Mis-named axes are worth renaming, with an alias
+
+`--table-skeleton-line-height` was a **length** on the line-height axis, whose scale is a set of unitless _ratios_ — so it was never a bypass, it was a mis-named height, and while it stood the axis could not be gated at all. One rename unlocked a whole axis at zero baseline cost.
+
+### Component Tokens
+
+Each component owns a token file under `src/tokens/components/`. The file may only derive from foundation, semantic, or other component tokens; component CSS may only consume those component tokens.
+
+#### Role-mirror knobs MUST be `initial` + a call-site fallback (the `:root` freeze rule)
+
+When a component-token default is just a **role token** (`--card-background` defaults to `--card`, `--table-header-background` to `--muted`, `--checkbox-checked-background` to `--primary`, `--focus-ring-color` to `--ring` …), you may **not** write the binding at `:root`:
+
+```css
+/* ✗ WRONG — freezes at the :root role value */
+:root {
+  --card-background: var(--card);
+}
+.ui-card {
+  background: hsl(var(--card-background));
+}
+```
+
+CSS substitutes a `var()` at the element that **declares** it, so `--card-background` computes to `:root`'s `--card` and inherits that frozen value down. A consumer who scopes the _role_ (`[data-tenant] { --card: <dark> }` or `.dark`) overrides `--card` but **never reaches** `--card-background` — the component keeps the light `:root` value. Under a dark theme this is glaring (a frozen light card under white text → invisible text); under a light theme it hides silently.
+
+Instead, declare the knob `initial` (a real, catalogued, guaranteed-invalid declaration — no role to freeze) and move the role default to the **call site** as a fallback, so it re-resolves live at the painting element under any scope, while an explicit theme override of the knob still wins:
+
+```css
+/* ✓ RIGHT — default re-resolves under scope; knob still overridable */
+:root {
+  --card-background: initial;
+} /* documented default = hsl(var(--card)) */
+.ui-card {
+  background: hsl(var(--card-background, var(--card)));
+}
+```
+
+The same rule applies to `@theme inline` (utilities re-resolve scoped roles) and to any `:root`-declared **composite** that wraps a role (e.g. a focus-ring box-shadow): read the role **directly** at the call site, never through a frozen `:root` intermediate. Pure non-colour knobs (spacing, radius, font-size) don't need this — they aren't scope-retinted — but any colour/fill/ border/shadow knob whose default is a role token does.
+
+**The same freeze bites any knob whose default is a RE-SCOPED tier, colour or not.** `--control-height` is re-scoped by `.ui-auth-shell` (44px comfortable) and by `.ui-auth-shell[data-variant="canonical"]` (36px), so a knob that mirrors it must follow the same `initial` + call-site-fallback shape:
+
+```css
+:root {
+  --otp-slot-size: initial;
+} /* documented default = var(--control-height) */
+.ui-otp-slot {
+  width: var(--otp-slot-size, var(--control-height));
+}
+```
+
+Ask "is the default a token that some scope re-declares?", not "is the default a colour?".
+
+Card primitive tokens:
+
+| Token                      | Purpose                                                                                        |
+| -------------------------- | ---------------------------------------------------------------------------------------------- |
+| `--card-space-inset`       | Shared header/body/footer **inline** inset — the column all slots align to                     |
+| `--card-space-shell-y`     | **Block** shell padding (header top · `solo` body top · terminal bottom) — default = the inset |
+| `--card-space-header-y`    | Banded header band vertical density (feeds `--card-space-divided-y`)                           |
+| `--card-space-body-y`      | Gap under the header + the body's own top padding                                              |
+| `--card-space-footer-y`    | Separated footer band vertical density (feeds `--card-space-divided-y`)                        |
+| `--card-space-divided-y`   | **Border-aware** symmetric top+bottom padding of a DIVIDED band                                |
+| `--card-space-gap`         | In-slot stack gap (header title ↕ description)                                                 |
+| `--card-accent-rail-width` | Width of the `accent` leading-edge stripe (default `6px`)                                      |
+| `--card-title-font-size`   | Card title scale                                                                               |
+| `--card-header-background` | Banded header background color token                                                           |
+| `--card-shadow`            | Card elevation                                                                                 |
+
+#### Border-aware vertical padding (dividers)
+
+A card slot's vertical padding depends on **whether it carries a divider border** — set it once via a token, never hard-code padding on the slot:
+
+- **Divided band** — a `<CardHeader banded>` (bottom border + muted band) or a `<CardFooter separated>` (top border). It reads as its own region, so it pads **symmetrically** top+bottom from `--card-space-divided-y` (which defaults to `--card-space-header-y`). One knob keeps the header- and footer-band rhythm in sync. - **Plain header** — no border; it _flows_ into the body.
+
+So: WITH a divider → symmetric band padding; WITHOUT → asymmetric flow padding. Tune the band density once at `--card-space-divided-y`; tune the accent stripe at `--card-accent-rail-width`.
+
+#### The two card axes are independent (gh#232)
+
+`--card-space-inset` owns the **inline** column; `--card-space-shell-y` owns the **block** shell edges (a plain header's top, a `solo` body's top, the terminal slot's bottom). `--card-space-shell-y` is declared `initial`, so its default resolves at the call site to `--card-space-inset` — a card that sets neither, or that only re-tunes the inset (including `density="tight|cozy"`), renders exactly as before. Override `--card-space-shell-y` alone to make a card **shorter without narrowing it**:
+
+```css
+/* a short login card that keeps its 24px column */
+.ui-auth-shell {
+  --auth-shell-card-padding-block-compact: 14px;
+}
+```
+
+That AuthShell knob is wired straight to `--card-space-shell-y` on the compact auth card; the inline column stays on `--auth-shell-compact-card-inset` and the header↔body gap on `--auth-shell-card-body-gap-compact`. Three knobs, three axes, no consumer bridge selector on `[data-slot="card-content"]`.
+
+Example app override:
+
+```css
+:root {
+  --card-space-inset: var(--space-section-active);
+  --card-space-divided-y: var(--space-stack-md); /* roomier banded header / separated footer */
+  --card-accent-rail-width: 4px; /* thinner accent stripe */
+}
+```
+
+### Density
+
+| App API                                                   | Owner         |
+| --------------------------------------------------------- | ------------- |
+| `<PageContainer density="compact\|default\|comfortable">` | `density.css` |
+
+Retunes `--phi-unit`, `--control-height`, `--table-row-height`, `--table-cell-padding-y` for the whole subtree.
+
+Control heights are `compact` 28px, `default` 32px, and `comfortable` 44px. Use `comfortable` for handheld/public surfaces that need the touch floor.
+
+### Card / Table / Dialog / Alert
+
+See `docs/SPACING.md` for Card slot matrix. Same pattern everywhere:
+
+1. Component TSX → `data-slot` + modifier flags only
+2. `*-layout.css` → all inset/gap/border-band rules
+3. Governance test fails if TSX reintroduces padding utilities
+
+## Preset components (avoid reinventing layout)
+
+| Need            | Use                               |
+| --------------- | --------------------------------- |
+| KPI stat tile   | `<StatCard label value delta />`  |
+| Page sections   | `<Flex direction="col" gap="md">` |
+| Row of controls | `<Flex gap="sm">`                 |
+| Status enum     | `<Badge status="…" />`            |
+| Empty list      | `<EmptyState … />`                |
+
+## The layer contract
+
+Every rule this package ships sits inside a cascade layer, and **layer order beats specificity outright**. Two halves, and both have already cost a release.
+
+### Inside the package
+
+`@import "tailwindcss"` establishes `theme, base, components, utilities`. Component CSS lives in `@layer components`, which is **earlier** than `utilities` — so a Tailwind utility a component emits on its own element outranks the layered rule that is supposed to own the same property, and no selector can win that fight.
+
+The documented token was dead, the narrow frame stayed at 14px, and a 5–6 character Japanese label could not fit its column measure — a WCAG 2.2 SC 1.4.10 failure that only manifests in Japanese. Two independent consumers reported it.
+
+A **responsive re-point** that must beat such a utility goes in **`@layer godxjp-ui-responsive`**, declared straight after Tailwind in `src/styles/base.css` and therefore the last layer:
+
+```css
+@layer godxjp-ui-responsive {
+  @container ui-table-collection (width < 40rem) {
+    [data-collapse-below="sm"] [data-slot="table"] {
+      font-size: var(--table-action-collection-font-size-compact);
+    }
+  }
+}
+```
+
+It is reserved for `@container` / `@media` re-points. Everything static stays in `@layer components`.
+
+### In a consumer app
+
+**Unlayered CSS outranks every layer, including `godxjp-ui-responsive`.** So:
+
+- Theme this package by setting **tokens** on a wrapper element (`.my-page { --table-…: 7rem; }`). - Do **not** write app selectors against package internals (`[data-slot]`, `[data-priority]`, `.ui-*`). An unlayered rule that does wins at _every_ width and kills the package's responsive re-points.
+
+## Adding a new component
+
+1. Add/update the component token file in `src/tokens/components/`.
+2. Add `src/styles/<component>-layout.css` with `[data-slot="…"]` rules.
+3. Import in `index.css`.
+4. Component TSX: structure + `data-slot` only.
+5. Extend `token-governance.test.ts` allowlist only for third-party adapters (calendar, cmdk).
+
+## MCP
+
+`godxjp_ui_guide` topic=`golden-ratio` · `tokens`