@godxjp/ui 32.5.0 → 32.6.0

package/DESIGN.md

@@ -0,0 +1,201 @@
+---
+version: alpha
+name: godxjp-ui
+description: "Restrained Japanese-enterprise admin UI. Warm off-white canvas, near-black ink, one neutral accent, hairline borders, 14px/1.7 type, dense tables. Hierarchy comes from spacing steps and type, not from boxes, colour or shadow."
+
+colors:
+  canvas: "#fdfdfc" # --background (= --card, --popover)
+  ink: "#24231e" # --foreground
+  ink-muted: "#68665e" # --muted-foreground
+  ink-tertiary: "#928f87" # --text-tertiary (captions, meta)
+  primary: "#18181b" # --primary. Neutral placeholder: set your brand here
+  on-primary: "#fdfdfc" # --primary-foreground
+  ring: "{colors.primary}" # --ring follows --primary; no separate focus hue
+  muted: "#f4f3f0" # --muted / --secondary (quiet fills, zebra, hover)
+  accent: "#ebe9e5" # --accent (hover/selected background, NOT a brand colour)
+  hairline: "#eeedec" # --border (dividers, card edges, table rules)
+  control-edge: "#90877f" # --input (the edge of an input; 3:1 against canvas)
+  success: "#68be8d" # --success  若竹
+  warning: "#f8b500" # --warning  山吹
+  info: "#4c6cb3" # --info     群青
+  attention: "#eb6101" # --attention 朱 (non-destructive urgency: late, overdue)
+  destructive: "#b7282e" # --destructive 茜 (delete, failed, irreversible)
+  text-success: "#09673b" # --text-success (status as text, AA on canvas)
+  text-warning: "#8f5600" # --text-warning
+  text-info: "#1d48a5" # --text-info
+  text-error: "#aa181f" # --text-error
+
+typography:
+  family: "system stack (--font-sans-base); Noto Sans JP via opt-in @godxjp/ui/styles/fonts"
+  base: 14px # --font-size-base; every step derives from it (ratio --font-size-ratio 1.1227)
+  page-title: { size: "~20px (--heading-h1)", weight: 500, lineHeight: 1.25 }
+  section-title: { size: "~17.6px (--heading-h2)", weight: 500, lineHeight: 1.25 }
+  card-title: { size: "14px (--card-title-font-size)", weight: 500, lineHeight: 1.25 }
+  body: { size: 14px, weight: 400, lineHeight: 1.7 } # --line-height-body
+  caption: { size: "~12.5px (--font-size-xs)", weight: 400, lineHeight: 1.5 }
+  weights: [400, 500, 700] # --font-weight-semibold is 500; there is no 600
+  numerals: tabular # Text tabular / Badge tabular on every number column
+
+rounded:
+  base: 6px # --radius (rides --scaling)
+  steps: "--radius-sm/md/lg/xl = radius / φ², / φ, ×1, × φ"
+  card: "~9.7px (--card-radius = radius × φ)"
+  pill: 9999px # --radius-pill: switch, radio, pill badge only
+
+spacing:
+  scale: "--space-1..24 = 4px steps (4, 8, 12, 16, 20, 24, 32, 40, 48, 80, 96)"
+  stack: { xs: 4px, sm: 8px, md: 16px, lg: 24px, xl: 40px } # Flex direction="col" gap
+  inline: { xs: 4px, sm: 8px, md: 12px, lg: 16px, xl: 24px } # Flex direction="row" gap
+  page: { x: 24px, y: 24px } # --space-page-x / -y
+  section: 16px # --space-section
+
+density:
+  axis: "AppProvider density / PageContainer density / data-density"
+  compact: "--scaling 0.92 (data-heavy tables)"
+  default: "--scaling 1 (control and row height 32px, --band-height-md)"
+  comfortable: "--scaling 1.08 (login, public, touch)"
+  touch-floor: 44px # --band-height-xl
+
+components:
+  button-primary:
+    {
+      background: "{colors.primary}",
+      text: "{colors.on-primary}",
+      height: "--control-height",
+      radius: "{rounded.base}",
+    }
+  button-secondary: { variant: outline, edge: "{colors.control-edge}" }
+  input:
+    {
+      background: "{colors.canvas}",
+      edge: "{colors.control-edge}",
+      focus: "edge recolours to {colors.ring}",
+    }
+  card:
+    {
+      background: "{colors.canvas}",
+      border: "1px {colors.hairline}",
+      shadow: "--shadow-sm",
+      radius: "{rounded.card}",
+      padding: "--card-space-inset",
+    }
+  table:
+    { rule: "1px {colors.hairline}", rowHeight: "--table-row-height", header: "{colors.ink-muted}" }
+  badge: { variant: outline, tone: "status role only" }
+---
+
+## Overview
+
+A calm, dense tool for people who use it all day. The look is restrained Japanese enterprise: 渋み (low chroma), 間 (even breathing room), 簡素 (nothing that does not carry information). Distinctiveness comes from exact spacing, alignment and type, never from decoration.
+
+The default `--primary` is a neutral ink (`240 6% 10%`). It is a placeholder, not a brand. Set the brand once with `--primary` in your theme, `tenantTheme('#RRGGBB')` from `@godxjp/ui/app`, a `data-brand` preset (`brand`, `crm`, `logistics`, `partner`, `slate`) or `@godxjp/ui/themes/godx.css`. `--ring` follows `--primary`.
+
+## Colors
+
+Colour is scarce. Most of the screen is canvas, ink and hairline.
+
+- **Accent (`--primary`)**: the one primary action per view, focus ring, links, the selected nav item. Nothing else: no tinted headers, avatars, icons or section backgrounds.
+- **Status (若竹 success, 山吹 warning, 群青 info, 朱 attention, 茜 destructive)**: only to state a status. Use `Badge status=…` (maps lifecycle keys to a fixed tone and icon) or `tone`. For status as text use the `--text-*` roles. Status colours are never re-themed per tenant.
+- 朱 attention for urgency that is not destructive (late, overdue); 茜 only for loss (delete, failed, irreversible).
+- `--accent` is the hover/selected surface, not a brand colour. `--muted` is for quiet fills.
+- No gradients, glows or tinted page sections on app surfaces.
+
+## 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.
+- 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 (「承認しました」).
+
+## Layout & Density
+
+- Hierarchy is spacing first: related items `gap="xs"`/`"sm"`, groups `"md"`, sections `"lg"`/`"xl"`. If every gap is the same, nothing is grouped.
+- A section is a `Heading` plus spacing. Add a `Separator` when two sections must not read as one. Use a surface only when it is a real boundary (see Components).
+- Pick one density per page up front: `compact` for review grids, `default` everywhere else, `comfortable` for login and touch.
+- Content measure: forms and settings in `PageContainer measure="narrow"` or `"medium"`; tables use the full width.
+- Spacing comes from component props (`gap`, `pad`) and tokens, never `p-4`/`mt-6` literals.
+
+## Elevation
+
+- Flat. A card is canvas with a 1px `--border` hairline and a near-invisible `--shadow-sm`; nothing heavier at rest.
+- `--shadow-md`/`--shadow-lg` belong to things that float: popover, dropdown, dialog, sheet, toast.
+- No hover lift on data cards. Depth never signals importance.
+
+## Components
+
+- **PageContainer** is the page shell: `title`, optional `subtitle`, `breadcrumb`, `extra` (page actions, primary last), `toolbar`, `footer`.
+- **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`.
+- **Descriptions** for record metadata. **ListRow** for setting rows (`trailing` holds the control).
+- **Form + FormField** for every input; actions at the end of the form or in a sticky `PageContainer footer`. Create/edit is a page, not a dialog.
+- **StatCard** only on a dashboard, always with `delta` that compares (vs last week, vs target). **EmptyState**: one sentence and at most one action.
+- **Alert** only for something the user must act on now. **Badge** only for status; one per row at most.
+
+## Admin Screen Anatomy
+
+### List
+
+Header: title, then `extra` with the primary create action last. Below it a `Toolbar` with search and filters. Then one Card holding the `DataTable` (`CardContent flush`) and `Pagination`. No KPI row, no subtitle that restates the title, no filter Card separate from the table.
+
+### Detail
+
+Header: record name as title, status `Badge` beside it, actions in `extra` (one primary). Body: `Descriptions` for metadata, then sections (Heading + content) for related records and history (`Timeline`). Use `Tabs` only when sections are independent and long. No Card per section; no icon beside every heading.
+
+### Form
+
+`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.
+
+### 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`.
+
+### Dashboard
+
+The only archetype with KPI tiles: at most four `StatCard`s, each with a comparison `delta` (use `inverse` when up is bad). Below, panels in `ResponsiveGrid`, each a Card with a title and one "view all" link: a work queue, a short table, a chart. Every number answers "compared to what".
+
+### Approval queue
+
+A list whose rows are decisions. Show requester, target, reason, submitted time; approve and reject reachable from the row (kebab or row buttons); with `DataTable`, also in `BulkActions`. Escalated or overdue rows get one status Badge, not a coloured row.
+
+## Do's and Don'ts
+
+### Do
+
+- Lead with the data. The first thing below the header is the table, form or record.
+- Use one `Button` default variant per view; the rest `outline` or `ghost`.
+- Group by spacing, then by heading, then by Separator, and only then by Card.
+- Write the subtitle only when it adds a fact the title does not (date, scope, count).
+- Right-align numbers, `tabular` digits, ISO/`Intl` dates.
+
+### Don't
+
+- A subtitle that restates or translates the title.
+- A StatCard row above a list or form.
+- A Card around every section, each with Header + Title + Description.
+- An EmptyState with a large icon inside a Card; an icon in every card header.
+- Alert banners as page decoration; several Alerts stacked.
+- Badge walls: a badge per cell, rainbow tones, badges for non-status labels.
+- Uniform `gap` everywhere; arbitrary px spacing.
+- Coloured avatars, tinted section backgrounds, gradients, hover lift.
+
+## Responsive
+
+- Check 390, 768 and 1280 wide. Nothing scrolls horizontally except a wide table inside its own container.
+- `DataTable` hides `hiddenOnMobile` columns and can stack rows (`collapseBelow`); `Table preset="action-collection"` keeps the actions column visible at 390.
+- `ResponsiveGrid` columns follow its container. `AppShell` turns the sidebar into a drawer on narrow screens.
+- Header `extra` wraps under the title; a toolbar wraps its filters. Touch targets 44px at `comfortable`.
+
+## Iteration Guide
+
+1. Pick the archetype, call `get_exemplar` and build from that screen, not from memory.
+2. Run `node node_modules/@godxjp/ui/scripts/ui-audit.mjs` until it is clean.
+3. Screenshot at 390, 768 and 1280 next to the exemplar's live preview.
+4. List the differences, fix the top 3 (structure before styling). Stop after 3 rounds.
+
+## Known Gaps
+
+- 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.
+- 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.

