@godxjp/ui 19.5.0 → 20.0.0

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.

package/scripts/guinea-pig-skill.md

@@ -0,0 +1,322 @@
+---
+name: godx-ui-guinea-pig
+description: "Bắt buộc cho mọi kho là consumer CHUỘT BẠCH của @godxjp/ui. Kích hoạt khi: dựng hay sửa bất kỳ màn hình nào, gặp một prop còn thiếu, định viết class Tailwind để lách, định tự dựng component thay cho thứ DS đã có, chạy ui-audit, hoặc thấy chú thích 'chờ upstream'. Dạy MỘT việc mà không tài liệu nào khác dạy: cách KHÉP VÒNG từ 'app thiếu gì' sang 'DS đã sửa, đã phát hành, app đã nâng, vá tạm đã gỡ'. Không dùng cho consumer thường — chuột bạch có nghĩa vụ sửa ngược lên DS, consumer thường thì không."
+---
+
+# Consumer chuột bạch của @godxjp/ui
+
+> Bản gốc của tệp này nằm ở kho `godx-jp/godxjp-ui`. Sửa thì sửa ở đó rồi chép
+> sang các consumer, đừng sửa bản chép — kho này đã hỏng đúng kiểu ấy một lần
+> với catalog MCP (xem §4).
+
+## 0. Bạn có HAI việc, không phải một
+
+Việc thứ nhất là làm xong màn hình. Việc thứ hai là **để lại design system tốt
+hơn lúc bạn gặp nó**. Chuột bạch là kho mà `@godxjp/ui` bị dùng thật lần đầu;
+mọi khoảng trống lộ ra ở đây mà không được sửa ngược lên sẽ là khoảng trống
+**vĩnh viễn** cho mọi consumer sau.
+
+Vì vậy một bản vá tạm ở đây không phải là "nợ kỹ thuật của app". Nó là hai lần
+thất bại: màn hình lệch chuẩn, VÀ khoảng trống bị giấu đi.
+
+Bạn được toàn quyền sửa `@godxjp/ui`. Đó là điều kho này tồn tại để làm.
+
+## 1. Trước khi viết dòng JSX đầu tiên
+
+Định vị bản checkout của DS. Không có thì clone:
+
+```bash
+ls ~/Herd/godxjp-ui 2>/dev/null || git clone git@github.com:godx-jp/godxjp-ui.git ~/Herd/godxjp-ui
+cd ~/Herd/godxjp-ui && pnpm install       # DS dùng pnpm, consumer thường dùng npm — đừng lẫn
+```
+
+Và hỏi MCP `godxjp-ui`, đừng đoán tên prop: `search_components`, `get_component`,
+`get_tokens`. **Catalog là nguồn sự thật, không phải trí nhớ của bạn.**
+
+## 2. Kỷ luật — thứ bị cấm kể cả khi "chỉ tạm thôi"
+
+Mười luật ở `docs/CONSUMER-RULES.md` của DS là hàng rào, `ui-audit` cưỡng chế
+chúng. Không chép lại ở đây. Ba điều cấm riêng của **chuột bạch**:
+
+1. **Tự dựng component thay cho thứ DS đã có hoặc lẽ ra phải có.** Hộp tự vẽ
+   thay `Card`, hàng tự ghép thay `ListRow`, palette tự viết thay
+   `CommandPalette`.
+2. **Dùng class tiện ích để lách một prop còn thiếu** — `gap-3`, `p-4`,
+   `w-[240px]`, `text-muted-foreground`.
+3. **Gõ mã màu hex hay số đo ngoài thang token.**
+
+Thước đo, chạy trước mọi lần review:
+
+```bash
+node node_modules/@godxjp/ui/scripts/ui-audit.mjs resources/js   # 0 lỗi là mức đạt
+```
+
+Một lỗi bạn **không sửa được ở phía consumer** chính là một khoảng trống của DS.
+Nó là đầu vào của §3, không phải một ngoại lệ để nới.
+
+## 3. Vòng lặp — sáu bước, và nó phải KHÉP
+
+Đây là phần không tài liệu nào khác có. `design-to-page` và `compose-a-screen`
+đều dừng ở `report-bug`; mở issue rồi để đó là hỏng nửa vời.
+
+### Bước 1 — Chứng minh đó là khoảng trống, đừng cảm thấy
+
+Viết ra đúng đoạn mã bạn **muốn** viết, rồi chạy `ui-audit` lên nó.
+
+Audit xanh nghĩa là **không có gì CẤM** bạn — chưa phải là bạn có nước đi. Nước
+đi chỉ có thật khi bạn MỞ TRANG và thấy nó đổi pixel. Đo được: 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** — 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.
+
+Chỉ khi mọi prop và token hiện có đều không nói được điều cần nói, VÀ mọi đường
+còn lại đều bị audit chặn, thì mới là bất khả.
+
+### Bước 2 — Ba câu hỏi, phải đủ cả ba
+
+Đọc `docs/WHAT-BELONGS-HERE.md` của DS. Tóm tắt không thay thế nó:
+
+1. Consumer có thật sự **không có nước đi hợp lệ** nào không? (không phải "bất tiện")
+2. Nó thuộc về **hình dạng** của component, hay **nội dung** của một màn?
+3. Consumer **khác** có cần không?
+
+Trượt bất kỳ câu nào → dựng ở consumer, và ghi rõ TRONG MÃ vì sao nó không
+thuộc về DS.
+
+### Bước 3 — Sửa trong DS, và sửa đủ bốn chỗ
+
+```
+src/…            mã
+src/…/__tests__/ test (§5)
+mcp/src/data/    catalog (§4 — chỗ hay quên nhất, và tốn kém nhất)
+docs/            nếu đổi hợp đồng công khai
+```
+
+Thứ tự ưu tiên, chỉ tiến khi bước trước thật sự không diễn đạt nổi:
+**dùng → ghép → thêm prop vào component đã có → tạo component mới.**
+Một prop nữa hơn một component nữa.
+
+### Bước 4 — Kiểm bằng tarball TRƯỚC khi phát hành
+
+Đây là bước làm cho "vừa làm vừa trải nghiệm" thành thật. Đừng phát hành rồi
+mới biết mình sửa trượt.
+
+```bash
+cd ~/Herd/godxjp-ui
+pnpm build && npm pack                    # ra @godxjp-ui-<version>.tgz
+cd <kho consumer>
+npm install ~/Herd/godxjp-ui/godxjp-ui-<version>.tgz
+```
+
+Rồi chạy màn hình thật với bản sửa: `ui-audit` phải sạch **và** đoạn mã bạn
+muốn viết ở Bước 1 phải chạy đúng. Nếu kho có bộ trình duyệt, chạy nó.
+
+**Xong việc thì hoàn nguyên `package.json` về bản registry** — đừng để một
+tarball đường dẫn máy bạn lọt vào commit. `main` phải `npm ci` được từ registry.
+
+### Bước 5 — Cổng của DS
+
+```bash
+# = verify:ci:static + check:frame-contracts + pnpm test, tức ĐÚNG những gì ci.yml chạy.
+cd ~/Herd/godxjp-ui && pnpm verify:ci
+```
+
+**Không nới, không tắt, không thêm ngoại lệ để lấy màu xanh.** Một cổng đỏ là
+một câu hỏi, không phải một chướng ngại. Nếu bạn tin cổng ấy sai thì nói ra và
+đưa số đo, đừng lặng lẽ sửa nó.
+
+### Bước 6 — Khép vòng
+
+Phát hành → nâng gói ở consumer → **gỡ vá tạm** → **gỡ mọi chú thích "chờ
+upstream"** → **đóng issue**.
+
+Vòng chưa khép thì việc chưa xong. Đợt 07–08/09/2026 mở 18 issue cho godxjp-ui;
+#401/#412 và #402 đã vá trên nhánh nhưng issue vẫn mở và consumer vẫn chờ —
+đó là hình dạng của thất bại này.
+
+## 4. Nghĩa vụ catalog — chỗ tốn kém nhất khi quên
+
+**Một prop có trong mã nhưng không có trong catalog MCP là một prop KHÔNG TỒN
+TẠI** với agent tiếp theo.
+
+Đây không phải suy đoán. Đo được trong phiên 08/09/2026: một agent mới, làm
+đúng mọi hướng dẫn (hỏi MCP, không đoán), kết luận _"Flex chỉ có gap"_ trong khi
+`pad` và `padRaw` đã nằm trong gói đã cài — vì catalog đã phát hành chưa có
+chúng. Nó làm đúng và vẫn ra sai.
+
+Nên sau mỗi lần thêm hay đổi prop:
+
+```bash
+node scripts/gen-component-api-manifest.mjs
+pnpm check:mcp-sync && pnpm check:mcp-prop-sync && pnpm check:component-api-manifest
+```
+
+Và kiểm ví dụ trong `mcp/src/data/{patterns,components}.ts` có **biên dịch được
+và qua nổi ui-audit** không. Catalog đã từng dạy: `<Dialog mode="confirm">`
+(không có API ấy), `variant="success"` (bị chính audit cấm),
+`<Input onValueChange>` (không có prop ấy). Ví dụ sai trong catalog không phải
+lỗi chính tả — nó là mã mà agent sau sẽ chép.
+
+## 5. Kỷ luật test của DS — luật, không phải gợi ý
+
+- **Test theo TỪNG component**, và chỉ những component **liên quan** tới nó.
+  `Dropdown` = menu + list + button + icon → chỉ quanh chừng đó. Không test lan man.
+- **Test của story/example KHÔNG nằm trong CI.** Chúng ở `tests/manual/`, chạy
+  bằng tay. CI không tiêu thời gian vào thứ vô bổ.
+- Test bám vào **role và nhãn**, không bám class Tailwind — có cổng
+  `check:no-tailwind-class-assertions` chặn.
+
+Vì sao role/nhãn: 138 trên 160 selector của bộ Playwright ở consumer bám vào
+`getByRole`/`getByLabel`. Chúng không phải nghi thức a11y — chúng là cái cân cho
+biết một lần đổi nền thư viện có làm vỡ CẤU TRÚC hay không. Gỡ chúng là mất cân.
+
+Nhưng chúng **không đo được màu, bo góc, hay phần tử nào đang được tô** — cả một
+đợt lỗi calendar đi qua chúng mà không cái nào đỏ. Cấu trúc và diện mạo là hai
+thước khác nhau; xem §5c.
+
+## 5b. Một cổng canh được đúng thứ nó CHẠY QUA
+
+Một cổng viết ra mà không nối vào CI là một cổng không tồn tại — y hệt một prop
+không có trong catalog (§4). Nhưng "đã nối" chưa đủ, và đợt 08/09/2026 đo được
+cả hai nửa của bài học này.
+
+**Nửa thứ nhất — đừng đo bằng cái thước sai.** Bản trước của mục này viết rằng
+"25 cổng `check:*` nằm ngoài `verify:ci`", và kết luận từ đó rằng chúng không
+chạy. Kiểm lại bằng workflow thì 22 trong 25 cổng ấy VẪN chạy mỗi lần merge hoặc
+mỗi đêm — chỉ là ở lane khác. Lý do rất đơn giản và rất dễ vấp: **không workflow
+nào chạy `verify:ci`.** `ci.yml` chạy `verify:ci:static` + `check:frame-contracts`
+
+- `pnpm test` chia shard; `ci-browser.yml` chạy `verify:browser` (gồm
+  `check:contrast`) và `check:frame-axe`; `ci-browser-full.yml` chạy các sweep rộng
+  theo lịch đêm; `release-integrity.yml` chạy `check:release-plan`. Hỏi "cổng này
+  có trong `verify:ci` không" là hỏi một script không ai gọi.
+
+Nên đừng tự viết đoạn `node -e` so với `verify:ci`. Hỏi thẳng cổng canh-cổng, nó
+đọc workflow rồi mới trả lời:
+
+```bash
+pnpm check:gate-coverage --report   # in ra: mỗi check:* chạy ở workflow nào
+pnpm check:gate-coverage            # đỏ nếu có cổng không ai chạy và không khai miễn trừ
+```
+
+Cổng này nằm trong `verify:ci:static`, nên thêm một `check:` mới mà quên nối vào
+đâu là CI đỏ ngay. Muốn để một cổng ngoài lề thì phải khai TƯỜNG MINH kèm lý do
+trong `EXEMPT` của `scripts/check-gate-coverage.mjs` — hiện có đúng hai cái, và
+cả hai đều là "cần người", không phải "chạy lâu": `check:voiceover-capture` (cần
+VoiceOver thật do người bật) và `check:frame-runtime` (chỉ là alias gọi tám cổng
+đã chạy riêng trong lane đêm). "Chạy lâu" không phải lý do để miễn trừ — đó là
+lý do để nằm trong lane đêm, và lane đêm VẪN được tính là có chạy.
+
+**Nửa thứ hai, và là nguyên nhân thật của lỗi đã lọt.** Một toast
+`data-type="success"` với tương phản **1,02:1** — chữ gần như vô hình — phát hành
+trong `@godxjp/ui@19.5.0` và bị bắt bởi **test trình duyệt của một consumer**.
+Kho DS có sẵn hai thứ đáng lẽ phải bắt được nó, và **cả hai đều đã chạy trong
+CI**:
+
+- `scripts/check-contrast.mjs` chạy mỗi lần merge trong job "Contrast + visual
+  audit" (55–59s, và tên job nằm trong `REQUIRED_CI_CHECK_RUNS` nên bản phát
+  hành không đi qua nổi nếu nó đỏ). Nó xanh — vì danh sách `ROUTES` của nó có 11
+  route và **không route nào render một cái toast**.
+- `src/components/feedback/__tests__/toast-tone-contrast.test.tsx` chạy trong
+  `pnpm test`. Nó xanh — vì nó đọc token trong `src/tokens/**` rồi tính tỉ số
+  trên giấy; nó chạy trong jsdom, mà jsdom **không tô màu**, nên nó không nhìn
+  thấy màu đã render thật.
+
+Không cổng nào bị tắt. Không cổng nào bị bỏ quên. Cả hai đều xanh và cả hai đều
+đúng với thứ chúng đo — chỉ là **không cái nào đo cái đã hỏng**. Đây là dạng
+hỏng đắt hơn hẳn dạng "quên nối cổng", vì bảng CI toàn xanh trông y hệt như một
+kho thật sự an toàn.
+
+`check:contrast` đã dính đúng dạng này một lần rồi, và vết sẹo còn nằm trong
+chú thích của chính nó: danh sách route từng trỏ vào `tiximax-*` sau khi các
+route đó bị đổi tên, nên chúng render ra "Showcase not found" và sweep báo trang
+rỗng ấy là AA sạch. Lần đó người ta thêm một guard chặn not-found. Lần này là
+cùng một hình dạng ở một trục khác: route tồn tại, nhưng bề mặt cần soi thì
+không có route nào chạm tới.
+
+Nên khi bạn thêm hay sửa một cổng, hỏi HAI câu chứ không phải một:
+
+1. **Nó có chạy không?** → `pnpm check:gate-coverage --report`.
+2. **Nó có đi qua bề mặt tôi vừa đụng không?** → mở chính danh sách đầu vào của
+   cổng (`ROUTES` của `check-contrast.mjs`, danh sách frame của `check:frame-axe`,
+   `include` của `vitest.config.ts`) và tìm bề mặt ấy trong đó. Cổng xanh trên
+   một danh sách không chứa thứ bạn vừa sửa thì nó chưa nói gì về bản sửa của bạn.
+
+Và một hệ quả cho phía consumer: **bộ test trình duyệt của bạn là lớp lưới cuối
+cùng của DS.** Hai lỗi tương phản trên do `php artisan test` của consumer bắt
+được, không phải do CI thư viện. Đừng bỏ axe ra khỏi bộ trình duyệt chỉ vì "hệ
+thống nội bộ" — ở đây nó không đo tuân thủ, nó đo xem DS có phát ra chữ đọc được
+hay không.
+
+## 5c. CSS hỏng IM LẶNG theo ba cách — và cách duy nhất thấy được
+
+Một luật CSS sai không báo lỗi, không cảnh báo, và đọc lên vẫn thuyết phục. Ba
+cơ chế, cả ba đo được trong một ngày:
+
+1. **Nhắm vào class không tồn tại.** `weekdays: cn("flex", …)` — không có class
+   DS, nên mọi luật viết cho `.ui-calendar-weekdays` chưa từng khớp lần nào.
+2. **Thua tầng khác.** `buttonVariants` đặt `rounded-[var(--button-radius)]` như
+   một Tailwind **utility**, mà `utilities` sau `components` — nên không luật
+   components nào đổi được bo góc của một Button. Phải trỏ lại chính biến đó.
+   Cùng lớp: CSS bên thứ ba nhập KHÔNG layer thắng mọi thứ; nhập sai vị trí
+   layer thì thua cả reset. Thứ tự đúng: `theme, base, vendor, components, utilities`.
+3. **Class ở phần tử này, sơn ở phần tử kia.** RDP đặt `day-selected` lên `<td>`,
+   còn nền/bo góc ở `<button>` bên trong → ngày chọn ra hình vuông sắc trong khi
+   hover thì tròn. Quy tắc: **một phần tử sở hữu bề mặt**, mọi trạng thái tô lên nó.
+
+Cách duy nhất phát hiện: **mở trang, `getComputedStyle`, rồi CHỤP MÀN HÌNH.** Đo
+đúng thuộc tính vừa sửa là chưa đủ — ba lần liên tiếp tôi báo "xong" trong khi
+khối đó đang vỡ ở chỗ khác.
+
+Token màu có HAI TẦNG: `--success/--warning/--info/--destructive` là màu **TÔ**;
+chữ phải đọc `--text-success/-warning/-info/-error`. Đo: `Text tone="warning"`
+đọc nhầm tầng cho **1,74:1**, đúng tầng cho **5,90:1**.
+
+## 5d. Tra catalog TRƯỚC khi tự dựng — bốn lần trong một ngày
+
+`CardContent flush` (đường kẻ chạm mép), `CardHeader banded` (header có kẻ khi
+thân là danh sách flush), `ListRow asChild` (hàng LÀ liên kết, thay cho một nút
+rời), `Calendar bordered` — cả bốn **đã có sẵn** và tôi vẫn tự dựng bằng thứ
+khác, vì không hỏi. Lỗi không phải "đoán sai tên prop" mà là **cho rằng thứ đó
+không tồn tại nên không hỏi**.
+
+Trước khi viết bất kỳ bố cục nào: `search_components` + `get_component`. Rẻ hơn
+mọi lần sửa sau.
+
+**Nhưng catalog chở PROP, không chở LUẬT BỐ CỤC** — và đó là một khoảng trống
+thật của catalog, không chỉ là lỗi của người dùng nó. Ví dụ đo được: `CardBar`
+trong manifest có đúng một prop (`extra`), không dòng nào nói nó **tự lấy đường
+kẻ theo VỊ TRÍ** — đầu thì kẻ dưới, cuối thì kẻ trên, ở giữa thì cả hai. Luật ấy
+chỉ nằm trong chú thích của `src/styles/card-layout.css`, cùng chỗ định nghĩa hai
+nhịp `section` (header phẳng) và `band` (header có kẻ).
+
+Nên khi làm bố cục bên trong một component của DS: **mở tệp `*-layout.css` của
+nó ra đọc**. Một agent hỏi MCP đúng cách vẫn sẽ không biết những luật này.
+
+## 6. Thứ KHÔNG đẩy lên DS
+
+- Bố cục của một trang cụ thể ("dashboard cần bốn thẻ ngang").
+- Số đo của một màn ("cột vai trò rộng 8rem").
+- Bất cứ thứ gì biết về miền nghiệp vụ của app này.
+
+DS sở hữu **hình dạng**. Màn hình sở hữu **nội dung**. Đẩy nhầm hướng làm DS
+phình ra thành thứ không ai nhớ nổi — cũng hỏng như để nó quá hẹp.
+
+## 7. Năm cách hỏng đã đo được — đừng lặp lại
+
+1. **Chẩn đoán bằng mắt rồi sửa.** Một lần đổ lỗi lệch header cho DS; hoá ra là
+   heuristic `onChat` của chính consumer. Đo trước, sửa sau.
+2. **Làm tròn số đo cho sạch lint.** Thiết kế cần 12px, thang bậc tên có 8 và
+   16 — "gần nhất" là một phép đoán, và mỗi khe lệch 4px × n phần tử là cả khối
+   trôi. Giữ nguyên literal và mở đường cho DS.
+3. **Đọc nhầm nguồn rồi kết luận chắc nịch.** Một lần đọc `.ui-inline-*` trong
+   khi thứ đang chạy là `.ui-flex-gap-*`, rồi tuyên bố "đã sửa rồi". Trích đúng
+   dòng đang chạy, không phải dòng trông giống.
+4. **Chạy audit sai chỗ.** `ui-audit` chỉ báo lỗi khi chạy TRONG cây consumer;
+   chạy nó ở `/tmp` ra 0 lỗi và ru ngủ.
+5. **Phép thử đột biến không thật sự đột biến.** Một lượt
+   `perl -0pi -e 's/data-slot="x"/BROKEN/'` thiếu cờ `/g` chỉ thay lần khớp ĐẦU
+   TIÊN — mà lần đầu lại nằm trong một dòng chú thích, nên mã chạy không hề đổi
+   và phép kiểm "không đỏ". Suýt kết luận rằng assertion là rỗng. Sau khi phá,
+   hãy XÁC NHẬN mình đã phá đúng chỗ (`git diff` một dòng) trước khi tin vào kết
+   quả màu.