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

package/src/patterns/action-bar/action-bar.spec.md

@@ -0,0 +1,458 @@
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — verified 0 world-class DS claim in body; blanket retract removed. -->
+
+# Action Bar 設計原則
+
+> **Foundational SSOT rationale**(cap 800,2026-04-25 approved):
+> 跨 pattern operations / utilities 角色系統 SSOT。Toolbar / DataTable / FileViewer / Dialog 等 action region 皆消費本 spec 的 overflow mechanics / section divider rules / primary 位置 / danger placement。scope 本質 > 單一 pattern。
+
+## 定位
+
+**Layout Family**:composite(cross-pattern;consumed by Toolbar / DataTable / FileViewer / Dialog 等 action region)。本 pattern 為 role system + overflow mechanics SSOT,非單一 layout family。
+
+操作列（Action Bar）是在有限空間內組合多個操作的排列模式，涵蓋 Toolbar、卡片操作列、對話框操作區等場景。
+
+本文件定義：操作的語意角色、視覺 pattern、Variant 選擇、分群與分隔線、溢出機制。
+Button 元件層規則（variant、size、icon、狀態）見 `button.spec.md`。
+
+## 世界級對照(按 pattern 類型)
+
+| 我們的 canonical | 對照 world-class |
+|------------------|-----------------|
+| Toolbar(純工具按鈕群)| Material Toolbar / VS Code EditorToolbar / Figma ToolbarLeft / Atlassian Appbar |
+| Action bar(業務操作列,primary CTA 結尾)| Polaris `ActionList / PageActions` / Linear Cmd+K bar / GitHub `toolbar` + `Save` grouping |
+| Search + filter(左搜尋右操作)| Gmail inbox toolbar / Linear list toolbar / Notion DB toolbar |
+| Overflow rule(space 不足)| Material M3 menu anchor / Atlassian overflow menu |
+
+---
+
+## 一、角色系統
+
+操作列中的所有操作分為兩種語意角色。**角色決定視覺 pattern 與位置。**
+
+### 業務操作（Operations）
+
+**使用者在此功能脈絡下，為完成目標所採取的一切操作。**
+
+> 判斷標準：移除這個操作，使用者是否無法完成他來這裡要做的事？是 → 業務操作。
+
+| 類型 | 範例 |
+|------|------|
+| 內容 CRUD | 新增、編輯、刪除、封存 |
+| 資料操作 | 篩選、排序、分組、搜尋 |
+| 資料流 | 匯入、匯出、列印 |
+| 協作 | 分享、指派、留言 |
+| 狀態推進 | 發佈、送審、完成 |
+
+### 工具操作（Utilities）
+
+**支援工作條件的操作，而非執行功能的核心工作。**
+
+> 判斷標準：這個操作跟「現在在做什麼任務」無關，任何頁面都可能有它？是 → 工具操作。
+
+| 類型 | 範例 |
+|------|------|
+| 環境調整 | 全螢幕、縮放、密度切換 |
+| 系統維護 | ↺ 刷新、重新載入 |
+| 全域設定 | ⚙ 設定 |
+| 輔助資源 | ? 說明文件、FAQ（外部連結亦同） |
+
+### Search 的角色判斷
+
+Search 的角色**不由「產品核心是不是搜尋」決定**，而由——
+
+> **結果如何被使用？**
+> - 點擊結果**跳走**（wayfinding） → **工具**
+> - 結果**留在當前頁被操作**（filter、bulk action） → **業務**
+
+| Search 類型 | 角色 | 代表 |
+|-------------|------|------|
+| 過濾當前視圖的資料 | **業務** | Data table / Kanban / list 的搜尋框，和 filter / sort / group 同類 |
+| 跨頁跳轉（結果點擊後跳走） | **工具** | App header search、Cmd+K、跨 workspace 文件 search |
+| 搜尋結果頁面（結果是操作對象） | **業務** | 結果頁本身支援圈選、批次處理；搜尋是進入該操作流程的入口 |
+
+**Gmail 陷阱**：Gmail 核心任務是處理信件，但 header search 點擊結果後跳去那封信——是 wayfinding，是**工具**。把「產品核心」當判斷依據會讓所有 search 都算成業務，角色分類失效。
+
+**擺放**：
+- 業務 search → 業務層，和 filter / sort / group 同區
+- 工具 search → 通常不在 action bar 內（放 app header 或快捷鍵）；若必須放 action bar，放工具層最右側
+
+---
+
+## 二、標準結構
+
+**工具層的位置由空間慣例決定，不由業務層排序推導。**
+工具層永遠在操作列最右側（LTR 語境），不隨對齊方式或業務層內容改變。
+
+> 為什麼：使用者對工具操作（設定、刷新、溢出）建立的是**位置記憶**，不是視覺掃描。位置一致比排序邏輯的對稱性更重要。
+
+```
+┌──────────────────────────┐ ┆ ┌──────────────────────┐
+│       業務操作群組        │ ┆ │  工具操作    溢出      │
+└──────────────────────────┘ ┆ └──────────────────────┘
+       Operations tier               Utilities tier
+```
+
+兩種對齊的差異只在業務層內部排序方向，工具層位置不變：
+
+**靠右對齊 Toolbar**（最常見）：
+
+```
+業務操作（primary 在業務層最右）  ┆  工具操作  全域溢出
+```
+
+**靠左對齊**：
+
+```
+業務操作（primary 在業務層最左）  ┆  工具操作  全域溢出
+```
+
+**對齊方向的決定**：操作列有標題時，標題在左、按鈕靠右（最常見）。操作列沒有標題時，按鈕靠左——空白放在右邊不會造成視覺斷裂，但空白放在左邊會讓按鈕群組像是漂在半空。
+
+---
+
+## 三、Variant 與排序
+
+### 業務操作
+
+| | |
+|--|--|
+| **允許 variant** | primary、secondary、tertiary、text、checked（`link` 是導覽語意，不屬於操作列） |
+| **Variant 選擇** | 以有框 variant（primary、secondary、tertiary、checked）為主，`text` 用於視覺重量最低的輔助操作。有框操作定義「這是操作區的重心」，text 是補充，不是預設。 |
+| **全局排序** | 先對所有可見業務按鈕做全局排序：`primary > secondary > tertiary > text`；靠右對齊時 primary 在業務層最右，靠左對齊時 primary 在業務層最左（工具層永遠在業務層右側，見第二節）。正確排序後有框操作自然在前、text 在後，不需要額外的集中規則。切換按鈕（text ↔ checked）依預設（未啟用）狀態的 variant 決定排序位置 |
+| **danger 位置** | `danger` 不影響跨 variant 排序。同 variant 內，danger 排在非 danger 之後（遠離主要焦點）。`primary+danger` 不受此規則影響——在刪除確認等場景中，破壞性操作本身就是主要動作 |
+| **danger 可見性** | 破壞性操作預設收進溢出選單。只有同時滿足**高頻**（使用者每次進入此畫面都可能用到）且**可逆**（有 undo 或垃圾桶機制）時，才值得攤開為可見按鈕。頻率不夠高或不可逆的破壞性操作，攤開只會增加誤觸風險（Gmail 的教訓：Delete 從預設可見改為隱藏，因為誤觸是最大客訴） |
+| **功能性分群** | 排序完成後，依功能關係在適當位置加分隔線形成群組；**不要先定義群組再各自排序**（會導致多個 primary 競爭焦點） |
+| **溢出位置** | 溢出按鈕（···）排除在全局排序之外，永遠放在所屬群組末端或工具層末端 |
+| **Size** | Toolbar 用小尺寸維持緊湊；form / dialog 用中尺寸配合表單元素的高度 |
+
+**可配置資料操作**（篩選、排序、分組）的 variant 建議：
+
+| 狀態 | Variant | Label |
+|------|---------|-------|
+| 未配置 | `text`（預設，在 Toolbar 脈絡下）／`tertiary`（脈絡不明確時，見下方 affordance 原則） | 通常 icon-only；脈絡不明確時補 label |
+| 已配置 / 啟用 | `checked`（`data-state=on`） | icon-only |
+
+篩選、排序、分組三個圖示（Filter、ArrowUpDown、Layers）在資料表格脈絡下意義唯一，Toolbar 場景通常全程 icon-only。
+
+**Checked 狀態的視覺依底層 variant 而變**：
+- `text` + `data-state=on` → `bg-neutral-selected`（灰底 + 原色 icon），低調但仍可辨識
+- `tertiary` + `data-state=on` → `bg-primary-subtle` + `text-primary`（藍底 + 藍色 icon），存在感更強
+
+**Variant 選擇 narrow scope**(2026-05-20 codex Layer B D1 verdict + WebFetch ≥ 5 world-class):
+
+| Context | Variant | Cite |
+|---|---|---|
+| **DataTable / Kanban / list 等 dense always-visible data toolbar** filter / sort / column controls | **`text` + pressed** + iconOnly + Popover wrap real panel(DataTableFilterPanel / DataTableSortManager) | `data-table.stories.tsx#WithBulkActions L998` SSOT |
+| **Standalone / labeled** sole state carrier(toolbar 外 / 單獨 filter UI 非 DataTable context) | `tertiary` + pressed | 視 case |
+| 純動作工具(無 state)/ 低重量輔助 | `text` | 既有 default |
+
+**Rationale**:dense data toolbar 已自帶 affordance + active state 由 pressed/chips/badges 顯示,trigger 用 low visual weight `text` 不該放大重量。`tertiary` 反而留給 standalone 場景(無 toolbar 上下文,trigger 是唯一 state carrier)。
+
+**World-class consensus(2026-05-20 WebFetch verified)**:
+- MUI Data Grid toolbar = `baseIconButton`(text-equivalent)/ active filters 用 toolbar chips 顯示
+- Polaris IndexFilters = toggle button + panel,active filters 用 badges/tags
+- Carbon dense toolbar = icon-only button + ghost variant
+- Linear filter button = low weight + filter chips 顯示 conditions
+- Notion DB view settings = compact button + 不放大重量
+
+**舊 wording**(retired 2026-05-20):「filter/sort 狀態是 toolbar 重點資訊 → tertiary」過寬,導致 DataTable scope 誤用 tertiary;canonical 已 narrow 到 standalone-only。
+
+### 工具操作
+
+| 子類型 | Variant |
+|--------|---------|
+| 純動作工具（點了就執行，無當前狀態） | `text` |
+| 可切換工具（全螢幕等）— 未啟用 | `text` |
+| 可切換工具 — 已啟用 | `checked` |
+
+**不允許**：primary、secondary（工具層必須是操作列中最低視覺重量）。`danger` 不適用於工具層——破壞性操作一定是對物件的業務操作，不是環境調整。
+
+**層內排序**：固定工具在前，全域溢出永遠最末。
+
+---
+
+## 三之一、tertiary vs text 的選擇（affordance 原則）
+
+`tertiary` 和 `text` 的差別**不是重要性程度，是 affordance 來源**：
+
+- **`tertiary` = 自帶 affordance**：按鈕用自己的框主動告訴使用者「這是可點的」
+- **`text` = 借用脈絡 affordance**：按鈕依賴周圍脈絡暗示可點
+
+### 判斷標準
+
+**這顆按鈕所在的位置，脈絡本身已經暗示「這裡可以點」了嗎？**
+
+| 脈絡暗示可點？ | 代表場景 | 選 |
+|----------------|----------|-----|
+| ✅ 是 | Toolbar、Table row hover、Card 的 action 區、已標記的 button group、Sidebar 內部操作 | **text** |
+| ❌ 否 | Dialog footer、Empty state、Form 主區塊的次要動作、獨立頁面中孤立出現的 dropdown trigger | **tertiary** |
+
+**為什麼**：若脈絡已經暗示可點，每顆按鈕再自帶框 = 視覺雜訊重複，搶走主要焦點；若脈絡沒暗示，`text` 按鈕會被當成純文字標籤看不見。
+
+### 常見應用
+
+| 情境 | Variant | 原因 |
+|------|---------|------|
+| Dialog Cancel / Back | **tertiary** | Footer 區域本身沒有點擊暗示，每顆按鈕要自帶 affordance |
+| Toolbar 的 Filter / Sort / View icons | **text** | Toolbar 是明確的操作區，脈絡已暗示可點 |
+| Table row 的 Edit / Delete | **text** | Row hover + 末端位置已是強線索 |
+| Empty state 的次要 CTA | **tertiary** | 按鈕漂浮在空白中，無脈絡線索 |
+| Dropdown trigger（Sort by ↓）在 Toolbar 內 | **text** | 借用 Toolbar 脈絡 |
+| Dropdown trigger 獨立出現在 page header | **tertiary** | 沒有 Toolbar 脈絡包覆，需自帶框 |
+| 可配置資料操作（filter/sort/group）在 Toolbar 的預設狀態 | **text** | 借用 Toolbar 脈絡 |
+
+### 推論
+
+- **同一顆按鈕搬家可能換 variant**：從 empty state 搬進 toolbar → tertiary 變 text。判斷依據不是按鈕本身，是它所處的脈絡
+- **成對出現不等於按鈕群**：Dialog 的 Cancel + Confirm 是兩顆，但 footer 區沒有脈絡暗示，兩顆都需要自帶 affordance——Cancel 仍是 tertiary、Confirm 仍是 primary，不會因為「成對」就變成 text 群組
+- **Toolbar 的工具按鈕群全程 text**：即使其中某顆被提升為 `tertiary` 想要加強可操作性，也要謹慎——它會在一排 text 按鈕中變得突兀。通常寧可全員 text + hover 狀態強化，也不要混合
+
+### 反例
+
+❌ **Toolbar 內用 tertiary 加強「可操作性」**
+```
+[🔽 tertiary] [👁 tertiary]  [+ New (primary)]  [⋯]
+```
+Toolbar 已經是明確操作區，tertiary 的框變成重複 affordance；多顆並排時視覺成格狀雜訊，還會和 primary 的視覺重量拉近，搶焦點。
+
+✅ **正確版本**
+```
+[🔽 text] [👁 text]  [+ New (primary)]  [⋯]
+```
+Tool 按鈕群靠 Toolbar 脈絡 + hover 狀態浮出，視覺退讓給 primary。
+
+---
+
+## 四、Icon 使用原則
+
+### 業務操作
+
+Icon 的目的是幫助辨識，不是視覺對稱。
+
+| 情境 | 規則 |
+|------|------|
+| Icon 非強制 | form / dialog 等場景可省略，label 即可 |
+| 同優先等級的操作 | 建議一致：同時有 `startIcon` 或同時沒有 |
+| 不同優先等級（primary vs tertiary） | 可以不同，視覺重量差異是刻意設計 |
+| `endIcon`（ChevronDown 等） | 互動指示器，不計入 `startIcon` 一致性判斷 |
+
+### 工具操作
+
+工具操作預設 icon-only。Icon 的適用性靠判斷，非硬規定：
+
+| 類型 | 說明 | 範例 |
+|------|------|------|
+| 脈絡無關 | 任何頁面都能辨識，永遠安全 | ⚙ ··· ✕ ⤢ ? |
+| 脈絡明確 | 在此 context 意義唯一 | ↺（資料 toolbar）、⬆（上傳功能區） |
+| 需謹慎 | 同 icon 在不同 context 意義可能不同 | ⬆（上傳 or 移上 or 捲頂） |
+
+原則：「在這個畫面脈絡下，使用者不需要讀 label 就能確定這個 icon 做什麼嗎？」若是，icon-only 可行；若不確定，補 label。
+
+所有 icon-only 按鈕必須設定 `aria-label`，Button 元件自動產生 tooltip。
+
+---
+
+## 五、分隔線規則
+
+分隔線有兩種語意，各自適用不同場景：
+
+**群組溢出邊界**
+群組溢出（···）標記一個群組的結束。**群組溢出右側必須加分隔線**，無論右側是另一個業務群組還是工具層，也無論右側的視覺類型為何。群組溢出邊界優先於角色接壤：即使右側是 text 工具層，只要有群組溢出，就必加分隔線。
+
+**角色接壤（無群組溢出時）**
+業務層沒有群組溢出，最後一個真實業務按鈕直接接工具層：
+
+```
+[...  最後一個業務按鈕]  ?  [第一個工具按鈕  ...]
+          有框         →       無框     = 不加（視覺差異已標記邊界）
+          無框         →       無框     = 必須加（邊界不可見）
+```
+
+**溢出按鈕（···）本身不構成工具層。** 工具層的存在取決於是否有固定工具按鈕（⚙ 設定、↺ 刷新、⤢ 全螢幕等）。沒有固定工具按鈕時，··· 是業務層的末端，不存在角色邊界，不加角色邊界分隔線。
+
+| 情境 | 分隔線 | 依據 |
+|------|--------|------|
+| 群組溢出右側（接任何內容） | **必須** | 群組溢出邊界 |
+| 業務層有框結尾 → 固定工具 text（無群組溢出） | **不加** | 角色接壤：視覺差異已足夠 |
+| 業務層無框 text 結尾 → 固定工具 text（無群組溢出） | **必須** | 角色接壤：邊界不可見 |
+| 業務操作層內的功能性分群 | **可選** | 同視覺類型功能域不同，視需要加 |
+| 固定工具 → 全域溢出（同屬工具層） | **不加** | 同屬工具層 |
+| 無固定工具（··· 是業務層末端） | **不加** | 沒有工具層，沒有角色邊界 |
+| 最右側為關閉 / 解除按鈕 | **必須** | 誤觸保護 |
+| 單一按鈕兩側都有分隔線 | 審查兩條各自的語意理由；正確套用規則後孤立自然不出現，若出現則代表某條分隔線應移除 | 孤立是症狀，根因是無語意的分隔線 |
+
+**分隔線語意判斷**：遵守以上規則後孤立自然不出現。若出現孤立，先問「這條分隔線有語意理由嗎？」而非接受孤立。
+
+**切換按鈕**：`text ↔ checked` 依預設（text）狀態決定位置與分隔線；切換為 checked 時不移動、不調整分隔線。
+
+---
+
+## 六、溢出選單
+
+溢出是機制，不是角色。**溢出按鈕一律最低視覺重量（無框 icon-only）**，不隨業務層有框/無框而改變。溢出排除在全局排序之外。
+
+### 判斷標準
+
+所有群組的低頻操作放進同一個選單，使用者能快速找到目標嗎？
+
+- **能** → 末端溢出（一個溢出在操作列最右，選單內用 section divider 分群）
+- **不能**（群組之間功能性質差異大，混在一起找東西慢）→ 群組溢出（各群組各自管理）
+
+### 末端溢出
+
+**一個溢出按鈕，在操作列絕對末端。** 選單內用 section divider 表達功能分群。
+
+適用於大多數操作列（資料表工具列、對話框操作區、卡片操作列等）。
+
+```
+[業務操作]  ┆  [固定工具]  [···]
+                              ↑ 唯一的溢出，永遠在最右
+
+[業務操作]  [···]             ← 沒有固定工具時
+```
+
+### 群組溢出
+
+各群組各自管理可見與隱藏的項目。每個群組獨立決定——有些群組需要溢出，有些全部攤開：
+
+```
+[B  I  U  ∨] | [☑  🖼  @  😀  🔗  +] | [↩  ↪]
+      ↑                  ↑                   ↑
+   有溢出             沒有溢出            沒有溢出
+```
+
+群組溢出可以是**永久的**（低頻項目攤開是雜亂，設計師主動策展）、**響應式的**（空間不足時收合），或兩者疊加。在群組數量多、群組之間功能性質差異大的 toolbar 中較常見（如 rich text editor）。
+
+規則：
+- 溢出附著在所屬群組末端（左側直接接該群組按鈕，無分隔線），只收納該群組的項目
+- 溢出右側必須加分隔線（群組溢出邊界，見第五節）
+- 不與末端溢出混用——避免使用者分不清各個 ··· 的範疇
+
+### 共通規則
+
+- 溢出按鈕不構成工具層。工具層需要有固定工具按鈕（⚙ 設定、↺ 刷新、⤢ 全螢幕等）才存在，只有 ··· 不算
+- **如果操作列出現大量溢出按鈕，這是資訊架構的問題，應回到功能規劃層重新設計**
+
+---
+
+## 七、空間不足時的降級
+
+### 末端溢出的操作列
+
+```
+1. 低頻業務操作收進末端溢出
+2. 工具操作已是 icon-only，維持不變
+3. 業務操作降級：低優先等級先降為 icon-only，主按鈕最後保留 label
+4. 降級後的 icon-only 業務操作需符合 icon-only 辨識度條件
+```
+
+### 群組溢出的操作列
+
+```
+1. 各群組內低頻項先收進該群組的溢出
+2. 群組繼續收合：保留最高頻的按鈕作為群組代表，其餘進溢出
+3. 單一按鈕的群組不需要溢出，空間極端不足時整個隱藏
+```
+
+---
+
+## 八、常見錯誤
+
+### ❌ 工具操作混入業務層
+
+```
+[儲存 | 複製] ┆ [↺ | 🗑] ┆ [···] ┆ [✕]
+                  ↑ 角色混用：↺ 是工具操作，🗑 是業務操作
+                    分在同一視覺群組 → 角色邊界失效，分隔線規則無從套用
+```
+
+正確版本：先分清角色，再套分隔線：
+
+```
+[儲存(framed) | 複製(framed) | 🗑(text danger)] ┆ [↺(text) | ···global] ┆ [✕]
+                                                  ↑                        ↑
+                                              text→text 角色接壤      關閉保護
+      有框→無框接壤，不加分隔線（視覺差異已足夠）
+```
+
+- 儲存、複製 = 有框業務（tertiary）；🗑 = 無框業務（text danger）→ 有框集中在前，不加分隔線
+- 🗑（業務）→ ↺（工具）= text→text 角色接壤 → 必加分隔線
+- ↺ → ···global = 同屬工具層 → 不加分隔線
+- ✕ 在末端 → 關閉保護，分隔線在 ✕ 左側；···global 左側一條（角色接壤），右側一條（關閉保護），各有語意
+
+### ❌ 同優先等級業務操作，icon 處理不一致
+
+```
+⬆ 上傳    匯出
+（同為 text variant，一個有 startIcon 一個沒有）
+```
+
+### ❌ 工具操作使用 primary 或 secondary
+
+工具層必須是操作列中最低視覺重量，否則搶走業務操作的焦點。
+
+### ❌ 工具層與全域溢出之間加分隔線，造成孤立
+
+```
+[ 業務操作 ]  ┆  ⚙  ┆  ···   ← ❌ ⚙ 兩側都有分隔線
+[ 業務操作 ]  ┆  ⚙  ···       ← ✅
+```
+
+### ❌ 無工具層卻加分隔線
+
+```
+⬆ 上傳   ⬇ 匯出   ┆   ···   ← ❌ 無角色邊界，分隔線無意義
+⬆ 上傳   ⬇ 匯出   ···        ← ✅
+```
+
+### ❌ Variant 排序錯誤：有框夾在無框之間
+
+```
+[ text ]  [ tertiary ]  [ text ]   ← ❌ tertiary 重量高於 text，應排在前
+[ tertiary ]  [ text ]  [ text ]   ← ✅
+```
+
+### ❌ 操作列被包上邊框
+
+加上邊框會變成 Segmented Control，語意與互動完全不同，不可混用。
+
+---
+
+## 九、快速判斷
+
+```
+這個操作是什麼角色？
+├── 移除它，使用者無法完成任務  →  業務操作
+│     ├── 一般操作                →  label 或 icon + label
+│     ├── 含多個子選項            →  + endIcon={ChevronDown}
+│     └── 可配置資料操作          →  text（未配置）/ checked（已配置）
+│           └── 需要更強可操作性提示  →  tertiary（未配置）
+└── 跟任務無關，服務環境          →  工具操作  →  icon-only + tooltip
+
+有工具層嗎？
+├── 有  →  業務層用什麼結尾？
+│           ├── 有框按鈕      →  不加分隔線（有框→無框視覺差異已足夠）
+│           └── 無框 text 按鈕 →  必須加分隔線（無框→無框邊界不可見）
+└── 無  →  不加任何分隔線（除非有關閉按鈕保護需求）
+
+溢出用哪種？
+└── 所有群組的低頻操作放進同一個選單，使用者能快速找到目標嗎？
+    ├── 能  →  末端溢出（一個，在最右）
+    └── 不能（群組多、功能性質差異大、找東西慢）→  群組各自管理溢出
+```
+
+---
+
+## 關聯文件
+
+- `button.spec.md`：Button 元件層的設計原則
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `bulk-action-bar.spec.md`
+- `calendar.spec.md`
+- `data-table.spec.md`
+- `file-viewer.spec.md`
+- `popover.spec.md`

