@qijenchen/design-system 0.1.0-beta.145 → 0.1.0-beta.147

package/src/patterns/overlay-surface/overlay-chrome-sizing.spec.md

@@ -0,0 +1,180 @@
+---
+internal: true
+# 同 overlay-surface.spec.md:DS-internal pattern 的分節,不是另一個 pattern;sub-spec 不另立 family(Dim 16 豁免)
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list.(2026-09-27 自 overlay-surface.spec.md 抽出,標記沿用) -->
+
+# Overlay chrome 分級尺寸設計原則(overlay-surface 的分節;獨立 SSOT)
+
+> **本 spec 是 overlay chrome 分級尺寸的獨立 SSOT**(2026-09-27 從 `overlay-surface.spec.md` 整段抽出「Overlay title typography canonical」「為什麼 SurfaceHeader 是 padding-based」「Size canonical」「Chrome dismiss size canonical」四節,避免單一 spec 過長(595 行 > 500 硬上限,待辦總帳 N19);內容零改動,只加本檔頭、檔尾指標,與 N23 的四處來源標註(見「為什麼用負 margin」與「震盪歷史備忘」))。SurfaceHeader / SurfaceBody / SurfaceFooter 結構、List-as-region、footer 對齊、Viewport-aware scroll chain、A11y 仍住 `./overlay-surface.spec.md`;程式碼對應 `overlay-surface.tsx`(`CHROME_UNBOUNDED_SLOT` / `COMPACT_HEADER_SLOT`)與 `../../components/Button/button.tsx`(`data-unbounded`)。
+>
+> **Layout Family**:同 `overlay-surface.spec.md`(非 Family 1–4 — structural container primitive 的分區尺寸);本檔不另立 family。
+
+## Overlay title typography canonical(modal vs non-modal 分級,2026-04-22)
+
+Overlay family 的 header title typography 依「modal vs non-modal」分級,**跟 chrome padding / dismiss behavior 同 rationale(modal 重量級 vs non-modal 輕量)**:
+
+| 家族 | Title typography | 套用元件 |
+|------|------------------|---------|
+| **Modal**(阻斷互動)| `text-body-lg font-medium truncate`(**16px**)| `Dialog` / `Sheet` |
+| **Non-modal**(可忽略)| `text-body font-medium truncate`(**14px**)| `Popover` / `Coachmark` |
+
+**Rationale**:
+- **Modal**:title 是決策 anchor,user 必須 process → 需視覺重量(16px + 重字重)
+- **Non-modal**:title 是輔助標籤,user 可忽略 → 輕量字級(14px)不搶 body content
+
+**世界級對照**(7 家 DS 同 split): <!-- @benchmark-unverified -->
+| DS | Modal title | Non-modal popover title |
+|----|-------------|------------------------|
+| Material M3 | Headline 24 / body 16 | Smaller 14-16 |
+| Polaris | Modal 大 | Popover 較小 |
+| Atlassian | Modal 大 | InlineDialog 小 |
+| Notion | 16+ | 14 |
+| Linear | 16 | 14 |
+| Figma | 16 | 13-14 |
+| GitHub Primer | 16 | 14 |
+
+**跟「density 鎖 md」同源**:Popover / Coachmark 把「輕量」貫穿 chrome:density 鎖 md + chrome button 透過 v5 unbounded trick 縮 layout + **title 小一級**。三件一起構成「輕量浮層」視覺語言,跟 Modal heavy 形成明確分化。
+
+**禁止**:consumer 自刻 `<h2 className="text-body-lg">` 繞 `PopoverTitle` — 若需要大 title 代表該用 Dialog 而非 Popover(選錯元件)。
+
+**SSOT**:
+- `components/Popover/popover.spec.md`「Title typography canonical(non-modal 特化)」(Popover 專用細節)
+- `components/Dialog/dialog.spec.md`「Title」(Modal 專用細節)
+
+---
+
+## 為什麼 SurfaceHeader 是 padding-based(而非 fixed-h)(2026-04-22 設計原則)
+
+**SurfaceHeader 永遠 padding-based**(`py-tight`,不鎖固定高度)。Header 高度 = `max(title line-height, button slot)+ 2×py`,**slot 設計為 ≤ title line-height** 讓 title 主導 → header 高度 = title 決定(slot 縮位 / CSS var 參數化等實作細節詳下方「Chrome dismiss size canonical」)。SurfaceFooter **不**套 unbounded slot trick(僅 padding + `border-t`,慣例放 bounded action buttons)。**語義宣告**:
+
+**Padding-based 宣告**:「本 chrome **可以成長** — title 可換行、可附 subtitle / description」。適用 overlay family(Dialog / Sheet / Popover / Coachmark),這些都是 modal/semi-modal 情境,title 有可能長(例如「確認要永久刪除 Marketing Q4 Campaign 這個專案嗎?」兩行 title),或有 subtitle(「這個操作無法復原」補充說明)。
+
+**Fixed-height 宣告**:「本 chrome **永遠單行固定結構** — 不會長高」。適用 chrome 類如 Sidebar / FileViewer toolbar / app top bar,這些 chrome 的內容是 logo / icons / 短固定 label,不會 grow。
+
+**兩者視覺上在單行 content 時都是 48/56,但是不同的設計宣告**:
+- 若 Dialog 用 fixed-h,未來塞兩行 title / subtitle 會被剪掉 → 違反 modal 作為「完整決策 context」的職責
+- 若 Sidebar 用 padding-based,chrome 可能在長 label 時變動 → 違反 sidebar chrome「剛性佈局」的職責
+
+**判斷 tree**:問「這個 chrome 的 title 有可能多行 / 有 subtitle / 有 description 嗎?」
+- **會** → padding-based(SurfaceHeader 或自刻 py-tight)
+- **不會** → fixed-h(`h-[var(--chrome-header-height)]`)
+
+**完整 canonical + 世界級對照**:`tokens/uiSize/uiSize.spec.md`「Chrome header 選型 canonical」節(含「2 種 pattern 對照」)
+
+---
+
+## Size canonical(per-overlay default size SSOT,2026-05-04)
+
+> **背景**:Popover / HoverCard 是「輕量浮層」(chrome 45 / slot 21 / title 小一級 / density 鎖 md);Dialog / Sheet 是「heavy commitment chrome」(chrome 48 / slot 24)。Per-surface body+footer button/field default size 跟「輕量 vs heavy」分化對應。
+>
+> **依據**:Linear / Notion / Airtable / Carbon / Material Menu / Atlassian Popup popover bodies 共識用 sm-density;Material AlertDialog / Carbon Modal / shadcn Dialog 共識用 md。world-class 雙派分明依「浮層密度」分。 <!-- @benchmark-unverified -->
+
+| Overlay | Header chrome | Body field controls | Body inline action(drag handle / trash / +CTA)| Footer action Buttons |
+|--|--|--|--|--|
+| **Popover** | unbounded sm → 21 slot(輕)| **sm**(輕量 dense info)| inline-action sm/md = **16+18** | **sm** |
+| **HoverCard** | (同 Popover)| **sm** | 同 | **sm** |
+| **Dialog** | unbounded sm → 24 slot | **md** | inline-action sm/md = 16+18 | **md** |
+| **Sheet** | (同 Dialog)| **md** | 同 | **md** |
+| **BulkActionBar** | N/A | N/A | N/A | **md**(default footer placement);未來 top-toolbar variant → sm |
+
+**核心 invariant**:overlay surface 內 **body field controls + footer Buttons 同一 size**(per-surface 一致)。違反 = 視覺重量割裂。
+
+**為什麼 Popover all-sm 而非 mix**:Popover 整體已是「輕量浮層」設計語言(chrome 短、title 小、density 鎖 md)。如果 body 用 md fields(32 高)+ footer sm Buttons(28 高),視覺重量割裂破壞「輕量」一致性。**all-sm 是內部一致性**(body 28 / footer 28 同高,延伸 chrome 輕一級的密度)。
+
+**為什麼 Dialog all-md 而非 mix**:Dialog 是 heavy commitment chrome,body 操作往往 form-heavy,md (32) 是 Field family default(`--field-height-md` SSOT),footer Buttons 同 md commit 視覺重量配得上 modal 結論性。
+
+**Drag handle / inline-action sizing**(對齊 `patterns/element-anatomy/inline-action.spec.md`):
+- Field sm/md 同 row → inline action **16 icon / 18 hover bg**
+- Field lg 同 row → inline action **20 icon / 22 hover bg**
+
+亦即:在 Popover(field=sm)或 Dialog(field=md)body 內,inline action 都同樣 16+18,差別只在 lg-density 場景。
+
+---
+
+## Chrome dismiss size canonical
+
+**設計 insight(本檔既有記載;2026-09-27 查無對話原文可引,依 M36(a) 標為來源不明,不得當 user 拍板引用)**:header 的 padding-based sizing 在 **unbounded button**(text variant / dismiss,無 bg/border)場景視覺 padding 過大;在 **bounded button** 則剛好。解法 = **保持 button native size 不變(命中區 / 視覺 render 都是 sm 原尺寸),但 layout 佔位縮到 title line-box(24,衍生自 --font-body-lg-size×1.5)** via 負 margin。
+
+**Canonical**:button native size **保留 sm**(命中區 / 視覺 render 不動);**unbounded 的靠 CSS 負 my 把 layout 佔位縮到 `--chrome-slot-h`** ≤ title line-height,讓 title 主導 chrome 高度。
+
+| Button 類型 | 判定(button.tsx L426-427)| Trick 套用 | Layout 佔位 | Dialog/Sheet header (slot 24)| Popover header (slot 21)|
+|--|--|--|--|--|--|
+| **Unbounded** | `variant === 'text'` OR `dismiss` → `data-unbounded="true"` | ✓ 套負 my | = `var(--chrome-slot-h)` | max(24, 24) + py-tight = **48** | max(21, 21) + py-tight = **45** |
+| **Bounded** | `primary` / `tertiary` / `outline` 等(有 bg/border) | ✗ 不套 | = native sm (28 md / 32 lg) | max(24, 28) + py-tight = **52**(自然長)| max(21, 28) + py-tight = **52**(自然長)|
+
+**為什麼差別**:Unbounded 沒視覺邊界 → native 28 是純 hit-target padding,縮 layout 不損視覺;Bounded 的 bg/border 就是內容,縮會切掉 → 必須讓 chrome 自然長高,**這是設計宣告「此 chrome 有重要 action,視覺重量該配得上」**。
+
+**實作**:
+
+```tsx
+// button.tsx ── 自動標記 data-unbounded
+const unboundedAttr = resolvedVariant === 'text' || dismiss ? { 'data-unbounded': 'true' } : {}
+
+// overlay-surface.tsx ── slot 透過 CSS var 參數化(2026-05-04 v3;2026-06-16 default 改衍生)
+const CHROME_UNBOUNDED_SLOT =
+  '[&_[data-unbounded]]:my-[calc((var(--chrome-slot-h,calc(var(--font-body-lg-size)*1.5))-var(--field-height-sm))/2)]'
+
+// SurfaceHeader default → slot 衍生自 title typography = calc(--font-body-lg-size × 1.5) = 24
+//   (2026-06-16:從寫死 field-height-xs 改衍生 → title 字級改了 slot 自動跟、不靠巧合;M17 SSOT;
+//    1.5 = typography.spec body 行高常數,非 token 故 inline,body 行高改須同步)
+// Popover-tier override → COMPACT_HEADER_SLOT(= calc(--font-body-size × 1.5) = 21,衍生自 text-body title)
+// 公式 = (slot - native) / 2 ──  Dialog md: (24-28)/2 = -2px / Popover md: (21-28)/2 = -3.5px
+```
+
+**覆蓋範圍**:
+- Dismiss X(`<Button dismiss />`)→ data-unbounded ✓
+- Text variant action(`<Button variant="text" />` 如 Share / Refresh / Settings)→ data-unbounded ✓
+- 所有無視覺邊界的 button,不限 dismiss
+
+**為什麼用負 margin 而非 fixed wrapper / size="xs"**:
+- `size="xs"` 會縮小 button 本身,**命中區也跟著縮到 24**,與 overlay chrome 的比例不協調(chrome 的 dismiss 是 `sm` = 28),也違反此處記載的意圖「touch 仍 sm」(**AI 推導、引不出 user 原話**;2026-09-27 依待辦總帳 N23 拿掉「user 意圖」的歸屬,引號內原字不動,來源說明見下一行)。**問題在比例,不在 a11y** —— 24 正好等於 `tokens/uiSize/uiSize.spec.md`「元件高度地板」(:169)訂的最小值,沒有低於任何我們採用的門檻;先前這裡寫的「違反 a11y 最小 24+ hit target」既與 :169 自相矛盾、也查無出處,2026-09-24 更正(同 `uiSize.spec.md:350`)
+  - ⚠️ **引號內為本檔既有記載,本輪查無對話出處,依 M36(a) 標為來源不明,不得再當成 user 拍板引用。** 2026-09-24 這一行一度被改寫成「按鈕本身仍 sm」並直接覆蓋掉原字 —— 兩句語意不同(一句講命中/觸控,一句講按鈕盒),而改寫沒有任何揭露。已還原為原字。要動引號內的字,只能拿得出對話原文才動
+- `min-h-chrome-header-height` fixed wrapper 會鎖死高度,**bounded button 失去自然長高能力**(違反上一條的意圖 —— 同樣是 AI 推導,引不出 user 原話)
+- 負 margin:button render / 命中區不變,僅影響 parent flex layout 計算 → 剛好是這裡要的「layout 24,視覺 / 命中 28」(AI 推導的設計目標,引不出 user 原話)
+
+**Consumer 使用方式**:
+
+```tsx
+// Dialog / Sheet / Popover / Coachmark(透過 SurfaceHeader)
+<Button data-dismiss iconOnly dismiss size="sm" startIcon={X} aria-label="關閉" />
+// `dismiss` prop → Button 自動標 `data-unbounded`(縮位 trick 判定詞);`data-dismiss` 用途不同,
+// 是 openAutoFocus 排除 marker(popover.tsx / dialog.tsx autofocus selector)。
+// SurfaceHeader 自動套負 my,無需 consumer 手動 y 調整
+
+// Header 若塞 bounded button(primary sm)→ Button 不自動標 `data-unbounded`,不套負 my → 自然長高
+<Button variant="primary" size="sm">套用</Button>
+
+// Notification banner(Notice / Alert / Toast):px-4 py-3 fixed,dismiss 用 xs 簡化(無 margin trick)
+<Button iconOnly dismiss size="xs" startIcon={X} aria-label="關閉通知" />
+```
+
+**Consumer 實際高度範例**:
+- Dialog header 只有 title + close X(sm,`dismiss` → 自動 `data-unbounded`)→ layout 佔位 24 → header = 48 md / 56 lg ✓
+- Dialog header 有 refresh/share(text variant)/ close(dismiss)sm → 全自動標 `data-unbounded` → 全部 layout 佔位 24 → header 仍 48/56
+- Dialog header 塞 primary sm(bounded,無 `data-unbounded`)→ primary layout 佔 28 → header = 52 md(自然長)
+- Popover header 同 pattern:48 md / 56 lg
+
+**Rationale**:Unbounded 無 bg/border → 2×py-tight 過大,縮 layout 佔位至 xs(24)讓 header = chrome-header-height = 48 自然閉合,跟 Sidebar / page header / top bar 對齊。Bounded 自帶視覺重量,自然長到 52+,跟 footer 一致。
+
+**共通 rationale**(全 overlay + banner 家族):corner close X 屬 **action group region**,必用 `<Button>` primitive(不自刻 `<button><X /></button>` 繞 DS token / a11y,不用 `ItemInlineActionButton`)。
+
+**本 session 震盪歷史備忘(M12 FP 記憶)**:
+- ❌ v1「chrome dismiss 全 xs(DS-wide 統一)」→ 錯:過度簡化 rationale
+- ❌ v2「三家族 modal sm / non-modal xs / banner xs」→ 錯:overlay 內部不必分化
+- ❌ v3「overlay 統一 sm + min-h chrome-header-height 強鎖 48/56」→ 錯:強鎖會讓 bounded button 被鎖死 slot
+- ❌ v4「padding-based + unbounded=xs / bounded=natural」→ 錯:xs 縮小 button 連命中區也縮到 24,與 chrome 的 28 失衡(違反上方「touch 仍 sm」那條 AI 推導的意圖、不是 user 原話 —— 2026-09-27 依 N23 註明;**不是 a11y 問題**,見上方「為什麼用負 margin 而非 fixed wrapper / size="xs"」)
+- ✅ v5「padding-based + unbounded `data-unbounded` 套負 my(native size sm 不變)/ bounded natural」→ 對:button native size 與命中區保 sm,僅 layout 佔位縮回 24,48/56 chrome-header-height 自然達成
+
+**SSOT 關聯**:
+- `tokens/uiSize/uiSize.spec.md`「--chrome-header-height」+ `globals.css` 聲明(md=3rem / lg=3.5rem)
+- `tokens/layoutSpace/layoutSpace.spec.md` tight = 12 md / 16 lg
+- `patterns/element-anatomy/inline-action.spec.md`「Dismiss canonical — X close only」
+- `components/Button/button.spec.md`「Dismiss 視覺類」+ unbounded / bounded 判斷
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `overlay-surface.spec.md`

