@godxjp/ui 19.6.0 → 20.0.0

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.

package/scripts/init-guinea-pig.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * init-guinea-pig — install the GUINEA-PIG skill into a consumer app.
+ *
+ * Deliberately NOT part of `init-agent-kit`. The agent kit is for every consumer; this skill
+ * carries an obligation only a guinea-pig repo accepts — that a gap found here is fixed UPSTREAM,
+ * in @godxjp/ui, rather than worked around locally. Installing it in an ordinary consumer would
+ * tell its agent to go edit a library it has no mandate over.
+ */
+import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { KIT_VERSION, shouldSkip } from "./_agent-setup.mjs";
+
+const root = process.env.INIT_CWD || process.cwd();
+const skip = shouldSkip(root);
+
+if (skip === "self") {
+  console.error("init-guinea-pig is for CONSUMER apps, not the @godxjp/ui repo itself.");
+  process.exit(1);
+}
+if (skip === "no-package") {
+  console.error(`No package.json at ${root} — run this from a consumer app's root.`);
+  process.exit(1);
+}
+
+const source = join(dirname(fileURLToPath(import.meta.url)), "guinea-pig-skill.md");
+const target = join(root, ".claude", "skills", "godx-ui-guinea-pig", "SKILL.md");
+
+if (existsSync(target)) {
+  console.log(`  guinea-pig skill already present:\n    ${target}`);
+  console.log(
+    "\n  Its BASE sections now refresh on `npm update @godxjp/ui`; anything you appended below\n" +
+      "  the `# 8.` marker is preserved. Re-running this command changes nothing.\n",
+  );
+  process.exit(0);
+}
+
+mkdirSync(dirname(target), { recursive: true });
+copyFileSync(source, target);
+
+/*
+ * Record the opt-in so `postinstall` can keep the skill current.
+ *
+ * Without this the file would be install-once like the rest of the kit used to be: a repo that
+ * opted in on 19.5 would still be reading 19.5's guidance after a dozen upgrades, which is the
+ * exact staleness this whole change exists to remove. The marker lives next to the skill rather
+ * than in package.json so it travels with the thing it describes.
+ */
+writeFileSync(join(dirname(target), ".guinea-pig-optin"), `${KIT_VERSION}\n`);
+
+console.log(`
+  guinea-pig skill installed:
+    • ${target}
+
+  This repo now carries the guinea-pig obligation: a gap found here is fixed in @godxjp/ui,
+  not worked around locally. Append a repo-specific section to the file for anything only
+  this app knows — a deliberate audit exception, its package manager, its open findings.
+
+  Restart your agent to load the skill.
+`);

package/scripts/postinstall.mjs

@@ -4,7 +4,14 @@
  * access to the component catalog + audit rules WITHOUT any manual step. Non-destructive (only
  * adds a missing server entry) and guarded so it never runs in CI or in the library's own repo.
  */
-import { ensureClaudeMd, ensureMcpJson, shouldSkip, writeWorkflowMd } from "./_agent-setup.mjs";
+import {
+  ensureClaudeMd,
+  ensureMcpJson,
+  ensureConsumerRules,
+  refreshGuineaPigSkill,
+  shouldSkip,
+  writeWorkflowMd,
+} from "./_agent-setup.mjs";
 
 const root = process.env.INIT_CWD || process.cwd();
 
