@godxjp/ui 33.16.0 → 33.18.0

package/README.md

@@ -18,7 +18,7 @@ npm i @godxjp/ui
 
 <!-- agent-catalog-counts:start -->
 
-The catalog — 171 components, 2257 tokens, 44 cardinal rules — is published in two forms from one
+The catalog — 171 components, 2263 tokens, 44 cardinal rules — is published in two forms from one
 source. **Entry point for either: [`AGENTS.md`](AGENTS.md).**
 <!-- agent-catalog-counts:end -->
 
@@ -56,7 +56,7 @@ static files straight from this public repo — no hosting, no deploy step:
 | [`agent/components-index.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json) | 54 KB | all 171 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–38 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.3 MB | all 171 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) | 861 KB | all 2257 design tokens, their values and why they exist |
+| [`agent/tokens.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json) | 862 KB | all 2263 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) | 23 KB | the 44 cardinal rules |
 <!-- prettier-ignore-end -->

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` 33.16.0.** If the project you are editing has a different
+**This catalog describes `@godxjp/ui` 33.18.0.** 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.
@@ -61,10 +61,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` — 44 cardinal rules. The ones about raw HTML and hardcoded colour are not
    style advice.
-4. `tokens.json` — 2257 design tokens, each tagged with its `tier`. **If you were handed a
-   brand, read the 218 `foundation` entries first** — `--primary`, `--background`,
+4. `tokens.json` — 2263 design tokens, each tagged with its `tier`. **If you were handed a
+   brand, read the 220 `foundation` entries first** — `--primary`, `--background`,
    `--radius`, `--font-size-base` are the handful everything else derives from. The
-   1926 `component` entries are per-part knobs; reach for one only when a role is
+   1930 `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,9 +148,9 @@ has stopped following the brand.
 
 | `tier` | count | what it is | set it? |
 |---|---|---|---|
-| `foundation` | 218 | 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` |
+| `foundation` | 220 | 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` | 113 | 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` | 1926 | 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` | 1930 | 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/AppShell.json

@@ -135,7 +135,7 @@
     23
   ],
   "storyPath": "layout/app-shell.tsx",
-  "tagline": "Root application shell — composes sidebar, topbar rail, main content area, and optional footer. Keyboard focus in clipped chrome stays inset; the main scroll region shows an inset brand ring by default (--region-focus-ring-width).",
+  "tagline": "Root application shell — composes sidebar, topbar rail, main content area, and optional footer. In print, navigation, topbar, breadcrumb and footer are hidden; main content flows across the paper width on the light --background. Put every consumer-authored dark theme override inside @media not print, with light declarations outside it, matching the package themes. Keyboard focus in clipped chrome stays inset; the main scroll region shows an inset brand ring by default (--region-focus-ring-width).",
   "usage": [
     "DO put a sidebar collapse toggle IN the rail, not floating in the bar (ADR C10): the shell does not render one, so pass it through `Sidebar action={(collapsed) => <Button variant=\"ghost\" size=\"icon\" aria-label={t(\"toggleSidebar\")} aria-expanded={!collapsed} …/>}` (or the `footer` render-prop), which keeps it attached to the rail in both states. A toggle in `Topbar start` under `topbarSpan=\"full\"` lands beside the brand, detached from the rail it controls. The shell has no edge-mounted toggle (a control straddling the rail border); `Sidebar action` keeps it inside the rail head, which is the supported placement. Below the navigation boundary the drawer has its own trigger; render no collapse toggle there.",
     "useAppShellNavigationMode() returns drawer/docked at the same 56.25rem boundary as AppShell. The root also publishes data-navigation. Use this instead of a consumer media query.",

package/agent/components/BlockEditor.json

@@ -16,7 +16,7 @@
       "type": "string"
     },
     {
-      "description": "Canonical Markdown after each edit — `serialize(editor.getJSON())`, identical to `normalize(body)` from `@godxjp/markdown/codec` (CODEC_ID kit-md@1).",
+      "description": "Canonical Markdown after each edit — `serialize(editor.getJSON())`, identical to `normalize(body)` from `@godxjp/markdown/codec` (CODEC_ID kit-md@2).",
       "name": "onValueChange",
       "type": "(markdown: string) => void"
     },

package/agent/components/Card.json

@@ -84,7 +84,7 @@
     "CardHeader",
     "CardTitle"
   ],
