@godxjp/ui 28.8.0 → 28.10.0

package/dist/tokens/components/table.css

@@ -6,7 +6,8 @@
   --table-row-height-comfortable: var(--band-height-xl);
   --table-row-height: calc(var(--table-row-height-default) * var(--scaling));
   --table-cell-padding-y: var(--space-2);
-  --table-cell-space-x: var(--control-padding-x);
+
+  --table-cell-space-x: initial;
 
   --table-cell-indent-space-step: var(--space-4);
 
@@ -15,7 +16,7 @@
   --table-pagination-padding-x: initial;
 
   --table-surface-min-inline-size: 640px;
-  --table-head-font-size: var(--font-size-xs);
+  --table-head-font-size: var(--font-size-xs, calc(var(--font-size-base) / var(--font-size-ratio)));
 
   --table-head-font-weight: var(--font-weight-medium);
 
@@ -59,7 +60,10 @@
   --table-action-collection-meta-width-floor: 5rem;
 
   --table-action-collection-flex-width-floor: 5rem;
-  --table-action-collection-font-size-compact: var(--font-size-xs);
+  --table-action-collection-font-size-compact: var(
+    --font-size-xs,
+    calc(var(--font-size-base) / var(--font-size-ratio))
+  );
   --table-action-collection-cell-space-x-compact: var(--space-2);
   --table-action-collection-cell-padding-y-compact: var(--space-2);
   --table-action-collection-row-height-compact: var(--table-row-height-compact);
@@ -72,13 +76,16 @@
   --table-stacked-collection-card-padding-x: var(--space-inline-md);
   --table-stacked-collection-card-gap: var(--space-stack-sm);
   --table-stacked-collection-cell-padding-y: var(--space-stack-xs);
-  --table-stacked-collection-label-font-size: var(--font-size-xs);
+  --table-stacked-collection-label-font-size: var(
+    --font-size-xs,
+    calc(var(--font-size-base) / var(--font-size-ratio))
+  );
 
   --table-select-column-width: 2.5rem;
   --table-sort-icon-size: var(--icon-size-xs);
   --table-toolbar-icon-size: var(--icon-size-md);
   --table-pagination-icon-size: var(--icon-size-md);
-  --table-pagination-font-size: var(--font-size-sm);
+  --table-pagination-font-size: var(--font-size-sm, var(--font-size-base));
 
   --table-skeleton-check-size: 1rem;
 
@@ -86,7 +93,7 @@
   --table-skeleton-line-height: var(--table-skeleton-line-block-size);
   --table-skeleton-radius: var(--radius-sm);
 
-  --table-font-size: var(--font-size-sm);
+  --table-font-size: var(--font-size-sm, var(--font-size-base));
 
   --table-line-height: calc(1.25 / 0.875);
 

package/dist/tokens/components/thought-chain.css

@@ -7,7 +7,10 @@
   --thought-chain-body-gap: var(--space-1);
 
   --thought-chain-icon-size: var(--band-height-sm);
-  --thought-chain-icon-font-size: var(--font-size-xs);
+  --thought-chain-icon-font-size: var(
+    --font-size-xs,
+    calc(var(--font-size-base) / var(--font-size-ratio))
+  );
   --thought-chain-icon-radius: var(--radius-pill);
 
   --thought-chain-icon-background: initial;

package/dist/tokens/components/toggle.css

@@ -3,7 +3,10 @@
 
   --toggle-count-min-width: var(--space-4);
   --toggle-count-space-inline: var(--space-1);
-  --toggle-count-font-size: var(--font-size-xs);
+  --toggle-count-font-size: var(
+    --font-size-xs,
+    calc(var(--font-size-base) / var(--font-size-ratio))
+  );
   --toggle-count-radius: var(--radius-pill);
 
   --toggle-count-gap: 0;

package/dist/tokens/components/tree.css

@@ -9,7 +9,7 @@
   --tree-node-padding-inline: var(--space-2);
   --tree-node-gap: var(--space-2);
   --tree-node-radius: var(--radius-sm);