package/README.md

@@ -51,6 +51,7 @@ 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/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** |

package/agent/DESIGN.md

@@ -0,0 +1,201 @@
+---
+version: alpha
+name: godxjp-ui
+description: "Restrained Japanese-enterprise admin UI. Warm off-white canvas, near-black ink, one neutral accent, hairline borders, 14px/1.7 type, dense tables. Hierarchy comes from spacing steps and type, not from boxes, colour or shadow."
+
+colors:
+  canvas: "#fdfdfc" # --background (= --card, --popover)
+  ink: "#24231e" # --foreground
+  ink-muted: "#68665e" # --muted-foreground
+  ink-tertiary: "#928f87" # --text-tertiary (captions, meta)
+  primary: "#18181b" # --primary. Neutral placeholder: set your brand here
+  on-primary: "#fdfdfc" # --primary-foreground
+  ring: "{colors.primary}" # --ring follows --primary; no separate focus hue
+  muted: "#f4f3f0" # --muted / --secondary (quiet fills, zebra, hover)
+  accent: "#ebe9e5" # --accent (hover/selected background, NOT a brand colour)
+  hairline: "#eeedec" # --border (dividers, card edges, table rules)
+  control-edge: "#90877f" # --input (the edge of an input; 3:1 against canvas)
+  success: "#68be8d" # --success  若竹
+  warning: "#f8b500" # --warning  山吹
+  info: "#4c6cb3" # --info     群青
+  attention: "#eb6101" # --attention 朱 (non-destructive urgency: late, overdue)
+  destructive: "#b7282e" # --destructive 茜 (delete, failed, irreversible)
+  text-success: "#09673b" # --text-success (status as text, AA on canvas)
+  text-warning: "#8f5600" # --text-warning
+  text-info: "#1d48a5" # --text-info
+  text-error: "#aa181f" # --text-error
+
+typography:
+  family: "system stack (--font-sans-base); Noto Sans JP via opt-in @godxjp/ui/styles/fonts"
+  base: 14px # --font-size-base; every step derives from it (ratio --font-size-ratio 1.1227)
+  page-title: { size: "~20px (--heading-h1)", weight: 500, lineHeight: 1.25 }
+  section-title: { size: "~17.6px (--heading-h2)", weight: 500, lineHeight: 1.25 }
+  card-title: { size: "14px (--card-title-font-size)", weight: 500, lineHeight: 1.25 }
+  body: { size: 14px, weight: 400, lineHeight: 1.7 } # --line-height-body
+  caption: { size: "~12.5px (--font-size-xs)", weight: 400, lineHeight: 1.5 }
+  weights: [400, 500, 700] # --font-weight-semibold is 500; there is no 600
+  numerals: tabular # Text tabular / Badge tabular on every number column
+
+rounded:
+  base: 6px # --radius (rides --scaling)
+  steps: "--radius-sm/md/lg/xl = radius / φ², / φ, ×1, × φ"
+  card: "~9.7px (--card-radius = radius × φ)"
+  pill: 9999px # --radius-pill: switch, radio, pill badge only
+
+spacing:
+  scale: "--space-1..24 = 4px steps (4, 8, 12, 16, 20, 24, 32, 40, 48, 80, 96)"
+  stack: { xs: 4px, sm: 8px, md: 16px, lg: 24px, xl: 40px } # Flex direction="col" gap
+  inline: { xs: 4px, sm: 8px, md: 12px, lg: 16px, xl: 24px } # Flex direction="row" gap
+  page: { x: 24px, y: 24px } # --space-page-x / -y
+  section: 16px # --space-section
+
+density:
+  axis: "AppProvider density / PageContainer density / data-density"
+  compact: "--scaling 0.92 (data-heavy tables)"
+  default: "--scaling 1 (control and row height 32px, --band-height-md)"
+  comfortable: "--scaling 1.08 (login, public, touch)"
+  touch-floor: 44px # --band-height-xl
+
+components:
+  button-primary:
+    {
+      background: "{colors.primary}",
+      text: "{colors.on-primary}",
+      height: "--control-height",
+      radius: "{rounded.base}",
+    }
+  button-secondary: { variant: outline, edge: "{colors.control-edge}" }
+  input:
+    {
+      background: "{colors.canvas}",
+      edge: "{colors.control-edge}",
+      focus: "edge recolours to {colors.ring}",
+    }
+  card:
+    {
+      background: "{colors.canvas}",
+      border: "1px {colors.hairline}",
+      shadow: "--shadow-sm",
+      radius: "{rounded.card}",
+      padding: "--card-space-inset",
+    }
+  table:
+    { rule: "1px {colors.hairline}", rowHeight: "--table-row-height", header: "{colors.ink-muted}" }
+  badge: { variant: outline, tone: "status role only" }
+---
+
+## Overview
+
+A calm, dense tool for people who use it all day. The look is restrained Japanese enterprise: 渋み (low chroma), 間 (even breathing room), 簡素 (nothing that does not carry information). Distinctiveness comes from exact spacing, alignment and type, never from decoration.
+
+The default `--primary` is a neutral ink (`240 6% 10%`). It is a placeholder, not a brand. Set the brand once with `--primary` in your theme, `tenantTheme('#RRGGBB')` from `@godxjp/ui/app`, a `data-brand` preset (`brand`, `crm`, `logistics`, `partner`, `slate`) or `@godxjp/ui/themes/godx.css`. `--ring` follows `--primary`.
+
+## Colors
+
+Colour is scarce. Most of the screen is canvas, ink and hairline.
+
+- **Accent (`--primary`)**: the one primary action per view, focus ring, links, the selected nav item. Nothing else: no tinted headers, avatars, icons or section backgrounds.
+- **Status (若竹 success, 山吹 warning, 群青 info, 朱 attention, 茜 destructive)**: only to state a status. Use `Badge status=…` (maps lifecycle keys to a fixed tone and icon) or `tone`. For status as text use the `--text-*` roles. Status colours are never re-themed per tenant.
+- 朱 attention for urgency that is not destructive (late, overdue); 茜 only for loss (delete, failed, irreversible).
+- `--accent` is the hover/selected surface, not a brand colour. `--muted` is for quiet fills.
+- No gradients, glows or tinted page sections on app surfaces.
+
+## 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.
+- 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 (「承認しました」).
+
+## Layout & Density
+
+- Hierarchy is spacing first: related items `gap="xs"`/`"sm"`, groups `"md"`, sections `"lg"`/`"xl"`. If every gap is the same, nothing is grouped.
+- A section is a `Heading` plus spacing. Add a `Separator` when two sections must not read as one. Use a surface only when it is a real boundary (see Components).
+- Pick one density per page up front: `compact` for review grids, `default` everywhere else, `comfortable` for login and touch.
+- Content measure: forms and settings in `PageContainer measure="narrow"` or `"medium"`; tables use the full width.
+- Spacing comes from component props (`gap`, `pad`) and tokens, never `p-4`/`mt-6` literals.
+
+## Elevation
+
+- Flat. A card is canvas with a 1px `--border` hairline and a near-invisible `--shadow-sm`; nothing heavier at rest.
+- `--shadow-md`/`--shadow-lg` belong to things that float: popover, dropdown, dialog, sheet, toast.
+- No hover lift on data cards. Depth never signals importance.
+
+## Components
+
+- **PageContainer** is the page shell: `title`, optional `subtitle`, `breadcrumb`, `extra` (page actions, primary last), `toolbar`, `footer`.
+- **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`.
+- **Descriptions** for record metadata. **ListRow** for setting rows (`trailing` holds the control).
+- **Form + FormField** for every input; actions at the end of the form or in a sticky `PageContainer footer`. Create/edit is a page, not a dialog.
+- **StatCard** only on a dashboard, always with `delta` that compares (vs last week, vs target). **EmptyState**: one sentence and at most one action.
+- **Alert** only for something the user must act on now. **Badge** only for status; one per row at most.
+
+## Admin Screen Anatomy
+
+### List
+
+Header: title, then `extra` with the primary create action last. Below it a `Toolbar` with search and filters. Then one Card holding the `DataTable` (`CardContent flush`) and `Pagination`. No KPI row, no subtitle that restates the title, no filter Card separate from the table.
+
+### Detail
+
+Header: record name as title, status `Badge` beside it, actions in `extra` (one primary). Body: `Descriptions` for metadata, then sections (Heading + content) for related records and history (`Timeline`). Use `Tabs` only when sections are independent and long. No Card per section; no icon beside every heading.
+
+### Form
+
+`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.
+
+### 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`.
+
+### Dashboard
+
+The only archetype with KPI tiles: at most four `StatCard`s, each with a comparison `delta` (use `inverse` when up is bad). Below, panels in `ResponsiveGrid`, each a Card with a title and one "view all" link: a work queue, a short table, a chart. Every number answers "compared to what".
+
+### Approval queue
+
+A list whose rows are decisions. Show requester, target, reason, submitted time; approve and reject reachable from the row (kebab or row buttons); with `DataTable`, also in `BulkActions`. Escalated or overdue rows get one status Badge, not a coloured row.
+
+## Do's and Don'ts
+
+### Do
+
+- Lead with the data. The first thing below the header is the table, form or record.
+- Use one `Button` default variant per view; the rest `outline` or `ghost`.
+- Group by spacing, then by heading, then by Separator, and only then by Card.
+- Write the subtitle only when it adds a fact the title does not (date, scope, count).
+- Right-align numbers, `tabular` digits, ISO/`Intl` dates.
+
+### Don't
+
+- A subtitle that restates or translates the title.
+- A StatCard row above a list or form.
+- A Card around every section, each with Header + Title + Description.
+- An EmptyState with a large icon inside a Card; an icon in every card header.
+- Alert banners as page decoration; several Alerts stacked.
+- Badge walls: a badge per cell, rainbow tones, badges for non-status labels.
+- Uniform `gap` everywhere; arbitrary px spacing.
+- Coloured avatars, tinted section backgrounds, gradients, hover lift.
+
+## Responsive
+
+- Check 390, 768 and 1280 wide. Nothing scrolls horizontally except a wide table inside its own container.
+- `DataTable` hides `hiddenOnMobile` columns and can stack rows (`collapseBelow`); `Table preset="action-collection"` keeps the actions column visible at 390.
+- `ResponsiveGrid` columns follow its container. `AppShell` turns the sidebar into a drawer on narrow screens.
+- Header `extra` wraps under the title; a toolbar wraps its filters. Touch targets 44px at `comfortable`.
+
+## Iteration Guide
+
+1. Pick the archetype, call `get_exemplar` and build from that screen, not from memory.
+2. Run `node node_modules/@godxjp/ui/scripts/ui-audit.mjs` until it is clean.
+3. Screenshot at 390, 768 and 1280 next to the exemplar's live preview.
+4. List the differences, fix the top 3 (structure before styling). Stop after 3 rounds.
+
+## Known Gaps
+
+- 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.
+- 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.

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.5.0.** If the project you are editing has a different
+**This catalog describes `@godxjp/ui` 32.6.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.
@@ -38,10 +38,13 @@ disk, and costs far fewer tokens than fetching a 1 MB JSON.
 { "mcpServers": { "godx-ui": { "command": "npx", "args": ["@godxjp/ui-mcp@<installed version>"] } } }
 ```
 
-Then ask it: `search_components`, `get_component`, `get_tokens`, `get_rule`, `list_anti_ai_tells`.
+Then, before any JSX: `get_design` (the visual target), `route_consumer_task`, `get_exemplar` for
+the closest screen, `search_components` → `get_component`. After building, screenshot at
+390 / 768 / 1280 beside the exemplar and fix the top 3 differences, at most 3 rounds.
 
 **You cannot run a process** (ChatGPT web · Claude.ai · anything fetching URLs)
-→ These files are for you. Fetch in this order:
+→ These files are for you. Read `DESIGN.md` (in this folder) first: tokens, scarcity rules and
+screen anatomy, the visual target the rules below do not give you. Then fetch in this order:
 
 0. `patterns-index.json` — 24 whole-task patterns as name + tagline + tags. **If your
    task is a task** — "build a settings page", "confirm a destructive delete", "a list page with
@@ -61,7 +64,7 @@ Then ask it: `search_components`, `get_component`, `get_tokens`, `get_rule`, `li
    `--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
    right everywhere except one component.
-5. `anti-ai-tells.json` — 26 shapes that make generated UI look generated, each with the
+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.
 
 **Do not fetch `components.json`.** It is 1.2 MB, and most URL fetchers truncate a
@@ -143,7 +146,7 @@ has stopped following the brand.
 
 | `tier` | count | what it is | set it? |
 |---|---|---|---|
-| `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.** Handed a brand colour, this is where it goes: `:root { --primary: <H> <S>% <L>%; }` (HSL components, no `hsl()` wrapper) |
+| `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` |
 
