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

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

@@ -0,0 +1,130 @@
+---
+name: ux-audit
+description: UX behavior audit for design-system components and product UI. Checks keyboard navigation, focus management, ARIA correctness, animation timing, interaction canonical (hover/click/drag/zoom), error/loading states, empty states. Invoke when user says「鍵盤用不了」「focus 跑飛」「動畫怪怪的」「無障礙檢查」, auto-invoked by `/component-quality-gate` Phase 4.5 (advanced mode) and `/design-system-audit` Dimension D4.
+---
+
+# UX Audit — UX 行為稽核
+
+## 存在意義
+
+現有 `/design-system-audit`(code/spec)+ `/visual-audit`(pixel)+ `/performance-audit`(render)**都不看行為**。interaction canonical、keyboard nav、focus trap、animation timing 這類 bug:
+- 視覺正常 / code 正常 / 效能正常
+- **Keyboard only user 完全卡關** / screen reader 讀不到 / focus 不回到 trigger / zoom wheel 跳大步
+
+本 skill 是稽核 6 維度的 **D4 UX 行為** canonical home。
+
+## 觸發時機(對齊 CLAUDE.md 稽核 canonical)
+
+| 情境 | 模式 | 本 skill 跑什麼 |
+|------|------|----------------|
+| 新元件 merge 前 | 進階強制 | 全面(kb / focus / ARIA / animation / interaction) |
+| 元件新功能 | 進階強制 | scoped to 新 interaction 路徑 |
+| 產品 demo 前 | 進階強制 | 全流程 keyboard-only walkthrough |
+| 日常 dev | 高效 | 主要 kb path 手動過一次 |
+| Release cut | 進階 + 全 DS | 全 DS 的 a11y / interaction 全掃 |
+
+## Preconditions
+
+- 元件 folder 存在於 `packages/design-system/src/components/{Name}/`
+- Storybook 可啟動(用於互動驗證)
+- 若稽核產品頁:URL 可訪問
+
+## Workflow
+
+### Phase 0 — Scope 判定
+
+- 單元件 scope → Phase 1-4 對該元件
+- 全 DS / URL scope → **先全掃列 interactive 元件清單**,按 interaction 複雜度(overlay > form > row > leaf)排序逐一 audit
+
+### Phase 1 — Keyboard navigation
+
+查 7 項:
+1. **Tab order**:DOM order = 視覺 reading order?`tabIndex` 不濫用(`tabIndex > 0` 禁用)
+2. **Focus visible ring**:所有 tabbable 元素 focus 有清楚 ring(用 `focus-visible` 非 `focus`)
+3. **Activation key**:Button/Link 回應 Enter + Space;menuitem / checkbox / radio 有特定 key 規則
+4. **Arrow key navigation**:list / menu / tabs / segmented control 在 group 內用方向鍵,不用 Tab
+5. **Escape 關閉 overlay**:Dialog / Popover / Sheet / DropdownMenu 按 Esc 關閉
+6. **Focus trap**:modal overlay 內 focus 不跑出 modal 外
+7. **Focus restore**:overlay 關閉後 focus 回 trigger
+
+### Phase 2 — Focus management(across state transitions)
+
+查 4 項:
+1. **Route change / async load**:新內容載入,focus 應指向新內容開頭(main landmark / first heading)
+2. **Error / validation**:form 送出驗證失敗,focus 應回第一個 invalid field + screen reader 讀 error
+3. **Dynamic content**:可折疊 section 展開後,focus 應維持在 trigger(非跳到內容)
+4. **List item removal**:刪除 item 後 focus 應移到**相鄰** item(不跳到文件頂)
+
+### Phase 3 — ARIA correctness
+
+查 6 項:
+1. **role** 正確:`role="button"` on <div> / 正確使用 `role="dialog"` / `role="menu"` / `role="grid"`
+2. **aria-label / aria-labelledby**:icon-only button 必有 aria-label;icon + text 不重複宣告
+3. **aria-expanded / aria-haspopup**:有 overlay 的 trigger 必宣告
+4. **aria-selected / aria-checked / aria-pressed**:狀態元件必正確 sync
+5. **aria-live**:動態訊息(validation / toast)用 `aria-live="polite"` 或 `"assertive"`
+6. **aria-hidden**:裝飾 icon 必 `aria-hidden`;隱藏內容不能 keyboard focus
+
+### Phase 4 — Animation / interaction canonical
+
+查 5 項:
+1. **Animation duration**:< 200ms(micro)或 200-400ms(macro);超過 400ms 主畫面 → 可能 block 輸入
+2. **Reduce-motion respect**:`@media (prefers-reduced-motion: reduce)` 下動畫減到 0 或極短
+3. **Wheel zoom step 細緻**:> 10% 離散 = 非世界級(對齊 Figma / Preview.app ~3-5%)
+4. **Hover delay**:tooltip / hover-card 的 open delay(700ms for tooltip, 500ms for hover-card per DS canonical)
+5. **Drag / pan**:pointer capture 正確;release on blur
+
+### Phase 5 — Data / state coverage 五態(2026-04-24 擴充,補 24-checklist #23 edge case gap)
+
+查 5 項 + null-safety + rapid-interaction:
+
+1. **Null-safety**:`null / undefined` label/value/children 不 crash(e.g. `{label}` 為 undefined render 空字串,不 `Cannot read properties of undefined`);空 array `.map()` 不 crash;emoji / 超長單字 / RTL 字元不爆版
+2. **Empty**:顯示 `<Empty>` 或對應 placeholder,非 blank;empty 有 CTA 讓使用者知道下步
+3. **Loading**:視語境用 CircularProgress / Skeleton / ProgressBar;aria-busy 宣告;**不阻斷可編輯狀態**(Input loading 仍可打字 per spec);**rapid-click / double-submit 有防護**(button loading 期間 disabled OR 靠上游 idempotent)
+4. **Error**:用 DS `<Notice>` 或 inline `<FieldError>`;配合 aria-live 通知 AT;error message 不吞(e.g. async rejection 有 fallback UI 非 silent swallow)
+5. **Success**(新加):成功 state 有視覺確認(toast / inline checkmark / state transition),讓使用者知道動作 landed,非 silent success
+
+**Edge case corollary**(現實髒資料):
+- Children 為 `null` / 為空 array / 元素數量極大(超 50 筆)
+- Option 重複 id / selected option 被移除後仍保留 value(stale selection)
+- disabled 時仍收到外部 value 更新(controlled forced update)
+- 從 uncontrolled 中途變 controlled(React warning 必出,或元件明文不支援)
+- Modal 關閉瞬間 async 回調仍 setState(unmount 後 setState warning)
+
+### Phase F — Report(必 STOP,對齊分權 canonical)
+
+產出:
+
+```markdown
+# UX Audit — {Scope} — {YYYY-MM-DD}
+
+## Summary
+- Keyboard: PASS / N fails
+- Focus: PASS / M fails
+- ARIA: PASS / K fails
+- Animation: PASS / L fails
+- Three states: PASS / P fails
+
+## Findings(按 severity 排序)
+### P0(完全 block a11y)
+### P1(嚴重影響 UX)
+### P2(建議改善)
+
+## 提議討論(待 user sign-off)
+- {若發現 DS canonical 本身有問題,列於此,不自改}
+```
+
+**STOP 點**:report 寫完**不自動修**。分權對齊 CLAUDE.md `# 稽核 canonical`(內含「Audit-vs-execute 分權」inline rule)。
+
+## Non-goals
+
+- 不改 code / spec(純 read-only report)
+- 不做視覺稽核(走 `/visual-audit`)
+- 不做 code-level audit(走 `/design-system-audit`)
+
+## 相關
+
+- `.claude/skills/design-system-audit/SKILL.md` — 全 dim 統籌(per design-system-audit SSOT);本 skill 是 D4 補位
+- `.claude/skills/visual-audit/SKILL.md` — pixel 層(D5)
+- `.claude/skills/performance-audit/SKILL.md` — 效能層(D3)
+- `.claude/skills/component-quality-gate/SKILL.md` — Phase 4.5 進階模式 chain 本 skill

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