-  --tree-node-font-size: var(--font-size-sm);
+  --tree-node-font-size: var(--font-size-sm, var(--font-size-base));
 
   --tree-switcher-size: 1.25rem;
 

package/dist/tokens/components/upload.css

@@ -7,17 +7,26 @@
   --upload-dropzone-border-width: var(--stroke-md);
   --upload-dropzone-icon-size: var(--icon-size-3xl);
   --upload-dropzone-hint-space-block-start: var(--space-3);
-  --upload-dropzone-hint-font-size: var(--font-size-sm);
+  --upload-dropzone-hint-font-size: var(--font-size-sm, var(--font-size-base));
   --upload-dropzone-meta-space-block-start: var(--space-1);
-  --upload-dropzone-meta-font-size: var(--font-size-xs);
+  --upload-dropzone-meta-font-size: var(
+    --font-size-xs,
+    calc(var(--font-size-base) / var(--font-size-ratio))
+  );
 
   --upload-tile-size: 6rem;
   --upload-tile-radius: var(--radius-md);
   --upload-tile-space-gap: var(--space-3);
   --upload-tile-icon-size: var(--icon-size-xl);
   --upload-tile-label-space-block-start: var(--space-1);
-  --upload-tile-label-font-size: var(--font-size-xs);
-  --upload-tile-overlay-font-size: var(--font-size-xs);
+  --upload-tile-label-font-size: var(
+    --font-size-xs,
+    calc(var(--font-size-base) / var(--font-size-ratio))
+  );
+  --upload-tile-overlay-font-size: var(
+    --font-size-xs,
+    calc(var(--font-size-base) / var(--font-size-ratio))
+  );
 
   --upload-overlay-background: initial;
   --upload-overlay-alpha: 70%;
@@ -33,14 +42,17 @@
 
   --upload-picture-icon-size: var(--icon-size-2xl);
   --upload-picture-empty-label-space-block-start: var(--space-2);
-  --upload-picture-empty-label-font-size: var(--font-size-sm);
-  --upload-picture-overlay-font-size: var(--font-size-sm);
+  --upload-picture-empty-label-font-size: var(--font-size-sm, var(--font-size-base));
+  --upload-picture-overlay-font-size: var(--font-size-sm, var(--font-size-base));
 
   --upload-picture-badge-radius: var(--radius-md);
   --upload-picture-badge-offset: var(--space-2);
   --upload-picture-badge-space-inline: var(--space-2);
   --upload-picture-badge-space-block: 0.125rem;
-  --upload-picture-badge-font-size: var(--font-size-xs);
+  --upload-picture-badge-font-size: var(
+    --font-size-xs,
+    calc(var(--font-size-base) / var(--font-size-ratio))
+  );
 
   --upload-avatar-size: 6rem;
 
@@ -57,14 +69,14 @@
   --upload-draft-space-block: var(--space-2);
   --upload-draft-space-gap: var(--space-2);
   --upload-draft-radius: var(--radius-md);
-  --upload-draft-font-size: var(--font-size-sm);
+  --upload-draft-font-size: var(--font-size-sm, var(--font-size-base));
   --upload-draft-icon-size: var(--icon-size-sm);
 
   --upload-row-space-inline: var(--space-3);
   --upload-row-space-block: var(--space-2);
   --upload-row-space-gap: var(--space-3);
   --upload-row-radius: var(--radius-md);
-  --upload-row-font-size: var(--font-size-sm);
+  --upload-row-font-size: var(--font-size-sm, var(--font-size-base));
   --upload-row-icon-size: var(--icon-size-md);
 
   --upload-crop-dialog-max-width: 24rem;

package/dist/tokens/foundation.css

@@ -146,37 +146,27 @@
 
   --font-size-base: 0.875rem;
   --font-size-ratio: 1.1227;
