@qijenchen/design-system 0.1.0-beta.10 → 0.1.0-beta.13

package/ds-canonical/skills/new-component/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: new-component
+description: Create-phase workflow for building a new design-system component from scratch. Walks through 6 phases (近親 spec → Family 判定 → 7-dim spec → tsx → 3 stories → self quality-gate) with checkpoints, ensuring world-class discipline is applied *while building*, not discovered in review. Complements /component-quality-gate (review-phase gate). Invoke when user says「我要做新元件 X」「新增 X 元件」「create new X component」or is about to `mkdir packages/design-system/src/components/Xyz`.
+---
+
+# New Component 建立流程(create-phase workflow)
+
+## 存在意義
+
+`/component-quality-gate` 是 **review-phase** gate(元件做完後驗 45 項),但建 **create-phase** 沒 workflow guide → AI 每次從 CLAUDE.md 零散規則自己湊,容易漏規則、誤套 pattern。
+
+本 skill 填 create-phase 空缺:6 phase 帶著 AI 一步一步建元件,對齊 CLAUDE.md 所有規則(Layout Family / Props 命名 / Spec 7 維度 / Stories 真實業務場景 / visual audit),最後自動 chain `/component-quality-gate` 做 exit check。
+
+**跟 /component-quality-gate 互補**:create(本 skill)在元件沒寫前先指引;quality-gate 在元件寫完後驗收。兩者不重疊。
+
+## When to invoke
+
+- User 明說建新元件(「做一個 X」「新增 X 元件」)
+- AI 即將 `mkdir packages/design-system/src/components/Xyz/`
+- 建元件前的「先 plan 再建」需求
+
+**不 invoke 的情境**:
+- 改既有元件(小 variant / size prop 增加)→ 走 sync hook + `/component-quality-gate`
+- prototype 比稿階段的 exploration UI → 走 `/prototype`(exploration 不進 DS)
+- 重構既有元件(not from scratch)→ 走 `/component-quality-gate` review
+
+## Preconditions
+
+- User 已給出新元件的 **名字 + 大致用途**(否則先對話釐清,再 invoke)
+- 元件 folder 不存在於 `packages/design-system/src/components/`(真的是新的)
+- 已讀 CLAUDE.md(skill 會 re-ref 關鍵章節,但 session 整體已有 context 更好)
+
+## Workflow(6 phase + 多 checkpoint)
+
+### Phase 1 — 近親 spec 掃讀(不憑直覺發明)
+
+對齊 CLAUDE.md mindset #2 + `# 遇不確定時的協議` Step 2 + memory `feedback_proactive_5layer_pipeline.md`「5-step pre-check」(寫 tsx 前必含 CLAUDE.md SSOT 清單 + tsx 開頭「── 消費的 SSOT ──」段)。
+
+1. **識別 2-3 個近親元件**(同 family、同 pattern、同職責):
+   - 視覺相似?(例:新 `StatusChip` → 近親 `Tag` / `Badge` / `Chip`)
+   - 功能相似?(例:新 `MultiSelect` → 近親 `Select` / `Combobox`)
+   - 資料形態相似?(例:新 `TimeRangePicker` → 近親 `DatePicker.Range` / `TimePicker`)
+2. **完整讀近親 spec.md**,至少 2 個,抓:
+   - 它的 Layout Family 宣告
+   - API surface(props 命名 / 型別)
+   - 禁止事項(往往透露 gotcha)
+   - SSOT anchor(往哪指)
+3. **查世界級對照**:Polaris / Material / Atlassian / Ant / Apple HIG 有沒對應元件?**至少 2 個** DS 的做法,記 3 行筆記(naming / API / 視覺模式)。
+4. **查 baseline 狀況**:`ls packages/design-system/src/components/` 確認名字衝突;`grep` CLAUDE.md「失敗記憶索引」看有沒同類別的歷史 bug。
+
+### Checkpoint 1 — 定位 Proposal(STOP 點)
+
+回報 user:
+- 元件名稱(按 CLAUDE.md `# 命名與語言一致性` 三重 test)
+- 近親元件清單 + 跟本元件的異同一句話
+- 世界級對照 2 個(Ant Design 叫 X / Material 叫 Y)
+- **問 user**:「這個 positioning 對嗎?要不要改名 / 重 scope?」
+
+**User 點頭才進 Phase 2。** 定位錯的話在此階段轉向最便宜。
+
+### Phase 2 — Layout Family 判定
+
+對齊 CLAUDE.md `# 4-Family Layout Model`。
+
+**判斷流程**(照 CLAUDE.md 既有):
+1. 垂直列表裡? → Family 1(menu)/ Family 2(reading)
+2. 單行可點擊 pill? → Family 3(action trigger / data indicator sub-profile)
+3. 單行可編輯? → Family 4(Field control,視覺對齊 Family 1)
+4. 都不是? → Non-family(self-contained primitive OR composite multi-section,**必寫 rationale**)
+
+**輸出**:
+- Family 宣告一句話(「Family 4 — Field control」OR「Non-family,composite multi-section (toolbar + grid + tile)」)
+- 若 non-family → 寫 3-5 行 rationale:為什麼不是 1-4
+- 若 Family 1/2 → **必消費** `patterns/element-anatomy/item-anatomy` 的 `<MenuItem>` + slot components,不重寫 row 結構
+- 若 Family 3 → follow Button Pill Layout canonical
+- 若 Family 4 → follow field-controls.spec.md
+
+### Phase 3 — 寫 spec.md 7 維度(先 spec 後 code,spec 是 judgment home)
+
+對齊 `.claude/rules/spec-rules.md`。7 維度缺一不可(除非元件本質無該面向,寫「本元件無 X 狀態」):
+
+1. **定位**(positioning + 實作基礎 + Layout Family + 世界級對照)
+2. **何時用**(3-5 個情境,真實業務,不 generic)
+3. **何時不用**(用表:情境 / 改用 / 原因)
+4. **禁止事項**(❌ 列表,對應常見誤用)
+5. **相關 / SSOT pointer**(近親元件互相 link,ownership 明確)
+6. **空值呈現 / 驗證時機**(Field 家族必寫 / 非 Field 可簡答)
+7. **Loading / 無障礙**(async 場景的 state / a11y 預設)
+
+**Checkpoint 2**:spec 寫完,回報 user → 請 user 看 spec 判定 positioning 是否 lock in。改 positioning 比改 code 便宜得多。
+
+### Phase 4 — 寫 tsx(shadcn 結構 + cva + 對齊 spec)
+
+對齊 `.claude/rules/ui-development.md`「shadcn 元件規範」 + `.claude/references/cva-patterns.md`。
+
+1. **結構**:`forwardRef + cva + VariantProps + cn() + { Component, componentVariants } export`
+2. **cva 適用法**:className variant 用 cva;style prop variant 用 object map;結構 variant 用 conditional rendering(見 cva-patterns.md)
+3. **Props 命名**:按 `.claude/rules/ui-development.md`「元件 Props 命名」:
+   - 行為 → `onDismiss` / `onClose` / `onClear` / `onRemove`(語意分層,見 CLAUDE.md)
+   - Slot icon → `startIcon` / `endIcon`(type `LucideIcon`)
+   - Slot media → `avatar`(type `ReactNode`)
+4. **Token 消費**:Padding / icon size / hover bg / shadow 全走 token(見 `.claude/rules/ui-development.md` 三層分層)
+5. **禁止 shadcn compat alias**(`bg-popover` / `text-muted-foreground` 等)—— 用 direct token
+6. **Field 家族元件**:default `size="md"` 對齊 field-height family(見 `tokens/uiSize/uiSize.spec.md`)
+7. **cva defaultVariants 異動**:改之後必 grep 元件所有檔案同步三方(spec / docblock / anatomy story)
+
+### Phase 5 — 寫 3 stories(真實業務場景,對齊 /story-writing skill 規格)
+
+chain `/story-writing` skill(如果 user 沒自己啟,本 skill 自動走其規則):
+
+**Phase 5.0 — Trait 宣告**(2026-04-26 M19 ensure-canonical pipeline):
+
+寫 stories 前,在 spec.md frontmatter 宣告元件 traits(對齊 `category-templates.md` v2):
+
+```yaml
+---
+component: {Name}
+family: {1|2|3|4|self-contained}
+traits:
+  - hasVariants       # 若 cva 有 ≥ 2 visual variants
+  - hasSizes          # 若 cva 有 ≥ 2 sizes
+  - hasInteractiveStates  # 若有 hover/focus/disabled/loading
+  - isOverlay         # 若是 portal-rendered overlay
+  - isInputLike       # 若是 text/number field
+  - isSelectionMulti  # 若是 Checkbox/Radio 多選
+  - isSelectionSingle # 若是 Switch 單一 toggle
+  - isMatrixHeavy     # 若 token × size 正交視覺軸(Avatar/Skeleton)
+  - isStructural      # 若結構主導(DataTable/Steps/Tabs)
+  - isInternal        # 若 L3 building block
+---
+```
+
+**判斷法**:讀本元件 cva variants / 行為 → 對照 traits 表 → 列適用的。**scope-N/A 的 trait 在 spec.md「邊界案例 scope」段明寫 rationale**(例:「Toast `hasSizes=false`,單尺寸對齊 Sonner idiom」)。
+
+**Phase 5.1-5.3 — 三層 stories**:
+
+1. **`{name}.stories.tsx` 展示**:per Phase 5.0 declared traits → 對照 `category-templates.md` 衍生 required core stories(`hasVariants` → AllVariants / `hasSizes` → AllSizes / `isOverlay` → OpenSnapshot 等)。再加 1-2 真實業務 scenario(Jira / Stripe / Notion 過 earn-existence)。Hook `check_story_category.sh` write-time 攔不符 trait core。
+2. **`{name}.anatomy.stories.tsx` 設計規格**:5-story 標準(Overview + SizeMatrix + ColorMatrix + StateBehavior + Inspector)或合理 subset + rationale。
+3. **`{name}.principles.stories.tsx` 設計原則**(對齊 Polaris/Carbon/Ant canonical,2026-04-26):universal core ≥ 2 of {`WhenToUse` / `WhenNotToUse` / `Vs{Sibling}Rule` / `ContentGuidelines`}。do / don't 情境對照,每則 Rule title + Rule note + 範例。Hook `check_principles_canonical.sh` write-time 攔不符。
+
+**兩個 test**:
+- 「人」test — 遮標題 5 秒讀者看懂情境?
+- 「舉一反三」test — 讀者推得出自己產品怎麼用?
+
+### Phase 6 — Self quality-gate(exit check)
+
+**Mandatory**。chain `/component-quality-gate` 走 45 項 checklist + Phase 4.5 visual audit(Layer A + B)+ **Dim 27 code quality audit**(2026-04-24 新:`node scripts/code-quality-audit.mjs --scope=component:{Name} --check`,P0 violation 必 block)。對齊 CLAUDE.md 稽核 canonical Tier 1 stakeholder-gate:元件要 merge 前 code + visual + clean-code 三層過關。
+
+**如何 chain**:
+1. Invoke `/component-quality-gate` skill,以本元件為 scope
+2. 45 項全綠 + visual 過關才算 create-phase 完成
+3. 若 quality-gate 發現問題 → 回 Phase 3 / 4 / 5 對應階段修,再跑 quality-gate
+4. 通過 → 回報 user「元件 {Name} 建立完成,已過 create + review 雙 gate」
+
+## Non-goals
+
+- 不自動進入 `packages/design-system/src/components/`(explorations/ 才是實驗場;prototype 階段跑 `/prototype` skill)
+- 不替 user 決定 positioning(Checkpoint 1 必須 user 點頭)
+- 不跳過 spec(`.claude/rules/spec-rules.md`:先 spec 後 code,spec 是 judgment home)
+- 不省略 quality-gate(Phase 6 chain mandatory,merge 前必過)
+
+## References
+
+- `references/new-component-checklist.md` — 完整 6 phase checklist + 各項 CLAUDE.md pointer
+
+## 相關 skill
+
+- `/component-quality-gate` — review-phase gate,本 skill Phase 6 chain 進去(create/review 兩端互補)
+- `/story-writing` — Phase 5 chain 進去寫 stories
+- `/design-system-audit` — DS-wide audit(全 dim per design-system-audit SSOT,Phase 0 自建 baseline),不是 per-component

