@qijenchen/design-system 0.1.0-beta.61 → 0.1.0-beta.63

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

@@ -89,7 +89,7 @@ Search 的角色**不由「產品核心是不是搜尋」決定**，而由——
 ┌──────────────────────────┐ ┆ ┌──────────────────────┐
 │       業務操作群組        │ ┆ │  工具操作    溢出      │
 └──────────────────────────┘ ┆ └──────────────────────┘
-       Operations tier               Utilities tier
+    業務層(Operations)          工具層(Utilities)
 ```
 
 兩種對齊的差異只在業務層內部排序方向，工具層位置不變：
@@ -142,7 +142,7 @@ Search 的角色**不由「產品核心是不是搜尋」決定**，而由——
 
 | 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 |
+| **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` SSOT |
 | **Standalone / labeled** sole state carrier(toolbar 外 / 單獨 filter UI 非 DataTable context) | `tertiary` + pressed | 視 case |
 | 純動作工具(無 state)/ 低重量輔助 | `text` | 既有 default |
 
@@ -283,7 +283,7 @@ Icon 的目的是幫助辨識，不是視覺對稱。
 
 **分隔線語意判斷**：遵守以上規則後孤立自然不出現。若出現孤立，先問「這條分隔線有語意理由嗎？」而非接受孤立。
 
-**切換按鈕**：`text ↔ checked` 依預設（text）狀態決定位置與分隔線；切換為 checked 時不移動、不調整分隔線。
+**切換按鈕**：`text` + `pressed` toggle——依預設（未啟用）狀態決定位置與分隔線；切為啟用（`pressed=true`）時不移動、不調整分隔線（啟用態不是 variant，見三節）。
 
 ---
 
@@ -331,6 +331,7 @@ Icon 的目的是幫助辨識，不是視覺對稱。
 ### 共通規則
 
 - 溢出按鈕不構成工具層。工具層需要有固定工具按鈕（⚙ 設定、↺ 刷新、⤢ 全螢幕等）才存在，只有 ··· 不算
+- 溢出選單本體的浮層行為（超出 viewport 的 collision 翻轉 / 內容過長捲動 / Esc 關閉 / 鍵盤導覽）由 `DropdownMenu` own（Radix 預設），本 pattern 不重定義
 - **如果操作列出現大量溢出按鈕，這是資訊架構的問題，應回到功能規劃層重新設計**
 
 ---
@@ -425,7 +426,7 @@ Icon 的目的是幫助辨識，不是視覺對稱。
 ├── 移除它，使用者無法完成任務  →  業務操作
 │     ├── 一般操作                →  label 或 icon + label
 │     ├── 含多個子選項            →  + endIcon={ChevronDown}
-│     └── 可配置資料操作          →  text（未配置）/ checked（已配置）
+│     └── 可配置資料操作          →  text + pressed（未配置 pressed=false / 已配置 pressed=true）
 │           └── 需要更強可操作性提示  →  tertiary（未配置）
 └── 跟任務無關，服務環境          →  工具操作  →  icon-only + tooltip
 
@@ -443,15 +444,21 @@ Icon 的目的是幫助辨識，不是視覺對稱。
 
 ---
 
+## 邊界與分權
+
+本 pattern 是組合指南（無 runtime 元件）——元件級邊界（無可見 action 時不渲染空操作列 / loading / disabled 狀態）與 a11y 細節由消費端元件 own：icon-only 必設 `aria-label` + tooltip（見第四節，Button own）；溢出選單的鍵盤 / focus 行為由 `DropdownMenu` own（見第六節）。
+
 ## 關聯文件
 
 - `button.spec.md`：Button 元件層的設計原則
+- `../../components/DropdownMenu/dropdown-menu.spec.md`：溢出選單浮層行為 SSOT（collision / 捲動 / Esc / 鍵盤）
 
 ## 被引用(auto-maintained,Dim 3 reciprocal audit)
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `bulk-action-bar.spec.md`
+- `button.spec.md`
 - `calendar.spec.md`
 - `data-table.spec.md`
 - `file-viewer.spec.md`

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

@@ -89,7 +89,7 @@ Switch / Checkbox / Radio / Avatar / Badge / CircularProgress / ProgressBar / Sk
 Dialog / Sheet / Popover / Tooltip / HoverCard / Coachmark / Command / SelectMenu / DropdownMenu
 
 **共同約束**:
-- 必消費 `patterns/overlay-surface/` 的 `SurfaceHeader` / `SurfaceBody` / `SurfaceFooter`(padding SSOT)
+- 結構化 chrome 浮層(Dialog / Sheet / Popover;Coachmark 經 `PopoverHeader`)消費 `patterns/overlay-surface/` 的 `SurfaceHeader` / `SurfaceBody` / `SurfaceFooter`(padding SSOT;實際 consumer 名單見 `overlay-surface.spec.md`「Consumers」)。menu 形浮層(Command / SelectMenu / DropdownMenu)走自有 menu surface canonical(`floatingLayerClass` + `py-2`);Tooltip(純文字 surface)與 HoverCard(behavior primitive,內容由 consumer 排)不消費 Surface*(2026-05-18 M18 anchor)
 - elevation 走 `--elevation-200`+ 的 overlay layer
 - dismiss 走 `onClose`(語意:關閉 overlay session,見 CLAUDE.md 命名 canonical)
 - 部分 overlay 有 modal vs non-modal 分流(Dialog / Sheet modal;Popover / HoverCard non-modal)
@@ -110,9 +110,9 @@ Tabs / Accordion / DataTable / Calendar / Carousel / Breadcrumb / Sidebar / Prof
 CheckboxGroup / RadioGroup / FieldGroup(若建)
 
 **共同約束**:
-- 自己**無 render**(transparent wrapper)
-- 提供 context(`CheckboxGroupContext`)給 descendant 同步 state
-- spec 應明文「本元件無視覺」,對應 anatomy story 只有 `Overview` + `Inspector` 兩個(no ColorMatrix / SizeMatrix)
+- 自己**無視覺 chrome**(無 bg / border / radius)——僅渲染 `role="group"` layout 容器 + 提供 context(`CheckboxGroupContext` 等)給 descendant 同步 state;視覺由 descendant(Checkbox / RadioGroupItem / SelectionItem)承載
+- RadioGroup 註記:兼任 Field 家族「承載欄位值的互動控件」(見 `field-controls.spec.md`「哪些元件吃 `<Field disabled>` cascade」),有 display / empty mode 內容渲染,其 anatomy story 因此含 ColorMatrix / SizeMatrix
+- spec 應明文「本元件無自有視覺 chrome」;純 wrapper 的 anatomy story 最小集 = `Overview` + `Inspector`
 
 ---
 