-  "tagline": "Surface container with optional accent stripe, variant fill (including the Ant Design borderless edge), hoverable lift, and density. ⚠️ The bare <Card> has NO inner padding — body content MUST be wrapped in <CardContent> (titles in <CardHeader>), or it sits FLUSH against the card edges. Never hand-roll padding with className=\"p-4\"; use <CardContent>. Compose with CardHeader/CardTitle/CardContent/CardFooter. For Ant Design's card-head TAB STRIP (tabs under the title, inside the card border) use the `tabList`/`activeTabKey`/`defaultActiveTabKey`/`onTabChange`/`extra`/`tabProps` props — the Card renders the strip and the children become the selected tab's body. For a non-tab TOOL strip inside the card (composer or editor tools) use <CardBar extra={…}> — a positionable bar that auto-draws its separator from its position (top→bottom border, bottom→top border, middle→both) and pins `extra` content to the inline-end edge; place it as first/last child of the Card. List FILTERS (search, filter selects, filter chips) are NOT a CardBar: CardBar's main slot scrolls sideways, and a filter strip never does — they go in a FilterBar ABOVE the card, which wraps (cardinal rule #51, pattern `list-filters`).",
+  "tagline": "Surface container that requests break-inside: avoid in print, with optional accent stripe, variant fill (including the Ant Design borderless edge), hoverable lift, and density. ⚠️ The bare <Card> has NO inner padding — body content MUST be wrapped in <CardContent> (titles in <CardHeader>), or it sits FLUSH against the card edges. Never hand-roll padding with className=\"p-4\"; use <CardContent>. Compose with CardHeader/CardTitle/CardContent/CardFooter. For Ant Design's card-head TAB STRIP (tabs under the title, inside the card border) use the `tabList`/`activeTabKey`/`defaultActiveTabKey`/`onTabChange`/`extra`/`tabProps` props — the Card renders the strip and the children become the selected tab's body. For a non-tab TOOL strip inside the card (composer or editor tools) use <CardBar extra={…}> — a positionable bar that auto-draws its separator from its position (top→bottom border, bottom→top border, middle→both) and pins `extra` content to the inline-end edge; place it as first/last child of the Card. List FILTERS (search, filter selects, filter chips) are NOT a CardBar: CardBar's main slot scrolls sideways, and a filter strip never does — they go in a FilterBar ABOVE the card, which wraps (cardinal rule #51, pattern `list-filters`).",
   "usage": [
     "DO always wrap body content in <CardContent> — the bare <Card> div has zero inner padding; content renders flush against card edges without it. Never add className=\"p-4\" directly on <Card> as a substitute.",
     "DO put titles/descriptions in <CardHeader>/<CardTitle>/<CardDescription>. Use <CardHeader banded> for a visually separated muted-background header band (mirrors <CardFooter separated>). Pair with <CardAction> inside a flex-row CardHeader for header-level action buttons.",

package/agent/components/Heading.json

@@ -44,6 +44,12 @@
       "description": "Single-line ellipsis.",
       "name": "truncate",
       "type": "boolean"
+    },
+    {
+      "defaultValue": "\"display\"",
+      "description": "Heading face. `editorial` sets this heading in --font-family-editorial — the opt-in serif a public/editorial page uses for its hero and section headings while every UI heading stays in the display face. Until a theme names --font-family-editorial it falls back to --font-family-display, so the prop is inert by default. Prefer it over moving --font-family-display, which re-faces EVERY heading (card titles, empty states, form sections).",
+      "name": "family",
+      "type": "\"display\" | \"editorial\""
     }
   ],
   "rules": [

package/agent/components/Markdown.json

@@ -63,7 +63,7 @@
       "type": "string"
     },
     {
-      "description": "Visible titles for GitHub-alert callouts (`> [!WARNING]`) that carry none of their own. English by default (the package has no i18n); pass localized strings. Grammar v1 (gh#1156): callouts, `:::toggle[summary]`, `::::columns`/`:::column{width=N}`, CJK-friendly emphasis — the same syntax the pure codec at `@godxjp/markdown/codec` (CODEC_ID kit-md@1, parse/serialize/normalize, DOM-free) and @godxjp/block-editor use.",
+      "description": "Visible titles for GitHub-alert callouts (`> [!WARNING]`) that carry none of their own. English by default (the package has no i18n); pass localized strings. Grammar v1 (gh#1156): callouts, `:::toggle[summary]`, `::::columns`/`:::column{width=N}`, CJK-friendly emphasis — the same syntax the pure codec at `@godxjp/markdown/codec` (CODEC_ID kit-md@2, parse/serialize/normalize, DOM-free) and @godxjp/block-editor use.",
       "name": "calloutTitles",
       "type": "Partial<Record<'note' | 'tip' | 'important' | 'warning' | 'caution', string>>"
     },
@@ -72,6 +72,12 @@
       "description": "`false` keeps ```mermaid fences as code. Diagrams need the optional peer `mermaid`.",
       "name": "mermaid",
       "type": "boolean"
+    },
+    {
+      "defaultValue": "true",
+      "description": "Fenced code in a known language is tokenised at parse time as `<span data-code-token>` with the kit's twelve names, which Prose colours (renderer v6). `false` leaves plain text for a host `pre` with its own highlighter.",
+      "name": "highlight",
+      "type": "boolean"
     }
   ],
   "related": [
@@ -87,6 +93,7 @@
     "Table of contents: outline(markdown) from @godxjp/markdown/codec returns { depth, text, id }[] with exactly the ids <Markdown> writes — feed it to the kit Anchor. YAML front matter is kept verbatim and never rendered; frontmatterOf(markdown) returns it (gh#1163).",
     "DO `<Prose><Markdown>{body}</Markdown></Prose>` for every rendered body (wiki page, issue, mail).",
     "DO record `MARKDOWN_FORMAT` and `RENDERER_VERSION` on stored versions.",
+    "DO `import \"@godxjp/markdown/katex.css\"` once in the app: `$…$`, `$$…$$` and ```math are drawn by KaTeX at parse time (trust: false, renderer v6) and need its stylesheet and fonts. A single `$` follows Pandoc's rule, so `$5 and $10` stays text.",
     "DON'T assemble react-markdown + rehype-sanitize per app, add rehype-raw, or render Mermaid yourself — `checkMermaidSvg` is the gate."
   ]
 }