@@ -0,0 +1,245 @@
+---
+name: visual-audit
+description: Pixel-level visual audit for design-system components based on user-provided screenshots. Catches bug classes that code/spec audits cannot see — asymmetric padding / broken overlay positioning / gap-eaten-by-hover-bg / baseline misalignment / overflow indicator obscuring content / wrong zoom step / dark-mode token mismatch. Requires a screenshot to run; refuses to proceed on guesses. Invoke via /visual-audit when user says「視覺對齊不對」「排版有問題」「gap 好像錯了」「看起來歪了」or uploads a Storybook screenshot asking「這樣對嗎」,auto-invoked by `/design-system-audit` Phase 3 (post-fix visual verify) and `/component-quality-gate` Ship phase.
+---
+
+# Visual Audit — screenshot-based pixel-level 稽核
+
+## 存在意義
+
+現有 `/design-system-audit`(全 dim per design-system-audit SSOT)+ `/product-ui-audit`(6 dim)**全部在 code / spec 層**。code 對、spec 對,**視覺仍可能錯**——這類 bug 在專案歷史反覆出現:
+
+- **DatePicker** 四邊邊距不對稱(左右不等 12px)、箭頭按鈕到容器頂距離 ≠ 最後一排日期到容器底距離
+- **Badge** 疊 Button 距離離譜(overlay offset 寫死 px 非 token)
+- **Avatar hover namecard** 的 list item 結構視覺跑掉
+- **Carousel** prev/next 箭頭覆蓋 content
+- **Rating** 星星有多餘邊框
+- **Image viewer** 滾輪縮放跳大步(對標 Figma 該每 notch ~1.1×)
+- **Button 群 gap** 被 hover bg overflow 吃掉(CLAUDE.md 有「同 flex 列互動 slot 幾何鐵律」但缺視覺 audit gate 鎖住)
+- **FileViewer 工具列** dark mode 切換後對比跑掉
+- **FileUpload / FileItem** 沒 fill container
+
+這些 bug 的共通點:`cva` 對、token 對、spec 對,但是消費組合後**實際 render 的 pixel 關係錯**。code audit 無視,只能靠視覺稽核。
+
+## 兩層架構 + state coverage canonical
+
+**Layer A mechanical**(`npm run visual-audit`):截圖 + WCAG + geometry。**Layer B AI**(本 skill):合理 / 一致 / 世界級對照。**Workflow**:`npm run visual-audit` → `/visual-audit` 讀 `snapshots/report.json`。詳 → [`references/audit-architecture.md`](references/audit-architecture.md)(兩層架構 + hover / focus-visible / play() coverage roadmap)。
+
+## Skill 生態位
+
+```
+/design-system-audit    全 dim 深度 audit(per design-system-audit SSOT,code/spec 層,Phase 0 自建 baseline)
+/product-ui-audit       consumer UI 對 DS 消費的 6 dim audit(code 層)
+/visual-audit           pixel-level 視覺 audit(本 skill,需 screenshot)
+/component-quality-gate  合入 DS 前的 45 項 checklist(Ship phase 可 chain 本 skill)
+```
+
+**關鍵切分**:visual-audit 只看 pixel,**不讀 code / 不改 code**。code / spec / cva 的事全部歸前兩 skill;視覺幾何對齊 / overlay 定位 / baseline / typography vertical rhythm 等「眼睛看得到、mechanical 量得出」的事才是本 skill scope。
+
+## When to invoke
+
+**明確觸發(直接 invoke)**:
+- User 說「視覺對齊不對」「排版歪了」「gap 好像錯」「4 邊邊距不對稱」「dark mode 看起來怪」
+- User 上傳 Storybook screenshot 配問題:「這樣對嗎」「能看出哪裡錯嗎」
+- User 指名元件 + 上傳圖:「audit DatePicker 的視覺」
+
+**自動觸發(chain from other skills)**:
+- `/design-system-audit` Phase 3 code/spec 修完後,若 user 要求 visual verify
+- `/component-quality-gate` Phase 4 Ship 階段,元件即將 merge 進 DS 前
+
+**不觸發**:
+- 要改 spec / cva / token → 走對應 code/spec skill,不是視覺 audit
+- 沒有 screenshot → **本 skill 拒跑**(見 Preconditions)
+- 只要看一眼順不順 → 不做 audit(這不 mechanical)
+
+## Preconditions(硬規則)
+
+**本 skill 在下列任一缺失下拒跑,回報 user 補齊後再 invoke**:
+
+1. **screenshot 缺失** — user 未上傳 Storybook 或元件實際 render 的截圖
+2. **audit target 未明** — 沒指定要稽核哪個元件 / 哪個 story / 哪個頁面
+3. **容器尺寸 / viewport 未知** — screenshot 沒附上容器寬度 / viewport size / 元件 size prop,無法 mechanical 量
+4. **token 聲明未知** — 該元件 spec 沒宣告該看哪些 token(本 skill 不推測,只比對)
+
+**拒跑回報範例**:
+
+```
+本 skill 需要以下資訊才能跑,目前缺:
+- [x] screenshot(Storybook 或實際 render)
+- [ ] 稽核 target(哪個元件 / 哪個 story 或 URL)
+- [ ] 容器 / viewport 資訊(container width / density / theme)
+
+補齊後請 re-invoke /visual-audit,不要讓我用猜的跑 audit。
+```
+
+**絕不**在資訊不足下憑感覺判斷——「看起來有點歪」不是 audit,是直覺。本 skill 產出必須全部是 mechanical 可驗證的結論。
+
+---
+
+## 涵蓋的視覺面向(13 項 checklist)
+
+完整 checklist(每項的「怎麼量」「合格標準」「refer 的 DS 規則 / token」)見 [references/visual-checklist.md](references/visual-checklist.md)。以下是摘要(每項 ≤ 2 行):
+
+| # | 面向 | 核心檢查 |
+|---|------|---------|
+| 1 | **4 邊邊距對稱** | 容器 top / right / bottom / left padding 實測值相等(除明文 asymmetric spec 外) |
+| 2 | **垂直對稱(to-top ↔ to-bottom)** | 最外層 element 到容器頂 = 最內層 element 到容器底(DatePicker 箭頭 vs 最後排日期) |
+| 3 | **水平 gap 實際值 == gap token 宣告值** | hover bg / ring / focus outline 不可溢出 box 吃掉宣告 gap(CLAUDE.md「同 flex 列互動 slot 幾何鐵律」) |
+| 4 | **Overlay 定位(badge / popover / hover-card)** | anchor-offset / side-offset 對稱;不覆蓋 anchor 內容 |
+| 5 | **Typography baseline 對齊** | icon 與同行 text 的 baseline 對齊(非 geometric center 誤植) |
+| 6 | **Icon ↔ text gap 一致** | 同類型 row 裡所有 icon-to-text 距離相等 |
+| 7 | **容器寬度 fill** | FileUpload / FileItem / Empty 等 block-level 元件是否 100% fill container(非內縮) |
+| 8 | **同 row field 高度對齊** | Input / Select / Button 並排時高度相同(`--field-height-md` = 36px) |
+| 9 | **跨 OS 一致 scrollbar** | 橫向 scrollbar 是否是 ScrollArea(避免 macOS 隱藏 / Windows 吃寬度) |
+| 10 | **Zoom / step 幅度** | 滾輪縮放 step ≈ 1.1×–1.25×(對標 Figma);不可跳大步(如 2×) |
+| 11 | **Dark mode 對比 / token 聯動** | 亮暗切換後 fg / bg / border / shadow 全部 token 對應;FileViewer 工具列永遠 dark mode |
+| 12 | **Overflow indicator 遮擋** | fade mask / 箭頭 button 不可遮到可讀資訊 |
+| 13 | **箭頭按鈕定位(Carousel / Image viewer)** | prev / next 箭頭不覆蓋 content;與邊緣距離對稱 |
+
+**世界級 benchmark 對照**(每項對齊的外部 DS)見 [references/world-class-benchmarks.md](references/world-class-benchmarks.md)。
+
+---
+
+## Workflow
+
+### Phase 0 — Setup + 拒跑 gate
+
+1. 讀 CLAUDE.md 完整(最新 token / 最新 layout primitive 規則)
+2. 檢查 user 是否提供 4 項必要資訊(見 Preconditions):
+   - screenshot
+   - audit target(元件 / story / URL)
+   - 容器 / viewport 資訊
+   - 該元件對應的 spec.md path
+3. **任一缺失 → 停下,按 Preconditions 範例回報,不 proceed**
+4. 讀該元件的 `{name}.spec.md`——記下 spec 宣告的 token 值(e.g.「field-height-md = 36px」「gap-2 = 8px」「layout-space-loose = 16px」),作為 mechanical 對照基準
+5. Create TaskList entries(13 個 checklist item 各一)
+
+### Phase 1 — 逐項 checklist(13 面向 mechanical 量測)
+
+對 screenshot 逐項走 [references/visual-checklist.md](references/visual-checklist.md)。每項執行:
+
+1. 開對應章節,照「怎麼量」的指引
+2. 用 image reading 讀 pixel 距離(screenshot 的座標或尺寸)
+3. 比對該項「合格標準」(通常是 token 值或 ratio)
+4. 記錄結果之一:
+   - `PASS` — 實測值 == spec 宣告值(或 ratio 在容差內)
+   - `FAIL` — 實測值偏離,記下**實測值 / 預期值 / 差異 / 對應 DS 規則**
+   - `無法判定` — screenshot 解析度 / 角度不夠量,記下**需要補什麼**
+
+**大原則**:
+- **不寫主觀描述**(「看起來鬆散」「感覺歪」不算 audit 結論)——只寫可 mechanical 驗證的數字 / ratio
+- **不推測 code**(「應該是 cva size 錯」不是本 skill 結論;code 的事走 `/design-system-audit`)
+- **不修 code**(本 skill 只報告,不 Edit 任何檔)
+- **超出 checklist 的視覺問題** → 記為 `額外觀察`,附 screenshot 座標 + 描述,交 user 決定要不要升級為 checklist 項
+
+### Phase 2 — 輸出 report(固定格式)
+
+產出檔案路徑:
+
+```
+.claude/skills/visual-audit/output/{YYYYMMDD}-{component}-visual-audit.md
+```
+
+**檔名規則**:同一天同元件多次跑 → 加 `-v2` / `-v3`。`{component}` 用 kebab-case(對齊專案慣例),例:`20260421-date-picker-visual-audit.md`。
+
+### Report 格式(嚴格)
+
+```markdown
+# Visual Audit — {Component} — {YYYY-MM-DD}
+
+Target: {story path / URL / description}
+Screenshot: {user-provided, 檔名或描述}
+容器資訊: {width / viewport / density / theme}
+Spec 依據: {packages/design-system/src/components/{Name}/{name}.spec.md}
+
+## Summary
+
+- PASS: N / 13
+- FAIL: M / 13
+- 無法判定: K / 13
+- 額外觀察: P 項
+
+## Checklist 結果
+
+### 1. 4 邊邊距對稱
+- 狀態: PASS / FAIL / 無法判定
+- 實測: top=12px, right=12px, bottom=8px, left=12px
+- 預期: 4 邊 = layout-space-loose(16px)或 spec 明文 asymmetric
+- 差異: bottom 少 4px,且非 spec 明文例外
+- 對應規則: `.claude/rules/ui-development.md`「建立 UI 前必讀」 → layout-space token + 該元件 spec.md 第 N 段
+- 建議修法方向(不自己改): 調整 bottom padding 對齊 layout-space-loose,或在 spec 記 rationale 為何 asymmetric
+
+### 2. 垂直對稱
+...
+
+(每項都展開,PASS 項可一行帶過「實測相等」)
+
+## 額外觀察(非 checklist 13 項)
+
+- {描述 + screenshot 座標 + 建議討論是否升級為 checklist 項}
+
+## 下一步
+
+- FAIL 項優先修順序: 1 → 3 → 4(geometry 類先於 typography 類)
+- 無法判定項需要: {補什麼 screenshot / 量測}
+- 本 report 不改 code;fix 請走 `/design-system-audit` 或直接 edit
+```
+
+### Phase 3 — Checkpoint(必停,STOP 點)
+
+Report 寫完後**停下來**,不 auto-fix。回報 user:
+
+```
+Visual audit 寫到 .claude/skills/visual-audit/output/{YYYYMMDD}-{component}-visual-audit.md
+
+- PASS: N / 13
+- FAIL: M / 13
+- 無法判定: K / 13
+
+FAIL 項摘要:
+- #1 4 邊邊距: bottom 少 4px(見 report 詳細)
+- #3 gap 吃掉: hover bg 溢出 ~4px(違反「同 flex 列幾何鐵律」)
+- ...
+
+下一步選項:
+1. 依 FAIL 清單去改 code / spec(我可以 chain 進 /design-system-audit 或手動 edit)
+2. 對某項 FAIL 有爭議 → 討論是否為 spec 明文例外(可加 rationale)
+3. 本輪 audit 就結束,user 自行處理
+
+(本 skill 不 auto-proceed;改 code 由其他 skill 或 user 決定。)
+```
+
+---
+
+## Non-goals(關鍵 — 混到這些就是職責混亂)
+
+- **不 audit code / spec**(code 層走 `/design-system-audit` / `/product-ui-audit`)
+- **不取代 pixel-diff 自動化**(Chromatic / Storybook screenshot-diff 是 tech debt,本 skill 過渡方案)
+- **不在沒有 screenshot 下跑 audit**(拒跑,見 Preconditions)
+- **不做主觀審美**(「看起來比較漂亮」不是 audit 結論)
+- **不改 code / spec / story**(純 read-only report)
+- **不推斷沒截到的部分**(screenshot 沒含某 state 不做推測)
+- **不 auto-fix**(Phase 3 STOP 交 user 決策)
+
+## Common failure modes(watch for these)
+
+- **憑感覺判 FAIL**:「看起來不順」不算;必須 mechanical 量測 + 對應 token 值
+- **把 code 問題寫進 report**(「cva size 應改 md」越界;本 skill 只記「視覺上 field 高度差 4px」讓後續 audit 查 code)
+- **主觀 + 機械混寫**:每項結論必須可驗證,主觀觀察一律進「額外觀察」區分
+- **screenshot 解析度不足硬量**:記「無法判定」+ 說明需求,不瞎猜
+- **跨元件比對忽略容器脈絡**:FileItem in Sidebar vs in Page 邊距可能本來就不同,先讀 spec 有無 context-aware 規則
+- **忘記對照 dark mode 版本**:亮暗兩套都要看,尤其 fg / bg / border / shadow
+
+## References
+
+- [references/visual-checklist.md](references/visual-checklist.md) — 13 面向完整 checklist(怎麼量 / 合格標準 / refer 的 DS 規則 / token)
+- [references/world-class-benchmarks.md](references/world-class-benchmarks.md) — 世界級對照(Figma zoom step、Material date-picker 邊距、Notion menu sticky header 等)
+
+## 相關
+
+- `.claude/skills/design-system-audit/SKILL.md` — 全 dim code/spec audit(per design-system-audit SSOT);本 skill 是其 pixel-level 補位
+- `.claude/skills/product-ui-audit/SKILL.md` — consumer UI 對 DS 消費 audit(code 層),不處理視覺
+- `.claude/skills/component-quality-gate/SKILL.md` — 元件合入 DS 前的 45 項 checklist;Ship phase 可 chain 本 skill
+- CLAUDE.md `# 同 flex 列的互動 slot 幾何鐵律` — 本 skill checklist #3 的主要 canonical 來源
+- `.claude/rules/ui-development.md`「建立 UI 前必讀」 → layout primitive / token spec 清單 — 本 skill「合格標準」的對照錨
+- `memory/project_pending_tasks`「視覺 regression 基建」條目 — 長期 tech debt(Chromatic / screenshot-diff)

