@godxjp/ui 19.6.0 → 20.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "19.6.0",
-  "godxUiMcp": "19.6.0",
+  "version": "20.0.0",
+  "godxUiMcp": "20.0.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -30,6 +30,9 @@
     "scripts/visual-audit-rules.mjs",
     "scripts/audit-hook.mjs",
     "scripts/init-agent-kit.mjs",
+    "scripts/init-guinea-pig.mjs",
+    "scripts/guinea-pig-skill.md",
+    "scripts/consumer-rule.md",
     "scripts/postinstall.mjs",
     "scripts/_agent-setup.mjs",
     "scripts/cli.mjs",
@@ -308,6 +311,7 @@
     "format": "prettier --check .",
     "format:fix": "prettier --write .",
     "test": "vitest run",
+    "test:manual": "vitest run --config vitest.manual.config.ts",
     "test:visual:auth-login": "node scripts/auth-shell-login-visual.mjs",
     "test:visual:auth-registration": "node scripts/auth-shell-registration-visual.mjs",
     "test:visual:topbar-collision": "node scripts/topbar-collision-visual.mjs",
@@ -335,8 +339,8 @@
     "check:frame-runtime": "pnpm check:data-entry-frame-runtime && pnpm check:data-entry-touch-aria && pnpm check:layout-nav-frames && pnpm check:provider-feedback-query-runtime && pnpm check:layout-nav-closure && pnpm check:final-touch-rtl && pnpm check:data-table-pagination-wrap && pnpm check:button-icon-xs",
     "verify": "pnpm typecheck && pnpm lint && pnpm format && pnpm build && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:no-consumer-coupling && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:no-external-assets && pnpm check:token-scale-bypass && pnpm check:dist-tokens-resolve && pnpm check:no-hardcoded-geometry && pnpm check:no-hardcoded-css-values && pnpm check:no-inline-magic-numbers && pnpm check:no-tailwind-class-assertions && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-lockstep && pnpm check:mcp-sync && pnpm check:doc-prop-existence && pnpm check:mcp-catalog-coverage && pnpm check:mcp-orphans && pnpm check:mcp-pattern-imports && pnpm check:audit-sync && pnpm check:frame-coverage && pnpm test",
     "verify:static": "pnpm build && pnpm check:packed-public-contract && pnpm typecheck && pnpm typecheck:docs && pnpm lint && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:no-consumer-coupling && pnpm check:use-client && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:token-scale-bypass && pnpm check:dist-tokens-resolve && pnpm check:no-hardcoded-geometry && pnpm check:no-hardcoded-css-values && pnpm check:no-inline-magic-numbers && pnpm check:no-tailwind-class-assertions && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-lockstep && pnpm check:mcp-sync && pnpm check:doc-prop-existence && pnpm check:mcp-catalog-coverage && pnpm check:mcp-orphans && pnpm check:mcp-pattern-imports && pnpm check:audit-sync && pnpm check:mcp-prop-sync && pnpm check:contrast && pnpm check:visual-audit && pnpm test",