package/agent/components/Table.json

@@ -95,6 +95,7 @@
   "storyPath": "data-display/table.tsx",
   "subParts": [
     "TableBody",
+    "TableCaption",
     "TableCell",
     "TableHead",
     "TableHeader",

package/agent/components-index.json

@@ -72,7 +72,7 @@
   {
     "group": "layout",
     "name": "AppShell",
-    "tagline": "Root application shell — composes sidebar, topbar rail, main content area, and optional footer. Keyboard focus in clipped chrome stays inset; the main scroll region shows an inset brand ring by default (--region-focus-ring-width)."
+    "tagline": "Root application shell — composes sidebar, topbar rail, main content area, and optional footer. In print, navigation, topbar, breadcrumb and footer are hidden; main content flows across the paper width on the light --background. Put every consumer-authored dark theme override inside @media not print, with light declarations outside it, matching the package themes. Keyboard focus in clipped chrome stays inset; the main scroll region shows an inset brand ring by default (--region-focus-ring-width)."
   },
   {
     "absorbed": [
@@ -215,7 +215,7 @@
   {
     "group": "data-display",
     "name": "Card",
-    "tagline": "Surface container with optional accent stripe, variant fill (including the Ant Design borderless edge), hoverable lift, and density. ⚠️ The bare <Card> has NO inner padding — body content MUST be wrapped in <CardContent> (titles in <CardHeader>), or it sits FLUSH against the card edges. Never hand-roll padding with className=\"p-4\"; use <CardContent>. Compose with CardHeader/CardTitle/CardContent/CardFooter. For Ant Design's card-head TAB STRIP (tabs under the title, inside the card border) use the `tabList`/`activeTabKey`/`defaultActiveTabKey`/`onTabChange`/`extra`/`tabProps` props — the Card renders the strip and the children become the selected tab's body. For a non-tab TOOL strip inside the card (composer or editor tools) use <CardBar extra={…}> — a positionable bar that auto-draws its separator from its position (top→bottom border, bottom→top border, middle→both) and pins `extra` content to the inline-end edge; place it as first/last child of the Card. List FILTERS (search, filter selects, filter chips) are NOT a CardBar: CardBar's main slot scrolls sideways, and a filter strip never does — they go in a FilterBar ABOVE the card, which wraps (cardinal rule #51, pattern `list-filters`)."
+    "tagline": "Surface container that requests break-inside: avoid in print, with optional accent stripe, variant fill (including the Ant Design borderless edge), hoverable lift, and density. ⚠️ The bare <Card> has NO inner padding — body content MUST be wrapped in <CardContent> (titles in <CardHeader>), or it sits FLUSH against the card edges. Never hand-roll padding with className=\"p-4\"; use <CardContent>. Compose with CardHeader/CardTitle/CardContent/CardFooter. For Ant Design's card-head TAB STRIP (tabs under the title, inside the card border) use the `tabList`/`activeTabKey`/`defaultActiveTabKey`/`onTabChange`/`extra`/`tabProps` props — the Card renders the strip and the children become the selected tab's body. For a non-tab TOOL strip inside the card (composer or editor tools) use <CardBar extra={…}> — a positionable bar that auto-draws its separator from its position (top→bottom border, bottom→top border, middle→both) and pins `extra` content to the inline-end edge; place it as first/last child of the Card. List FILTERS (search, filter selects, filter chips) are NOT a CardBar: CardBar's main slot scrolls sideways, and a filter strip never does — they go in a FilterBar ABOVE the card, which wraps (cardinal rule #51, pattern `list-filters`)."
   },
   {
     "group": "data-display",

package/agent/components.json

@@ -1329,7 +1329,7 @@
       23
     ],
     "storyPath": "layout/app-shell.tsx",
-    "tagline": "Root application shell — composes sidebar, topbar rail, main content area, and optional footer. Keyboard focus in clipped chrome stays inset; the main scroll region shows an inset brand ring by default (--region-focus-ring-width).",
+    "tagline": "Root application shell — composes sidebar, topbar rail, main content area, and optional footer. In print, navigation, topbar, breadcrumb and footer are hidden; main content flows across the paper width on the light --background. Put every consumer-authored dark theme override inside @media not print, with light declarations outside it, matching the package themes. Keyboard focus in clipped chrome stays inset; the main scroll region shows an inset brand ring by default (--region-focus-ring-width).",
     "usage": [
       "DO put a sidebar collapse toggle IN the rail, not floating in the bar (ADR C10): the shell does not render one, so pass it through `Sidebar action={(collapsed) => <Button variant=\"ghost\" size=\"icon\" aria-label={t(\"toggleSidebar\")} aria-expanded={!collapsed} …/>}` (or the `footer` render-prop), which keeps it attached to the rail in both states. A toggle in `Topbar start` under `topbarSpan=\"full\"` lands beside the brand, detached from the rail it controls. The shell has no edge-mounted toggle (a control straddling the rail border); `Sidebar action` keeps it inside the rail head, which is the supported placement. Below the navigation boundary the drawer has its own trigger; render no collapse toggle there.",
       "useAppShellNavigationMode() returns drawer/docked at the same 56.25rem boundary as AppShell. The root also publishes data-navigation. Use this instead of a consumer media query.",
@@ -3042,6 +3042,12 @@
         "description": "Single-line ellipsis.",
         "name": "truncate",
         "type": "boolean"
+      },
+      {
+        "defaultValue": "\"display\"",
+        "description": "Heading face. `editorial` sets this heading in --font-family-editorial — the opt-in serif a public/editorial page uses for its hero and section headings while every UI heading stays in the display face. Until a theme names --font-family-editorial it falls back to --font-family-display, so the prop is inert by default. Prefer it over moving --font-family-display, which re-faces EVERY heading (card titles, empty states, form sections).",
+        "name": "family",
+        "type": "\"display\" | \"editorial\""
       }
     ],
     "rules": [
@@ -3756,7 +3762,7 @@
       "CardHeader",
       "CardTitle"
     ],
-    "tagline": "Surface container with optional accent stripe, variant fill (including the Ant Design borderless edge), hoverable lift, and density. ⚠️ The bare <Card> has NO inner padding — body content MUST be wrapped in <CardContent> (titles in <CardHeader>), or it sits FLUSH against the card edges. Never hand-roll padding with className=\"p-4\"; use <CardContent>. Compose with CardHeader/CardTitle/CardContent/CardFooter. For Ant Design's card-head TAB STRIP (tabs under the title, inside the card border) use the `tabList`/`activeTabKey`/`defaultActiveTabKey`/`onTabChange`/`extra`/`tabProps` props — the Card renders the strip and the children become the selected tab's body. For a non-tab TOOL strip inside the card (composer or editor tools) use <CardBar extra={…}> — a positionable bar that auto-draws its separator from its position (top→bottom border, bottom→top border, middle→both) and pins `extra` content to the inline-end edge; place it as first/last child of the Card. List FILTERS (search, filter selects, filter chips) are NOT a CardBar: CardBar's main slot scrolls sideways, and a filter strip never does — they go in a FilterBar ABOVE the card, which wraps (cardinal rule #51, pattern `list-filters`).",
+    "tagline": "Surface container that requests break-inside: avoid in print, with optional accent stripe, variant fill (including the Ant Design borderless edge), hoverable lift, and density. ⚠️ The bare <Card> has NO inner padding — body content MUST be wrapped in <CardContent> (titles in <CardHeader>), or it sits FLUSH against the card edges. Never hand-roll padding with className=\"p-4\"; use <CardContent>. Compose with CardHeader/CardTitle/CardContent/CardFooter. For Ant Design's card-head TAB STRIP (tabs under the title, inside the card border) use the `tabList`/`activeTabKey`/`defaultActiveTabKey`/`onTabChange`/`extra`/`tabProps` props — the Card renders the strip and the children become the selected tab's body. For a non-tab TOOL strip inside the card (composer or editor tools) use <CardBar extra={…}> — a positionable bar that auto-draws its separator from its position (top→bottom border, bottom→top border, middle→both) and pins `extra` content to the inline-end edge; place it as first/last child of the Card. List FILTERS (search, filter selects, filter chips) are NOT a CardBar: CardBar's main slot scrolls sideways, and a filter strip never does — they go in a FilterBar ABOVE the card, which wraps (cardinal rule #51, pattern `list-filters`).",
     "usage": [
       "DO always wrap body content in <CardContent> — the bare <Card> div has zero inner padding; content renders flush against card edges without it. Never add className=\"p-4\" directly on <Card> as a substitute.",
       "DO put titles/descriptions in <CardHeader>/<CardTitle>/<CardDescription>. Use <CardHeader banded> for a visually separated muted-background header band (mirrors <CardFooter separated>). Pair with <CardAction> inside a flex-row CardHeader for header-level action buttons.",
@@ -5081,7 +5087,7 @@
         "type": "string"
       },
       {
-        "description": "Visible titles for GitHub-alert callouts (`> [!WARNING]`) that carry none of their own. English by default (the package has no i18n); pass localized strings. Grammar v1 (gh#1156): callouts, `:::toggle[summary]`, `::::columns`/`:::column{width=N}`, CJK-friendly emphasis — the same syntax the pure codec at `@godxjp/markdown/codec` (CODEC_ID kit-md@1, parse/serialize/normalize, DOM-free) and @godxjp/block-editor use.",
+        "description": "Visible titles for GitHub-alert callouts (`> [!WARNING]`) that carry none of their own. English by default (the package has no i18n); pass localized strings. Grammar v1 (gh#1156): callouts, `:::toggle[summary]`, `::::columns`/`:::column{width=N}`, CJK-friendly emphasis — the same syntax the pure codec at `@godxjp/markdown/codec` (CODEC_ID kit-md@2, parse/serialize/normalize, DOM-free) and @godxjp/block-editor use.",
         "name": "calloutTitles",
         "type": "Partial<Record<'note' | 'tip' | 'important' | 'warning' | 'caution', string>>"
       },
@@ -5090,6 +5096,12 @@
         "description": "`false` keeps ```mermaid fences as code. Diagrams need the optional peer `mermaid`.",
         "name": "mermaid",
         "type": "boolean"
+      },
+      {
+        "defaultValue": "true",
+        "description": "Fenced code in a known language is tokenised at parse time as `<span data-code-token>` with the kit's twelve names, which Prose colours (renderer v6). `false` leaves plain text for a host `pre` with its own highlighter.",
+        "name": "highlight",
+        "type": "boolean"
       }
     ],
     "related": [
@@ -5105,6 +5117,7 @@
       "Table of contents: outline(markdown) from @godxjp/markdown/codec returns { depth, text, id }[] with exactly the ids <Markdown> writes — feed it to the kit Anchor. YAML front matter is kept verbatim and never rendered; frontmatterOf(markdown) returns it (gh#1163).",
       "DO `<Prose><Markdown>{body}</Markdown></Prose>` for every rendered body (wiki page, issue, mail).",
       "DO record `MARKDOWN_FORMAT` and `RENDERER_VERSION` on stored versions.",
+      "DO `import \"@godxjp/markdown/katex.css\"` once in the app: `$…$`, `$$…$$` and ```math are drawn by KaTeX at parse time (trust: false, renderer v6) and need its stylesheet and fonts. A single `$` follows Pandoc's rule, so `$5 and $10` stays text.",
       "DON'T assemble react-markdown + rehype-sanitize per app, add rehype-raw, or render Mermaid yourself — `checkMermaidSvg` is the gate."
     ]
   },