package/ds-canonical/skills/new-component/references/new-component-checklist.md

@@ -0,0 +1,85 @@
+# New Component 建立 checklist(每 phase 必過)
+
+本檔對應 `SKILL.md` 6 phase,每項可直接勾選。
+
+---
+
+## Phase 1 — 近親 spec 掃讀
+
+- [ ] 識別 2-3 個近親元件(同 family / pattern / 職責)
+- [ ] 完整讀至少 2 個近親 spec.md
+- [ ] 抓到 Layout Family 宣告、API surface、禁止事項、SSOT anchor
+- [ ] 查至少 2 個世界級 DS(Polaris / Material / Atlassian / Ant / Apple HIG)對應元件
+- [ ] `ls packages/design-system/src/components/` 確認名字無衝突
+- [ ] grep CLAUDE.md `# 失敗記憶索引` 查同類歷史 bug
+
+## Checkpoint 1 — 定位 Proposal
+
+- [ ] 元件名通過「命名三重 test」(既有語言 / 世界級 idiom / 跨元件無衝突,見 CLAUDE.md `# 命名與語言一致性`)
+- [ ] 報 user:元件名 / 近親 / 世界級對照 / positioning 一句話
+- [ ] User 點頭
+
+## Phase 2 — Layout Family 判定
+
+- [ ] 走 CLAUDE.md `# 4-Family Layout Model` 判斷流程
+- [ ] 若 Family 1/2 → 確認消費 `<MenuItem>` + slot components(不重寫 row 結構)
+- [ ] 若 Family 3 → follow `Button Pill Layout` canonical(見 button.spec.md)
+- [ ] 若 Family 4 → follow field-controls.spec.md
+- [ ] 若 Non-family → 寫 3-5 行 rationale 說明為什麼不是 1-4
+
+## Phase 3 — spec.md 7 維度
+
+- [ ] 定位(含 Layout Family + 實作基礎 + 世界級對照)
+- [ ] 何時用(3-5 真實業務情境)
+- [ ] 何時不用(表格:情境 / 改用 / 原因)
+- [ ] 禁止事項(❌ 清單)
+- [ ] 相關 / SSOT pointer(互相 link,ownership 明確)
+- [ ] 空值呈現 / 驗證時機(若不適用寫明文「本元件無 X」)
+- [ ] Loading / 無障礙(若不適用寫明文)
+- [ ] **Checkpoint 2**:spec 寫完停下報 user,lock in positioning
+
+## Phase 4 — tsx
+
+- [ ] 結構 shadcn + forwardRef + cva + VariantProps + cn()
+- [ ] cva 適用正確(見 `.claude/references/cva-patterns.md`;style prop / 結構性 variant 不硬塞 cva)
+- [ ] Props 命名按「是什麼」不按「在哪裡」(startIcon / endIcon / avatar / onDismiss / onClose / onClear / onRemove)
+- [ ] callback 命名分層正確(`.claude/rules/ui-development.md`「元件 Props 命名」 的 canonical)
+- [ ] Token 消費三層分層(chrome/layout-space / 元件內/Tailwind p-N / 精確幾何/calc)
+- [ ] Icon size 三層分層(row 走 RowSizeContext / Button 走 Button mapping / 一次性 inline size={n} 對齊 uiSize)
+- [ ] 無 shadcn compat alias(bg-popover 等)
+- [ ] 無硬色 / shadow-sm / 預設 typography class
+- [ ] `tsc --noEmit` 過
+- [ ] cva defaultVariants 正確(Field 家族 default md;其他按 spec 明示)
+- [ ] cva defaultVariants 改動 → 三方同步(spec / docblock / anatomy story)
+
+## Phase 5 — stories(3 個 .stories.tsx 檔)
+
+- [ ] `{name}.stories.tsx` 展示 3-5 真實業務情境(禁 Option A/B/C / 抽象代號 / 極端不現實)
+- [ ] `{name}.anatomy.stories.tsx` 含 Overview + SizeMatrix + ColorMatrix(若有) + StateBehavior + Inspector(或 subset + rationale)
+- [ ] `{name}.principles.stories.tsx` 含 do/don't Rule stories,每則 title + note + 範例
+- [ ] 「人」test 過:遮標題 5 秒能懂情境
+- [ ] 「舉一反三」test 過:讀者推得出自己產品怎用
+- [ ] hook `check_story_anatomy.sh` 未觸發 block(無手刻 list item / label Button dismiss / 自刻 overlay)
+- [ ] Storybook title path 正確(`Design System/Components/{Name}/{中文子頁}` 或 `Internal/{Name}/...`)
+
+## Phase 6 — Self quality-gate chain
+
+- [ ] Invoke `/component-quality-gate` skill
+- [ ] 45 項全綠
+- [ ] Phase 4.5 visual audit Layer A 過(0 contrast / 0 geometry violation)
+- [ ] Phase 4.5 Layer B AI 視覺判斷過(或有 documented rationale)
+- [ ] 回報 user「元件 {Name} 建立完成,已過 create + review 雙 gate」
+
+---
+
+## 常見失敗 → 回哪 phase 修
+
+| Quality-gate finding | 回 phase |
+|---|---|
+| Spec 七維度漏項 / positioning 不明 | Phase 3 |
+| cva 結構錯 / 硬色 / token leak | Phase 4 |
+| Stories 用 Option A/B/C / 虛構情境 | Phase 5 |
+| Layout Family 判錯 / 不消費 MenuItem | Phase 2 |
+| 名字跟既有元件撞語義 | Phase 1(改名後全回 Checkpoint 1) |
+| Visual audit contrast 不過 | Phase 4(改 token),重跑 Phase 6 |
+| Visual audit geometry fail(等高 / 對稱 padding / gap 錯) | Phase 4(改 tsx 或 assertion rationale),重跑 Phase 6 |