@@ -160,35 +163,27 @@ theme, every tenant scope and every audit in this package.
 
 ```tsx
 import { PageContainer, Flex } from "@godxjp/ui/layout";
-import { Card, CardHeader, CardTitle, CardDescription, CardContent, DataTable } from "@godxjp/ui/data-display";
+import { Card, CardContent, DataTable } from "@godxjp/ui/data-display";
 import { Button } from "@godxjp/ui/general";
-import { Select } from "@godxjp/ui/data-entry";
-import { Alert, AlertTitle, AlertDescription } from "@godxjp/ui/feedback";
+import { Select, SearchInput } from "@godxjp/ui/data-entry";
 
 export default function InvoicesPage() {
   return (
-    <PageContainer title="請求一覧" subtitle="今月の未収を上から">
-      <Flex direction="col" gap="lg">
-        <Alert tone="warning">
-          <AlertTitle>お支払いが確認できていません</AlertTitle>
-          <AlertDescription>3 件の請求が期限を過ぎています。</AlertDescription>
-        </Alert>
+    <PageContainer title="請求一覧" extra={<Button>請求を作成</Button>}>
+      <Flex direction="col" gap="sm">
+        {/* filters sit ABOVE the table they filter */}
+        <Flex direction="row" gap="sm" wrap>
+          <SearchInput aria-label="請求を検索" />
+          <Select width="auto" options={statuses} defaultValue="unpaid" aria-label="状態" />
+          <Button variant="outline">CSV</Button>
+        </Flex>
 
+        {/* `flush` because DataTable draws its own edges — a padded body double-insets it */}
         <Card>
-          <CardHeader>
-            <CardTitle level={2}>未収</CardTitle>
-            <CardDescription>期限順。金額は税込。</CardDescription>
-          </CardHeader>
-          {/* `flush` because DataTable draws its own edges — a padded body double-insets it */}
           <CardContent flush>
-            <DataTable data={rows} columns={columns} getRowId={(r) => r.id} striped />
+            <DataTable data={rows} columns={columns} getRowId={(r) => r.id} />
           </CardContent>
         </Card>
-
-        <Flex direction="row" gap="sm" wrap>
-          <Select width="auto" options={statuses} defaultValue="unpaid" aria-label="状態" />
-          <Button variant="outline" size="sm">CSV</Button>
-        </Flex>
       </Flex>
     </PageContainer>
   );
@@ -196,7 +191,8 @@ export default function InvoicesPage() {
 ```
 
 Note what is absent: no colour, no pixel, no raw control, no `<div className="flex gap-4">` where
