@godxjp/ui 32.6.0 → 32.7.1

package/DESIGN.md

@@ -102,7 +102,7 @@ Colour is scarce. Most of the screen is canvas, ink and hairline.
 
 ## Typography
 
-- One family. Hierarchy from size steps, weight 400/500/700 and `ink` vs `ink-muted`. Page title ~20px; anything larger belongs on a marketing page.
+- One family. Hierarchy from size steps, weight 400/500/700 and `ink` vs `ink-muted`. Page title ~20px; anything larger belongs on a marketing page. One exception: a long-form document title (Reader) is ~22px, two steps above its ~17.6px section headings, because one step reads flat there.
 - Body 14px / 1.7. Captions and meta 12.5px muted. `Text tabular` on every number, time and money column.
 - Japanese prose: `Text break="phrase"` so lines break between phrases.
 - Copy is quiet and factual: no praise, no alarm, no emoji, no em dash in UI strings. A success message states the fact (「承認しました」).
@@ -123,7 +123,7 @@ Colour is scarce. Most of the screen is canvas, ink and hairline.
 
 ## Components
 
-- **PageContainer** is the page shell: `title`, optional `subtitle`, `breadcrumb`, `extra` (page actions, primary last), `toolbar`, `footer`.
+- **PageContainer** is the page shell: `title`, optional `subtitle`, `breadcrumb`, `extra` (page actions, primary last), `toolbar`, `footer`. Omit `title` only when the content draws the page's one `<h1>` (a document reader); PageContainer then renders no heading.
 - **Card** only for a real boundary: a table with its own toolbar and pagination, a list of setting rows, a dashboard panel, a danger zone (`accent="destructive"`), a selectable item. Not around every section, never nested. `CardContent flush` for tables and row lists.
 - **Toolbar** (+ `ToolbarGroup`) is the filter strip: search, labelled filters, clear-all, result count. It sits above the table, never in the page header.
 - **DataTable** for lists: sort, selection with `DataTable.BulkActions`, density, empty/loading/error states. Row actions in one kebab `DropdownMenu`.