-  --font-size-2xs: calc(
-    var(--font-size-base) / var(--font-size-ratio) / var(--font-size-ratio)
-  );
-  --font-size-xs: calc(var(--font-size-base) / var(--font-size-ratio));
-  --font-size-sm: var(--font-size-base);
-  --font-size-lg: calc(
-    var(--font-size-base) * var(--font-size-ratio) * var(--font-size-ratio)
-  );
-  --font-size-xl: calc(var(--font-size-lg) * var(--font-size-ratio));
-  --font-size-2xl: calc(var(--font-size-xl) * var(--font-size-ratio));
-
-  --font-size-display: 3.375rem;
+
+  --font-size-2xs: initial;
+  --font-size-xs: initial;
+  --font-size-sm: initial;
+  --font-size-lg: initial;
+  --font-size-xl: initial;
+  --font-size-2xl: initial;
+
+  --font-size-display: clamp(2rem, 1.5rem + 2.5vw, 3.375rem);
   --font-size-display-ratio: 1.28;
-  --font-size-3xl: calc(
-    var(--font-size-display) / var(--font-size-display-ratio) / var(--font-size-display-ratio)
-  );
-  --font-size-4xl: calc(
-    var(--font-size-display) / var(--font-size-display-ratio)
-  );
-  --font-size-5xl: var(--font-size-display);
-
-  --heading-h1: calc(
-    var(--font-size-base) * var(--font-size-ratio) * var(--font-size-ratio) * var(--font-size-ratio)
-  );
-  --heading-h2: calc(
-    var(--font-size-base) * var(--font-size-ratio) * var(--font-size-ratio)
-  );
-  --heading-h3: var(--font-size-base);
-  --heading-h4: var(--font-size-xs);
-
-  --heading-h5: var(--font-size-2xs);
+
+  --font-size-3xl: initial;
+  --font-size-4xl: initial;
+  --font-size-5xl: initial;
+
+  --heading-h1: initial;
+  --heading-h2: initial;
+  --heading-h3: initial;
+  --heading-h4: initial;
+
+  --heading-h5: initial;
 
   --font-weight-normal: 400;
   --font-weight-medium: 500;
@@ -225,6 +215,10 @@
   --stroke-xl: 4px;
   --stroke-2xl: 6px;
 
+  --blur-sm: 4px;
+  --blur-md: 8px;
+  --blur-lg: 16px;
+
   --band-height-xs: 1.5rem;
   --band-height-sm: 1.75rem;
   --band-height-md: 2rem;

package/dist/tokens/semantic/layout.css

@@ -18,6 +18,8 @@
   --space-inline-md: var(--space-3);
   --space-inline-lg: var(--space-4);
 
+  --space-inline-xl: var(--space-6);
+
   --overlay-z-index: 50;
 
   --sticky-z-index: 20;
@@ -71,14 +73,26 @@
 
   --page-measure-wide: 72rem;
 
-  --page-title-font-size: var(--heading-h1);
-  --page-title-font-size-compact: var(--heading-h2);
+  --page-title-font-size: var(
+    --heading-h1,
+    calc(
+      var(--font-size-base) * var(--font-size-ratio) * var(--font-size-ratio) *
+        var(--font-size-ratio)
+    )
+  );
+  --page-title-font-size-compact: var(
+    --heading-h2,
+    calc(var(--font-size-base) * var(--font-size-ratio) * var(--font-size-ratio))
+  );
   --page-subtitle-font-size: var(--font-size-base);
-  --page-subtitle-font-size-compact: var(--font-size-sm);
+  --page-subtitle-font-size-compact: var(--font-size-sm, var(--font-size-base));
 
-  --page-title-font-size-chrome: var(--heading-h3);
+  --page-title-font-size-chrome: var(--heading-h3, var(--font-size-base));
 
-  --page-subtitle-font-size-chrome: var(--font-size-2xs);
+  --page-subtitle-font-size-chrome: var(
+    --font-size-2xs,
+    calc(var(--font-size-base) / var(--font-size-ratio) / var(--font-size-ratio))
+  );
 
   --page-pad-block-start-chrome: 0px;
 

package/docs/COMPOSITION-VS-COMPONENT.md