package/ds-canonical/skills/performance-audit/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: performance-audit
+description: Performance audit for design-system components and product UI. Checks render count, unnecessary re-renders, memoization gaps, bundle size impact, useEffect chains, context thrashing. Invoke when user says「這元件效能如何」「為什麼很卡」「bundle 變大」「re-render 太多」, auto-invoked by `/component-quality-gate` Phase 4.5 (advanced mode) and `/design-system-audit` Dimension D3.
+---
+
+# Performance Audit — 元件效能稽核
+
+## 存在意義
+
+現有 `/design-system-audit`(全 dim per design-system-audit SSOT,code/spec 層)+ `/visual-audit`(pixel 層)**都不看效能**。render 次數過多、context 亂鋪、useEffect 鏈條過長這類 bug:
+- tsc 過、eslint 過、視覺正常
+- production 卡
+- 日常 dev 看不出來,到 stakeholder demo 才爆
+
+本 skill 作為稽核 6 維度的 **D3 元件效能** canonical home。
+
+## 觸發時機(對齊 CLAUDE.md 稽核 canonical)
+
+| 情境 | 模式 | 本 skill 跑什麼 |
+|------|------|----------------|
+| 新元件 merge 前 | 進階強制 | 全面(render count / memo / bundle) |
+| 元件新功能 | 進階強制 | 全面 scoped to 新 prop / variant |
+| 產品 demo 前 | 進階強制 | scoped to URL(常用頁 route) |
+| 日常 dev | 高效 | tsc pass + bundle diff 門檻即可 |
+| Release cut | 進階 + 全 DS scope | 全 DS render / memo / bundle 全跑 |
+
+## Preconditions
+
+- 元件 folder 存在於 `packages/design-system/src/components/{Name}/`
+- `node_modules` 已安裝
+- Storybook 可啟動(用於 render-count 測量)
+
+## Workflow
+
+### Phase 0 — Scope 判定(一致性類必先全掃)
+
+- 若 scope = 單元件 → 走 Phase 1-3 對該元件
+- 若 scope = 全 DS / URL → **先全掃列出所有 hot path**(render 過多元件 / bundle 大元件 / context 亂鋪元件),Phase 1-3 按 impact 排序逐一 audit
+
+### Phase 1 — Render & re-render
+
+查 4 項:
+1. **Unnecessary re-render**:consumer 改 prop / state 時,本元件是否 re-render?`React.memo` 是否需要?
+2. **Inline 物件 / 函式 prop**:`style={{ ... }}` / `onClick={() => ...}` 每 render 造新 ref → child memo 失效
+3. **Context 粒度**:`<ThemeProvider value={theme}>` 若含頻繁變動 field(e.g. `openMenuId`)→ 整個 subtree 重渲。Context 必切分粒度或用 selector
+4. **Key 穩定性**:list items 用 `key={index}` 導致無意義 remount
+
+**工具**:
+- React DevTools Profiler record → 看 flame graph
+- `why-did-you-render` dev dep 觸發警告(未來可加)
+- 直接 grep pattern(inline style / arrow onClick)
+
+### Phase 2 — Memoization / dependency
+
+查 3 項:
+1. **useMemo / useCallback dep array**:遺漏 dep(stale closure)/ 多 dep(無效 memo)
+2. **useEffect dep array**:同上;特別注意 object / array dep(每 render 新 ref → 無限迴圈或無效 cleanup)
+3. **Computed value in render**:重計算 heavy op(sort / filter / 轉換) → 必 `useMemo`
+
+### Phase 3 — Bundle size
+
+查 3 項:
+1. **Direct heavy import**:`import * as Icons from 'lucide-react'`(全庫入 bundle) vs `import { Check } from 'lucide-react'`
+2. **Lazy-loadable portion**:Dialog / Sheet / Coachmark 等 rare-use overlay,可 `React.lazy` 減首屏
+3. **Duplicate dep**:`framer-motion` vs `motion/react` / 不同版本 react-day-picker 等
+
+**工具**:
+- `npx vite build --report`(vite bundle visualizer)
+- bundle-size CI check(未來可加)
+
+### Phase F — Report(必 STOP,對齊分權 canonical)
+
+產出:
+
+```markdown
+# Performance Audit — {Scope} — {YYYY-MM-DD}
+
+## Summary
+- Render issues: N
+- Memoization gaps: M
+- Bundle impact: K KB
+
+## Findings(按 impact 排序)
+### P0: {title}
+- 位置: {file:line}
+- 現況: {render count / bundle contribution}
+- 建議: {具體修法}
+- 是 canonical 修實作(auto),還是原則待討論(STOP)?
+
+## 提議討論(待 user sign-off)
+- {若發現 canonical 本身有問題,列於此,不自改}
+```
+
+**STOP 點**:report 寫完**不自動修**。分權對齊 CLAUDE.md `# 稽核 canonical`(內含「Audit-vs-execute 分權」inline rule)。
+
+## Non-goals
+
+- 不改 code / spec(純 read-only report)
+- 不做 micro-benchmark(10ms 以下差異不 report,噪音太多)
+- 不處理 network / backend(純前端 render / bundle)
+
+## 相關
+
+- `.claude/skills/design-system-audit/SKILL.md` — 全 dim 統籌(per design-system-audit SSOT);本 skill 是 D3 補位
+- `.claude/skills/visual-audit/SKILL.md` — pixel 層(D5)
+- `.claude/skills/ux-audit/SKILL.md` — UX 行為層(D4)
+- `.claude/skills/component-quality-gate/SKILL.md` — Phase 4.5 進階模式 chain 本 skill

