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

package/src/lib/drag-visual.ts

@@ -6,7 +6,7 @@
  *
  * ## Pattern
  *
- * - **Source element**(被拖中的 row/column):`opacity-30`(半透,user 仍看得到原位)
+ * - **Source element**(被拖中的 row/column):`opacity-disabled`(= var(--opacity-disabled) 0.45 半透,user 仍看得到原位;2026-05-06 v14.5.2 由 opacity-30 改)
  *   — 不是 `opacity:0` 全隱形,因 user 拖太遠看不到「源頭」會迷失方向。對齊 TreeView 最早 v1 + Notion / Atlassian / Linear。
  * - **Ghost preview**(浮動 follow cursor):透過 dnd-kit `<DragOverlay>` portal,clone source 的 outerHTML
  *   strip transform/transition/opacity → render 在 portal 層,visually 跟 cursor 走。
@@ -26,7 +26,7 @@
  * - `bg-primary`:semantic state token(`--primary`)— 跟 focus state ring color 同 source(M23 一致)
  * - `bg-primary-subtle`:semantic primary subtle(`--primary-subtle`)— inside-drop dim background
  * - `h-0.5` / `w-0.5`:Tailwind size token = 2px(對齊 hairline divider thickness 概念)
- * - `opacity-30`:Tailwind 30% opacity(半透但仍清楚看到 outline)
+ * - `opacity-disabled`:DS token var(--opacity-disabled)= 0.45(半透但仍清楚看到 outline;見下方 v14.5.2 note)
  */
 
 import type * as React from 'react'

package/src/lib/utils.ts

@@ -36,7 +36,8 @@ const twMerge = extendTailwindMerge({
         'text-fg-muted',
         'text-fg-disabled',
         'text-inverse-fg',
-        'text-on-emphasis',  // 白字於飽和色底(Avatar color variants / Steps filled indicator)
+        'text-on-emphasis',       // 白字於夠深的飽和色底(Avatar / Tag solid / Steps filled indicator)
+        'text-on-emphasis-dark',  // 深字於太亮的飽和色底(yellow/amber/orange/lime solid;原 warning-foreground)
 
         // Status 基色(base)
         'text-primary',
@@ -91,3 +92,22 @@ const twMerge = extendTailwindMerge({
 export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs))
 }
+
+// ── line-clamp 安全對照(2026-07-18 決策4)────────────────────────────────────
+// 動態 `line-clamp-${n}` / `line-clamp-[${n}]` = Tailwind 掃不到具體值 → silent 失效(失敗記憶索引:
+//   「Tailwind v4 動態 class」陷阱)。此 map 全靜態字串 → Tailwind 可掃。canonical 上限 1-6(spec maxLines/
+//   descriptionClamp ≤6);超界值 dev-warn + clamp 回 6(不 crash、不靜默失效)。null/0/undefined → 不 clamp。
+const LINE_CLAMP: Record<number, string> = {
+  1: 'line-clamp-1', 2: 'line-clamp-2', 3: 'line-clamp-3',
+  4: 'line-clamp-4', 5: 'line-clamp-5', 6: 'line-clamp-6',
+}
+export function lineClampClass(n: number | undefined | null): string | undefined {
+  if (n == null || n <= 0) return undefined
+  const rounded = Math.round(n)
+  if (rounded !== n || n > 6) {
+    if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
+      console.warn(`[DS] line-clamp 值 ${n} 超出 canonical 範圍 1-6(或非整數)→ clamp 回 6。請傳 1-6 整數。`)
+    }
+  }
+  return LINE_CLAMP[Math.min(6, Math.max(1, rounded))]
+}

package/src/patterns/README.md

@@ -1,29 +1,33 @@
 # patterns/ Charter
 
-## 這裡只收:runtime UI 佈局 / 互動 primitive
+## 這裡收:多元件共用的視覺 primitive + 跨元件設計參照(anatomy)+ 組合指南
 