@@ -146,6 +146,14 @@ Header: record name as title, status `Badge` beside it, actions in `extra` (one
 
 `Form` in a narrow measure; fields grouped by Heading sections, not Cards. Labels via `FormField`; helper text only when it adds information. One primary submit and a secondary cancel at the end, or in a sticky footer for long forms. Errors inline on the field plus `FormErrors` summary on submit.
 
+### Editor
+
+Edit (or create) one document or record. Header: record name as title, status `Badge` beside it, a subtitle only for a fact such as when it was last saved, and ONE primary Save in `extra` (`Button type="submit" form=<form id>`), Cancel `outline` before it. Body: one `Form` in a `SplitPane`: the main column holds the title field and a large body editor (`BlockEditor`, or `Textarea autoSize`); the aside holds metadata fields and read-only facts in `Descriptions`. The change note goes either directly under the body (where the writer finishes) or last in the aside — pick one per app and keep it. Name each aside group with a `Heading level={2}` one step above its field labels. A part that is its own controlled component with its own `Form` (forms cannot nest) stays a separate form; the header Save then submits by handler (`onClick`) instead of `form=<id>`, still one Save. No Card per field group, no second Save at the bottom.
+
+### Reader
+
+A long-form document to read. The document owns the page's one `<h1>`: `PageContainer` gets `breadcrumb` and `extra` (Edit) and no `title`. `LegalDocumentShell` draws the reading column: title two steps above the section headings, one metadata line (version, date with `dateKind="updated"` for a revision), the contents rail, and prose at a reading measure with `Text break="phrase"` for Japanese. No Card around the article, no subtitle, no icon per heading.
+
 ### Settings
 
 Each section is a Heading (plus one muted line if it adds a fact) over its content: `Descriptions` for read-only values, `ListRow` rows in one `Card` with `CardContent flush` for controls (`trailing` holds the control). Separate sections with spacing or a `Separator`. Changes that apply instantly need no Save button; a page with a Save button applies nothing until saved. Destructive actions last, in one `Card accent="destructive"`, each behind `AlertDialog`.
@@ -197,5 +205,7 @@ A list whose rows are decisions. Show requester, target, reason, submitted time;
 
 - The default primary is neutral by design; a product without a brand colour looks monochrome until one is set.
 - `ui-audit` checks primitives and tokens, not structure: a page can pass it and still show every Don't above.
+- `card-per-section` counts Cards per file, so a screen split across components can pass with a Card around every section.
 - Exemplar previews deploy on release tags, so they can lag `main`. On GitHub Pages a showcase URL answers HTTP 404 and renders through `404.html`, so open it in a browser; a plain fetch sees the 404.
 - Dark theme (`data-theme="dark"`) is supported; the exemplars are reviewed in light.
+- On narrow screens the `PageContainer` title steps down (≈17.6px) while body h2 stays ≈15.7px — one step apart. A document page not built on `LegalDocumentShell` keeps only that step on phones; there is no intermediate page-title size yet.

package/README.md

@@ -18,7 +18,7 @@ npm i @godxjp/ui
 
 <!-- agent-catalog-counts:start -->
 
-The catalog — 161 components, 2195 tokens, 43 cardinal rules — is published in two forms from one
+The catalog — 161 components, 2197 tokens, 43 cardinal rules — is published in two forms from one
 source. **Entry point for either: [`AGENTS.md`](AGENTS.md).**
 <!-- agent-catalog-counts:end -->
 
@@ -51,12 +51,12 @@ static files straight from this public repo — no hosting, no deploy step:
 | --- | --- | --- |
 | [`agent/START-HERE.md`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/START-HERE.md) | 11 KB | **read first** — self-contained: the four rules, the token override model, a page that passes review |
 | [`agent/llms.txt`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/llms.txt) | 3 KB | the [llms.txt](https://llmstxt.org/) entry point |
-| [`agent/DESIGN.md`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/DESIGN.md) | 12 KB | the visual spec: tokens, colour scarcity, admin screen anatomy, do/don't |
+| [`agent/DESIGN.md`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/DESIGN.md) | 14 KB | the visual spec: tokens, colour scarcity, admin screen anatomy, do/don't |
 | [`agent/index.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/index.json) | 3 KB | manifest: version, counts, every file's URL |
 | [`agent/components-index.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json) | 47 KB | all 161 as name + group + tagline — **fetch this first** |
 | [`agent/components/<Name>.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components/Select.json) | 1 KB–37 KB | one file per component, each with its `importPath` — **this is the route to take** |
 | [`agent/components.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components.json) | 1.2 MB | all 161 entries in one file — most URL fetchers truncate this silently; prefer the per-component files |
-| [`agent/tokens.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json) | 846 KB | all 2195 design tokens, their values and why they exist |
+| [`agent/tokens.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json) | 846 KB | all 2197 design tokens, their values and why they exist |
 | [`agent/vocabulary.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/vocabulary.json) | 7 KB | the controlled prop vocabulary |
 | [`agent/rules.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/rules.json) | 21 KB | the 43 cardinal rules |
 <!-- prettier-ignore-end -->

package/agent/DESIGN.md

@@ -102,7 +102,7 @@ Colour is scarce. Most of the screen is canvas, ink and hairline.
 
 ## Typography
 
-- One family. Hierarchy from size steps, weight 400/500/700 and `ink` vs `ink-muted`. Page title ~20px; anything larger belongs on a marketing page.
+- One family. Hierarchy from size steps, weight 400/500/700 and `ink` vs `ink-muted`. Page title ~20px; anything larger belongs on a marketing page. One exception: a long-form document title (Reader) is ~22px, two steps above its ~17.6px section headings, because one step reads flat there.
 - Body 14px / 1.7. Captions and meta 12.5px muted. `Text tabular` on every number, time and money column.
 - Japanese prose: `Text break="phrase"` so lines break between phrases.
 - Copy is quiet and factual: no praise, no alarm, no emoji, no em dash in UI strings. A success message states the fact (「承認しました」).
@@ -123,7 +123,7 @@ Colour is scarce. Most of the screen is canvas, ink and hairline.
 
 ## Components
 
-- **PageContainer** is the page shell: `title`, optional `subtitle`, `breadcrumb`, `extra` (page actions, primary last), `toolbar`, `footer`.
+- **PageContainer** is the page shell: `title`, optional `subtitle`, `breadcrumb`, `extra` (page actions, primary last), `toolbar`, `footer`. Omit `title` only when the content draws the page's one `<h1>` (a document reader); PageContainer then renders no heading.
 - **Card** only for a real boundary: a table with its own toolbar and pagination, a list of setting rows, a dashboard panel, a danger zone (`accent="destructive"`), a selectable item. Not around every section, never nested. `CardContent flush` for tables and row lists.
 - **Toolbar** (+ `ToolbarGroup`) is the filter strip: search, labelled filters, clear-all, result count. It sits above the table, never in the page header.
 - **DataTable** for lists: sort, selection with `DataTable.BulkActions`, density, empty/loading/error states. Row actions in one kebab `DropdownMenu`.
@@ -146,6 +146,14 @@ Header: record name as title, status `Badge` beside it, actions in `extra` (one
 
 `Form` in a narrow measure; fields grouped by Heading sections, not Cards. Labels via `FormField`; helper text only when it adds information. One primary submit and a secondary cancel at the end, or in a sticky footer for long forms. Errors inline on the field plus `FormErrors` summary on submit.
 
+### Editor
+
+Edit (or create) one document or record. Header: record name as title, status `Badge` beside it, a subtitle only for a fact such as when it was last saved, and ONE primary Save in `extra` (`Button type="submit" form=<form id>`), Cancel `outline` before it. Body: one `Form` in a `SplitPane`: the main column holds the title field and a large body editor (`BlockEditor`, or `Textarea autoSize`); the aside holds metadata fields and read-only facts in `Descriptions`. The change note goes either directly under the body (where the writer finishes) or last in the aside — pick one per app and keep it. Name each aside group with a `Heading level={2}` one step above its field labels. A part that is its own controlled component with its own `Form` (forms cannot nest) stays a separate form; the header Save then submits by handler (`onClick`) instead of `form=<id>`, still one Save. No Card per field group, no second Save at the bottom.
+
+### Reader
+
+A long-form document to read. The document owns the page's one `<h1>`: `PageContainer` gets `breadcrumb` and `extra` (Edit) and no `title`. `LegalDocumentShell` draws the reading column: title two steps above the section headings, one metadata line (version, date with `dateKind="updated"` for a revision), the contents rail, and prose at a reading measure with `Text break="phrase"` for Japanese. No Card around the article, no subtitle, no icon per heading.
+
 ### Settings
 
 Each section is a Heading (plus one muted line if it adds a fact) over its content: `Descriptions` for read-only values, `ListRow` rows in one `Card` with `CardContent flush` for controls (`trailing` holds the control). Separate sections with spacing or a `Separator`. Changes that apply instantly need no Save button; a page with a Save button applies nothing until saved. Destructive actions last, in one `Card accent="destructive"`, each behind `AlertDialog`.
@@ -197,5 +205,7 @@ A list whose rows are decisions. Show requester, target, reason, submitted time;
 
 - The default primary is neutral by design; a product without a brand colour looks monochrome until one is set.
 - `ui-audit` checks primitives and tokens, not structure: a page can pass it and still show every Don't above.
+- `card-per-section` counts Cards per file, so a screen split across components can pass with a Card around every section.
 - Exemplar previews deploy on release tags, so they can lag `main`. On GitHub Pages a showcase URL answers HTTP 404 and renders through `404.html`, so open it in a browser; a plain fetch sees the 404.
 - Dark theme (`data-theme="dark"`) is supported; the exemplars are reviewed in light.
+- On narrow screens the `PageContainer` title steps down (≈17.6px) while body h2 stays ≈15.7px — one step apart. A document page not built on `LegalDocumentShell` keeps only that step on phones; there is no intermediate page-title size yet.

package/agent/START-HERE.md

@@ -3,7 +3,7 @@
 You are about to write code against a design system you did not author. This file is the whole
 contract. Read it before you write JSX.
 
-**This catalog describes `@godxjp/ui` 32.6.0.** If the project you are editing has a different
+**This catalog describes `@godxjp/ui` 32.7.1.** If the project you are editing has a different
 version in its `package.json`, read the pinned catalog for THAT version instead
 (`…/v<their-version>/agent/…`). A catalog newer than the installed package describes props that do
 not exist yet; older, and it hides props that do. Neither failure announces itself.
@@ -59,10 +59,10 @@ screen anatomy, the visual target the rules below do not give you. Then fetch in
    its `importPath`, and its examples. Fetch only the handful you picked in step 1.
 3. `rules.json` — 43 cardinal rules. The ones about raw HTML and hardcoded colour are not
    style advice.
-4. `tokens.json` — 2195 design tokens, each tagged with its `tier`. **If you were handed a
+4. `tokens.json` — 2197 design tokens, each tagged with its `tier`. **If you were handed a
    brand, read the 211 `foundation` entries first** — `--primary`, `--background`,
    `--radius`, `--font-size-base` are the handful everything else derives from. The
-   1872 `component` entries are per-part knobs; reach for one only when a role is
+   1874 `component` entries are per-part knobs; reach for one only when a role is
    right everywhere except one component.
 5. `anti-ai-tells.json` — 35 shapes that make generated UI look generated, each with the
    fix. Read before you reach for a gradient hero or a wall of coloured chips.
@@ -148,7 +148,7 @@ has stopped following the brand.
 |---|---|---|---|
 | `foundation` | 211 | the seeds — `--primary`, `--background`, `--foreground`, `--radius`, `--font-size-base`, `--shadow-color`. Everything below is derived from these | **yes — this is the main road.** The default `--primary` is a neutral placeholder: set it (`:root { --primary: <H> <S>% <L>%; }`, HSL components, no `hsl()` wrapper) or import a theme preset such as `@godxjp/ui/themes/godx.css` |
 | `semantic` | 112 | named roles that follow the seeds — `--ring`, `--text-link`, `--primary-hover`, `--overlay-background` | only when the seed is right and ONE role must differ. That role then stops following a later brand change |
-| `component` | 1872 | per-part knobs, `--{component}-{part}-{property}` | rarely. Most are declared `initial` with the real default at the call site — deliberate, so a scoped override re-resolves instead of freezing at `:root` |
+| `component` | 1874 | per-part knobs, `--{component}-{part}-{property}` | rarely. Most are declared `initial` with the real default at the call site — deliberate, so a scoped override re-resolves instead of freezing at `:root` |
 
 A token whose `value` is `initial` is not empty and not broken: `initial` is the guaranteed-invalid
 value, so the real default is computed where the element paints it. Set it and yours wins.

package/agent/components/Anchor.json

@@ -71,7 +71,7 @@
       "type": "(event: React.MouseEvent<HTMLAnchorElement>, item: AnchorItemProp) => void"
     },
     {
-      "description": "Accessible name of the <nav> landmark. antd ships an unnamed <div>; a page routinely carries a breadcrumb, a rail and this, so a localized default (\"On this page\") applies when omitted.",
+      "description": "SCREEN-READER-ONLY accessible name of the <nav> landmark — it is never drawn (unlike Progress `label`, which is a visible caption). Need a visible heading over the links? Render a Heading yourself and keep this as the landmark name. antd ships an unnamed <div>; a page routinely carries a breadcrumb, a rail and this, so a localized default (\"On this page\") applies when omitted.",
       "name": "label",
       "type": "string"
     },

package/agent/components/ChatSuggestion.json

@@ -92,7 +92,7 @@
     6
   ],
   "storyPath": "data-entry/chat-composer.tsx",
-  "tagline": "Trigger-character autocomplete over a ChatComposer (Ant Design X Suggestion): type / at a word boundary and a Command list opens against the composer, driven from the textarea without ever taking focus off it.",
+  "tagline": "In @godxjp/chat since v32, not @godxjp/ui: add @godxjp/chat as a dependency at the same version as @godxjp/ui. Trigger-character autocomplete over a ChatComposer (Ant Design X Suggestion): type / at a word boundary and a Command list opens against the composer, driven from the textarea without ever taking focus off it.",
   "usage": [
     "DO wire BOTH halves of the render prop: `onTrigger` from the composer's onValueChange and `onKeyDown` from its onKeyDown. With only one wired the list either never opens or cannot be driven.",
     "DO decide yourself what a pick does to the draft — onValueChange hands you the value; the typed /query is still in the box, so replace it or append to it as your screen needs.",

package/agent/components/LegalDocumentShell.json

@@ -5,7 +5,7 @@
   "name": "LegalDocumentShell",
   "props": [
     {
-      "description": "Document title — the <h1> that names the <article> (e.g. 'Terms of Service').",
+      "description": "Document title — the <h1> that names the <article> (e.g. 'Terms of Service'). Sized two type steps above the section <h2>s (--legal-document-title-font-size, default the --font-size-2xl step) so the page does not read flat. Around it, PageContainer may omit `title` so this stays the page's only <h1>.",
       "name": "title",
       "required": true,
       "type": "ReactNode"
@@ -26,6 +26,12 @@
       "name": "effectiveDate",
       "type": "string"
     },
+    {
+      "defaultValue": "\"effective\"",
+      "description": "What the date means, which picks its localized caption: 'effective' (施行日 / Effective, a policy in force from that date) or 'updated' (更新日 / Updated, a wiki page or help article last revised). Never prefix a label of your own to the date: word order differs per locale.",
+      "name": "dateKind",
+      "type": "\"effective\" | \"updated\""
+    },
     {
       "description": "Short plain-language summary rendered under the metadata, above the contents.",
       "name": "summary",

package/agent/components/PageContainer.json

@@ -20,9 +20,8 @@
       "type": "string"
     },
     {
-      "description": "Page heading rendered as <h1>.",
+      "description": "Page heading rendered as <h1>. OPTIONAL when the content draws its own heading (a document reader, LegalDocumentShell): omitted, no <h1> is rendered and a header with no other slot is dropped. The page must then still have exactly one <h1> from its content; `titleRef` has nothing to attach to.",
       "name": "title",
-      "required": true,
       "type": "string"
     },
     {

package/agent/components/Progress.json

@@ -26,7 +26,7 @@
       "type": "string"
     },
     {
-      "description": "Text label beside/below the bar; it also becomes the accessible name. Pass `aria-labelledby` instead when the name is ALREADY on screen (a row's company name, a card heading) — the bar then borrows it rather than repeating it.",
+      "description": "VISIBLE caption beside/below the bar; it also becomes the accessible name. (Unlike Anchor `label`, which is screen-reader-only: there the name is never drawn.) Pass `aria-labelledby` instead when the name is ALREADY on screen (a row's company name, a card heading) — the bar then borrows it rather than repeating it.",
       "name": "label",
       "type": "string"
     },

package/agent/components-index.json

@@ -812,7 +812,7 @@
   {
     "group": "data-entry",
     "name": "ChatSuggestion",
-    "tagline": "Trigger-character autocomplete over a ChatComposer (Ant Design X Suggestion): type / at a word boundary and a Command list opens against the composer, driven from the textarea without ever taking focus off it."
+    "tagline": "In @godxjp/chat since v32, not @godxjp/ui: add @godxjp/chat as a dependency at the same version as @godxjp/ui. Trigger-character autocomplete over a ChatComposer (Ant Design X Suggestion): type / at a word boundary and a Command list opens against the composer, driven from the textarea without ever taking focus off it."
   },
   {
     "group": "navigation",

package/agent/components.json

@@ -665,9 +665,8 @@
         "type": "string"
       },
       {
-        "description": "Page heading rendered as <h1>.",
+        "description": "Page heading rendered as <h1>. OPTIONAL when the content draws its own heading (a document reader, LegalDocumentShell): omitted, no <h1> is rendered and a header with no other slot is dropped. The page must then still have exactly one <h1> from its content; `titleRef` has nothing to attach to.",
         "name": "title",
-        "required": true,
         "type": "string"
       },
       {
@@ -2317,7 +2316,7 @@
     "name": "LegalDocumentShell",
     "props": [
       {
-        "description": "Document title — the <h1> that names the <article> (e.g. 'Terms of Service').",
+        "description": "Document title — the <h1> that names the <article> (e.g. 'Terms of Service'). Sized two type steps above the section <h2>s (--legal-document-title-font-size, default the --font-size-2xl step) so the page does not read flat. Around it, PageContainer may omit `title` so this stays the page's only <h1>.",
         "name": "title",
         "required": true,
         "type": "ReactNode"
@@ -2338,6 +2337,12 @@
         "name": "effectiveDate",
         "type": "string"
       },
+      {
+        "defaultValue": "\"effective\"",
+        "description": "What the date means, which picks its localized caption: 'effective' (施行日 / Effective, a policy in force from that date) or 'updated' (更新日 / Updated, a wiki page or help article last revised). Never prefix a label of your own to the date: word order differs per locale.",
+        "name": "dateKind",
+        "type": "\"effective\" | \"updated\""
+      },
       {
         "description": "Short plain-language summary rendered under the metadata, above the contents.",
         "name": "summary",
@@ -4727,7 +4732,7 @@
         "type": "string"
       },
       {
-        "description": "Text label beside/below the bar; it also becomes the accessible name. Pass `aria-labelledby` instead when the name is ALREADY on screen (a row's company name, a card heading) — the bar then borrows it rather than repeating it.",
+        "description": "VISIBLE caption beside/below the bar; it also becomes the accessible name. (Unlike Anchor `label`, which is screen-reader-only: there the name is never drawn.) Pass `aria-labelledby` instead when the name is ALREADY on screen (a row's company name, a card heading) — the bar then borrows it rather than repeating it.",
         "name": "label",
         "type": "string"
       },
@@ -14902,7 +14907,7 @@
       6
     ],
     "storyPath": "data-entry/chat-composer.tsx",
-    "tagline": "Trigger-character autocomplete over a ChatComposer (Ant Design X Suggestion): type / at a word boundary and a Command list opens against the composer, driven from the textarea without ever taking focus off it.",
+    "tagline": "In @godxjp/chat since v32, not @godxjp/ui: add @godxjp/chat as a dependency at the same version as @godxjp/ui. Trigger-character autocomplete over a ChatComposer (Ant Design X Suggestion): type / at a word boundary and a Command list opens against the composer, driven from the textarea without ever taking focus off it.",
     "usage": [
       "DO wire BOTH halves of the render prop: `onTrigger` from the composer's onValueChange and `onKeyDown` from its onKeyDown. With only one wired the list either never opens or cannot be driven.",
       "DO decide yourself what a pick does to the draft — onValueChange hands you the value; the typed /query is still in the box, so replace it or append to it as your screen needs.",
@@ -15932,7 +15937,7 @@
         "type": "(event: React.MouseEvent<HTMLAnchorElement>, item: AnchorItemProp) => void"
       },
       {
-        "description": "Accessible name of the <nav> landmark. antd ships an unnamed <div>; a page routinely carries a breadcrumb, a rail and this, so a localized default (\"On this page\") applies when omitted.",
+        "description": "SCREEN-READER-ONLY accessible name of the <nav> landmark — it is never drawn (unlike Progress `label`, which is a visible caption). Need a visible heading over the links? Render a Heading yourself and keep this as the landmark name. antd ships an unnamed <div>; a page routinely carries a breadcrumb, a rail and this, so a localized default (\"On this page\") applies when omitted.",
         "name": "label",
         "type": "string"
       },

package/agent/index.json

@@ -4,14 +4,14 @@
     "components": 161,
     "patterns": 24,
     "rules": 43,
-    "tokens": 2195,
+    "tokens": 2197,
     "vocabulary": 14
   },
   "design": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/DESIGN.md",
   "files": [
     {
       "file": "DESIGN.md",
-      "note": "12 KB — the visual spec: tokens, colour scarcity, admin screen anatomy (list, detail, form, settings, dashboard), do/don't. Read before composing a screen.",
+      "note": "14 KB — the visual spec: tokens, colour scarcity, admin screen anatomy (list, detail, form, settings, dashboard), do/don't. Read before composing a screen.",
       "url": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/DESIGN.md"
     },
     {
@@ -54,19 +54,19 @@
   "note": "Pin to the tag that matches the @godxjp/ui version you installed. A catalog newer than your package describes props you do not have; older, and it hides props you do.",
   "read": {
     "live": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/index.json",
-    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v32.6.0/agent/index.json"
+    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v32.7.1/agent/index.json"
   },
   "source": "mcp/src/data — the same data @godxjp/ui-mcp serves — plus the foundation and semantic token tiers, read from src/tokens/*.css",
   "start": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/START-HERE.md",
   "tokenTiers": {
     "component": "per-part knobs, --{component}-{part}-{property}; usually leave these alone",
     "counts": {
-      "component": 1872,
+      "component": 1874,
       "foundation": 211,
       "semantic": 112
     },
     "foundation": "the seeds a consumer is invited to set — --primary, --background, --radius",
     "semantic": "named roles that follow the seeds — --ring, --text-link, --overlay-background"
   },
-  "version": "32.6.0"
+  "version": "32.7.1"
 }

package/agent/llms.txt

@@ -1,17 +1,17 @@
 # @godxjp/ui
 
-> A Japanese-enterprise React design system: 161 components, 2195 design tokens,
-> 43 cardinal rules. This file is the entry point for AI agents. Catalog version 32.6.0.
+> A Japanese-enterprise React design system: 161 components, 2197 design tokens,
+> 43 cardinal rules. This file is the entry point for AI agents. Catalog version 32.7.1.
 
 If your client can run a process, do not read these files — run the MCP server instead
-(`npx @godxjp/ui-mcp@32.6.0`). It is searchable and version-locked. These files exist for agents
+(`npx @godxjp/ui-mcp@32.7.1`). It is searchable and version-locked. These files exist for agents
 that can only fetch URLs.
 
 ## Start
 
 - [START-HERE.md](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/START-HERE.md): the whole contract — the four rules, the token override model, a page that passes review. Read this first; it is self-contained.
 - [index.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/index.json): version, counts, and the URL of every file.
-- [DESIGN.md](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/DESIGN.md): 12 KB — the visual spec: tokens, colour scarcity, admin screen anatomy (list, detail, form, settings, dashboard), do/don't. Read it before composing a screen.
+- [DESIGN.md](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/DESIGN.md): 14 KB — the visual spec: tokens, colour scarcity, admin screen anatomy (list, detail, form, settings, dashboard), do/don't. Read it before composing a screen.
 
 ## Catalog
 
@@ -19,7 +19,7 @@ that can only fetch URLs.
 - [components-index.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json): 47 KB — all 161 components as name, group, tagline, plus `absorbed`: the names that do NOT exist and map to it (`Combobox` → `Select`).
 - [components/<Name>.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components/Select.json): one file per component (1 KB–37 KB, median 6 KB). Read the index, then fetch only the ones you chose — this is the selective route, and the reason you do not need the blob.
 - [components.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components.json): 1.2 MB — every entry in one file. Most URL fetchers truncate a response this size without saying so; prefer the per-component files.
-- [tokens.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json): every design token with its value, the reason it exists, and its `tier` — 211 `foundation` seeds (`--primary`, `--background`, `--radius`: set these when you are handed a brand), 112 `semantic` roles, 1872 `component` knobs.
+- [tokens.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json): every design token with its value, the reason it exists, and its `tier` — 211 `foundation` seeds (`--primary`, `--background`, `--radius`: set these when you are handed a brand), 112 `semantic` roles, 1874 `component` knobs.
 - [vocabulary.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/vocabulary.json): the controlled prop vocabulary — which prop name means what, across every component.
 - [rules.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/rules.json): 43 cardinal rules.
 - [anti-ai-tells.json](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/anti-ai-tells.json): 35 shapes that make generated UI look generated, each with its fix.
@@ -27,7 +27,7 @@ that can only fetch URLs.
 ## Pinning
 
 Every URL above tracks `main`. To pin to the release a project actually installed, swap `main` for
-the tag: `.../godx-jp/godxjp-ui/v32.6.0/agent/...`. A catalog that does not match the installed
+the tag: `.../godx-jp/godxjp-ui/v32.7.1/agent/...`. A catalog that does not match the installed
 package describes props that are absent, or hides props that are present, and says nothing either way.
 
 Pinned catalogs only exist for releases whose tag actually contains `agent/`. If `…/v<version>/agent/index.json` returns 404, that release predates this catalog: read `…/main/…` instead and compare `index.json` → `version` against the package you have, so you at least know which way it drifted.

package/agent/tokens.json

@@ -7877,6 +7877,18 @@
     "tier": "component",
     "value": "15rem"
   },
+  {
+    "description": "Page inline margin of a shell used BARE, the way a public reader page uses it (gh#1296): default = --space-page-x, --space-page-compact-x at ≤720px, resolved at the call site because both re-derive under a density scope. Inside PageContainer / CenteredShell, which already pad, it resolves to 0 so the gutter is never doubled.",
+    "name": "--legal-document-page-padding-inline",
+    "tier": "component",
+    "value": "initial"
+  },
+  {
+    "description": "Document title size — two type-scale steps above a section heading, so the h1 reads as the page title and not as one more section (gh#1296). Default = the --font-size-2xl step.",
+    "name": "--legal-document-title-font-size",
+    "tier": "component",
+    "value": "initial"
+  },
   {
     "description": "Distance the pinned rail keeps from the top of the scrollport.",
     "name": "--legal-document-toc-inset-block-start",

package/dist/components/layout/page-container.js

@@ -61,12 +61,18 @@ function PageContainerRoot({
   children,
   className
 }) {
-  const reveal = stickyFooter && footer != null && footerReveal === "onScroll";
+  const hasTitle = title != null && title !== false && title !== "";
+  const hasIcon = icon != null && icon !== false;
+  const { start: extraStart, end: extraEnd } = resolvePageExtra(extra);
+  const hasHeading = headerLoading || hasTitle || hasIcon || status != null || !!subtitle;
+  const hasBreadcrumb = !!breadcrumb && breadcrumb.length > 0;
+  const hasEyecatch = isValidElement(cover) && cover.props.variant === "eyecatch";
+  const hasHeader = hasHeading || hasBreadcrumb || hasEyecatch || extraStart != null || extraEnd != null;
+  const reveal = stickyFooter && footer != null && footerReveal === "onScroll" && hasHeader;
   const { headerRef, revealed } = useFooterReveal(reveal);
   const footerRef = useRef(null);
   useToastStickyBarClearance([footerRef], stickyFooter && !!footer && (!reveal || revealed));
   const { t } = useTranslation();
-  const { start: extraStart, end: extraEnd } = resolvePageExtra(extra);
   const titleFocus = titleRef === void 0 ? void 0 : { ref: titleRef, tabIndex: -1 };
   const coverVariant = cover == null || cover === false ? void 0 : isValidElement(cover) && cover.props.variant === "eyecatch" ? "eyecatch" : "banner";
   return /* @__PURE__ */ jsxs(
@@ -90,7 +96,7 @@ function PageContainerRoot({
       ),
       children: [
         coverVariant === "banner" ? /* @__PURE__ */ jsx("div", { className: "ui-page-cover-slot", children: cover }) : null,
-        /* @__PURE__ */ jsxs(
+        hasHeader && /* @__PURE__ */ jsxs(
           "header",
           {
             ref: headerRef,
@@ -98,7 +104,7 @@ function PageContainerRoot({
             "data-layout": headerLayout,
             "aria-busy": headerLoading ? "true" : void 0,
             children: [
-              breadcrumb && breadcrumb.length > 0 && /* @__PURE__ */ jsx(
+              hasBreadcrumb && /* @__PURE__ */ jsx(
                 "nav",
                 {
                   "aria-label": breadcrumbLabel ?? breadcrumbAriaLabel ?? t("navigation.breadcrumb.ariaLabel"),
@@ -144,8 +150,8 @@ function PageContainerRoot({
               ),
               coverVariant === "eyecatch" ? /* @__PURE__ */ jsx("div", { className: "ui-page-cover-slot", children: cover }) : null,
               /* @__PURE__ */ jsxs("div", { className: "ui-page-header-row", children: [
-                /* @__PURE__ */ jsxs("div", { className: "ui-page-header-heading", children: [
-                  icon != null && icon !== false ? /* @__PURE__ */ jsx("div", { className: "ui-page-header-icon", children: icon }) : null,
+                hasHeading && /* @__PURE__ */ jsxs("div", { className: "ui-page-header-heading", children: [
+                  hasIcon ? /* @__PURE__ */ jsx("div", { className: "ui-page-header-icon", children: icon }) : null,
                   headerLoading ? /* @__PURE__ */ jsx(
                     "h1",
                     {
@@ -154,9 +160,9 @@ function PageContainerRoot({
                       children: /* @__PURE__ */ jsx("span", { className: "sr-only", children: t("layout.pageHeader.loading") })
                     }
                   ) : status != null ? /* @__PURE__ */ jsxs("div", { className: "ui-page-header-title-row", children: [
-                    /* @__PURE__ */ jsx("h1", { ...titleFocus, className: "ui-page-title", children: title }),
+                    hasTitle && /* @__PURE__ */ jsx("h1", { ...titleFocus, className: "ui-page-title", children: title }),
                     /* @__PURE__ */ jsx("div", { className: "ui-page-header-status", children: status })
-                  ] }) : /* @__PURE__ */ jsx("h1", { ...titleFocus, className: "ui-page-title", children: title }),
+                  ] }) : hasTitle ? /* @__PURE__ */ jsx("h1", { ...titleFocus, className: "ui-page-title", children: title }) : null,
                   headerLoading ? (
                     // Decorative only — the pending state is already announced once by the heading above,
                     // so a second live placeholder here would double-announce it.

package/dist/contracts/measurement.json

@@ -1,6 +1,6 @@
 {
   "$comment": "AUTO-GENERATED by scripts/gen-measurement-contract.mjs — do not edit. Read this instead of guessing: docs/MEASUREMENT-CONTRACT.md.",
-  "version": "32.6.0",
+  "version": "32.7.1",
   "targetSize": {
     "standard": "WCAG 2.2 SC 2.5.8 Target Size (Minimum), level AA — 24×24 CSS px",
     "min": 24,

package/dist/i18n/messages/en.json

@@ -324,7 +324,8 @@
     "legalDocumentShell": {
       "contents": "Contents",
       "version": "Version {version}",
-      "effectiveDate": "Effective {date}"
+      "effectiveDate": "Effective {date}",
+      "updatedDate": "Updated {date}"
     },
     "errorSurface": {
       "statusLabel": "HTTP status {status}",

package/dist/i18n/messages/ja.json

@@ -319,7 +319,8 @@
     "legalDocumentShell": {
       "contents": "目次",
       "version": "バージョン {version}",
-      "effectiveDate": "施行日 {date}"
+      "effectiveDate": "施行日 {date}",
+      "updatedDate": "更新日 {date}"
     },
     "errorSurface": {
       "statusLabel": "HTTP ステータス {status}",

package/dist/i18n/messages/vi.json

@@ -320,7 +320,8 @@
     "legalDocumentShell": {
       "contents": "Mục lục",
       "version": "Phiên bản {version}",
-      "effectiveDate": "Hiệu lực từ {date}"
+      "effectiveDate": "Hiệu lực từ {date}",
+      "updatedDate": "Cập nhật {date}"
     },
     "errorSurface": {
       "statusLabel": "Trạng thái HTTP {status}",

package/dist/lab/legal-document-shell.js

@@ -33,6 +33,7 @@ const LegalDocumentShell = React.forwardRef(
     title,
     version,
     effectiveDate,
+    dateKind = "effective",
     summary,
     contentsLabel,
     sections,
@@ -135,9 +136,12 @@ const LegalDocumentShell = React.forwardRef(
               version !== void 0 && /* @__PURE__ */ jsx("span", { children: t("layout.legalDocumentShell.version", { version }) }),
               effectiveDate !== void 0 && // <time dateTime> keeps the MACHINE-readable value as the ISO 8601 input while
               // the visible text is the Intl-formatted, locale-correct rendering.
-              /* @__PURE__ */ jsx("time", { dateTime: effectiveDate, children: t("layout.legalDocumentShell.effectiveDate", {
-                date: formatEffectiveDate(effectiveDate, locale)
-              }) })
+              /* @__PURE__ */ jsx("time", { dateTime: effectiveDate, children: t(
+                dateKind === "updated" ? "layout.legalDocumentShell.updatedDate" : "layout.legalDocumentShell.effectiveDate",
+                {
+                  date: formatEffectiveDate(effectiveDate, locale)
+                }
+              ) })
             ] }),
             summary !== void 0 && // A <div> (not <p>): the summary slot may carry block content, and a <p> inside a <p>
             // is invalid HTML the browser silently un-nests.

package/dist/props/components/layout.prop.d.ts

@@ -44,7 +44,13 @@ export type PageContainerExtraProp = ExtraProp | {
 export type PageContainerProp = {
     toolbarPad?: PadProp;
     footerPad?: PadProp;
-    title: TitleProp;
+    /**
+     * The page's `<h1>`. Optional for a page whose CONTENT draws its own heading (a document reader,
+     * a LegalDocumentShell): omitted, PageContainer renders no `<h1>` at all, and a header with no
+     * other slot is not rendered. The page must then still have exactly one `<h1>` — from the
+     * content (WCAG 1.3.1 / 2.4.6); `titleRef` has nothing to attach to.
+     */
+    title?: TitleProp;
     subtitle?: SubtitleProp;
     /**
      * Status/meta band rendered beside the title inside the heading — StatusBadge, environment tag,
@@ -1676,6 +1682,12 @@ export type LegalDocumentShellProp = {
      * `<time dateTime={effectiveDate}>`, so the machine-readable value is always the ISO input.
      */
     effectiveDate?: string;
+    /**
+     * What the date in `effectiveDate` means, which picks its localized caption: `"effective"`
+     * (default — 「施行日」 / "Effective", a policy in force from that date) or `"updated"`
+     * (「更新日」 / "Updated", a wiki page or help article last revised on that date).
+     */
+    dateKind?: "effective" | "updated";
     /** Short plain-language summary rendered under the metadata, above the contents. */
     summary?: ReactNode;
     /** Accessible name + visible caption of the contents `<nav>` (e.g. "Contents"). */

package/dist/props/registry.d.ts

@@ -1309,6 +1309,10 @@ export declare const COMPONENT_PROP_REGISTRY: {
             readonly field: "effectiveDate";
             readonly local: true;
             readonly reason: "ISO 8601 date input formatted via Intl.DateTimeFormat in the active locale.";
+        }, {
+            readonly field: "dateKind";
+            readonly local: true;
+            readonly reason: "Meaning of the date (effective | updated) — selects the localized caption, so the consumer never concatenates a label with a formatted date.";
         }, {
             readonly field: "summary";
             readonly local: true;

package/dist/props/registry.js

@@ -1402,6 +1402,11 @@ const COMPONENT_PROP_REGISTRY = {
         local: true,
         reason: "ISO 8601 date input formatted via Intl.DateTimeFormat in the active locale."
       },
+      {
+        field: "dateKind",
+        local: true,
+        reason: "Meaning of the date (effective | updated) \u2014 selects the localized caption, so the consumer never concatenates a label with a formatted date."
+      },
       {
         field: "summary",
         local: true,

package/dist/styles/layers.json

@@ -1,5 +1,5 @@
 {
-  "version": "32.6.0",
+  "version": "32.7.1",
   "generatedBy": "scripts/gen-style-layers.mjs — do not edit by hand; run `pnpm gen:style-layers`",
   "base": "base.css",
   "fonts": "fonts.css",