@godxjp/ui 31.31.7 → 32.0.0

package/agent/rules.json

@@ -1,33 +1,28 @@
 [
   {
-    "body": "Every primitive / shell / composite has a paired story under `src/stories/<group>/<Name>.stories.tsx` covering every variant + state on light + dark.",
+    "body": "Every primitive / shell / composite has an example page under `docs/<group>/` (rendered at `/isolate/<group>-<name>`) covering every prop value and state on light + dark, built from real primitives.",
     "number": 1,
-    "title": "Storybook is mandatory"
+    "title": "Every component has a real-screen docs page"
   },
   {
-    "body": "Visual values come from CSS custom properties in `src/tokens/` + `src/styles/theme.css`. Token-named Tailwind utilities (`bg-background`) are fine; raw value utilities (`bg-blue-500`) are forbidden.",
+    "body": "Visual values come from CSS custom properties in `src/tokens/` (the `@theme` bridge lives in `src/styles/base.css`). Token-named Tailwind utilities (`bg-background`) are fine; raw value utilities (`bg-blue-500`) are forbidden.",
     "number": 2,
     "title": "Tokens, not utilities"
   },
   {
-    "body": "Anything with keyboard / ARIA / portal wraps the relevant Radix primitive.",
+    "body": "Anything with keyboard / ARIA / portal behaviour is built on `react-aria-components` (or the matching `react-aria` hook). Do not add a new `@radix-ui` import: `pnpm check:radix-surface` is a ratchet that only lets the remaining Radix files shrink.",
     "number": 3,
-    "title": "Radix for interactive primitives"
+    "title": "Accessible behaviour comes from react-aria-components, not new Radix"
   },
   {
-    "body": "Primitives are thin wrappers; consumers can fork the source in place.",
-    "number": 4,
-    "title": "shadcn-style ownership"
-  },
-  {
-    "body": "`initI18n()` in `src/i18n/index.ts` is THE instance; consumers extend via `addResourceBundle`.",
+    "body": "Strings go through `t()` / `useTranslation()` from `src/i18n/`. Consumers add or override messages with `registerMessages(locale, messages)`; there is no second i18n instance and no i18next dependency.",
     "number": 5,
-    "title": "One i18next singleton"
+    "title": "One message catalogue"
   },
   {
-    "body": "Every interactive primitive passes axe-core (keyboard nav, ARIA, focus-visible, 4.5:1 contrast, `prefers-reduced-motion`). Stories double as a11y test surfaces.",
+    "body": "Every interactive primitive meets WCAG 2.2 AA (keyboard nav, ARIA, focus-visible, 4.5:1 text contrast, `prefers-reduced-motion`). It is measured by `pnpm check:frame-axe` on the component's own `/isolate/**` frame, run locally.",
     "number": 6,
-    "title": "WCAG 2.1 AA baseline"
+    "title": "WCAG 2.2 AA baseline"
   },
   {
     "body": "Every release-worthy change updates `CHANGELOG.md` under `## Unreleased` in the same PR.",
@@ -45,17 +40,12 @@
     "title": "No marketing speak"
   },
   {
-    "body": "Localised docs at `docs/i18n/<bcp47>/`; front-matter tracks staleness.",
+    "body": "Prose in `docs/` and `agent/` is English. Translated UI messages live in `docs/i18n/messages/<locale>.json`; a translation never replaces the English source.",
     "number": 10,
     "title": "English is canonical for docs"
   },
   {
-    "body": "Never push a pin to a SHA not on the submodule remote.",
-    "number": 11,
-    "title": "Submodule discipline"
-  },
-  {
-    "body": "`feat/<scope>` / `fix/<scope>` → submodule `main`. CI green + squash-merge. No direct push to `main`. `--no-verify` forbidden.",
+    "body": "Work lands on `main` through a pull request; `feat/<scope>` / `fix/<scope>` branches. CI green + squash-merge. No direct push to `main`. `--no-verify` forbidden.",
     "number": 12,
     "title": "Branch + PR workflow"
   },
@@ -65,32 +55,22 @@
     "title": "TypeScript strict"
   },
   {
-    "body": "Locked stack: Radix UI, cmdk, sonner, lucide-react, react-aria-components + `@internationalized/date`, i18next + react-i18next, class-variance-authority + clsx + tailwind-merge. New peer → ADR documenting why it's the canonical choice.",
+    "body": "The runtime stack is what `package.json` declares: react-aria-components / react-aria / react-stately, cmdk, sonner, lucide-react, @tanstack/react-table, react-day-picker, class-variance-authority + clsx + tailwind-merge. A new dependency needs an ADR saying why it is the canonical choice and why an existing one cannot do it.",
     "number": 14,
-    "title": "Every third-party library is shadcn / Radix-recommended"
+    "title": "Every third-party library is a deliberate, declared choice"
   },
   {
-    "body": "Inside a primitive `.tsx`, don't `@apply` a Tailwind utility that re-encodes a token — reference the canonical CSS class from `tokens.css` instead. Composite token-named utilities remain fine.",
+    "body": "Inside a primitive `.tsx`, don't `@apply` a Tailwind utility that re-encodes a token — reference the token (or the component's CSS class in `src/styles/`) instead. Composite token-named utilities remain fine.",
     "number": 15,
     "title": "No `@apply` re-encoding tokens"
   },
   {
-    "body": "A primitive that needs a new color / spacing / radius adds it there FIRST, then references it.",
+    "body": "A primitive that needs a new color / spacing / radius adds the token to the right tier in `src/tokens/` FIRST, then references it.",
     "number": 16,
-    "title": "CSS source-of-truth is `src/tokens/` + `src/styles/theme.css`"
-  },
-  {
-    "body": "Story set matches primitive set under each group. CI-checked via `scripts/check-stories-parity.mjs`.",
-    "number": 17,
-    "title": "`src/stories/` ↔ `src/components/` parity"
-  },
-  {
-    "body": "Every primitive has a reference page; every page maps to a primitive. CI-checked via `scripts/check-docs-parity.mjs`.",
-    "number": 18,
-    "title": "`docs/reference/<group>/` ↔ `src/components/<group>/` parity"
+    "title": "CSS source-of-truth is `src/tokens/`"
   },
   {
-    "body": "`me-service`, `forge-service`, `admin-service` never appear in source / comments / prop names. Per-deployment brand color lives at `[data-accent=\"<palette>\"]`.",
+    "body": "`me-service`, `forge-service`, `admin-service` never appear in source / comments / prop names. Per-deployment brand colour is a token override on `:root` or a scope such as `[data-tenant]` (see docs/CUSTOMER-THEMING.md), never a component fork.",
     "number": 19,
     "title": "No service-specific anything"
   },
@@ -100,57 +80,47 @@
     "title": "No \"platform-only\" exports"
   },
   {
-    "body": "`data-theme` (light / dark), `data-accent` (6 palettes), `data-density` (compact / default / comfortable), `data-font-size` (sm / base / lg / xl). Read from tokens, never hardcode values.",
+    "body": "`.dark` / light theme, `data-density` (compact / default / comfortable) and `data-font-size` (sm / base / lg) are axes the component must follow. Read from tokens, never hardcode values.",
     "number": 21,
     "title": "Every component honours every theme axis"
   },