@@ -5192,7 +5205,7 @@
         "type": "string"
       },
       {
-        "description": "Canonical Markdown after each edit — `serialize(editor.getJSON())`, identical to `normalize(body)` from `@godxjp/markdown/codec` (CODEC_ID kit-md@1).",
+        "description": "Canonical Markdown after each edit — `serialize(editor.getJSON())`, identical to `normalize(body)` from `@godxjp/markdown/codec` (CODEC_ID kit-md@2).",
         "name": "onValueChange",
         "type": "(markdown: string) => void"
       },
@@ -5722,6 +5735,7 @@
     "storyPath": "data-display/table.tsx",
     "subParts": [
       "TableBody",
+      "TableCaption",
       "TableCell",
       "TableHead",
       "TableHeader",

package/agent/index.json

@@ -4,8 +4,8 @@
     "components": 171,
     "patterns": 28,
     "rules": 44,
-    "tokens": 2257,
-    "vocabulary": 15
+    "tokens": 2263,
+    "vocabulary": 16
   },
   "design": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/DESIGN.md",
   "files": [
@@ -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/v33.16.0/agent/index.json"
+    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v33.18.0/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": 1926,
-      "foundation": 218,
+      "component": 1930,
+      "foundation": 220,
       "semantic": 113
     },
     "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": "33.16.0"