@@ -84,6 +84,7 @@ new UI need
 | **PricingTable** / feature grid                         | ❌  | ❌  | ❌  | ❌  | ❌  | ❌  | ❌  | **Composition** — `ResponsiveGrid` + `Card`                              |
 | Dashboard **page layout**                               | ❌  | ❌  | ❌  | ❌  | ➖  | ❌  | ❌  | **Composition** — `AppShell` + `PageContainer` + `ResponsiveGrid`        |
 | "Icon medallion"                                        | ❌  | ❌  | ❌  | ❌  | ✅  | ❌  | ❌  | **Composition** — `Avatar` (square) + a Lucide glyph                     |
+| **Section** / **Band** (full-bleed + measured column)   | ❌  | ❌  | ❌  | ❌  | ✅  | ❌  | ❌  | **Composition** — `<section>` + `Flex measure` + `pad`; see §3.1         |
 
 `✅ pass · ❌ fail · ➖ borderline`. **StatCard** is the instructive borderline: C2 is weak (it owns little behavior), but it is a universal KPI tile with a controlled API, fully tokenized, broadly reused — so it earns its place. A **Hero** fails six of seven; it is unambiguously a composition.
 
@@ -106,6 +107,46 @@ C2 rather than C7.
 
 **ServiceLauncherCard is the ONE recorded exception, and it is recorded so that it stays one.** It shipped before the test was run against it, and when the test was run it came back with two hard FAILs: **C2** — no state, no keyboard handling, no focus management, its only ARIA three static attributes — and **C3** — its own imports are `Card` + `CardContent` + `Badge` + a Lucide glyph, so "could I build this right now from primitives?" is yes. By §2 that makes it a composition pattern. It is kept anyway because `src/components/layout/app-launcher.tsx` consumes it: it is an internal building block of a component that **does** pass, so the question was never "should it exist" but "should it be PUBLIC", and removing a public export is breaking. Keeping it public was the cheaper call and the ledger lives on gh#814 and at the top of `src/components/data-display/service-launcher-card.tsx`. **Consumers should compose `Card` + `Badge` for a service tile** — reach for `ServiceLauncherCard` only to match `AppLauncher`'s own tiles — and this row is not precedent for adding another static tile to `src/components/`.
 
+### 3.1 "Full-bleed outside, measured column inside" — the case that was answered with a PROP (gh#839)
+
+This row exists because the question it settles was asked the other way round, and the right answer
+turned out to be neither "add a component" nor "do nothing".
+
+**A `Section` component is refused, and it is refused for Hero's reasons.** It owns no state, no
+keyboard, no focus and no ARIA a `<section aria-labelledby>` does not already have (**C2**); it is
+`<section>` + `Flex` + padding + a max-width, i.e. buildable today (**C3**); its API would be the
+grab-bag `band` / `measure` / `glow` / `surface` / `bleed` that **C4** names by name; and a JP
+business-software library would be shipping a marketing band to every consumer (**C7**). One
+criterion of seven passes. Nothing about that is close.
+
+**But "do nothing" was also refused, and that is the part worth remembering.** The doctrine's own
+remedy for a composition is a TOKEN (§4.3), and `--page-measure-wide` shipped in 28.8.0 — so on
+paper the gap was already closed. It was not. A token is only closed when something can READ it,
+and three unrelated pages had each hand-written the identical four declarations to do so:
+`docs/showcase/marketing-page.tsx` as an inline `style` constant, `acme-website.tsx` as `.tx-shell`,
+`futurelastic-web.tsx` as `.fl-shell` — one shape, three spellings, two of them page-local CSS
+classes on the pages whose entire claim is that they need none. `docs/TOKENS.md` calls a value that
+appears in more than one place tier 1, and the same logic reads on a SHAPE.
+
+**The third move is a prop on a primitive that already passes the test.** `Flex measure` (narrow |
+medium | wide) centres the box and caps it at `var(--page-measure-*)`; it adds no gutter, because
+`pad` owns that. A full-bleed band is now `<section>` — carrying the edge-to-edge paint — around one
+`<Flex direction="col" measure="wide" pad={{ inline: 6, block: 20 }}>`. Measured on
+`marketing-page.tsx`: seven bands, 7 inline `style` spreads and 3 `CSSProperties` constants gone,
+the metric that page defends (0 bespoke classes, 0 raw px/rem literals) unchanged at 0/0, and the
+geometry byte-identical (1440: section 1440px, column 1152px, band 96/80px, gutter 24px).
+
+**`PageContainer measure="wide"` stays refused, and for the original reason.** A marketing page is
+full-bleed `<section>`s; `PageContainer` owns page padding and a header/toolbar/footer scaffold, so
+the two pages that are the prop's proof still cannot consume it. The prop went to the primitive
+those pages CAN put inside a `<section>`, which is the distinction the earlier deferral was missing
+rather than a reversal of it.
+
+**The rule this leaves behind:** when a composition repeats a shape, ask whether an existing
+primitive is missing ONE AXIS before you ask whether a new component is missing. A component that
+fails C1–C7 and a prop that closes the same gap are not the same proposal, and the test above is
+only asking about the first.
+
 ---
 
 ## 4. How to build a composition pattern correctly

