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

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

@@ -0,0 +1,258 @@
+---
+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.
+---
+
+<!-- _generated: canonical provider skill projection; source: skills/visual-audit/SKILL.md; provider: codex; do not edit this adapter view. -->
+
+<!-- provider-binding: profile=repository-legacy-surfaces-v1; provider=codex; strategy=generated-binding-header; assumptionCount=4; assumptionFingerprint=sha256:0fd67f1adf4fc31b0756f12522a1dfd7f0af40f3e4b08002f1ee18cac446f7fe; evidence=packages/governance/canonical/providers.json#codex -->
+
+## Provider binding contract
+
+This canonical workflow contains a committed inventory of legacy assumptions. Resolve them exactly as follows; an unavailable resolution or inventory drift is `ADAPTER-BLOCKED`:
+
+- `provider-surface-path`: Resolve legacy repository paths through generated views while treating ds-canonical as the semantic owner.
+
+> **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「合格標準」的對照錨

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

@@ -0,0 +1,101 @@
+> **Product-role projection(build 自動)**:本 skill 的執行步驟已只保留本 product repo 實際存在的指令。DS-author-only executor 會被改寫為 browser/manual/product-CI 等價驗證,不得在 product 中嘗試不存在的腳本。
+# 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 → Git-owned neutral evidence)<br>(2) WCAG 對比度掃描(所有可見文字 / icon vs 底色,flag AA 不過的組合)<br>(3) DOM 幾何 assertion(等高 / 對稱 padding / 正確 gap — 讀 `the product visual acceptance criteria` 定義) | `use the active browser/Storybook screenshot workflow and preserve visual evidence`(Playwright-driven) | **use the active browser/Storybook screenshot workflow and preserve visual evidence`<absolute-git-dir>/governance-runtime/evidence/visual/visual-audit/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`),讀 `<absolute-git-dir>/governance-runtime/evidence/visual/visual-audit/*.png` + `report.json` 做 pattern recognition | invoke 時 AI 跑 |
+
+### Layer A 先跑,Layer B 後補(workflow)
+
+```
+1. use the active browser/Storybook screenshot workflow and preserve visual evidence
+2. /visual-audit                         # 本 skill 讀 neutral runtime evidence 做 Layer B 判斷
+   (skill 自動讀 <absolute-git-dir>/governance-runtime/evidence/visual/visual-audit/report.json 作為 Layer A evidence,
+    重點關注 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 / 大改)
+use the active browser/Storybook screenshot workflow and preserve visual evidence
+
+# scoped 跑(快速驗證 — 1 個 component)
+use the active browser/Storybook screenshot workflow and preserve visual evidence
+
+# 只跑 changed(git diff)— 對齊 AGENTS.md provider-neutral「日常 dev」高效模式
+use the active browser/Storybook screenshot workflow and preserve visual evidence
+
+# 不啟 storybook(如果 storybook 已起)
+use the active browser/Storybook screenshot workflow and preserve visual evidence
+```
+
+Output:
+- `<absolute-git-dir>/governance-runtime/evidence/visual/visual-audit/{scenarioId}.png` — retina PNG
+- `<absolute-git-dir>/governance-runtime/evidence/visual/visual-audit/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`(等)
+
+`use the active browser/Storybook screenshot workflow and preserve visual evidence` 預設 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 完工後跑 `use the active browser/Storybook screenshot workflow and preserve visual evidence`,看 `report.json` 新增的 violation,回填 `visual-assertions.json`。

package/ds-canonical/fork/codex/agents/skills/visual-audit/references/visual-checklist.md