-  {
-    "body": "Every visual literal comes from `design-handoff/ui-system/<latest-bundle>/`. Token-pin canon literals; never substitute \"close enough\". If the bundle doesn't cover a case — STOP, ask the user to mock it.",
-    "number": 22,
-    "title": "100% match to the design canon"
-  },
   {
     "body": "One concept per prop. Reuse shared vocabulary (`size`, `variant`, `color`, `tone`, `accent`, `padding`, `density`, `orientation`, `placement`, `current`, `value` / `defaultValue` / `onValueChange`, `open` / `defaultOpen` / `onOpenChange`, `justify`, `sticky`, `offset`). Before adding a new prop or token: grep for an existing one.",
     "number": 23,
     "title": "Concept-first prop API"
   },
   {
-    "body": "Defaults target `xs` (≥0px); progressive enhancement via `sm:` / `md:` / `lg:` / `xl:` / `2xl:`. Touch targets ≥ 44 × 44 px (`--touch-target-min`, does NOT scale with density). Runtime viewport via `useBreakpoint`, never `window.innerWidth`. Stories render at narrow viewport first.",
+    "body": "Defaults target `xs` (≥0px); progressive enhancement via `sm:` / `md:` / `lg:` / `xl:` / `2xl:`. Touch targets ≥ 24 × 24 px (`--touch-target-min`, WCAG 2.2 SC 2.5.8; does NOT scale with density). Runtime viewport via `useMediaQuery` / `useIsMobile` from `@godxjp/ui/hooks`, never `window.innerWidth`. Examples render at narrow viewport first.",
     "number": 24,
     "title": "Mobile-first"
   },
   {
-    "body": "When a story looks wrong, fix the primitive / CSS / token. Never paper over with a story tweak. Story-only diff without a paired primitive / CSS / token diff is rejected.",
+    "body": "When a docs example looks wrong, fix the primitive / CSS / token. Never paper over it with an example tweak. A docs-only diff without a paired primitive / CSS / token diff does not close a defect.",
     "number": 25,
-    "title": "Stories are docs; UI is the primitive"
+    "title": "Docs pages are evidence; the primitive is the product"
   },
   {
-    "body": "`dist/` ships only the consumer surface. Storybook, tests, scripts, design-handoff, `dev-probe/` stay out of npm. Every `dependencies` entry is `external` in `tsup`. Verification via `pnpm pack` + grep of `dist/`.",
+    "body": "`dist/` ships only the consumer surface. Tests, scripts, design-handoff, `dev-probe/` stay out of npm. Every `dependencies` entry is `external` in `tsup`. Verification via `pnpm pack` + grep of `dist/`.",
     "number": 26,
     "title": "Library isolation"
   },
   {
-    "body": "Primitives at `src/components/<group>/<Name>.tsx`; six canonical groups (general, layout, data-display, data-entry, feedback, navigation). Barrel = `src/components/primitives.ts` (single file). Stories + reference docs mirror the same group hierarchy.",
+    "body": "Components live at `src/components/<group>/<name>.tsx`, one folder per public subpath (`general`, `layout`, `data-display`, `data-entry`, `feedback`, `navigation`, plus the adapter groups `charts`, `query`, `react-router`). The group's `index.ts` is its barrel; docs examples under `docs/<group>/` mirror the same hierarchy.",
     "number": 27,
     "title": "Per-group folder structure"
   },
   {
-    "body": "Three classes: consumer surface (matched by `tsup` entry + `package.json::exports`), Storybook-only (`src/stories/`), build-input-only (`cn.ts`, per-group sources consumed via the barrel). No `src/lib/`, `src/utils/`, `src/internal/`, `src/clients/`, `src/screens/`. Service clients live with the composite that uses them.",
+    "body": "Two classes: consumer surface (matched by a `tsup` entry + `package.json::exports`) and build-input-only (`cn`, shared helpers in `src/lib/`, consumed through a group barrel). No `src/internal/`, `src/clients/`, `src/screens/`. Service clients live with the composite that uses them.",
     "number": 28,
     "title": "`src/` folder taxonomy"
   },
   {
     "body": "No raw `<button>` / `<input>` / hand-rolled chips when a primitive exists. HTML semantics (`<section>`, `<article>`, …) for structure are fine. Inline `style={{}}` limited to layout / positioning; no colour / radius / typography overrides.",
     "number": 29,
-    "title": "Stories consume framework primitives only"
+    "title": "Docs examples consume framework primitives only"
   },
   {
-    "body": "No opaque `<XyzDemo />` wrapper components, no zero-arg `Demo` helpers. Use `render: function StoryName() { … }` so Storybook's source panel shows runnable JSX, not `<XyzDemo />`.",
-    "number": 30,
-    "title": "Story `render` returns JSX directly"
-  },
-  {
-    "body": "One Radix base = one framework primitive. `<SimpleX>` over `<X>` is forbidden; add a prop to `<X>` instead. Composites under `src/components/composites/` that combine multiple primitives are NOT wrappers.",
+    "body": "One base = one framework primitive. A convenience wrapper that restates a base primitive under another name is forbidden; add a prop to the base instead. Composites that combine multiple primitives are NOT wrappers.",
     "number": 31,
     "title": "No nested wrapper / convenience primitives"
   },