+  "version": "33.18.0"
 }

package/agent/llms.txt

@@ -1,10 +1,10 @@
 # @godxjp/ui
 
-> A Japanese-enterprise React design system: 171 components, 2257 design tokens,
-> 44 cardinal rules. This file is the entry point for AI agents. Catalog version 33.16.0.
+> A Japanese-enterprise React design system: 171 components, 2263 design tokens,
+> 44 cardinal rules. This file is the entry point for AI agents. Catalog version 33.18.0.
 
 If your client can run a process, do not read these files — run the MCP server instead
-(`npx @godxjp/ui-mcp@33.16.0`). It is searchable and version-locked. These files exist for agents
+(`npx @godxjp/ui-mcp@33.18.0`). It is searchable and version-locked. These files exist for agents
 that can only fetch URLs.
 
 ## Start
@@ -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): 54 KB — all 171 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–38 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.3 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` — 218 `foundation` seeds (`--primary`, `--background`, `--radius`: set these when you are handed a brand), 113 `semantic` roles, 1926 `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` — 220 `foundation` seeds (`--primary`, `--background`, `--radius`: set these when you are handed a brand), 113 `semantic` roles, 1930 `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): 44 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/v33.16.0/agent/...`. A catalog that does not match the installed
+the tag: `.../godx-jp/godxjp-ui/v33.18.0/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/rules.json

@@ -80,7 +80,7 @@
     "title": "No \"platform-only\" exports"
   },
   {
-    "body": "`.dark` / light theme, `data-density` (compact / default / comfortable) and `data-font-size` (sm / base / lg) are axes the component must follow. Read from tokens, never hardcode values.",
+    "body": "`.dark` / light theme, `data-density` (compact / default / comfortable) and `data-font-size` (sm / base / lg) are axes the component must follow. Read from tokens, never hardcode values. Enclose every consumer-authored dark override in @media not print and leave light declarations outside it, matching the shipped themes so paper uses the light palette.",
     "number": 21,
     "title": "Every component honours every theme axis"
   },

