@godxjp/ui 32.5.0 → 32.6.0

package/docs/CONSUMER-RULES.md

@@ -1,9 +1,10 @@
-# @godxjp/ui — the ten consumer rules
+# @godxjp/ui — the consumer rules
 
-Read this once; the audit enforces it. Everything else in `docs/` is for contributors.
+Read this once; the audit enforces it. What the audit cannot see (how a screen is composed, what it
+should look like) is in the package's `DESIGN.md`. Everything else in `docs/` is for contributors.
 
 1. Load styles with `import "@godxjp/ui/styles.css"` (precompiled, no Tailwind needed) or `@import "@godxjp/ui/styles"` (Tailwind v4). Neither ships font files: fonts are opt-in since v32 (`pnpm add @fontsource/noto-sans-jp @fontsource/m-plus-2`, then `@import "@godxjp/ui/styles/fonts.css"` after the styles import; the GoDX preset does this for you). Never cherry-pick `*-layout.css`.
-2. **Mount `<AppProvider defaultLocale="…">` once, at the root.** Without it the kit's OWN strings (dialog close/cancel/delete, counters, picker labels) fall to the resting locale `vi` and pickers to UTC — measured in a Japanese app as Vietnamese buttons, silently (gh#1005). A development build now warns once when a kit component renders outside it; `syncI18nLocale(locale, fallback)` is the escape for an app that truly cannot mount the provider. Every page is `<PageContainer title subtitle extra footer>`; its sections are spaced by the page. Group items inside a section with `<Flex direction="col" gap>` or `<ResponsiveGrid>`.
+2. **Mount `<AppProvider defaultLocale="…">` once, at the root.** Without it the kit's OWN strings (dialog close/cancel/delete, counters, picker labels) fall to the resting locale `vi` and pickers to UTC — measured in a Japanese app as Vietnamese buttons, silently (gh#1005). A development build now warns once when a kit component renders outside it; `syncI18nLocale(locale, fallback)` is the escape for an app that truly cannot mount the provider. Every page is `<PageContainer title extra footer>` (a `subtitle` only when it adds a fact the title does not); its sections are spaced by the page. Group items inside a section with `<Flex direction="col" gap>` or `<ResponsiveGrid>`.
 3. No Tailwind layout on your own elements: no `flex`, `grid`, `gap-*`, `p-*`, `m-*`, `space-*`. Rows are `<Flex>` (default row), stacks are `<Flex direction="col">`, grids are `<ResponsiveGrid>`.
 4. No hand-rolled surfaces: no `rounded-* border bg-*` divs. A box is `Card`, a pill is `Badge`, a person is `Avatar`, a row is `ListRow`, a label/value pair is `Descriptions`, an empty area is `EmptyState`, a read-only sample of a colour the USER chose is `Swatch`. A LIST of those rows is `<Flex as="ul" marker="none" direction="col" gap="none">` with `<ListRow as="li">` children — `marker="none"` keeps the `<ul>`, the `<li>` semantics and the gap token while dropping the bullet and the indent. Never a raw `<ul>`/`<ol>` (it carries no gap token), never `<div role="list">` + `<div role="listitem">`, and never a wrapper around each row: the divider is `:not(:last-child)` among siblings, so a row alone in its own wrapper is always the last one and EVERY divider disappears silently. A bulleted prose list is the same `<Flex as="ul">` without `marker`.
 5. Real controls only: `Button`, `Input`, `Select`, `Textarea`, `Checkbox`… never raw `<button>`/`<input>`; a labelled control lives in `<FormField label>`. A Select outside a form takes `width="auto"`. **A disabled control's reason is visible text, never a tooltip** — see below. **Fields live in a `<Form layout="horizontal" labelWidth controlWidth>`** — never a group of `FormField`s without one, never a hand-rolled `<Flex>` row of fields (a row that belongs together is `<SpaceCompact>` or `<Form columns>`); size each control for its content with `controlWidth` (GOV.UK text-input width: a port ~7rem, a short enum ~10rem); three or more fields is a page, not a Dialog. The audit rules are `formfield-needs-form`, `dialog-form-too-big` and `select-width-hint`. **A case the kit cannot express is an issue, not a hand-roll:** open it on godx-jp/godxjp-ui, use the nearest valid composition, and mark it `// TODO(godxjp-ui#<n>)` (gh#998). **One action row, one Button size:** every `Button` under one parent takes the same `size` — a missing size is `default`, and `icon-sm` pairs with `sm`, `icon-xs` with `xs`, `icon` with default. Never `size="sm"` beside a default Button. The audit rules are `mixed-button-size` (static) and `mixed-button-height` (visual-audit, within 0.5px) (gh#1084).

package/docs/README.md