-    "verify:ci": "pnpm build && pnpm check:packed-public-contract && pnpm typecheck && pnpm typecheck:docs && pnpm lint && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:no-consumer-coupling && pnpm check:use-client && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:token-scale-bypass && pnpm check:dist-tokens-resolve && pnpm check:no-hardcoded-geometry && pnpm check:no-hardcoded-css-values && pnpm check:no-inline-magic-numbers && pnpm check:no-tailwind-class-assertions && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-lockstep && pnpm check:mcp-sync && pnpm check:doc-prop-existence && pnpm check:mcp-catalog-coverage && pnpm check:mcp-orphans && pnpm check:mcp-pattern-imports && pnpm check:audit-sync && pnpm check:mcp-prop-sync && pnpm test",
-    "verify:ci:static": "pnpm build && pnpm check:packed-public-contract && pnpm typecheck && pnpm typecheck:docs && pnpm lint && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:no-consumer-coupling && pnpm check:use-client && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:no-external-assets && pnpm check:token-scale-bypass && pnpm check:dist-tokens-resolve && pnpm check:no-hardcoded-geometry && pnpm check:no-hardcoded-css-values && pnpm check:no-inline-magic-numbers && pnpm check:no-tailwind-class-assertions && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-lockstep && pnpm check:mcp-sync && pnpm check:doc-prop-existence && pnpm check:mcp-catalog-coverage && pnpm check:mcp-orphans && pnpm check:mcp-pattern-imports && pnpm check:audit-sync && pnpm check:mcp-prop-sync",
+    "verify:ci": "pnpm verify:ci:static && pnpm check:frame-contracts && pnpm test",
+    "verify:ci:static": "pnpm build && pnpm check:packed-public-contract && pnpm typecheck && pnpm typecheck:docs && pnpm lint && pnpm preview:build && pnpm check:registry && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:no-consumer-coupling && pnpm check:use-client && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:no-external-assets && pnpm check:token-scale-bypass && pnpm check:no-antd-runtime && pnpm check:dist-tokens-resolve && pnpm check:no-hardcoded-geometry && pnpm check:no-hardcoded-css-values && pnpm check:no-inline-magic-numbers && pnpm check:no-tailwind-class-assertions && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-lockstep && pnpm check:mcp-sync && pnpm check:doc-prop-existence && pnpm check:mcp-catalog-coverage && pnpm check:mcp-orphans && pnpm check:mcp-pattern-imports && pnpm check:audit-sync && pnpm check:gate-coverage && pnpm check:mcp-prop-sync",
     "verify:browser": "pnpm check:contrast && pnpm check:visual-audit",
     "verify:release": "pnpm verify:static && pnpm check:frame-contracts && pnpm check:frame-coverage && pnpm check:frame-axe",
     "verify:publish-tree": "pnpm build && pnpm check:packed-public-contract && pnpm check:use-client && pnpm check:dist-tokens-resolve",
@@ -365,9 +369,6 @@
     "check:rtl": "node scripts/check-rtl.mjs",
     "check:typography": "node scripts/check-typography.mjs",
     "gen:component-tokens": "node scripts/gen-component-tokens.mjs",
-    "gen:antd-tokens": "node scripts/gen-antd-tokens.mjs",
-    "check:antd-tokens": "node scripts/gen-antd-tokens.mjs --check",
-    "report:antd-tokens": "node scripts/gen-antd-tokens.mjs --report",
     "check:no-antd-runtime": "node scripts/check-no-antd-runtime.mjs",
     "gen:email-tokens": "node scripts/gen-email-tokens.mjs",
     "check:core-isolation": "node scripts/check-core-isolation.mjs",
@@ -384,6 +385,7 @@
     "dev": "node scripts/dev.mjs",
     "prepublishOnly": "pnpm run build",
     "check:audit-sync": "node scripts/check-audit-sync.mjs",
+    "check:gate-coverage": "node scripts/check-gate-coverage.mjs",
     "check:contrast": "node scripts/check-contrast.mjs",
     "visual-audit": "node scripts/visual-audit.mjs",
     "check:visual-audit": "node scripts/visual-audit-smoke.mjs",
@@ -451,6 +453,7 @@
     "@radix-ui/react-toggle": "^1.1.18",
     "@radix-ui/react-toggle-group": "^1.1.19",
     "@radix-ui/react-tooltip": "^1.2.16",
+    "@react-aria/utils": "^3.34.1",
     "@tanstack/react-table": "^9.2.4",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -460,6 +463,7 @@
     "input-otp": "^1.5.0",
     "lucide-react": "^1.37.0",
     "qrcode.react": "4.2.0",
+    "react-aria-components": "^1.21.1",
     "react-day-picker": "^10.0.1",
     "react-resizable-panels": "^4.12.3",
     "sonner": "^2.0.8",
@@ -483,7 +487,6 @@
     "@types/react-dom": "^19.2.5",
     "@vitejs/plugin-react": "^6.1.1",
     "@vitest/coverage-v8": "^4.1.11",
-    "antd": "6.6.2",
     "axe-core": "^4.13.0",
     "eslint": "^10.9.1",
     "eslint-plugin-react": "^7.37.5",

package/scripts/_agent-setup.mjs