package/agent/tokens.json

@@ -773,6 +773,18 @@
     "tier": "foundation",
     "value": "var(--font-family-sans)"
   },
+  {
+    "description": "EDITORIAL face (opt-in) — a magazine-style serif for a hero, an article or a public page's section heading, beside a sans UI. Read by `Heading family=\"editorial\"` and by the PageContainer `headerScale=\"display\"` title. `initial`, default = --font-family-display at the call site, so nothing changes until a theme names a face.",
+    "name": "--font-family-editorial",
+    "tier": "foundation",
+    "value": "initial"
+  },
+  {
+    "description": "FIGURES face (opt-in) — the family tabular numbers are set in (`Text tabular`, `Badge tabular`, numeric TableHead/TableCell): a brand that sets prices in a figure face beside a CJK UI face. `initial` = inherit, so tabular figures keep the surrounding family until a theme names one.",
+    "name": "--font-family-tabular",
+    "tier": "foundation",
+    "value": "initial"
+  },
   {
     "description": "── Type scale — GOLDEN-RATIO modular scale (Ant/Tailwind model). ONE base + ONE ratio; every step is base × ratioⁿ, so the whole scale stays in golden proportion. `--font-size-ratio` is φ^¼ (the golden ratio's quarter-step ≈ 1.1227) — a TRUE golden ratio yet dense enough that headings stay small (h1≈20, h2≈18; pure φ=1.618 would be marketing-size). Internal apps get the 14px DEFAULT with ZERO config; a customer overrides `--font-size-base` (and optionally `--font-size-ratio`) and the entire scale rescales in golden proportion. 14px — THE base (= <body>). The single knob; override to retheme.",
     "name": "--font-size-base",
@@ -7187,6 +7199,12 @@
     "tier": "component",
     "value": "32rem"
   },
+  {
+    "description": "Corner of the dialog panel. `initial`: square mobile, --radius-lg → --radius desktop at the call site; a brand whose dialogs are rounder than its cards (cards 8px, dialogs 16px) sets it once here.",
+    "name": "--dialog-radius",
+    "tier": "component",
+    "value": "initial"
+  },
   {
     "description": "Per-instance width, set by DialogContent `width` (gh#1174) — `initial`, so the default above resolves at the call site; the viewport cap (minus --dialog-viewport-inset) always wins.",
     "name": "--dialog-width",
@@ -12749,6 +12767,24 @@
     "tier": "component",
     "value": "0.06"
   },