package/docs/DESIGN-AUTHORITY.md

@@ -449,6 +449,20 @@ expandable.expandedRowKeys` / `onExpandedRowsChange`. This library already mappe
   (`role="toolbar"`, `aria-pressed`); the prop there only keeps the last item selected.
   Divergence from Radix's markup is the point of the change, not a side effect of it.
 
+- **`Input addonBefore` / `addonAfter` stay, although antd DEPRECATED them (gh#841).** Verified in
+  `ant-design@master` rather than on the docs page: `components/input/Input.tsx` carries
+  `@deprecated Use Space.Compact instead` on both props and fires a dev-time
+  `devUseWarning('Input').deprecated(…)` for each, while still rendering them; both locale tables
+  strike the rows through and the `addon` demo is flagged `debug`, so it no longer appears on the
+  published page. The deprecation is a REFACTOR onto `Space.Compact`, and this library has no
+  `Space` — so following it would delete the joined control and put nothing in its place, which is
+  a breaking change bought for nothing. `addonBefore` IS the joined control here: it renders
+  `.ui-input-group`, and gh#841 squared its seam. The steer that IS followed is the one antd's own
+  live surface gives: a GLYPH belongs in `prefix`, inside the field, where there is one box, one
+  border and no seam; an addon is for a label segment. Written on the prop
+  (`src/props/components/data-entry.prop.ts`) and in the MCP catalog. Revisit if a `Space`/compact
+  primitive is ever ported — then antd's steer is followable and this becomes a migration.
+
 **A knob that only a fork could reach is not parity either.** antd's `components`,
 `filterDropdown`, `classNames`/`styles` semantic maps and `prefixCls` all exist to let a consumer
 replace the rendered markup. This library answers that layer with tokens (cardinal rule #45), so

package/docs/DEVELOPMENT.md

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

package/docs/TOKENS.md

@@ -297,7 +297,22 @@ Instead, declare the knob `initial` (a real, catalogued, guaranteed-invalid decl
 }
 ```
 
