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

package/src/components/Checkbox/checkbox.spec.md

@@ -0,0 +1,344 @@
+---
+component: Checkbox
+family: 4
+variants: {}
+sizes:
+  sm:
+    when: "form field-height 28 / compact chrome / dialog / panel context"
+  md:
+    when: "default general UI"
+  lg:
+    when: "touch / prominent CTA / stakeholder-facing surface"
+traits:
+  - isSelectionMulti
+benchmark:
+  - Radix Checkbox primitive: github.com/radix-ui/primitives/tree/main/packages/react/checkbox
+  - Ant Design Checkbox: github.com/ant-design/ant-design/tree/master/components/checkbox
+  - MUI Checkbox: github.com/mui/material-ui/tree/master/packages/mui-material/src/Checkbox
+  - Polaris Checkbox: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Checkbox
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Checkbox 設計原則
+
+(Radio 共用本規格,詳見 `../RadioGroup/radio-group.spec.md`;本文件通用於兩者視覺與行為,名稱保留 Checkbox 為主體)
+
+## 定位
+
+Checkbox 和 Radio 是**表單內的選擇控件**，視覺語言完全一致，差異只有形狀和語意。兩者都綁在 form state、隨 submit 才生效（非即時套用——這是與 Switch 的根本差異，見下「與 Switch 的分界」）。
+
+**Layout Family**：非上述 family — self-contained primitive（獨立視覺，無 slot 結構）。
+
+**實作基礎**：Checkbox 基於 Radix Checkbox、Radio 基於 Radix RadioGroup（皆 shadcn 包裝 + 橋接 DS token）。
+
+| | Checkbox | Radio |
+|---|---|---|
+| 形狀 | `rounded-md`（方） | `rounded-full`（圓） |
+| 指示器 | Check icon | Filled dot |
+| 語意 | 獨立 toggle（多選） | 互斥選擇（單選，必須在 RadioGroup 內） |
+
+---
+
+## 何時用 Checkbox
+
+- **表單多選**：通知類型、權限授予、標籤群組
+- **單一同意**：服務條款、隱私政策、訂閱行銷訊息（勾選才送出表單）
+- **indeterminate 半選**：階層式表格的「全選」checkbox 反映部分子項已選
+- **部分綁定的布林欄位**：form 裡的 is_public / is_featured（**但若是即時套用 → 用 Switch**）
+
+## 何時用 Radio
+
+- **表單單選且 2-5 個選項全部可見**：付款方式、訂閱方案、權限角色、票種
+- **選項需要描述文字**（法律條款、方案比較、feature list）
+- **決策節點**（使用者需要對比評估才能選）
+
+**Radio vs Select 的分界詳見 `../Select/select.spec.md`「與 RadioGroup 的分界」**（SSOT 在 Select spec）。
+
+## 何時不用（Checkbox / Radio 皆不適合）
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 布林且即時套用（bluetooth、notification enable）| `Switch` | 見下「與 Switch 的分界」 |
+| 單選但 6+ 選項 / 空間受限 | `Select` | Radio 全可見會佔滿頁面 |
+| 多選但 6+ 選項 / 空間受限 | `Combobox` | Checkbox stack 全可見會佔滿頁面 |
+| 階層結構（部門 / 資料夾）| `TreeView` | Checkbox 是平面選項 |
+| 純視覺切換（側欄收合）| `Button pressed` | 切換狀態屬於介面行為，不是 form value |
+
+---
+
+## 與 Switch 的分界
+
+兩者都是布林 on/off，常被誤用互換。判斷**不是視覺形狀**，而是以下三個角度——**任何一個明確傾向哪邊就選哪邊**：
+
+### 1. 套用時機
+
+- **Checkbox**：值隨 form submit 才套用。使用者勾選 → 按「儲存」→ 生效。中途可反悔
+- **Switch**：值即時套用。使用者切換 → 立刻生效（呼叫 API / 改 URL / 觸發副作用）。沒有「取消」
+
+### 2. 心智模型
+
+- **Checkbox**：選擇 / 同意——「我選這個項目」、「我同意這個條件」。與書面表單類比
+- **Switch**：開啟 / 關閉——「這個功能我要開」、「這個設定我要關」。與物理開關（牆上 light switch、iPhone settings 開關）類比
+
+### 3. 結果可逆性的即時感
+
+- **Checkbox**：勾選不代表生效——送出前可反悔。視覺語言強調「尚未確定」
+- **Switch**：切換即結果——使用者按下那刻就改變系統狀態。視覺語言強調「現在是這樣」
+
+### Fallback heuristic
+
+- 在 form 裡、旁邊有 submit button / cancel button → **Checkbox**
+- 獨立的 inline control、旁邊沒有 submit 流程 → **Switch**
+
+### 情境對照表
+
+| 場景 | 選哪個 | 原因 |
+|------|-------|------|
+| 我同意服務條款 | Checkbox | 隨 form submit 才成立 |
+| 通知類型勾選（email / SMS / push）| Checkbox | form 設定，按儲存才套用 |
+| Bluetooth on/off | Switch | 立刻開 / 關，不經 submit |
+| Wi-Fi on/off | Switch | 立刻生效 |
+| Dark mode 切換 | Switch | 即時套用 |
+| Push 通知開關（settings 頁）| Switch | 立刻生效 |
+| 訂閱行銷訊息 | Checkbox | form 內，按儲存才套用 |
+| is_public / is_featured（編輯表單）| Checkbox | form field，送出才生效 |
+| is_public（admin 即時切換）| Switch | 切換立刻套用 |
+
+**本節是 Checkbox vs Switch 的 SSOT**，未來 Switch 建立 spec 時用一行 pointer 指回本節。
+
+---
+
+## 尺寸
+
+三種尺寸（sm/md = 16px、lg = 20px），對齊 icon 系統。sm 和 md 視覺相同，純粹是命名 mapping 讓消費者直接傳同一個 size。
+
+| Size | 控件尺寸 | 內部 icon | 配對 field |
+|------|---------|----------|-----------|
+| sm | 16px | 12px | field sm |
+| md | 16px | 12px | field md |
+| lg | 20px | 16px | field lg |
+
+### 為什麼不完全對齊 `--field-height-*`
+
+- **現況**:控件 sm=16 / md=16 / lg=20px(不等於 `--field-height-sm/md/lg` = 28/32/36px)
+- **Rationale**:Checkbox 控件是**選擇指示器**(indicator),不是容器;field-height 是「可編輯 control 的容器高度」,indicator 視覺上要明顯小於容器,才符合「選項前有個小方框」的心智模型。控件本體走 icon tier(sm/md=16, lg=20),行高對齊透過 SelectionItem 的 `py = (field-height - 1lh) / 2` 保證(控件垂直置中於 1lh 容器)
+- **世界級對照**:Material 3 Checkbox = 18px touch target 內的 18px container / Ant Design Checkbox = 16px 控件 / Polaris Checkbox = 16px——全部獨立於 field-height,控件 icon 與 field 分離是共識 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+---
+
+## Label 對齊
+
+Checkbox/Radio 不內建 label。Label 組合使用 `SelectionItem` 元件。
+
+對齊機制：
+1. 外層 `<div>` 設 `text-body` / `text-body-lg`（建立 line-height context）
+2. 控件包在 `h-[1lh]` 的容器內（容器高度 = 一行文字高度）
+3. `flex items-center`（控件在文字行高內垂直置中）
+4. 外層 `flex items-start`（多行時控件對齊第一行）
+
+`1lh` 在 `<div>` 上正常繼承，改字體自動重算。
+
+---
+
+## SelectionItem 佈局
+
+垂直排列和水平排列共用 `SelectionItem`。
+
+| | 垂直 | 水平 |
+|---|---|---|
+| Item 間距 | 0（padding 處理） | 24px（gap-6） |
+| Item padding | `py = (field-height - 1lh) / 2` | 同左 |
+| Label ↔ Description | 2px（`--item-gap-label-desc-reading` / `-reading-lg`,size-aware） | 同左 |
+| 單行高度 | = field-height（對齊 Input） | 同左 |
+| 多行高度 | padding 維持不變，總高度 = `1lh × line-count + py × 2` | — |
+
+---
+
+## Clamp 政策(Label / Description 行數)
+
+| Prop | 預設 | 理由 |
+|---|---|---|
+| `labelMaxLines` | `'none'`(∞) | Form 欄位的選項標籤可能很長,絕不可截斷 |
+| `descMaxLines` | `'none'`(∞) | Form 欄位的補充說明、條款、隱私聲明必須完整呈現 |
+
+**為什麼預設不截斷?**
+
+Checkbox / Radio 在 form 內承載的常常是:
+- **法律條款**(「我同意服務條款 + 隱私政策...」)
+- **隱私聲明**(「允許 Cookie 用於...」)
+- **複雜條件描述**(「啟用此功能會...」)
+
+**任何截斷都是違法或誤導**——使用者必須完整看到他正在同意什麼。MenuItem 的「掃視優先」不適用,SelectionItem 的核心訴求是「**完整閱讀後同意**」。
+
+### Per-instance override
+
+若 consumer 有合理理由(例如 settings 頁的選項列表想截斷過長 label 維持掃視節奏),可以顯式覆寫:
+
+```tsx
+<SelectionItem labelMaxLines={1} descMaxLines={2} ... />
+```
+
+**注意:不能傳 `undefined` 表達「不截」**——React 的 destructure default 會把 undefined 當「沒傳」、fallback 到預設值。要明確表達「不截」傳 `'none'`(雖然語意等同預設,但更明確)。
+
+### 為什麼不像 MenuItem 強制截斷?
+
+| | MenuItem | SelectionItem |
+|---|---|---|
+| 使用情境 | 浮層選單,挑一個 | Form 內,**同意**或**選擇**內容本身 |
+| 內容性質 | 選項名稱(短) | 條款 / 聲明 / 條件描述(可長) |
+| 截斷後果 | 失去 context,但可重開選單看完 | **法律或道德問題**(同意了沒看到的內容) |
+| 預設政策 | label / desc 都 `1`(掃視優先) | label / desc 都 `'none'`(完整閱讀優先) |
+
+---
+
+## 狀態
+
+### Checkbox
+
+| 狀態 | 邊框 | 底色 | 指示器 |
+|------|------|------|--------|
+| unchecked | border | surface | 無 |
+| checked | primary | primary | white check |
+| indeterminate | primary | primary | white minus |
+| hover unchecked | neutral-6 | surface | 無 |
+| hover checked | primary-hover | primary-hover | white check |
+| hover indeterminate | primary-hover | primary-hover | white minus |
+| disabled unchecked | 無 | neutral-2 | 無 |
+| disabled checked | 無 | neutral-2 | fg-disabled check |
+| disabled indeterminate | 無 | neutral-2 | fg-disabled minus |
+
+### Indeterminate（半選）
+
+`checked="indeterminate"` 表示「部分子項被選中」。視覺上與 checked 相同（藍底白圖示），只是圖示從 Check 換成 Minus。
+
+典型場景：SelectMenu 的「全選」checkbox——當部分選項被勾選時顯示 indeterminate。
+
+Indeterminate 是由父層邏輯控制的狀態，Checkbox 本身不會自動進入 indeterminate——必須明確傳入 `checked="indeterminate"`。
+
+### Radio
+
+| 狀態 | 邊框 | 底色 | 指示器 |
+|------|------|------|--------|
+| unchecked | border | surface | 無 |
+| checked | primary | surface | primary dot |
+| hover unchecked | neutral-6 | surface | 無 |
+| hover checked | primary-hover | surface | primary-hover dot |
+| disabled unchecked | 無 | neutral-2 | 無 |
+| disabled checked | 無 | neutral-2 | fg-disabled dot |
+
+---
+
+## Controlled / Uncontrolled API(M26)
+
+繼承 Radix `CheckboxPrimitive.Root` triplet:`checked` / `defaultChecked` / `onCheckedChange`(Radix forward 不改名)。Form 用 `name` + `value`(native form contract)。3 模式:
+
+- **Uncontrolled**:只傳 `defaultChecked`,DOM 自管 — 適合表單 native submit
+- **Controlled**:傳 `checked` + `onCheckedChange`,React state 主導 — 適合需即時聯動其他欄位
+- **Read-only**:傳 `checked` 不傳 `onCheckedChange` → Radix 視同 controlled disabled state
+
+CheckboxGroup 額外提供 `value` / `defaultValue` / `onValueChange`(string[] 多選 array)— group-level controlled 模式;item 不傳獨立 onChange(group 統一 dispatch)。
+
+---
+
+## 群組模式(CheckboxGroup)
+
+**`<CheckboxGroup>`** 是多選 Checkbox 的 layout primitive,跟 `<Checkbox>` **同資料夾**(合併於 2026-04-21,原單獨 `CheckboxGroup/` folder 併入)。對齊 Ant Design `Checkbox.Group` / Chakra `CheckboxGroup` / Mantine `Checkbox.Group` 世界級:standalone + group 家族同資料夾。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+### Canonical 鐵律:零外部 gap
+
+**垂直 CheckboxGroup item 之間沒有外部 gap**。間距完全靠每個 Checkbox 內部的 SelectionItem `py = (field-height - 1lh) / 2` 公式生成 — 單行高度對齊 field-height,多 row stacked 時 row-to-row 自然有 py × 2 的呼吸空間。
+
+**禁止**外層加 `gap-y-*` / `space-y-*` / margin → double padding,違反 canonical。
+
+### 為什麼 zero gap valid（不違反 inline-action canonical）
+
+SelectionItem py 公式保證:
+1. 單行 checkbox 高度 = field-height(對齊 Input 高度,row align)
+2. 多行堆疊時相鄰 row 的 py 各自擴散 = 2×py 真實視覺呼吸空間
+3. Density 切換時 py 自動跟 field-height 縮放,間距等比例變化
+
+外加 gap → double-padding 視覺斷裂。
+
+### 世界級對照
+
+- **Atlassian / Radix**:row 間距由 item 自身 py 擁有,group 無 gap
+- **Ant Design / Chakra**:依賴 Checkbox 自帶 line-height,group 無 spacing 或預設 0
+- **流派:row 高度定義 gap,不加外部 gap** — 本 DS 採此
+
+### CheckboxGroupContext(隔離 fieldCtx)
+
+Group 內的 Checkbox 透過 `CheckboxGroupContext` 知道自己在 group 裡:
+- `insideGroup && insideField` → 保留 label(每個 Checkbox 是 group 內選項)
+- `insideField && !insideGroup` → 抑制 label(let FieldLabel 接管,solo-in-Field 場景)
+
+每個 Checkbox 自己的 `id` 透過 `useId` 生成(不共用 fieldCtx.id)→ 修了 2026-04-21「點擊只 toggle 第一個」bug。
+
+### Orientation
+
+| 值 | Layout | 典型場景 |
+|---|---|---|
+| `vertical`(預設) | `grid`(無 gap,靠 SelectionItem py) | 篩選條件、偏好設定、權限組 |
+| `horizontal` | `flex flex-wrap gap-4` | 短 label 並排(Email / Push / SMS) |
+
+Horizontal 需 `gap-4` 因 row 的 py 不擴散到左右。
+
+### Field 整合
+
+`<CheckboxGroup>` 有 `fieldLayout: 'block'` 屬性(跟 RadioGroup 一致),在 `<Field orientation="horizontal">` 內 control area 自動切 `items-start` + padding-top 對齊第一個 item 的 label 第一行。
+
+### 用法範例
+
+```tsx
+<CheckboxGroup>
+  <Checkbox label="待處理" defaultChecked />
+  <Checkbox label="進行中" defaultChecked />
+  <Checkbox label="已完成" />
+</CheckboxGroup>
+
+<Field orientation="horizontal">
+  <FieldLabel>通知方式</FieldLabel>
+  <CheckboxGroup orientation="horizontal">
+    <Checkbox label="Email" />
+    <Checkbox label="Push" />
+    <Checkbox label="SMS" />
+  </CheckboxGroup>
+</Field>
+```
+
+---
+
+## 禁止事項
+
+- ❌ Radio 不可單獨使用——必須在 RadioGroup 內
+- ❌ Checkbox 不內建 label——label 組合用 SelectionItem
+- ❌ 垂直 CheckboxGroup 加 `gap-y-*` / `space-y-*`——違反 zero-gap canonical
+- ❌ 多選一不用 Checkbox——用 Radio 或 Select
+- ❌ 即時套用的布林開關用 Checkbox——用 Switch（見「與 Switch 的分界」）
+- ❌ Form 內同意條款用 Switch——條款是「勾選送出才成立」的書面行為，用 Checkbox
+
+---
+
+## 相關
+
+- `../Switch/switch.spec.md` — 即時套用的布林開關（Checkbox vs Switch SSOT 在本 spec「與 Switch 的分界」）
+- `../Select/select.spec.md` — 單選下拉（Radio vs Select SSOT 在 Select spec）
+- `../Combobox/combobox.spec.md` — 多選下拉（Checkbox stack vs Combobox 對照在 Combobox spec）
+- `../RadioGroup/radio-group.spec.md` — Radio 的 group 容器 + 結構對稱 reciprocal
+- `../SelectionControl/selection-item.spec.md` — Checkbox / Radio 共用的 SelectionItem 佈局 primitive（本 spec 的 Clamp 政策為其 SSOT）
+- `../Field/field-controls.spec.md` — Field Control 共用規則
+
+## A11y 預設
+
+**ARIA / Pattern**:繼承 Radix `checkbox` primitive a11y 預設(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/checkbox#accessibility)。
+
+**Focus**:Radix primitive 自管 focus trap / restoration / visible ring(`outline: 2px solid var(--ring)` per design-system focus-visible canonical)。
+
+**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `menu-item.spec.md`
+- `segmented-control.spec.md`

package/src/components/Chip/chip.spec.md

@@ -0,0 +1,237 @@
+---
+component: Chip
+family: 3
+variants: {}
+sizes: {}
+traits:
+  - hasInteractiveStates
+benchmark:
+  - MUI Chip: github.com/mui/material-ui/tree/master/packages/mui-material/src/Chip
+  - Ant Design Tag: github.com/ant-design/ant-design/tree/master/components/tag
+  - Carbon Tag: github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Tag
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Chip 設計原則
+
+## 定位
+
+Chip 是 **Material Design Filter Chip** 的實作——用於從多個選項裡**選取任意數量（多選）或單一選項（單選）**，視覺上是一排獨立的 pill。
+基於 Radix ToggleGroup，橋接設計系統 token。
+
+**Layout Family**：CLAUDE.md 4-Family Model **Family 3（Pill Layout）action trigger sub-profile**。內部結構 `[startIcon?] [<span px-1>label</span>] [suffix badge? + endIcon?]` 繼承 Button canonical（code docblock 明寫「鏡射 Button」）。SSOT 在 `components/Button/button.spec.md`「Pill Layout」章節。Chip 特有視覺（`rounded-full`、單一固定 `h-field-sm` size、hover/selected 色彩規則）寫在本 spec 下方章節。
+
+---
+
+## 何時用
+
+- **Filter panel 的 tag 選取**：語言、狀態、類別、標籤
+- **Toolbar 上的多選過濾**：列表頁、搜尋結果頁
+- **標籤選取**：為內容選擇適合的 tags
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 2–5 個互斥單選且視覺要 compact 連體 | `SegmentedControl` | Chip 各自獨立，SegmentedControl 連體表達互斥更強 |
+| 單一按鈕 on/off | `Button pressed` | 單個 toggle 不需要 Chip 的 group 語意 |
+| 純顯示不可互動 | `Tag` | Chip 是 control，Tag 是 label |
+| 計數 / 狀態指示器（不可互動）| `Badge`(`../Badge/badge.spec.md`) | Badge 是純視覺 indicator(count / status dot),Chip 是 selectable control |
+| 使用者已輸入的 token（收件人、filter summary）| Input chip 系列（`LinkInput` / `PeoplePicker`）| 那些是 input 內的 token，不是獨立選擇器 |
+
+---
+
+## 與 SegmentedControl 的差異
+
+| | Chip | SegmentedControl |
+|---|---|---|
+| 選擇語意 | 多選為主，可選單選 | 固定單選（radio） |
+| 視覺連接 | 各自獨立 pill，`gap-2` | Items 連體，`-ml-px` border 重疊 |
+| 圓角 | `rounded-full`（M3 身份特徵）| `rounded-md` |
+| 規模 | 可能幾十個，必須處理 overflow | 2–5 個，規模固定 |
+| Field 整合 | 不塞進 Field（規模不對） | 塞得進 Field（`useFieldContext()` 讀 size）|
+| Overflow | `wrap` / `scroll` / `menu` 三模式 | 不支援 |
+
+---
+
+## 內部結構（鏡射 Button）
+
+```
+[startIcon?]  [<span px-1>label</span>]  [<span gap-1>badge? + endIcon?</span>]
+  ↑              ↑                          ↑
+  16px           text-body leading-compact   badge / LucideIcon
+  │─── gap-1 ─│─── gap-1 ──────────────────│
+```
+
+- Slot 間 `gap-1`（4px），與 Button 一致
+- Label 包 `<span className="px-1">`，與 Button 一致
+- Suffix wrapper `<span className="inline-flex items-center gap-1">`，與 Button 一致
+- Icon size：`16`（固定，因為 Chip 只有一個 size）
+
+**支援的 slot**：
+| Slot | 說明 |
+|---|---|
+| `startIcon` | `LucideIcon`，最多一個 |
+| `badge` | 通常是計數指示器（「React 24」「進行中 3」）|
+| `endIcon` | 用於 chip 點下去會展開更多的少見情境（如 `ChevronDown` 開 popover 選子分類）|
+
+**不支援**：`danger` / `loading` / `pressed` / `asChild` / `iconOnly` / `dismiss` — 這些是其他元件的職責，混進 Chip 會模糊邊界。
+
+### 為什麼不支援 dismiss X
+
+Filter chip 的「移除這個 filter」動作已由「再點一次 deselect」承擔。加 dismiss X 等於同一動作有兩個 affordance，違反 Hicks's Law。Material 3 / Atlassian / Polaris filter chips 都不提供 dismiss。
+
+**需要 dismiss 的情境** = active filter token / 使用者輸入 token，那是 Input chip 的語意（走 `LinkInput` / `Tag` + `onDismiss` 路線），不是 Filter chip。
+
+### 為什麼不需要 checkmark-on-selected
+
+Material 3 filter chip 在 selected 時會把 startIcon 換成 `Check`。我們不做，因為視覺層已經用 **primary-hover border + text + `primary-subtle` 背景**明確表達 selected 狀態，再加 icon 是冗餘信號。
+
+---
+
+## Size — 只有一種
+
+Chip **只有一個 size**，對應 `h-field-sm`（md density 28px / lg density 32px）。
+
+對齊 Material 3 / Atlassian / Polaris / Ant Design 的世界級共識：chips 使用單一高度，不暴露 size prop。使用場景（filter bar、tag panel）高度一致，多 size 不增加表達力、只增加 API 負擔。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+**為什麼用 `--field-height-sm` 不用獨立 token**：chip 高度仍需 density 感知，沿用 `field-height-sm` 保證跟 Button / Input 的 density 節奏一致。若未來需要跟 form 高度解耦再新增 `--chip-height`。
+
+---
+
+## State
+
+對應你設計中的四狀態：
+
+| State | 樣式 |
+|---|---|
+| **Default** | `bg-surface border-border text-foreground` |
+| **Hover**（未選）| `hover:border-border-hover`（對齊 Input / SegmentedControl hover 的 border 加深一階）|
+| **Selected** | `bg-primary-subtle border-primary-hover text-primary-hover`（對齊 `semantic.css:67` canonical 選中規則）|
+| **Disabled** | `cursor-not-allowed text-fg-disabled`，border 維持 `border-border` 不變色 |
+
+Hover 和 selected 的色彩都對齊系統 canonical 規則，跟 SegmentedControl / Input / Tabs underline 使用同一套 primary-hover token，保持選中語意的視覺統一。
+
+---
+
+## ChipGroup — Chip 必須在群組內
+
+Chip **不可單獨使用**，必須放在 `<ChipGroup>` 裡。跟 SegmentedControl / RadioGroup 的結構對齊。
+
+```tsx
+<ChipGroup type="multiple" value={tags} onValueChange={setTags}>
+  <Chip value="react">React</Chip>
+  <Chip value="vue">Vue</Chip>
+  <Chip value="svelte">Svelte</Chip>
+</ChipGroup>
+```
+
+### Type
+
+| Type | 語意 | 預設 |
+|---|---|---|
+| `multiple` | 可勾選任意數量（checkbox 語意）| ★ **預設**（filter 最常見） |
+| `single` | 互斥單選（radio 語意）| 從 tag 群裡選唯一主要 tag |
+
+### Layout
+
+Chip 的 overflow 處理有三種模式：
+
+| Layout | 行為 | 何時用 |
+|---|---|---|
+| `wrap` ★default | 塞不下時換到下一排 | 大多數情況（filter panel / tag cloud） |
+| `scroll` | 單行、水平滾動，邊緣 fade mask 指示還有內容 | Toolbar / header filter 必須單行 |
+| `menu` | 塞不下的 chips 收進 `⋯` dropdown menu | 單行且需要完整選項可見（ListView toolbar）|
+
+**詳見 overflow 段落。**
+
+---
+
+## Overflow 三種模式
+
+### wrap — 預設
+
+塞不下時 chip 換到下一排。最簡單、最常見——filter panel 裡 chip 數量不定時用這個。實作細節（flex-wrap / gap token）見 `.tsx`。
+
+### scroll — 滾動 + fade mask + scroll arrows
+
+- 外層 `overflow-x-auto scrollbar-none`
+- 邊緣用 `mask-image: linear-gradient(...)` 做漸變透明，指示還有內容在視窗外
+- Mask 依滾動位置動態調整：
+  - 不可滾動 → 無 mask
+  - 可往右滾（atEnd = false）→ 右邊 fade
+  - 可往左滾（atStart = false）→ 左邊 fade
+  - 雙向可滾 → 兩側 fade
+- **左右 scroll arrow buttons**：`atStart === false` 顯示左 arrow、`atEnd === false` 顯示右 arrow，點擊捲動 80% 容器寬度（smooth）
+- 使用 `useScrollEdges()` hook 追蹤 scroll state
+
+**為什麼用 mask 不用 gradient overlay**：mask 淡化的是 chips 本身的 alpha，會自動融合任何背景色（dark mode / card / surface 都自動正確）。Gradient overlay 需要寫死 `from-surface` 等具體色，遇到不同背景就漂移。
+
+**為什麼要 scroll arrow buttons**（與 Tabs scroll 同規則）：鍵盤用方向鍵、trackpad 用兩指滑、滑鼠滾輪使用者只能靠 arrows（`Shift+wheel` 太隱晦）。Material 3 / Ant Design / Carbon 都這麼做。
+
+### menu — 收進 DropdownMenu
+
+- 所有 Chip 渲染在 DOM 中（保留 Radix ToggleGroup 的 a11y）
+- 用 `useOverflowIndices()` 偵測哪些 chip 溢出
+- 溢出的 chip 套 `invisible`（`visibility: hidden`，不佔 hit test 但保持 layout）
+- 右側渲染 `<Button variant="text" iconOnly startIcon={MoreVertical} />`(overflow menu canonical icon,見 CLAUDE.md「常用 icon canonical」;對齊決策 10)
+- 點擊開 DropdownMenu，內容是 `DropdownMenuCheckboxItem` 陣列，checked 狀態跟 ChipGroup 當前 value 同步
+- 點 menu item 時呼叫 ChipGroup 的 `onValueChange`，更新的值同時反映到可見 chips 和 menu checked state
+
+**a11y 保留機制**：因為溢出的 chips 只是視覺隱藏、仍在 DOM，Radix ToggleGroup 的 roving tabindex 依然可以 focus 它們。鍵盤使用者可以透過 Tab 進入 ChipGroup，用方向鍵在所有 chips 之間導覽（含視覺隱藏的），或用 Tab 到 `⋯` 按鈕用 dropdown 介面。兩條互動路徑同時可用。
+
+**menu 模式需要 controlled ChipGroup**：菜單 items 透過 `onValueChange` 觸發選擇變化，因此 ChipGroup 必須傳 `value` + `onValueChange`（controlled）。uncontrolled mode（`defaultValue`）的 menu 模式無法讓 menu items 與 chips 同步狀態。
+
+---
+
+## 禁止事項
+
+- ❌ Chip 單獨使用——必須在 ChipGroup 內
+- ❌ 用 `danger` / `loading` / `pressed` / `asChild` / `iconOnly`——不支援
+- ❌ 加 dismiss X——用 Input chip / Tag 代替
+- ❌ 手動改 `data-state` 或 `aria-pressed` / `aria-checked`——由 Radix 管理
+- ❌ 把 Chip 塞進 Field 當 form control——規模語意不對，用 SegmentedControl
+- ❌ Menu 模式搭配 uncontrolled（只給 `defaultValue`）——menu items 無法同步狀態，TS 不擋但 runtime 會看到 menu 勾選失效
+
+## 為何無 Inspector
+
+Chip 決策維度是「selection 行為(single / multi / menu)」× layout(連體 / 間隔)× overflow——已在 `SelectionMatrix` / `LayoutMatrix` 兩張結構矩陣覆蓋。互動 Inspector 無法呈現 selection model 的差異(需要 side-by-side 對照)。
+
+ColorMatrix 已建:展示 default / hover / selected / disabled 四狀態的 bg / border / text / icon token 對照,採 pill-canonical 規則(`--primary-hover` 同步染 border + text,bg 維持 surface 不染色),對齊 SegmentedControl / Tabs 未選 hover。
+
+---
+
+## 相關
+
+- Button (`button.spec.md`) — Chip 內部結構對標的來源
+- SegmentedControl (`segmented-control.spec.md`) — compact 連體單選變體
+- Tag — 純顯示 / dismissible tag
+- `useOverflowItems` hook (`packages/design-system/src/hooks/use-overflow-items.ts`) — scroll / menu 的共用追蹤邏輯，Tabs 也消費同一個 hook
+
+## A11y 預設
+
+**ARIA / Pattern**:繼承 Radix `toggle-group` primitive a11y 預設(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/toggle-group#accessibility)。
+
+**Keyboard 行為**:
+
+- Tab — 進入 group
+- ←/→ — 切換
+- Enter / Space — toggle
+
+**Focus**:Radix primitive 自管 focus trap / restoration / visible ring(`outline: 2px solid var(--ring)` per design-system focus-visible canonical)。
+
+**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `badge.spec.md`
+- `tag.spec.md`
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `opacity.spec.md`