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

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

@@ -0,0 +1,201 @@
+---
+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.
+---
+
+> **Product-role projection(build 自動)**:本 skill 的執行步驟已只保留本 product repo 實際存在的指令。DS-author-only executor 會被改寫為 browser/manual/product-CI 等價驗證,不得在 product 中嘗試不存在的腳本。
+
+# /scan-similar-bugs — Fix-time DS-wide Exhaustive Scan
+
+**目的**:任何 bug fix 提交後,**機械化掃 DS-wide 找同 pattern**,而非靠 model 記得 M10。
+
+**對齊**:
+- `node_modules/@qijenchen/design-system/ds-canonical/rules/meta-patterns.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 independent review 抓 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 independent review):
+- multi-issue session 結束後**一次**(不是每 fix 一次)
+- session 內 ≥ 2 fix commit 觸發批次 root-pattern scan
+- session_start_governance_check.sh Check 6 偵測 24h 內 ≥1 fix commit 且 skill-invokes log 24h 無 scan-similar-bugs invoke → soft 提醒
+
+**手動 invoke**:
+- user 明言「掃同類 bug / 看其他元件有沒有 / 全 DS scan」
+- multi-issue batch session 結束想驗 root-pattern DS-wide
+
+**不 invoke**(對齊 provider-neutral 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`)
+- 不在本 skill 擴張成 full canonical redesign；工程治理 canonical remediation 轉交 audit 自主處理，只有產品／UI／UX SSOT 真取捨才是 human boundary
+
+---
+
+## 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
+use the active browser/Storybook screenshot workflow and preserve visual evidence
+# 或 base 同 pattern 自寫 dim-specific scan
+```
+
+**Output**:候選清單(file:line + 樣本)。
+
+### Phase 1.5 — Authority classification + triage receipt
+
+產出:
+```
+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
+
+Execution:
+- deterministic fix → Auto-fix all confirmed N
+- engineering judgment → 依 owning spec + highest certified capability 逐檔收斂；task／deliverable 明確要求時才加 independent review
+- 不屬 frozen scope → Backlog with evidence；不得用 defer 逃避 scope 內修復
+- 會改產品／UI／UX SSOT 且仍有真取捨 → batch-at-end human-only decision
+```
+
+不可 silent 跳過 confirmed scope；影響 N 檔是工程 blast radius，不是 user approval gate。必記錄 scope、evidence、tests 與 rollback。
+
+### Phase 2 — 批量 / 個別 fix
+
+按 Phase 1.5 authority classifier 執行。每修一檔:
+- 用 Edit(不 Write,降風險)
+- 修完 grep 該 anti-pattern 應 0 match
+- npx tsc --noEmit 必過
+
+### Phase 3 — Visual / unit verify
+
+- Visual:跑 `use the active browser/Storybook screenshot workflow and preserve visual evidence` 或 dim-specific scan
+- Unit:跑 `npm run governance:check`
+- 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)
+- 加 canonical hook:the installed immutable governance checker(若 pattern 易 grep)，再由 generator 投影到各 provider；禁止直接新增 provider-owned hook。
+- 加 visual test:the product-specific verification workflow (when configured)(若需 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 公式
+
+---
+
+## Authority gates(禁止跳 classifier)
+
+### Gate 1 — Phase 1 後 Triage
+N 個 candidate 的修法 scope由 agent 依 frozen scope、canonical、tests 與 rollback 自行收斂；檔案數量不構成人類工程核准門檻。
+
+### Gate 2 — 動 canonical
+若 N candidates 都 violate 同 canonical,但 canonical 本身可能 outdated → 走 audit 重訂。工程／治理決策 AUTO；只有重訂會改產品／UI／UX SSOT 且存在真取捨才停。
+
+### Gate 3 — Backlog
+只有不屬 frozen scope 的 improvement 才放 Backlog，必寫 memory + evidence + reason；Scope 內可修復項不得因 milestone 或工程偏好 defer。
+
+---
+
+## 對位其他 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 | 不重複 |
+| the installed immutable governance checker E.2(hook;原 check_l3_primitive_import.sh folded 折入,P0 BLOCK) | L3 primitive import 違規 | 即時 detect,本 skill 是 batch retro scan |
+| the installed immutable governance checker(retired 2026-06 → canonical the installed immutable governance checker history;新 file / M-row 治理由 the installed immutable governance checker + the installed immutable governance checker 現役防線接手)| 新 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,133 @@
+---
+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。
+
+## 觸發時機(對齊 shared governance 稽核 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(500ms for tooltip, 700ms for hover-card,per `tokens/motion/motion.spec.md` 三層 tier SSOT)
+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 and route
+
+產出:
+
+```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(建議改善)
+
+## Authority classification
+- P2E:{工程／治理 finding，交 canonical owner 自主修復}
+- P2H:{只有真正產品／UI／UX SSOT 取捨才列 exact target-bound decision}
+```
+
+本 skill 保持 read-only，report 是 evidence receipt；caller／canonical owner 對 P2E 直接接續
+修復與驗證，不把 read-only skill boundary 誤當 user checkpoint。只有 P2H 或
+shared-governance human-only boundary 才停止。
+
+## 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,248 @@
+---
+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.
+---
+
+> **Product-role projection(build 自動)**:本 skill 的執行步驟已只保留本 product repo 實際存在的指令。DS-author-only executor 會被改寫為 browser/manual/product-CI 等價驗證,不得在 product 中嘗試不存在的腳本。
+
+# 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**(`use the active browser/Storybook screenshot workflow and preserve visual evidence`):截圖 + WCAG + geometry。**Layer B AI**(本 skill):合理 / 一致 / 世界級對照。**Workflow**:`use the active browser/Storybook screenshot workflow and preserve visual evidence` → `/visual-audit` 讀 `<absolute-git-dir>/governance-runtime/evidence/visual/visual-audit/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 前的 35 項 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)
+
+## Baseline 更新鐵律(2026-07-07 軌道 5 codify)
+
+**覆蓋任何 `infra/governance/baseline/visual/{curated,targeted}/*.png` 前,模型必 Read 新舊兩張圖並寫出「觀察到的具體差異」**。所有 provider-specific baseline compatibility path 都僅是 deterministic generated delivery/discovery projection,not authority,do not edit,禁止當 reverse SSOT 寫入。
+(diff 百分比是訊號、圖才是真相)。禁只看 pct 就 cp。錨例:2026-07-07 VR 換日 bug——釘日期後
+pct 一模一樣,只有看圖才發現 today 圈仍在真實日期(元件內部時間);FileViewer 40.3% 只有看圖
+才知道是 zoom 94→100(fit 被凍壞)非渲染炸裂。配套:roadmap 方向 7 accept-baseline workflow
+(script 化時「看圖步驟」不可省)。
+
+## Evidence preflight(硬規則)
+
+先從 explicit target、目前 frozen scope／changed paths、Layer-A report、story registry 與
+capture manifest 解析 audit target。缺 screenshot 時，優先用既有 Storybook／product capture
+流程自行產生；viewport、density、theme 與 size 必取自同一 capture manifest，不靠猜測或
+另問 user。元件 token 由 owning spec 與 token registry 解析。
+
+只有在本機／既有受治理環境確實無法取得 target 或影像，且原因是不可代理的登入、MFA、
+OAuth 或 private surface access 時，才形成 shared-governance human-only action；此時先完成
+所有其他 preflight，只回報唯一必要操作。若 owning spec 缺 token，記為 P2E governance
+evidence gap 並交 canonical owner；若補值會創造產品／UI／UX SSOT 真取捨才列 P2H。
+
+**絕不**在 evidence 不足下憑感覺判斷——「看起來有點歪」不是 audit,是直覺。本 skill
+產出必須全部是 mechanical 可驗證的結論；無法取得的項目記為 fail-closed evidence gap，
+不能用 blanket user checkpoint 取代。
+
+---
+
+## 涵蓋的視覺面向(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 + evidence gate
+
+1. 讀 `AGENTS.md` 與 `node_modules/@qijenchen/design-system/ds-canonical/rules/ui-development.md`(最新 token / 最新 layout primitive 規則);provider view 只用於 discovery,不能反向當 authority
+2. 依 Evidence preflight 從 frozen scope／changed paths、Layer-A report 與 registry 定 target。
+3. 取得或自行 capture screenshot，並綁定同一份 viewport／density／theme／size manifest；
+   缺 evidence 時依上節 fail closed，不把工程查找工作轉交 user。
+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 座標 + 描述；依 shared governance authority classifier 路由：純機械 coverage／治理補強是 P2E/AUTO，只有升級會改變產品／UI／UX SSOT 且仍有真取捨才 P2H
+
+### Phase 2 — 輸出 report(固定格式)
+
+產出檔案路徑:
+
+```
+<absolute-git-dir>/governance-runtime/evidence/visual/manual-audit/{YYYYMMDD}-{component}-visual-audit.md
+```
+
+寫入前必須以 `node scripts/lib/governance-runtime-evidence.mjs --repo-root "$PWD" --path "visual/manual-audit/{filename}" --prepare-file` 取得經驗證的 exact destination;不得自行推導 `.git` 路徑,不得寫 provider home。
+
+**檔名規則**:同一天同元件多次跑 → 加 `-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 — Read-only handoff(skill boundary，不是 user approval checkpoint)
+
+Report 寫完後，本唯讀 skill 不直接改 source；將 evidence 交回 primary context 並依 shared governance authority classifier 繼續：
+
+```
+Visual audit 寫到 <absolute-git-dir>/governance-runtime/evidence/visual/manual-audit/{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 可由既有 canonical 決定 → P2E，由 primary context 依 Standing Authorization remediation + verify
+2. 純工程／治理原因尚未收斂 → P2E，依 Engineering Decision Policy、tests 與 hard gates 收斂；task／deliverable 明確要求時才加 independent review，optional review 缺席不得阻擋一般工程；無法收斂則 fail closed 回報 technical blocker
+3. 必須改變產品／UI／UX SSOT 且仍有真實選擇或取捨 → P2H，batch-at-end 請 user 拍板
+4. 證據不足 → 補足 screenshot／量測，不以猜測結案
+
+(本 skill 保持 read-only；primary implementation 不需另取 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 不做推測)
+- **不在本 read-only skill 內 auto-fix**(Phase 3 將 evidence 交回 primary context；依 P2E/P2H classifier 繼續)
+
+## 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 前的 35 項 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「合格標準」的對照錨