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

package/ds-canonical/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 必先向 user 確認(SKILL.md Preconditions 項 3)
+- 合格標準若為 token → 對照「該元件 spec 宣告的 token 值」或 `tokens/*/` primitive;不是「看起來接近就算對」
+- **容差規範**:px 量測允許 ±1px(螢幕截圖 sub-pixel rounding);ratio 允許 ±5%;明文標「精確」的項目(如對稱)不給容差
+
+**記錄格式**(每項在 report 都長這樣):
+- `狀態: PASS / FAIL / 無法判定`
+- `實測: {量到的值}`
+- `預期: {token 值或 ratio}`
+- `差異: {若 FAIL,寫出 diff 和推測破壞規則}`
+- `對應規則: {CLAUDE.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
+
+**對應規則**:CLAUDE.md `# Consistency Audit 原則`(actual == canonical OR rationale-for-deviation)
+
+---
+
+## 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 + `.claude/rules/ui-development.md`「建立 UI 前必讀」 layout-space token
+
+---
+
+## 3. 水平 gap 實際值 == gap token 宣告值(hover bg 不可吃掉)
+
+**Canonical source**: CLAUDE.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(違反 CLAUDE.md「同 flex 列幾何鐵律」)
+
+**FAIL 範例**:FileItem 2026-04-19 bug,Button hover-bg 24px 超出 16px box,`gap-2`(8px)實際剩 ~4px
+
+**對應規則**:`.claude/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;`.claude/rules/ui-development.md`「元件 Props 命名」「常用 icon canonical」(若箭頭用錯 icon);`.claude/rules/ui-development.md`「建立 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`;`.claude/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;`.claude/rules/ui-development.md`「建立 UI 前必讀」 → uiSize token
+
+---
+
+## 9. 跨 OS 一致 scrollbar
+
+**Canonical source**: `.claude/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 寬度
+
+**對應規則**:`.claude/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`;`.claude/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 句)
+- 交 user 決定是否升級為 checklist 項目
+- **不直接寫成 FAIL**(checklist 是 SSOT,擴項需正式流程)
+- 若同類觀察累積 3+ 次跨元件出現 → 建議升級為第 14 項 checklist 並更新本 reference

package/ds-canonical/skills/visual-audit/references/world-class-benchmarks.md

@@ -0,0 +1,198 @@
+# Visual Audit — 世界級對照 benchmark
+
+本檔為 SKILL.md Phase 1 各 checklist 項「合格標準」的**外部參考錨**。DS 內既有 spec / token 是第一順位 canonical;**本檔是 spec 沒寫、或需要補世界級 rationale 時的次級參考**。
+
+**使用原則**:
+- 合格標準優先走 DS 內 spec / token(actual == canonical)
+- DS spec 沒寫時,本檔提供世界級 idiom 作「可類推的合理區間」
+- 本檔數值**不可取代** DS 規則,只提供「世界級通常怎麼做」的事實陳述
+- 看到 FAIL 但 DS 無明文 canonical → 用本檔指出「世界級通常 X,本元件偏離 X」,交 user 決定是補 spec 還是改 code
+
+---
+
+## 1. 4 邊邊距對稱 / 2. 垂直對稱(DatePicker / Menu / Dialog)
+
+| DS | 規範重點 | 數值 |
+|----|---------|------|
+| **Material 3 Date Picker** | 4 邊等距,top/bottom action bar 高度鏡射 | 12dp 四邊 |
+| **Apple HIG Date Picker(iOS / macOS)** | 精準 grid,4 邊 padding 等值 | 16pt 四邊 |
+| **Atlassian DatePicker** | `padding: 8px` 四邊 | 8px |
+| **Notion Menu** | 上下 padding 同值,sticky header 單獨佔空間 | 6px 上下 |
+
+**世界級 idiom**:**4 邊等 padding 是 default**;asymmetric 必有 rationale(sticky header / footer action bar / arrow space)。DS 若無明文 asymmetric → 4 邊應等。
+
+---
+
+## 3. 水平 gap(同 flex 列互動 slot)
+
+| DS | 規範重點 |
+|----|---------|
+| **Polaris ActionList / Menu** | item 之間 `gap-0`,每 item 自含 padding;inline action gap 8px |
+| **Material 3 Chip group** | 8dp gap between chips |
+| **Atlassian Button group** | 8px gap;ring/focus outline 限制在 box 內,不 overflow |
+| **Ant Design Space** | default `gap-8`,hover bg 限制 box 內 |
+
+**世界級 idiom**:**hover bg / ring / focus outline 不超出 slot box**,保護 gap token 如實呈現。這對齊 CLAUDE.md`# 同 flex 列的互動 slot 幾何鐵律`。
+
+---
+
+## 4. Overlay 定位(Popover / Tooltip / Badge)
+
+| DS | 規範重點 | 數值 |
+|----|---------|------|
+| **Material 3 Popover** | anchor 到 popover 最小 8dp spacing | 8dp |
+| **Atlassian Tooltip** | 6px offset from anchor | 6px |
+| **Polaris Popover** | 4px offset | 4px |
+| **Ant Design Tooltip** | 4px offset 預設,可 side-offset prop 調 | 4px |
+| **Material Badge(dot / number)** | 以 anchor 右上角為 center 定位,offset 用 anchor 尺寸比例 | (24dp 圖示)右上 8×8 dot 中心離 anchor 右上 (−4, +4) |
+
+**世界級 idiom**:
+- **side-offset 預設 4–8px**,tooltip 偏小(4–6)、popover 偏大(6–8)
+- **Badge 定位用相對比例**(anchor size × ratio),不硬寫 px(不同 anchor size 壞掉)
+- **不覆蓋 anchor content**——overlay 的存在是補充 anchor,不是替代
+
+---
+
+## 5. Typography baseline 對齊 / 6. Icon ↔ text gap
+
+| DS | 規範重點 | 數值 |
+|----|---------|------|
+| **Material 3 List Item** | icon 16dp 對齊 text cap-height 中心;gap 16dp | 16/16 |
+| **Polaris ResourceList** | icon 20px,gap 12px | 20/12 |
+| **Apple HIG Menu Item** | SF Symbols 與 text 用 `items-center`,gap 8pt | sym/8 |
+| **Atlassian Button with icon** | icon 16px,gap 8px | 16/8 |
+| **Notion MenuItem** | icon 18px,gap 8px | 18/8 |
+
+**世界級 idiom**:
+- **gap 8px** 是跨 DS 最常見值(Material 的 16dp 是 outlier,其 menu 本身較寬鬆)
+- **icon 與 text 用 `items-center`**(幾何中心),不是 `items-baseline`
+- **icon size 跟 text size 比例 ≈ 1:1**(16px icon 配 14-16px text),1:1.2 也 ok
+
+---
+
+## 7. 容器寬度 fill(Block vs Inline)
+
+| DS | 規範重點 |
+|----|---------|
+| **Material 3 TextField** | 預設 block,fill container;可 `style="width:auto"` 覆寫 |
+| **Polaris TextField** | 預設 100% fill |
+| **Ant Design Input** | 預設 100% fill(與 antd Form 整合) |
+| **Chakra Input** | 預設 100% fill |
+| **shadcn Input** | `w-full` class 預設 |
+
+**世界級 idiom**:
+- **field 類元件預設 block fill container**——consumer 常嵌 form layout,讓 field 填滿容器是合理 default
+- **Tag / Chip / Badge 類是 inline fit-content**
+- **File upload area 類(upload zone / drop zone)fill container**——這是拖放互動預期的
+
+---
+
+## 8. 同 row field 高度對齊
+
+| DS | field-height |
+|----|--------------|
+| **Material 3 Text field** | 40dp(dense)/ 56dp(standard) |
+| **Polaris TextField** | 32px(slim)/ 36px(medium) |
+| **Atlassian TextField** | 32px(default) |
+| **Apple HIG macOS** | 22pt(small)/ 28pt(regular)/ 36pt(large) |
+| **本 DS** | 28 / 36 / 44px(sm / md / lg) |
+
+**世界級 idiom**:**同 row field 用同一 size token**,混 size 是 bug(除非 spec 明文)。本 DS 的 36px md 對齊 Material dense(40dp)和 Polaris medium(36px),是 mainstream 值。
+
+---
+
+## 9. 跨 OS 一致 scrollbar
+
+| 平台 | native scrollbar 行為 |
+|------|--------------------|
+| **macOS** | 預設 overlay(不吃寬度),滾動時淡入 |
+| **Windows** | 預設 chunky(吃 ~15px 寬度),永遠可見 |
+| **Linux GTK** | 類似 Windows(吃寬度) |
+| **iOS / Android** | overlay |
+
+**世界級 idiom**:
+- **Web DS 用 overlay scrollbar 跨 OS 一致**(Radix ScrollArea / Ant Design Scrollbar 都這樣做)
+- **原因**:Windows native scrollbar 吃寬度會讓同一 page 在 Mac 和 Windows 上 layout 不同,違反「設計在任何平台視覺一致」
+
+對應 DS:`components/ScrollArea/` + CLAUDE.md「overflow 使用三規則」。
+
+---
+
+## 10. Zoom / step 幅度
+
+| App | 單次 zoom-in step |
+|-----|-----------------|
+| **Figma** | 約 1.1×(持續滾輪)/ `Cmd+=` 跳到 preset(50%/100%/200%) |
+| **Photoshop** | 1.2×(`Alt + 滾輪`)/ preset jumps |
+| **Adobe XD** | 1.1× 滾輪 |
+| **Sketch** | 1.1× 滾輪 |
+| **Google Maps** | 2× per step(但 maps 是 tile-based,不同場景) |
+| **PDF viewers(Preview / Acrobat)** | 1.25× |
+
+**世界級 idiom**:
+- **圖片 / 設計工具的滾輪 zoom 介於 1.1×–1.25×**
+- **跳大步(1.5× / 2×)只適合 tile-based 地圖**,不適合 image viewer
+- **跳太小(1.02×)user 要滑很久**
+- 本 DS 的 ImageViewer / FileViewer 應落在 1.1×–1.2×
+
+---
+
+## 11. Dark mode 對比
+
+| DS | 規範重點 |
+|----|---------|
+| **Material 3** | dark surface `#121212`,elevation 用 overlay 白色提亮(不同 layer 不同透明度) |
+| **Apple HIG dark** | system dark bg `#1c1c1e`,text `#ffffff` with 100% opacity;對比需 ≥ 4.5:1 |
+| **Polaris dark** | semantic token 反轉,shadow 改用 inverse-foreground 微提亮 |
+| **Atlassian ADG dark** | neutral palette 反轉;每 elevation level dark mode 都有對應 token |
+
+**世界級 idiom**:
+- **WCAG AA 對比 ≥ 4.5:1**(body text)/ 3:1(large text)
+- **Dark mode shadow 不消失**——要麼改用 overlay(Material 方式)要麼降低 opacity 仍保留
+- **永遠 dark 的工具列**(圖像編輯器、影片播放器)是世界級慣例(Photoshop、Premiere、YouTube Studio)——鎖住 `data-theme="dark"` 不跟全域切
+
+---
+
+## 12. Overflow indicator(Tabs / Chip)
+
+| DS | 規範重點 |
+|----|---------|
+| **Material 3 Tabs** | scrollable 模式 + fade mask 16dp,箭頭 40dp 寬度可點擊但視覺只佔 16dp |
+| **Polaris Tabs** | 溢出用「More」button 收納(不是 fade mask) |
+| **Atlassian Tabs** | 箭頭 overflow 按鈕,不蓋 text |
+
+**世界級 idiom**:
+- **fade mask 寬度 16–32px** 足夠提示「有更多」,不蓋完整 item
+- **箭頭按鈕用 overlay 層**(不佔 tab 寬度),不蓋 item 可讀部分
+- **極端位置(最左 / 最右)對應邊指示器消失**——不再有溢出就不再提示
+
+---
+
+## 13. 箭頭按鈕定位(Carousel / ImageViewer)
+
+| App / DS | 規範重點 |
+|---------|---------|
+| **Carousel.swiper.js default** | 箭頭離 container 邊 10px,y 方向 50%(置中),半透明 bg |
+| **Apple HIG Photos** | 箭頭隱藏於 hover,位置 container 外側 12pt |
+| **Figma thumbnail grid** | 無箭頭,用滑鼠拖曳(不同範式) |
+| **Google Photos lightbox** | 箭頭 y-center,離 container 邊 16px,40×40 hit area |
+| **Ant Design Carousel** | 箭頭 y-center,離 container 邊 12px |
+
+**世界級 idiom**:
+- **兩箭頭對稱(prev 離左 == next 離右)**
+- **y 方向 content 垂直置中**(y=50%)
+- **不蓋核心 content**——寧可半透明 bg + 箭頭偏外,也不讓箭頭 shadow content text
+- **箭頭到邊用 token**,不硬寫 px(避免不同 size carousel 比例跑掉)
+
+---
+
+## 通用:如何引用本檔的 benchmark
+
+在 audit report FAIL 項寫:
+```
+對應規則: DS 無明文 canonical → 世界級對照見 world-class-benchmarks.md §N
+Benchmark: Material/Polaris/Atlassian 通常 X(本元件為 Y)
+建議討論: 是補 spec rationale 還是調向世界級 X
+```
+
+**不可**單以本檔為判決依據 FAIL(DS 內 spec 為第一順位);本檔是**補 rationale 的參考錨**,不是 canonical。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qijenchen/design-system",
-  "version": "0.1.0-beta.10",
+  "version": "0.1.0-beta.13",
   "private": false,
   "description": "World-class design system — components, patterns, tokens, hooks (single source of truth for team distribution).",
   "type": "module",