@@ -18,9 +25,13 @@ try {
   // but no mandate). Only the hooks — which DO change the loop — stay behind `init-agent`.
   const md = ensureClaudeMd(root);
   const wf = writeWorkflowMd(root);
-  if (r === "present" && md === "present" && !wf) process.exit(0); // already configured — stay quiet
+  const skill = refreshGuineaPigSkill(root);
+  const rules = ensureConsumerRules(root);
+  if (r === "present" && md === "present" && !wf && !skill && !rules) process.exit(0); // current — stay quiet
   console.log(
     `\n  @godxjp/ui → MCP in .mcp.json (${r}); workflow mandate in CLAUDE.md (${md}).\n` +
+      (rules ? `  common consumer rules in .ai/rules/godxjp-ui.md (glob ${rules}/**).\n` : "") +
+      (skill ? "  guinea-pig skill refreshed to this version (your section 8 kept).\n" : "") +
       "  Your agent now has live component + audit guidance. Restart it to pick up the MCP.\n" +
       "  For auto-audit on every edit (PostToolUse + SessionStart hooks):\n" +
       "    npx @godxjp/ui init-agent\n",

package/scripts/ui-audit.mjs

@@ -28,6 +28,23 @@ const EMOJI = /\p{Extended_Pictographic}/u;
 /** Regional-indicator pairs = emoji flags (🇯🇵) — broken on Win/Linux; use Intl.DisplayNames. */
 const EMOJI_FLAG = /\p{Regional_Indicator}/u;
 
+/**
+ * The attribute run of a JSX OPEN TAG, for rules that must see the whole element rather than one
+ * class name. Two things a plain `[^>]*` gets wrong, both of them the "green because it measured
+ * nothing" shape:
+ *
+ *  1. `[^>]` stops at the `>` of an arrow function, so `<Button onClick={() => go()} size="icon">`
+ *     was invisible while the identical `<Button size="icon" onClick={() => go()}>` was flagged.
+ *     A rule that depends on ATTRIBUTE ORDER is a rule an author flips by moving a prop — the same
+ *     defect `no-hand-rolled-surface` had with CLASS order. `(?:=>[^>]*)*` lets the run step over
+ *     an arrow and keep going; the tag's own `>` still ends it.
+ *  2. The scanner below feeds rules ONE LINE at a time, and prettier wraps any element wider than
+ *     printWidth onto several lines. Every rule anchored on `<Tag …>` therefore only ever saw
+ *     single-line elements. Rules carrying `spansElement: true` are matched against the whole file
+ *     instead (line number derived from the match offset), so wrapping no longer hides a violation.
+ */
+const ATTRS = String.raw`[^>]*(?:=>[^>]*)*`;
+
 /**
  * @type {{id:string, severity:'error'|'warn', test:RegExp, message:string, standard?:string, exempt?:RegExp}[]}
  *
@@ -70,7 +87,25 @@ const RULES = [
     severity: "warn",
     // rounded + border/bg on the consumer's own element = a fake Card / Badge / Avatar / ListRow
     // that drifts from the real ones (a 38px account pill beside 32px controls).
-    test: /className=(?:"[^"]*|'[^']*|\{`[^`]*)\brounded(?:-(?:full|sm|md|lg|xl|2xl))?\b[^"'`]*\b(?:border|bg-)/,
+    //
+    // ORDER-INDEPENDENT, and it has to be: the old single regex required `rounded` to appear
+    // BEFORE `border`/`bg-`, so the identical element passed or failed depending on how the
+    // classes happened to be sorted — and prettier's Tailwind plugin sorts them. A `bg-current …
+    // rounded-full` dot was clean, `prettier --write` reordered it to `rounded-full bg-current`,
+    // and the warning appeared with no source change. A rule a formatter can flip is a rule
+    // nobody can trust.
+    test: (line) => {
+      const m = line.match(/className=(?:"([^"]*)"|'([^']*)'|\{`([^`]*)`)/);
+      if (!m) return false;
+      const cls = m[1] ?? m[2] ?? m[3] ?? "";
+      // A MARKER is not a surface. `size-1` is 4px — a dot, a pip, a status bead. The primitives
+      // this rule points at (Card, Badge, Avatar, ListRow, Descriptions, EmptyState) all start at
+      // control height, so none of them can express one, and flagging it sends the reader looking
+      // for a component that does not exist. The cut-off is `size-2` / 8px: below that there is no
+      // room for the padding and type that make something a surface.
+      if (/\b(?:size|[wh])-(?:0\.5|1|1\.5|2)\b/.test(cls)) return false;
+      return /\brounded(?:-(?:full|sm|md|lg|xl|2xl))?\b/.test(cls) && /\b(?:border|bg-)/.test(cls);
+    },
     message:
       "Hand-rolled surface (rounded + border/bg) — use Card, Badge, Avatar, ListRow, Descriptions or EmptyState so height, padding and radius come from the tokens (docs/CONSUMER-RULES.md §4).",
   },
@@ -92,11 +127,15 @@ const RULES = [
   {
     id: "status-tone-not-variant",
     severity: "error",
+    spansElement: true,
     // Only the tone-driven status components (Badge/Tag/StatCard) are wrong here — they expose a
     // `tone` prop and reserve `variant` for STRUCTURE (default|secondary|outline). Button, Alert,
     // DropdownMenuItem, ContextMenuItem, AlertDialog etc. legitimately use `variant` for emphasis,
     // so they must NOT be flagged.
-    test: /<(?:Badge|Tag|StatCard)\b[^>]*\bvariant=["'](?:success|warning|destructive|info|neutral)["']/,
+    test: new RegExp(
+      `<(?:Badge|Tag|StatCard)\\b${ATTRS}\\bvariant=["'](?:success|warning|destructive|info|neutral)["']`,
+      "g",
+    ),
     message:
       "Badge/Tag/StatCard status uses tone, not variant (variant is structural: default|secondary|outline). Use tone='success|warning|destructive|info|neutral'.",
   },
@@ -110,7 +149,12 @@ const RULES = [
   {
     id: "value-callback-on-value-change",
     severity: "error",
-    test: /<(?:Checkbox\.Group|Upload|Cascader|TreeSelect|Transfer|SearchSelect|DatePicker|DateRangePicker|TimePicker|ColorPicker|LocalePicker|TimezonePicker|DateFormatPicker|TimeFormatPicker)\b[^>]*\bonChange=/,
+    spansElement: true,
+    test: new RegExp(
+      "<(?:Checkbox\\.Group|Upload|Cascader|TreeSelect|Transfer|SearchSelect|DatePicker|" +
+        `DateRangePicker|TimePicker|ColorPicker|LocalePicker|TimezonePicker|DateFormatPicker|TimeFormatPicker)\\b${ATTRS}\\bonChange=`,
+      "g",
+    ),
     message:
       "Abstract value components use onValueChange, not onChange. Reserve onChange for DOM events.",
   },
@@ -219,7 +263,8 @@ const RULES = [
   {
     id: "card-manual-padding",
     severity: "error",
-    test: /<Card\b[^>]*\bp-[1-9]/,
+    spansElement: true,
+    test: new RegExp(`<Card\\b${ATTRS}\\bp-[1-9]`, "g"),
     message:
       "Don't hand-roll padding on <Card> (className='p-4'…) — wrap the body in <CardContent>. (p-0 for a full-bleed table is fine.)",
   },
@@ -232,7 +277,8 @@ const RULES = [
   {
     id: "manual-field-error",
     severity: "warn",
-    test: /<p[^>]*className="[^"]*text-(xs|sm)[^"]*text-destructive/,
+    spansElement: true,
+    test: new RegExp(`<p${ATTRS}className="[^"]*text-(?:xs|sm)[^"]*text-destructive`, "g"),
     message:
       "Field errors should use <FormField error=…>, not a hand-rolled <p> (rules §1). OK only for checkbox/radio groups.",
   },
@@ -281,9 +327,13 @@ const RULES = [
   {
     id: "icon-button-needs-name",
     severity: "warn",
+    spansElement: true,
     // An icon-only Button (size="icon") with no author-supplied accessible name. A combobox/icon
     // button's name is computed from author (aria-label / aria-labelledby / title), not glyph content.
-    test: /<Button\b(?=[^>]*\bsize=["']icon["'])(?![^>]*\b(?:aria-label|aria-labelledby|title)=)[^>]*>/,
+    test: new RegExp(
+      `<Button\\b(?=${ATTRS}\\bsize=["']icon["'])(?!${ATTRS}\\b(?:aria-label|aria-labelledby|title)=)${ATTRS}>`,
+      "g",
+    ),
     standard: "WCAG 2.2 SC 4.1.2 · 1.1.1 · WAI-ARIA 1.2",
     message:
       "Icon-only <Button size=\"icon\"> needs an accessible name — add aria-label={t('…')}. The icon is decorative (aria-hidden); the name comes from the author, not the glyph.",
@@ -291,7 +341,8 @@ const RULES = [
   {
     id: "img-needs-alt",
     severity: "warn",
-    test: /<img\b(?![^>]*\balt=)[^>]*>/,
+    spansElement: true,
+    test: new RegExp(`<img\\b(?!${ATTRS}\\balt=)${ATTRS}>`, "g"),
     standard: "WCAG 2.2 SC 1.1.1 · HTML Living Standard (WHATWG)",
     message:
       'Every <img> needs an alt attribute (alt="" for purely decorative images). Prefer the <Avatar>/<AspectRatio> primitives for product imagery.',
@@ -476,16 +527,22 @@ function walk(dir, acc = []) {
 // 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>).
-const CARD_FLUSH =
-  /<Card(?![^>]*\bp-0\b)(?:\s[^>]*)?>\s*<(?!CardContent|CardHeader|CardCover|CardFooter|CardBar|\/Card)/g;
+const CARD_FLUSH = new RegExp(
+  `<Card(?!${ATTRS}\\bp-0\\b)(?:\\s${ATTRS})?>\\s*<(?!CardContent|CardHeader|CardCover|CardFooter|CardBar|\\/Card)`,
+  "g",
+);
 
 // Structural: a bare <label>/<Label> paired with a TEXT control (its sibling) instead of a
 // <FormField>. FormField OWNS the label↔control association (htmlFor/id), aria-describedby/
 // error wiring, AND the field rhythm (label gap + field spacing) — a hand-rolled Label+Input
 // loses all of it (the cramped login-form failure mode). Checkbox/Radio/Switch use Field/Label
 // legitimately, so they are NOT matched. Whole-file pass (the pair spans lines).
-const BARE_FIELD =
-  /<(?:label|Label)\b[^>]*>[\s\S]{0,240}?<\/(?:label|Label)>\s*<(?:Input|Select|Textarea|NumberInput|SearchInput|SearchSelect|DatePicker|DateRangePicker|TimePicker|MonthPicker|MonthRangePicker|Cascader|TreeSelect|input)\b/g;
+const BARE_FIELD = new RegExp(
+  `<(?:label|Label)\\b${ATTRS}>[\\s\\S]{0,240}?</(?:label|Label)>\\s*` +
+    "<(?:Input|Select|Textarea|NumberInput|SearchInput|SearchSelect|DatePicker|DateRangePicker|" +
+    "TimePicker|MonthPicker|MonthRangePicker|Cascader|TreeSelect|input)\\b",
+  "g",
+);
 
 // Two <Card> siblings written back to back at the same indentation with nothing between them.
 // Direct children of PageContainer are spaced by the page; anywhere else they touch.
@@ -507,17 +564,20 @@ const ACTIVE_RULES =
   SELF && !args.includes("--consumer") ? RULES.filter((r) => r.scope !== "consumer") : RULES;
 
 const findings = [];
+let filesScanned = 0;
 for (const dir of SCAN_DIRS) {
   for (const file of walk(isAbsolute(dir) ? dir : join(CWD, dir))) {
     const rel = relative(CWD, file);
+    filesScanned += 1;
     const content = readFileSync(file, "utf8");
     const origLines = content.split("\n");
     const scanContent = stripComments(content); // comments blanked; strings + line numbers kept
     const scanLines = scanContent.split("\n");
     scanLines.forEach((line, i) => {
       for (const rule of ACTIVE_RULES) {
+        if (rule.spansElement) continue; // matched over the whole file below, not line by line
         if (
-          rule.test.test(line) &&
+          (typeof rule.test === "function" ? rule.test(line) : rule.test.test(line)) &&
           !isSuppressed(rule.id, origLines[i], origLines[i - 1]) &&
           !isExempt(rule, origLines[i], origLines[i - 1])
         ) {
@@ -533,6 +593,26 @@ for (const dir of SCAN_DIRS) {
         }
       }
     });
+    // Element-spanning rules: matched against the WHOLE file, because a JSX element prettier wrapped
+    // over five lines is invisible to a line-by-line scan. Same offset→line-number idiom as the
+    // block rules below.
+    for (const rule of ACTIVE_RULES) {
+      if (!rule.spansElement) continue;
+      for (const match of scanContent.matchAll(rule.test)) {
+        const lineNo = scanContent.slice(0, match.index).split("\n").length;
+        if (isSuppressed(rule.id, origLines[lineNo - 1], origLines[lineNo - 2])) continue;
+        if (isExempt(rule, origLines[lineNo - 1], origLines[lineNo - 2])) continue;
+        findings.push({
+          file: rel,
+          line: lineNo,
+          rule: rule.id,
+          severity: rule.severity,
+          standard: rule.standard,
+          message: rule.message,
+          snippet: match[0].replace(/\s+/g, " ").slice(0, 120),
+        });
+      }
+    }
     for (const match of scanContent.matchAll(CARD_FLUSH)) {
       const lineNo = scanContent.slice(0, match.index).split("\n").length;
       if (isSuppressed("card-needs-content", origLines[lineNo - 1], origLines[lineNo - 2]))
@@ -589,7 +669,28 @@ for (const dir of SCAN_DIRS) {
 const errors = findings.filter((f) => f.severity === "error");
 const warnings = findings.filter((f) => f.severity === "warn");
 
-if (asJson) {
+// A run that opened NO file is not a clean run. The default SCAN_DIRS are a consumer's
+// `resources/js/{components,pages,layouts}`; `walk()` swallows ENOENT and returns [], so in any
+// tree without that layout — this repo included — `pnpm audit` printed
+// "✓ No UI-standardization violations found." and exited 0 having read nothing at all.
+if (filesScanned === 0) {
+  const message =
+    `ui-audit scanned 0 files — none of [${SCAN_DIRS.join(", ")}] exists (or all were filtered). ` +
+    `Pass the directories to scan, e.g. \`node scripts/ui-audit.mjs src docs\`. ` +
+    `Reporting a clean audit without opening a file is not a result.`;
+  if (asJson) {
+    process.stdout.write(
+      JSON.stringify({ summary: null, error: message, findings: [] }, null, 2) + "\n",
+    );
+  } else {
+    console.error(`✗ ${message}`);
+  }
+  process.exitCode = 2;
+}
+
+if (filesScanned === 0) {
+  // already reported above
+} else if (asJson) {
   process.stdout.write(
     JSON.stringify(
       { summary: { errors: errors.length, warnings: warnings.length }, findings },
@@ -622,4 +723,4 @@ if (asJson) {
 }
 
 // See the note above --rules: exitCode, so a large JSON report drains fully.
-process.exitCode = errors.length > 0 ? 1 : 0;
+if (filesScanned > 0) process.exitCode = errors.length > 0 ? 1 : 0;