package/src/patterns/overlay-surface/overlay-surface.spec.md

@@ -227,7 +227,7 @@ item 沒有底色時只驗第 2 題(content 對齊 header title);沒有底色**
 > **不要 → `SurfaceFooter`**(內容左緣對齊**這個浮層的內容左邊界**,見下方「要對齊誰」)
 
 判準是「**誰負責左右 gutter**」—— 跟 `../element-anatomy/item-anatomy.spec.md`「Token: `--item-px`」是同一條線:
-列自己帶 gutter 所以容器給 0;按鈕自己沒有 gutter 所以容器給 `loose`。兩者相加就是 2026-09-17 那次 28px 的病。
+列自己帶 gutter 所以容器給 0;按鈕自己沒有 gutter 所以容器給 `loose`。兩者相加就是 2026-09-17 那次 28px 的病。同一條線也管 body:FileItem `surface="upload-manager"` 的上傳列可點時整列滑過、底色鋪到面板左右邊 → 列自帶 `loose`、面板 body 左右 0(2026-09-25 待辦總帳 B12,推翻 06-03 的「左右交給面板」;owner `../../components/FileItem/file-item.spec.md`「upload-manager 浮層面板 composition」)。
 
 | | `SurfaceFooter` | 列式 footer |
 |---|---|---|
