@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

package/ds-canonical/fork/skills/scan-similar-bugs/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: scan-similar-bugs
+description: Auto-invoke after fix commits — extracts root-cause anti-pattern, greps DS-wide for same pattern, runs visual verify, batches related fixes. Closes M10 mechanical gap. Invoke via /scan-similar-bugs.
+---
+
+> **⚠️ Fork 工具註記(build 自動加)**:本 skill 提到的 `scripts/*.mjs` 或非標準 `npm run <audit>` 是 **DS-author repo 的機械工具,未隨 fork 套件附帶**(Claude Code 不掃 node_modules,fork 也無這些 executor + dep)。你的 product fork 用本 skill 的**方法論**(human / AI judgment)+ 既有 committed governance hook 的機械強制即可;要 mechanical 腳本層(截圖 / CI gate)請自行設置對應工具,或把該檢查 PR 回 DS repo 跑。
+
+# /scan-similar-bugs — Fix-time DS-wide Exhaustive Scan
+
+**目的**:任何 bug fix 提交後,**機械化掃 DS-wide 找同 pattern**,而非靠 model 記得 M10。
+
+**對齊**:
+- CLAUDE.md M10 「Proactive exhaustive scan」mechanical 落地
+- mindset #1「不取巧」+ #2「優先消費既有」+ #6「meta 抽象」
+- 對齊 IDE「find similar / find references」+ Chrome DevTools「find usages」+ GitHub Copilot「related code」3+ 家世界級 idiom
+
+**對位其他 skill**:
+- `/design-system-audit` 是**定期 batch** full-dim audit
+- `/visual-audit` 是**單次視覺對齊** check
+- 本 skill 是 **batch-end-only root-pattern scan**(2026-05-12 codex 抓 infra conflict 重構:per-fix → batch-end,對齊 `/bug-fix-rhythm` Phase 2-3 batch fix + single end-verify canonical;M32 split 後 batch-end home 移至 bug-fix-rhythm skill)
+
+## When to invoke
+
+**強制(auto-chain)— batch-end only**(2026-05-12 重構,per codex):
+- multi-issue session 結束後**一次**(不是每 fix 一次)
+- session 內 ≥ 2 fix commit 觸發批次 root-pattern scan
+- session_start_governance_check.sh 偵測 上 session 有 ≥ 2 fix commit 但 batch-end scan 沒跑 → 提醒
+
+**手動 invoke**:
+- user 明言「掃同類 bug / 看其他元件有沒有 / 全 DS scan」
+- multi-issue batch session 結束想驗 root-pattern DS-wide
+
+**不 invoke**(對齊 Anthropic Best Practice 小修 skip plan):
+- **Surgical visual bug**(user 列 N 個 visual defects + 無 canonical / API / cross-component → 批 fix + final verify only,不必 scan-similar)
+- pure refactor(無 bug 修復語義)
+- spec.md / docs only commit
+- 純 typo / import cleanup
+
+## Non-goals
+
+- 不擴展 scope 到「audit full-dim品質」(那是 `/design-system-audit`)
+- 不做視覺 regression baseline diff(那是 `/visual-audit`)
+- 不改 canonical(找到 pattern 後修是 surgical fix,動 canonical 走 audit / Checkpoint)
+
+---
+
+## Workflow(5 phases)
+
+### Phase 0 — 抓 root-cause anti-pattern
+
+```bash
+# 讀 last fix commit message + diff
+git log -1 --format='%s%n%n%b'
+git show HEAD --stat
+```
+
+從 commit message + diff 抽出 grep-able pattern。常見類型:
+
+| Bug 類型 | Anti-pattern grep target |
+|---|---|
+| Padding / sizing 公式錯 | `calc((var(--field-height-X) - <num>px) / 2)` etc |
+| Token leak / shadcn alias | `bg-popover / text-muted-foreground / bg-accent` |
+| 硬寫 magic number | `text-[14px] / shadow-[0_2px_8px_...]` |
+| API mis-use(prop combo)| `iconOnly + endIcon` / `loading + disabled` |
+| a11y missing | `<button>` 無 `aria-label` 又無 children |
+| Symbol mis-import | `from 'shadcn/ui/X'` |
+| CSS w/h asymmetric | SVG 量測 width !== height |
+
+**Output**: `ANTI_PATTERN`(grep regex / Playwright assertion)。
+
+### Phase 1 — DS-wide grep / visual scan
+
+選最適合的 detection:
+
+**Static grep**(快,適合 token / class / API mis-use):
+```bash
+grep -rnE "$ANTI_PATTERN" node_modules/@qijenchen/design-system/src/ --include="*.tsx" \
+  | grep -v "test_\|stories\|node_modules"
+```
+
+**Playwright visual scan**(慢,適合 geometry / a11y / interaction):
+```bash
+node scripts/scan-asymmetric-icons.mjs   # 已存在,iconOnly visual scan template
+# 或 base 同 pattern 自寫 dim-specific scan
+```
+
+**Output**:候選清單(file:line + 樣本)。
+
+### ⚠️ Checkpoint 1 — Triage
+
+向 user present:
+```
+Phase 1 found N candidates of same anti-pattern:
+- node_modules/@qijenchen/design-system/src/components/A/a.tsx:42  > grep match
+- node_modules/@qijenchen/design-system/src/components/B/b.tsx:18  > grep match
+- node_modules/@qijenchen/design-system/src/components/C/c.tsx:55  > 視覺 14×16
+
+Proceed?
+- (a) Auto-fix all N(若修法 deterministic 例 token rename)
+- (b) Review per-file(若 fix 需個別判斷)
+- (c) 留 N 個 tech debt 後續處理(寫 memory + 不修)
+```
+
+不可 silent 跳過 user — fix scope 影響 N 元件,**M10 + 稽核 vs 執行 分權**要求 user 拍板。
+
+### Phase 2 — 批量 / 個別 fix
+
+按 Checkpoint 1 user 選的路執行。每修一檔:
+- 用 Edit(不 Write,降風險)
+- 修完 grep 該 anti-pattern 應 0 match
+- npx tsc --noEmit 必過
+
+### Phase 3 — Visual / unit verify
+
+- Visual:跑 `npm run icons:scan` 或 dim-specific scan
+- Unit:跑 `npm run hooks:test`
+- TSC:`npx tsc -b`
+- 全綠才繼續
+
+### Phase 4 — Final report + memory + new defense
+
+```markdown
+## Scan-similar-bugs report
+
+### Root cause(來自 last fix commit `<hash>`)
+- Pattern:{ANTI_PATTERN}
+- Origin file:{first detected location}
+
+### DS-wide impact
+- {N} candidates found
+- {M} fixed this run
+- {K} deferred(spec rationale 已記)
+
+### New defense layer(防 future regression)
+- 加 hook:`.claude/hooks/check_<pattern>.sh`(若 pattern 易 grep)
+- 加 visual test:`scripts/scan-<pattern>.mjs`(若需 Playwright)
+- 加 spec rule:{spec.md anchor}
+
+## Self-improvement capture
+- 新 anti-pattern 加進本 skill 的 Phase 0 「Bug 類型 → grep target」表
+- M10 fire 紀錄(commit 後本 skill invoke vs not)
+```
+
+寫進:
+- 對應 commit message
+- `memory/` 若是 cross-session pattern
+- 本 skill `references/` 若是 reusable detection 公式
+
+---
+
+## ⚠️ Checkpoints(禁止跳)
+
+### Checkpoint 1 — Phase 1 後 Triage
+N 個 candidate 的修法 scope。**禁止 auto-fix 超過 5 檔不 ask user**。
+
+### Checkpoint 2 — 動 canonical
+若 N candidates 都 violate 同 canonical,但 canonical 本身可能 outdated → 走 audit 重訂(不在本 skill scope)。
+
+### Checkpoint 3 — Defer 的 tech debt
+若 user 選 (c) 留 tech debt → 必寫 memory + 標明「deferred at <date>,reason: <reason>」。`/codify-corrections` 季度會 review。
+
+---
+
+## 對位其他 skill / hook
+
+| Tool | scope | 跟本 skill 關係 |
+|---|---|---|
+| `/design-system-audit` | full-dim batch audit | 本 skill 抓不到的 architectural pattern audit 補位 |
+| `/visual-audit` | 單次視覺對齊 | Phase 3 verify 用 |
+| `/scan-similar-bugs`(本) | **immediate-after-fix grep + verify** | M10 mechanical 落地 |
+| `/knowledge-prune` | 季度 governance prune | 不重複 |
+| `check_canonical_propagation.sh` E.2(hook;原 check_l3_primitive_import.sh folded 折入,P0 BLOCK) | L3 primitive import 違規 | 即時 detect,本 skill 是 batch retro scan |
+| `pre_write_subsumption_check.sh`(hook)| 新 file / M-row | 不重複 |
+
+**3 層 防線**:
+- Hook(pre/post tool):**寫的瞬間** detect
+- 本 skill(fix-time):**修完瞬間** scan DS-wide
+- `/design-system-audit`(periodic):**季度** full-dim sweep
+
+---
+
+## 世界級對照
+
+- **Chrome DevTools "find references"**:單元件變更後找其他 consumers
+- **VS Code "find similar code"**:AI-powered same-pattern scan
+- **GitHub Copilot Workspace**:fix 後自動 propose related changes
+- **WebStorm "Inspect Code → Similar Patterns"**:同 pattern detect
+
+我們對齊 4 家但加 **DS-domain-specific anti-pattern table**(Phase 0 列表),是 generic IDE 沒做到的。
+
+---
+
+## Self-improvement capture
+
+每次 invoke 完寫:
+- (a) 新發現 anti-pattern → 加到 Phase 0 表(grep target template 更新)
+- (b) Detection false positive → 修 grep regex 或加 allowlist 註解 pattern
+- (c) Phase 1 漏掃 location → 補 grep scope(extend 到 hooks/ / scripts/ etc)
+
+回填 SKILL.md 或 references/ 形成累積資產。