-每個 pattern 提供**多元件在 runtime 實際消費**的東西:
-- `.tsx` / `.ts` 實作(primitive component / hook)
-- `.spec.md` 設計原則
-- `.stories.tsx` 展示
-- `.example.tsx`(選用)
+每個 pattern 是「給多元件 runtime 消費」**或**「給人/AI 設計時參照」的東西,三型:
+- **runtime primitive / hook**(`.tsx` / `.ts` 實作)— eg. `ChromeHeader`(公開組合 primitive,對標 item-anatomy MenuItem/slots)/ `SurfaceHeader` / `useOverflowItems`(後二者 internal:`internal: true`)
+- **跨元件設計參照 / anatomy**(可見消費者文件)— eg. `item-anatomy` 的 4-slot 結構 + 24px 閾值 + scanning/reading 模式 + Inspector;對齊世界級 **Material/Carbon「Anatomy」可見參照**(2026-06-06 研究:4 家 DS 一律把 anatomy 當可見第一線文件,**不藏**)
+- **跨元件組合指南**(spec 為主,**可無 `.tsx`**)— eg. `action-bar` 的 role 系統 / 排列公式;對齊世界級 **Polaris/Atlassian/Carbon「Pattern = 組合多元件解決情境的指南」**
+- 配 `.spec.md` 設計原則 + `.stories.tsx` 展示(**範例 = 人/AI 設計時的必要可見參照,不可藏**)
 
-**核心特徵**:元件 code 會 `import` 這個 pattern 使用,或遵循它畫出相同視覺結構。
+**核心特徵**:元件 code `import` 它,或設計時遵循它的結構/指南。
+
+**audience-split(2026-06-06 研究 codify;對齊 Polaris/Carbon「Contributing 區」分界)**:
+- ✅ 進這裡(可見前台)= 設計師/工程師**消費時要看的設計參照**(anatomy / 範例 / 組合指南)。
+- ❌ **不**進這裡 = 「我們內部怎麼把東西分 component/pattern/internal/token」這種**分類/治理 meta** → 屬 `.spec.md` + `.claude/` 治理層(世界級放 **Contributing** 區,不放消費前台 Storybook;Storybook 只放範例)。
 
 ## Public pattern vs Internal pattern(2026-05-23 user 永久拍板 SSOT)
 
-詳定義 → `.claude/rules/ui-development.md`「Public component vs Internal primitive canonical」段。
+詳定義 → `packages/design-system/ds-canonical/rules/ui-development.md`「Public component vs Internal primitive canonical」段。
 
-- **Public pattern**:end-user app 可直接 `<X />` render(`action-bar` / `resize-handle` / `element-anatomy` MenuItem)。Storybook title `Design System/Patterns/<Name>`。
-- **Internal pattern**:end-user app 直接 render 無 functioning UI,需 DS 內部其他元件 wrap(`header-canonical/ChromeHeader` / `horizontal-overflow useOverflowItems` / `overlay-surface SurfaceHeader/Body/Footer`)。Storybook title `Design System/Internal Patterns/<Name>`。Frontmatter `internal: true`。Export jsDoc `@internal`。
-- 下方 "當前居民" 表「Consumer」欄 = **DS-internal consumer**(不是 end-user app)— 若 Consumer 全是 other DS components → internal pattern。
+- **Public pattern**:consumer 可直接 import 用,或作為公開設計原則 / anatomy 參照(`action-bar` / `resize-handle` / `element-anatomy`(item-anatomy + slots)/ `header-canonical`(ChromeHeader header anatomy))。Storybook title `Design System/Patterns/<Name>`。
+- **Internal pattern**:只被 DS 內部其他元件 wrap、consumer 不直接碰且**無公開 anatomy 參照**(`horizontal-overflow useOverflowItems` / `overlay-surface SurfaceHeader/Body/Footer`)。Storybook title `Design System/Internal Patterns/<Name>`。Frontmatter `internal: true`。Export jsDoc `@internal`。
+- 下方 "當前居民" 表「Consumer」欄 = **DS-internal consumer**(不是 end-user app)— 若 Consumer 全是 other DS components 且**無公開 anatomy 參照** → internal pattern;但 anatomy 設計原則(item-anatomy / header-canonical)即使 runtime primitive 的 consumer 全是 DS 元件,其 anatomy story 仍是**公開 Patterns**(對齊世界級「anatomy 不藏」)。
 
 ## 當前居民
 
 | Pattern | 提供什麼 runtime primitive | Consumer |
 |---------|-------------------------|----------|
 | `element-anatomy/` | flat 多檔 home:<br>• `element-anatomy.spec.md` — 4-family taxonomy overview(F1-F4,F3/F4 pointer out)<br>• `item-anatomy.{spec.md,tsx,stories.tsx}` — F1/F2 row 深度 SSOT + runtime primitive(`<MenuItem>` + slot components `<ItemIcon>` / `<ItemAvatar>` / `<ItemLabel>` / `<ItemSuffix>` / `<ItemInlineAction>`) | Menu / Tree / Sidebar / File / Selection 等 row 元件;所有元件 spec 第一段宣告 Family 時查 element-anatomy.spec.md |