@@ -160,14 +130,9 @@
     "title": "No redundant props"
   },
   {
-    "body": "No two names for the same export across the framework surface; no legacy aliases in stories / docs (source may keep an alias for a deprecation cycle, but the marketing surfaces use the canonical name only).",
+    "body": "No two names for the same export across the framework surface; no legacy aliases in docs or examples (source may keep an alias for a deprecation cycle, but the documentation surface uses the canonical name only).",
     "number": 33,
-    "title": "Stories / source / docs name-synchronized"
-  },
-  {
-    "body": "Storybook's react-docgen serializer strips every function value (`cell: ({row}) => <JSX/>`, `render: ({field}) => <Input/>`, `rowClassName`, `renderItem`, …) to `() => {}`. Any story whose `render` passes a function-valued prop, references a module-level helper (`Badge`, `EMPLOYEE_COLUMNS`, etc.), or uses a render-prop pattern MUST override `parameters.docs.source.code` with the literal copy-paste-ready snippet — type aliases, helper functions spelled out, column definitions with cell JSX visible, inline data array. The `render()` callback stays as-is (module-level constants are fine for runtime performance); `source.code` is the marketing surface. Skip ONLY for stories whose JSX is purely static primitives Storybook can serialize verbatim (`<Button variant=\"primary\">Click</Button>`).",
-    "number": 34,
-    "title": "Storybook source panel = real, copy-paste-ready code"
+    "title": "Docs / source name-synchronized"
   },
   {
     "body": "A `Badge` / `Badge` reads as one atomic unit. Its label must never break across lines — pin `white-space: nowrap` on the chip (done in `badge-layout.css`), especially inside narrow `DataTable` cells (スコープ / ステータス columns). If a cell is too tight, widen the column or shorten the label; never let the chip wrap.",
@@ -240,12 +205,12 @@
     "title": "Two token value forms — read the call site before you set a colour"
   },
   {
-    "body": "Hover, active, selected, checked, pressed and focus are their own tokens: 95 published (`node -e \"const t=require('./node_modules/@godxjp/ui/agent/tokens.json'); console.log(t.filter(x => /-(hover|active|selected|checked|pressed|focus)(-|$)/.test(x.name)).length)\"`), 62 of which paint a colour, an edge or an elevation. A theme that re-materialises a surface and sets only its RESTING fill ships every other state broken, and each defect is reported from a screenshot rather than by a gate: a sidebar row at dark-violet-on-violet (`--sidebar-item-active-foreground` defaults to the live `--primary-active`, src/styles/shell-layout.css:2289-2291), a Segmented hover with a dark fill under dark text (`--segmented-item-hover-background` set without `--segmented-item-hover-color`), a Topbar hover block. `--focus-ring-color` is on that list and a ring that fails 3:1 on its new ground is a WCAG 2.2 SC 1.4.11 defect, not a polish item. THE METHOD: for every component you re-theme, list its tokens (`get_component`, or `grep -- \"--<component>-\" node_modules/@godxjp/ui/dist/tokens/components/`) and set the state rows at the same time as the resting row. A state knob left at its default resolves against the LIVE role at the painting element — the correct default, and exactly why it can be wrong for you once `--accent` is no longer pale.",
+    "body": "Hover, active, selected, checked, pressed and focus are their own tokens: 95 published (`node -e \"const t=require('./node_modules/@godxjp/ui/agent/tokens.json'); console.log(t.filter(x => /-(hover|active|selected|checked|pressed|focus)(-|$)/.test(x.name)).length)\"`), 62 of which paint a colour, an edge or an elevation. A theme that re-materialises a surface and sets only its RESTING fill ships every other state broken, and each defect is reported from a screenshot rather than by a gate: a sidebar row at dark-violet-on-violet (`--sidebar-item-active-foreground` defaults to the live `--primary-active`, in `src/styles/shell-layout.css`), a Segmented hover with a dark fill under dark text (`--segmented-item-hover-background` set without `--segmented-item-hover-color`), a Topbar hover block. `--focus-ring-color` is on that list and a ring that fails 3:1 on its new ground is a WCAG 2.2 SC 1.4.11 defect, not a polish item. THE METHOD: for every component you re-theme, list its tokens (`get_component`, or `grep -- \"--<component>-\" node_modules/@godxjp/ui/dist/tokens/components/`) and set the state rows at the same time as the resting row. A state knob left at its default resolves against the LIVE role at the painting element — the correct default, and exactly why it can be wrong for you once `--accent` is no longer pale.",
     "number": 49,
     "title": "Interaction states are 95 separate tokens — resting state is not one of them"
   },
   {
-    "body": "`src/styles/base.css:261` sets `color: hsl(var(--foreground))` on `body`, which is above every scope a consumer can make, so that `var()` substitutes against the ROOT's `--foreground` exactly once and every element below inherits the already-resolved colour. A plain `<div>` carrying a theme's tokens therefore retints every SURFACE and no TEXT: measured, a title whose own computed `--foreground` was the theme's near-white still painted `rgb(36, 35, 30)`, 1.34:1 on real pixels, with every element reporting it was inside the scope (gh#881). It is the §3 freeze rule applied to a PROPERTY instead of a token, and worse there — a token can be given a knob and `color` on `body` cannot. FIX, React: wrap the region in `ThemeScope` (`@godxjp/ui/app`), which re-states `color` on its own element (src/lib/overlay-portal.tsx:270, `display: contents` so the box goes and the inheritance stays) AND on the body-level host it creates for portalled overlays (:203) — the other half, since a Dialog portals to `document.body` and would otherwise wear the root's theme. FIX, stylesheet-only scope: declare `color: hsl(var(--foreground))` on your own selector alongside the tokens; that is your element, not a selector into this package, so cardinal rule \"a consumer sets tokens, never selectors\" permits it — but it does NOT reach portalled overlays. docs/TOKEN-RESOLUTION.md §5 rule 7.",
+    "body": "`src/styles/base.css` sets `color: hsl(var(--foreground))` on `body`, which is above every scope a consumer can make, so that `var()` substitutes against the ROOT's `--foreground` exactly once and every element below inherits the already-resolved colour. A plain `<div>` carrying a theme's tokens therefore retints every SURFACE and no TEXT: measured, a title whose own computed `--foreground` was the theme's near-white still painted `rgb(36, 35, 30)`, 1.34:1 on real pixels, with every element reporting it was inside the scope (gh#881). It is the §3 freeze rule applied to a PROPERTY instead of a token, and worse there — a token can be given a knob and `color` on `body` cannot. FIX, React: wrap the region in `ThemeScope` (`@godxjp/ui/app`), which re-states `color` on its own element (`src/lib/overlay-portal.tsx`, `display: contents` so the box goes and the inheritance stays) AND on the body-level host it creates for portalled overlays — the other half, since a Dialog portals to `document.body` and would otherwise wear the root's theme. FIX, stylesheet-only scope: declare `color: hsl(var(--foreground))` on your own selector alongside the tokens; that is your element, not a selector into this package, so cardinal rule \"a consumer sets tokens, never selectors\" permits it — but it does NOT reach portalled overlays. docs/TOKEN-RESOLUTION.md §5 rule 7.",
     "number": 50,
     "title": "A scoped theme must state its own `color`"
   }

package/agent/tokens.json