-`Flex` exists.
+`Flex` exists — and no subtitle restating the title, no KPI row above the list, no banner, no Card
+header repeating the page title. The page answers one question: which invoice next.
 
 **Take the import path from the catalog, not from the group.** Every entry in
 `components/<Name>.json` carries an `importPath`; it is the only one guaranteed to resolve. The

package/agent/anti-ai-tells.json

@@ -128,7 +128,7 @@
   {
     "body": "Empty state with a chrome / pastel 3D icon (coin, key, shield)\nfloating in the center. Looks like every NFT marketplace from\n2021.",
     "category": "imagery",
-    "fix": "Simple lucide-react line icon (`<Inbox size={48} />`) +\ndescriptive title. Or a flat illustration matching the brand\npalette. Skip the 3D entirely unless your brand IS 3D.",
+    "fix": "No illustration. In an admin screen an EmptyState is one\nsentence and one action (`<EmptyState title action />`, no `icon`).\nA first-run page outside a Card may take one small line icon via\n`icon={Inbox}`; never a large glyph or a 3D render.",
     "name": "Floating 3D crypto icon"
   },
   {
@@ -137,6 +137,60 @@
     "fix": "Solid background (`--background`). If you need depth, use a\nsubtle 1px border + `--card` background tint. Reserve high-effort\nbackgrounds for pages where they matter (marketing hero, product\nshowcase) — not every internal screen.",
     "name": "Decorative gradient mesh background"
   },
