菜单
Audit product / consumer UI code (非 design-system 本身) against DS usage discipline + mindset adherence. Catches element misuse / design principle violations / token leakage / geometry bugs / a11y gaps across 7 dimensions. Invoke via /product-ui-audit when user says「audit 這個 UI」「檢查 X feature 用對 DS 嗎」「這段 code 符合設計原則嗎」,or auto-invoked by /prototype Phase 3.5 gate.
Systematic audit of this design system for world-class quality. Runs the full audit dimension list(per `## The N audit dimensions` section) covering spec hygiene / code correctness / a11y / naming / tokens / patterns / CLAUDE.md consistency / Layout Family compliance / prop value collisions / shadcn alias leakage / home-name-vs-scope fit / spec hardcoded-values, and surfaces actionable fix lists. Has explicit checkpoints where the skill MUST stop and ask user. Invoke via /design-system-audit when asked to audit, re-audit, check quality, or verify design system health.
Phase A Claude solo 完整深度進階稽核 → Phase B codex 同流程稽核 + 比稿辯論共識 → Phase C 落地。SSOT-UI/UX 中文人話 propose / 其他 autonomous。對齊 M14/M18/M19/M20/M22/M23/M26/M29/M31/M32 + audit dim list 全集(SSOT = design-system-audit/SKILL.md)+ codex-collab 5-step。
Codex dual-track collab for visual/SSOT/canonical decisions. Claude own → codex own → 比稿 synthesize(永遠 3-step,不 pass-through)。Local `codex exec` 為主 transport(地端);GitHub PR comment 為 fallback。Queue SSOT `.claude/memory/codex-brief-queue.jsonl`。Invoke when user asks「跟 codex 討論 / 比稿 / 確認」.
Prune governance sprawl across CLAUDE.md / specs / skills / hooks / memory / settings. Finds duplicate rules (Rule-of-3), dead hooks (6mo 0 fire via `.claude/logs/hook-fires-per-hook.jsonl`), stale memories, over-concrete bug case studies that should abstract to meta, and contradictions across homes. Enforces per-file budget (CLAUDE.md target ≤ 200 / transition ≤ 400, spec ≤ 300, SKILL ≤ 250, memory ≤ 100) and retire rate ≥ 5% / quarter. Invoke via /knowledge-prune quarterly or when CLAUDE.md > 800 / MEMORY.md > 20 entries / audit Phase F reports sprawl. Auto-chained by /design-system-audit --deep Phase 4.5.
Auto-invoke when listing options / 建議 / 候選方案. Forces inline 7-Q principle check(M8 benchmark / M17 SSOT / Rule-of-3 / M10 subsumption)per option BEFORE listing. Failures filtered or labeled. Codifies「verify before propose」runtime discipline.
Process .claude/logs/user-corrections.jsonl — the Stop-hook-harvested signals of user corrections ("不是" / "不對" / "應該" / "糾正" etc.). Dedup by session + keyword, cluster by topic, propose edits to the right home(CLAUDE.md M-row / memory feedback file / skill reference / spec.md rationale). Each cluster is a Checkpoint — user approves before edit. After codification archive processed entries. Invoke when user-corrections.jsonl > 20 entries(session_start soft reminder)or > 40 entries(hard threshold), OR quarterly. This skill closes the loop between mindset
| name | product-ui-audit |
| description | Audit product / consumer UI code (非 design-system 本身) against DS usage discipline + mindset adherence. Catches element misuse / design principle violations / token leakage / geometry bugs / a11y gaps across 7 dimensions. Invoke via /product-ui-audit when user says「audit 這個 UI」「檢查 X feature 用對 DS 嗎」「這段 code 符合設計原則嗎」,or auto-invoked by /prototype Phase 3.5 gate. |
Purpose: design-system-audit audits the DS itself(spec / cva / SSOT 三方漂移);product-ui-audit audits consumer UI code(不是 DS 本身,是 app / exploration / feature code — 即「consumer 用 DS 的地方」)。防止:
明確觸發(直接 invoke):
/prototype Phase 3.5 自動 invoke(audit src/explorations/{topic-slug}/)不觸發:
/design-system-audit(不同 scope)design-system-audit /design-system-audit audit DS 本身(設計系統內部)
/product-ui-audit audit consumer UI code(本 skill)
/prototype 呼叫本 skill 作 Phase 3.5 gate
/delivery-handoff 只在產品交付前執行(產 handoff 文件)
src/app/** / src/explorations/** / src/pages/** / src/features/** / apps/**(含 DS repo 自家 apps/template + create-app 產物)等 — 不掃 packages/design-system/src/)每個 dimension 獨立檢查,產出 findings。詳細 grep pattern + rule 見 references/audit-checks.md。
packages/design-system/src/tokens/utility-registry.json;此處 inline 為 grep 便利,新增 alias 改 registry)[--foo] shorthand 靜默失效w-[48px] 應改 token)此維對齊既有 token 防線(lib/_token_hygiene.sh 5-check:shadcn alias / v4 shorthand / hardcoded shadow / primitive-color-as-utility / native overflow，由 post_edit_dispatcher.sh source；+ check_opacity_token_usage.sh 讀 utility-registry.json)+ 擴充硬色值 / 硬 px 檢查。
掃是否正確消費既有 layout primitives(非自 roll):
| 視覺 pattern | 應消費 | 違規 signal |
|---|---|---|
| icon+title+desc 垂直居中 | <Empty> | 自己寫 flex flex-col items-center 3-layer text |
| row prefix+content+suffix | item-layout | 自己寫 flex items-center gap-2 3-slot |
| overlay Header/Body/Footer | overlay-surface | 自己寫 border-b/border-t padding loose/tight |
| 橫向按鈕列 | action-bar pattern | 自己 flex gap-2 按鈕組 |
| 水平溢出 + fade mask | horizontal-overflow | 自己 overflow-x-auto + mask |
| 跨 OS 一致捲軸 | ScrollArea | native overflow-(auto|scroll) |
| 圖像 / media 容器 | AspectRatio | 硬寫 aspect-video / aspect-square class |
| Field wrapper | Field + fieldWrapperStyles | 自己 border + padding + startIcon + endAction |
aria-label對齊 CLAUDE.md 5 條 mindset:
Option A/B/C / 按鈕一 / Rule A?text-[13px])aria-labelrole 正確詳見 references/audit-checks.md。
chain .claude/skills/design-system-audit/references/principle-audit-protocol.md 做 4 子維 scoped 對 consumer code:
判斷 auto vs STOP 依 protocol 公式。修 consumer code 一致化 = AUTO;建議修 DS canonical 本身 = STOP 提議。
確認 audit target:file / folder / feature area。提問 user 若模糊。禁止掃整個 repo(失焦)。
7 個維度各自獨立 grep + code review。可 parallelize。
產出 report 表格:
| Dim | File:Line | Finding | Severity | Fix suggestion |
|-----|-----------|---------|----------|----------------|
| 1 Token | src/app/foo.tsx:42 | 硬寫 `#3b82f6` | P0 | 改 var(--primary) |
| 2 Layout | src/app/bar.tsx:87 | 自己寫 icon+title+desc 垂直堆疊 | P1 | 改用 `<Empty>` |
| 3 Component | src/app/baz.tsx:12 | icon-only Button 無 aria-label | P0 | 加 aria-label |
| ... |
類似 design-system-audit 的 triage checkpoint:
🔍 Audit 結果
P0(必修,無爭議):N 項
P1(批次修 + review):M 項
P2(需討論):K 項
先修 P0?還是全給 user 看?
詳見 references/report-template.md。
若 user 同意 fix,surgical 修復。每批(Dim 1 / Dim 2 / ...)一個 commit。
npx tsc --noEmit 通過對齊 CLAUDE.md 稽核 canonical Tier 1 stakeholder-gate:產品 UI 要給 stakeholder / end-user 看之前,code + visual 雙層都要過。Phase 1-4 是 code 層;本 Phase 補視覺層。
Input:Phase 4 verify 過關的產品 UI(screens / routes / embedded widgets)
Process:
npm run visual-audit -- --urls=<csv>(例:--urls=http://localhost:3000/inbox,http://localhost:3000/settings)npm run visual-audit -- --scope=component:<topic>snapshots//visual-audit skill):讀 snapshots/*.png,判斷設計合理性(視覺對齊 / 覆蓋限制 / 世界級對照 / typography hierarchy)Gate 規則:P0 有 → 停下修,不放給 stakeholder;P1 / P2 走跟 Phase 2 Report 同樣 user-decision 流程。
何時可跳:內部 UI(只給 engineer / admin 看,非 stakeholder / end-user)→ user 明示 skip,但建議跑一次 Layer A 抓 a11y P0。
為什麼 mandatory:code audit 對 + spec 對,視覺仍可能錯(對比不夠、overlay 疊到文字、跨 OS 捲軸跑版)——這類 bug 只有視覺層抓得到。產品給 stakeholder / user 看時 = stakeholder-visible artifact,必過 Tier 1 gate。
audit 完畢報告應含: