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

package/src/tokens/color/semantic.css

@@ -50,7 +50,9 @@
    │  --fg-disabled     disabled 文字（neutral-6）                       │
    │                                                                     │
    │  文字色一律使用 neutral alpha，透明度疊加在任何背景皆可維持對比      │
-   │  弱化 icon hover 後變 fg-secondary（neutral-8）                     │
+   │  弱化 icon hover 後變 fg-secondary（neutral-8）— 往前一階不跳階      │
+   │    rule owner 對偶:patterns/element-anatomy/inline-action.spec.md   │
+   │    「Icon 色彩」段;機械強制 check_pattern_invariants.sh C.5         │
    └─────────────────────────────────────────────────────────────────────┘
 
    ┌─ 互動狀態（引用色盤 step）─────────────────────────────────────────────┐
@@ -67,7 +69,13 @@
    │  --border-hover  input/checkbox/radio hover 邊框（neutral-6）       │
    │  --divider       分隔線（neutral-4，比 border 更淡）                │
    │  --ring          focus 輪廓（= primary）                           │
-   │  選中狀態的邊框或文字 → 直接使用 var(--primary-hover)              │
+   │  選中狀態的邊框或文字 → 直接使用 var(--primary)                    │
+   │  (2026-07-06 拍板:持續選中站 base、hover 階專屬瞬時態——            │
+   │   Ant / Atlassian / Material 三家「瞬時弱、持續強」實錘)            │
+   │  選中之上的互動 = 同色相升降階(完整三階,2026-07-07 補):          │
+   │    hover → var(--primary-hover)、按壓 → var(--primary-active)      │
+   │  (Button pressed hover / Ant active 頁 hover 同派;實心填色家族     │
+   │   同理:bg-primary → hover bg-primary-hover,Checkbox/Switch/DateGrid)│
    └─────────────────────────────────────────────────────────────────────┘
 
    ┌─ Static Subtle ─────────────────────────────────────────────────────┐
@@ -82,8 +90,9 @@
    │                                                                     │
    │  Selected state family（toggle on / 持續選中 element 的互動）       │
    │    --neutral-selected         rest 持續選中   = neutral-2            │
-   │    --neutral-selected-hover   hover（變淺）   = neutral-1            │
-   │    --neutral-selected-active  :active 深一階  = neutral-3            │
+   │    --neutral-selected-hover   切換鈕hover(變淺) = neutral-1          │
+   │    --neutral-selected-focus   鍵盤焦點 深一階  = neutral-3           │
+   │    --neutral-selected-active  按壓專屬 深一階  = neutral-3           │
    │                                                                     │
    │  --bg-disabled                互動元件 disabled 背景  = neutral-2    │
    │                                                                     │
@@ -122,10 +131,10 @@
    │   (subtle)   bg-{primary|info|error|success|warning}-subtle         │
    │   (text)     text-{info|error|success|warning}-text                  │
    │                  ↑ 用於 subtle bg 上的文字（資訊呈現）                │
-   │  Special     text-warning-foreground（yellow solid 例外）            │
+   │  On-fill     --on-emphasis（白）/ --on-emphasis-dark（深,亮底用）   │
    │  Neutral     bg-neutral-hover / bg-neutral-active / bg-disabled     │
    │              bg-neutral-selected / bg-neutral-selected-hover /       │
-   │              bg-neutral-selected-active                              │
+   │              bg-neutral-selected-focus / bg-neutral-selected-active  │
    │              bg-muted / bg-secondary                                 │
    │  Border      border-border / border-border-hover / border-divider   │
    │  Focus       ring-ring                                               │
@@ -137,7 +146,7 @@
    │     （不橋接成 utility class——只有 Tag/Avatar dismiss 一個 consumer）│
    └─────────────────────────────────────────────────────────────────────┘
 
-   選中邊框/文字 → border-[var(--primary-hover)] / text-[var(--primary-hover)]
+   選中邊框/文字 → border-primary / text-primary(2026-07-06 持續選中改 base,hover 階專屬瞬時態)
    ═══════════════════════════════════════════════════════════════════════ */
 
 
@@ -171,24 +180,33 @@
 
   /* 文字 / Icon */
   --foreground:           var(--color-neutral-9);
-  --warning-foreground:   var(--black-a85);
   --fg-secondary:         var(--color-neutral-8);
   --fg-muted:             var(--color-neutral-7);
   --fg-disabled:          var(--color-neutral-6);
 