package/ds-canonical/skills/product-ui-audit/SKILL.md

@@ -0,0 +1,230 @@
+---
+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 6 dimensions. Invoke via /product-ui-audit when user says「audit 這個 UI」「檢查 X feature 用對 DS 嗎」「這段 code 符合設計原則嗎」,or auto-invoked by /prototype Phase 3.5 gate.
+---
+
+# Product UI Audit Workflow
+
+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 的地方」)。防止:
+
+- 元件亂用(wrong variant / missing props / incorrect composition)
+- 設計原則亂用(placeholder 文案 / 憑直覺創造 pattern / Mindset 違反)
+- Token 逃逸(硬寫 hex / shadcn alias 回流 / shadow-sm 繞過 elevation)
+- 幾何 bug(flex gap token 被 overflow 吃、slot box 不一致)
+- A11y 缺口
+
+## When to run
+
+**明確觸發(直接 invoke)**:
+- User 說「audit 這個 UI」「audit X feature」「檢查 /src/app/xxx」
+- User 說「這段 code 符合設計原則嗎」「DS 用對了嗎」「有元件亂用嗎」
+- `/prototype` Phase 3.5 自動 invoke(audit `src/explorations/{topic-slug}/`)
+- PR review 前自我檢查
+
+**不觸發**:
+- 要 audit DS 本身 → 走 `/design-system-audit`(不同 scope)
+- 要 audit token 定義 → 走 `design-system-audit`
+- 只要求補 stories → 直接補,不需 audit
+
+## 生態位
+
+```
+  /design-system-audit   audit DS 本身(設計系統內部)
+  /product-ui-audit      audit consumer UI code(本 skill)
+  /prototype             呼叫本 skill 作 Phase 3.5 gate
+  /delivery-handoff      只在產品交付前執行(產 handoff 文件)
+```
+
+## Preconditions
+
+- User 指定 audit target(file path / folder / feature area)
+- Target 是 consumer 層 UI code(`src/app/**` / `src/explorations/**` / `src/pages/**` / `src/features/**`等 — **不掃 `packages/design-system/src/`**)
+- CLAUDE.md 全讀(6 維 audit 都依此為基準)
+
+---
+
+## 6-Dimension Audit
+
+每個 dimension 獨立檢查,產出 findings。詳細 grep pattern + rule 見 `references/audit-checks.md`。
+
+### Dim 1 — Token 紀律(token hygiene)
+
+- 硬寫 hex / rgb / rgba / hsl 色值
+- shadcn compat alias(bg-popover / text-muted-foreground / bg-accent / bg-destructive / bg-background / bg-card / border-input / text-primary-foreground / text-accent-foreground / text-card-foreground / text-popover-foreground)
+- Tailwind default shadow(shadow-sm / md / lg / xl / 2xl / inner)— 應走 elevation token
+- Tailwind v4 `[--foo]` shorthand 靜默失效
+- 硬寫 px 值當該用 token(`w-[48px]` 應改 token)
+
+此維對齊既有 `check_token_hygiene.sh` hook 的 4 項 + 擴充硬色值 / 硬 px 檢查。
+
+### Dim 2 — Layout primitive 消費(per CLAUDE.md 清單)
+
+掃是否正確消費既有 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 |
+
+### Dim 3 — 元件使用正確性
+
+- Button / Input / Select 等 variant / size / props 組合合理
+  - icon-only 有 `aria-label`
+  - Button primary 沒堆疊(一個 row 一個 primary)
+  - Input 外有 Field wrapper(非 standalone input)
+- Composition 正確
+  - Popover 不放互動破壞(Dialog trigger in Popover content 避免)
+  - Accordion / Tabs / Carousel 不巢狀
+- Radix API 用對
+  - Dialog 有 DialogTitle / DialogDescription for a11y
+  - DropdownMenu 不當 Select 用
+
+### Dim 4 — Mindset adherence
+
+對齊 CLAUDE.md 5 條 mindset:
+
+- **M1 對標世界級**:新 pattern 有對標備註? 或找得到對應既有元件?
+- **M2 不憑直覺發明**:新數值(gap / padding / font-size)前有 grep 既有?
+- **M3 改一處看三處**:若改 DS 的 cva defaultVariants,spec / docblock / anatomy 三方同步?
+- **M4 真實業務場景**:stories / examples 用真實場景 (Jira / Stripe / Notion...)?無 `Option A/B/C` / `按鈕一` / `Rule A`?
+- **M5 猶豫就問**:code 裡有 TODO-未確認留白?
+
+### Dim 5 — 視覺幾何(Mindset #1 視覺擴充 + CLAUDE.md「同 flex 列互動 slot 幾何鐵律」)
+
+- 同 flex 行的互動 slot box 尺寸一致(例:FileItem status / delete 都 h-field-sm)
+- hover-bg / ring / focus outline 不溢出 box 吃 gap token
+- padding 對稱正確
+- Typography tier 正確(text-body / text-caption / etc.,不自造 `text-[13px]`)
+
+### Dim 6 — A11y
+
+- icon-only 元件有 `aria-label`
+- interactive element `role` 正確
+- Dialog / Popover / Sheet 有 title + description
+- keyboard navigation 可用(Tab / Enter / Esc)
+- color contrast(不用純 color 傳 state — 要 icon / label 配合)
+
+詳見 `references/audit-checks.md`。
+
+### Dim 7 — D6 設計原則自檢(consumer 是否牴觸 DS canonical)
+
+chain `.claude/skills/design-system-audit/references/principle-audit-protocol.md` 做 4 子維 scoped 對 consumer code:
+
+- **D6a 合理性**:consumer 自己的設計判斷是否有 rationale(為什麼這樣用 DS 元件)
+- **D6b 一致性**:跨 feature 同概念處理一致(同 team 兩頁面 dismiss 不應用不同方式)
+- **D6c 無矛盾**:consumer 實作是否牴觸 DS spec 聲明(例:用 Button 作 dismiss 明顯違 item-anatomy SSOT)
+- **D6d 完整性**:state 覆蓋(error / loading / empty)
+
+判斷 auto vs STOP 依 protocol 公式。修 consumer code 一致化 = AUTO;建議修 DS canonical 本身 = STOP 提議。
+
+---
+
+## Workflow
+
+### Phase 0 — Scope
+
+確認 audit target:file / folder / feature area。提問 user 若模糊。禁止掃整個 repo(失焦)。
+
+### Phase 1 — Parallel 6-dim audit
+
+6 個維度各自獨立 grep + code review。可 parallelize。
+
+### Phase 2 — Report
+
+產出 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 |
+| ... |
+```
+
+### ⚠️ Checkpoint 1 — Triage & fix decision
+
+類似 design-system-audit 的 triage checkpoint:
+
+```
+🔍 Audit 結果
+
+P0(必修,無爭議):N 項
+P1(批次修 + review):M 項
+P2(需討論):K 項
+
+先修 P0?還是全給 user 看?
+```
+
+詳見 `references/report-template.md`。
+
+### Phase 3 — Fix(optional)
+
+若 user 同意 fix,surgical 修復。每批(Dim 1 / Dim 2 / ...)一個 commit。
+
+### Phase 4 — Verify
+
+- `npx tsc --noEmit` 通過
+- re-run 本 skill(縮窄到原 findings)確認 zero regression
+
+### Phase 5 — Visual audit(stakeholder-gate,mandatory on stakeholder-visible work)
+
+對齊 **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**:
+1. 確認 user 有提供 **URL 清單**(產品 app routes)或 **Storybook scenario id**(若產品 stories 在 Storybook):
+   - URL mode:`npm run visual-audit -- --urls=<csv>`(例:`--urls=http://localhost:3000/inbox,http://localhost:3000/settings`)
+   - Storybook mode:`npm run visual-audit -- --scope=component:<topic>`
+2. **Layer A mechanical**(auto):WCAG 對比度 + DOM 幾何 assertion + retina screenshot → `snapshots/`
+3. **Layer B AI judgement**(chain `/visual-audit` skill):讀 `snapshots/*.png`,判斷設計合理性(視覺對齊 / 覆蓋限制 / 世界級對照 / typography hierarchy)
+4. Violation 分級:
+   - Contrast AA 不過 → **P0**(a11y 強制)
+   - Geometry assertion fail → **P0**(機械規則違反)
+   - Layer B AI 視覺判斷 finding → 按嚴重度 P0 / P1 / P2
+
+**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 完畢報告應含:
+1. **Scope**:audit 了什麼(path / file 數量)
+2. **Summary**:per dimension 的 pass/fail 數
+3. **Findings table**:具體 file:line + severity + fix
+4. **Recommendations**:P0 優先 / 建議修順序
+5. **Next step**:等 user Checkpoint 1 決策
+
+---
+
+## Non-goals
+
+- 不 audit DS 本身(走 /design-system-audit)
+- 不改 user 未同意的 P1/P2(僅 P0 可自動修,需 user 決策 P1+)
+- 不 audit 業務邏輯正確性(本 skill 管 UI / DS consumption / design principles,不管 data flow 對不對)
+- 不 replace code review(本 skill 是 pre-review self-check,不是 final QA)
+
+## Common failure modes
+
+- **Scope 太廣**:掃整個 repo 導致 findings 爆量,triage 崩潰 → 限制 scope 到 feature / folder
+- **Dim 間互相矛盾**:Dim 2 建議用 Empty 但 Dim 3 說 Button 該在某處 — surface 而非自己選
+- **P0/P1 分類偏誤**:把明確 bug 當 P1 / 把 style preference 當 P0 — 嚴格按 audit-checks.md 分類
+- **AI 自行修 P2**:違反 checkpoint 精神,每個 P2 都是設計決策
+
+## References
+
+- [references/audit-checks.md](references/audit-checks.md) — 6 維度具體 grep pattern + rule
+- [references/common-misuses.md](references/common-misuses.md) — 常見元件誤用 negative example 庫
+- [references/report-template.md](references/report-template.md) — P0/P1/P2 severity 分類 + report 格式