@@ -8,14 +8,16 @@
   "files": [
     "dist",
     "src/**/*.{tsx,ts,css}",
+    "src/**/*.spec.md",
     "!src/**/*.stories.tsx",
     "!src/**/*.anatomy.stories.tsx",
     "!src/**/*.principles.stories.tsx",
-    "!src/**/*.spec.md",
     "!src/**/*.spec.ts",
     "!src/**/*.test.ts",
     "README.md",
-    "scripts"
+    "CLAUDE.md",
+    "ds-canonical",
+    "cli-init.mjs"
   ],
   "exports": {
     ".": {
@@ -29,10 +31,11 @@
     },
     "./styles/tokens.css": "./src/styles/tokens.css",
     "./styles/tokens": "./src/styles/tokens.css",
-    "./styles/preset.css": "./src/styles/preset.css",
-    "./styles/preset": "./src/styles/preset.css",
     "./package.json": "./package.json"
   },
+  "bin": {
+    "qijenchen-ds-init": "./cli-init.mjs"
+  },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -76,6 +79,7 @@
     "embla-carousel-react": "^8.6.0",
     "lucide-react": "^0.577.0",
     "react-day-picker": "^9.14.0",
+    "react-is": "^18.0.0 || ^19.0.0",
     "react-zoom-pan-pinch": "^4.0.3",
     "recharts": "^3.8.1",
     "sonner": "^2.0.7",