-  /* On-emphasis:飽和色底的對比文字(white on filled surface)
-     消費者:Avatar color variants(blue/red/green/... fill + on-emphasis text)
-           Steps filled indicator(completed/active 的 icon 色)
-     為什麼獨立 token:foreground 是 neutral 文字色,warning-foreground 是 warning
-     子場景 amber 底的對比,都不是「任何飽和色底的通用對比」。Polaris 叫 text-onEmphasis,
-     Material 叫 on-primary/on-secondary family。我們用 on-emphasis 保持通用。
-     Dark mode 不反轉(白字在飽和色底永遠白)
-     2026-05-20 fix:raw oklch → primitive --color-white */
+  /* ── On-emphasis 配對:飽和 / 填色底上的對比文字 ──────────────────────────────
+     世界級對照:Material on-primary/on-secondary family、Radix --accent-contrast、
+     Polaris text-{x}-on-bg-fill —— 「填色底的文字色」依底色明暗成對提供,不是單一固定白。
+     本 DS 採「2-bucket」(白 + 深)而非 per-hue(12 個 token = 過度設計;深底白字已是最大對比,
+     per-hue 救不了暗色邊緣):
+       --on-emphasis       = 白字,用於「夠深」的飽和色底(WCAG ≥3:1 大粗字達標的 hue)
+       --on-emphasis-dark  = 深字(= black-a85),用於「太亮」的色底(白字連 3:1 都不及格:yellow/amber/orange/lime)
+     命名:配對白↔深;不用「inverse」(已保留給 --inverse-* 反相 surface 命名空間),不用 mode 字眼
+     (token 名一律不編碼 light/dark mode,mode 靠 redefinition)。
+     合規門檻(2026-06-04 user 拍板「以最低為原則」)= WCAG large/bold 3:1(solid chip/avatar 視大粗字)。
+     消費者:Avatar / Tag solid color variants、Steps filled indicator、Calendar today、Tooltip、
+     warning solid surface(黃底深字)等 —— 「亮底深字」一律消費 --on-emphasis-dark(不再有 warning 專屬 token)。
+     兩者都「Dark mode 不反轉」(白 / 深字在飽和底永遠同極性,底色明暗跨 mode 不變)。
+     ⚠️ green 例外:green-6 白字實測 2.47(連 3:1 都不過),但 user 拍板維持白字(沿用世界級慣見的
+        「綠底白字」按鈕觀感)→ documented exception(知情違反),待日後評估是否調 green-6。
+     2026-06-04 改名:原 --warning-foreground 被 categorical yellow/amber 借用 = 誤名(它跟 warning 無關,
+        本質是「亮底深字」通用概念)→ 改名 --on-emphasis-dark + 移除 warning 專屬 alias(user「以乾淨為主」)。 */
   --on-emphasis:          var(--color-white);
+  --on-emphasis-dark:     var(--black-a85);
 
   /* Brand / Action — 品牌主操作色
      --primary-text 為 SOP 規定的 5 件套之一，目前無消費者
-     （Button 直接用 text-white, Tag 用 primitive --color-blue-7） */
+     （Button 直接用 text-on-emphasis, Tag 用 primitive --color-blue-7） */
   --primary:              var(--color-blue-6);
   --primary-hover:        var(--color-blue-5);
   --primary-active:       var(--color-blue-7);
@@ -197,7 +215,11 @@
 
   /* Status: Info — 資訊狀態色
      目前指向 blue（與 primary 同源），但語義獨立——如未來 brand 改色，
-     primary 跟著改，info 仍維持「資訊=藍」的通用慣例 */
+     primary 跟著改，info 仍維持「資訊=藍」的通用慣例。
+     ⚠️ 選取控件(Checkbox/Switch/Radio/Calendar selected)的 checked 藍 = --primary 非 --info:
+     選取是「互動操作的 selected state」隨 brand 走(Material 3 CheckboxTokens
+     SelectedContainerColor=Primary / shadcn bg-primary / Ant colorPrimary 同款);
+     --info 只給資訊呈報(Alert/Badge/Toast info)。2026-06-12 codify per user 提問 */
   --info:                 var(--color-blue-6);
   --info-hover:           var(--color-blue-5);
   --info-active:          var(--color-blue-7);
@@ -319,6 +341,7 @@
   --neutral-hover:        var(--color-neutral-1);
   --neutral-active:       var(--color-neutral-2);
   --bg-disabled:          var(--color-neutral-2);
+  --bg-readonly:          var(--color-neutral-2);  /* readonly 鎖定欄位 chrome — 同值但獨立 owner(≠ disabled:可聚焦/選取/提交,僅不可改值);詳 color.spec.md Static Subtle 邊界 */
 
   /* Neutral Interactive — Selected state family
      ─────────────────────────────────────────────────────────────
@@ -335,10 +358,17 @@
        --neutral-active  = :active 瞬間 click 回饋（transient）
        --neutral-selected = 持續 toggle on / 長時間選中（persistent）
 
-     典型消費者：Button text variant pressed、DropdownMenu 單選項目、
-     SelectMenu 單選項目、Tab active、menu item selected。 */
+     選中之上的疊加(2026-08-11 user 拍板;SSOT = item-anatomy.spec.md「選中 × 互動疊加」格):
+       -hover  = 可取消切換鈕專屬「hover 預告釋放」→ 變淺(Fluent ToggleButton 同構;Carbon/Atlassian
+                 同名 token 是變深,本 DS 反向是切換鈕語意的有意設計 — 列元件禁用本 token)
+       -focus  = 鍵盤焦點/反白停在「選中列」→ 深一階(游標可見性 WCAG 2.4.7;滑鼠 hover 一律釘住不變)
+       -active = 只有「按住」的瞬間(按壓專屬;禁借給 hover/反白 — 2026-07-05 D4 借用已於 2026-08-11 糾正)
+
+     典型消費者：Button toggle pressed(-hover 變淺/-active 按壓)、DropdownMenu/SelectMenu 單選項目、
+     SidebarMenuButton/TreeItem/TimePicker/MenuItem 選中列(皆 -focus)。 */
   --neutral-selected:         var(--color-neutral-2);
   --neutral-selected-hover:   var(--color-neutral-1);
+  --neutral-selected-focus:   var(--color-neutral-3);
   --neutral-selected-active:  var(--color-neutral-3);
 
   /* Static Subtle — 靜態弱化背景(2026-05-20 v3 註解濃縮原則,SSOT 詳 color.spec.md「Static Subtle Background」段)*/
@@ -362,6 +392,17 @@
   --chart-3:              var(--color-green-6);
   --chart-4:              var(--color-yellow-7);
   --chart-5:              var(--color-deep-orange-6);
+
+  /* Highlight — 文字反白與頁內搜尋配對(2026-08-28 拍板;SSOT 詳 color.spec.md「Highlight」段)
+     反白必半透明(VS Code theme-color「must not be opaque」鐵律)、只動底色不動字色(對比 ≥4.5:1 驗收)。
+     搜尋雙檔制 = VS Code findMatchBackground(current)/ findMatchHighlightBackground(others)普世慣例;
+     amber-3 / -5 對階 Radix step 3(UI element bg)/ step 5(Active/Selected bg);行內文字保持原色
+     → 底色停亮階,故 -current 不取 -active 映射的第 7 階(--amber-active 已佔且 -active = 按壓語意)。
+     Dark:-selection / -match 由 primitive 公式自動反轉;-current 需降一階覆寫 amber-4
+     (dark amber-5 白字對比 3.03 < 4.5,詳 dark 區塊註解)。 */
+  --text-selection:       color-mix(in oklch, var(--color-blue-5) 30%, transparent);
+  --search-match:         var(--color-amber-3);
+  --search-match-current: var(--color-amber-5);
 }
 
 
@@ -421,6 +462,12 @@
   --indigo-hover:         var(--color-indigo-7);
   --indigo-active:        var(--color-indigo-5);
 
+  /* Highlight — dark 唯一覆寫:-current 降一階 amber-4。
+     數學驗收(oklch→sRGB→WCAG):dark amber-5 配白字對比 3.03 過不了 4.5 鐵門檻;
+     amber-4 = 5.89 ✓ 且與 amber-3(全部配對)區辨 1.86 優於 light 的 1.31。
+     --text-selection / --search-match 由 primitive 公式自動反轉,不需覆寫。 */
+  --search-match-current: var(--color-amber-4);
+
   /* Inverse — dark mode 反轉（深字 + 黑色透明 overlay）
      overlay 值為 light mode neutral-* 的鏡射（black @ 2% / 4%）
      2026-05-20 fix:raw oklch → primitive --black-a85(既有 alpha token,L46)*/
@@ -450,6 +497,7 @@
   /* Foreground */
   --color-foreground:            var(--foreground);
   --color-on-emphasis:           var(--on-emphasis);
+  --color-on-emphasis-dark:      var(--on-emphasis-dark);
 
   /* Primary */
   --color-primary:               var(--primary);
@@ -463,9 +511,13 @@
   --color-error:                 var(--error);
   --color-success:               var(--success);
   --color-warning:               var(--warning);
-  --color-warning-foreground:    var(--warning-foreground);
   --color-notification:          var(--notification);
 
+  /* Highlight(反白 / 搜尋配對) */
+  --color-text-selection:        var(--text-selection);
+  --color-search-match:          var(--search-match);
+  --color-search-match-current:  var(--search-match-current);
+
   /* Presence Status(Avatar badge) */
   --color-status-online:         var(--status-online);
   --color-status-busy:           var(--status-busy);
@@ -506,10 +558,12 @@
   --color-neutral-hover:             var(--neutral-hover);
   --color-neutral-active:            var(--neutral-active);
   --color-disabled:                  var(--bg-disabled);
+  --color-readonly:                  var(--bg-readonly);
 
   /* Neutral Interaction — Selected state family */
   --color-neutral-selected:          var(--neutral-selected);
   --color-neutral-selected-hover:    var(--neutral-selected-hover);
+  --color-neutral-selected-focus:    var(--neutral-selected-focus);
   --color-neutral-selected-active:   var(--neutral-selected-active);
 
   /* Surface Utility */

package/src/tokens/density/density.spec.md

@@ -6,7 +6,7 @@ Density 由**兩個獨立維度**構成,並配合一個 convenience attribute
 
 | 維度 | 管的是 | attribute | 範例 |
 |------|--------|-----------|------|
-| **UI Size** | 元件**高度 / 內距**(Button / Input / SelectionItem / field-height / table-row) | `data-ui-size` | `md`(28px field)/ `lg`(32px field) |
+| **UI Size** | 元件**高度 / 內距**(Button / Input / SelectionItem / field-height / table-row) | `data-ui-size` | `md`(32px field-height-md)/ `lg`(36px field-height-md) |
 | **Layout Space** | 版面**間距 / 外框 padding**(section gutter / dialog body padding / form gap) | `data-layout-space` | `md`(tight gap)/ `lg`(loose gap) |
 | **Density**(convenience)| 一鍵同時切兩者 | `data-density` | `md` / `lg` |
 