+  {
+    "description": "TableCaption — `initial`, defaults resolved at the call site (table-layout.css): ink --muted-foreground, size --font-size-sm, block inset --space-2. It sits above the rows (HTML's own side).",
+    "name": "--table-caption-color",
+    "tier": "component",
+    "value": "initial"
+  },
+  {
+    "description": "Table component tokens: row height, cell padding.",
+    "name": "--table-caption-font-size",
+    "tier": "component",
+    "value": "initial"
+  },
+  {
+    "description": "Table component tokens: row height, cell padding.",
+    "name": "--table-caption-space-y",
+    "tier": "component",
+    "value": "initial"
+  },
   {
     "description": "Distance from the text baseline to the underline. In `em` on purpose: the rule has to stay proportional across the seven type steps, and a px value that reads right at `lg` crowds the descenders at `2xs`. GoDX v2.3 guideline: `.gx a { text-underline-offset: .18em }`",
     "name": "--text-link-underline-offset",

package/agent/vocabulary.json

@@ -1,4 +1,16 @@
 [
+  {
+    "concept": "Opt-in heading face, independent of UI headings.",
+    "name": "HeadingFamilyProp",
+    "notes": "display preserves the default markup; editorial reads --font-family-editorial with --font-family-display as its fallback.",
+    "usedBy": [
+      "Heading"
+    ],
+    "values": [
+      "display",
+      "editorial"
+    ]
+  },
   {
     "concept": "Which breadcrumb item represents the current page.",
     "name": "BreadcrumbCurrentItemProp",

package/dist/components/data-display/index.d.ts

@@ -20,7 +20,7 @@ export { Card, CardBar, CardContent, CardCover, CardDescription, CardFooter, Car
 export type { StatCardProps, CardBarProps, CardTabItemProp, CardTabItemProps } from "./card.js";
 export { ServiceCatalogCta, ServiceLauncherCard, ServiceLauncherCardSkeleton, } from "./service-launcher-card.js";
 export type { ServiceCatalogCtaProps, ServiceLauncherCardProps, ServiceLauncherCardSkeletonProps, ServiceLauncherStatusTone, } from "./service-launcher-card.js";
-export { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "./table.js";
+export { Table, TableBody, TableCaption, TableCell, TableHead, TableHeader, TableRow, } from "./table.js";
 export { Descriptions } from "./descriptions.js";
 export { DataTable, flexRender } from "./data-table.js";
 export type { ColumnDef, Density as TableDensity } from "./data-table.js";

package/dist/components/data-display/index.js

@@ -24,7 +24,15 @@ import {
   ServiceLauncherCard,
   ServiceLauncherCardSkeleton
 } from "./service-launcher-card.js";
-import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "./table.js";
+import {
+  Table,
+  TableBody,
+  TableCaption,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow
+} from "./table.js";
 import { Descriptions } from "./descriptions.js";
 import { DataTable, flexRender } from "./data-table.js";
 import { EmptyState } from "./empty-state.js";
@@ -100,6 +108,7 @@ export {
   Swatch,
   Table,
   TableBody,
+  TableCaption,
   TableCell,
   TableHead,
   TableHeader,

package/dist/components/data-display/table.d.ts

@@ -157,6 +157,15 @@ export declare const Table: React.ForwardRefExoticComponent<React.HTMLAttributes
 } & React.RefAttributes<HTMLTableElement>>;
 export declare const TableHeader: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLTableSectionElement> & React.RefAttributes<HTMLTableSectionElement>>;
 export declare const TableBody: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLTableSectionElement> & React.RefAttributes<HTMLTableSectionElement>>;
+/**
+ * The table's `<caption>` — its accessible name AND the visible sentence that says what the rows
+ * are and under which conditions they were collected ("Prices for the Holo variant · shipping not
+ * included"). Place it as the FIRST child of `<Table>` (HTML requires it). Without this part a
+ * consumer had to hand-roll a raw `<caption>` or put the sentence outside the table, where it no
+ * longer names it. It sits above the rows (HTML's own side); colour, size and inset are knobs:
+ * `--table-caption-color`, `--table-caption-font-size`, `--table-caption-space-y`.
+ */
+export declare const TableCaption: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLTableCaptionElement> & React.RefAttributes<HTMLTableCaptionElement>>;
 /**
  * The row's STATE — same wash/rail/`--surface-*` grounding `DataTable`'s own `rowTone` already
  * writes onto `data-tone` (gh#866). Typed here so a hand-composed row can discover it instead of

package/dist/components/data-display/table.js

@@ -196,6 +196,8 @@ const TableBody = React.forwardRef(({ className, ...props }, ref) => (
   /* @__PURE__ */ jsx("tbody", { ref, "data-slot": "table-body", className: cn(className), ...props })
 ));
 TableBody.displayName = "TableBody";
+const TableCaption = React.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx("caption", { ref, "data-slot": "table-caption", className: cn(className), ...props }));
+TableCaption.displayName = "TableCaption";
 const TableRow = React.forwardRef(({ className, tone, interactive, ...props }, ref) => /* @__PURE__ */ jsx(
   "tr",
   {
@@ -293,6 +295,7 @@ TableCell.displayName = "TableCell";
 export {
   Table,
   TableBody,
+  TableCaption,
   TableCell,
   TableHead,
   TableHeader,

package/dist/components/general/typography.d.ts

@@ -93,4 +93,5 @@ export declare const Heading: React.ForwardRefExoticComponent<Omit<React.HTMLAtt
     align?: import("../../props/index.js").TextAlignProp;
     truncate?: boolean;
     weight?: import("../../props/index.js").FontWeightProp;
+    family?: import("../../props/index.js").HeadingFamilyProp;
 } & React.RefAttributes<HTMLHeadingElement>>;

package/dist/components/general/typography.js

@@ -530,6 +530,7 @@ const Heading = React.forwardRef(
     align,
     truncate,
     weight = "medium",
+    family,
     className,
     ...props
   }, ref) => React.createElement(as ?? `h${level}`, {
@@ -543,6 +544,8 @@ const Heading = React.forwardRef(
     "data-align": align,
     "data-weight": weight,
     "data-truncate": truncate ? "" : void 0,
+    // Only the opt-in face is stamped; a default heading keeps its markup byte-for-byte.
+    "data-family": family === "editorial" ? "editorial" : void 0,
     className: cn("ui-heading", className),
     ...props
   })

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": "33.16.0",
+  "version": "33.18.0",
   "targetSize": {
     "standard": "WCAG 2.2 SC 2.5.8 Target Size (Minimum), level AA — 24×24 CSS px",
     "min": 24,

package/dist/lib/hooks.d.ts

@@ -21,6 +21,14 @@ export declare function useTimeoutFlag(signal: unknown, ms?: number): boolean;
  * first defined value arrives, then PROMOTES to controlled for good.
  */
 export declare function useControlledLatch(valueIsDefined: boolean): boolean;
+/**
+ * Live `matchMedia(query).matches`, hydration-safe. Built on `useSyncExternalStore` so that during
+ * hydration React renders with the SERVER snapshot (`false`, what SSR sent) and switches to the live
+ * match immediately after — the first client render never differs from the server HTML. Reading
+ * `matchMedia` in the initial `useState` made a phone hydrate a different tree than the server sent
+ * (AppShell `data-navigation` "docked" → "drawer", an attribute mismatch React does not patch up).
+ * A client-only mount still gets the live value on its first render.
+ */
 export declare function useMediaQuery(query: string): boolean;
 export declare function useIsMobile(): boolean;
 /**

package/dist/lib/hooks.js

@@ -1,6 +1,6 @@
 "use client";
 import { useLayoutEffect } from "@react-aria/utils";
-import { useEffect, useState } from "react";
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
 import { flushSync } from "react-dom";
 function useDebouncedValue(value, delay = 250) {
   const [debounced, setDebounced] = useState(value);
@@ -43,29 +43,28 @@ function useControlledLatch(valueIsDefined) {
   if (valueIsDefined && !latched) setLatched(true);
   return valueIsDefined || latched;
 }
+const getServerMatch = () => false;
 function useMediaQuery(query) {
-  const isBrowser = typeof window !== "undefined";
-  const getMatch = () => isBrowser ? window.matchMedia(query).matches : false;
-  const [matches, setMatches] = useState(getMatch());
-  useEffect(() => {
-    if (!isBrowser) return void 0;
-    const mediaQuery = window.matchMedia(query);
-    const updateMatch = () => {
-      setMatches(mediaQuery.matches);
-    };
-    updateMatch();
-    if (typeof mediaQuery.addEventListener === "function") {
-      mediaQuery.addEventListener("change", updateMatch);
+  const subscribe = useCallback(
+    (onChange) => {
+      if (typeof window === "undefined" || typeof window.matchMedia !== "function") return () => {
+      };
+      const mediaQuery = window.matchMedia(query);
+      if (typeof mediaQuery.addEventListener === "function") {
+        mediaQuery.addEventListener("change", onChange);
+        return () => {
+          mediaQuery.removeEventListener("change", onChange);
+        };
+      }
+      mediaQuery.addListener(onChange);
       return () => {
-        mediaQuery.removeEventListener("change", updateMatch);
+        mediaQuery.removeListener(onChange);
       };
-    }
-    mediaQuery.addListener(updateMatch);
-    return () => {
-      mediaQuery.removeListener(updateMatch);
-    };
-  }, [isBrowser, query]);
-  return matches;
+    },
+    [query]
+  );
+  const getMatch = () => typeof window !== "undefined" && typeof window.matchMedia === "function" ? window.matchMedia(query).matches : false;
+  return useSyncExternalStore(subscribe, getMatch, getServerMatch);
 }
 function useIsMobile() {
   return useMediaQuery("(max-width: 767px)");

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

@@ -1,6 +1,6 @@
 /** Foundation component prop types — @see docs/COMPONENTS.md#foundation */
 import type * as React from "react";
-import type { ActivityAnnounceProp, ActivityVariantProp, AsChildProp, ButtonSizeProp, ButtonVariantProp, ChildrenProp, ClassNameProp, DescriptionProp, DisabledProp, FontWeightProp, HeadingLevelProp, IconSizeProp, IdProp, InViewAmountProp, LabelProp, OnClickProp, OnOpenChangeProp, OpenProp, PendingProp, RevealDelayProp, RevealTriggerProp, ShapeProp, SizeProp, TextAlignProp, TextSizeProp, TextToneProp, TextWhitespaceProp, TextBreakProp, TypographyActionsConfigProp, TypographyCopyConfigProp, TypographyEditConfigProp, TypographyEllipsisConfigProp, TypographyTypeProp } from "../vocabulary/index.js";
+import type { ActivityAnnounceProp, ActivityVariantProp, AsChildProp, ButtonSizeProp, ButtonVariantProp, ChildrenProp, ClassNameProp, DescriptionProp, DisabledProp, FontWeightProp, HeadingFamilyProp, HeadingLevelProp, IconSizeProp, IdProp, InViewAmountProp, LabelProp, OnClickProp, OnOpenChangeProp, OpenProp, PendingProp, RevealDelayProp, RevealTriggerProp, ShapeProp, SizeProp, TextAlignProp, TextSizeProp, TextToneProp, TextWhitespaceProp, TextBreakProp, TypographyActionsConfigProp, TypographyCopyConfigProp, TypographyEditConfigProp, TypographyEllipsisConfigProp, TypographyTypeProp } from "../vocabulary/index.js";
 /**
  * @see Text — typographic primitive; replaces hand-rolled `<span className="text-[13px] …">`.
  *
@@ -131,6 +131,13 @@ export type HeadingProp = Omit<React.HTMLAttributes<HTMLHeadingElement>, "color"
     truncate?: boolean;
     /** Weight (system canon: 400 · 500 · 700). Default `medium` — set `bold` for an emphasised title. */
     weight?: FontWeightProp;
+    /**
+     * Heading face. `editorial` sets this heading in --font-family-editorial — the opt-in serif a
+     * public or editorial page uses for its hero and section headings while the UI stays sans. Until a
+     * theme names that face it falls back to --font-family-display, so the prop is inert by default.
+     * Omit it (or `display`) for every UI heading.
+     */
+    family?: HeadingFamilyProp;
 };
 /**
  * The antd `BlockProps` behaviour shared by `Text` / `Link`.