@@ -4,10 +4,15 @@
  * NON-DESTRUCTIVE: it only creates a missing file or ADDS a missing key, never
  * overwrites existing config.
  */
+import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 /** The godxjp-ui MCP server — pulled on demand via npx (no extra dependency to ship). */
+/** This package's own root — the source of the version we stamp with. */
+const SELF_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
 export const MCP_SERVER = { command: "npx", args: ["@godxjp/ui-mcp"] };
 export const MCP_KEY = "godx-ui";
 
@@ -16,7 +21,47 @@ export const AUDIT_HOOK_CMD = "node node_modules/@godxjp/ui/scripts/audit-hook.m
 export const PRIMER_CMD = "cat .claude/godxjp-ui-workflow.md";
 
 /** The per-session workflow mandate the SessionStart hook injects into the agent. */
-export const WORKFLOW_MD = `# @godxjp/ui — mandatory workflow (read every session)
+export const KIT_VERSION = readJson(join(SELF_ROOT, "package.json"))?.version ?? "0.0.0";
+
+const STAMP = (v) => `<!-- godxjp-ui:version ${v} -->`;
+const STAMP_RE = /<!-- godxjp-ui:version ([^\s]+) -->/;
+
+/** The version stamped in `text`, or null when it predates stamping. */
+export function stampedVersion(text) {
+  return text?.match(STAMP_RE)?.[1] ?? null;
+}
+
+/**
+ * A stamp that tracks the CONTENT, for the files this package owns outright.
+ *
+ * A version stamp answers "which release wrote this", which is the wrong question for a file whose
+ * whole job is to carry current guidance. Measured: editing `consumer-rule.md` without bumping the
+ * package left two of three consumers holding the previous text, with a stamp that read as current
+ * and nothing anywhere reporting a difference. The rules are edited far more often than the
+ * version moves — most of all while they are being written, which is exactly when a stale copy
+ * does the most damage.
+ *
+ * So the digest goes in alongside the version: the version stays for humans reading the file, and
+ * the digest is what the refresh actually compares. Identical body → still a no-op.
+ */
+const DIGEST_RE = /<!-- godxjp-ui:digest ([0-9a-f]{12}) -->/;
+const digestOf = (body) => createHash("sha256").update(body).digest("hex").slice(0, 12);
+const OWNED_STAMP = (body) => `${STAMP(KIT_VERSION)}\n<!-- godxjp-ui:digest ${digestOf(body)} -->`;
+
+/** The content digest stamped in `text`, or null when it predates digest stamping. */
+export function stampedDigest(text) {
+  return text?.match(DIGEST_RE)?.[1] ?? null;
+}
+
+/**
+ * Replace the MANAGED region of a file and leave everything else alone.
+ *
+ * Refreshing is only safe if it cannot eat hand-written content, so the contract is narrow: the
+ * region is delimited, and anything outside the delimiters survives byte-for-byte. A consumer that
+ * 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.
@@ -50,6 +95,7 @@ or change a component, page, or form — no exceptions.
 /** 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) -->
+${STAMP(KIT_VERSION)}
 ## @godxjp/ui — mandatory UI workflow (do NOT skip)
 
 This app uses @godxjp/ui. EVERY time you build or change UI:
@@ -82,6 +128,24 @@ function readJson(path) {
 }
 
 /** Ensure `.mcp.json` registers the godx-ui MCP server. Returns 'created' | 'added' | 'present'. */
+/**
+ * The version that wrote each managed artefact, stamped so `postinstall` can tell "already there"
+ * apart from "already there and STALE".
+ *
+ * Everything below used to be install-once: `ensureMcpJson` returned early on a present key,
+ * `writeWorkflowMd` on a present file, `ensureClaudeMd` on a present marker. So `npm update
+ * @godxjp/ui` brought new components, new audit rules and new catalog entries — and left the
+ * agent reading whatever guidance shipped the day the package was FIRST installed. The library
+ * moved; the instructions for using it did not.
+ */
+export function refreshBlock(current, next, startMarker, endMarker) {
+  const i = current.indexOf(startMarker);
+  if (i < 0) return current.replace(/\s*$/, "") + "\n\n" + next;
+  const j = endMarker ? current.indexOf(endMarker, i) : -1;
+  const tail = j < 0 ? "" : current.slice(j + endMarker.length);
+  return current.slice(0, i) + next + tail;
+}
+
 export function ensureMcpJson(root) {
   const path = join(root, ".mcp.json");
   const json = readJson(path) ?? {};
@@ -127,7 +191,14 @@ export function ensureClaudeHooks(root) {
 export function writeWorkflowMd(root) {
   const path = join(root, ".claude", "godxjp-ui-workflow.md");
   mkdirSync(dirname(path), { recursive: true });
-  if (existsSync(path)) return false;
+  // This file is owned entirely by the package — the CLAUDE.md block tells the consumer to edit
+  // it, but nothing else reads from it, so a stale copy is pure loss. Rewrite when the stamp moves.
+  if (existsSync(path)) {
+    const cur = readFileSync(path, "utf8");
+    if (stampedVersion(cur) === KIT_VERSION) return false;
+    writeFileSync(path, WORKFLOW_MD);
+    return "refreshed";
+  }
   writeFileSync(path, WORKFLOW_MD);
   return true;
 }
@@ -139,7 +210,16 @@ export function writeWorkflowMd(root) {
 export function ensureClaudeMd(root) {
   const path = join(root, "CLAUDE.md");
   const existing = existsSync(path) ? readFileSync(path, "utf8") : null;
-  if (existing?.includes("godxjp-ui:start")) return "present";
+  if (existing?.includes("godxjp-ui:start")) {
+    // Present — but at WHICH version? Refresh only the delimited block; anything the consumer
+    // wrote around it is untouched.
+    if (stampedVersion(existing) === KIT_VERSION) return "present";
+    writeFileSync(
+      path,
+      refreshBlock(existing, CLAUDE_MD_BLOCK, "<!-- godxjp-ui:start", "<!-- godxjp-ui:end -->"),
+    );
+    return "refreshed";
+  }
   if (existing == null) {
     writeFileSync(path, CLAUDE_MD_BLOCK);
     return "created";
@@ -157,3 +237,85 @@ export function shouldSkip(root) {
   if (pkg.name === "@godxjp/ui" || pkg.name === "@godxjp/ui-mcp") return "self";
   return null;
 }
+
+/**
+ * Keep an opted-in guinea-pig skill current.
+ *
+ * The file is co-authored: sections 0–7 come from this package, and section 8 onward is whatever
+ * the repo wrote about ITSELF — its package manager, its audit baseline, its deliberate
+ * exceptions. So the refresh replaces the head and keeps the tail, which is the only split that
+ * lets the guidance move without eating the consumer's own notes.
+ *
+ * Only runs where `.guinea-pig-optin` exists: the skill carries an obligation to fix things
+ * UPSTREAM, and pushing that into a repo that never asked for it would tell its agent to go edit
+ * a library it has no mandate over.
+ */
+export function refreshGuineaPigSkill(root) {
+  const dir = join(root, ".claude", "skills", "godx-ui-guinea-pig");
+  const target = join(dir, "SKILL.md");
+  const optin = join(dir, ".guinea-pig-optin");
+  if (!existsSync(optin) || !existsSync(target)) return false;
+  if (readFileSync(optin, "utf8").trim() === KIT_VERSION) return false;
+
+  const base = readFileSync(join(SELF_ROOT, "scripts", "guinea-pig-skill.md"), "utf8");
+  const current = readFileSync(target, "utf8");
+  const marker = "\n---\n\n# 8. ";
+  const i = current.indexOf(marker);
+  writeFileSync(target, base.replace(/\s*$/, "") + "\n" + (i < 0 ? "" : current.slice(i)));
+  writeFileSync(optin, `${KIT_VERSION}\n`);
+  return true;
+}
+
+/**
+ * Install the common consumer rules as a PATH-TRIGGERED file, and wire them into `.ai/rules`.
+ *
+ * The skill and this file say overlapping things on purpose, because they fire at different
+ * moments: a skill loads when the TASK matches its description — once, at the start — while an
+ * `.ai/rules` entry loads every time an agent touches a file under its glob. Measured over one
+ * session: a dashboard file was edited dozens of times and the skill was never re-read, so the
+ * laws that mattered were out of context for every edit after the first.
+ *
+ * The glob is DETECTED, not assumed. A rule wired to a directory the repo does not have is a rule
+ * that never fires, which is worse than no rule at all — it looks installed.
+ *
+ * Unlike the skill, this file is owned OUTRIGHT by the package and is rewritten whole. That is the
+ * honest shape for `.ai/rules`, where the convention is one file per concern and the index loads
+ * them all: a repo with something of its own to say writes its own rule file instead of editing
+ * this one. The file says so at the top, because the first draft preserved nothing and silently
+ * ate a note left inside it — measured, and the reason for that banner.
+ */
+export function ensureConsumerRules(root) {
+  const uiDir = ["resources/js", "app/javascript", "src/components", "src", "app"].find((d) =>
+    existsSync(join(root, d)),
+  );
+  if (!uiDir) return false;
+
+  const dir = join(root, ".ai", "rules");
+  const target = join(dir, "godxjp-ui.md");
+  const body = readFileSync(join(SELF_ROOT, "scripts", "consumer-rule.md"), "utf8");
+  const front = `---\npaths:\n    - '${uiDir}/**'\n---\n\n`;
+  // The digest covers the FRONT MATTER too: the detected glob is part of what makes this file
+  // correct, and a repo that grows a `resources/js` after shipping with `src` needs the rewrite.
+  const managed = `${front}${body}`;
+  const next = `${OWNED_STAMP(managed)}\n${managed}`;
+
+  if (existsSync(target) && stampedDigest(readFileSync(target, "utf8")) === digestOf(managed)) {
+    return false;
+  }
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(target, next);
+
+  // Only touch the index when the repo keeps one; a missing index means the repo reads rule files
+  // directly, and inventing one would change how it loads everything else.
+  const index = join(dir, "index.md");
+  if (existsSync(index)) {
+    const cur = readFileSync(index, "utf8");
+    if (!cur.includes(".ai/rules/godxjp-ui.md")) {
+      writeFileSync(
+        index,
+        cur.replace(/\s*$/, "") + `\n| ${uiDir}/** | .ai/rules/godxjp-ui.md |\n`,
+      );
+    }
+  }
+  return uiDir;
+}

package/scripts/consumer-rule.md

@@ -0,0 +1,98 @@
+# @godxjp/ui
+
+> **Tệp này do gói `@godxjp/ui` sở hữu và bị GHI ĐÈ mỗi lần nâng cấp.**
+> Đừ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`.
+
+## Bố cục chuẩn của platform: BA CỘT, và ba cột là BA PHẠM VI
+
+Vỏ mặc định của mọi app trên platform là ba cột, dựng bằng một `AppShell`:
+
+```
+navRail (3.5rem) │ sidebar (16rem) │ content
+```
+
+Không tự dựng ba cột bằng cách nhét hai cột vào một khe `sidebar` rồi nới
+`--app-shell-sidebar-width`. Hai bẫy đã đo được: `Sidebar` render
+`.sb-root { display: contents }` nên hai `Sidebar` đặt cạnh nhau **tan vào một
+flex row** và cùng co về 0; và nới token dùng chung khiến mép nội dung **nhảy
+64px giữa các route**. `navRail` sở hữu track riêng nên không cần cả hai.
+
+**Đặt một control vào cột nào là câu hỏi về PHẠM VI, không phải về chỗ trống:**
+
+| Cột       | Phạm vi                                                       | Chứa gì                                                                                     |
+| --------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `navRail` | **platform** — đúng với cả tổ chức, sống sót qua việc đổi app | đổi tổ chức · đổi app · thông báo · tin nhắn · sự kiện · cài đặt tổ chức · lối tắt liên-app |
+| `sidebar` | **app** — của riêng app đang mở                               | mục/kênh/route của chính app này                                                            |
+| `topbar`  | **trang** — bạn đang ở đâu, làm được gì ở đây                 | breadcrumb · hành động của trang · menu tài khoản                                           |
+
+Hai luật phủ định, và chúng làm được việc:
+
+- Điều hướng của app **không bao giờ** vào rail. Một rail lặp lại mục của
+  sidebar là dải chrome thứ hai mang thứ hạng của dải thứ nhất, chỉ dựng đứng.
+- Công tắc cấp platform **không bao giờ** vào sidebar — đổi app xong nó biến
+  mất, trong khi nó vẫn phải ở đó.
+- Đích nào hợp cả hai thì thuộc **rail**: nó sống sót qua việc đổi app.
+
+`sidebarCollapsed` chỉ gập cột `sidebar`; rail giữ nguyên bề rộng, nên đích cấp
+platform vẫn với tới được lúc gập. Đừng dựng lại hành vi này bằng CSS của kho.
+
+Bề rộng rail là token `--app-shell-nav-rail-width` — kho nào muốn rail rộng kiểu
+Slack thì đặt lại **một dòng**, không fork `.app-nav-rail`.
+
+## Trước khi viết bố cục: TRA, đừng dựng
+
+Hỏi MCP `godxjp-ui` (`search_components`, `get_component`). Đo được trong một
+ngày: năm thứ cần đều ĐÃ CÓ và vẫn bị dựng lại bằng thứ khác —
+
+| Cần                                      | Đã có                 |
+| ---------------------------------------- | --------------------- |
+| đường kẻ chạm mép Card                   | `<CardContent flush>` |
+| header có kẻ khi thân là danh sách flush | `<CardHeader banded>` |
+| một hàng LÀ liên kết (thay cho nút rời)  | `<ListRow asChild>`   |
+| kẻ ô từng ngày trong lịch                | `<Calendar bordered>` |
+| dải giữa hai vùng, tự kẻ theo VỊ TRÍ     | `<CardBar>`           |
+
+Lỗi không phải "đoán sai tên prop" mà là **cho rằng nó không tồn tại nên không
+hỏi**.
+
+## Catalog chở PROP, không chở LUẬT BỐ CỤC
+
+`CardBar` trong manifest có đúng một prop (`extra`) — không dòng nào nói nó tự
+kẻ theo vị trí (đầu: kẻ dưới · cuối: kẻ trên · giữa: cả hai). Luật ấy chỉ nằm
+trong chú thích `node_modules/@godxjp/ui/src/styles/card-layout.css`.
+
+**Làm bố cục trong một component của DS → mở tệp `*-layout.css` của nó ra đọc.**
+
+## Card không lồng Card
+
+Một `<Card>` trong `<Card>` cho hai mép bo cách nhau 16px và hai lớp padding
+chồng lên. Cần viền cho thứ bên trong thì tìm trục của chính nó
+(`Calendar bordered`), đừng bọc thêm một mặt phẳng nữa.
+
+Cùng lý do: đừng xếp `<Alert>` thành danh sách trong Card — mỗi Alert là một mặt
+phẳng, và `Alert` còn phát `role="alert"` nên cả danh sách sẽ tự đọc to lên khi
+tải trang. Danh sách là `ListRow`.
+
+## Màu chữ đọc tầng CHỮ, không đọc tầng TÔ
+
+`--success/--warning/--info/--destructive` là màu **TÔ** (nền badge, thanh, viền
+alert). Chữ đọc `--text-success/-warning/-info/-error`.
+
+Đo được: `Text tone="warning"` đọc nhầm tầng cho **1,74:1**; đúng tầng cho
+**5,90:1**. Cùng `tone` ấy trong `Badge` vẫn đạt 5,52:1 — nên cùng một prop
+hiện đọc được ở chỗ này và không đọc được ở chỗ kia, trên cùng một màn hình.
+
+## Audit xanh ≠ chạy đúng
+
+`ui-audit` xanh chỉ nghĩa là **không có gì cấm** bạn. Đo được: một consumer viết
+`modifiers` + `modifiersClassNames` cho màu cuối tuần — audit xanh, tsc xanh,
+build xanh, và **số màu chữ trên cả lưới vẫn là 1**, vì class rơi vào `<td>` còn
+`<button>` tự đặt màu.
+
+Một API chết im lặng trông y hệt một API đang chạy. **Mở trang và đo** mới biết.