@@ -18,7 +18,7 @@ Density 由**兩個獨立維度**構成,並配合一個 convenience attribute
 
 **反例**(耦合):Material M3 / Polaris density 模式綁 control size + spacing — 無法「寬版面 + 標準 control」的場景。
 
-**我們走 decouple 流派**:解決 Dialog / overlay chrome 的痛點 — header 想要寬鬆呼吸(layout=lg),但不要被 button chrome 撐高(ui-size 跟 page 走 md)。
+**我們走 decouple 流派**:解決 Dialog / overlay chrome 的痛點 — header 想要版面間距寬鬆(layout-space=lg),但不要被 button chrome 撐高(ui-size 跟 page 走 md)。
 
 ## 預設同步(density convenience)
 
@@ -35,24 +35,23 @@ Density 由**兩個獨立維度**構成,並配合一個 convenience attribute
 
 ## 解耦用法(canonical 情境)
 
-當需要「layout 寬鬆 + control 標準」時,**顯式設兩個 attribute**:
+當需要「版面間距寬鬆(layout-space)+ 控件高度標準(ui-size)」時,**顯式設兩個 attribute**:
 
-### Canonical 情境 1 — 歷史備忘(Dialog 已撤回)
+### Canonical 情境 1 — Overlay 的 layout-space tier(2026-06-15 重訂)
 
-**歷史:** Dialog 先前設 `data-layout-space="lg"` 給 header/body 寬鬆呼吸,但跟 `--chrome-header-height` canonical(md=48)衝突(強設 lg 會變 56)。**已於 2026-04-22 v5 撤回**,Dialog 全盤繼承 page density(跟 Sheet 對齊)。
+**核心原則**:浮層(Portal overlay)**預設全繼承 page density**;只鎖「**有設計理由 + 該元件真的消費到**」的那個 dial,**禁用 `data-density` master switch 鎖浮層**(它連 ui-size 一起鎖 → 內部控件 / 選單 item 對不上觸發點)。**ui-size 永遠跟 page** —— 浮層只決定「版面間距 tier」(layout-space),控件大小交給 page。
 
-**本情境仍有效的使用時機**:若未來有新元件需要「page density = md 但此元件 chrome 要 lg padding」,可用 `data-layout-space="lg"`(不撐高 header 的 rationale 仍成立,前提是 chrome-header-height 對齊不是需求)。
+| 浮層 | 鎖 | 理由 |
+|------|----|------|
+| Dialog | **不鎖(繼承 page)** | layout-space 本 spec 第 10 行定義即管「dialog body padding」,鎖死 = override 自家 dial 自相矛盾;modal 寬鬆需求在 lg 階自然滿足(md 16 = Polaris 下限合格);button 不撐高由 ui-size 繼承解決。有同類 dial 的 SAP/Cloudscape modal 跟 dial、不鎖 |
+| Popover / Coachmark | `data-layout-space="md"` | 輕量浮層 → header py-tight 保持精簡;ui-size 跟 page 讓內部 field 控件對齊觸發點。Coachmark 建在 Popover 上自動繼承 |
+| Tooltip / DropdownMenu | 不鎖(繼承 page) | 不消費任何 layout-space token(Tooltip padding 寫死 px-3 py-2;Dropdown 是 RowSize + py-2);鎖 ui-size 會把選單 item(field-height-{size})釘在 md-scale → 對不上 lg 觸發點 |
+| Sheet | 不鎖(繼承 page) | 側板,螢幕變小時常駐側板會 responsive 變 Sheet;若 Sheet 鎖 tier 而側板繼承 page → 切換瞬間跳 mode,不一致 |
+| FileViewer | 不鎖(繼承 page) | 全螢幕 chrome 殼。原 `lockDensity="lg"` 只鎖在兩個 ChromeHeader、沒鎖 body → header(px-loose@lg=24)與 body(px-loose@page=16)左緣不對齊;移除 → 全 surface 同密度 |
 
-```tsx
-// 假設未來某元件需要 lg 呼吸 + page-default ui-size
-<SomeContent data-layout-space="lg">
-  <Button size="sm" />  {/* 仍是 28px md */}
-</SomeContent>
-```
+**Tier alignment**:每個 overlay 宣告自己的 layout-space tier → header 高度隨之(Dialog lg → title 24 + py-tight 16×2 = 56;Popover md → 45)。「對齊 `--chrome-header-height`」是**同 tier 內**成立(Popover 45 ≠ Dialog 56 ≠ chrome 48 本就允許,各宣告各 tier),非跨 page 強制。詳 `patterns/header-canonical/header-canonical.spec.md` A 家族。
 
-**實際 v5 canonical(Dialog / Sheet / Popover)**:
-- Dialog / Sheet:繼承 page density(無 override)
-- Popover / DropdownMenu / Tooltip / Sidebar:`data-density="md"` 鎖定(Portal 逃逸 + compact 語意)
+**為何不鎖 ui-size**:field-height token 隨 density 變(md 28/32/36 → lg 32/36/40);鎖 ui-size=md 會把浮層內控件 / 選單 item 釘死 md-scale,lg page 上對不上 lg 觸發點。decouple = 只鎖版面間距、控件跟 page。對標 Carbon spacing scale 獨立於 control size / GitHub Primer 8px scale 獨立。
 
 ### Canonical 情境 2 — 單獨切 ui-size
 