@@ -310,166 +310,9 @@ DatePicker **不是**例外 —— 它的日曆格線有左緣,footer 的預設
 
 ---
 
-## Overlay title typography canonical(modal vs non-modal 分級,2026-04-22)
+## Overlay chrome 分級尺寸 → `overlay-chrome-sizing.spec.md`(2026-09-27 抽出,獨立 SSOT)
 
-Overlay family 的 header title typography 依「modal vs non-modal」分級,**跟 chrome padding / dismiss behavior 同 rationale(modal 重量級 vs non-modal 輕量)**:
-
-| 家族 | Title typography | 套用元件 |
-|------|------------------|---------|
-| **Modal**(阻斷互動)| `text-body-lg font-medium truncate`(**16px**)| `Dialog` / `Sheet` |
-| **Non-modal**(可忽略)| `text-body font-medium truncate`(**14px**)| `Popover` / `Coachmark` |
-
-**Rationale**:
-- **Modal**:title 是決策 anchor,user 必須 process → 需視覺重量(16px + 重字重)
-- **Non-modal**:title 是輔助標籤,user 可忽略 → 輕量字級(14px)不搶 body content
-
-**世界級對照**(7 家 DS 同 split): <!-- @benchmark-unverified -->
-| DS | Modal title | Non-modal popover title |
-|----|-------------|------------------------|
-| Material M3 | Headline 24 / body 16 | Smaller 14-16 |
-| Polaris | Modal 大 | Popover 較小 |
-| Atlassian | Modal 大 | InlineDialog 小 |
-| Notion | 16+ | 14 |
-| Linear | 16 | 14 |
-| Figma | 16 | 13-14 |
-| GitHub Primer | 16 | 14 |
-
-**跟「density 鎖 md」同源**:Popover / Coachmark 把「輕量」貫穿 chrome:density 鎖 md + chrome button 透過 v5 unbounded trick 縮 layout + **title 小一級**。三件一起構成「輕量浮層」視覺語言,跟 Modal heavy 形成明確分化。
-
-**禁止**:consumer 自刻 `<h2 className="text-body-lg">` 繞 `PopoverTitle` — 若需要大 title 代表該用 Dialog 而非 Popover(選錯元件)。
-
-**SSOT**:
-- `components/Popover/popover.spec.md`「Title typography canonical(non-modal 特化)」(Popover 專用細節)
-- `components/Dialog/dialog.spec.md`「Title」(Modal 專用細節)
-
----
-
-## 為什麼 SurfaceHeader 是 padding-based(而非 fixed-h)(2026-04-22 設計原則)
-
-**SurfaceHeader 永遠 padding-based**(`py-tight`,不鎖固定高度)。Header 高度 = `max(title line-height, button slot)+ 2×py`,**slot 設計為 ≤ title line-height** 讓 title 主導 → header 高度 = title 決定(slot 縮位 / CSS var 參數化等實作細節詳下方「Chrome dismiss size canonical」)。SurfaceFooter **不**套 unbounded slot trick(僅 padding + `border-t`,慣例放 bounded action buttons)。**語義宣告**:
-
-**Padding-based 宣告**:「本 chrome **可以成長** — title 可換行、可附 subtitle / description」。適用 overlay family(Dialog / Sheet / Popover / Coachmark),這些都是 modal/semi-modal 情境,title 有可能長(例如「確認要永久刪除 Marketing Q4 Campaign 這個專案嗎?」兩行 title),或有 subtitle(「這個操作無法復原」補充說明)。
-
-**Fixed-height 宣告**:「本 chrome **永遠單行固定結構** — 不會長高」。適用 chrome 類如 Sidebar / FileViewer toolbar / app top bar,這些 chrome 的內容是 logo / icons / 短固定 label,不會 grow。
-
-**兩者視覺上在單行 content 時都是 48/56,但是不同的設計宣告**:
-- 若 Dialog 用 fixed-h,未來塞兩行 title / subtitle 會被剪掉 → 違反 modal 作為「完整決策 context」的職責
-- 若 Sidebar 用 padding-based,chrome 可能在長 label 時變動 → 違反 sidebar chrome「剛性佈局」的職責
-
-**判斷 tree**:問「這個 chrome 的 title 有可能多行 / 有 subtitle / 有 description 嗎?」
-- **會** → padding-based(SurfaceHeader 或自刻 py-tight)
-- **不會** → fixed-h(`h-[var(--chrome-header-height)]`)
-
-**完整 canonical + 世界級對照**:`tokens/uiSize/uiSize.spec.md`「Chrome header 選型 canonical」節(含「2 種 pattern 對照」)
-
----
-
-## Size canonical(per-overlay default size SSOT,2026-05-04)
-
-> **背景**:Popover / HoverCard 是「輕量浮層」(chrome 45 / slot 21 / title 小一級 / density 鎖 md);Dialog / Sheet 是「heavy commitment chrome」(chrome 48 / slot 24)。Per-surface body+footer button/field default size 跟「輕量 vs heavy」分化對應。
->
-> **依據**:Linear / Notion / Airtable / Carbon / Material Menu / Atlassian Popup popover bodies 共識用 sm-density;Material AlertDialog / Carbon Modal / shadcn Dialog 共識用 md。world-class 雙派分明依「浮層密度」分。 <!-- @benchmark-unverified -->
-
-| Overlay | Header chrome | Body field controls | Body inline action(drag handle / trash / +CTA)| Footer action Buttons |
-|--|--|--|--|--|
-| **Popover** | unbounded sm → 21 slot(輕)| **sm**(輕量 dense info)| inline-action sm/md = **16+18** | **sm** |
-| **HoverCard** | (同 Popover)| **sm** | 同 | **sm** |
-| **Dialog** | unbounded sm → 24 slot | **md** | inline-action sm/md = 16+18 | **md** |
-| **Sheet** | (同 Dialog)| **md** | 同 | **md** |
-| **BulkActionBar** | N/A | N/A | N/A | **md**(default footer placement);未來 top-toolbar variant → sm |
-
-**核心 invariant**:overlay surface 內 **body field controls + footer Buttons 同一 size**(per-surface 一致)。違反 = 視覺重量割裂。
-
-**為什麼 Popover all-sm 而非 mix**:Popover 整體已是「輕量浮層」設計語言(chrome 短、title 小、density 鎖 md)。如果 body 用 md fields(32 高)+ footer sm Buttons(28 高),視覺重量割裂破壞「輕量」一致性。**all-sm 是內部一致性**(body 28 / footer 28 同高,延伸 chrome 輕一級的密度)。
-
-**為什麼 Dialog all-md 而非 mix**:Dialog 是 heavy commitment chrome,body 操作往往 form-heavy,md (32) 是 Field family default(`--field-height-md` SSOT),footer Buttons 同 md commit 視覺重量配得上 modal 結論性。
-
-**Drag handle / inline-action sizing**(對齊 `patterns/element-anatomy/inline-action.spec.md`):
-- Field sm/md 同 row → inline action **16 icon / 18 hover bg**
-- Field lg 同 row → inline action **20 icon / 22 hover bg**
-
-亦即:在 Popover(field=sm)或 Dialog(field=md)body 內,inline action 都同樣 16+18,差別只在 lg-density 場景。
-
----
-
-## Chrome dismiss size canonical
-
-**User 設計 insight**:header 的 padding-based sizing 在 **unbounded button**(text variant / dismiss,無 bg/border)場景視覺 padding 過大;在 **bounded button** 則剛好。解法 = **保持 button native size 不變(touch target / 視覺 render 都是 sm 原尺寸),但 layout 佔位縮到 title line-box(24,衍生自 --font-body-lg-size×1.5)** via 負 margin。
-
-**Canonical**:button native size **保留 sm**(touch target / 視覺 render 不動);**unbounded 的靠 CSS 負 my 把 layout 佔位縮到 `--chrome-slot-h`** ≤ title line-height,讓 title 主導 chrome 高度。
-
-| Button 類型 | 判定(button.tsx L426-427)| Trick 套用 | Layout 佔位 | Dialog/Sheet header (slot 24)| Popover header (slot 21)|
-|--|--|--|--|--|--|
-| **Unbounded** | `variant === 'text'` OR `dismiss` → `data-unbounded="true"` | ✓ 套負 my | = `var(--chrome-slot-h)` | max(24, 24) + py-tight = **48** | max(21, 21) + py-tight = **45** |
-| **Bounded** | `primary` / `tertiary` / `outline` 等(有 bg/border) | ✗ 不套 | = native sm (28 md / 32 lg) | max(24, 28) + py-tight = **52**(自然長)| max(21, 28) + py-tight = **52**(自然長)|
-
-**為什麼差別**:Unbounded 沒視覺邊界 → native 28 是純 hit-target padding,縮 layout 不損視覺;Bounded 的 bg/border 就是內容,縮會切掉 → 必須讓 chrome 自然長高,**這是設計宣告「此 chrome 有重要 action,視覺重量該配得上」**。
-
-**實作**:
-
-```tsx
-// button.tsx ── 自動標記 data-unbounded
-const unboundedAttr = resolvedVariant === 'text' || dismiss ? { 'data-unbounded': 'true' } : {}
-
-// overlay-surface.tsx ── slot 透過 CSS var 參數化(2026-05-04 v3;2026-06-16 default 改衍生)
-const CHROME_UNBOUNDED_SLOT =
-  '[&_[data-unbounded]]:my-[calc((var(--chrome-slot-h,calc(var(--font-body-lg-size)*1.5))-var(--field-height-sm))/2)]'
-
-// SurfaceHeader default → slot 衍生自 title typography = calc(--font-body-lg-size × 1.5) = 24
-//   (2026-06-16:從寫死 field-height-xs 改衍生 → title 字級改了 slot 自動跟、不靠巧合;M17 SSOT;
-//    1.5 = typography.spec body 行高常數,非 token 故 inline,body 行高改須同步)
-// Popover-tier override → COMPACT_HEADER_SLOT(= calc(--font-body-size × 1.5) = 21,衍生自 text-body title)
-// 公式 = (slot - native) / 2 ──  Dialog md: (24-28)/2 = -2px / Popover md: (21-28)/2 = -3.5px
-```
-
-**覆蓋範圍**:
-- Dismiss X(`<Button dismiss />`)→ data-unbounded ✓
-- Text variant action(`<Button variant="text" />` 如 Share / Refresh / Settings)→ data-unbounded ✓
-- 所有無視覺邊界的 button,不限 dismiss
-
-**為什麼用負 margin 而非 fixed wrapper / size="xs"**:
-- `size="xs"` 會縮小 button 本身,**touch target 也變 24**(違反 a11y 最小 24+ hit target,也違反 user 意圖「touch 仍 sm」)
-- `min-h-chrome-header-height` fixed wrapper 會鎖死高度,**bounded button 失去自然長高能力**(違反 user 意圖)
-- 負 margin:button render / touch target 不變,僅影響 parent flex layout 計算 → 剛好 user 想要的「layout 24,視覺 / 觸控 28」
-
-**Consumer 使用方式**:
-
-```tsx
-// Dialog / Sheet / Popover / Coachmark(透過 SurfaceHeader)
-<Button data-dismiss iconOnly dismiss size="sm" startIcon={X} aria-label="關閉" />
-// `dismiss` prop → Button 自動標 `data-unbounded`(縮位 trick 判定詞);`data-dismiss` 用途不同,
-// 是 openAutoFocus 排除 marker(popover.tsx / dialog.tsx autofocus selector)。
-// SurfaceHeader 自動套負 my,無需 consumer 手動 y 調整
-
-// Header 若塞 bounded button(primary sm)→ Button 不自動標 `data-unbounded`,不套負 my → 自然長高
-<Button variant="primary" size="sm">套用</Button>
-
-// Notification banner(Notice / Alert / Toast):px-4 py-3 fixed,dismiss 用 xs 簡化(無 margin trick)
-<Button iconOnly dismiss size="xs" startIcon={X} aria-label="關閉通知" />
-```
-
-**Consumer 實際高度範例**:
-- Dialog header 只有 title + close X(sm,`dismiss` → 自動 `data-unbounded`)→ layout 佔位 24 → header = 48 md / 56 lg ✓
-- Dialog header 有 refresh/share(text variant)/ close(dismiss)sm → 全自動標 `data-unbounded` → 全部 layout 佔位 24 → header 仍 48/56
-- Dialog header 塞 primary sm(bounded,無 `data-unbounded`)→ primary layout 佔 28 → header = 52 md(自然長)
-- Popover header 同 pattern:48 md / 56 lg
-
-**Rationale**:Unbounded 無 bg/border → 2×py-tight 過大,縮 layout 佔位至 xs(24)讓 header = chrome-header-height = 48 自然閉合,跟 Sidebar / page header / top bar 對齊。Bounded 自帶視覺重量,自然長到 52+,跟 footer 一致。
-
-**共通 rationale**(全 overlay + banner 家族):corner close X 屬 **action group region**,必用 `<Button>` primitive(不自刻 `<button><X /></button>` 繞 DS token / a11y,不用 `ItemInlineActionButton`)。
-
-**本 session 震盪歷史備忘(M12 FP 記憶)**:
-- ❌ v1「chrome dismiss 全 xs(DS-wide 統一)」→ 錯:過度簡化 rationale
-- ❌ v2「三家族 modal sm / non-modal xs / banner xs」→ 錯:overlay 內部不必分化
-- ❌ v3「overlay 統一 sm + min-h chrome-header-height 強鎖 48/56」→ 錯:強鎖會讓 bounded button 被鎖死 slot
-- ❌ v4「padding-based + unbounded=xs / bounded=natural」→ 錯:xs 縮小 button 連 touch target 也變 24(違反 a11y / user 意圖)
-- ✅ v5「padding-based + unbounded `data-unbounded` 套負 my(native size sm 不變)/ bounded natural」→ 對:button native size 與 touch target 保 sm,僅 layout 佔位縮回 24,48/56 chrome-header-height 自然達成
-
-**SSOT 關聯**:
-- `tokens/uiSize/uiSize.spec.md`「--chrome-header-height」+ `globals.css` 聲明(md=3rem / lg=3.5rem)
-- `tokens/layoutSpace/layoutSpace.spec.md` tight = 12 md / 16 lg
-- `patterns/element-anatomy/inline-action.spec.md`「Dismiss canonical — X close only」
-- `components/Button/button.spec.md`「Dismiss 視覺類」+ unbounded / bounded 判斷
+「Overlay title typography canonical」(modal 16 / non-modal 14)、「為什麼 SurfaceHeader 是 padding-based(而非 fixed-h)」、「Size canonical」(per-overlay body 控件與 footer 按鈕尺寸)、「Chrome dismiss size canonical」(`data-unbounded` 負 margin 縮位、v1–v5 震盪歷史)四節整段住在 `./overlay-chrome-sizing.spec.md`;本檔只留這個指標。
 
 ---
 