-| `action-bar/` | `action-bar.tsx` + `action-bar.spec.md` — toolbar / action row 排列公式 | 任何有按鈕列的頁面 |
+| `action-bar/` | **組合指南 pattern**(`action-bar.spec.md` — toolbar / action row 的 role 系統 + 排列公式;**無 `.tsx`**,屬 guidance 非 runtime 件 — 對齊世界級「pattern = 組合指南」)| 任何有按鈕列的頁面,用 Button / ButtonGroup / ButtonDivider 依此指南組合 |
 | `horizontal-overflow/` | `useOverflowItems` hook + fade-mask 樣式 | Tabs / ChipGroup |
 | `overlay-surface/` | `SurfaceHeader/Body/Footer` sub-components + padding SSOT | Dialog / Popover / Sheet |
 | `header-canonical/` | `<ChromeHeader>` primitive(withTabs / lockDensity 窄 API)+ cross-family canonical SSOT(chrome + overlay 兩家族 W1-W6 lockstep:border auto-suppress / token equality / tabs size 對應 / flush stack / md future tier / sm default)| Sidebar / FileViewer Toolbar / FileViewer InfoPanel(ChromeHeader 直接消費);Dialog / Sheet / Popover(SurfaceHeader 走 cross-family canonical)|
@@ -38,10 +42,10 @@ element-level 結構分類永遠用 **anatomy**(Material / Polaris / Atlassian /
 
 | 疑似要放這但其實不是 | 實際應去 | 為什麼 |
 |-------------------|---------|--------|
-| 「怎麼寫 story」的指南 | `.claude/skills/story-writing/` | 文件撰寫 workflow,不是 runtime primitive。AI 只在寫 story 時需要 |
-| 「元件完成清單」/ 品質 gate | `.claude/skills/component-quality-gate/` | 是 invoke-time checklist,不是 runtime primitive |
-| 「規則放哪裡」的 8-home 指南 | `.claude/skills/design-system-audit/references/rule-placement.md` | governance reference,audit skill 相關 |
-| CLAUDE.md 某段太長想搬出來 | 先看 8-home flowchart:是 runtime pattern 才來這 | 「要搬出 CLAUDE.md」不等於「該放 patterns/」 |
+| 「怎麼寫 story」的指南 | `packages/design-system/ds-canonical/skills/story-writing/` | 文件撰寫 workflow,不是 runtime primitive。AI 只在寫 story 時需要 |
+| 「元件完成清單」/ 品質 gate | `packages/design-system/ds-canonical/skills/component-quality-gate/` | 是 invoke-time checklist,不是 runtime primitive |
+| 「規則放哪裡」的 Level 1–9 taxonomy | `packages/design-system/ds-canonical/skills/design-system-audit/references/rule-placement.md` | governance reference,audit skill 相關 |
+| provider instruction 某段太長想搬出來 | 先看 Level 1–9 rule-placement taxonomy:是 runtime pattern 才來這 | 「要搬出 provider instruction」不等於「該放 patterns/」 |
 | 單一元件的規則 | `components/{Name}/{name}.spec.md` | 只 1 個元件影響範圍 |
 | Token 命名規則 | `tokens/` 對應 spec | |
 | Cross-cutting non-visual primitive(i18n / formatters / type modules)| `packages/design-system/src/lib/{topic}/` | 無 visual surface — 對齊 Material `@mui/material/locale` / Ant ConfigProvider 共識 |

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

@@ -1,4 +1,4 @@
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — verified 0 world-class DS claim in body; blanket retract removed. -->
+<!-- @benchmark-unverified-blanket: body 含 pattern 級 world-class 對照(世界級對照表 L17-24 + Variant narrow-scope 對照 L141-156:Material/VS Code/Figma/Atlassian/Polaris/Linear/GitHub/Gmail/Notion/MUI/Carbon),為 named-reference 級而非 per-source URL/#L/snapshot cite,故 file-level 標 unverified-blanket。 -->
 
 # Action Bar 設計原則
 
@@ -89,7 +89,7 @@ Search 的角色**不由「產品核心是不是搜尋」決定**，而由——
 ┌──────────────────────────┐ ┆ ┌──────────────────────┐
 │       業務操作群組        │ ┆ │  工具操作    溢出      │
 └──────────────────────────┘ ┆ └──────────────────────┘
-       Operations tier               Utilities tier
+    業務層(Operations)          工具層(Utilities)
 ```
 
 兩種對齊的差異只在業務層內部排序方向，工具層位置不變：
@@ -116,9 +116,9 @@ Search 的角色**不由「產品核心是不是搜尋」決定**，而由——
 
 | | |
 |--|--|
-| **允許 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 決定排序位置 |
+| **允許 variant** | primary、secondary、tertiary、text（`link` 是導覽語意,不屬於操作列）。**啟用態(on/checked)不是 variant** —— 由 `pressed` prop 表達(產生 `data-state=on`) |
+| **Variant 選擇** | 以有框 variant（primary、secondary、tertiary）為主,`text` 用於視覺重量最低的輔助操作。有框操作定義「這是操作區的重心」,text 是補充,不是預設。可切換按鈕維持其 variant + 加 `pressed` toggle(非換成 checked variant) |
+| **全局排序** | 先對所有可見業務按鈕做全局排序：`primary > secondary > tertiary > text`；靠右對齊時 primary 在業務層最右，靠左對齊時 primary 在業務層最左（工具層永遠在業務層右側，見第二節）。正確排序後有框操作自然在前、text 在後，不需要額外的集中規則。切換按鈕（維持 variant + `pressed` toggle）依預設（未啟用）狀態的 variant 決定排序位置 |
 | **danger 位置** | `danger` 不影響跨 variant 排序。同 variant 內，danger 排在非 danger 之後（遠離主要焦點）。`primary+danger` 不受此規則影響——在刪除確認等場景中，破壞性操作本身就是主要動作 |
 | **danger 可見性** | 破壞性操作預設收進溢出選單。只有同時滿足**高頻**（使用者每次進入此畫面都可能用到）且**可逆**（有 undo 或垃圾桶機制）時，才值得攤開為可見按鈕。頻率不夠高或不可逆的破壞性操作，攤開只會增加誤觸風險（Gmail 的教訓：Delete 從預設可見改為隱藏，因為誤觸是最大客訴） |
 | **功能性分群** | 排序完成後，依功能關係在適當位置加分隔線形成群組；**不要先定義群組再各自排序**（會導致多個 primary 競爭焦點） |
@@ -130,19 +130,19 @@ Search 的角色**不由「產品核心是不是搜尋」決定**，而由——
 | 狀態 | Variant | Label |
 |------|---------|-------|
 | 未配置 | `text`（預設，在 Toolbar 脈絡下）／`tertiary`（脈絡不明確時，見下方 affordance 原則） | 通常 icon-only；脈絡不明確時補 label |
-| 已配置 / 啟用 | `checked`（`data-state=on`） | icon-only |
+| 已配置 / 啟用 | 維持 variant 不變 + `pressed={true}`（產生 `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），存在感更強
+**啟用態（`data-state=on`）的視覺由 `pressedTone` prop 決定（非底層 variant）**：
+- `pressedTone="emphasis"`（**button.tsx 預設**）→ `bg-primary-subtle` + `text-primary`（藍底 + 藍色 icon），存在感強。secondary / tertiary / text 三者在此 tone 下視覺相同
+- `pressedTone="neutral"` → `bg-neutral-selected`（灰底 + 原色 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 |
+| **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 |
 
@@ -163,7 +163,7 @@ Search 的角色**不由「產品核心是不是搜尋」決定**，而由——
 |--------|---------|
 | 純動作工具（點了就執行，無當前狀態） | `text` |
 | 可切換工具（全螢幕等）— 未啟用 | `text` |
-| 可切換工具 — 已啟用 | `checked` |
+| 可切換工具 — 已啟用 | 維持 variant（如 `text`）+ `pressed={true}` |
 
 **不允許**：primary、secondary（工具層必須是操作列中最低視覺重量）。`danger` 不適用於工具層——破壞性操作一定是對物件的業務操作，不是環境調整。
 
@@ -254,36 +254,44 @@ Icon 的目的是幫助辨識，不是視覺對稱。
 
 ## 五、分隔線規則
 
-分隔線有兩種語意，各自適用不同場景：
+分隔線**只有四個正當理由**。每一條線都必須對得上其中一個；對不上就是裝飾，不得存在。
 
-**群組溢出邊界**
-群組溢出（···）標記一個群組的結束。**群組溢出右側必須加分隔線**，無論右側是另一個業務群組還是工具層，也無論右側的視覺類型為何。群組溢出邊界優先於角色接壤：即使右側是 text 工具層，只要有群組溢出，就必加分隔線。
+| # | 理由 | 判準 | 加不加 |
+|---|------|------|--------|
+| 1 | **群組結束** | 群組溢出（···）的右側，無論右側是什麼 | **必加** |
+| 2 | **邊界看不見** | 相鄰兩側視覺同類（都無框 / 都有框），不畫線就分不出換群 | **必加** |
+| 3 | **誤觸保護** | 關閉 / 解除鈕的**左側緊鄰其他操作按鈕** | **必加** |
+| 4 | **功能域切換** | 兩側分屬不同功能域，且需要讓使用者看出這個切換 | **可加**（須具名理由） |
 
-**角色接壤（無群組溢出時）**
-業務層沒有群組溢出，最後一個真實業務按鈕直接接工具層：
+**視覺差異不是禁令**（2026-08-06 修訂）：有框 ↔ 無框的對比只會讓**理由 2 不成立**（邊界本來就看得見），**不構成禁止**。若同一位置存在理由 1 / 3 / 4，照樣加線。舊版寫「有框結尾 → 工具層 text ＝ 不加」是把「充分條件」寫成了「排他條件」，與同表的「功能性分群可選」及「群組溢出無論右側視覺類型」自相矛盾，故移除。
 
-```
-[...  最後一個業務按鈕]  ?  [第一個工具按鈕  ...]
-          有框         →       無框     = 不加（視覺差異已標記邊界）
-          無框         →       無框     = 必須加（邊界不可見）
-```
+**理由 3 的三個邊界情況**（與實作一致）：
+
+- 關閉鈕**左邊沒有操作按鈕**（它是唯一操作）→ **不加**。沒有東西需要被隔開。
+- 關閉鈕與其他操作之間**隔著非操作內容**（如 BulkActionBar 的「已選 N 筆」文字 + 既有分隔線）→ **不加**。隔離已經存在，再加一條是重複標記。
+- 關閉鈕**不在操作列末端**（如 BulkActionBar 置於最左）→ 理由 3 不適用，其左側是容器邊緣而非其他操作。
+
+**理由 4 的具名要求**：加線者必須在該處寫下它區隔的是**哪兩個功能域**（程式碼註解或 story label）。說不出來就是裝飾。「看起來比較整齊」「對稱」「習慣這樣」都不是理由。
+
+**優先序與去重**：理由 1 高於其他（群組邊界即使右側是 text 工具層也必加）。多個理由同時成立時**只畫一條線**，不疊加。
 
-**溢出按鈕（···）本身不構成工具層。** 工具層的存在取決於是否有固定工具按鈕（⚙ 設定、↺ 刷新、⤢ 全螢幕等）。沒有固定工具按鈕時，··· 是業務層的末端，不存在角色邊界，不加角色邊界分隔線。
+**孤立檢查（結果導向的自我驗證）**：任何一顆按鈕若左右兩側都有線，代表其中一條沒有真正的理由 —— 回頭逐條檢查理由，刪掉對不上的那條。
 
-| 情境 | 分隔線 | 依據 |
-|------|--------|------|
-| 群組溢出右側（接任何內容） | **必須** | 群組溢出邊界 |
-| 業務層有框結尾 → 固定工具 text（無群組溢出） | **不加** | 角色接壤：視覺差異已足夠 |
-| 業務層無框 text 結尾 → 固定工具 text（無群組溢出） | **必須** | 角色接壤：邊界不可見 |
-| 業務操作層內的功能性分群 | **可選** | 同視覺類型功能域不同，視需要加 |
-| 固定工具 → 全域溢出（同屬工具層） | **不加** | 同屬工具層 |
-| 無固定工具（··· 是業務層末端） | **不加** | 沒有工具層，沒有角色邊界 |
-| 最右側為關閉 / 解除按鈕 | **必須** | 誤觸保護 |
-| 單一按鈕兩側都有分隔線 | 審查兩條各自的語意理由；正確套用規則後孤立自然不出現，若出現則代表某條分隔線應移除 | 孤立是症狀，根因是無語意的分隔線 |
+**落點歸屬（誰放這條線）**：由 DS 元件自動放，consumer 零自刻。已落地：Dialog 標題列（`dialog.tsx:184-193`）、Notice 家族（`notice.tsx`，Alert / Toast 共用同一基座因此行為一致）、ButtonGroup（`ButtonDivider`）。Consumer 自刻是「漏放 / 幾何漂移」的根因。
 
-**分隔線語意判斷**：遵守以上規則後孤立自然不出現。若出現孤立，先問「這條分隔線有語意理由嗎？」而非接受孤立。
+**切換按鈕**：`text` + `pressed` toggle——依預設（未啟用）狀態決定位置與分隔線；切為啟用（`pressed=true`）時不移動、不調整分隔線（啟用態不是 variant，見三節）。
 
-**切換按鈕**：`text ↔ checked` 依預設（text）狀態決定位置與分隔線；切換為 checked 時不移動、不調整分隔線。
+### 分隔線幾何(2026-07-08 WM 戰役 codify,user 拍板 — **scope 僅限本節語意的「action region 群組分隔線」**)
+
+**版面切分的 divider(pane `border-l` / 全高欄界 / 區塊邊界)不適用本段 — 那類是 border,兩側零 gap、貼齊版面。**
+
+**唯一實作 = `<ButtonDivider />`**(`components/Button/button-group.tsx`)。consumer 與 DS 元件都不得手寫高度,也不再用 `<Separator>` 畫 action region 群組線 —— 兩套機制是 2026-08-07 之前長度四散(13/16/24px)的根因。
+
+- **長度**(垂直軸唯一定義):**線長 = 所在那一列「最高元件」的高度 − `--action-divider-inset`(8px),不短於 `--action-divider-min`(16px),垂直置中**。基準是最高元件而非容器,故同列每條線必然等長(不參差),換尺寸階時自動跟著走:xs 24→16 / sm 28→20 / md 32→24 / lg 密度 36→28,比值 0.67–0.78。inset 8px 是我們尺寸階唯一可行值(世界級「撐滿再減」的兩家各減 16px,但最小控件 32px;套到我們 24px 的 xs 階只剩 8px,比 Button 圖示 16px 還矮一半)。min 16px 不是新常數,是**本公式在最小控件階的取值**(`--field-height-xs` 24px − 8px),故地板永不覆寫公式,只在「容器宣稱高度比自身內容還矮」時(如 `ItemSuffix` 的 `h-[1lh]`=21px 卻裝 24px 控件)修回誠實值;`--field-height-xs` 不隨 density 縮放,min 在任何密度成立。Token SSOT = `tokens/uiSize/uiSize.css`。
+- **前提**:必須住在**自動高度的 cluster** 內。直接置於固定高度容器(48/56px chrome header)時基準會退化成容器高 —— CSS 無法在容器有明確高度時看見「最高手足」。
+- **水平間距** = 自身兩端各 4px 於 `gap-2` 容器 → 兩側各 8+4 = 12px 對稱。
+- **世界級對照**(長度):做過真工具列的四家全部矮於控件,無一等高 —— VS Code 固定 16px(`height:16px`,同檔 `.codicon` 亦 16px,https://github.com/microsoft/vscode/blob/main/src/vs/base/browser/ui/actionbar/actionbar.css)/ Primer `ActionBar.VerticalDivider` 固定 20px + `margin-top: calc((控件高 − 20px)/2)` 置中(https://github.com/primer/react/blob/main/packages/react/src/ActionBar/ActionBar.module.css)/ Fluent `ToolbarDivider` 因 Toolbar `alignItems:center` 落在 `minHeight: 20px` 地板(https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-divider/library/src/components/Divider/useDividerStyles.styles.ts)/ JetBrains `ActionToolbarImpl` 以最高按鈕反推(maxButtonHeight − 5px)。等長於控件的先例(Ant `Space.Compact` / Chakra `Group attached` / SLDS button-group / Atlassian split button)全屬**控件內部接縫**——線就是控件自己的邊框,與群組分隔線是不同問題。語意依據:Fluent「block dividers → strict distinction;inset → imply closer relationships」+ Material「full width 分隔不相關大區塊,inset 分隔區塊內相關內容」;工具列的兩個 action 群是同列近親 → 屬 inset 定義域。
+- **禁**:`h-full` / 手寫任何高度 class / 單側 margin / 用 `<Separator>` 畫 action region 群組線。
 
 ---
 
@@ -331,6 +339,7 @@ Icon 的目的是幫助辨識，不是視覺對稱。
 ### 共通規則
 
 - 溢出按鈕不構成工具層。工具層需要有固定工具按鈕（⚙ 設定、↺ 刷新、⤢ 全螢幕等）才存在，只有 ··· 不算
+- 溢出選單本體的浮層行為（超出 viewport 的 collision 翻轉 / 內容過長捲動 / Esc 關閉 / 鍵盤導覽）由 `DropdownMenu` own（Radix 預設），本 pattern 不重定義
 - **如果操作列出現大量溢出按鈕，這是資訊架構的問題，應回到功能規劃層重新設計**
 
 ---
@@ -372,13 +381,13 @@ Icon 的目的是幫助辨識，不是視覺對稱。
 [儲存(framed) | 複製(framed) | 🗑(text danger)] ┆ [↺(text) | ···global] ┆ [✕]
                                                   ↑                        ↑
                                               text→text 角色接壤      關閉保護
-      有框→無框接壤，不加分隔線（視覺差異已足夠）
+      有框→無框：沒有對上任何理由，所以不加（不是因為「禁止」）
 ```
 
-- 儲存、複製 = 有框業務（tertiary）；🗑 = 無框業務（text danger）→ 有框集中在前，不加分隔線
-- 🗑（業務）→ ↺（工具）= text→text 角色接壤 → 必加分隔線
-- ↺ → ···global = 同屬工具層 → 不加分隔線
-- ✕ 在末端 → 關閉保護，分隔線在 ✕ 左側；···global 左側一條（角色接壤），右側一條（關閉保護），各有語意
+- 儲存、複製 = 有框業務（tertiary）；🗑 = 無框業務（text danger）→ 同屬業務層、無功能域切換 → 不加
+- 🗑（業務）→ ↺（工具）= 兩側都無框，邊界看不見 → 必加（理由 2）
+- ↺ → ···global = 同屬工具層、視覺同類但無換群 → 不加
+- ✕ 在末端且左邊緊鄰 ···global → 必加（理由 3 誤觸保護）；···global 左側那條屬理由 2，兩條各有理由，不是孤立
 
 ### ❌ 同優先等級業務操作，icon 處理不一致
 
@@ -425,15 +434,17 @@ Icon 的目的是幫助辨識，不是視覺對稱。
 ├── 移除它，使用者無法完成任務  →  業務操作
 │     ├── 一般操作                →  label 或 icon + label
 │     ├── 含多個子選項            →  + endIcon={ChevronDown}
-│     └── 可配置資料操作          →  text（未配置）/ checked（已配置）
+│     └── 可配置資料操作          →  text + pressed（未配置 pressed=false / 已配置 pressed=true）
 │           └── 需要更強可操作性提示  →  tertiary（未配置）
 └── 跟任務無關，服務環境          →  工具操作  →  icon-only + tooltip
 
-有工具層嗎？
-├── 有  →  業務層用什麼結尾？
-│           ├── 有框按鈕      →  不加分隔線（有框→無框視覺差異已足夠）
-│           └── 無框 text 按鈕 →  必須加分隔線（無框→無框邊界不可見）
-└── 無  →  不加任何分隔線（除非有關閉按鈕保護需求）
+這裡要不要分隔線？（逐條對理由，對不上就不加）
+├── 左邊是群組溢出（···）嗎？                    →  必加（群組結束）
+├── 兩側視覺同類、不畫就分不出換群嗎？            →  必加（邊界看不見）
+├── 右邊是關閉鈕，且它左邊緊鄰其他操作按鈕嗎？    →  必加（誤觸保護）
+│     └── 只有關閉鈕 / 中間隔著文字 / 關閉鈕不在末端  →  不加
+├── 兩側分屬不同功能域且需要讓人看出來嗎？        →  可加（須寫明是哪兩個域）
+└── 以上皆非                                     →  不加（有框↔無框的視覺差異本身不是加線理由，也不是禁令）
 
 溢出用哪種？
 └── 所有群組的低頻操作放進同一個選單，使用者能快速找到目標嗎？
@@ -443,16 +454,23 @@ 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`
 - `popover.spec.md`
+- `separator.spec.md`