@@ -94,34 +93,38 @@ document.documentElement.setAttribute('data-layout-space', 'md')
    - 是 → 用 `data-density="X"`(convenience)
    - 否(想解耦) → 明示 `data-layout-space="X"` + / 或 `data-ui-size="Y"`
 
-3. **Portal 逃逸 subtree?**(Dialog / Popover / Sheet / DropdownMenu)
-   - Portal 到 body 的元件**不繼承 trigger 的 density** → 必自設(對齊 Meta-Pattern M3)
+3. **Portal 逃逸 subtree?**(Dialog / Popover / Sheet / DropdownMenu / Tooltip)
+   - density 設在 `html` root 時,CSS cascade 會傳到 portal 出去的內容(portal 掛 body,仍在 html 底下)→ **浮層繼承 page density 正常,不需自設**。
+   - 只有 density 設在「中層 div」時 portal 才逃逸該 subtree(M3 邊界)。
+   - **鎖浮層 density/layout-space = 刻意覆蓋成某 tier,需設計理由(見情境 1 表)**,非 Portal 必要;且只鎖該元件真正消費的 dial。
 
 ## 消費者清單
 
 | 元件 | attribute 設置 | 用法理由 |
 |------|---------------|---------|
-| Dialog | 無(繼承 page,v5 校準)| 跟 Sheet 對齊;header 高度 = `--chrome-header-height` 自動對齊(md=48 / lg=56);原 `data-layout-space="lg"` 已於 2026-04-22 撤回(衝突 chrome-header canonical) |
-| Sheet | 無(繼承 page) | Sheet 繼承 page density,不 lock |
-| Popover | `data-density="md"` | Portal 逃逸,且 popover 語意「compact」兩維度同鎖 md |
-| DropdownMenu | `data-density="md"` | 同 Popover |
-| Tooltip | `data-density="md"` | 同 Popover |
-| Sidebar | `data-density="md"` | Sidebar 本身 compact(不管 page 是否 lg)|
+| Dialog | **無(繼承 page,2026-06-16)** | layout-space 定義即管 dialog body padding → 鎖 = override 自家 dial 自相矛盾;header 隨 page md=48 / lg=56;有同類 dial 的 SAP/Cloudscape modal 跟 dial |
+| Sheet | 無(繼承 page) | 側板;responsive 會跟常駐側板互換,不能跳 mode |
+| Popover / Coachmark | `data-layout-space="md"`(2026-06-15) | 輕量;header py-tight 精簡;ui-size 繼承 page → 內部控件對齊觸發點。Coachmark 建在 Popover 上自動繼承 |
+| DropdownMenu | 無(繼承 page,2026-06-15) | 不消費 layout-space token;鎖 ui-size 會讓 menu item(field-height-{size})對不上觸發點 |
+| Tooltip | 無(繼承 page,2026-06-15) | 不消費任何 density/layout-space token,鎖 = inert |
+| FileViewer | 無(繼承 page,2026-06-15) | 全螢幕 chrome 殼;原 lockDensity 只鎖 header 造成左緣不對齊 → 移除 |
+| Sidebar | 無(繼承 page) | inline chrome(非 Portal 逃逸),跟隨 page density;size="md" 在 density="lg" 下自動變 36px row(見 sidebar.spec.md)|
+
+**邊界:page density=lg 下的 Portal overlay**——Tooltip / DropdownMenu 繼承 page → lg page 上隨 page 放大,選單 item 對齊 lg 觸發點。Popover / Coachmark 鎖 layout-space=md(header 精簡)但 ui-size 仍繼承 lg(內部控件放大)。Dialog 繼承 page(不鎖)→ md 16 / lg 24 padding 隨 page。皆透過 `[data-layout-space="md|lg"]` reset selector(layoutSpace.css L21/L31)在任意 page density 上正確解析。
 
 ## Anti-patterns(禁止)
 
 - ❌ 元件同時設 `data-density` + `data-ui-size`(重複,以後者為準但混亂)
-- ❌ Overlay Portal 元件不自設 density(Portal 到 body 不繼承 trigger — 見 Meta-Pattern M3)
+- ❌ **用 `data-density` master switch 鎖浮層**(連 ui-size 一起鎖 → 內部控件 / 選單 item 對不上觸發點)。只鎖該元件真正消費的 dial(見情境 1 表)
+- ❌ **把 density/layout-space lock 設在 header primitive(ChromeHeader / SurfaceHeader)而非 surface 根**——header 鎖、body 沒鎖 → 左緣不對齊(FileViewer 圖二 bug)。lock 一律放 surface 根容器
 - ❌ 為了追求表面一致性硬把 Dialog button 綁 lg ui-size(犧牲 header 高度 / strapline 彈性)
+- ❌ **鎖 Dialog 的 layout-space**(2026-06-16 定論)—— 本 spec 第 10 行定義 layout-space 就管「dialog body padding」,鎖 Dialog = 令自家 dial 對它點名要管的對象失效 = 自相矛盾;有同類 dial 的 SAP/Cloudscape 都讓 modal 跟 page dial。modal 寬鬆需求在 lg 階自然滿足(md 16 = Polaris 下限),不靠鎖。Popover/Coachmark 鎖 md 是另一回事(空間效率、消費 layout-space token、且為非阻斷錨定浮層)
 
 ## 被引用(auto-maintained,Dim 3 reciprocal audit)
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
-- `dialog.spec.md`
+- `coachmark.spec.md`
 - `dropdown-menu.spec.md`
-- `popover.spec.md`
-- `sheet.spec.md`
-- `sidebar.spec.md`
-- `tooltip.spec.md`
-- `uiSize.spec.md`
+- `file-viewer.spec.md`
+- `header-canonical.spec.md`

package/src/tokens/density/density.stories.tsx

@@ -0,0 +1,254 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { Button } from '@/design-system/components/Button/button'
+
+const meta: Meta = {
+  title: 'Design System/Tokens/Density',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: `
+\`data-density\` 統一控制 **UI Size**（元件高度 / 內距）與 **Layout Space**（版面間距）。
+
+- **md**（預設）：緊湊，適合資訊密集的桌面 UI
+- **lg**：寬鬆，適合觸控或更大點擊目標
+
+底層仍可用 \`data-ui-size\` / \`data-layout-space\` 單獨控制（逃生艙）。
+
+CSS 定義：\`uiSize/uiSize.css\` · \`layoutSpace/layoutSpace.css\`
+        `,
+      },
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj
+
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function ColHeader({ cols = '180px 1fr 80px 1fr 80px' }: { cols?: string }) {
+  return (
+    <div className="grid gap-x-4 pb-2 border-b border-border mb-1" style={{ gridTemplateColumns: cols }}>
+      <span />
+      <span className="text-caption text-fg-muted">md（預設）</span>
+      <span />
+      <span className="text-caption text-fg-muted">lg</span>
+      <span />
+    </div>
+  )
+}
+
+function TokenRow({
+  token, md, lg, desc, attr, isSolid = true, cols = '180px 1fr 80px 1fr 80px',
+}: {
+  token: string; md: string; lg: string; desc?: string
+  attr: string; isSolid?: boolean; cols?: string
+}) {
+  return (
+    <div className="grid items-center gap-x-4 border-b border-border py-3 last:border-0"
+      style={{ gridTemplateColumns: cols }}>
+      <div>
+        <code className="block text-caption font-medium text-fg-secondary">{token}</code>
+        {desc && <span className="text-caption text-fg-muted">{desc}</span>}
+      </div>
+      {/* md */}
+      <div {...{ [attr]: 'md' }}>
+        <div
+          className={`rounded-md ${isSolid ? 'bg-primary opacity-70' : 'bg-primary-subtle'}`}
+          style={isSolid
+            ? { height: `var(${token})`, width: '100%' }
+            : { height: '20px', width: `var(${token})` }
+          }
+        />
+      </div>
+      <span className="text-caption text-fg-muted text-right">{md}</span>
+      {/* lg */}
+      <div {...{ [attr]: 'lg' }}>
+        <div
+          className={`rounded-md ${isSolid ? 'bg-primary' : 'bg-primary-subtle'}`}
+          style={isSolid
+            ? { height: `var(${token})`, width: '100%' }
+            : { height: '20px', width: `var(${token})` }
+          }
+        />
+      </div>
+      <span className="text-caption text-fg-muted text-right">{lg}</span>
+    </div>
+  )
+}
+
+
+// ── 1. Overview ──────────────────────────────────────────────────────────────
+
+export const Overview: Story = {
+  name: '總覽',
+  parameters: {
+    docs: {
+      description: {
+        story: '`data-density` 同時切換 UI Size 與 Layout Space。左欄 md，右欄 lg。',
+      },
+    },
+  },
+  render: () => {
+    function Row({ label, token, isSolid }: { label: string; token: string; isSolid: boolean }) {
+      return (
+        <div className="grid items-center gap-x-4 border-b border-border py-2.5 last:border-0"
+          style={{ gridTemplateColumns: '200px 1fr 1fr' }}>
+          <code className="text-caption font-medium text-fg-secondary">{label}</code>
+          <div data-density="md">
+            <div
+              className={`rounded-md ${isSolid ? 'bg-primary opacity-70' : 'bg-primary-subtle'}`}
+              style={{ height: isSolid ? `var(${token})` : '16px', width: isSolid ? '100%' : `var(${token})` }}
+            />
+          </div>
+          <div data-density="lg">
+            <div
+              className={`rounded-md ${isSolid ? 'bg-primary' : 'bg-primary-subtle'}`}
+              style={{ height: isSolid ? `var(${token})` : '16px', width: isSolid ? '100%' : `var(${token})` }}
+            />
+          </div>
+        </div>
+      )
+    }
+    return (
+      <div className="max-w-2xl">
+        <div className="grid gap-x-4 pb-2 border-b border-border mb-1"
+          style={{ gridTemplateColumns: '200px 1fr 1fr' }}>
+          <span />
+          <span className="text-caption text-fg-muted">md（預設）</span>
+          <span className="text-caption text-fg-muted">lg</span>
+        </div>
+        <p className="py-2 text-caption font-medium text-fg-muted">Field Height</p>
+        <Row label="--field-height-lg" token="--field-height-lg" isSolid />
+        <Row label="--field-height-md" token="--field-height-md" isSolid />
+        <Row label="--field-height-sm" token="--field-height-sm" isSolid />
+        <p className="py-2 text-caption font-medium text-fg-muted">Table Row</p>
+        <Row label="--table-row-lg" token="--table-row-lg" isSolid />
+        <Row label="--table-row-md" token="--table-row-md" isSolid />
+        <Row label="--table-row-sm" token="--table-row-sm" isSolid />
+        <p className="py-2 text-caption font-medium text-fg-muted">Layout Space — 版面間距</p>
+        <Row label="--layout-space-loose" token="--layout-space-loose" isSolid={false} />
+        <Row label="--layout-space-tight" token="--layout-space-tight" isSolid={false} />
+      </div>
+    )
+  },
+}
+
+
+// ── 2. UI Size ───────────────────────────────────────────────────────────────
+
+export const UISize: Story = {
+  name: 'UI 尺寸',
+  parameters: {
+    docs: {
+      description: {
+        story: '元件高度 semantic token。Field height 用於 Button、Input 等互動元件。Table row 用於 DataTable。',
+      },
+    },
+  },
+  render: () => (
+    <div className="max-w-2xl space-y-6">
+      <div>
+        <p className="mb-2 text-caption font-medium text-fg-muted">Field Height（Button、Input、SelectionItem）</p>
+        <ColHeader />
+        <TokenRow attr="data-ui-size" token="--field-height-xs" md="24px" lg="24px" />
+        <TokenRow attr="data-ui-size" token="--field-height-sm" md="28px" lg="32px" />
+        <TokenRow attr="data-ui-size" token="--field-height-md" md="32px" lg="36px" />
+        <TokenRow attr="data-ui-size" token="--field-height-lg" md="36px" lg="40px" />
+      </div>
+      <div>
+        <p className="mb-2 text-caption font-medium text-fg-muted">Table Row（DataTable）</p>
+        <ColHeader />
+        <TokenRow attr="data-ui-size" token="--table-row-sm" md="32px" lg="40px" />
+        <TokenRow attr="data-ui-size" token="--table-row-md" md="40px" lg="48px" />
+        <TokenRow attr="data-ui-size" token="--table-row-lg" md="48px" lg="56px" />
+      </div>
+    </div>
+  ),
+}
+
+
+// ── 3. Layout Space ──────────────────────────────────────────────────────────
+
+const LS_COLS = '220px 1fr 80px 1fr 80px'
+
+export const LayoutSpace: Story = {
+  name: '版面間距',
+  parameters: {
+    docs: {
+      description: {
+        story: '版面間距 token。用於頁面側邊、header 內距、內容到 action buttons 的結論留白。',
+      },
+    },
+  },
+  render: () => (
+    <div className="max-w-2xl">
+      <ColHeader cols={LS_COLS} />
+      <TokenRow attr="data-layout-space" cols={LS_COLS} token="--layout-space-loose"  md="16px" lg="24px" desc="頁面側邊、內容區外層" isSolid={false} />
+      <TokenRow attr="data-layout-space" cols={LS_COLS} token="--layout-space-tight"  md="12px" lg="16px" desc="Header 上下內距" isSolid={false} />
+      {/* 2026-07-14 audit Dim 68:bottom ≠ 通用「頁面底部留白」— layoutSpace.spec.md 定義為
+          「結論留白:內容到 action buttons(commitment 前視覺暫停)」;無 action 的容器底依
+          bounded / unbounded / element 用 loose / 0 / tight(spec 規則 4)*/}
+      <TokenRow attr="data-layout-space" cols={LS_COLS} token="--layout-space-bottom" md="48px" lg="48px" desc="內容 → action buttons 結論留白" isSolid={false} />
+    </div>
+  ),
+}
+
+
+// ── 4. Page Layout ───────────────────────────────────────────────────────────
+
+export const PageLayout: Story = {
+  name: '頁面版型',
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        story: '兩種密度下的版面呼吸感對比。左側 md，右側 lg。',
+      },
+    },
+  },
+  render: () => {
+    const Page = ({ mode }: { mode: 'md' | 'lg' }) => (
+      <div data-density={mode} className="flex-1 border-r border-border last:border-0">
+        <div
+          className="border-b border-border bg-surface flex items-center"
+          style={{ paddingLeft: 'var(--layout-space-loose)', paddingRight: 'var(--layout-space-loose)', paddingTop: 'var(--layout-space-tight)', paddingBottom: 'var(--layout-space-tight)' }}
+        >
+          <span className="text-caption font-medium text-fg-secondary">
+            {mode.toUpperCase()} density
+          </span>
+        </div>
+        <div style={{ padding: `var(--layout-space-tight) var(--layout-space-loose)` }}>
+          <div className="space-y-2">
+            {[1, 2, 3].map(i => (
+              <div key={i} className="h-8 rounded-md bg-neutral-hover" />
+            ))}
+          </div>
+        </div>
+        {/* 2026-07-14 audit Dim 68:bottom 是「內容 → action buttons」結論留白(layoutSpace.spec.md
+            規則 4 line 1)— 原 demo 把它畫成無 action 的通用頁尾 band = 教錯用法。補 action row
+            讓 48px 留白真的落在 content 與 commitment 之間。 */}
+        <div style={{ height: 'var(--layout-space-bottom)', borderTop: '1px dashed var(--border)' }}
+          className="flex items-center justify-center">
+          <span className="text-caption text-fg-muted">bottom 48 — 內容 → action 結論留白</span>
+        </div>
+        <div
+          className="flex justify-end"
+          style={{ padding: `0 var(--layout-space-loose) var(--layout-space-tight)` }}
+        >
+          <Button variant="primary">儲存變更</Button>
+        </div>
+      </div>
+    )
+
+    return (
+      <div className="flex min-h-64">
+        <Page mode="md" />
+        <Page mode="lg" />
+      </div>
+    )
+  },
+}