package/src/patterns/element-anatomy/element-anatomy.spec.md

@@ -0,0 +1,215 @@
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Element Anatomy 設計原則(4-Family Model Taxonomy)
+
+本檔是 design system 中 **element-level 結構分類系統**的頂層 governance doc——跨 pattern / cross-component。每個元件 spec 第一段**必須聲明 Layout Family**(1/2/3/4 或「非 family,self-contained / composite」)。
+
+**為什麼住 `patterns/element-anatomy/` 而非 DS 根目錄**:taxonomy 橫跨 patterns + components 兩個家:
+- Family 1+2(row 結構)→ runtime primitive 在同 folder `item-anatomy.{spec.md, tsx, stories.tsx}`
+- Family 3(pill 結構)→ SSOT pointer 到 `components/Button/button.spec.md`
+- Family 4(field control 結構)→ SSOT pointer 到 `components/Field/field-controls.spec.md`
+
+Taxonomy 跟 F1+F2 runtime primitive **co-locate 在同 folder** 是 `packages/design-system/src/README.md` L17 的 home governance 決策:**「即使跨 pattern 的 taxonomy(如 4-Family Model)也住在最相關的 pattern topic 資料夾內,folder = topic home,不需要頂層 flat 檔案」**。co-location 讓新 element 查 taxonomy 時,runtime primitive 就在隔壁,查閱效率最高。
+
+**與「layout」命名分家**:「anatomy」= element-level 結構分類;「layout」= page-level 版面(未來頁面設計原則的家)。世界級 DS 一致如此(Material Foundations > Layout = page grid / Polaris / Atlassian / Carbon 皆然)。
+
+---
+
+## 4 個可繼承的 Layout Family
+
+| Family | 用途 | 結構 | Sizes baseline | SSOT |
+|--------|------|------|----------------|------|
+| **1. Menu item anatomy** | Menu 容器內的掃視單列(scanning mode)| `[small icon/avatar 16-20px] [content: label 單行 + desc 選用] [small suffix]`, tight density, leading-compact | **sm / md / lg** | `patterns/element-anatomy/item-anatomy.spec.md`「Family 1: Menu item」章節 |
+| **2. List item anatomy** | 頁面上的閱讀式單列(reading mode)| `[larger icon/avatar 20-24px] [content: label + multi-line desc OK] [suffix action/button/counter]`, looser density, reading typography | **sm / md / lg** | `patterns/element-anatomy/item-anatomy.spec.md`「Family 2: List item」章節 |
+| **3. Pill anatomy** | 單行互動 pill(action trigger / data indicator)| `[startIcon?] [<span px-1>label</span>] [suffix badge/endIcon/dismiss]`, single-line, whitespace-nowrap | **sm / md / lg + 可選 xs** | `components/Button/button.spec.md`「Pill Layout」章節 |
+| **4. Field control anatomy** | 可編輯資料輸入(單行為主,Textarea 多行 variant) | `fieldWrapperStyles + [startIcon?] [<editable content>] [endAction?]`, **視覺對齊 Family 1** | **sm / md / lg** | `components/Field/field-controls.spec.md` |
+
+---
+
+## 尺寸 baseline 與合法偏離
+
+每個 Family 有明文 baseline sizes。消費元件**必須**實作 baseline,除非有合理理由偏離——偏離必須在元件 spec 明文記錄。
+
+| 偏離類型 | 範例 | 合理理由 |
+|---------|------|---------|
+| **單一固定 size** | Chip (`h-field-sm`) / Notice / Alert / Toast | 世界級共識(Material 3 filter chips / Material Banner):此類元件不需密度選擇 | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+| **Alias** | Tag lg=md=24px | 子元件補齊(discrete tier):consumer 傳 size 不 break,視覺等同 |
+| **Mode 取代 Size** | FileItem(`compact` / `rich`) | **結構變體**非密度變體——用 size 會誤導 |
+| **額外 xs**(Family 3 only) | Button / SegmentedControl xs | icon-only toolbar utility(24px 固定 不配對 Field) |
+
+違反但無理由 = 設計 bug,必須改 code 或補 spec 理由。
+
+---
+
+## Family 3 兩個 sub-profile(重要)
+
+同結構、不同 role、不同 padding / typography:
+
+| Sub-profile | 成員 | Padding | Typography | Cursor | 為什麼 |
+|-------------|------|---------|-----------|--------|------|
+| **Action trigger** | Button / SegmentedControl / Chip | 較鬆(xs=`px-2`, sm+=`px-3`) | 對應 size 的 font-medium | pointer | 需命中區 + 視覺重量搶點擊焦點 |
+| **Data indicator** | Tag | 較緊(`px-1` 所有 size) | font-normal | text | Passive 讀取,不搶焦點 |
+
+---
+
+## Size Pairing 規則(跨 Family)
+
+| Pairing | 意義 |
+|---------|------|
+| Tag md ↔ Field md / Tag sm ↔ Field sm | Tag 的 size 對應同名 Field size,視覺對齊 form 內字級 |
+| Button sm/md/lg ↔ Field sm/md/lg | Button 配對 Field 時 size 同名 |
+| Button xs = 獨立 utility | 不配對 Field,用於 toolbar compact button |
+| Family 4 視覺對齊 Family 1 | 讓 Select trigger + dropdown options 視覺連續 |
+
+---
+
+## Consumers 快速查
+
+| Family | Canonical | Consumers |
+|--------|-----------|-----------|
+| 1 Menu item | `MenuItem`(from `item-anatomy`) | `TreeItem`, `SidebarMenuButton`, `DropdownMenuItem`(重用 MenuItem), `SelectMenu` 內部 |
+| 2 List item | (無單一 canonical) | `StepItem`(例外:indicator 對齊), `FileItem`(icon 作邊界), `Notice` → `Alert/Toast`(視覺一致非語意), `SelectionItem` variant → `RadioGroup` / `Checkbox` group |
+| 3 Pill | `Button` | `SegmentedControlItem`, `Chip`, `Tag`(data indicator sub-profile) |
+| 4 Field control | `Input`(field-controls SSOT) | `NumberInput`, `DatePicker`, `Select`, `Combobox`, `LinkInput`, `PeoplePicker`, `Textarea`(multi-line variant) |
+
+---
+
+## 不進 Family Model 的元件
+
+不能舉一反三的不分類。**Composite 類再細分三子類**,因為三類的設計約束不同:
+
+### Self-contained primitive(獨立視覺 atom,無 slot 結構)
+
+Switch / Checkbox / Radio / Avatar / Badge / CircularProgress / ProgressBar / Skeleton / Separator
+
+各自獨立視覺,spec 直接描述自己結構。
+
+### Overlay-composite(浮層 composite,消費 overlay-surface pattern)
+
+Dialog / Sheet / Popover / Tooltip / HoverCard / Coachmark / Command / SelectMenu / DropdownMenu
+
+**共同約束**:
+- 必消費 `patterns/overlay-surface/` 的 `SurfaceHeader` / `SurfaceBody` / `SurfaceFooter`(padding SSOT)
+- elevation 走 `--elevation-200`+ 的 overlay layer
+- dismiss 走 `onClose`(語意:關閉 overlay session,見 CLAUDE.md 命名 canonical)
+- 部分 overlay 有 modal vs non-modal 分流(Dialog / Sheet modal;Popover / HoverCard non-modal)
+- 在 dark-mode context(如 FileViewer chrome)中需支援 `data-theme="dark"` 子樹
+
+### Page-composite(頁面內 composite,無 overlay 性質)
+
+Tabs / Accordion / DataTable / Calendar / Carousel / Breadcrumb / Sidebar / NameCard / FileItem / FileUpload / FileViewer / OverflowIndicator
+
+**共同約束**:
+- 消費多個 row primitive 或 self-contained primitive
+- 不走 overlay-surface(沒有 elevation / dismiss)
+- 佈局 token 用 `--layout-space-*`(chrome / section)
+- 各自 own 內部 layout SSOT(例:DataTable 的 header row、Calendar 的 grid、Carousel 的 track + arrow)
+
+### Pure-wrapper(純行為 wrapper,無自己視覺)
+
+CheckboxGroup / RadioGroup / FieldGroup(若建)
+
+**共同約束**:
+- 自己**無 render**(transparent wrapper)
+- 提供 context(`CheckboxGroupContext`)給 descendant 同步 state
+- spec 應明文「本元件無視覺」,對應 anatomy story 只有 `Overview` + `Inspector` 兩個(no ColorMatrix / SizeMatrix)
+
+---
+
+### 判斷新 composite 時的流程
+
+寫新 composite spec 時先自問:
+1. 這是浮層(elevation / Portal / dismiss session)嗎? → **Overlay-composite**
+2. 這是頁面內多區塊 layout 嗎? → **Page-composite**
+3. 這本身無視覺、只是 context / state wrapper 嗎? → **Pure-wrapper**
+
+三題全否 → 應該是 Family 1/2/3/4 或 Self-contained primitive,而不是 composite。
+
+---
+
+## 允許的跨 Family 視覺對齊
+
+Family 4 的 Input / Select 視覺對齊 Family 1 的 menu-item(高度、字體、icon size)——但兩個 family **各自 own SSOT**。這是「視覺對齊」非「結構繼承」。
+
+---
+
+## Field Composition(不在 family 但相關)
+
+`components/Field/field.spec.md` 描述 **form field composition pattern**——Field 容器如何包 Family 4 control + label + help。不同 scope 的 pattern(composition 非 element anatomy),不列入 4-Family。
+
+---
+
+## 新元件判斷流程
+
+1. **垂直列表裡?** → Family 1(menu 容器)/ Family 2(頁面)
+2. **單行可點擊 / 可讀的 pill?** → Family 3(action trigger or data indicator)
+3. **單行可編輯資料?** → Family 4(必須視覺對齊 Family 1)
+4. **都不是?** → **停下討論**——新 family 還是 self-contained
+
+CLAUDE.md `# 4-Family Layout Model` 留概要 + 判斷流程(每 session signal)。本檔 own 完整 taxonomy + Family 3 sub-profile + size pairing + consumers + exclusions。
+
+---
+
+## 視覺容器 breathing invariant(DS-wide canonical · 2026-04-22)
+
+**規則**(rule · 必遵守):
+
+> 任何**有明確視覺邊界的容器**(permanent `bg-*` / `border` / `shadow-*` 三者任一),**必有 inner padding**,不讓內容物(含 standalone card、pill、row、text 等任何 children)觸容器邊。
+
+**責任層**:**父容器(chrome)** — 子元件 `w-full` responsive 不變。
+
+**為什麼責任在父容器**:
+- 子元件不知道自己會住在哪個 chrome → 硬綁 max-w / margin 會破壞 responsive
+- 父容器知道自己的視覺 policy(bg/border/shadow 都是它的決策)→ 天然 SSOT
+- 子元件統一 `w-full` 扣掉父 padding 自動有 breathing
+
+**建議值**(guide · 非 strict):
+
+| Chrome 類型 | 建議 inner padding | 範例 |
+|------------|------------------|------|
+| 一般 chrome(Dialog / Sheet / Popover / Card body) | `--layout-space-loose`(16/24)/`--layout-space-tight`(12/16) | SurfaceBody 已 own canonical |
+| 側邊 chrome(Sidebar / Drawer section) | `--layout-space-tight` 到 `--layout-space-loose` | 視深度 |
+| Inline pill(Badge / Chip / Tag) | `px-1` / `px-2` | 對齊元件 size |
+| Form field control wrapper | `px-3`(固定,對齊 Field family)| fieldWrapperStyles |
+
+Consumer 自建 chrome-like div 帶 bg/border/shadow 時,參考上表或就近取 `--layout-space-*` token。**具體值允許偏離,但 breathing 本身必存在**。
+
+**世界級對照**(DS-wide 共識):
+- Material Design 3:`<mat-card-content>` 16dp / `<mat-dialog-content>` 24dp / Drawer section padding
+- Polaris(Shopify):`<Page>` 16-20px / `<Card>` 16-20px / `<Modal>` 20px
+- Atlassian:`<Box padding="space.200">` / `<ModalBody>` 24px / Drawer body padding
+- Ant Design:`<Modal.Body>` 24px / `<Card.Meta>` inner padding
+- Apple HIG:Inset Grouped list group 16pt inset / Card 內容 16pt
+- Carbon(IBM):Tile / Modal 內容 16-32px padding
+
+無反例 — 6 家一致在 chrome 層提供 inner padding 當 SSOT。
+
+**反例(破圖)**:
+- Consumer 自建 `<div className="bg-surface-raised rounded-lg">{rich FileItem list}</div>` **無 padding** → rich card w-full 貼父 div 邊,card rounded 貼父 rounded 視覺「卡在一起」
+- Consumer 自建 `<div className="border rounded-md">{text}</div>` 無 padding → text 貼 border 邊,看似斷字
+- Chrome primitive 被 override 拿掉 padding(`<SheetBody className="p-0">`)後塞 card 元件 → 同上
+
+**Enforcement**:
+- Chrome primitive(SurfaceHeader / SurfaceBody / SurfaceFooter / Input wrapper / Field wrapper)**已 own canonical padding**,繼續守 SSOT
+- Consumer 自建的有視覺邊界 div → hook `check_container_breathing.sh` warn(grep `bg-*|border|shadow-*` 無 `p*-`)
+- Audit dim 新增:「consumer 自建 chrome 是否有 inner padding」
+
+**與既有規則的關係**:
+- `overlay-surface.spec.md` 「M11 state walk hover 檢查(三 invariant 必同時 ✓)」第 3 條(content 在 hover bg 內 breathing)= 本規則的**應用層 instance**(hover bg 也算「permanent」在該 state 內),非獨立規則
+- `.claude/rules/ui-development.md`「Padding source 分層規則」定 **padding 來源**(token / Tailwind / calc);本規則定 **padding 是否存在**(是 invariant)
+
+---
+
+## 相關
+
+- `patterns/element-anatomy/item-anatomy.spec.md` — Family 1+2 row anatomy deep SSOT + runtime primitive(`<MenuItem>` canonical + `<ItemIcon>` / `<ItemAvatar>` / `<ItemLabel>` / `<ItemSuffix>` / `<ItemInlineAction>` slot components)
+- `components/Button/button.spec.md` — Family 3 Pill anatomy SSOT
+- `components/Field/field-controls.spec.md` — Family 4 Field control anatomy SSOT
+- CLAUDE.md `# 4-Family Layout Model` — 每 session signal 的概要 + judgment flow
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `calendar.spec.md`
+- `time-picker.spec.md`