@godxjp/ui 28.12.0 → 29.0.0

package/docs/TOKEN-RESOLUTION.md

@@ -0,0 +1,195 @@
+# Token resolution — who overrides whom, and how to prove it
+
+This document exists because of one complaint: _"rất nhiều chỗ cứ đè cấu hình lung tung làm ảnh
+hưởng component này sang component khác"_ — configuration overriding configuration until changing
+one component moves another. That is a real failure mode and prose does not settle it, so this
+page is **an order, a rule, and a tool**. The tool is `scripts/explain-token.mjs`.
+
+Nothing here is invented. Ant Design v5 settled this problem years ago and its vocabulary is used
+throughout; where this package lacks one of Ant Design's layers, that is said plainly rather than
+papered over with a new word.
+
+---
+
+## 1. The order
+
+**Yes, the chain is what you said.** For a value at a given element, strongest first:
+
+| #   | layer             | in this package                                                | Ant Design equivalent                      |
+| --- | ----------------- | -------------------------------------------------------------- | ------------------------------------------ |
+| 1   | **instance**      | `style={{ "--card-radius": "…" }}` on the element              | a component prop / `<Component style>`     |
+| 2   | **nearest scope** | `[data-tenant]`, `.dark`, `[data-density]`, any region wrapper | the **nearest** `ConfigProvider theme`     |
+| 3   | **global**        | `:root` in the app's own `theme.css`                           | the outermost `ConfigProvider theme.token` |
+| 4   | **default**       | `:root` in `src/tokens/**`                                     | `theme.defaultAlgorithm` seed              |
+
+There is no bespoke machinery here: a CSS custom property is resolved by the ordinary cascade, so
+"nearest scope wins" is just inheritance, and "the app's `theme.css` beats the package" is just the
+layer contract — **unlayered CSS outranks every `@layer`**, and everything this package ships is
+layered (`docs/TOKENS.md` · The layer contract).
+
+Between 2 and 3 there is no ambiguity to resolve: an override on a wrapper is _nearer_ to the
+element than `:root`, so it wins by inheritance, not by specificity. Two scopes on the same element
+are ordinary cascade — higher specificity, then later.
+
+## 2. The four tiers — Ant Design's model, and the one layer we do not have
+
+Ant Design v5: **Seed → Map → Alias → Component**. This package:
+
+| Ant Design                           | here        | file                          | count |
+| ------------------------------------ | ----------- | ----------------------------- | ----- |
+| **Seed Token**                       | foundation  | `src/tokens/foundation.css`   | 201   |
+| **Map Token** (derived by algorithm) | — _partial_ | `src/tokens/derived.css`      | —     |
+| **Alias Token**                      | semantic    | `src/tokens/semantic/*.css`   | 92    |
+| **Component Token**                  | component   | `src/tokens/components/*.css` | 1688  |
+
+**The Map layer is PARTIAL, not missing** — an earlier draft of this page said "missing" and Codex
+was right to reject it. `derived.css` really is a Map layer for the brand ramp: `--ring`,
+`--primary-hover` and `--primary-active` are computed from `--primary` with relative colour, which
+is derivation by algorithm in the sense Ant Design means. Foundation mixes seed and derived too —
+the spacing steps are `calc(<n> * var(--scaling))` (`foundation.css:673`) and the shadows derive
+from `--shadow-color` (`foundation.css:290`).
+
+What is genuinely thin is its **reach**: the hover knobs are themselves `initial`, the destructive
+states are authored literals (`derived.css:136`), and the `@supports not (color: hsl(from …))`
+branch hands older engines literals that stop following the seed altogether (`derived.css:188`).
+That last one is why `tenantTheme()` (gh#868) computes hover/pressed in JavaScript — not because
+there was no algorithm layer, but because the one that exists does not survive an engine without
+relative colour.
+
+A previous draft also claimed the thin Map layer is _why_ the component tier needs 1688 tokens.
+That is unsupported and has been removed: deriving defaults does not remove the need for
+independently overridable component knobs, which is what most of those 1688 are.
+
+## 3. The rule that makes the order work — and silently breaks it
+
+`var()` substitutes **where it is declared**, not where it is read.
+
+```css
+/* BROKEN — the chain is dead at step 2 */
+:root {
+  --card-border-color: var(--border);
+}
+.ui-card {
+  border-color: var(--card-border-color);
+}
+```
+
+`--card-border-color` resolves against the **root's** `--border`, once. A `[data-tenant]` below
+root that sets its own `--border` can never reach it: the binding already happened higher up. Step
+2 of the chain exists, and for that token it does nothing.
+
+```css
+/* CORRECT — knob is `initial`, formula at the CALL SITE */
+:root {
+  --card-border-color: initial;
+}
+.ui-card {
+  border-color: var(--card-border-color, hsl(var(--border)));
+}
+```
+
+Now the fallback is evaluated **at `.ui-card`**, where the scope is in effect, so the tenant's
+`--border` is the one that arrives — and an explicit `--card-border-color` still overrides it.
+
+This package has paid for that distinction seven times: gh#687, gh#843, gh#848, gh#866 and others.
+It is the single most common cause of "I overrode the token and nothing happened."
+
+## 4. The tool
+
+```
+node node_modules/@godxjp/ui/scripts/explain-token.mjs --card-radius     # one token: every declaration, every read
+node node_modules/@godxjp/ui/scripts/explain-token.mjs --table           # a whole family
+node node_modules/@godxjp/ui/scripts/explain-token.mjs --audit           # every freeze, orphan and unpublished token
+```
+
+(From inside this repo's own checkout, drop the `node_modules/@godxjp/ui/` prefix.)
+
+For one token it prints every declaration site — marked `root-only` or `below root` — with its
+selector, its value, and whether it is a freeze; then every read and whether that read carries a
+call-site fallback. If two components move together, run it on the token they share and the shared
+declaration is on the screen.
+
+**It does not compute a winner, and says so.** The first version ranked selectors into four
+"cascade" buckets by regex and printed them strongest-last. Codex found that `@theme inline` and
+`[dir="rtl"] .ui-actions[data-fade-in-inline]` both scored top precedence on the substring
+`inline`, that `:root[data-brand="crm"]` was filed as a descendant scope, and that "strongest last"
+sorted by alphabetical filename. A tool meant to settle override disputes that invents precedence
+is worse than no tool. `root-only` is the one property it can prove, and it is the only one the
+freeze test needs. `--audit` ends with the four things it cannot see; read them before treating a
+clean run as proof.
+
+### What `--audit` reports today
+
+```
+2090 declared · 1973 published · 641 frozen · 6 orphan reads
+```
+
+- **frozen (641)** — a root-only binding whose source is restated somewhere below root. The naive
+  test ("any `:root` binding that reads a token") reports **1028**, and a list that long is one
+  nobody reads; `--actions-gap: var(--space-1)` only matters because `--space-1` really is
+  restated. The scoped set is derived on every run, never hand-listed — a hand-kept list is what
+  went blind in gh#854. It counts **any** declaration below root, not just theme-looking scopes:
+  `.ui-page-container` inside `@media (max-width: 720px)` restates `--space-section-active`
+  (`layout.css:992`) while `--card-space-inset` binds it at `:root` (`card.css:6`), so below 720px
+  a Card keeps the root's inset. An earlier, narrower version of this test missed exactly that.
+- **orphan reads (6)** — `var(--x)` where `--x` is declared nowhere and no fallback is given.
+- **unpublished (117)** — declared in CSS but absent from `agent/tokens.json`, so a consumer cannot
+  discover them. From the consumer's point of view these are hard-coded. `--card-accent-color` is
+  one: six call-site declarations, zero documentation.
+
+## 5. Rules for anyone adding or changing a token
+
+1. **Declare it in the tier it belongs to.** Component tokens go in `src/tokens/components/<name>.css`,
+   named `--{component}-{part}-{property}`; `check:token-tiers` enforces the shape.
+2. **A knob that mirrors a role is `initial` + a call-site fallback.** Never a `:root` binding.
+   See §3. If you are unsure whether it mirrors a role, run `explain-token.mjs` on the role and see
+   whether any scope restates it.
+3. **Do not write another component's token from your own rule — with one qualified exception.**
+   Writing `--badge-*` from a Card rule is the literal shape of "changing one component moves
+   another," and that is the default answer.
+
+   The exception is a **composition default**: a child whose geometry legitimately differs when it
+   sits inside a particular parent. `control.css:313` does exactly this — a count Badge inside a
+   boxed Button gets `--badge-space-y: 0` and a tighter radius, because a chip in a button is not a
+   standalone status chip. That is correct, and an earlier draft of this rule would have forbidden
+   it.
+
+   To qualify, all three must hold: the boundary is **documented** at the rule; the child's tokens
+   are **public**, so the relationship is inspectable; and a per-instance override on the child
+   still **wins**. The descendant selector deserves scrutiny of its own — `control.css:313` reaches
+   every nested Badge, not just a direct child — but that is a scoping question, not grounds to ban
+   composition.
+
+4. **Publish it.** A token absent from `agent/tokens.json` is not part of the API, whatever the
+   stylesheet says. `pnpm regen` does this; `check:agent-catalog` verifies it.
+5. **A consumer sets tokens, never selectors.** App CSS targeting `[data-slot]`, `[data-priority]`
+   or `.ui-*` is unlayered and therefore outranks every package layer at every width, including the
+   responsive re-points — which is how a page-local fix becomes a library-wide regression.
+6. **A theme that makes a surface translucent owns its own `prefers-reduced-transparency` and
+   `@supports not (backdrop-filter)` fallbacks.** The library cannot write them on the theme's
+   behalf — it does not know what opaque colour the theme wants, and guessing at one role's own
+   colour is not safe: `docs/themes/glassmorphism.css` sets `--card: 0 0% 100% / 42%`, so a fallback
+   that fell back to `hsl(var(--card))` would still be 42% translucent. Both branches stay
+   custom-property overrides on the theme's own selector, same shape as rule 5.
+
+7. **A scoped theme cannot re-ink text it does not own the `color` of.** `src/styles/base.css`
+   sets `color: hsl(var(--foreground))` on `body`, above every scope, so that `var()` substitutes
+   once against the root and everything below inherits the resolved colour — the §3 freeze rule
+   applied to a PROPERTY rather than a token, and worse there, because a token can be given a knob
+   and `color` on `body` has none to give. `ThemeScope` re-states it on itself and on the
+   body-level overlay host, so a region wrapped in one re-inks correctly (gh#881). **A plain
+   wrapper themed by a stylesheet must state `color: hsl(var(--foreground))` on its own element
+   too** — that is the consumer's own element, not a selector into this package, so rule 5 permits
+   it.
+
+## 6. What is not yet true
+
+The owner's second question was whether **every smallest element** is configurable. It is not, and
+the measurement is in `docs/THEME-API-COVERAGE.md`. Two known shapes of failure:
+
+- a painted property written as a literal, with no token at all;
+- a property written as `var(--x)` where `--x` is unpublished — reachable in principle, invisible
+  in practice.
+
+Both are counted there per component. This page describes how resolution _works_; that one says how
+far it currently _reaches_.

package/docs/TOKENS.md

@@ -44,17 +44,18 @@ src/styles/
 
 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.
 
-#### The three tone tiers — FILL, TEXT, MARK
+#### The four tone tiers — FILL, TEXT, MARK, SURFACE
 
-A status tone can be painted three ways, and each way is judged against a different thing. Reading
+A status tone can be painted four ways, and each way is judged against a different thing. Reading
 the wrong tier is this palette's most expensive recurring bug, because nothing about it looks wrong
 in the source.
 
-| Tier     | Tokens                                      | What it paints                                                     | Contrast bar                                              |
-| -------- | ------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------- |
-| **FILL** | `--success`, `--warning`, `--info`, `--destructive` | A solid chip, band or bar with a label ON it                        | AA **4.5:1** against its own `*-foreground` label          |
-| **TEXT** | `--text-success`, `--text-warning`, `--text-info`, `--text-error` | Small coloured type — a StatCard delta, an outline badge label, a field's error line | AA **4.5:1** against the surface BEHIND it                 |
-| **MARK** | `--mark-success`, `--mark-warning`, `--mark-info`, `--mark-destructive`, `--mark-primary`, `--mark-attention` | A thin shape carrying meaning with nothing written on it — a `Card accent` rail, a `DataTable rowTone` rail | SC 1.4.11 **3:1** against the surface it sits on |
+| Tier        | Tokens                                                                                                        | What it paints                                                                                                                                                                            | Contrast bar                                            |
+| ----------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| **FILL**    | `--success`, `--warning`, `--info`, `--destructive`                                                           | A solid chip, band or bar with a label ON it                                                                                                                                              | AA **4.5:1** against its own `*-foreground` label       |
+| **TEXT**    | `--text-success`, `--text-warning`, `--text-info`, `--text-error`                                             | Small coloured type — a StatCard delta, an outline badge label, a field's error line                                                                                                      | AA **4.5:1** against the surface BEHIND it              |
+| **MARK**    | `--mark-success`, `--mark-warning`, `--mark-info`, `--mark-destructive`, `--mark-primary`, `--mark-attention` | A thin shape carrying meaning with nothing written on it — a `Card accent` rail, a `DataTable rowTone` rail                                                                               | SC 1.4.11 **3:1** against the surface it sits on        |
+| **SURFACE** | `--surface-success`, `--surface-warning`, `--surface-info`, `--surface-destructive`                           | The pale GROUND a toned surface paints — an `Alert` tint, a status `Badge` chip, a toned `DataTable` row, a toast, a `ChatBubble`, a toned Dialog/Sheet header, an `EmptyState` medallion | whatever sits ON it must clear AA **4.5:1** — see below |
 
 The MARK tier exists because both rails were reading FILL, and two of them were effectively
 invisible. Measured in Chromium on the light card: `Card accent="warning"` drew its 6px rail at
@@ -66,6 +67,44 @@ place and both follow — and since 3:1 is looser than 4.5:1, anything legible a
 a mark by construction. `--mark-attention` is the exception: there is no `--text-attention`, and
 the fill already clears the floor in both themes (3.32 / 6.75).
 
+**The SURFACE tier is `initial` and has no default of its own (gh#866).** The other three tiers
+hold a colour; this one holds a brand's ANSWER, and there is no single derived value it could
+carry — Alert washes at 5%, Badge at 10%, the row tone at 6%, the medallion at 12%, the toast
+`color-mix`es into `--popover`. So each surface keeps its own formula AT ITS CALL SITE, behind the
+role:
+
+```css
+background-color: var(--surface-success, hsl(var(--success) / var(--alert-bg-alpha)));
+```
+
+Unset, every surface paints exactly what it painted before (measured in Chromium: 30/30 computed
+values byte-identical). Set on a scope — `[data-tenant] { --surface-success: #E8F5EF }` — all nine
+follow, because the formula lives where the paint happens rather than at `:root`; the same probe
+measured 0/30 before the roles existed and 30/30 after.
+
+The tier exists because DERIVATION TIES THE GROUND'S HUE TO THE INK. A brand kit that pairs
+`--success #126342` with `--success-soft #E8F5EF` is not describing a derivation: #E8F5EF is a
+separately chosen mint, not that green at any alpha, and the only move the system offered was to
+lighten the success TEXT until its wash matched — damaging the ink's contrast to fix the colour of
+the ground.
+
+**A brand's ground is the brand's contrast problem, and these are the numbers to check.** Everything
+this library paints ON a status surface reads the TEXT tier — the Alert icon and title, the Badge
+label (`text-*-strong`), the toast ink — and on the kit's four grounds that measures success
+**6.22:1** · warning **5.48:1** · error **6.64:1** · info **7.34:1**, with body ink
+(`--foreground`) at 13.9–14.4:1. All four clear AA, so the role is safe to hand a brand.
+
+The one thing that does NOT is the Callout RAIL, which is the FILL tier by design (a 4px rail at
+the border alpha reads as a smudge): against the brand grounds it measures success **1.99:1** and
+warning **1.62:1**, under SC 1.4.11's 3:1. That is inherited, not introduced — on today's derived
+tint the same rail measures **2.12:1** and **1.69:1** — and the repair is the MARK tier, not a
+lighter ground.
+
+`primary` and `attention` have no SURFACE entry on purpose: a brand ships "soft" pairs for the four
+statuses, and two more roles nobody asked for make the vocabulary harder to learn. Borders stay
+derived too (`--alert-border-alpha`, `--chat-bubble-tone-border-alpha`) — the kit supplies no border
+colours.
+
 Two guards, because one was not enough:
 `src/tokens/__tests__/tone-mark-contrast.test.ts` recomputes every tone × ground × theme off the
 committed tokens and reads the alias out of the CSS (so repointing a mark back at FILL fails the
@@ -75,20 +114,20 @@ gate had ever looked at one.
 
 **Progress and Legend joined the tier, and the wa-iro question is settled.** `.ui-legend-swatch`,
 `.ui-progress-bar` and `.ui-progress-segment` all read FILL as standalone graphics and all failed
-the same floor. The floor applies: nothing is written on a progress fill, so *where the colour
-stops* is the entire datum, and a slice of a partition carries its share of the whole with no words
+the same floor. The floor applies: nothing is written on a progress fill, so _where the colour
+stops_ is the entire datum, and a slice of a partition carries its share of the whole with no words
 on it — that is precisely a "graphical object required to understand the content". The hue loses.
 The two moved together because a swatch is a SAMPLE of the bar beside it; a key that is not the
 colour it is a key to is not a key.
 
-| surface | tone | ground | FILL (before) | MARK (after) |
-| --- | --- | --- | --- | --- |
-| `.ui-legend-swatch` | warning | light card | **1.74** | **5.90** |
-| `.ui-legend-swatch` | success | light card | **2.18** | **6.84** |
-| `.ui-legend-swatch` | destructive | dark card | **2.95** | **5.52** |
-| `.ui-progress-segment` | warning | light track | **1.60** | **5.41** |
-| `.ui-progress-segment` | success | light track | **2.00** | **6.28** |
-| `.ui-progress-segment` | destructive | dark track | **2.42** | **4.52** |
+| surface                | tone        | ground      | FILL (before) | MARK (after) |
+| ---------------------- | ----------- | ----------- | ------------- | ------------ |
+| `.ui-legend-swatch`    | warning     | light card  | **1.74**      | **5.90**     |
+| `.ui-legend-swatch`    | success     | light card  | **2.18**      | **6.84**     |
+| `.ui-legend-swatch`    | destructive | dark card   | **2.95**      | **5.52**     |
+| `.ui-progress-segment` | warning     | light track | **1.60**      | **5.41**     |
+| `.ui-progress-segment` | success     | light track | **2.00**      | **6.28**     |
+| `.ui-progress-segment` | destructive | dark track  | **2.42**      | **4.52**     |
 
 Worst case anywhere on the two routes after the move: **4.52:1**. `.ui-progress-bar` (meter and
 over-capacity) reads the same tokens as the slice, so a `tone="warning"` meter and a `warning`
@@ -101,10 +140,10 @@ failure — was on `text-destructive`, the FILL utility. So the same `tone` was
 `Alert` and near-invisible one line below it, in the field that caused it. Measured in Chromium on
 `/isolate/layout-auth-recovery-examples-mfa-challenge`:
 
-| surface | ground | FILL (before) | TEXT (after) |
-| --- | --- | --- | --- |
-| `.ui-form-field-note[role="alert"]` | dark card | **2.95** | **5.52** |
-| `.ui-form-field-note[role="alert"]` | light card | 6.16 | **7.21** |
+| surface                             | ground     | FILL (before) | TEXT (after) |
+| ----------------------------------- | ---------- | ------------- | ------------ |
+| `.ui-form-field-note[role="alert"]` | dark card  | **2.95**      | **5.52**     |
+| `.ui-form-field-note[role="alert"]` | light card | 6.16          | **7.21**     |
 
 Only the DARK branch failed, and the light one passing is why it survived: the fill is tuned for a
 white label ON it, so it darkens on light grounds and lightens on dark ones — the opposite of what
@@ -114,13 +153,13 @@ two `ui-auth-shell` routes it had never loaded.
 
 **A theme that repoints `--secondary` owes `--progress-track-background`.** The track defaults to
 `hsl(var(--secondary))`, which is a pale neutral in the stock palette. `docs/showcase/acme-portal`
-repurposes `--secondary` as a navy *button* colour, so its bars were drawn on a near-black track
+repurposes `--secondary` as a navy _button_ colour, so its bars were drawn on a near-black track
 and the mark fills measured 2.50 (success) / 2.90 (warning) on it. Naming the track explicitly is
 the fix — 6.49 / 5.59 after — not dragging the tier back.
 
 Three guards now, and each sees something the others cannot: the ratio tests in
 `tone-mark-contrast.test.ts` (rails against card/background, progress marks against the track);
-the *same file's* CSS-alias assertions, which fail if a rule is repointed at the fill tier and
+the _same file's_ CSS-alias assertions, which fail if a rule is repointed at the fill tier and
 which also pin the swatch and the slice to the **same** token per tone; and `check:contrast`'s
 **thin fill** pass — added because adding `/isolate/data-display-progress` to that gate's route
 list on its own changed nothing at all. The graphic pass wants ≤24px on both axes and the rail
@@ -209,7 +248,7 @@ A system with only tier 1 turns every exception into a hack (`!important`, a glo
 
 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.
+The two left need tokens in `components/control.css` (`.ui-otp-separator-icon`) and `components/shell.css` (`.tb-icon-btn svg`).
 
 **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.
 

package/docs/asset-modules.d.ts

@@ -44,3 +44,10 @@ declare module "*.gif" {
   const src: string;
   export default src;
 }
+
+/**
+ * A docs-owned theme stylesheet, imported for its side effect (e.g. `docs/themes/*.css`) —
+ * exactly like `preview/src/*.css`. There is nothing to type; the import exists only so the
+ * bundler includes the file.
+ */
+declare module "*.css";

package/docs/data-display/charts.tsx

@@ -1,6 +1,8 @@
+import type * as React from "react";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
 import { Flex, PageContainer, ResponsiveGrid } from "@godxjp/ui/layout";
 import { AreaChart, BarChart, LineChart, PieChart } from "@godxjp/ui/charts";
+import { useTranslation } from "@godxjp/ui/i18n";
 
 /**
  * Charts — tree-shaken `@godxjp/ui/charts` entry (needs the `recharts` optional
@@ -42,7 +44,18 @@ const sparseRevenue = [
 
 const jpy = { style: "currency", currency: "JPY" } as const;
 
+/** 生鮮品の相場推移 — 値そのものではなく「形」が意味を持つ連続値 (gh#865)。 */
+const priceHistory = [
+  { week: "第1週", price: 25400 },
+  { week: "第2週", price: 26800 },
+  { week: "第3週", price: 26100 },
+  { week: "第4週", price: 28300 },
+  { week: "第5週", price: 27600 },
+  { week: "第6週", price: 29900 },
+];
+
 export default function Demo() {
+  const { t } = useTranslation();
   return (
     <PageContainer
       title="Charts"
@@ -192,6 +205,73 @@ export default function Demo() {
             </CardContent>
           </Card>
         </ResponsiveGrid>
+
+        <ResponsiveGrid columns={2}>
+          <Card>
+            <CardHeader>
+              <CardTitle level={2}>{t("chartsDocs.areaSplitTitle")}</CardTitle>
+              <CardDescription>{t("chartsDocs.areaSplitBody")}</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <AreaChart
+                label={t("chartsDocs.areaSplitLabel")}
+                description={t("chartsDocs.areaSplitDescription")}
+                data={priceHistory}
+                categoryKey="week"
+                series={[
+                  {
+                    dataKey: "price",
+                    label: t("chartsDocs.priceSeries"),
+                    color: "var(--chart-5)",
+                    fillColor: "var(--chart-3)",
+                  },
+                ]}
+                valueDomain={[24000, 31000]}
+                valueTicks={[24000, 26000, 28000, 30000]}
+                numberFormat={jpy}
+                showLegend={false}
+                showDots
+                curved
+              />
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle level={2}>{t("chartsDocs.tokenScopeTitle")}</CardTitle>
+              <CardDescription>{t("chartsDocs.tokenScopeBody")}</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Flex
+                direction="col"
+                style={
+                  {
+                    "--chart-series-stroke-width": "3",
+                    "--chart-area-fill-alpha": "0.07",
+                    "--chart-grid-line-dash": "none",
+                  } as React.CSSProperties
+                }
+              >
+                <AreaChart
+                  label={t("chartsDocs.tokenScopeLabel")}
+                  data={priceHistory}
+                  categoryKey="week"
+                  series={[
+                    {
+                      dataKey: "price",
+                      label: t("chartsDocs.priceSeries"),
+                      color: "var(--chart-5)",
+                    },
+                  ]}
+                  valueDomain={[24000, 31000]}
+                  numberFormat={jpy}
+                  showLegend={false}
+                  curved
+                />
+              </Flex>
+            </CardContent>
+          </Card>
+        </ResponsiveGrid>
       </Flex>
     </PageContainer>
   );

package/docs/data-display/data-table/index.tsx

@@ -3,6 +3,7 @@ import { useMemo, useState } from "react";
 import { AppProvider } from "@godxjp/ui/app";
 import { Badge, Card, CardContent, DataTable, type ColumnDef } 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";
 import {
   DropdownMenu,
@@ -110,6 +111,7 @@ export default function Demo() {
     direction: "desc",
   });
   const [density, setDensity] = useState<DensityProp>("comfortable");
+  const { t } = useTranslation();
 
   const rows = useMemo(() => {
     if (!sort) return invoices;
@@ -166,6 +168,34 @@ export default function Demo() {
             getRowId={(row) => row.id}
           />
         </Flex>
+        {/* The RECORD collection — a wide, heterogeneous record set. The fold is a CONTAINER
+            query, not a viewport one, so the same table folds by the width it is GIVEN: the two
+            blocks below are one component and one column list, rendered wide and narrow.
+
+            Below `collapseBelow` the header row hides and every `<tr>` becomes a bordered
+            key-value card. The per-cell labels are DERIVED from the same `ColumnDef.header` the
+            `<th>` uses (gh#864) — one declaration, so the card can never drift from the table it
+            collapsed out of, and the value that loses its header keeps its name. */}
+        <Flex direction="col" gap="sm" id="stacked-record-collection">
+          <Text weight="medium">{t("dataTableDocs.stackedRecordWide")}</Text>
+          <DataTable
+            preset="stacked-record-collection"
+            collapseBelow="sm"
+            data={invoices}
+            columns={columns}
+            getRowId={(row) => row.id}
+          />
+        </Flex>
+        <Flex direction="col" gap="sm" id="stacked-record-collection-folded" className="max-w-xs">
+          <Text weight="medium">{t("dataTableDocs.stackedRecordFolded")}</Text>
+          <DataTable
+            preset="stacked-record-collection"
+            collapseBelow="sm"
+            data={invoices}
+            columns={columns}
+            getRowId={(row) => row.id}
+          />
+        </Flex>
         {/* Row TONE — the leading-edge rail + wash for a row in a named state. The status Badge
             stays in its own cell: the rail makes the row findable, it does not carry the meaning
             (WCAG 1.4.1). */}

package/docs/data-display/popover.tsx

@@ -78,7 +78,7 @@ export default function Demo() {
               </PopoverTrigger>
               <PopoverContent aria-label="ワークスペース">
                 <Select aria-label="ワークスペース" defaultOpen defaultValue="tokyo">
-                  <SelectTrigger aria-label="ワークスペース" data-picker-trigger="">
+                  <SelectTrigger data-picker-trigger="">
                     <SelectValue />
                   </SelectTrigger>
                   <SelectContent>

package/docs/data-display/table.tsx

@@ -1,4 +1,5 @@
 import {
+  Badge,
   Card,
   CardContent,
   CardDescription,
@@ -13,6 +14,7 @@ import {
   TableRow,
 } from "@godxjp/ui/data-display";
 import { Text } from "@godxjp/ui/general";
+import { useTranslation } from "@godxjp/ui/i18n";
 import { Flex, PageContainer } from "@godxjp/ui/layout";
 
 /**
@@ -21,6 +23,7 @@ import { Flex, PageContainer } from "@godxjp/ui/layout";
  * for a custom one-off table. Composed only from real @godxjp/ui components.
  */
 export default function Demo() {
+  const { t } = useTranslation();
   return (
     <PageContainer
       title="Table"
@@ -290,6 +293,55 @@ export default function Demo() {
           </CardContent>
         </Card>
 
+        {/* ── gh#876 — TableRow tone, a typed route to the same paint DataTable's own
+            `rowTone` writes onto `data-tone` (wash + leading rail + `--surface-*` grounding,
+            gh#866). A hand-composed row discovers it from types now; `data-tone` written by
+            hand keeps working unchanged — this is an addition, not a migration. */}
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>{t("tableDocs.title")}</CardTitle>
+            <CardDescription>
+              `TableRow tone` writes the same `data-tone` attribute `DataTable`&apos;s `rowTone`
+              already writes for you — no more reaching for the raw attribute to discover the row
+              can be toned at all.
+            </CardDescription>
+          </CardHeader>
+          <CardContent flush>
+            <Table>
+              <TableHeader>
+                <TableRow>
+                  <TableHead>{t("tableDocs.item")}</TableHead>
+                  <TableHead align="end">{t("tableDocs.amount")}</TableHead>
+                  <TableHead>{t("tableDocs.status")}</TableHead>
+                </TableRow>
+              </TableHeader>
+              <TableBody>
+                <TableRow>
+                  <TableCell>{t("tableDocs.fee")}</TableCell>
+                  <TableCell numeric>¥440</TableCell>
+                  <TableCell>
+                    <Badge tone="neutral">{t("tableDocs.done")}</Badge>
+                  </TableCell>
+                </TableRow>
+                <TableRow tone="warning">
+                  <TableCell>{t("tableDocs.overdue")}</TableCell>
+                  <TableCell numeric>¥128,000</TableCell>
+                  <TableCell>
+                    <Badge tone="warning">{t("tableDocs.check")}</Badge>
+                  </TableCell>
+                </TableRow>
+                <TableRow tone="destructive">
+                  <TableCell>{t("tableDocs.failed")}</TableCell>
+                  <TableCell numeric>¥52,300</TableCell>
+                  <TableCell>
+                    <Badge tone="destructive">{t("tableDocs.failedBadge")}</Badge>
+                  </TableCell>
+                </TableRow>
+              </TableBody>
+            </Table>
+          </CardContent>
+        </Card>
+
         <Card>
           <CardHeader>
             <CardTitle level={2}>関連ファイル · flush, no table</CardTitle>

package/docs/feedback/sheet.tsx

@@ -141,8 +141,8 @@ export default function Demo() {
                 <SheetBody>
                   <Flex direction="col" gap="md">
                     <FormField id="filter-account" label="勘定科目">
-                      <Select value={account} onValueChange={setAccount}>
-                        <SelectTrigger id="filter-account" aria-label="勘定科目">
+                      <Select aria-label="勘定科目" value={account} onValueChange={setAccount}>
+                        <SelectTrigger id="filter-account">
                           <SelectValue placeholder="すべての勘定科目" />
                         </SelectTrigger>
                         <SelectContent>
@@ -154,8 +154,8 @@ export default function Demo() {
                       </Select>
                     </FormField>
                     <FormField id="filter-status" label="ステータス">
-                      <Select value={status} onValueChange={setStatus}>
-                        <SelectTrigger id="filter-status" aria-label="ステータス">
+                      <Select aria-label="ステータス" value={status} onValueChange={setStatus}>
+                        <SelectTrigger id="filter-status">
                           <SelectValue placeholder="すべてのステータス" />
                         </SelectTrigger>
                         <SelectContent>
@@ -166,8 +166,8 @@ export default function Demo() {
                       </Select>
                     </FormField>
                     <FormField id="filter-source" label="ソース">
-                      <Select value={source} onValueChange={setSource}>
-                        <SelectTrigger id="filter-source" aria-label="ソース">
+                      <Select aria-label="ソース" value={source} onValueChange={setSource}>
+                        <SelectTrigger id="filter-source">
                           <SelectValue placeholder="すべてのソース" />
                         </SelectTrigger>
                         <SelectContent>
@@ -444,10 +444,10 @@ export default function Demo() {
               modal=&#123;false&#125; on Sheet renders a non-modal panel, a pattern WAI-ARIA APG
               allows. The page behind keeps working: no scrim, no scroll lock, nothing hidden from
               assistive tech, and a press outside does not close the panel. Open the order summary
-              (side=&quot;left&quot;, so the quantity controls stay uncovered), then change a quantity
-              below. The total inside the panel follows. Focus moves into the
-              panel on open, Tab can leave it, Escape closes it while focus is inside, and focus
-              returns to the trigger.
+              (side=&quot;left&quot;, so the quantity controls stay uncovered), then change a
+              quantity below. The total inside the panel follows. Focus moves into the panel on
+              open, Tab can leave it, Escape closes it while focus is inside, and focus returns to
+              the trigger.
             </CardDescription>
           </CardHeader>
           <CardContent>