package/src/tokens/elevation/elevation.spec.md

@@ -1,3 +1,5 @@
+<!-- @benchmark-cited: D5 retrofit backfill 2026-06-10 — body world-class claims marked per-claim inline;對齊 token spec 家族 7/9 既有 marker 慣例(deep-audit A.0 抓漏)。 -->
+
 # Elevation 設計原則
 
 Elevation 定義陰影層級，區分內容層（Card）和浮層（Modal/Popover）的視覺深度。
@@ -11,18 +13,16 @@ Elevation 定義陰影層級，區分內容層（Card）和浮層（Modal/Popove
 <div style={{ boxShadow: 'var(--elevation-200)' }} />
 ```
 
-
 ## 層級
 
 | Token | 用途 | 對應元件 |
 |-------|------|----------|
-| `--elevation-100` | 頁面內容層，靜止 | Card |
-| `--elevation-100-hover` | 頁面內容層，hover / 拖拽 | 可拖拽 card |
+| `--elevation-100` | 頁面內容層，靜止 | Card 類內容容器(DS 尚無 Card 元件;現行唯一 DS consumer = Slider thumb hover 陰影,per `slider.spec.md` 互動 canonical) |
+| `--elevation-100-hover` | 頁面內容層，hover / 拖拽 lift | —(目前無 DS 內建 consumer;預留給 consumer 的可拖拽 / hover-lift card,如 board card drag) |
 | `--elevation-200` | 浮層，靜止 | Modal、popover、dropdown、overlay drawer |
-| `--elevation-200-hover` | 浮層，hover | — |
-
-elevation-100 < elevation-200，數字越大浮起越高。
+| `--elevation-200-hover` | 浮層，hover | —(同上,預留) |
 
+elevation-100 < elevation-200，數字越大浮起越高。`*-hover` 兩枚為靜止 token 的「抬升一階」變體:元素被 hover / 拖起時切換,幾何(offset / blur)不變、只加深陰影 alpha(`tokens/color/primitives.css` 定義,light / dark 各一組)。
 
 ## 與 Surface 的配對規則
 
@@ -40,15 +40,16 @@ elevation-100 < elevation-200，數字越大浮起越高。
 <div className="bg-surface rounded-lg" style={{ boxShadow: 'var(--elevation-200)' }} />
 ```
 