+  {
+    "body": "Every section of a page wrapped in Card + CardHeader + CardTitle\n+ CardDescription. Boxes everywhere, so no box means anything.",
+    "category": "structure",
+    "fix": "Mark a section with `<Heading level={2}>` and section spacing\n(PageContainer children). Card only for a real boundary: a table\nsurface, a selectable item. ui-audit: card-per-section.",
+    "name": "Card per section"
+  },
+  {
+    "body": "A Card (or StatCard) inside a Card: two borders for one boundary.",
+    "category": "structure",
+    "fix": "One Card; group inside it with Heading + Flex or Separator.\nui-audit: nested-card.",
+    "name": "Nested Card"
+  },
+  {
+    "body": "PageContainer title=\"クーポン管理\" subtitle=\"クーポンの一覧です\".\nThe subtitle repeats the title in more words.",
+    "category": "copy",
+    "fix": "Omit subtitle. Use it only for a fact the title lacks (scope,\nowner, last sync time).",
+    "name": "Subtitle restating the title"
+  },
+  {
+    "body": "3–4 StatCards above a list or detail page: 件数, 公開中, 合計.\nA row count is not a KPI.",
+    "category": "structure",
+    "fix": "Drop the row; the total is `<Pagination showTotal>`, a record's\nfigures are Descriptions rows. StatCard rows belong on a dashboard\nwith comparison or trend (delta). ui-audit: kpi-row-off-dashboard.",
+    "name": "KPI tile row on a non-dashboard page"
+  },
+  {
+    "body": "A large icon + title + description centred inside a Card or\ntable surface.",
+    "category": "structure",
+    "fix": "One sentence + one action: `<EmptyState title action />`, no\n`icon` (or variant=\"compact\"). ui-audit: empty-state-icon-in-card.",
+    "name": "Icon EmptyState inside a Card"
+  },
+  {
+    "body": "An info Alert at the top of each page explaining the page, or\nseveral Alerts repeating the same notice.",
+    "category": "structure",
+    "fix": "Alert only for a state that blocks or changes the task. Field\nerrors in FormField, results in a toast, standing info in plain\ntext. ui-audit: alert-per-page.",
+    "name": "Alert banner on every page"
+  },
+  {
+    "body": "A Badge in every table column, tiers and categories in\ndifferent colours. Colour stops meaning status.",
+    "category": "visual",
+    "fix": "Badge for status only, one status column per table. Tiers,\ncategories and scopes are plain text (or one neutral tone).\nui-audit: badge-wall.",
+    "name": "Badge wall"
+  },
+  {
+    "body": "The same gap everywhere: between sections, between a heading\nand its content, between fields. No hierarchy.",
+    "category": "layout",
+    "fix": "Two steps: section step (PageContainer children / gap=\"lg\")\nand item step (gap=\"sm\" inside a section).",
+    "name": "Uniform spacing"
+  },
+  {
+    "body": "A Lucide icon before each CardTitle, section heading and button\nlabel. Decoration that adds no meaning.",
+    "category": "visual",
+    "fix": "Text alone. An icon only where it is the affordance (icon-only\nbutton with aria-label) or carries status.",
+    "name": "Icon in every heading and button"
+  },
   {
     "body": "Settings page with 40 form fields in a single scroll. User\nloses their place, can't find the field they came for.",
     "category": "structure",
@@ -146,7 +200,7 @@
   {
     "body": "Click a Button → Dialog opens → click \"Edit\" → another Dialog\nopens → click \"Confirm\" → AlertDialog opens. Triple stack;\nuser loses context.",
     "category": "structure",
-    "fix": "Use Sheet for the FIRST level (side panel), Dialog for the\nconfirm. Or, redesign the flow so the edit is INLINE in the\nfirst Dialog (no second Dialog needed). AlertDialog for confirm\nis correct — but ONE deep, not three.",
+    "fix": "Use Sheet for the FIRST level (side panel), Dialog for the\nconfirm. Or, redesign the flow so the edit is INLINE in the\nfirst Dialog (no second Dialog needed). A destructive confirm\n(AlertDialog preset, or Dialog variant=\"destructive\") is correct —\nbut ONE deep, not three.",
     "name": "Modal-in-modal-in-modal"
   },
   {

package/agent/index.json

@@ -1,13 +1,19 @@
 {
   "counts": {
-    "anti-ai-tells": 26,
+    "anti-ai-tells": 35,
     "components": 161,
     "patterns": 24,
     "rules": 43,
     "tokens": 2195,
     "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.",
+      "url": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/DESIGN.md"
+    },
     {
       "file": "components-index.json",
       "note": "47 KB — name + group + tagline for all 161. FETCH THIS FIRST, then fetch only the components you chose.",
@@ -48,7 +54,7 @@
   "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.5.0/agent/index.json"
+    "pinned": "https://raw.githubusercontent.com/godx-jp/godxjp-ui/v32.6.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",
@@ -62,5 +68,5 @@
     "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.5.0"
+  "version": "32.6.0"
 }