package/ds-canonical/skills/visual-audit/references/audit-architecture.md

@@ -0,0 +1,100 @@
+# Visual audit — Layer A + Layer B 架構 + Interactive state coverage canonical
+
+(Extracted from SKILL.md 2026-05-04 — file budget consolidation,SKILL.md 留 1-line summary + pointer 本檔。)
+
+## 兩層稽核架構(2026-04-21 升級)
+
+本專案視覺稽核已分 **Layer A mechanical + Layer B AI judgement**,互補覆蓋:
+
+| Layer | 做什麼 | 由誰做 | 自動化 |
+|-------|-------|--------|--------|
+| **A. Mechanical** | (1) 截圖每個 scenario(retina PNG → `snapshots/`)<br>(2) WCAG 對比度掃描(所有可見文字 / icon vs 底色,flag AA 不過的組合)<br>(3) DOM 幾何 assertion(等高 / 對稱 padding / 正確 gap — 讀 `scripts/visual-assertions.json` 定義) | `scripts/visual-audit.mjs`(Playwright-driven) | **npm run visual-audit** 一鍵跑,產出 `snapshots/report.json` + PNG。CI 可接(exit 1 on violation) |
+| **B. AI judgement** | (1) 設計合理性(badge 位置語意對、carousel 箭頭不壓文字、zoom step 手感)<br>(2) 跨元件視覺一致(同 flex 列幾何鐵律、Family 視覺對齊)<br>(3) 世界級對照(「這跟 Figma/Notion/iOS 相比還差在哪」) | **本 skill**(`/visual-audit`),讀 `snapshots/*.png` + `report.json` 做 pattern recognition | invoke 時 AI 跑 |
+
+### Layer A 先跑,Layer B 後補(workflow)
+
+```
+1. npm run visual-audit                  # Layer A 產 snapshots + report
+2. /visual-audit                         # 本 skill 讀 snapshots/ 做 Layer B 判斷
+   (skill 自動讀 snapshots/report.json 作為 Layer A baseline,
+    重點關注 A 沒 flag 但視覺仍不對的 case)
+```
+
+### 為什麼分兩層
+
+- Mechanical 能抓的事(對比度、等高、padding 數字)讓 script 做,AI 不浪費 token
+- 設計合理性 / 世界級對照需要 pattern matching,只有 AI / human 能做——這部分走 skill
+- 兩層互相 cross-check:Layer A 漏掉但 Layer B 看出 → 回填新 assertion 到 `visual-assertions.json`,轉為 mechanical
+
+### Layer A 命令速查
+
+```bash
+# 全跑(建議 release / 大改)
+npm run visual-audit
+
+# scoped 跑(快速驗證 — 1 個 component)
+node scripts/visual-audit.mjs --scope=component:Button
+
+# 只跑 changed(git diff)— 對齊 CLAUDE.md「日常 dev」高效模式
+node scripts/visual-audit.mjs --scope=changed
+
+# 不啟 storybook(如果 storybook 已起)
+node scripts/visual-audit.mjs --no-auto-start
+```
+
+Output:
+- `snapshots/{scenarioId}.png` — retina PNG
+- `snapshots/report.json` — `{ contrast: [], geometryViolations: [], a11yViolations: [], baselineDiff: {} }`
+
+## Layer A interactive state coverage canonical
+
+**核心事實**:當前 `visual-audit.mjs` 只抓「頁面 render 完 + blur activeElement + 800ms wait」後的**靜態 snapshot**——**hover / focus-visible / active / pressed / tooltip-visible / menu-open / dropdown-open 等 post-interaction state 預設不被抓到**。
+
+### 當前覆蓋 vs Gap
+
+| 狀態 | 當前 Layer A 覆蓋? | 抓法 |
+|------|------------------|------|
+| **Default render state** | ✓ 抓 | scenario 載入後直接 screenshot |
+| **Overlay open**(Dialog / Popover / DropdownMenu chrome) | ✓ 抓 | 用 `defaultOpen` pattern(Radix Portal 自動生效) |
+| **Hover state**(cursor-over 視覺) | ✗ 不抓 | 需 `play()` + `userEvent.hover()` |
+| **Focus-visible**(ring / outline) | ✗ 不抓 | 需 `play()` + `element.focus()` |
+| **Active / pressed**(按下瞬間) | ✗ 不抓 | 需 `play()` + `userEvent.pointer()` |
+| **Tooltip visible**(iconOnly Button hover tooltip) | ✗ 不抓 | 需 `play()` + focus 觸發器 + 等 delay |
+| **Menu item hover highlight** | ✗ 不抓 | 需 `play()` + hover first item after `defaultOpen` |
+| **Combobox / Select 展開後 listbox** | 部分 | 靠 `defaultOpen` 可抓 listbox,但 hover highlight 需 play |
+
+### 解法:Storybook `play()` + `@storybook/test`
+
+Storybook v8 的 `play()` 在 story 渲染後執行,可觸發互動狀態。`@storybook/test` 提供 `userEvent` / `within` / `expect` 等 API:
+
+```tsx
+import type { StoryObj } from '@storybook/react'
+import { userEvent, within } from '@storybook/test'
+
+export const HoverState: StoryObj = {
+  render: () => <Button>Hover me</Button>,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    const btn = canvas.getByRole('button')
+    await userEvent.hover(btn)
+    // visual-audit.mjs 在 play 完後 screenshot,可抓 hover bg
+  },
+}
+```
+
+### 命名 convention(scenario IDs Layer A 認得)
+
+`{Component}/{base}--hover-state` / `--focus-visible` / `--active-state` / `--with-tooltip` / `--menu-item-hover`(等)
+
+`scripts/visual-audit.mjs` 預設 wait 800ms after render — play 觸發互動後 800ms 內不應該變化(再長要拉 explicit wait)。
+
+### Coverage 提升 roadmap(prioritized)
+
+| Wave | Story 加 play | 抓的狀態 |
+|------|--------------|----------|
+| 1 | Button / IconButton / Tooltip | hover / focus-visible / active / tooltip-visible |
+| 2 | DropdownMenu / Combobox / Select | menu-open + first-item hover |
+| 3 | Tabs / SegmentedControl / Switch | hover transition / focus-visible |
+| 4 | Form controls(Input / Checkbox / Radio) | invalid state(via aria-invalid)/ disabled hover |
+
+每 wave 完工後跑 `npm run visual-audit`,看 `report.json` 新增的 violation,回填 `visual-assertions.json`。