package/src/components/Accordion/accordion.spec.md

@@ -0,0 +1,114 @@
+---
+component: Accordion
+family: composite
+variants: {}
+sizes: {}
+traits:
+  - hasInteractiveStates
+  - isStructural
+benchmark:
+  - Radix Accordion primitive: github.com/radix-ui/primitives/tree/main/packages/react/accordion
+  - MUI Accordion: github.com/mui/material-ui/tree/master/packages/mui-material/src/Accordion
+  - Ant Design Collapse: github.com/ant-design/ant-design/tree/master/components/collapse
+  - Carbon Accordion: github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Accordion
+---
+
+# Accordion 設計原則
+
+## 定位
+
+Accordion 是**垂直堆疊、可收合的多區塊容器**——每個 item 由 header（含 chevron）點擊切換展開 / 收合狀態。適合「多段內容,多數時間只想看其中一段」的情境。
+
+**實作基礎**：shadcn/ui 結構 + Radix Accordion primitive。本 DS 保留 shadcn 的 `Accordion / AccordionItem / AccordionTrigger / AccordionContent` API,視覺全改本 DS token,移除 shadcn 預設的 hover underline(web 早期 link style,與現代 SaaS 質感不符)。
+
+**Layout Family**：非上述 family — composite / multi-section（多個 AccordionItem 垂直堆疊，自 own layout）。
+
+---
+
+## 何時用
+
+- **FAQ / 說明**：常見問題、使用教學（預設全收合，使用者展開有興趣的）
+- **設定分組**：一般 / 通知 / 安全 / 付款等多節 settings 頁（長 form 拆段）
+- **進階選項可隱藏**：預設展示主要欄位，「進階選項」收合起來避免壓力
+- **單邊 sidebar 多分類**：檔案樹、notion-style 工作區 sidebar
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 只有一個區塊要收合 | `<details>` 或自組 toggle | Accordion 是「多 item」pattern,單 item 無必要 |
+| 切換平行視圖（A / B / C 三選一）| `Tabs` | Tabs 是互斥切換,Accordion 是獨立收合(或單選) |
+| 複雜 sidebar 導航（深度 tree）| `TreeView` / `Sidebar` | Accordion 無 nested 結構 |
+| 收合整個浮層/側欄 | `Dialog` / `Sheet` / `Popover` | 那是浮層控制不是 inline 收合 |
+| 長列表只顯示 N 個 | 自組 「顯示更多」按鈕 | Accordion 不是「more / less」pattern |
+
+---
+
+## type：single vs multiple
+
+**`type="single"`**（預設推薦）：一次只能展開一個 item。展開新 item 自動收合前一個。適合 FAQ / 指南類(讀者看完一段再下一段)。
+
+**`type="multiple"`**：多個 item 可同時展開。適合 settings page / 工作 context(使用者同時比對多段)。
+
+**判斷法**：「使用者會不會想同時看兩段?」會 → multiple;不會 / 同時看反而混亂 → single。
+
+---
+
+## collapsible (配合 single)
+
+`single` 搭配 `collapsible={true}`:已展開的那個可以再點一次收合(回到「全部收合」狀態)。預設 `false`——已展開的無法再收合(必須保持有一個展開)。
+
+- **FAQ / 使用教學** → `collapsible={true}`(允許全收起,乾淨視覺)
+- **必須展開一個才合理** → `collapsible={false}`(罕見)
+
+---
+
+## 視覺規則
+
+- **AccordionItem 底線**:相鄰 item 以底 divider 分隔(視覺界定每一段)
+- **Trigger 文字**:正常閱讀色 + medium 字重(可掃視的 section heading 等級)
+- **Trigger hover**:文字色 tint 弱化,**不用 underline**
+- **Chevron**:朝下 → data-state=open 旋轉 180° → 朝上,transition 帶平滑
+- **Content 文字**:次要閱讀色—— 主資訊在 trigger,展開內容是補充
+- **焦點環**:鍵盤 focus 用 ring token(非自訂 outline)
+
+**為什麼 hover 不用底線**:shadcn 預設 `hover:underline` 是 web 早期 link convention,現代 SaaS(Notion / Linear / Stripe / Vercel)皆不使用。改用文字色 tint 弱化維持統一質感,同時保留可點擊提示——不變色會讓使用者不確定是否能點擊,比起「被誤以為是 link」的風險,「失去可點擊提示」的風險更高。
+
+完整 class / token 對照見 anatomy story(`ColorMatrix` + `SizeMatrix`)。
+
+---
+
+## 禁止事項
+
+- ❌ **不在 Accordion 內放另一個 Accordion**（巢狀會讓使用者迷失;用 TreeView 或拆頁）
+- ❌ **不寫「全部展開 / 全部收合」按鈕**（違反 accordion 節省空間的設計意圖;若需要此功能,改用 TreeView 或 DescriptionList）
+- ❌ **單一 item 不用 Accordion**（用 `<details>` 或自組 toggle;見「何時不用」）
+- ❌ **不用 Accordion 做主要導航**（主導航用 Tabs / Sidebar,Accordion 是 content-level 收合）
+- ❌ **AccordionContent 不放互動重焦點元素**（例:complex form / Dialog trigger;收合後焦點消失,但如果只是輸入欄位可以）
+
+---
+
+## A11y 預設
+
+Radix Accordion 自動處理:
+- **鍵盤**：Tab 到 trigger → Enter/Space 切換;ArrowUp/Down 在 trigger 間移動
+- **ARIA**：trigger `aria-expanded` / `aria-controls` 自動設置,content `role="region"` + `aria-labelledby`
+- **焦點**：收合時焦點停在 trigger,不會跳到隱藏 content 內
+
+Consumer 無需額外處理,保留 Radix `data-state` 屬性即可。
+
+---
+
+## 邊界狀態
+
+Empty state 由 consumer 處理(無 items 則不渲染);loading 狀態由 consumer 用 `<Skeleton />` 包;disabled state 詳 `../Field/field-controls.spec.md`;density 由 Radix 繼承。
+
+---
+
+## 相關
+
+- `../Tabs/tabs.spec.md` — 互斥切換視圖（非收合）
+- `../Dialog/dialog.spec.md` — 阻斷性浮層
+- `../Sheet/sheet.spec.md` — 側邊抽屜
+- `../TreeView/tree-view.spec.md` — 具層級結構的收合（Accordion 的巢狀延伸）
+- Radix Accordion primitive — `@radix-ui/react-accordion`