-
 ## 浮層間距（sideOffset）
 
-所有從觸發元件彈出的浮層（Tooltip、Popover、SelectMenu、Dropdown、HoverCard、Coachmark）與觸發元件的間距統一 **8px**（`sideOffset={8}`）。
+所有從觸發元件彈出的浮層（Tooltip、Popover、SelectMenu、DropdownMenu、HoverCard、Coachmark）與觸發元件的間距統一 **8px**（`sideOffset={8}`）。
 
 不因浮層類型或位置而異——一致的間距讓使用者建立穩定的空間預期。
 
 **SSOT** → `tokens/elevation/overlay-geometry.ts` exports `OVERLAY_SIDE_OFFSET = 8` / `OVERLAY_COLLISION_PADDING = 8`。所有 primitive `default` 必 import 該 const(M17 SSOT 必可傳播);Radix `sideOffset` 接 number 不接 CSS var,因此用 JS const 共用,改值只動一處全部聯動。
 
+**視窗邊緣碰撞(邊界案例)**:浮層貼近 viewport 邊不足以容納時,Radix `avoidCollisions`(預設開)自動翻轉 / 平移,並與邊緣保持 `collisionPadding` = `OVERLAY_COLLISION_PADDING`(8px;Tooltip / Popover / DropdownMenu 皆接此 const)。例外:HoverCard 用 12(Radix / browser rounding 讓 visual padding 少 1-2px 的補償,見 `hover-card.tsx` 註解)。
+
 | 浮層類型 | sideOffset | 說明 |
 |---------|-----------|------|
 | Tooltip | 8px | TooltipContent 預設值 |
@@ -72,10 +73,6 @@ elevation-100 < elevation-200，數字越大浮起越高。
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
-- `slider.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
 - `motion.spec.md`
+- `slider.spec.md`
+- `token-system.spec.md`