@@ -2,7 +2,7 @@
 
 | Doc                                          | Purpose                                                                                                                                                                                                               |
 | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [CONSUMER-RULES.md](./CONSUMER-RULES.md)     | **Start here if you build an app with @godxjp/ui** — the ten rules the audit enforces (styles entry, layout owners, real primitives, tokens)                                                                          |
+| [CONSUMER-RULES.md](./CONSUMER-RULES.md)     | **Start here if you build an app with @godxjp/ui** — the rules the audit enforces (styles entry, layout owners, real primitives, tokens)                                                                          |
 | [DEVELOPMENT.md](./DEVELOPMENT.md)           | **Contributor guideline** — role/boundary, architecture, how to add/extend, verify                                                                                                                                    |
 | [COMPONENTS.md](./COMPONENTS.md)             | Component catalog by taxonomy group                                                                                                                                                                                   |
 | [PROPS-VOCABULARY.md](./PROPS-VOCABULARY.md) | Atomic prop types (`*Prop` suffix)                                                                                                                                                                                    |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "32.5.0",
-  "godxUiMcp": "32.5.0",
+  "version": "32.6.0",
+  "godxUiMcp": "32.6.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -28,6 +28,7 @@
   "description": "React UI framework built on design tokens: accessible components, a controlled prop vocabulary, and a machine-readable catalog for coding agents.",
   "files": [
     "LICENSE",
+    "DESIGN.md",
     "agent",
     "dist",
     "scripts/ui-audit.mjs",

package/scripts/_agent-setup.mjs

@@ -167,87 +167,60 @@ function resyncVersionStamp(text) {
  * appended repo-specific sections keeps them.
  */
 export const WORKFLOW_MD = `${STAMP(KIT_VERSION)}
-# @godxjp/ui — mandatory workflow (read every session)
-
-You are building UI in an app that uses @godxjp/ui. Follow this EVERY time you create
-or change a component, page, or form — no exceptions.
-
-## The rules the audit enforces (docs/CONSUMER-RULES.md in node_modules/@godxjp/ui)
-- Styles: \`@import "@godxjp/ui/styles"\` or \`@godxjp/ui/styles/core\` (no fonts). Never cherry-pick layers.
-- Layout: sections of a page are spaced by \`PageContainer\`; siblings go in \`<Flex direction="col" gap>\` /
+# @godxjp/ui — workflow (read every session)
+
+Follow this every time you create or change a page, component or form.
+
+## Before JSX
+1. **Design target.** Read \`node_modules/@godxjp/ui/DESIGN.md\` (MCP \`get_design\`): tokens,
+   scarcity rules, screen anatomy, do/don't.
+2. **Route.** \`route_consumer_task "<task>"\` → \`compose-a-screen\` for app screens. The
+   marketing skills (soft, minimalist, brutalist, gpt-tasteskill, imagegen-*) are for landing
+   pages only.
+3. **Exemplar.** \`get_exemplar\` with archetype list | detail | form | settings | dashboard |
+   approval. Match its structure; it is the visual target.
+4. **Discover, then look up.** \`search_components "<area>"\` first, \`get_component <Name>\`
+   second — \`get_component\` cannot find a name you do not already have (a consumer hand-rolled
+   the shipped \`OrgSwitcher\` and \`TopbarItem\` this way). Code already in this repo is not the
+   authority: search even when a neighbouring file seems to answer. Never guess a prop.
+
+## Contract (ui-audit enforces it; full text in node_modules/@godxjp/ui/docs/CONSUMER-RULES.md)
+- Styles: \`@import "@godxjp/ui/styles"\` (or \`import "@godxjp/ui/styles.css"\`); fonts are opt-in
+  via \`@godxjp/ui/styles/fonts.css\`. Never cherry-pick layers.
+- Layout: \`PageContainer\` spaces sections; siblings go in \`<Flex direction="col" gap>\` /
   \`<ResponsiveGrid>\`. No \`flex\` / \`grid\` / \`gap-*\` / \`p-*\` / \`m-*\` on your own elements.
-- Surfaces: \`Card\` / \`Badge\` / \`Avatar\` / \`ListRow\` / \`Descriptions\` / \`EmptyState\` — never a
-  \`rounded border\` div. Text is \`<Text tone size weight truncate>\`, never utility classes.
-
-## Before writing UI
-1. **DISCOVERY BEFORE LOOKUP — in this order, every time.**
-   1. \`search_components "<the area you are about to build>"\` FIRST. This is the only call that
-      answers "what already exists here". Ask it before the first line of JSX, not after.
-   2. \`get_component <Name>\` second, once you know the name.
-   \`get_component\` answers "how do I use X" and is USELESS for finding X — you can only look up a
-   name you already have. Skipping step 1 is how a consumer hand-rolled an organization switcher
-   the package ships (\`OrgSwitcher\`) and built three topbar cells out of Buttons instead of
-   \`TopbarItem\`: both were one \`search_components\` call away, and neither was ever searched for.
-   **Existing code in this repo is NOT the authority.** Reading a neighbouring file and copying it
-   is the most common way this rule gets skipped — measured: of four fresh agents given a vague UI
-   task, all four answered correctly but two never called the MCP at all, saying the answer was
-   already in the code. They were only right because that code had just been fixed; a week earlier
-   the same files hand-rolled a switcher and put Buttons in topbar slots, and both agents would
-   have copied it. Search the catalog even when a local file looks like it already answers you.
-   Also \`list_audit_rules\`, \`list_visual_checks\`. Never guess a prop; never hand-roll what a
-   primitive already does.
-2. **Real primitives only.** No raw \`<input>/<select>/<button>/<textarea>/<table>\`, no
-   styled-div fakes. A labelled control ALWAYS goes in \`<FormField label=…>\` (it owns the
-   label↔control wiring, error/aria, AND the field rhythm). Never pair a bare \`<Label>\`
-   with an \`<Input>\`.
-3. **Tokens, not literals.** Semantic colour tokens (bg-primary, text-muted-foreground),
-   token spacing/size/radius/type — no raw palette (bg-blue-600), no hex, no arbitrary
-   \`[13px]\`. No emoji in product UI. Logical CSS (ms-/me-/ps-/pe-) for RTL.
-
-## After writing UI
-4. **Audit (runs automatically too).** \`node node_modules/@godxjp/ui/scripts/ui-audit.mjs\`
-   — fix every finding. A PostToolUse hook also runs it on each edit and feeds findings back.
-5. **Before a visual review**, run the runtime audit against the running app:
-   \`node node_modules/@godxjp/ui/scripts/visual-audit.mjs <url>\` (axe + contrast + layout).
+- Surfaces: \`Card\` / \`Badge\` / \`Avatar\` / \`ListRow\` / \`Descriptions\` / \`EmptyState\`, never a
+  \`rounded border\` div. Text is \`<Text tone size weight>\`.
+- Real controls only; a labelled control sits in \`<FormField label>\` inside a \`<Form>\`.
+- Semantic tokens only: no hex, palette names, arbitrary \`[13px]\`, emoji. Logical CSS (ms-/me-).
+- Screen composition (what the audit cannot see) is in \`.ai/rules/godxjp-ui.md\`.
+
+## After JSX
+5. \`node node_modules/@godxjp/ui/scripts/ui-audit.mjs <files>\` — zero errors (a PostToolUse hook
+   also runs it on each edit).
+6. Screenshot at 390 / 768 / 1280 next to the exemplar, list the top 3 differences, fix them,
+   repeat — at most 3 rounds.
+7. Before a visual review: \`node node_modules/@godxjp/ui/scripts/visual-audit.mjs <url>\`
+   (axe + contrast + layout).
 `;
 
 /** Delimited block appended to the consumer's CLAUDE.md — loaded into the agent's context
- * every turn (the most reliable "ensure it reads the rules"). Markers keep it idempotent. */
-export const CLAUDE_MD_BLOCK = `<!-- godxjp-ui:start (managed by @godxjp/ui — edit .claude/godxjp-ui-workflow.md instead) -->
+ * every turn, so it carries only the default path and points at the workflow for the rest.
+ * Markers keep it idempotent. */
+export const CLAUDE_MD_BLOCK = `<!-- godxjp-ui:start (managed by @godxjp/ui — rewritten by npx godxjp-ui sync-rules) -->
 ${STAMP(KIT_VERSION)}
-## @godxjp/ui — mandatory UI workflow (do NOT skip)
-
-This app uses @godxjp/ui. EVERY time you build or change UI:
-
-0. **Ten rules** — read \`node_modules/@godxjp/ui/docs/CONSUMER-RULES.md\` once. Styles via
-   \`@godxjp/ui/styles\` or \`styles/core\` (never cherry-pick layers). Page sections are spaced by
-   \`PageContainer\`; siblings go in \`<Flex direction="col" gap>\` / \`<ResponsiveGrid>\`; no
-   \`flex\`/\`grid\`/\`gap-*\`/\`p-*\`/\`m-*\` on your own elements; boxes are \`Card\`/\`Badge\`/
-   \`ListRow\`/\`Descriptions\`, never a \`rounded border\` div; text is \`<Text tone size weight>\`.
-1. **DISCOVERY BEFORE LOOKUP — in this order, every time.**
-   1. \`search_components "<the area you are about to build>"\` FIRST. This is the only call that
-      answers "what already exists here". Ask it before the first line of JSX, not after.
-   2. \`get_component <Name>\` second, once you know the name.
-   \`get_component\` answers "how do I use X" and is USELESS for finding X — you can only look up a
-   name you already have. Skipping step 1 is how a consumer hand-rolled an organization switcher
-   the package ships (\`OrgSwitcher\`) and built three topbar cells out of Buttons instead of
-   \`TopbarItem\`: both were one \`search_components\` call away, and neither was ever searched for.
-   **Existing code in this repo is NOT the authority.** Reading a neighbouring file and copying it
-   is the most common way this rule gets skipped — measured: of four fresh agents given a vague UI
-   task, all four answered correctly but two never called the MCP at all, saying the answer was
-   already in the code. They were only right because that code had just been fixed; a week earlier
-   the same files hand-rolled a switcher and put Buttons in topbar slots, and both agents would
-   have copied it. Search the catalog even when a local file looks like it already answers you.
-   Also \`list_audit_rules\`, \`list_visual_checks\`. Never guess a prop; never hand-roll what a
-   primitive already does.
-2. **Real primitives only.** No raw \`<input>/<select>/<button>/<textarea>/<table>\`. A labelled
-   control ALWAYS goes in \`<FormField label=…>\` — never a bare \`<Label>\`+\`<Input>\`. Semantic
-   tokens, not raw palette/hex/arbitrary values. No emoji in product UI. Logical CSS for RTL.
-3. **Scan after writing.** \`node node_modules/@godxjp/ui/scripts/ui-audit.mjs <files>\` and fix
-   every finding (a PostToolUse hook runs this automatically and feeds findings back). Before a
-   visual review: \`node node_modules/@godxjp/ui/scripts/visual-audit.mjs <url>\` (axe + layout).
-
-Full guide: \`.claude/godxjp-ui-workflow.md\`.
+## @godxjp/ui — UI workflow
+
+Before any JSX for a screen:
+1. Read \`node_modules/@godxjp/ui/DESIGN.md\` (MCP \`get_design\`).
+2. \`route_consumer_task\` → \`compose-a-screen\`; \`search_components\` before hand-rolling anything.
+3. \`get_exemplar\` (list | detail | form | settings | dashboard | approval) — match its structure.
+
+After building:
+4. \`node node_modules/@godxjp/ui/scripts/ui-audit.mjs <files>\` — zero errors.
+5. Screenshot at 390 / 768 / 1280 beside the exemplar; fix the top 3 differences; max 3 rounds.
+
+Rules: \`node_modules/@godxjp/ui/docs/CONSUMER-RULES.md\`. Details: \`.claude/godxjp-ui-workflow.md\`.
 <!-- godxjp-ui:end -->
 `;
 

package/scripts/consumer-rule.md

@@ -1,39 +1,33 @@
 # @godxjp/ui
 
-> **Tệp này do gói `@godxjp/ui` sở hữu.** Cài gói không tự ghi gì cả: nội dung chỉ được ghi lại
-> khi bạn chạy `npx godxjp-ui sync-rules` (thêm `--dry-run` để xem trước). Chạy lại sau mỗi lần
-> nâng cấp. Dấu `<!-- godxjp-ui:version -->` luôn được đồng bộ với phiên bản
-> gói đang cài — kể cả khi thân tệp không đổi giữa hai bản.
-> Đừng sửa ở đây — luật của riêng kho thuộc về một tệp khác trong `.ai/rules/`,
-> và index sẽ nạp cả hai. (Khác với `.claude/skills/.../SKILL.md`, nơi mục §8
-> trở đi là của kho và được giữ lại.)
-
-Đây là **danh sách kiểm** bắn mỗi lần chạm một tệp UI. Lý do đầy đủ nằm ở
-`docs/CONSUMER-RULES.md` (10 luật) và, với kho chuột bạch, ở
-`.claude/skills/godx-ui-guinea-pig/SKILL.md`.
-
-## Loading styles: one entry, fonts are opt-in
-
-```ts
-import "@godxjp/ui/styles.css"; // precompiled, no Tailwind needed
-```
+> **Tệp do gói `@godxjp/ui` sở hữu**, ghi lại mỗi lần chạy `npx godxjp-ui sync-rules`. Đừng sửa ở
+> đây — luật riêng của kho thuộc về một tệp khác trong `.ai/rules/`.
+
+Danh sách kiểm bắn mỗi lần chạm một tệp UI. Luật đầy đủ: `docs/CONSUMER-RULES.md`.
+
+## Styles và theme
 
 ```css
-@import "@godxjp/ui/styles"; /* Tailwind v4: every component layer, NO font files */
-@import "@godxjp/ui/styles/fonts.css"; /* optional, after the styles import: the bundled faces */
+@import "@godxjp/ui/styles"; /* or: import "@godxjp/ui/styles.css" — no Tailwind needed */
 ```
 
-Since v32 the styles entry no longer bundles fonts. A Japanese app that wants the bundled faces
-installs them and adds the fonts import (the GoDX preset does both for you):
+Fonts are opt-in (`@godxjp/ui/styles/fonts.css`, after the styles import). Never cherry-pick
+`*-layout.css` layers. The default `--primary` is a neutral placeholder: set `--primary` once in
+your theme, or import a preset (`@godxjp/ui/themes/godx.css`). Details: `docs/CUSTOMER-THEMING.md`.
 
-```bash
-pnpm add @fontsource/noto-sans-jp @fontsource/m-plus-2
-```
+## Screen composition (ui-audit không thấy những lỗi này)
 
-An app that supplies its own face (next/font, self-host, a system stack) skips the fonts import and
-names its face with `--font-sans-base`. Never cherry-pick individual `*-layout.css` layers: that
-breaks the layer-order contract, which is not the same thing as choosing an entry point. Reasons
-and measurements are in `docs/CUSTOMER-THEMING.md`.
+- Most sections are a `Heading` + content, NOT a `Card`. A Card is for a genuinely separate
+  surface (a table, a form block), never a frame around every section.
+- No `subtitle` that restates the `title`. Leave it out unless it adds a fact.
+- Filters sit ABOVE the table they filter, never after it.
+- KPI tiles (`StatCard`) only on dashboards, 3–4 at most. A list page opens with its list.
+- `EmptyState` = one sentence + one action. Inside a Card it has no icon.
+- `Alert` only for something the user must act on now; not a page decoration.
+- Tiers / categories / roles render in ONE neutral tone (`<Badge variant="outline">`); colour
+  is for status.
+- Vary spacing by level: `xs` inside a group, `sm` within a row, `md` between items, `lg`
+  between blocks. One gap everywhere reads as generated.
 
 ## Bố cục chuẩn của platform: BA CỘT, và ba cột là BA PHẠM VI
 
@@ -85,11 +79,10 @@ ngày: năm thứ cần đều ĐÃ CÓ và vẫn bị dựng lại bằng thứ
 | dải giữa hai vùng, tự kẻ theo VỊ TRÍ                             | `<CardBar>` (`border` để ép khi xếp chồng)                                         |
 | chip "điều kiện đang bật" có dấu × để bỏ                         | `<Badge onRemove>` — KHÔNG phải `TagInput`                                         |
 | dải tab nằm TRONG đầu Card                                       | `<Card tabList activeTabKey onTabChange>`                                          |
-| tiêu đề / đoạn văn / liên kết trong văn bản                      | `<Title>` · `<Paragraph>` · `<Link>` (`Text` 33 prop)                              |
+| tiêu đề / đoạn văn / liên kết trong văn bản                      | `<Heading level>` · `<Text as="p">` · `<Link>`                                     |
 | nút nổi góc màn (quay lên đầu, hành động nhanh)                  | `<FloatButton>`                                                                    |
 | khung xương của một FORM khi đang tải                            | `<SkeletonForm>`                                                                   |
 | ô màu chỉ để xem, màu do NGƯỜI DÙNG chọn                         | `<Swatch>`                                                                         |
-| ảnh đại diện của một tệp / bản xem trước                         | `<Thumbnail>`                                                                      |
 | danh sách "có gì trong gói này"                                  | `<FeatureList>`                                                                    |
 | panel kéo giãn được (chia đôi màn)                               | `<DraggablePanel>`                                                                 |
 | màn hội thoại AI                                                 | `<Welcome>` · `<Conversations>` · `<Attachments>` · `<ThoughtChain>` · `<Actions>` |
@@ -120,48 +113,19 @@ godx-mailer dính bốn lỗi form trong một ngày, cả bốn đều là kit
 Ca kit không diễn đạt được thì **mở issue ở godx-jp/godxjp-ui**, tạm dùng cách
 hợp lệ gần nhất kèm `// TODO(godxjp-ui#<n>)` — không tự chế.
 
-## Dialog và AlertDialog là MỘT họ — `variant` là lối chuẩn
-
-Đừng với tay sang 12 export `AlertDialog*` nữa. Chúng **vẫn chạy y như cũ** (gỡ
-là breaking change) nhưng là **LỐI CŨ**: đo được 26 export với **12 cặp trùng
-tên** và **0** phần chỉ `AlertDialog` mới có. antd — thẩm quyền bề mặt prop của
-gói này — chỉ có MỘT `Modal`, và mức nguy hiểm ở đó là một PROP.
+## Xác nhận nguy hiểm: `Dialog variant="destructive"`
 
 ```tsx
-<DialogContent variant="destructive">   {/* thay cho <AlertDialogContent> */}
+<DialogContent variant="destructive">   {/* không dùng họ AlertDialog* — lối cũ */}
 ```
 
-Một prop ấy quyết định ba thứ đi cùng nhau: `role="alertdialog"`, click ra ngoài
-KHÔNG đóng, nút chính nhấn mạnh destructive (và ✕ mặc định tắt). Esc VẪN đóng —
-y như `AlertDialogContent` trước nay. Đặt `variant` ở `DialogRoot` thì cả cây kế
-thừa.
-
-## antd là CHUẨN — thiếu gì thì port 100%, đừng tự thiết kế
-
-`docs/DESIGN-AUTHORITY.md` của gói: **nơi antd đặt tên cho một năng lực, gói này
-lấy nguyên tên và nguyên ngữ nghĩa của antd.** Một năng lực còn thiếu được port
-từ antd **100% TRƯỚC** — tên, prop, ngữ nghĩa — rồi mới cải tiến. Không thiết kế
-lại trước, không port một nửa.
-
-Nghĩa là với consumer: thấy thiếu prop thì **mở issue kèm tên antd của nó**
-(`sorter`, `closable`, `okType`…), đừng đề xuất một cái tên mới và đừng tự vẽ
-lại bằng class tiện ích. Ba trục cố ý lệch khỏi antd đều đã ghi lý do trong
-DESIGN-AUTHORITY (logical thay cho `left/right`, từ vựng giá trị của gói này,
-`density` thay cho `size`) — lệch thêm thì phải viết ra ở đó.
-
-## Catalog giờ chở CẢ luật bố cục — nhưng phải hỏi mới có
-
-Mục này từng nói "catalog chở PROP, không chở LUẬT BỐ CỤC", với `CardBar` làm
-bằng chứng: một prop (`extra`), không dòng nào nói nó tự kẻ theo vị trí. **Bằng
-chứng ấy đã hết đúng.** `CardBar` nay có 6 prop, trong đó `border` (`"none" |
-"block-start" | "block-end" | "both"`) ép được đường kẻ khi xếp chồng, và cả
-`Card` lẫn `CardBar` trong catalog đều nói ra luật vị trí (đầu: kẻ dưới · cuối:
-kẻ trên · giữa: cả hai).
-
-Nên luật hiện hành là: **hỏi `get_component` trước** — nay nó thường trả lời cả
-hình dạng lẫn luật. Còn khi `usage`/`description` im lặng về bố cục thì mới mở
-`node_modules/@godxjp/ui/src/styles/*-layout.css` của component ấy ra đọc; chú
-thích trong đó vẫn là bản đầy đủ nhất.
+Một prop: `role="alertdialog"`, click ra ngoài không đóng, nút chính nhấn mạnh destructive.
+Thiếu prop thì mở issue kèm tên antd của nó (`docs/DESIGN-AUTHORITY.md`), đừng tự đặt tên.
+
+## Luật bố cục: hỏi `get_component` trước
+
+`usage`/`description` thường nói cả luật vị trí (vd. `CardBar` tự kẻ theo vị trí, `border` để
+ép). Khi catalog im lặng thì mới đọc `node_modules/@godxjp/ui/src/styles/*-layout.css`.
 
 ## Card không lồng Card
 

package/scripts/ui-audit.mjs

@@ -295,6 +295,22 @@ const isAsChildSlot = (content, index) => {
 const rawTagOutsideAsChildSlot = (tag) => (content) =>
   [...content.matchAll(rawTag(tag))].filter((match) => !isAsChildSlot(content, match.index));
 
+/*
+ * ADMIN-SCREEN TELLS (gh#1294). Consumer screens built only from correct primitives still read as
+ * generated, through structure: a Card per section, a Card in a Card, a KPI tile row above a
+ * list, an icon EmptyState inside a Card, a wall of Badges or Alerts. Each is sometimes right, so
+ * these are WARNINGS. The per-file limits were set from four consumer repos (ql, platform,
+ * godx-task, godx-content: 511 files importing @godxjp/ui, 2026-10-14) to flag the densest
+ * ~10–15% of the files that use the tag at all:
+ *   Card   ≥5 → 43 of 336 files (12.8%)
+ *   Badge  ≥5 → 28 of 211 (13.3%)
+ *   Alert  ≥4 → 27 of 200 (13.5%)
+ */
+const CARD_LIMIT = 5;
+const BADGE_LIMIT = 5;
+const ALERT_LIMIT = 4;
+const STATCARD_ROW = 3;
+
 /**
  * @type {{id:string, severity:'error'|'warn', test:RegExp, message:string, standard?:string,
  *         exempt?:RegExp, classOnly?:boolean}[]}
@@ -915,6 +931,64 @@ const RULES = [
     message:
       "Buttons in one row mix sizes — every Button under one parent takes the same `size` (a missing size is `default`; `icon-sm` pairs with `sm`, `icon-xs` with `xs`, `icon` with default). Pick the row's size and apply it to every button in it (docs/CONSUMER-RULES.md §5).",
   },
+  // Admin-screen tells (gh#1294) — structure, not decoration; limits measured, see CARD_LIMIT.
+  {
+    id: "nested-card",
+    replacement: "Heading + Flex inside the one Card",
+    scope: "consumer",
+    severity: "warn",
+    spansElement: true,
+    matches: nestedCardMatches,
+    message:
+      "A Card (or StatCard) inside a Card — two borders for one boundary. Group inside the outer Card with a Heading and Flex/Separator; keep Card for a real surface boundary.",
+  },
+  {
+    id: "card-per-section",
+    replacement: "Heading + Flex direction=col per section",
+    scope: "consumer",
+    severity: "warn",
+    spansElement: true,
+    matches: (source) => densityMatches(source, ["Card"], CARD_LIMIT),
+    message: `${CARD_LIMIT}+ Cards in one file — a Card per section. Mark sections with a Heading and section spacing (PageContainer children, Flex gap="lg"); keep Card for a real boundary (a table surface, a selectable item).`,
+  },
+  {
+    id: "kpi-row-off-dashboard",
+    replacement: "drop the StatCard row; put counts in the table header or Pagination total",
+    scope: "consumer",
+    severity: "warn",
+    spansElement: true,
+    matches: kpiRowMatches,
+    message: `${STATCARD_ROW}+ StatCards outside a dashboard — a row count is not a KPI. Keep StatCard rows for a dashboard with comparison or trend (delta); a list shows its total in Pagination showTotal.`,
+  },
+  {
+    id: "empty-state-icon-in-card",
+    replacement: 'EmptyState title + action, no icon (or variant="compact")',
+    scope: "consumer",
+    severity: "warn",
+    spansElement: true,
+    matches: emptyStateIconInCardMatches,
+    message:
+      'An icon EmptyState inside a Card. In an admin surface an empty state is one sentence and one action: drop `icon`, or use variant="compact".',
+  },
+  {
+    id: "badge-wall",
+    replacement: "plain text for categories; Badge only for status",
+    scope: "consumer",
+    severity: "warn",
+    spansElement: true,
+    matches: (source) => densityMatches(source, ["Badge", "Tag"], BADGE_LIMIT),
+    message: `${BADGE_LIMIT}+ Badge/Tag in one file. Badge is for status; render categories, tiers and scopes as plain text, and keep one status column per table.`,
+  },
+  {
+    id: "alert-per-page",
+    replacement:
+      "one Alert for the page's blocking state; inline FormField errors and toasts for the rest",
+    scope: "consumer",
+    severity: "warn",
+    spansElement: true,
+    matches: (source) => densityMatches(source, ["Alert"], ALERT_LIMIT),
+    message: `${ALERT_LIMIT}+ Alerts in one file. An Alert is for a state that blocks or changes the task; field errors belong in FormField, results in a toast, and standing info in plain text.`,
+  },
 ];
 
 /**
@@ -1554,9 +1628,11 @@ const BUTTON_ROW_TRANSPARENT = new Set([
   "TooltipTrigger",
 ]);
 
-/** A Button's `size` literal from its OPENING tag's own attributes (not a nested element's). */
-function buttonSizeOf(openTag) {
-  // Blank every `{…}` body so `icon={<Plus size="sm" />}` cannot answer for the Button.
+/**
+ * An opening tag with every `{…}` body blanked (the `{` kept), so `icon={<Plus size="sm" />}`
+ * cannot answer for the element that owns the attribute.
+ */
+function topLevelAttrs(openTag) {
   let top = "";
   let depth = 0;
   let quote = "";
@@ -1573,7 +1649,12 @@ function buttonSizeOf(openTag) {
     top += depth ? (ch === "{" && depth === 1 ? "{" : " ") : ch;
     if (ch === "}") depth--;
   }
-  const at = /\bsize\s*=\s*/.exec(top);
+  return top;
+}
+
+/** A Button's `size` literal from its OPENING tag's own attributes (not a nested element's). */
+function buttonSizeOf(openTag) {
+  const at = /\bsize\s*=\s*/.exec(topLevelAttrs(openTag));
   if (!at) return "default";
   const rest = openTag.slice(at.index + at[0].length);
   const lit = /^(?:"([^"]*)"|'([^']*)'|\{\s*(?:"([^"]*)"|'([^']*)'|`([^`$]*)`)\s*\})/.exec(rest);
@@ -1587,15 +1668,14 @@ const buttonSizeFamily = (size) => {
 };
 
 /**
- * `mixed-button-size`: group every <Button> by its nearest non-transparent JSX parent and yield
- * one match per group whose size families differ. A tag stack over the whole file; an element in
- * an attribute (`actions={<>…</>}`) gets the attribute's owner as its parent, kept apart from the
- * owner's children. A `<` glued to an identifier outside JSX children is a TS generic.
+ * Every JSX opening tag in the file, with the stack of elements open around it. A tag stack over
+ * the whole file; an element in an attribute (`actions={<>…</>}`) gets the attribute's owner as an
+ * `attr: true` frame, kept apart from the owner's children. A `<` glued to an identifier outside
+ * JSX children is a TS generic. `stack` is live: read it before asking for the next element.
  */
-function* mixedButtonSizeMatches(source) {
+function* jsxElements(source) {
   const stack = []; // { tag, id, attr }
   const pending = []; // opening tags whose attributes are still being scanned
-  const groups = new Map();
   let nextId = 0;
   const settle = (upTo) => {
     while (pending.length && pending.at(-1).end < upTo) {
@@ -1625,21 +1705,31 @@ function* mixedButtonSizeMatches(source) {
     const end = jsxOpeningEnd(source, m.index);
     if (end >= source.length) continue;
     const openTag = source.slice(m.index, end + 1);
-    if (tag === "Button") {
-      const parent = stack.findLast((f) => f.attr || !BUTTON_ROW_TRANSPARENT.has(f.tag));
-      const size = buttonSizeOf(openTag);
-      if (parent && size !== null) {
-        (groups.get(parent.id) ?? groups.set(parent.id, []).get(parent.id)).push({
-          size,
-          index: m.index,
-          openTag,
-        });
-      }
-    }
+    yield { tag, index: m.index, openTag, stack };
     const frame = { tag, id: nextId++, attr: true };
     stack.push(frame);
     pending.push({ end, frame, selfClose: /\/\s*>$/.test(openTag) });
   }
+}
+
+/**
+ * `mixed-button-size`: group every <Button> by its nearest non-transparent JSX parent and yield
+ * one match per group whose size families differ.
+ */
+function* mixedButtonSizeMatches(source) {
+  const groups = new Map();
+  for (const { tag, index, openTag, stack } of jsxElements(source)) {
+    if (tag !== "Button") continue;
+    const parent = stack.findLast((f) => f.attr || !BUTTON_ROW_TRANSPARENT.has(f.tag));
+    const size = buttonSizeOf(openTag);
+    if (parent && size !== null) {
+      (groups.get(parent.id) ?? groups.set(parent.id, []).get(parent.id)).push({
+        size,
+        index,
+        openTag,
+      });
+    }
+  }
   for (const group of groups.values()) {
     const families = new Set(group.map((b) => buttonSizeFamily(b.size)));
     if (group.length < 2 || families.size < 2) continue;
@@ -1650,6 +1740,46 @@ function* mixedButtonSizeMatches(source) {
   }
 }
 
+/** One finding per file, at the `limit`-th occurrence of any tag in `tags`, naming the count. */
+function* densityMatches(source, tags, limit) {
+  const hits = [];
+  for (const { tag, index } of jsxElements(source)) if (tags.includes(tag)) hits.push(index);
+  if (hits.length >= limit) yield { 0: `${hits.length} in this file`, index: hits[limit - 1] };
+}
+
+/** A Card or StatCard opened while another Card is open, in children or in an attribute. */
+function* nestedCardMatches(source) {
+  for (const { tag, index, openTag, stack } of jsxElements(source)) {
+    if ((tag === "Card" || tag === "StatCard") && stack.some((f) => f.tag === "Card")) {
+      yield { 0: openTag, index };
+    }
+  }
+}
+
+/** ≥3 StatCards in a file whose path does not say it is a dashboard. */
+function* kpiRowMatches(source, rel = "") {
+  if (/dashboard/i.test(rel)) return;
+  yield* densityMatches(source, ["StatCard"], STATCARD_ROW);
+}
+
+/** An EmptyState that draws an icon (not `icon={null}`, not compact) inside a Card. */
+function* emptyStateIconInCardMatches(source) {
+  for (const { tag, index, openTag, stack } of jsxElements(source)) {
+    if (tag !== "EmptyState" || !stack.some((f) => f.tag === "Card" || f.tag === "CardContent")) {
+      continue;
+    }
+    const top = topLevelAttrs(openTag);
+    const icon = /\bicon\s*=\s*/.exec(top);
+    if (!icon || /^\{\s*(?:null|undefined)\s*\}/.test(openTag.slice(icon.index + icon[0].length))) {
+      continue;
+    }
+    const variant = /\bvariant\s*=\s*/.exec(top);
+    const rest = variant ? openTag.slice(variant.index + variant[0].length) : "";
+    if (/^(?:"compact"|'compact'|\{\s*["'`]compact["'`]\s*\})/.test(rest)) continue;
+    yield { 0: openTag, index };
+  }
+}
+
 // Structural: a <Card> (without p-0) whose first child is body content rather than a Card
 // sub-component sits FLUSH (no padding). Per-line regexes can't see across lines, so this is a
 // whole-file pass. The body must be wrapped in <CardContent> (titles in <CardHeader>).
@@ -2065,7 +2195,7 @@ for (const dir of SCAN_DIRS) {
     for (const rule of fileRules) {
       if (!rule.spansElement || !isJsx) continue;
       for (const match of rule.matches
-        ? rule.matches(scanContent)
+        ? rule.matches(scanContent, rel)
         : scanContent.matchAll(rule.test)) {
         // A comparison `>` inside a JSX prop is not the end of its opening tag.
         if (