@@ -141,7 +141,7 @@ Family 4 的 Input / Select 視覺對齊 Family 1 的 menu-item(高度、字體
 
 ## 新元件判斷流程
 
-1. **垂直列表裡?** → Family 1(menu 容器)/ Family 2(頁面)
+1. **垂直列表裡?** → Family 1(menu 容器)/ Family 2(頁面)——分界看「容器 + 閱讀模式」:浮層 menu 內掃視選擇 = Family 1(scanning),頁面上閱讀內容 = Family 2(reading);深度規格詳 `item-anatomy.spec.md` Family 1 / Family 2 章節
 2. **單行可點擊 / 可讀的 pill?** → Family 3(action trigger or data indicator)
 3. **單行可編輯資料?** → Family 4(必須視覺對齊 Family 1)
 4. **都不是?** → **停下討論**——新 family 還是 self-contained
@@ -174,7 +174,7 @@ CLAUDE.md `# 4-Family Layout Model` 留概要 + 判斷流程(每 session signal)
 
 Consumer 自建 chrome-like div 帶 bg/border/shadow 時,參考上表或就近取 `--layout-space-*` token。**具體值允許偏離,但 breathing 本身必存在**。
 
-**世界級對照**(DS-wide 共識):
+**世界級對照**(DS-wide 共識): <!-- @benchmark-unverified -->
 - 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
@@ -212,4 +212,6 @@ Consumer 自建 chrome-like div 帶 bg/border/shadow 時,參考上表或就近
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `calendar.spec.md`
+- `field.spec.md`
+- `item-anatomy.spec.md`
 - `time-picker.spec.md`

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

@@ -1,6 +1,6 @@
 <!-- @benchmark-cited: D5 retrofit 2026-05-18 — verified 0 world-class DS claim in body; blanket retract removed. -->
 
-# Inline Action 設計規格(SSOT)
+# Inline Action 設計原則(SSOT)
 
 **Layout Family**:non-family(hosted inline element,無 own layout — 由宿主 family 1/4 提供)。
 
@@ -153,7 +153,7 @@ Q3. Row 多大?
 | Menu / TreeView / SidebarMenuButton / SelectionItem suffix | Row inline flow | Inline Action | Inline with content |
 | SidebarGroup header chevron | Aux toggle | Inline Action | Inline header toggle |
 | Select ChevronDown / DatePicker Calendar / Combobox ChevronDown | Field chrome(裝飾)| **Decorative**(不是 action)| Click falls through;host 是 trigger |
-| **FileItem compact**(row 24)| Row slot | Inline Action | Row 太小容不下 Button xs 24 |
+| **FileItem compact**(row 24)| Row slot | Button xs iconOnly(`var(--field-height-xs)` 容器 + data-unbounded 收斂到 1lh)| 2026-04-23 user 統一 rich + compact 同 primitive,不撐高 row(見 file-item.tsx 註解)|
 | **FileItem rich**(row 56 sm/md rich)| Row slot | Button xs iconOnly(24 固定)| ≤ 24 cap,不放大 |
 | **DataTable header cell internal**(sort indicator / ⌄ menu / filter funnel / pin)| Header cell host internal | **Inline Action**(`ItemInlineActionButton` asChild for DropdownMenu)| Embedded inline,跟 label 一體 |
 | **DataTable body cell internal**(display endAction / clear / edit indicator)| Cell content host internal | **Inline Action**(自動繼承 Field family endAction)| Field display 元件已對齊 |
@@ -188,6 +188,11 @@ Row action 的 affordance 是「次要功能」,不是 primary CTA。Button chro
 - 尺寸:`patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」(overlay sm + v5 trick / banner xs explicit)
 - variant / divider:`patterns/action-bar/action-bar.spec.md`(corner action group)
 
+### 邊界案例
+
+- **帶可見文字 label 的觸發**:不是 Inline Action — Inline Action 必 icon-only(label 走 tooltip + `aria-label`,見「實作要求」);需要可見文字 → `Button`(text / tertiary)。
+- **Dark mode**:hover / active / fg 全走 semantic token(`--neutral-hover` 等)自動 adapt,Inline Action 不 own dark token;colored host 的繼承色由 host token 處理(見 `tag.spec.md`)。
+
 ### Inline action 共用元件(`ItemInlineAction` / `ItemSuffix`)
 
 Canonical 實作於 `item-anatomy.tsx`,匯出 `ItemInlineAction` / `ItemSuffix`(從 `RowSizeContext` 自動查 icon size / hover bg / tooltip / aria-label / fg-muted → foreground 全內建)。
@@ -199,7 +204,7 @@ Canonical 實作於 `item-anatomy.tsx`,匯出 `ItemInlineAction` / `ItemSuffix`(
 <ItemSuffix hoverReveal>{actions.map((a) => <ItemInlineAction action={a} />)}</ItemSuffix>
 ```
 
-**Host 走宣告式 API**(`inlineActions?: InlineActionConfig[]` / `endAction?: InlineActionConfig` prop)— 不自刻 button JSX。已遷移:`SidebarMenuButton` / `Input` / `NumberInput`(2026-05-31 infra-audit 修 stale status:verify input.tsx/number-input.tsx 已用 endAction InlineActionConfig)。Pending refactor:`Tag` / `LinkInput` / `Combobox`。
+**Host 走宣告式 API**(`inlineActions?: InlineActionConfig[]` / `endAction?: InlineActionConfig` prop)— 不自刻 button JSX。已遷移:`SidebarMenuButton` / `Input` / `NumberInput`(2026-05-31 infra-audit 修 stale status:verify input.tsx/number-input.tsx 已用 endAction InlineActionConfig)、`Tag`(2026-05-01:宣告式 `onRemove` + 內部 `ItemInlineActionButton`,見 tag.tsx)。`LinkInput` / `Combobox` 屬下方「不適用清單」(右側 chrome 獨佔),內建 inline action 已直接消費 `ItemInlineAction` primitive——無 pending。
 
 ### Dismiss canonical — X close only
 
@@ -224,7 +229,7 @@ Canonical 實作於 `item-anatomy.tsx`,匯出 `ItemInlineAction` / `ItemSuffix`(
 
 #### `dismiss` prop 觸發條件(Button 限定)
 
-**明示**:`<Button dismiss />` 或 callback = `onClose` / `onDismiss` → 觸發弱化 override(icon fg-muted → hover foreground;variant 強制 text)
+**明示**:`<Button dismiss />`(唯一機械觸發;Button 無 `onClose` / `onDismiss` prop)→ 觸發弱化 override(icon fg-muted → hover foreground;variant 強制 text)。語意判準:點擊語意 = X close 才用 dismiss
 
 **不觸發**:callback = `onRemove`(collection 操作)/ `onClear`(欄位清空)/ `onDelete` — 這些不是 dismiss 語意,Button 用對應 variant 即可
 
@@ -244,7 +249,7 @@ Tag solid / branded color variant(`red / blue / orange`)→ Tag 內 X **繼承 h
 
 sonner toast auto-dismiss / Radix Dialog `DialogClose` wiring — 第三方只管 state logic(何時關),**我們渲染的視覺按鈕必套對應 canonical**(chrome corner → Button dismiss;chrome padding → Inline Action)。
 
-hook `check_story_anatomy.sh` 規則 B 已在 stories 層攔 label Button 作 dismiss。
+hook `check_story_invariants.sh` R1(原 `check_story_anatomy.sh` 規則 B,已 folded)已在 stories 層攔 label Button 作 dismiss。
 
 ---
 
@@ -279,7 +284,7 @@ hook `check_story_anatomy.sh` 規則 B 已在 stories 層攔 label Button 作 di
 - `disabled / readonly` 模式 / Sidebar `collapsible=icon` 模式跟 config 一致(slot 也要被相同條件隱藏)
 - Reveal 模式(`actionsReveal="hover"`)、絕對定位 chrome 跟 config 共用,consumer 不需重做
 - Padding budget(Sidebar)slot mode 預設按 1 icon 寬度預留,多 icon 寬度需 consumer 自控 className
-- 視覺一致性 by consumer — 但 **app-code 不可直接 import L3 primitive**(`ItemInlineActionButton` / `ItemInlineAction` / `RowSizeProvider`),由 `check_l3_primitive_import.sh` 攔截。需要視覺一致 inline-action button 時,(a) 用 host 自帶 slot(此 escape hatch)、(b) 用 `<Button iconOnly variant="text" />`、(c) 走 spec rationale 例外申請
+- 視覺一致性 by consumer — 但 **app-code 不可直接 import L3 primitive**(`ItemInlineActionButton` / `ItemInlineAction` / `RowSizeProvider`),由 `check_canonical_propagation.sh` E.2(原 `check_l3_primitive_import`,已 folded,P0 BLOCK)攔截。需要視覺一致 inline-action button 時,(a) 用 host 自帶 slot(此 escape hatch)、(b) 用 `<Button iconOnly variant="text" />`、(c) 走 spec rationale 例外申請
 
 **現況清單**(2026-04-25 補完):
 - ✅ `Input.endSlot`
@@ -289,7 +294,7 @@ hook `check_story_anatomy.sh` 規則 B 已在 stories 層攔 label Button 作 di
 
 **不適用清單**:DatePicker / Combobox / Select / TimePicker / LinkInput 右側由元件自帶 chrome 獨佔(Calendar / ChevronDown / Clock / ExternalLink 等 intrinsic affordance),不開放 consumer 放置 endAction/endSlot — 這些元件的 inline-action 需求走**內建 clear X**(consumer 透過 `clearable` prop opt-in)或 `<Button iconOnly />` 放在 Field 外側。Escape hatch canonical 不涵蓋此類 host(本質上非 consumer-facing slot)。
 
-**世界級對照**:
+**世界級對照**: <!-- @benchmark-unverified -->
 - Material UI:`InputAdornment` ReactNode slot(無 config,純 escape hatch 派 — 我們的 90/10 比 Material 更有結構)
 - Polaris:`TextField.connectedRight` ReactNode 只接 Button,但無 config-based 簡化,API 一致性差
 - Ant Design:`Input.suffix` ReactNode slot,跟 Material 同派
@@ -301,20 +306,15 @@ hook `check_story_anatomy.sh` 規則 B 已在 stories 層攔 label Button 作 di
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
-- `sheet.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
 - `alert.spec.md`
 - `breadcrumb.spec.md`
 - `data-table.spec.md`
 - `field-controls.spec.md`
+- `item-anatomy.spec.md`
+- `overlay-surface.spec.md`
 - `popover.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
+- `sheet.spec.md`
+- `sidebar.spec.md`
 - `tag.spec.md`
+- `tree-view.spec.md`
+- `uiSize.spec.md`

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

@@ -1,4 +1,4 @@
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline(M22(d) 顯式撤回;本檔 frontmatter 無 benchmark list,來源 URL 未補)。 -->
 
 # Item Anatomy 設計原則(Family 1 + Family 2 row 結構 SSOT)
 
@@ -47,7 +47,7 @@
 
 | 元件 | 繼承的部分 | 不繼承的部分 |
 |------|----------|-----------|
-| `Tabs`（Trigger） | gap-2 slot 間距、scanning 字體 tier、hover 行為 | 結構是**橫向 inline**（非垂直 row）, 高度系統對標 Button, 無 prefix/content/suffix column | 詳細對標分析見 `components/Tabs/tabs.spec.md`「Tabs 不完全屬於 item-layout」段 |
+| `Tabs`（Trigger） | gap-2 slot 間距、scanning 字體 tier、hover 行為 | 結構是**橫向 inline**（非垂直 row）, 高度系統對標 Button, 無 prefix/content/suffix column;詳細對標分析見 `components/Tabs/tabs.spec.md`「Tabs 不完全屬於 item-layout」段 |
 
 ---
 
@@ -141,9 +141,9 @@
 
 ```bash
 # 看有沒有繞過 item-anatomy 的手刻 list item
-rg "className=\"flex.*py-[0-9].*hover:bg\" packages/design-system/src src/hooks --type tsx
+rg 'className="flex.*py-[0-9].*hover:bg' packages/design-system/src -g '*.tsx'
 # 看有沒有繞過 DescriptionList 的手刻 key-value grid
-rg "grid-cols-\[[0-9]+px_1fr\]" packages/design-system/src src/hooks --type tsx
+rg 'grid-cols-\[[0-9]+px_1fr\]' packages/design-system/src -g '*.tsx'
 ```
 
 非空 = drift,要改用 primitive。
@@ -198,7 +198,9 @@ rg "grid-cols-\[[0-9]+px_1fr\]" packages/design-system/src src/hooks --type tsx
 
 ### Card header 大 prefix 對齊（avatar > text block）
 
-Row primitive 的 24px 閾值規則適用於**列表行**（prefix 跟 text block 接近等高）。當 prefix 遠大於 text block 時（如 64px profile avatar 搭配 1-2 行文字），改用 **card header 模式**：
+Row primitive 的 24px 閾值規則適用於**列表行**（prefix 跟 text block 接近等高）。當 prefix 遠大於 text block 時（如 64px profile avatar 搭配 1-2 行文字），改用 **card header 模式**。
+
+**為什麼置中**：text block 遠矮於 prefix 時，若沿用列表行的 top-align（`h-[1lh]` 對第一行），文字會頂在 avatar 上緣、下方大片留白，視覺重心偏上失衡；垂直置中讓 text 與大 avatar 形成均衡的 identity pair。實作：
 
 ```tsx
 <div className="flex items-start gap-3">
@@ -324,7 +326,7 @@ Consumer 不需手動插 Separator——把同類 items 包進 Group,自動分
 
 **為什麼 state 不獨立列規則**:state 視覺(hover / focus / active / selected)跟隨 permanent layer 分類,不獨立觸發。瞬時 state(hover/focus/active)單一 item 啟用不會創造相鄰衝突;selected 的連續 bg 在 permanent flush / transparent item 上是 **multi-select feature**(Finder / Gmail / Notion idiom),在 permanent standalone card 上依然必 gap(card identity 保留)。
 
-### 世界級 benchmark(2026-04-22 掃 6 家)
+### 世界級 benchmark(2026-04-22 掃 6 家) <!-- @benchmark-unverified -->
 
 | DS | menu item | file/card list | table row | settings row |
 |----|-----------|---------------|-----------|-------------|
@@ -363,6 +365,12 @@ Consumer 不需手動插 Separator——把同類 items 包進 Group,自動分
 - `file-upload.stories.tsx` rich list(standalone card)→ 改 `gap-2` + 移除 `border overflow-hidden` 外框
 - `file-item.stories.tsx` Rich / HoverSwap rich block / Clickable:同上
 
+### 邊界案例
+
+- **多行 item(文字換行)**:不改變分類 — gap 判定只看永久視覺層,與 item 高度 / 行數無關
+- **Selected 連續多 item**:見上「為什麼 state 不獨立列規則」— flush / transparent 的連續 selected bg 是 multi-select feature;standalone card 依然必 gap
+- **Dark mode**:分隔 affordance(`border-divider` / bg token)走 semantic token 自動 adapt,分類與 gap 判定不變
+
 ### 跟 Group auto-separation 的關係
 
 本規則處理**單一 group 內 item 之間**;「Group auto-separation」處理**相鄰 group 之間**(自帶 16px + border 分隔)。
@@ -386,7 +394,7 @@ Consumer 不需手動插 Separator——把同類 items 包進 Group,自動分
 | **control** | Selection 機制(Checkbox / RadioGroupItem) | 只有 SelectionItem 有 | **永遠 inline**(`h-[1lh]`) |
 | **prefix** | 視覺輔助(icon / avatar / thumbnail) | 可選,在所有 item 元件 | 24px 閾值規則 |
 | **content** | label + 可選 description | 永遠存在 | 佔滿剩餘空間,`flex-1 min-w-0` |
-| **suffix** | label 的 metadata(tag、chevron、time、count) | 可選,在所有 item 元件 | **24px 閾值規則(跟 prefix 同公式但獨立)** |
+| **suffix** | label 的 metadata(tag、chevron、time、count) | 可選,在所有 item 元件 | **永遠 `h-[1lh]` inline 對齊第一行 label(跟 prefix 解耦,見「24px 閾值對齊規則」suffix 段)** |
 
 **suffix 可以塞什麼**(支援 Switch 同時遵守 24px 閾值):
 
@@ -399,7 +407,7 @@ Consumer 不需手動插 Separator——把同類 items 包進 Group,自動分
 
 ### 互動 control 在 suffix(Switch / Checkbox / Select)
 
-Menu item / dropdown item 的 suffix 是**可以**塞 Switch / Checkbox / Select 的——世界級 dropdown menu(macOS / Windows / VS Code 的 View menu、Notion 的 page options)普遍用 menu item + trailing toggle/checkmark 呈現「此項 on/off」。**條件**:必須遵守 item-anatomy 的對齊 + 點擊語義規則。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+Menu item / dropdown item 的 suffix 是**可以**塞 Switch / Checkbox / Select 的——世界級 dropdown menu(macOS / Windows / VS Code 的 View menu、Notion 的 page options)普遍用 menu item + trailing toggle/checkmark 呈現「此項 on/off」。**條件**:必須遵守 item-anatomy 的對齊 + 點擊語義規則。 <!-- @benchmark-unverified -->
 
 **視覺對齊**(跟 `Tag` / `Chevron` 共用規則):
 
@@ -414,18 +422,16 @@ MenuItem 承載 Switch 時,**整列 row 的 click = toggle 這個 control**(不
 
 ```tsx
 // ✅ Canonical:row click 與 suffix Switch 同步 toggle(row 可點擊、Switch 視覺反映狀態)
-<DropdownMenuItem
-  suffix={<Switch checked={dark} tabIndex={-1} aria-hidden />}
-  onClick={() => setDark(!dark)}
->
+// (DropdownMenuItem 無任意 suffix slot——trailing 互動 control 用 MenuItem endContent)
+<MenuItem endContent={<Switch checked={dark} tabIndex={-1} aria-hidden />} onClick={() => setDark(!dark)}>
   Dark mode
-</DropdownMenuItem>
+</MenuItem>
 
 // ❌ 錯:row 跟 Switch 各自獨立,兩個不同 action
-<DropdownMenuItem onClick={navigate('/settings')}>
+<MenuItem onClick={() => navigate('/settings')}>
   Dark mode
   <Switch checked={dark} onCheckedChange={setDark} />  {/* Switch 有自己的 click,搶 row click */}
-</DropdownMenuItem>
+</MenuItem>
 ```
 
 **Switch 實作細節**:放 suffix 時 Switch 應 `tabIndex={-1}` + `aria-hidden`(或去掉自己的 click handler),讓 **row 成為唯一互動靶子**、Switch 純視覺反映狀態。Radix `DropdownMenuCheckboxItem` 的 Checkbox 就是這模式(checkmark 是視覺,整列是 trigger)。Switch 類比採用同樣規則。
@@ -439,7 +445,7 @@ MenuItem 承載 Switch 時,**整列 row 的 click = toggle 這個 control**(不
 
 兩者**結構一致**(label 左 / toggle 右齊),差別只在**容器層級**(menu item = overlay row / Field horizontal = page row)。
 
-**世界級對照**:macOS View menu「Show toolbar」+ ✓ / Figma View menu「Show layout grids」+ toggle / VS Code View menu「Toggle sidebar」+ ✓——都是 menu item + trailing toggle/check 的 canonical 應用。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**世界級對照**:macOS View menu「Show toolbar」+ ✓ / Figma View menu「Show layout grids」+ toggle / VS Code View menu「Toggle sidebar」+ ✓——都是 menu item + trailing toggle/check 的 canonical 應用。 <!-- @benchmark-unverified -->
 
 **外層**:`flex items-start`——多行時 control / prefix / suffix 的 Y 不隨文字下移。
 
@@ -457,13 +463,11 @@ MenuItem 承載 Switch 時,**整列 row 的 click = toggle 這個 control**(不
 
 ---
 
+## 24px 閾值對齊規則(Prefix)與 Suffix inline 對齊
 
-## 24px 閾值對齊規則(Prefix 與 Suffix 共用同一條公式)
-
+**核心原則**:Prefix 的對齊容器高度由**自己內容物的大小**決定(24px 閾值公式);**Suffix 一律 `h-[1lh]` inline 對齊第一行 label**(實作 SSOT:`ItemSuffix` primitive 與 MenuItem suffix slot 皆固定 `h-[1lh]`,見 `menu-item.spec.md`「Suffix 對齊(實作限制)」)。兩 slot 各自獨立,不互相同步。
 
-**核心原則**:每個 slot 的對齊容器高度由**自己內容物的大小**決定。Prefix 和 suffix 用的是**完全一樣**的公式,只是各自獨立判斷,不互相同步。
-
-### 公式
+### 公式(prefix slot)
 
 | 內容物高度 | 對齊容器 | 對齊目標 |
 |---|---|---|
@@ -484,7 +488,7 @@ MenuItem 承載 Switch 時,**整列 row 的 click = toggle 這個 control**(不
 
 **2. 業界 convention 全部如此**
 
-Apple Mail / Gmail / iOS Settings / Material 3 / Atlassian DSP / Polaris ResourceItem——**全部**是「prefix 跟 suffix 各自獨立對齊」。沒有任何一個把小 suffix 強迫對齊到大 avatar 中心。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+Apple Mail / Gmail / iOS Settings / Material 3 / Atlassian DSP / Polaris ResourceItem——**全部**是「prefix 跟 suffix 各自獨立對齊」。沒有任何一個把小 suffix 強迫對齊到大 avatar 中心。 <!-- @benchmark-unverified -->
 
 | 系統 | Prefix(大 avatar) | Suffix(小元素) |
 |---|---|---|
@@ -497,22 +501,20 @@ Apple Mail / Gmail / iOS Settings / Material 3 / Atlassian DSP / Polaris Resourc
 
 把小 suffix 強迫對齊大 avatar 中心,小 suffix 會「下沉」到 description 行,**視覺上跟 label 失聯**。對齊 label 第一行則讓 suffix 跟它修飾的對象在同一條基準線上,視覺重量自然分配。
 
-### 大塊 suffix 的對待方式(symmetric 規則)
+### 大塊 suffix(> 24px)不支援 block 對齊(2026-06-11 收斂對齊實作)
 
-`suffix > 24px` 的場景雖然罕見,但**完全套用同一條公式**——當 suffix 是 thumbnail、stacked badge 等大塊內容時,自己的對齊容器走 block calc,對齊文字塊中心。
+`suffix > 24px`(thumbnail / stacked badge)在 DS 內**零實作、不支援 block 對齊**:`ItemSuffix` primitive 與 MenuItem suffix slot 皆固定 `h-[1lh]` inline(SSOT:`item-anatomy.tsx` ItemSuffix、`menu-item.spec.md`「Suffix 對齊(實作限制)」),本 folder anatomy story 對齊表亦明文「Suffix 所有情況 = 一行文字高度」。世界級同向:上表 Material 3 List trailing icon top-aligned(對齊第一行,非文字塊中心)。
 
 | 場景 | Prefix | Suffix | 結果 |
 |---|---|---|---|
-| 標準選單(MenuItem 大宗) | icon 16px / avatar 24px | Tag / Chevron(≤24px) | 兩邊都 inline |
+| 標準選單(MenuItem 大宗) | icon 16px / avatar 24px | Tag / Chevron(≤24px) | Prefix inline,suffix inline |
 | 用戶選單(avatar + name + role) | avatar 32px(block) | Chevron(≤24px) | Prefix block,suffix inline ← **各自獨立** |
-| 帶縮圖列表(thumbnail + title + 縮圖) | icon 16px(inline) | thumbnail 40px(block) | Prefix inline,suffix block ← **各自獨立** |
-| 雙視覺重的卡片 | avatar 40px(block) | thumbnail 40px(block) | 兩邊都 block |
 
-**沒有「prefix 跟 suffix 必須同步」的情況。** 每個 slot 反映自己內容物的視覺重量,各自走公式。
+**沒有「prefix 跟 suffix 必須同步」的情況。** 未來若需 thumbnail 級大塊 suffix,屬 API 擴充——先回本 spec 補 canonical 再動 primitive。
 
 ### Avatar 尺寸選擇
 
-**用於 prefix slot**。Avatar 尺寸是 **consumer 依視覺重量意圖決定**的——有兩組預設可選,對齊模式跟著 size 走,**不跟著 description 的有無走**。
+**用於 prefix slot**。Avatar 尺寸是 **consumer 依視覺重量意圖決定**的——有兩組預設可選,對齊模式跟著 size 走,**不跟著 description 的有無走**(scope:裸 `<ItemAvatar>` 組合;經 `MenuItem avatar`(AvatarData)高階 API 時由 MenuItem 自動依 description 有無選 inline/block 尺寸——AvatarData 無 size 欄位,見 `menu-item.spec.md`「startIcon vs avatar」)。
 
 **兩組預設尺寸**(依 row size):
 
@@ -530,7 +532,7 @@ Apple Mail / Gmail / iOS Settings / Material 3 / Atlassian DSP / Polaris Resourc
 | > 24 | 無 | `h-[1lh]` inline | 大 avatar 但無 desc,仍對齊第一行(block 沒意義) |
 | > 24 | 有 | `h-[block calc]` block | 大 avatar 視覺重,平衡 label + desc 整個文字塊 |
 
-**關鍵**:consumer 可以自由選擇「小 avatar + description」——那是完全合法的組合,此時 avatar inline 對齊第一行 label,description 從第二行自然往下。沒有「有 desc 就必須用 block 尺寸」的規則。
+**關鍵**:consumer 可以自由選擇「小 avatar + description」——那是完全合法的組合,此時 avatar inline 對齊第一行 label,description 從第二行自然往下。沒有「有 desc 就必須用 block 尺寸」的規則。此自由度屬裸 `<ItemAvatar>` 組合;MenuItem 的 AvatarData API 不暴露此選擇(自動推導,見上 scope 註)。
 
 **程式化規則**(scope:**row context only** — Sidebar / SelectMenu / TreeView / Combobox / Menu 等 row primitive 子樹內):consumer **必須**用 `<ItemAvatar>` / `<ItemIcon>` helper 元件,**禁止** `import { AVATAR_SIZE }` 手動查表,更**禁止**硬寫 `<Avatar size={N} />`。
 
@@ -636,7 +638,7 @@ Label x 位置受 prefix 尺寸影響(icon 16 vs avatar 24,差 8px)。**對齊
 
 **範例**:Sidebar footer 只有一個 user row(Alan Chen)→ 用 inline avatar 24px 的自然預設,不需要縮成 16px 去對齊上方 main nav 的 icon。Main nav 和 footer 是不同 group,本來就該各自獨立。
 
-**業界 convention**:Apple HIG list section、Material 3 list、Atlassian DSP 全部採用「section-scoped consistency」——同一 section 內 leading element 類型一致,跨 section 變化是正常的。沒有任何世界級系統要求整個 sidebar / menu 所有 prefix 強迫同尺寸。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**業界 convention**:Apple HIG list section、Material 3 list、Atlassian DSP 全部採用「section-scoped consistency」——同一 section 內 leading element 類型一致,跨 section 變化是正常的。沒有任何世界級系統要求整個 sidebar / menu 所有 prefix 強迫同尺寸。 <!-- @benchmark-unverified -->
 
 ❌ **錯誤示範**:為了讓 footer avatar 跟 main nav icon 齊左,把 avatar 從 24 改成 16——這是用錯誤方向修了一個根本不存在的問題,且違反 Avatar 尺寸公式。
 
@@ -649,7 +651,7 @@ Label x 位置受 prefix 尺寸影響(icon 16 vs avatar 24,差 8px)。**對齊
 | School | 代表 | 行為 | 我們的預設? |
 |---|---|---|---|
 | A | Slack / VS Code Explorer / Discord | Per-section 獨立 prefix 寬度 | **✅ 預設** |
-| B | Notion / Linear / Atlassian Confluence | 全域對齊 | 🟡 Opt-in via `uniformPrefix` | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+| B | Notion / Linear / Atlassian Confluence | 全域對齊 | 🟡 Opt-in via `uniformPrefix` | <!-- @benchmark-unverified -->
 
 兩派都是世界級慣例,沒有絕對對錯。**選 A 作為預設的理由**:
 
@@ -683,7 +685,7 @@ Label x 位置受 prefix 尺寸影響(icon 16 vs avatar 24,差 8px)。**對齊
 
 ### 其他 row primitive 怎麼接
 
-要對齊 Notion 模式,在 row primitive 的頂層 wrapper(例如 `<TreeView>` 的 root)加: <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+要對齊 Notion 模式,在 row primitive 的頂層 wrapper(例如 `<TreeView>` 的 root)加: <!-- @benchmark-unverified -->
 
 ```tsx
 const slotStyle = getUniformPrefixSlotStyle(size)
@@ -702,12 +704,12 @@ const slotStyle = getUniformPrefixSlotStyle(size)
 - ❌ 拿 escape hatch `uniformPrefix={false}` 配合 mixed prefix 沒有設計理由——這違反使用者視覺直覺,只在「刻意製造視覺斷層」時才該用
 - ❌ 在 row primitive 的某個中層元件再做一次 `:has()` 偵測——應該由頂層容器一次處理,中層不該重複 logic
 
-
-
 ## SelectionItem:Control 跟 Prefix 同高度(不歪斜)
 
 `SelectionItem` 永遠有 **control** slot(checkbox / radio)。當 prefix(icon / avatar)也存在時,**兩者必須在同一條 baseline**——否則視覺歪斜。
 
+> **何時用 SelectionItem(vs 裸 RadioGroup / Checkbox group)**:SSOT → `components/SelectionControl/selection-item.spec.md`「何時用」;本節只 own control + prefix 對齊規則。
+
 ### 規則:control 跟著 prefix 的對齊走
 
 | prefix 模式 | Control 對齊 | Prefix 對齊 | 結果 |
@@ -788,10 +790,10 @@ Block 模式時 checkbox 不在 label 第一行——它跟 avatar 在同一高
 
 | Consumer | Primitive 消費 | Rationale |
 |----------|--------------|-----------|
-| **FileItem**(rich + compact) | ✅ ItemContent + ItemPrefix + ItemInlineActionButton | 純 row-item layout,完美 fit |
+| **FileItem**(rich + compact) | ✅ ItemContent + ItemPrefix(hover action 為 Button xs iconOnly,非 ItemInlineActionButton——2026-04-23 user 統一,見 file-item.tsx)| 純 row-item layout,完美 fit |
 | **Notice / Alert / Toast** | ✅ ItemContent + ItemPrefix | title+desc 標準 row-item 結構 |
 | **ProfileCard** | ✅ ItemContent(+ `labelTruncate=false` + `labelClassName` escape hatch) | 偏離 rationale:card context 用 `text-body-lg font-medium`,非一般 body label |
-| **MenuItem** | ✅ ItemContent(`mode="scanning"\|"scanning-lg"`)+ `itemPrefixAlignVariants` cva SSOT | Content 用 ItemContent 配合 size-aware scanning mode(sm/md = caption / lg = body-compact);label+desc clamp 透過 className escape hatch(MenuItem 特化 labelMaxLines / descMaxLines 語意) |
+| **MenuItem** | ✅ ItemContent(`mode="scanning"` + `size="md"\|"lg"` 正交)+ `itemPrefixAlignVariants` cva SSOT | Content 用 ItemContent 配合 size-aware scanning mode(sm/md = caption / lg = body-compact);label+desc clamp 透過 className escape hatch(MenuItem 特化 labelMaxLines / descMaxLines 語意) |
 | **Sidebar / TreeView** | ✅ ItemPrefix(+ 其他 primitives) | Label-only(無 description),不需 ItemContent |
 | **Empty** | ❌ token-direct only | **結構限制**:centered stack pattern(icon → title → desc → action 垂直居中),非 row-item 佈局。保持手刻 |
 | **Dialog**(DialogTitle / DialogDescription) | ❌ token-direct only | **結構限制**:title 跟 desc 是獨立 Radix `<DialogTitle>` / `<DialogDescription>` component(aria-labelledby / aria-describedby 語義),非同層 span 配對 |
@@ -800,7 +802,7 @@ Block 模式時 checkbox 不在 label 第一行——它跟 avatar 在同一高
 | **Switch**(standalone mode with label+desc) | ❌ token-direct only | **a11y 限制(同 SelectionItem)**:standalone mode 用 `<label htmlFor={inputId}>` 包 label+desc+switch,form control 關聯必要。Control-only mode(放 MenuItem suffix 等)不涉及 label+desc,不在 ItemContent scope |
 | **Steps**(`StepDescription`) | ❌ token-direct only | **API 限制**:StepLabel 跟 StepDescription 是獨立 public forwardRef subcomponent,consumer 分開寫;遷 ItemContent(single-component API)= breaking API |
 
-**共 5 consumer 消費 primitive(FileItem / Notice / ProfileCard / MenuItem / TreeView・Sidebar),5 consumer 保 token-direct 各有 a11y / semantic / API 結構限制**。Token 層 SSOT 100% 覆蓋(改 `--item-gap-label-desc-<mode>[-lg]` 4 變體 → 全 DS 同步);primitive 層覆蓋結構能 fit 的 consumer。
+**共 5 consumer 消費 primitive(FileItem / Notice / ProfileCard / MenuItem / TreeView・Sidebar),6 consumer 保 token-direct(Empty / Dialog / DescriptionList / SelectionItem / Switch / Steps)各有 a11y / semantic / API 結構限制**。Token 層 SSOT 100% 覆蓋(改 `--item-gap-label-desc-<mode>[-lg]` 4 變體 → 全 DS 同步);primitive 層覆蓋結構能 fit 的 consumer。
 
 **Switch 跟 SelectionItem 同 blocker**(2026-04-23 user 糾正):兩者都是 `<label htmlFor>` 表單 control 關聯結構,ItemContent 用 `<span>` 渲染 label 會破壞 form a11y。這類結構**只能 token-level SSOT**(實際已做)。
 
@@ -820,7 +822,7 @@ World-class benchmark(6 家 DS):
 - Polaris / Atlassian / Apple HIG:typography token 手選(無 density prop)
 - 6 家共識:14/20 vs 16/24 兩擋 body 表達 scanning vs reading
 
-本 DS 採 density-prop 派(A 派),跟 Material / Carbon / Ant 對齊。`mode` 比 `dense` 更 self-documenting。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+本 DS 採 density-prop 派(A 派),跟 Material / Carbon / Ant 對齊。`mode` 比 `dense` 更 self-documenting。 <!-- @benchmark-unverified -->
 
 **未來改 scanning typography(e.g. 從 caption 12 改到 caption 13)**:只改 `--font-caption-size` token 一處 → 所有 `mode="scanning"` 的 consumer 同步動。
 
@@ -921,7 +923,6 @@ World-class benchmark(6 家 DS):
 
 ---
 
-
 ## Inline Action 設計規格 → `inline-action.spec.md`(2026-04-24 抽出,獨立 SSOT)
 
 嵌入 Tag dismiss / Field endAction / Row suffix action 的 icon primitive。完整 265 行視覺規格 / API / predicate / Icon 色 / same-row consistency → 見 `patterns/element-anatomy/inline-action.spec.md`。
@@ -1022,19 +1023,23 @@ Selection control(Dropdown / Menu / List / SegmentedControl / Chip)的 item 視
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `alert.spec.md`
+- `color.spec.md`
 - `command.spec.md`
-- `data-table.spec.md`
 - `dropdown-menu.spec.md`
+- `element-anatomy.spec.md`
 - `empty.spec.md`
 - `field.spec.md`
 - `file-item.spec.md`
+- `header-canonical.spec.md`
+- `inline-action.spec.md`
 - `menu-item.spec.md`
 - `notice.spec.md`
-- `overlay-surface.spec.md`
 - `select-menu.spec.md`
 - `select.spec.md`
 - `selection-item.spec.md`
 - `sidebar.spec.md`
+- `steps.spec.md`
+- `tabs.spec.md`
 - `tag.spec.md`
 - `time-picker.spec.md`
 - `toast.spec.md`

package/src/patterns/element-anatomy/item-anatomy.stories.tsx

@@ -812,7 +812,7 @@ const InspectorInner = () => {
               {hasPx && <span><strong style={{ color: Z.pad.text }}>padding-x</strong> = {pxPx}</span>}
               {effectiveHasPrefix && <span><strong style={{ color: Z.icon.text }}>prefix-content gap</strong> = {gapPx}</span>}
               <span><strong style={{ color: Z.label.text }}>py</strong> = {preset.py.includes('calc') ? `calc((field-height-${size} − 一行文字高度) / 2)` : preset.py}</span>
-              {hasDescription && <span>label-desc gap = --item-gap-label-desc-reading (2px)</span>}
+              {hasDescription && <span>{`label-desc gap = --item-gap-label-desc-${preset.mode}${size === 'lg' ? '-lg' : ''} (2px)`}</span>}
             </div>
           </div>
         </div>
@@ -839,7 +839,7 @@ const InspectorInner = () => {
               <TkVal token={preset.gap} value={preset.gapDesc} />
             </PropRow>
             {hasDescription && (
-              <PropRow label="label-desc" dot={Z.gap.text}><TkVal token="--item-gap-label-desc-reading" value="2px" /></PropRow>
+              <PropRow label="label-desc" dot={Z.gap.text}><TkVal token={`--item-gap-label-desc-${preset.mode}${size === 'lg' ? '-lg' : ''}`} value="2px" /></PropRow>
             )}
             {effectiveHasSuffix && (
               <PropRow label="suffix gap" dot={Z.suffix.text}>
@@ -1507,7 +1507,7 @@ export const IconActionPrimitiveDecision = {
               <tr><Td>Tag dismiss X</Td><Td>Pill body</Td><Td mono>Inline Action</Td><Td>Colored host,繼承顏色</Td></tr>
               <tr><Td>Menu / TreeView suffix action</Td><Td>Row inline flow</Td><Td mono>Inline Action</Td><Td>Inline with content</Td></tr>
               <tr><Td>SidebarGroup header chevron</Td><Td>Aux toggle</Td><Td mono>Inline Action</Td><Td>Inline header toggle</Td></tr>
-              <tr><Td><strong>FileItem compact</strong>(row 24)</Td><Td>Row slot</Td><Td mono>Inline Action</Td><Td>Row 太小容不下 Button xs 24</Td></tr>
+              <tr><Td><strong>FileItem compact</strong>(row 24)</Td><Td>Row slot</Td><Td mono>Button xs iconOnly</Td><Td>2026-04-23 user 統一 rich + compact 同 primitive(field-height-xs 容器 + data-unbounded 收斂)</Td></tr>
               <tr><Td><strong>FileItem rich</strong>(row 56)</Td><Td>Row slot</Td><Td mono>Button xs iconOnly</Td><Td>&le; 24 cap,不放大</Td></tr>
               <tr><Td><strong>DataTable row action</strong></Td><Td>Row dedicated column</Td><Td mono>Button xs iconOnly</Td><Td>&le; 24 cap(跨 tier 固定)</Td></tr>
               <tr><Td><strong>Dialog / Sheet chrome corner close</strong></Td><Td>Action group region</Td><Td mono>Button sm iconOnly dismiss</Td><Td>corner 屬 action group,可與 refresh / share 並排</Td></tr>
@@ -1591,8 +1591,8 @@ export const IconActionPrimitiveDecision = {
             </div>
           </div>
           <div className="flex items-center gap-3 px-3 py-2 rounded-md border border-border bg-surface">
-            <span className="flex-1 text-caption text-fg-secondary">✅ compact row:都用 Inline Action(icon 16,hover-bg 18,size="sm")</span>
-            <div className="flex items-center gap-1">
+            <span className="flex-1 text-caption text-fg-secondary">✅ compact row:都用 Inline Action(icon 16,hover-bg 18,size="sm",gap-2)</span>
+            <div className="flex items-center gap-2">
               <ItemInlineActionButton icon={RotateCw} size="sm" aria-label="重試" />
               <ItemInlineActionButton icon={Download} size="sm" aria-label="下載" />
               <ItemInlineActionButton icon={MoreVertical} size="sm" aria-label="更多" />
@@ -1600,7 +1600,7 @@ export const IconActionPrimitiveDecision = {
           </div>
           <div className="flex items-center gap-3 px-3 py-2 rounded-md border border-error bg-surface">
             <span className="flex-1 text-caption text-error-text">❌ 禁止混 Inline Action + Button(box 尺寸不一致)</span>
-            <div className="flex items-center gap-1">
+            <div className="flex items-center gap-2">
               <ItemInlineActionButton icon={RotateCw} size="sm" aria-label="重試" />
               <Button variant="text" size="xs" iconOnly startIcon={Download} aria-label="下載" />
             </div>

package/src/patterns/element-anatomy/item-anatomy.tsx

@@ -215,7 +215,7 @@ ItemPrefix.displayName = "ItemPrefix"
  * 直接用 `<ItemPrefix>` 就好,不需此 cva。
  *
  * ── SSOT 傳播 ──
- * gap 用 `var(--item-gap-label-desc)` token;font-size 用 token-awareness
+ * gap 用 `var(--item-gap-label-desc-scanning[-lg])` token(bare 變體已不存在,4 個 mode×size 變體);font-size 用 token-awareness
  * (`var(--font-caption-size)` / `var(--font-body-size)`)。改 token → 公式同步。
  */
 // code-quality-allow: long-function — cva variant/styles table — 拆 fn 會失去 type inference + 跨 fn 傳 config 反而難讀
@@ -270,7 +270,7 @@ ItemLabel.displayName = "ItemLabel"
  * `<ItemContent>` — Row primitive 的 label + optional description 內容區(SSOT)。
  *
  * ── 存在的唯一理由 ──
- * 封裝「flex-col + label + description + `mt-[var(--item-gap-label-desc)]` gap」結構,
+ * 封裝「flex-col + label + description + `mt-[var(--item-gap-label-desc-<mode>[-lg])]` gap」結構,
  * 避免 13+ 消費者各自 hard-code `mt-0.5`。改 token 一處,全 DS 同步。
  *
  * ── Consumer 偏離 canonical ──
@@ -278,7 +278,7 @@ ItemLabel.displayName = "ItemLabel"
  * 該元件 `spec.md` 明文寫下 rationale(對齊 item-anatomy canonical「偏離必明文」)。
  * 合法偏離範例:
  *   - MenuItem 的 `leading-compact + text-caption` scanning-mode typography
- *     → MenuItem spec 明文 rationale + 消費 `--item-gap-label-desc` token 直接用
+ *     → MenuItem spec 明文 rationale + 消費 `--item-gap-label-desc-scanning[-lg]` token 直接用
  *   - SelectionItem 的 control slot 跟 block formula 綁定
  *     → SelectionItem spec 明文 rationale
  *

package/src/patterns/header-canonical/chrome-header.tsx

@@ -55,8 +55,9 @@ export interface ChromeHeaderProps
    * Tabs row slot(2026-05-18 加 per W2/W4 真實能用 + user-mandated fix)。
    * 提供時 ChromeHeader 自動 column 結構:
    *   row 1 = children(h-chrome-header-height 固定,px-loose,跟 single-row 模式同)
-   *   row 2 = tabsSlot 包在 `<div px-loose border-b border-divider>`
-   *           ↑ wrapper 提供 W2 padding inheritance + W1 全寬 paint(一條線)
+   *   row 2 = tabsSlot 包在 `HEADER_TABS_SLOT_WRAPPER_CLASS` wrapper
+   *           (`[&>[role=tablist]]:w-full` + 注入 TabsList 內 px-loose;wrapper 本身
+   *           無 padding 無 border——border 由 TabsList 自畫,W1 全寬 paint 一條線)
    *
    * Consumer 傳:`tabsSlot={<TabsList>...</TabsList>}`,TabsContent 放 ChromeHeader 之外。
    * Standalone Tabs(無 chrome header)該直接用 `<TabsList>` 不需 wrapper。