-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 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 **as long as nothing re-scopes what they read** — see the two paragraphs below, which is where that qualifier cost a release.
+
+**A DERIVED TIER FREEZES ON ITS OWN SEED — the `--font-size-*` ramp (gh#834).** The type scale is one base and one ratio, and every step used to be written `--font-size-5xl: var(--font-size-display)` / `--font-size-lg: calc(var(--font-size-base) * …)` on `:root`. Those substitute on `<html>`, so a `[data-tenant]` that re-seeds the base — the route level 3 of `docs/CUSTOMER-THEMING.md` documents, and which level 1 calls a seed — moved `text-base` and **nothing else**. Measured with `--font-size-base: 24px; --font-size-display: 80px` on a scope: 2xs/xs/sm/lg/xl/2xl/3xl/4xl/5xl all sat exactly where `:root` had left them, and a showcase whose comment read "80px hero via text-5xl" painted 54.
+
+So every **derived** step is now an `initial` knob and the formula lives at the call site, spelled in terms of the un-derived knobs only (`--font-size-base`, `--font-size-ratio`, `--font-size-display`, `--font-size-display-ratio`) — an `initial` knob cannot be chained through, so `xl` reads `base × ratio³` rather than `lg × ratio`:
+
+```css
+:root {
+  --font-size-5xl: initial;
+} /* documented default = var(--font-size-display) */
+[data-slot="text"][data-size="5xl"] {
+  font-size: var(--font-size-5xl, var(--font-size-display));
+}
+```
+
+**Every reader must carry the fallback**: a bare `var(--font-size-xs)` on an `initial` knob resolves to nothing, and the failure is silent and total. `check:frame-token-scope` is the gate that measures both halves — it fails on a step that stops following a scoped seed, and on a bare read of an empty knob.
 
 **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:
 

package/docs/data-entry/tag-input.tsx

@@ -2,6 +2,7 @@ import { useState } from "react";
 
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
 import { FormField, TagInput } from "@godxjp/ui/data-entry";
+import { useTranslation } from "@godxjp/ui/i18n";
 import { Flex, PageContainer } from "@godxjp/ui/layout";
 
 /**
@@ -11,9 +12,17 @@ import { Flex, PageContainer } from "@godxjp/ui/layout";
  * Composed only from real @godxjp/ui components.
  */
 export default function Demo() {
+  const { t } = useTranslation();
   const [invoiceTags, setInvoiceTags] = useState<string[]>(["営業部", "Q1"]);
   const [skillTags, setSkillTags] = useState<string[]>(["経理", "仕訳入力"]);
   const [recipientEmails, setRecipientEmails] = useState<string[]>([]);
+  /* The reporter's exact 71-character string, held FIRST so the truncated chip is one of the two
+     that render rather than one of the ones `+N` hides (gh#840). */
+  const [ledgerTags, setLedgerTags] = useState<string[]>([
+    "THEME_SEED_LEDGER_0007_CONTRAST_VERIFIED_AGAINST_CANVAS_AND_LABEL_00042",
+    "本番",
+    "ổn định",
+  ]);
 
   return (
     <PageContainer
@@ -87,6 +96,34 @@ export default function Demo() {
           </CardContent>
         </Card>
 
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>{t("showcase.tagInput.longIdTitle")}</CardTitle>
+            <CardDescription>
+              maxTagTextLength cuts the chip TEXT only — the whole value stays in the chip&apos;s
+              title and in the remove button&apos;s accessible name. maxTagCount collapses the rest
+              into a +N that names, in its own title and aria-label, exactly which tags it hides.
+              Neither may swallow a value silently (gh#840).
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <FormField
+              id="ledger-tags"
+              label={t("showcase.tagInput.ledgerLabel")}
+              helper={t("showcase.tagInput.ledgerHelper")}
+            >
+              <TagInput
+                id="ledger-tags"
+                value={ledgerTags}
+                onValueChange={setLedgerTags}
+                maxTagCount={2}
+                maxTagTextLength={16}
+                aria-label={t("showcase.tagInput.ledgerLabel")}
+              />
+            </FormField>
+          </CardContent>
+        </Card>
+
         <Card>
           <CardHeader>
             <CardTitle level={2}>無効状態</CardTitle>

package/docs/layout/flex.tsx

@@ -8,6 +8,7 @@ import {
   ListRow,
 } from "@godxjp/ui/data-display";
 import { Button, Text } from "@godxjp/ui/general";
+import { useTranslation } from "@godxjp/ui/i18n";
 import { Flex, PageContainer } from "@godxjp/ui/layout";
 
 /**
@@ -20,6 +21,7 @@ import { Flex, PageContainer } from "@godxjp/ui/layout";
  * @godxjp/ui components.
  */
 export default function Demo() {
+  const { t } = useTranslation();
   return (
     <PageContainer
       title="Flex"
@@ -398,6 +400,44 @@ export default function Demo() {
             </Flex>
           </CardContent>
         </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>{t("showcase.flexMeasure.title")}</CardTitle>
+            <CardDescription>{t("showcase.flexMeasure.lead")}</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="sm">
+              <Flex
+                id="measure-narrow"
+                measure="narrow"
+                surface="muted"
+                pad={{ block: 2, inline: 6 }}
+                justify="center"
+              >
+                <Text tone="muted">measure=&quot;narrow&quot; · 42rem</Text>
+              </Flex>
+              <Flex
+                id="measure-medium"
+                measure="medium"
+                surface="muted"
+                pad={{ block: 2, inline: 6 }}
+                justify="center"
+              >
+                <Text tone="muted">measure=&quot;medium&quot; · 48rem</Text>
+              </Flex>
+              <Flex
+                id="measure-wide"
+                measure="wide"
+                surface="muted"
+                pad={{ block: 2, inline: 6 }}
+                justify="center"
+              >
+                <Text tone="muted">measure=&quot;wide&quot; · 72rem</Text>
+              </Flex>
+            </Flex>
+          </CardContent>
+        </Card>
       </Flex>
     </PageContainer>
   );

package/docs/roadmap/website-components.md

@@ -649,6 +649,40 @@ with no call site in the two pages that are its proof, which is the tier-2 mista
 warns about. The token stands on its own as the vocabulary a composition caps its shell with, the
 way `--gradient-hero` does.
 
+**CLOSED in gh#839, and the refusal above still stands.** Leaving the centred column to "the
+composition writes it" was measured and found wanting: three unrelated pages hand-wrote the SAME
+four declarations — `marketing-page.tsx` as an inline `style` constant, `acme-website.tsx` as
+`.tx-shell`, `futurelastic-web.tsx` as `.fl-shell` — which `docs/TOKENS.md` calls tier 1, and two of
+the three spelled it as a page-local CSS class. The answer was not a `Section` component (it fails
+C1–C7 the way Hero does — `docs/COMPOSITION-VS-COMPONENT.md` §3.1 carries the ledger) and not
+`PageContainer`, which still cannot be consumed by a full-bleed page. It is **`Flex measure`**
+(`narrow | medium | wide`, reading `--page-measure-*`), on the primitive a `<section>` CAN put
+inside itself. It centres and caps and nothing else: `pad` keeps the gutter, so a band is
+`<section>` around one `<Flex direction="col" measure="wide" pad={{ inline: 6, block: 20 }}>`.
+
+| step                               | reader                                                         |
+| ---------------------------------- | -------------------------------------------------------------- |
+| `--space-section-band` (80px)      | `pad={{ block: 20 }}` — `GapStepProp` gained 20/24             |
+| `--space-section-hero` (96px)      | `pad={{ block: 24 }}`                                          |
+| `--page-measure-{narrow,med,wide}` | `Flex measure` — and `PageContainer measure` for the first two |
+
+**No compact rung for the band steps, decided on measurement.** At 320×568 the hero band is 96px
+at both edges = 33.8% of the first screen, and the `<h1>` still lands fully above the fold (top
+195px, bottom 315px). Three reasons not to add one: (1) 96px is already the NARROW rung of the
+industry pair — Tailwind UI's marketing sections are `py-24 sm:py-32`, i.e. 96px on a phone and
+128px from `sm` up, so the missing step is at the wide end, not the narrow one; (2) a numeric `pad`
+step is a VALUE by contract (`pad={3}` is 12px at every width — `GapStepProp`'s own docstring says
+so), and making 20/24 responsive would make them the two steps whose number lies; (3) a
+`--space-section-band-compact` token would have nowhere to be flipped: every `-active`/`-compact`
+pair in this repo switches inside a COMPONENT's scope (`.ui-page-container`,
+`.ui-centered-shell[data-preset="public-landing"]`), and a plain `<section>` has no such scope — so
+it would ship as vocabulary with no caller, the exact defect gh#839 exists to stop.
+`--centered-shell-landing-main-padding-block-compact` is not the counter-example it looks like: it
+is 40px → 24px of a SHELL's `main` padding, not a marketing band, and it lives inside that shell's
+own scope. **The real capability the band wants is a responsive object form for `pad`**, the one
+`direction` and `ResponsiveGrid columns` already take (`pad={{ block: { base: 12, md: 20 } }}`) —
+that is its own issue, and a much larger one than a token rung.
+
 ---
 
 ## 6. The animation and motion story