@@ -0,0 +1,297 @@
+# Visual Audit — 13 面向 checklist(怎麼量 / 合格標準 / refer 的 DS 規則)
+
+每個面向 = SKILL.md Phase 1 的一個 TaskList 項。本檔案規範:**怎麼量、合格標準、對應哪條 DS 規則**。全部 mechanical 可驗證,不允許「看起來不順」這類主觀描述。
+
+**通用量測原則**:
+- 用 image reading 取 screenshot 像素座標(左上為原點 0,0;單位 px)
+- 同一面向的 4 個量測點必須用「同一張 screenshot 的同一縮放比例」;混不同 screenshot 比例會誤判
+- 容器寬度 / viewport / density / theme 必綁定同一 Layer-A capture manifest；不得靠猜測，也不得把可由 registry/capture 解析的工程工作轉問 user
+- 合格標準若為 token → 對照「該元件 spec 宣告的 token 值」或 `tokens/*/` primitive;不是「看起來接近就算對」
+- **容差規範**:px 量測允許 ±1px(螢幕截圖 sub-pixel rounding);ratio 允許 ±5%;明文標「精確」的項目(如對稱)不給容差
+
+**記錄格式**(每項在 report 都長這樣):
+- `狀態: PASS / FAIL / 無法判定`
+- `實測: {量到的值}`
+- `預期: {token 值或 ratio}`
+- `差異: {若 FAIL,寫出 diff 和推測破壞規則}`
+- `對應規則: {AGENTS.md 章節 or spec.md 段落 or token 名}`
+
+---
+
+## 1. 4 邊邊距對稱
+
+**Canonical source**: 元件自身 `spec.md` 宣告的 padding token;`tokens/layoutSpace/layoutSpace.spec.md`;`tokens/uiSize/uiSize.spec.md`
+
+**怎麼量**:
+1. 找元件最外層容器(含 border 的那層)的 4 個內邊到第一個 child 的距離
+2. 分別量 top / right / bottom / left padding
+3. 與 spec 宣告的 padding token 值比對(如 `layout-space-loose = 16px`)
+
+**合格標準**:
+- 4 邊全等 token 值 → PASS
+- 元件 spec 明文宣告 asymmetric(例「top padding 較大為 sticky header」) → 照 spec 查
+- 4 邊不等且 spec 無 rationale → FAIL
+
+**FAIL 範例**:DatePicker 量到 top=12 / right=12 / bottom=8 / left=12,spec 未宣告 bottom asymmetric → FAIL,建議討論是對齊 12 還是補 spec rationale
+
+**對應規則**:AGENTS.md `# 稽核 canonical`「Consistency 類稽核必 Phase 0 全掃再判」(actual == canonical OR rationale-for-deviation;design-system-audit Dim 13 enforce)
+
+---
+
+## 2. 垂直對稱(to-top ↔ to-bottom)
+
+**Canonical source**: 元件 `spec.md` 的結構描述;「外層 element 到容器頂」= 「內層末端到容器底」為共通視覺節奏,除非 spec 明文否認
+
+**怎麼量**:
+1. 找元件最上方功能 element(如 DatePicker 的 prev/next 箭頭按鈕)量其 top 邊到容器頂的距離 A
+2. 找元件最下方 content element(如最後一排日期 cell)量其 bottom 邊到容器底的距離 B
+3. A vs B 相等判定
+
+**合格標準**:
+- A == B(±1px) → PASS
+- 元件 spec 明文有 asymmetric rationale(如「footer action bar 較高」) → 照 spec 查
+- A != B 且無 rationale → FAIL
+
+**FAIL 範例**:DatePicker 箭頭按鈕 top=12px 但最後一排日期 bottom=4px → 差異 8px 違反上下對稱
+
+**對應規則**:該元件 spec.md + `node_modules/@qijenchen/design-system/ds-canonical/rules/ui-development.md`「建立 UI 前必讀」 layout-space token
+
+---
+
+## 3. 水平 gap 實際值 == gap token 宣告值(hover bg 不可吃掉)
+
+**Canonical source**:`node_modules/@qijenchen/design-system/ds-canonical/references/ui-dev-rules.md` `# 同 flex 列的互動 slot 幾何鐵律`(gap 鐵律)
+
+**怎麼量**:
+1. 量同一 flex row 相鄰兩 interactive slot 的 **box 邊** 之間距離(不是「視覺中心距離」,是右邊 slot 左緣 - 左邊 slot 右緣)
+2. 比對 cva `gap-N` 或 `gap-[var(--layout-space-X)]` 的宣告值
+3. **關鍵**:量 hover state 時的 gap(滑鼠移上去 hover bg 放大後),不只 default state
+4. 檢查 hover bg / ring / focus outline 是否超出 slot box —— 若超出,實際 gap = 宣告 gap - overflow 量
+
+**合格標準**:
+- default + hover 兩態的 gap 都 == 宣告值(±1px) → PASS
+- hover 狀態 gap 被 bg overflow 吃掉 → FAIL(違反 `node_modules/@qijenchen/design-system/ds-canonical/references/ui-dev-rules.md`「同 flex 列幾何鐵律」)
+
+**FAIL 範例**:FileItem 2026-04-19 bug,Button hover-bg 24px 超出 16px box,`gap-2`(8px)實際剩 ~4px
+
+**對應規則**:`node_modules/@qijenchen/design-system/ds-canonical/rules/ui-development.md` → `# 同 flex 列的互動 slot 幾何鐵律`(必讀)
+
+---
+
+## 4. Overlay 定位(Badge / Popover / HoverCard / Tooltip)
+
+**Canonical source**: 對應元件 spec(`tooltip.spec.md` / `popover.spec.md` / `hover-card.spec.md`);`patterns/overlay-surface/overlay-surface.spec.md`
+
+**怎麼量**:
+1. 定位 anchor 元件(底層觸發元件)的 box 四邊
+2. 量 overlay 的位置:side-offset(overlay 離 anchor 的距離)、alignment(start / center / end)
+3. 檢查:
+   - **side-offset 對稱**:若 overlay 說明「距 anchor 8px」,實際量應 == 8px
+   - **不覆蓋 anchor content**:overlay 不該遮住 anchor 上的可讀資訊
+   - **不超出 viewport**:overlay 貼邊時仍在 viewport 內(flip 行為正確)
+   - **Badge 特例**:badge 疊 anchor 時,offset 應用 token(`--ui-size-*`)非硬寫 px
+
+**合格標準**:
+- side-offset 等 spec 宣告值 → PASS
+- 不覆蓋 anchor content → PASS
+- 任一違反 → FAIL
+
+**FAIL 範例**:Carousel prev/next 箭頭覆蓋 carousel item content;Badge 疊 Button 距離離譜用硬寫 px
+
+**對應規則**:對應元件 spec;`node_modules/@qijenchen/design-system/ds-canonical/rules/ui-development.md`「元件 Props 命名」「常用 icon canonical」(若箭頭用錯 icon);同檔「建立 UI 前必讀」 overlay-surface pattern
+
+---
+
+## 5. Typography baseline 對齊
+
+**Canonical source**: `tokens/typography/typography.spec.md`;`patterns/element-anatomy/item-anatomy.spec.md`
+
+**怎麼量**:
+1. 找 icon + text 同行的 row(如 MenuItem / Button / Tag)
+2. 量 icon 幾何中心的 y 座標 vs text baseline 的 y 座標
+3. **重要區分**:icon 應對齊 text **中線(cap-height 中心)** 而非 baseline(baseline 是字母底緣,icon 對那會視覺偏下);但實務用 `items-center` flex 已處理 geometric center,只需檢查實際 render 是否視覺對齊
+
+**合格標準**:
+- icon 幾何中心 y == text optical center y(±1px) → PASS
+- icon 明顯偏上 / 偏下 → FAIL(常見原因:用了 `items-baseline` 而非 `items-center`,或 icon box 高度與 text line-height 不匹配)
+
+**FAIL 範例**:MenuItem icon 16px 與 body text 14px(line-height 1.5=21px),幾何中心若對 y=7 vs y=10.5,差 3.5px → 視覺偏上
+
+**對應規則**:`tokens/typography/typography.spec.md` line-height(scanning 1.3 vs reading 1.5);`item-anatomy.spec.md` Inline Action 規格
+
+---
+
+## 6. Icon ↔ text gap 一致
+
+**Canonical source**: `patterns/element-anatomy/item-anatomy.spec.md` Inline Action / slot 規格(`gap-2` = 8px 標準)
+
+**怎麼量**:
+1. 列出同一列表內所有 row(如 SidebarMenu 的 5 個 MenuItem)
+2. 逐 row 量 icon right edge → text left edge 的距離
+3. 5 個值應全等
+
+**合格標準**:
+- 全部相等(±1px) → PASS
+- 任一 row 偏離 → FAIL(常見原因:某 row 用了不同 gap class,或某 row icon size 偏離 ICON_SIZE 常數)
+
+**FAIL 範例**:5 個 MenuItem 有 4 個 gap=8px,1 個 gap=12px(consumer 手動加了 `gap-3`)
+
+**對應規則**:`item-anatomy.spec.md`;`node_modules/@qijenchen/design-system/ds-canonical/rules/ui-development.md`「新增數值前必須先查既有 pattern」
+
+---
+
+## 7. 容器寬度 fill
+
+**Canonical source**: 元件 spec 宣告容器行為(block / inline / fill-container);`field-controls.spec.md` 對 field 類
+
+**怎麼量**:
+1. 量元件 outer box 寬度 vs 其 parent 容器寬度
+2. 若元件是 block-level(如 FileUpload / FileItem / Empty / Field),應 100% fill parent width
+3. 若元件是 inline-level(如 Tag / Chip / Button default),應 fit-content
+
+**合格標準**:
+- block-level == parent width(±1px) → PASS
+- inline-level == content width → PASS
+- block-level 內縮(未 fill) → FAIL
+
+**FAIL 範例**:FileUpload 在 800px 容器內只佔 600px,兩側 100px 空白 → 違反 block-level 預設行為
+
+**對應規則**:對應元件 spec;`components/Field/field.spec.md`(Field 類)
+
+---
+
+## 8. 同 row field 高度對齊
+
+**Canonical source**: `tokens/uiSize/uiSize.spec.md` field-height family(`--field-height-sm/md/lg` = 28/36/44px)
+
+**怎麼量**:
+1. 找同一 row 並排的 field 類元件(Input / Select / DatePicker / Button 等)
+2. 量每個 element box height
+3. 全部相等且 == 對應 `--field-height-{size}` 值
+
+**合格標準**:
+- 全等 token 值(±1px) → PASS
+- 任一偏離 → FAIL
+
+**FAIL 範例**:Input(size=md, 36px)+ Button(size=md, 36px)+ Select(誤用 size=sm, 28px)→ Select 偏低 8px
+
+**對應規則**:`uiSize.spec.md` field-height family;`node_modules/@qijenchen/design-system/ds-canonical/rules/ui-development.md`「建立 UI 前必讀」 → uiSize token
+
+---
+
+## 9. 跨 OS 一致 scrollbar
+
+**Canonical source**:`node_modules/@qijenchen/design-system/ds-canonical/rules/ui-development.md`「建立 UI 前必讀」 「overflow 使用三規則」;`components/ScrollArea/`
+
+**怎麼量**:
+1. 找 screenshot 內的 scrollable area
+2. 檢查 scrollbar 視覺:
+   - **ScrollArea 的**:有 overlay scrollbar,不吃 content 寬度,macOS/Windows/Linux 視覺一致
+   - **native overflow 的**:macOS 預設隱藏,Windows 吃 ~15px 寬度,跨 OS 不一致
+3. 若 screenshot 來自 Windows,量 scrollbar 是否佔 content 寬度(佔 = native;不佔 = ScrollArea)
+
+**合格標準**:
+- 需捲動的場景使用 ScrollArea(scrollbar 為 overlay style) → PASS
+- 用 native `overflow-auto` 且 user 實際用 Windows 會吃寬度 → FAIL
+- horizontal-overflow pattern 刻意隱藏 scrollbar + fade mask → PASS(不同場景)
+
+**FAIL 範例**:DataTable 水平捲動用 native overflow-x-auto → Windows user 看到 15px scrollbar 吃 cell 寬度
+
+**對應規則**:`node_modules/@qijenchen/design-system/ds-canonical/rules/ui-development.md`「建立 UI 前必讀」 → overflow 使用三規則
+
+---
+
+## 10. Zoom / step 幅度
+
+**Canonical source**: `world-class-benchmarks.md` Figma/Photoshop zoom step;元件 spec(如 FileViewer / ImageViewer)
+
+**怎麼量**:
+1. 取 zoom-in/out 前後兩張 screenshot
+2. 量某固定 element(如圖片裡一個標示)的 box 尺寸 before / after
+3. 算 ratio = after / before
+
+**合格標準**:
+- 單次滾輪 / 單次 button tick 的 ratio 在 1.1×–1.25× 區間 → PASS(對標 Figma ≈ 1.1×,Photoshop ≈ 1.2×)
+- 跳大步(如 1.5× / 2×)→ FAIL(user 會感覺「跳過想看的中間值」)
+- 跳太小(如 1.02×)→ FAIL(user 要滑很久才有感)
+
+**FAIL 範例**:ImageViewer 單次滾輪從 100% 跳到 200% → ratio 2.0,違反世界級習慣
+
+**對應規則**:`world-class-benchmarks.md`「Figma zoom step」;元件 spec 若有宣告 step 以 spec 為準
+
+---
+
+## 11. Dark mode 對比 / token 聯動
+
+**Canonical source**: `tokens/color/color.spec.md` semantic token dark mode 反轉;元件 spec 的 dark mode 行為段
+
+**怎麼量**:
+1. 取 light + dark 兩張 screenshot(同元件、同 state)
+2. 逐元素檢查:
+   - **fg / bg 對比比**:dark mode 文字是否仍可讀(對比 ≥ WCAG AA 4.5:1)
+   - **border / divider 可見**:dark mode border 不該消失於 bg
+   - **shadow 聯動**:`--elevation-*` token 在 dark mode 應調整(通常變更透明,因 dark bg 陰影要提亮)
+3. 若元件**永遠 dark mode**(如 FileViewer 工具列)→ 檢查 light theme 下仍為 dark 外觀,不跟全域 theme 切
+
+**合格標準**:
+- fg/bg 對比符合 WCAG AA → PASS
+- border/shadow 在 dark mode 仍可見 → PASS
+- shadow 用 `--elevation-*` token 而非硬寫 `shadow-md` → PASS(看不出硬寫,但若 dark mode shadow 消失 = 強烈信號)
+- 永遠 dark mode 元件在 light theme 下不跟切 → PASS
+
+**FAIL 範例**:Popover 在 dark mode 下 shadow 消失(用了 `shadow-md` 硬寫);FileViewer 工具列在 light theme 變白(dark-mode override 失效)
+
+**對應規則**:`color.spec.md`;`node_modules/@qijenchen/design-system/ds-canonical/rules/ui-development.md`「Tailwind 5 條核心」「shadow 一律用 `--elevation-*` token」;元件 spec 的 dark mode 段
+
+---
+
+## 12. Overflow indicator 遮擋
+
+**Canonical source**: `patterns/horizontal-overflow/horizontal-overflow.spec.md`;`components/OverflowIndicator/`(若存在)
+
+**怎麼量**:
+1. 找有 horizontal-overflow 的 container(Tabs / ChipGroup 等)
+2. 檢查 fade mask 寬度 + 位置:
+   - fade mask 應只蓋「視覺提示溢出」的範圍(通常 16–32px),不蓋完整 item
+   - 箭頭按鈕(若有)不該蓋住 item 的可讀部分(text / icon)
+3. 捲到最左 / 最右極端時,對應邊的 fade mask / 箭頭應消失(無溢出就無提示)
+
+**合格標準**:
+- fade mask 不蓋完整 item 的 text / icon → PASS
+- 箭頭按鈕不遮 item 可讀資訊 → PASS
+- 極端位置時對應邊指示器消失 → PASS
+
+**FAIL 範例**:Tabs 箭頭按鈕遮住第一個 Tab 一半 text;fade mask 寬度 80px 完全蓋掉邊緣 tab
+
+**對應規則**:`horizontal-overflow.spec.md`
+
+---
+
+## 13. 箭頭按鈕定位(Carousel / ImageViewer)
+
+**Canonical source**: 對應元件 spec(Carousel / ImageViewer);`patterns/overlay-surface/` 若箭頭浮在 content 上
+
+**怎麼量**:
+1. 找箭頭按鈕(prev / next)的位置
+2. 量:
+   - **兩箭頭對稱**:prev 離左邊距離 == next 離右邊距離(除 spec 明文 asymmetric)
+   - **不覆蓋 content**:箭頭 y 方向置中,x 方向在 content 外側或 overlay 層不蓋核心 content
+   - **箭頭到容器邊**:該距離應用 token(如 `--layout-space-tight`),非硬寫 px
+
+**合格標準**:
+- 左右對稱(±1px) → PASS
+- 不覆蓋 content 核心區 → PASS
+- 使用 token 非硬寫 px → PASS(可從「距離對稱 + 是標準 token 值」反推)
+
+**FAIL 範例**:Carousel prev 離左邊 8px、next 離右邊 16px(不對稱);箭頭 y 方向佔 content 垂直 1/3 高度並蓋住文字
+
+**對應規則**:對應元件 spec;`tokens/layoutSpace/layoutSpace.spec.md`
+
+---
+
+## 補充:如何處理「checklist 沒涵蓋但視覺上怪」的情況
+
+- 記為 `額外觀察`,附 screenshot 座標 + 描述(1-2 句)
+- 依 shared governance authority classifier 路由：純機械 coverage／治理補強由 P2E 自動處理；只有改變產品／UI／UX SSOT 且仍有真取捨才交 P2H 決定是否升級
+- **不直接寫成 FAIL**(checklist 是 SSOT,擴項需正式流程)
+- 若同類觀察累積 3+ 次跨元件出現 → 建議升級為第 14 項 checklist 並更新本 reference