@@ -544,8 +387,8 @@ border-l border-divider">`)/ Atlassian `modal-dialog/examples/101-full-height-il
 
 overlay-surface 是 **layout pattern**(`SurfaceHeader` / `SurfaceBody` / `SurfaceFooter`),不持有互動行為 — a11y 大宗在 consumer overlay primitive(Dialog / Sheet / Popover / HoverCard)上,由 Radix 處理:
 
-- **Role + ARIA**:`Dialog.Content` / `Sheet.Content`(皆 wrap Radix Dialog)自帶 `role="dialog"` + `aria-labelledby`(連 DialogTitle id)+ `aria-describedby`(optional Description)。**modality 機制**:Radix 不發 `aria-modal` 屬性,而是用 `hideOthers`(把背景 sibling subtree 套 `aria-hidden`)+ `RemoveScroll` 達成 modal — 對齊 WAI-ARIA APG「aria-hidden on background content」做法(APG 指出 `aria-modal` 的 AT 支援不一致,hideOthers 較穩健)。`Popover.Content` 同樣 wrap Radix(non-modal,Radix `modal` 預設 false)且**也帶** `role="dialog"`(Radix non-modal dialog,APG sanctioned)——但**不** trap focus、**不**自動 `aria-labelledby`(consumer 需自設 `aria-label`)。`HoverCard.Content` 才是真的**無 role**(Radix react-hover-card 不發任何 role)
-- **Focus trap**:Dialog / Sheet 自帶 modal focus trap;Popover / HoverCard 不 trap(non-modal canonical)
+- **Role + ARIA**:`Dialog.Content` / `Sheet.Content`(皆 wrap Radix Dialog)自帶 `role="dialog"` + `aria-labelledby`(連 DialogTitle id)+ `aria-describedby`(optional Description)。**modality 機制**:Radix 不發 `aria-modal` 屬性,而是用 `hideOthers`(把背景 sibling subtree 套 `aria-hidden`)+ `RemoveScroll` 達成 modal — 對齊 WAI-ARIA APG「aria-hidden on background content」做法(APG 指出 `aria-modal` 的 AT 支援不一致,hideOthers 較穩健)。`Popover.Content` 同樣 wrap Radix(non-modal,Radix `modal` 預設 false)且**也帶** `role="dialog"`(Radix non-modal dialog,APG sanctioned)——Tab 在面板裡繞圈但滑鼠點外面可離開(見下一條)、**不**自動 `aria-labelledby`(consumer 需自設 `aria-label`)。`HoverCard.Content` 才是真的**無 role**(Radix react-hover-card 不發任何 role)
+- **Focus trap / Tab 走向**(2026-09-25 更正,原句「Popover / HoverCard 不 trap」被讀成 Tab 可以走出 Popover,與實測不符;待辦總帳 B11):**對話框型浮層 Tab 留在裡面** —— Dialog / Sheet 是 modal trap(Tab 繞圈,滑鼠點外面也出不去);Popover 是 non-modal:Tab / Shift+Tab 同樣在面板裡繞圈(Radix FocusScope `loop: true`,`@radix-ui/react-popover` 1.1.15 `dist/index.mjs:225-226`),只是滑鼠點外面 / 程式移焦可離開並關閉。依據 W3C「Like non-modal dialogs, modal dialogs contain their tab sequence.」(<https://github.com/w3c/aria-practices/blob/3f094fde1c81b25dfa69162563bf28d093f854d4/content/patterns/dialog-modal/dialog-modal-pattern.html#L29-L30>)。**選單類浮層 Tab = 收起並往下走**(DropdownMenu、單選下拉;規則在 `components/SelectMenu/select-menu.spec.md`「A11y 預設」與 `components/DropdownMenu/dropdown-menu.spec.md`)。HoverCard 焦點不進卡片(Radix 把卡片內可 Tab 節點設 `tabindex="-1"`),Tab 從觸發元素照頁面順序走
 - **Esc / 點外面關閉**:Radix 處理(可被 `onEscapeKeyDown` / `onPointerDownOutside` 攔截)
 - **AutoFocus on open**:consumer 自管 `onOpenAutoFocus`(Popover 範例:`handlePopoverOpenAutoFocus` 找 body 第一個 interactive 元素,跳過 close X 避免 tooltip leak)
 
@@ -583,11 +426,14 @@ overlay-surface 是 **layout pattern**(`SurfaceHeader` / `SurfaceBody` / `Surfac
 
 - `app-shell.spec.md`
 - `coachmark.spec.md`
+- `date-picker.spec.md`
 - `dialog.spec.md`
 - `element-anatomy.spec.md`
 - `file-item.spec.md`
 - `header-canonical.spec.md`
+- `item-anatomy.spec.md`
 - `motion.spec.md`
+- `overlay-chrome-sizing.spec.md`
 - `popover.spec.md`
 - `sheet.spec.md`
 - `time-picker.spec.md`

package/src/patterns/overlay-surface/overlay-surface.tsx

@@ -27,9 +27,11 @@ import { HEADER_TABS_SLOT_WRAPPER_CLASS } from '@/design-system/patterns/header-
  * ── Unbounded controls 在 header canonical(v5 trick,2026-04-22)──
  * Dismiss X(always unbounded)+ text variant header action → **`size="sm"` native**
  * + SurfaceHeader CSS 自動套負 my trick(對 `[data-unbounded]`),layout 佔位縮回 24
- * (xs 等同)。Rationale:button native size 跟 touch target 保留 sm(a11y 最小 24+ hit
- * target,視覺 render 仍 28/32),layout 佔位精確匹配 chrome-header-height 幾何。詳
- * `overlay-surface.spec.md`「Chrome dismiss size canonical」。
+ * (xs 等同)。Rationale:button native size 跟命中區保留 sm(視覺 render 仍 28/32,命中 ≡ 可視
+ * → `ds-canonical/references/hit-area-canonical.md`),layout 佔位精確匹配 chrome-header-height 幾何。
+ * 縮到 xs 的問題是**與 chrome 的比例**(chrome dismiss 是 sm = 28),不是 a11y —— 24 正好是
+ * `tokens/uiSize/uiSize.spec.md`「元件高度地板」訂的最小值。詳
+ * `overlay-chrome-sizing.spec.md`「Chrome dismiss size canonical」(2026-09-27 自 `overlay-surface.spec.md` 拆出)。
  *
  * **Notification banner family**(Notice / Alert / Toast,fixed `px-4 py-3` variant,
  * 無 padding-based header)→ dismiss 用 `size="xs"` explicit(24 固定,無 trick)。

package/src/patterns/resize-handle/resize-handle.spec.md

@@ -64,11 +64,11 @@ benchmark:
 
 取值依據:7px 命中區 / 1px line 非自創——來自下方「世界級對照細節」5 家共識(hit zone 7-8px fingertip-friendly / 1px line non-intrusive)+ DataTable v11 已 ship 的既有 canonical(本 primitive 抽取自它,M17)。
 
-- **命中區**:7px 寬(horizontal)/ 高(vertical),`-3px` outward offset 跨 boundary 抓得到。**外側 3px 必須真的抓得到**(2026-09-10):primitive 給命中區 `z-index: 1`,否則 DOM 順序在後的 positioned 鄰居會蓋住它;消費端的容器不得用 `overflow: hidden` 裁到它(要抑制 flex `min-width: auto` 時改 `min-w-0`)。面板 / 捲動容器的邊界把它裁掉是預期例外(AG Grid 同)。世界級:AG Grid `.ag-header-cell-resize{position:absolute;z-index:2;width:8px;right:-3px}`(https://unpkg.com/ag-grid-community/styles/ag-grid.css)、MUI X `columnSeparator` `position:'absolute', zIndex:30, right:-5`、目標寬 10(https://github.com/mui/mui-x/blob/master/packages/x-data-grid/src/components/containers/GridRootStyles.ts)、VS Code `.monaco-sash{position:absolute;z-index:35}`(https://github.com/microsoft/vscode/blob/main/src/vs/base/browser/ui/sash/sash.css)。閘:`scripts/data-table-pinned-resize-invariant.mjs` R3(欄界兩側各 2px 都要命中把手;`--selftest` 注入 overflow:hidden / z-index:auto 必紅)。
+- **命中區**:7px 寬(horizontal)/ 高(vertical),`-3px` outward offset 跨 boundary 抓得到。**外側 3px 必須真的抓得到**(2026-09-10):primitive 給命中區 `z-index: 1`,否則 DOM 順序在後的 positioned 鄰居會蓋住它;消費端的容器不得用 `overflow: hidden` 裁到它(要抑制 flex `min-width: auto` 時改 `min-w-0`)。面板 / 捲動容器的邊界把它裁掉是預期例外(AG Grid 同)。世界級:AG Grid `.ag-header-cell-resize{position:absolute;z-index:2;width:8px;right:-3px}`(https://unpkg.com/ag-grid-community/styles/ag-grid.css)、MUI X `columnSeparator` `position:'absolute', zIndex:30, right:-5`、目標寬 10(https://github.com/mui/mui-x/blob/master/packages/x-data-grid/src/components/containers/GridRootStyles.ts)、VS Code `.monaco-sash{position:absolute;z-index:35}`(https://github.com/microsoft/vscode/blob/main/src/vs/base/browser/ui/sash/sash.css)。閘:`scripts/data-table-pinned-resize-invariant.mjs` R3(欄界兩側各 2px 都要命中把手;`--selftest` 注入 overflow:hidden / z-index:auto 必紅);AgentPanel 左緣把手同款,`scripts/agent-panel-breakpoint.mjs`「OE1 把手外側」(面板根節點 2026-09-29 由 `overflow-hidden` 改 `overflow-y-clip` + `min-w-0`,外側 2px 必命中;對照組注入 overflow:hidden 必紅)。
 - **Indicator**:消費既有 DataTable resize indicator contract，預設覆蓋完整可調整邊；確切 thickness / offset 與 source utility 由 `resize-handle.tsx` 擁有
   - **idle**:`bg-divider`
   - **disabled**:`bg-divider`(無 hover affordance)
-  - **hover**:`bg-[var(--border-hover)]`(via `group/resize` selector)
+  - **hover**:`bg-[var(--border-hover)]`(via `group/resize` selector)。**為什麼靜止 `--divider`(neutral-4)滑過跳到 `--border-hover`(neutral-6)而不是下一階**(2026-09-27 補寫;待辦總帳 A8,2026-09-25 R17 篩為「保留、規格補理由」,**AI 推導、未逐題經 user 拍板**):把手線是 `ds-canonical/references/hit-area-canonical.md`「唯一例外」那種**先天只有 1px 寬的線**,滑過只走一階(neutral-4 → 5)在 1px 上幾乎看不出來,回饋等於沒有;世界級同樣直接跳到強調色 —— MUI X 欄分隔線滑過與拖拉中都直接換成 `vars.colors.foreground.accent`(一手:[`GridRootStyles.ts`](https://github.com/mui/mui-x/blob/master/packages/x-data-grid/src/components/containers/GridRootStyles.ts) `columnSeparator` 的 `'&:hover': { color: vars.colors.foreground.accent }` 與 `columnSeparator--resizing` 同值,2026-09-27 讀 master;待辦總帳記的 `:482-485` 是較早版本的行號)、AG Grid 拖拉中 1px 主色(下方「世界級對照細節」表)。本 DS 的折衷:滑過跳到 `--border-hover`(消費 Field 邊框滑過那一階,不自創值)、拖拉中才用主色。`scripts/hover-own-pair-baseline.json` 兩筆 resize-handle 命中因此登記為 `documented`(理由住這一條),`scripts/data-table-pinned-resize-invariant.mjs` R4 量的懸停值 = `--border-hover` 維持不變。
   - **dragging**:`bg-primary`(拖拉中由元件自己判定 —— pointerdown 到 pointerup / cancel;沒有 `isResizing` prop,舊寫法已更正 2026-09-10)
   - **idle 線的歸屬**(2026-09-10,user 抓「釘選欄位 resize 時分隔線沒有變藍」):`showLine=false` 只把 **idle** 線交給消費端(DataTable 面板邊界欄由凍結邊界線 `dtPanelBoundaryRight::after` 畫、表格外框欄由外框畫),**hover 與拖拉的狀態色仍由本元件畫**,畫在同一個像素上 —— 左釘選面板的邊界線在面板最後一個像素、與把手線同位,狀態色剛好蓋在它上面;右釘選面板的邊界線與外框在鄰面板 / 外框那一像素,把手線只能畫在自己面板內側相鄰的一像素(面板 `overflow` 裁切,越界不可見),拖拉中看起來是「主色線緊貼灰線」。舊行為:`showLine=false` 連狀態色一起不畫,面板邊界欄拖拉中沒有任何回饋 = 違反本表。閘:`scripts/data-table-pinned-resize-invariant.mjs` R4(釘選邊界欄拖拉中把手線 = primary、放開後回透明)。
 - **Cursor**:`col-resize` / `row-resize`(`disabled` 時無)
@@ -76,7 +76,7 @@ benchmark:
 
 ## a11y
 
-- `role="separator"` + `aria-orientation`(horizontal 拖拉 → `vertical` 分隔線)+ `aria-valuenow / aria-valuemin / aria-valuetext="Npx"`(+ 有上限才 `aria-valuemax`;無上限時 valuetext 避免被讀成百分比)+ `aria-label` 必填;`tabIndex=0`;focus-visible = `outline-2 outline-offset-[-2px] outline-ring`(DataTable 既有字串)。
+- `role="separator"` + `aria-orientation`(horizontal 拖拉 → `vertical` 分隔線)+ `aria-valuenow / aria-valuemin / aria-valuetext="Npx"`(+ 有上限才 `aria-valuemax`;無上限時 valuetext 避免被讀成百分比)+ `aria-label` 必填;`tabIndex=0`;焦點框 = `focus-visible:focus-ring-inset`(內描邊,往內 2px;`resize-handle.tsx:243`)。
 - 鍵盤:←/→(horizontal)或 ↑/↓(vertical)每步 `step`、Home = min、End = max(有上限才);命中的鍵 preventDefault + stopPropagation(不冒泡到排序 / 欄位拖曳)。
 - `disabled` = 只畫線:無 role / tabIndex / cursor,`aria-hidden`。
 - 對照 [APG Window Splitter](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/):Left/Right Arrow 移動垂直 splitter、Home/End 到極限。

package/src/styles/base.css

@@ -47,7 +47,7 @@
      要改成往內畫的才加 `focus-ring-inset`(見下方 @utility)。 */
   :focus-visible {
     outline: 2px solid var(--ring);
-    outline-offset: 2px;
+    outline-offset: var(--stack-gap); /* 2px;「疊在一起的兩樣東西」之間的縫,全 DS 同一個 token(tokens/uiSize/uiSize.css) */
   }
 
   /* 文字反白 — 底色 token 化(--text-selection;SSOT = color.spec.md「Highlight」段)。

package/src/tokens/categorical-color.ts

@@ -131,7 +131,12 @@ export const CAT_SOLID_TOKENS: Record<CategoricalHue, { bg: string; text: string
   magenta: { bg: 'var(--color-magenta-6)', text: 'var(--on-emphasis)' },
 }
 
-/** Calendar event tile:subtle 底 + hover step-2(1:1)。 */
+/**
+ * Calendar event tile:subtle 底 + hover step-2(1:1)。
+ * 淡底的滑過 = 同色離底更遠一格:淺色變深、深色變亮(色階號碼 = 離所在底色多遠;primitives.css 檔頭、
+ * color.spec.md「Dark mode subtle」)。與上方實心色互動 state 不同 —— 那是 semantic `--{hue}-hover`(深色要反轉),
+ * 這裡是淡底區 step-1 → step-2,兩主題同向,直接用 primitive(2026-09-26 深色 step-2..4 改半透明淡底後成立)。
+ */
 export const CAT_EVENT: Record<CategoricalHue, string> = {
   blue: 'bg-[var(--color-blue-1)] text-[var(--color-blue-7)] hover:bg-[var(--color-blue-2)]',
   green: 'bg-[var(--color-green-1)] text-[var(--color-green-7)] hover:bg-[var(--color-green-2)]',