package/ds-canonical/fork/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 存在於 `node_modules/@qijenchen/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`)
+
+## 相關
+
+- `node_modules/@qijenchen/design-system/ds-canonical/skills/design-system-audit/SKILL.md` — 全 dim 統籌(per design-system-audit SSOT);本 skill 是 D4 補位
+- `node_modules/@qijenchen/design-system/ds-canonical/skills/visual-audit/SKILL.md` — pixel 層(D5)
+- `node_modules/@qijenchen/design-system/ds-canonical/skills/performance-audit/SKILL.md` — 效能層(D3)
+- `node_modules/@qijenchen/design-system/ds-canonical/skills/component-quality-gate/SKILL.md` — Phase 4.5 進階模式 chain 本 skill

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

@@ -0,0 +1,247 @@
+---
+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.
+---
+
+> **⚠️ Fork 工具註記(build 自動加)**:本 skill 提到的 `scripts/*.mjs` 或非標準 `npm run <audit>` 是 **DS-author repo 的機械工具,未隨 fork 套件附帶**(Claude Code 不掃 node_modules,fork 也無這些 executor + dep)。你的 product fork 用本 skill 的**方法論**(human / AI judgment)+ 既有 committed governance hook 的機械強制即可;要 mechanical 腳本層(截圖 / CI gate)請自行設置對應工具,或把該檢查 PR 回 DS repo 跑。
+
+# 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 吃掉(node_modules/@qijenchen/design-system/ds-canonical/references/ui-dev-rules.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(node_modules/@qijenchen/design-system/ds-canonical/references/ui-dev-rules.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(固定格式)
+
+產出檔案路徑:
+
+```
+node_modules/@qijenchen/design-system/ds-canonical/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 依據: {node_modules/@qijenchen/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 明文例外
+- 對應規則: `node_modules/@qijenchen/design-system/ds-canonical/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 寫到 node_modules/@qijenchen/design-system/ds-canonical/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 等)
+
+## 相關
+
+- `node_modules/@qijenchen/design-system/ds-canonical/skills/design-system-audit/SKILL.md` — 全 dim code/spec audit(per design-system-audit SSOT);本 skill 是其 pixel-level 補位
+- `node_modules/@qijenchen/design-system/ds-canonical/skills/product-ui-audit/SKILL.md` — consumer UI 對 DS 消費 audit(code 層),不處理視覺
+- `node_modules/@qijenchen/design-system/ds-canonical/skills/component-quality-gate/SKILL.md` — 元件合入 DS 前的 45 項 checklist;Ship phase 可 chain 本 skill
+- node_modules/@qijenchen/design-system/ds-canonical/references/ui-dev-rules.md `# 同 flex 列的互動 slot 幾何鐵律` — 本 skill checklist #3 的主要 canonical 來源
+- `node_modules/@qijenchen/design-system/ds-canonical/rules/ui-development.md`「建立 UI 前必讀」 → layout primitive / token spec 清單 — 本 skill「合格標準」的對照錨
+- `memory/project_pending_tasks`「視覺 regression 基建」條目 — 長期 tech debt(Chromatic / screenshot-diff)