@@ -1,6 +1,6 @@
 [
   {
-    "description": "Color system (HSL components) — the reference design: warm hue-60 neutral spine, GoDX violet primary (identity v2.3), 和色/wa-iro semantics. The neutral spine still carries SmartHR's values and says so per line; the PRIMARY has not been SmartHR blue since v2.3. #fdfdfb warm off-white",
+    "description": "Color system (HSL components) — the reference design: warm hue-60 neutral spine, a NEUTRAL INK primary (v32, gh#1220), 和色/wa-iro semantics. The neutral spine still carries SmartHR's values and says so per line. The GoDX violet identity is a preset now, not a default: `@godxjp/ui/themes/godx.css` restores it exactly. #fdfdfb warm off-white",
     "name": "--background",
     "tier": "foundation",
     "value": "60 33% 99%"
@@ -66,10 +66,10 @@
     "value": "48 8% 13%"
   },
   {
-    "description": "SmartHR MAIN, two lightness steps down from #0077c7 (gh#299). The published blue measures 4.62:1 as TEXT on --background — compliant, but with 0.12 of headroom, which every tint this system applies to a row then spends: the zebra stripe (muted/0.4) takes it to 4.46 and hover (muted/0.5) to 4.43. A link inside a striped table therefore failed AA while the same link on a card passed, which is not a defensible place to draw that line. 37% clears every one of those states with margin and is indistinguishable from the original side by side. GoDX violet #7A00FF — brand identity v2.3 core.action.primary.bg",
+    "description": "NEUTRAL INK (v32 decision A1, gh#1220) — ≈ zinc-900 #18181b. A neutral fits any brand and is one token to override; a blue default would itself be a brand choice. Near-white label on it: 17.4:1. The GoDX violet #7A00FF moved to `themes/godx.css`. Guarded by src/tokens/__tests__/neutral-primary-1220.test.ts.",
     "name": "--primary",
     "tier": "foundation",
-    "value": "268.7 100% 50%"
+    "value": "240 6% 10%"
   },
   {
     "description": "Foundation tokens: color, typography, raw spacing, ratio, radius, shadow.",
@@ -138,7 +138,7 @@
     "value": "30 7% 53%"
   },
   {
-    "description": "STATUS FILLS AND THE INK THAT RIDES ON THEM. The FILLS are the palette and they do not move: 若竹, 山吹, 群青, 朱 are named colours, every solid success/attention surface in every consumer is one of them, and a chip that changes hue on upgrade is a different design. What moved is the INK, and only where it failed to be readable (gh#643). Measured from these very tokens (src/tokens/__tests__/status-fill-contrast.test.ts, and confirmed in Chromium by `check:frame-axe` on /isolate/foundation-colors at 320/375/1440): role fill WAS near-white ink dark ink (48 8% 13%) success #68be8d 2.19:1 ✗ 7.08:1 ✓ attention #eb6101 3.32:1 ✗ 4.68:1 ✓ warning #f8b500 1.74:1 ✗ 8.91:1 ✓ (already dark — the precedent) primary #7a00ff 6.32:1 ✓ destructive … 6.10:1 ✓ info #4c6cb3 5.00:1 ✓ Two of the eight light-theme fills carried an ink their own lightness cannot support, and the package already knew the answer twice over: --warning-foreground has always been this same near-black on the equally pale 山吹, and the DARK theme flips --success-foreground / --attention-foreground to 48 9% 9% for exactly this reason. The light block was the outlier. REJECTED — darkening 若竹 and 朱 so the near-white ink clears 4.5:1. A fill needs luminance ≤ 0.183 for that; 若竹 sits at 0.422, so \"keep the white text\" means a different green, not a darker one. That is the palette change this deliberately is not. 若竹 #68be8d",
+    "description": "STATUS FILLS AND THE INK THAT RIDES ON THEM. The FILLS are the palette and they do not move: 若竹, 山吹, 群青, 朱 are named colours, every solid success/attention surface in every consumer is one of them, and a chip that changes hue on upgrade is a different design. What moved is the INK, and only where it failed to be readable (gh#643). Measured from these very tokens (src/tokens/__tests__/status-fill-contrast.test.ts, and confirmed in Chromium by `check:frame-axe` on /isolate/foundation-colors at 320/375/1440): role fill WAS near-white ink dark ink (48 8% 13%) success #68be8d 2.19:1 ✗ 7.08:1 ✓ attention #eb6101 3.32:1 ✗ 4.68:1 ✓ warning #f8b500 1.74:1 ✗ 8.91:1 ✓ (already dark — the precedent) primary #18181b 17.45:1 ✓ (the GoDX preset violet #7a00ff: 6.32:1) destructive … 6.10:1 ✓ info #4c6cb3 5.00:1 ✓ Two of the eight light-theme fills carried an ink their own lightness cannot support, and the package already knew the answer twice over: --warning-foreground has always been this same near-black on the equally pale 山吹, and the DARK theme flips --success-foreground / --attention-foreground to 48 9% 9% for exactly this reason. The light block was the outlier. REJECTED — darkening 若竹 and 朱 so the near-white ink clears 4.5:1. A fill needs luminance ≤ 0.183 for that; 若竹 sits at 0.422, so \"keep the white text\" means a different green, not a darker one. That is the palette change this deliberately is not. 若竹 #68be8d",
     "name": "--success",
     "tier": "foundation",
     "value": "146 40% 58%"
@@ -186,10 +186,10 @@
     "value": "48 8% 13%"
   },
   {
-    "description": "IDENTITY role — the GoDX violet, identity v2.3. This is the PRODUCT MARK colour (Logo `mark=\"godx\"` / `tone=\"success\"`, its wordmark, the email brand capsule), and it is deliberately distinct from two neighbours it keeps being confused with: · from --primary — a service re-theming its action colour must never recolour the mark. They hold the SAME VALUE today and are still separate declarations; `brand-identity-role.test.ts` asserts on the DECLARATION, not the value, that this one never reads `var(--primary)` (gh#250). · from --success — 若竹 #68be8d is the STATUS green (badges, progress, \"saved\" text) and stays exactly as it is. The mark borrowed it once, rendering the identity at #69bf8e — ΔE76 ≈ 17.5 from the identity of the day, a plainly wrong brand colour (gh#250/#214). Until v2.3 this role was 翠 emerald #009766, and the prose here described that emerald for several releases after the declaration moved to violet — an agent reading the file was told one colour and shown another. If the identity moves again, THIS COMMENT MOVES WITH IT. There is no Tailwind `bg-brand` utility on purpose: `--color-brand` is already taken by --text-brand, so identity surfaces read `hsl(var(--brand))` directly in component CSS. GoDX violet #7A00FF — brand identity v2.3. Same value as --primary today, NOT an alias of it: re-theming the action colour must still leave the identity alone, which is what brand-identity-role.test.ts checks on the DECLARATION rather than the value.",
+    "description": "IDENTITY role — the PRODUCT MARK colour (Logo `tone=\"success\"`, its wordmark, the email brand capsule). Neutral ink by default since v32 (gh#1220); the GoDX preset (`themes/godx.css`) sets it back to the violet of identity v2.3. It is deliberately distinct from two neighbours it keeps being confused with: · from --primary — a service re-theming its action colour must never recolour the mark. They hold the SAME VALUE by default and are still separate declarations; `brand-identity-role.test.ts` asserts on the DECLARATION, not the value, that this one never reads `var(--primary)` (gh#250). · from --success — 若竹 #68be8d is the STATUS green (badges, progress, \"saved\" text) and stays exactly as it is. The mark borrowed it once, rendering the identity at #69bf8e — ΔE76 ≈ 17.5 from the identity of the day, a plainly wrong brand colour (gh#250/#214). If the identity moves again, THIS COMMENT MOVES WITH IT. There is no Tailwind `bg-brand` utility on purpose: `--color-brand` is already taken by --text-brand, so identity surfaces read `hsl(var(--brand))` directly in component CSS. neutral ink. Same value as --primary by default, NOT an alias of it: re-theming the action colour must still leave the identity alone, which is what brand-identity-role.test.ts checks on the DECLARATION rather than the value.",
     "name": "--brand",
     "tier": "foundation",
-    "value": "268.7 100% 50%"
+    "value": "240 6% 10%"
   },
   {
     "description": "Foundation tokens: color, typography, raw spacing, ratio, radius, shadow.",
@@ -834,13 +834,7 @@
     "value": "initial"
   },
   {
-    "description": "h5 exists for antd's `Typography.Title level={5}`; `Heading` still stops at 4. It takes the next step DOWN the same scale rather than a new number — see TitleLevelProp. = the --font-size-2xs step — ≈ 11.1px (antd Title only)",
-    "name": "--heading-h5",
-    "tier": "foundation",
-    "value": "initial"
-  },
-  {
-    "description": "Foundation tokens: color, typography, raw spacing, ratio, radius, shadow.",
+    "description": "h5 exists for antd's `Typography.Title level={5}`; `Heading` still stops at 4. It takes the next step DOWN the same scale rather than a new number — see TitleLevelProp.",
     "name": "--font-weight-normal",
     "tier": "foundation",
     "value": "400"
@@ -1290,28 +1284,28 @@
     "value": "initial"
   },
   {
-    "description": "THE STEPS, BY LABEL POLARITY. A state steps the fill AWAY from the label that rides on it, so its contrast can only rise: lightness is monotonic in every sRGB channel at fixed H and S. darken — for a LIGHT label (the light theme's default): the kit's two steps below the bg, identity v2.3 #6400D4 (hover) and #5200B0 (action.primary.pressed), hue-snapped. lighten — for a DARK label (the dark theme's default): the kit's dark hover #E8DAFF one step up, and pressed one step further up — UNLESS that runs off the top of the ramp. Past 83.4% L the second step would land at 98.5%+ (#fbf7ff for our seed, 1.056:1 from white — the brand is simply gone), so pressed reflects to one step BELOW the seed instead. `clamp(0, (l - 83.4) * 1000, 1)` is that switch, 0 or 1. A reflected fill is still ≥77.6% L, which clears 4.5:1 on any label darker than luminance 0.032. A theme picks the pair for its conventional label below; a service whose label polarity is the other way round (a light seed with dark text in the light theme) points the two knobs at the other pair — `applyPrimaryColor` does exactly that from the label it chooses.",
+    "description": "AT THE ENDS OF THE RAMP THE STEP TURNS AROUND (v32, gh#1220). A seed darker than 12% L has no room below it: the neutral ink (240 6% 10%) stepped to 1.6% for hover and 0% for pressed, 1.16:1 from rest, which reads as no hover at all. Below 12% L hover goes UP 9.6 and pressed UP 4.8 (ink: 19.6% / 14.8%). The bound is 12, not 20, and the up-steps are small, because a light label must stay AA: the worst hue (green, highest luminance per L) peaks at 21.6% L, still ≥ 6:1 under white — at 20 / +15.5 the dense sweep measured #004400 pressed at 4.06:1. The mirror case: above 94% L (the dark theme's near-white ink, 98%) hover ran into 100% (1.04:1), so both lighten steps turn DOWN (92.2% / 86.4% for the ink). Mid-ramp seeds (the GoDX violet, 50% and 86.9%) take exactly the old steps. Brand INKS (`--text-*`) keep their own formula below: an ink sits on a light surface and must step away from it, whatever the fill does.",
     "name": "--primary-hover-darken-channels",
     "tier": "semantic",
-    "value": "h s calc(l - 8.4)"
+    "value": "h s calc(l - 8.4 + 18 * clamp(0, (12 - l) * 1000, 1))"
   },
   {
     "description": "DERIVED COLOUR — the interaction states that hang off the authored seeds.",
     "name": "--primary-active-darken-channels",
     "tier": "semantic",
-    "value": "h s calc(l - 15.5)"
+    "value": "h s calc(l - 15.5 + 20.3 * clamp(0, (12 - l) * 1000, 1))"
   },
   {
     "description": "DERIVED COLOUR — the interaction states that hang off the authored seeds.",
     "name": "--primary-hover-lighten-channels",
     "tier": "semantic",
-    "value": "h s calc(l + 5.8)"
+    "value": "h s calc(l + 5.8 - 11.6 * clamp(0, (l - 94) * 1000, 1))"
   },
   {
     "description": "DERIVED COLOUR — the interaction states that hang off the authored seeds.",
     "name": "--primary-active-lighten-channels",
     "tier": "semantic",
-    "value": "h s calc(l + 11.6 - 17.4 * clamp(0, (l - 83.4) * 1000, 1))"
+    "value": "h s calc(l + 11.6 - 17.4 * clamp(0, (l - 83.4) * 1000, 1) - 5.8 * clamp(0, (l - 94) * 1000, 1))"
   },
   {
     "description": "DERIVED COLOUR — the interaction states that hang off the authored seeds.",
@@ -1365,19 +1359,19 @@
     "description": "Light: one step DOWN the ramp from the action colour — the same step `--primary-hover` takes, so the link sits where identity v2.3 puts it and moves when the seed does.",
     "name": "--text-link-channels",
     "tier": "semantic",
-    "value": "var(--primary-hover-channels)"
+    "value": "h s calc(l - 8.4)"
   },
   {
     "description": "DERIVED COLOUR — the interaction states that hang off the authored seeds.",
     "name": "--text-brand-channels",
     "tier": "semantic",
-    "value": "var(--primary-hover-channels)"
+    "value": "h s calc(l - 8.4)"
   },
   {
     "description": "The pressed ink is two steps down — identity v2.3 action.primary.pressed (#5200B0).",
     "name": "--text-primary-channels",
     "tier": "semantic",
-    "value": "var(--primary-active-channels)"
+    "value": "h s calc(l - 15.5)"
   },
   {
     "description": "#c44b4d",
@@ -1710,7 +1704,7 @@
     "value": "48rem"
   },
   {
-    "description": "THE MARKETING MEASURE (gh#831). A landing page is not a reading column: two unrelated website showcases each hand-wrote a shell cap (1200px and 1140px) because the widest name here was `medium` at 768px. 72rem sits between the two measured values and is a step the industry already ships (Tailwind `--container-6xl`); the wide-container cluster runs 1136–1320px (Radix Container 4 = 1136, Primer/Tailwind = 1280, Bootstrap = 1320). No `PageContainer` branch reads it yet — see docs/roadmap/website-components.md §5.9 — so today this is the VOCABULARY a marketing composition caps its own shell with, as `--gradient-hero` is. 1152px outer → 1104px surface",
+    "description": "THE MARKETING MEASURE (gh#831). A landing page is not a reading column: two unrelated website showcases each hand-wrote a shell cap (1200px and 1140px) because the widest name here was `medium` at 768px. 72rem sits between the two measured values and is a step the industry already ships (Tailwind `--container-6xl`); the wide-container cluster runs 1136–1320px (Radix Container 4 = 1136, Primer/Tailwind = 1280, Bootstrap = 1320). No `PageContainer` branch reads it yet (the website-components roadmap, §5.9), so today this is the VOCABULARY a marketing composition caps its own shell with, as `--gradient-hero` is. 1152px outer → 1104px surface",
     "name": "--page-measure-wide",
     "tier": "semantic",
     "value": "72rem"
@@ -2892,7 +2886,7 @@
     "value": "var(--space-2)"
   },
   {
-    "description": "ChatBubble / ChatBubbleList component tokens — one message in a conversation, and the feed it lives in (docs/roadmap/ai-chat-components.md §2/§3). NAMING NOTE: the roadmap spelled the surface knob `--chat-bubble-surface`. `surface` is not one of the property words `check:token-tiers` accepts for the `--{component}-{part}-{property}` shape, so the knob ships as `--chat-bubble-background` — the same word every other component tier uses for the same role (`--card-background`, `--list-row-unread-background`).",
+    "description": "ChatBubble / ChatBubbleList component tokens (@godxjp/chat since v32) — one message in a conversation, and the feed it lives in. NAMING NOTE: the roadmap spelled the surface knob `--chat-bubble-surface`. `surface` is not one of the property words `check:token-tiers` accepts for the `--{component}-{part}-{property}` shape, so the knob ships as `--chat-bubble-background` — the same word every other component tier uses for the same role (`--card-background`, `--list-row-unread-background`).",
     "name": "--chat-bubble-padding-inline",
     "tier": "component",
     "value": "var(--space-3)"
@@ -2940,7 +2934,7 @@
     "value": "0.08"
   },
   {
-    "description": "ChatBubble / ChatBubbleList component tokens — one message in a conversation, and the feed it lives in (docs/roadmap/ai-chat-components.md §2/§3). NAMING NOTE: the roadmap spelled the surface knob `--chat-bubble-surface`. `surface` is not one of the property words `check:token-tiers` accepts for the `--{component}-{part}-{property}` shape, so the knob ships as `--chat-bubble-background` — the same word every other component tier uses for the same role (`--card-background`, `--list-row-unread-background`).",
+    "description": "ChatBubble / ChatBubbleList component tokens (@godxjp/chat since v32) — one message in a conversation, and the feed it lives in. NAMING NOTE: the roadmap spelled the surface knob `--chat-bubble-surface`. `surface` is not one of the property words `check:token-tiers` accepts for the `--{component}-{part}-{property}` shape, so the knob ships as `--chat-bubble-background` — the same word every other component tier uses for the same role (`--card-background`, `--list-row-unread-background`).",
     "name": "--chat-bubble-tone-border-alpha",
     "tier": "component",
     "value": "0.35"
@@ -2952,7 +2946,7 @@
     "value": "initial"
   },
   {
-    "description": "ChatBubble / ChatBubbleList component tokens — one message in a conversation, and the feed it lives in (docs/roadmap/ai-chat-components.md §2/§3). NAMING NOTE: the roadmap spelled the surface knob `--chat-bubble-surface`. `surface` is not one of the property words `check:token-tiers` accepts for the `--{component}-{part}-{property}` shape, so the knob ships as `--chat-bubble-background` — the same word every other component tier uses for the same role (`--card-background`, `--list-row-unread-background`).",
+    "description": "ChatBubble / ChatBubbleList component tokens (@godxjp/chat since v32) — one message in a conversation, and the feed it lives in. NAMING NOTE: the roadmap spelled the surface knob `--chat-bubble-surface`. `surface` is not one of the property words `check:token-tiers` accepts for the `--{component}-{part}-{property}` shape, so the knob ships as `--chat-bubble-background` — the same word every other component tier uses for the same role (`--card-background`, `--list-row-unread-background`).",
     "name": "--chat-bubble-end-foreground",
     "tier": "component",
     "value": "initial"
@@ -3192,7 +3186,7 @@
     "value": "calc(var(--icon-size-sm) * var(--scaling))"
   },
   {
-    "description": "VALIDATION STATUS — antd's `status` axis (docs/DESIGN-AUTHORITY.md names Ant Design the taxonomy authority). Only the FOCUS half is a knob: the boundary itself has to be painted from a Tailwind utility, because `border-input` sits in a later cascade layer than this file's component rules and would win over any of them (measured in Chromium — see components/data-entry/control-appearance.ts). The error boundary therefore reuses the role `aria-invalid:border-destructive` already paints, and cannot drift into a second red. The warning halo borrows the ERROR halo's alpha rather than inventing a second opacity: antd derives both from one `colorXxxOutline` recipe and the generated file carries only the error one (scripts/gen-antd-tokens.mjs).",
+    "description": "VALIDATION STATUS — antd's `status` axis (docs/DESIGN-AUTHORITY.md names Ant Design the taxonomy authority). Only the FOCUS half is a knob: the boundary itself has to be painted from a Tailwind utility, because `border-input` sits in a later cascade layer than this file's component rules and would win over any of them (measured in Chromium — see components/data-entry/control-appearance.ts). The error boundary therefore reuses the role `aria-invalid:border-destructive` already paints, and cannot drift into a second red. The warning halo borrows the ERROR halo's alpha rather than inventing a second opacity: antd derives both from one `colorXxxOutline` recipe, and only the error one is defined in this tier.",
     "name": "--control-status-warning-border-color",
     "tier": "component",
     "value": "var(--warning)"
@@ -7272,41 +7266,17 @@
     "value": "5rem"
   },
   {
-    "description": "SKELETON · antd 6 parity (ant-design/components/skeleton/style/index.ts). antd derives every element box from `controlHeight` and its ±steps; the same boxes here read the `--control-height` tier, so a skeleton button is exactly as tall as the Button it stands in for and follows density with it. The two RATIOS are antd's own multipliers (button = 2× the box, input = 5×); they are unitless on purpose — a service widens the stand-in without leaving the height tier. gh#888 — φ tier freezes at :root; default = calc(var(--radius) / var(--radius-ratio) / var(--radius-ratio))",
+    "description": "SKELETON · antd 6 parity (ant-design/components/skeleton/style/index.ts). antd derives every element box from `controlHeight` and its ±steps; the same boxes here read the `--control-height` tier, so a skeleton input is exactly as tall as the Input it stands in for and follows density with it. The RATIO is antd's own multiplier (input = 5× the box); it is unitless on purpose — a service widens the stand-in without leaving the height tier. gh#888 — φ tier freezes at :root; default = calc(var(--radius) / var(--radius-ratio) / var(--radius-ratio))",
     "name": "--skeleton-element-radius",
     "tier": "component",
     "value": "initial"
   },
-  {
-    "description": "Feedback primitive tokens: dialog, alert, empty state.",
-    "name": "--skeleton-button-width-ratio",
-    "tier": "component",
-    "value": "2"
-  },
   {
     "description": "Feedback primitive tokens: dialog, alert, empty state.",
     "name": "--skeleton-input-width-ratio",
     "tier": "component",
     "value": "5"
   },
-  {
-    "description": "antd's node/image square is `controlHeight * 1.5 * 2`.",
-    "name": "--skeleton-node-size",
-    "tier": "component",
-    "value": "calc(var(--control-height) * 3)"
-  },
-  {
-    "description": "Feedback primitive tokens: dialog, alert, empty state.",
-    "name": "--skeleton-image-glyph-size",
-    "tier": "component",
-    "value": "var(--icon-size-4xl)"
-  },
-  {
-    "description": "Role-mirror (#44): `initial` so the glyph re-resolves under a scoped theme. Default = hsl(var(--muted-foreground) / 0.4).",
-    "name": "--skeleton-image-glyph-color",
-    "tier": "component",
-    "value": "initial"
-  },
   {
     "description": "ARTICLE rhythm. antd: avatar gutter = `padding` (16), title offset beside an avatar = `marginSM` (12), title→paragraph = `controlHeightSM` (24), line→line = `controlHeightXS` (16). antd's fourth value — 28px (`marginLG + marginXXS`) for title→paragraph WITH an avatar — is not a step of this repo's spacing scale (it goes 24 → 32), and docs/DESIGN-AUTHORITY.md says take a step or leave it rather than invent a number, so both cases take the 24px step.",
     "name": "--skeleton-article-avatar-gap",
@@ -9708,25 +9678,25 @@
     "value": "13rem"
   },
   {
-    "description": "ORG CHART — boxes joined by lines, top-down (`src/components/data-display/org-chart.tsx`). Every length the chart paints is a knob (cardinal rule #45) and the defaults are the quiet reading (#44): a hairline connector in the border hue, a card-coloured box with the hairline edge every other surface here has. An `agent` box differs by its STROKE STYLE only (dashed), so a theme that retunes the edge colour retunes both kinds at once. ROLE-MIRROR KNOBS ARE `initial`, WITH THE DEFAULT AT THE CALL SITE (docs/TOKENS.md · \"Role-mirror knobs MUST be `initial`\"), so a scoped `[data-tenant]` / `.dark` override reaches them instead of freezing at `:root`.",
+    "description": "ORG CHART — boxes joined by lines, top-down (`src/lab/org-chart.tsx`). Every length the chart paints is a knob (cardinal rule #45) and the defaults are the quiet reading (#44): a hairline connector in the border hue, a card-coloured box with the hairline edge every other surface here has. An `agent` box differs by its STROKE STYLE only (dashed), so a theme that retunes the edge colour retunes both kinds at once. ROLE-MIRROR KNOBS ARE `initial`, WITH THE DEFAULT AT THE CALL SITE (docs/TOKENS.md · \"Role-mirror knobs MUST be `initial`\"), so a scoped `[data-tenant]` / `.dark` override reaches them instead of freezing at `:root`.",
     "name": "--org-chart-node-padding-block",
     "tier": "component",
     "value": "var(--space-3)"
   },
   {
-    "description": "ORG CHART — boxes joined by lines, top-down (`src/components/data-display/org-chart.tsx`). Every length the chart paints is a knob (cardinal rule #45) and the defaults are the quiet reading (#44): a hairline connector in the border hue, a card-coloured box with the hairline edge every other surface here has. An `agent` box differs by its STROKE STYLE only (dashed), so a theme that retunes the edge colour retunes both kinds at once. ROLE-MIRROR KNOBS ARE `initial`, WITH THE DEFAULT AT THE CALL SITE (docs/TOKENS.md · \"Role-mirror knobs MUST be `initial`\"), so a scoped `[data-tenant]` / `.dark` override reaches them instead of freezing at `:root`.",
+    "description": "ORG CHART — boxes joined by lines, top-down (`src/lab/org-chart.tsx`). Every length the chart paints is a knob (cardinal rule #45) and the defaults are the quiet reading (#44): a hairline connector in the border hue, a card-coloured box with the hairline edge every other surface here has. An `agent` box differs by its STROKE STYLE only (dashed), so a theme that retunes the edge colour retunes both kinds at once. ROLE-MIRROR KNOBS ARE `initial`, WITH THE DEFAULT AT THE CALL SITE (docs/TOKENS.md · \"Role-mirror knobs MUST be `initial`\"), so a scoped `[data-tenant]` / `.dark` override reaches them instead of freezing at `:root`.",
     "name": "--org-chart-node-padding-inline",
     "tier": "component",
     "value": "var(--space-3)"
   },
   {
-    "description": "ORG CHART — boxes joined by lines, top-down (`src/components/data-display/org-chart.tsx`). Every length the chart paints is a knob (cardinal rule #45) and the defaults are the quiet reading (#44): a hairline connector in the border hue, a card-coloured box with the hairline edge every other surface here has. An `agent` box differs by its STROKE STYLE only (dashed), so a theme that retunes the edge colour retunes both kinds at once. ROLE-MIRROR KNOBS ARE `initial`, WITH THE DEFAULT AT THE CALL SITE (docs/TOKENS.md · \"Role-mirror knobs MUST be `initial`\"), so a scoped `[data-tenant]` / `.dark` override reaches them instead of freezing at `:root`.",
+    "description": "ORG CHART — boxes joined by lines, top-down (`src/lab/org-chart.tsx`). Every length the chart paints is a knob (cardinal rule #45) and the defaults are the quiet reading (#44): a hairline connector in the border hue, a card-coloured box with the hairline edge every other surface here has. An `agent` box differs by its STROKE STYLE only (dashed), so a theme that retunes the edge colour retunes both kinds at once. ROLE-MIRROR KNOBS ARE `initial`, WITH THE DEFAULT AT THE CALL SITE (docs/TOKENS.md · \"Role-mirror knobs MUST be `initial`\"), so a scoped `[data-tenant]` / `.dark` override reaches them instead of freezing at `:root`.",
     "name": "--org-chart-node-gap",
     "tier": "component",
     "value": "var(--space-3)"
   },
   {
-    "description": "ORG CHART — boxes joined by lines, top-down (`src/components/data-display/org-chart.tsx`). Every length the chart paints is a knob (cardinal rule #45) and the defaults are the quiet reading (#44): a hairline connector in the border hue, a card-coloured box with the hairline edge every other surface here has. An `agent` box differs by its STROKE STYLE only (dashed), so a theme that retunes the edge colour retunes both kinds at once. ROLE-MIRROR KNOBS ARE `initial`, WITH THE DEFAULT AT THE CALL SITE (docs/TOKENS.md · \"Role-mirror knobs MUST be `initial`\"), so a scoped `[data-tenant]` / `.dark` override reaches them instead of freezing at `:root`.",
+    "description": "ORG CHART — boxes joined by lines, top-down (`src/lab/org-chart.tsx`). Every length the chart paints is a knob (cardinal rule #45) and the defaults are the quiet reading (#44): a hairline connector in the border hue, a card-coloured box with the hairline edge every other surface here has. An `agent` box differs by its STROKE STYLE only (dashed), so a theme that retunes the edge colour retunes both kinds at once. ROLE-MIRROR KNOBS ARE `initial`, WITH THE DEFAULT AT THE CALL SITE (docs/TOKENS.md · \"Role-mirror knobs MUST be `initial`\"), so a scoped `[data-tenant]` / `.dark` override reaches them instead of freezing at `:root`.",
     "name": "--org-chart-node-text-gap",
     "tier": "component",
     "value": "var(--space-1)"
@@ -9768,7 +9738,7 @@
     "value": "initial"
   },
   {
-    "description": "ORG CHART — boxes joined by lines, top-down (`src/components/data-display/org-chart.tsx`). Every length the chart paints is a knob (cardinal rule #45) and the defaults are the quiet reading (#44): a hairline connector in the border hue, a card-coloured box with the hairline edge every other surface here has. An `agent` box differs by its STROKE STYLE only (dashed), so a theme that retunes the edge colour retunes both kinds at once. ROLE-MIRROR KNOBS ARE `initial`, WITH THE DEFAULT AT THE CALL SITE (docs/TOKENS.md · \"Role-mirror knobs MUST be `initial`\"), so a scoped `[data-tenant]` / `.dark` override reaches them instead of freezing at `:root`.",
+    "description": "ORG CHART — boxes joined by lines, top-down (`src/lab/org-chart.tsx`). Every length the chart paints is a knob (cardinal rule #45) and the defaults are the quiet reading (#44): a hairline connector in the border hue, a card-coloured box with the hairline edge every other surface here has. An `agent` box differs by its STROKE STYLE only (dashed), so a theme that retunes the edge colour retunes both kinds at once. ROLE-MIRROR KNOBS ARE `initial`, WITH THE DEFAULT AT THE CALL SITE (docs/TOKENS.md · \"Role-mirror knobs MUST be `initial`\"), so a scoped `[data-tenant]` / `.dark` override reaches them instead of freezing at `:root`.",
     "name": "--org-chart-node-font-size",
     "tier": "component",
     "value": "var(--font-size-sm, var(--font-size-base))"
@@ -9786,7 +9756,7 @@
     "value": "var(--space-8)"
   },
   {
-    "description": "ORG CHART — boxes joined by lines, top-down (`src/components/data-display/org-chart.tsx`). Every length the chart paints is a knob (cardinal rule #45) and the defaults are the quiet reading (#44): a hairline connector in the border hue, a card-coloured box with the hairline edge every other surface here has. An `agent` box differs by its STROKE STYLE only (dashed), so a theme that retunes the edge colour retunes both kinds at once. ROLE-MIRROR KNOBS ARE `initial`, WITH THE DEFAULT AT THE CALL SITE (docs/TOKENS.md · \"Role-mirror knobs MUST be `initial`\"), so a scoped `[data-tenant]` / `.dark` override reaches them instead of freezing at `:root`.",
+    "description": "ORG CHART — boxes joined by lines, top-down (`src/lab/org-chart.tsx`). Every length the chart paints is a knob (cardinal rule #45) and the defaults are the quiet reading (#44): a hairline connector in the border hue, a card-coloured box with the hairline edge every other surface here has. An `agent` box differs by its STROKE STYLE only (dashed), so a theme that retunes the edge colour retunes both kinds at once. ROLE-MIRROR KNOBS ARE `initial`, WITH THE DEFAULT AT THE CALL SITE (docs/TOKENS.md · \"Role-mirror knobs MUST be `initial`\"), so a scoped `[data-tenant]` / `.dark` override reaches them instead of freezing at `:root`.",
     "name": "--org-chart-sibling-gap",
     "tier": "component",
     "value": "var(--space-4)"

package/agent/vocabulary.json

@@ -171,11 +171,11 @@
     ]
   },
   {
-    "concept": "Named hosted-identity FLOW MEASURE for AuthShell — the card max-width plus the desktop and mobile page gutters, all owned by component tokens.",
+    "concept": "Named hosted-identity FLOW MEASURE for the auth CenteredShell (`variant=\"auth\"`) — the card max-width plus the desktop and mobile page gutters, all owned by component tokens.",
     "name": "AuthShellPresetProp",
-    "notes": "Orthogonal to AuthShell's `variant` (which owns control density + heading size) and applied after it, so `variant=\"canonical\" preset=\"device-authorization\"` composes. device-authorization = 380px card / 5px inline gutter at 390; context-selection = 25rem card, edge-to-edge on mobile. Selecting a preset REPLACES any consumer-side --auth-shell-card-max-width override — a page-local width is the anti-pattern these presets exist to remove.",
+    "notes": "Orthogonal to the auth CenteredShell's `variant` (which owns control density + heading size) and applied after it, so `variant=\"auth-canonical\" preset=\"device-authorization\"` composes. device-authorization = 380px card / 5px inline gutter at 390; context-selection = 25rem card, edge-to-edge on mobile. Selecting a preset REPLACES any consumer-side --auth-shell-card-max-width override — a page-local width is the anti-pattern these presets exist to remove.",
     "usedBy": [
-      "AuthShell"
+      "CenteredShell"
     ],
     "values": [
       "default",

package/dist/app/app-provider.d.ts

@@ -2,14 +2,16 @@ import * as React from "react";
 import { type AppDateFormat, type AppLocale, type AppTimeFormat, type AppTimezone } from "./types.js";
 import type { AppContextValue, AppProviderProp } from "../props/components/app.prop.js";
 export type { AppProviderProp, AppContextValue } from "../props/components/app.prop.js";
-export declare function AppProvider({ children, defaultLocale, fallbackLocale, defaultTimezone, systemTimezone, defaultTimeFormat, defaultDateFormat, timezoneOptions, storageKey, persist, theme: initialTheme, brand: initialBrand, density: initialDensity, fontSize: initialFontSize, scaling: initialScaling, emitFieldNames, onLocaleChange, onTimezoneChange, onTimeFormatChange, onDateFormatChange, onThemeChange, onBrandChange, onDensityChange, onFontSizeChange, onScalingChange, }: AppProviderProp): React.JSX.Element;
+/** `AppProvider`'s props (`preset` included since v32, gh#1219 / gh#1220). */
+export type AppProviderProps = AppProviderProp;
+export declare function AppProvider({ children, preset, defaultLocale: defaultLocaleProp, fallbackLocale, defaultTimezone: defaultTimezoneProp, systemTimezone, defaultTimeFormat, defaultDateFormat, timezoneOptions, storageKey, persist, theme: initialTheme, brand: initialBrand, density: initialDensity, fontSize: initialFontSize, scaling: initialScaling, emitFieldNames, onLocaleChange, onTimezoneChange, onTimeFormatChange, onDateFormatChange, onThemeChange, onBrandChange, onDensityChange, onFontSizeChange, onScalingChange, }: AppProviderProps): React.JSX.Element;
 export declare function useAppContext(): AppContextValue;
 /** Returns null outside AppProvider — used by pickers for optional context. */
 export declare function useOptionalAppContext(): AppContextValue | null;
 /** Shorthand for `{ locale, setLocale }`. */
 export declare function useAppLocale(): {
-    locale: AppLocale;
-    fallbackLocale: AppLocale;
+    locale: string;
+    fallbackLocale: string;
     setLocale: (locale: AppLocale) => void;
     dateFnsLocale: import("date-fns").Locale;
     dayPickerLocale: Partial<import("react-day-picker").DayPickerLocale>;