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

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

@@ -1,7 +1,8 @@
 ---
 pattern: overlay-surface
 internal: true
-scope: overlay shell sub-components (SurfaceHeader / SurfaceBody / SurfaceFooter + padding SSOT) — DS-internal consumer only(Dialog / Sheet / Popover / HoverCard / Coachmark wrap)
+family: composite  # composes SurfaceHeader/Body/Footer,非 Family 1-4 row element
+scope: overlay shell sub-components (SurfaceHeader / SurfaceBody / SurfaceFooter + padding SSOT) — DS-internal consumer only(Dialog / Sheet / Popover / Coachmark wrap;HoverCard 未納入,見「何時不用」)
 ---
 
 <!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
@@ -17,22 +18,24 @@ Dialog 和 Popover 的**結構化 sub-components 共用 primitive**——提供
 
 **Layout Family**:非上述 family — structural container primitive(不是 element-level layout,是 surface-level 分區)。
 
-**Consumers**:`Dialog` / `Popover`。未來任何其他「elevation-200 浮層」(如 Drawer / Sheet)的結構化 sub-components 都應消費本 primitive。
+**Consumers**:`Dialog` / `Sheet`(直接消費 `SurfaceHeader` / `SurfaceFooter`,body 走 ScrollArea canonical 見下)、`Popover`(直接消費 `SurfaceHeader` / `SurfaceFooter`,PopoverBody 直接 wrap `SurfaceBody` bare — 見「Popover 例外」);`Coachmark` 經 `PopoverHeader` wrapper、`DatePicker` / `TimePicker` 直接消費 `SurfaceFooter`、DataTable 篩選/排序面板經 raw `SurfaceHeader` 間接消費。未來任何其他「elevation-200 浮層」(如 Drawer)的結構化 sub-components 都應消費本 primitive。
 
 ---
 
 ## 規則
 
 ### SurfaceHeader
-- `border-b border-divider`(上下分隔）
+- `border-b border-divider`(上下分隔;**例外**:`withTabs` / `tabsSlot` 時撤 border-b,由 tabs underline 接管 paint,`tabsSlot` 並自動切 column mode — 契約 SSOT 見 `patterns/header-canonical/header-canonical.spec.md` W1 / W2)
 - `px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]`
 - `flex items-center gap-2 shrink-0`(不被 flex-grow 壓縮)
 
 ### SurfaceBody
 - `px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]`
-- **無額外 flex 屬性**——consumer 依浮層類型決定:
+- **永遠套 `flex-1 min-h-0 overflow-y-auto`**(viewport-aware scroll:視窗太小時 body 內捲動;非 flex-col parent 內 flex-1/min-h-0 為 no-op,backward compat)。2026-05-31 infra-audit 修:原寫「無額外 flex 屬性」與 code(overlay-surface.tsx:183 恆套)矛盾。consumer 依浮層類型:
+- **Focus ownership**:SurfaceBody 不預設 `tabIndex`——短內容時它不是 scroll region,一律塞進 sequential focus order 會製造多餘 tab stop。當 bare SurfaceBody 在定高/viewport 壓縮下**實際 overflow**時,consumer 必須傳 `tabIndex={0}` + `role="region"` + 語意明確的 `aria-label`;SurfaceBody runtime 內建 inset DS focus ring。`BodyScroll` story 的 play assertion 機械驗證該具名節點確實 overflow 且可聚焦。Dialog / Sheet 正式 consumer 仍優先走下節 ScrollArea canonical。
   - **Popover**:多數 bare consume,padding 即是總 padding
   - **Dialog / Sheet**:consumer **不直接 wrap SurfaceBody**——走 ScrollArea canonical(下節),padding 搬到 ScrollArea viewport 內層 div
+- **邊界**:空 children → 不渲染 placeholder、無最小高度(定高浮層內仍被 `flex-1` 撐滿剩餘空間);viewport 極小 → 見「Viewport-aware scroll chain invariant」節(body 內捲動);loading / error / empty 屬 consumer 內容層職責,非本 structural pattern(見 `dialog.spec.md`「狀態處理的職責邊界」)
 
 ---
 
@@ -84,8 +87,7 @@ Dialog 和 Popover 的**結構化 sub-components 共用 primitive**——提供
   <div className="py-2">                       {/* list outer wrapper:menu group 8px breathing */}
     {items.map(item => (
       <MenuItem key={item.id} className="px-[var(--layout-space-loose)]">{item.label}</MenuItem>
-      // 或 hand-craft Family 2 row(prefix+content)時:
-      // <div className="flex items-center gap-3 py-2 px-[var(--layout-space-loose)] rounded-md hover:bg-neutral-hover">
+      // Family 2 row 請直接消費 item-anatomy primitives；utility 組合由其 source 擁有。
     ))}
   </div>
 </DialogBody>
@@ -111,7 +113,7 @@ chrome 邊 ─ hover bg 左邊 ─────── [ loose breathing ] ──
 | Slack channel list | 0 | loose | ✓ |
 | Raycast / Spotlight | 0 | loose | ✓ |
 | VS Code Quick Pick | 0 | loose | ✓ |
-| Material M3 / Polaris Modal+List | px only | item inset | ✗(另一合法家族,鬆散版)|
+| Material M3 / Polaris Modal+List | px only | item inset | ✗(另一合法家族,鬆散版)| <!-- @benchmark-unverified -->
 
 本 DS 選 Linear-family。
 
@@ -122,7 +124,7 @@ list 不再是 body 唯一 region → **不該撤 body chrome padding**(撤了
 ```tsx
 <DialogBody>  {/* 預設 chrome padding */}
   <Input search />                              {/* search row */}
-  <div className="mt-tight py-2 -mx-loose">     {/* list outer:撤 body 水平 padding 讓 item flush chrome */}
+  <div className="mt-[var(--layout-space-tight)] py-2 -mx-[var(--layout-space-loose)]">  {/* list outer:撤 body 水平 padding 讓 item flush chrome */}
     {items.map(...)}
   </div>
 </DialogBody>
@@ -170,12 +172,12 @@ list 不再是 body 唯一 region → **不該撤 body chrome padding**(撤了
 - Item `px=0` 讓 content 直接觸 hover bg 邊(content-inside-bg breathing 違反)
 - list outer 重複 `py-4` + item 各自 `py-2`(過鬆)
 - 不對稱 padding 無 rationale
-```
 
 ### SurfaceFooter
 - `border-t border-divider`
 - `px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]`
 - `flex items-center justify-end gap-2 shrink-0`(右對齊按鈕列,不被壓縮)
+- **Footer px = body 內容內縮原則**:預設 `layout-space-loose` 讓 footer 按鈕左緣對齊 SurfaceHeader title / SurfaceBody 內容左緣(整面板內容垂直對齊一條線,同 Body alignment rationale)。**例外**:body 為 full-bleed(滿欄 column selector / 無 chrome padding 的 unbounded list)、無內容左緣可對齊時,可經 `className` override 較緊 px(eg. TimePicker footer override `px-[var(--layout-space-tight)]` 對齊滿欄置中 columns、保窄面板平衡)。**注**:`--field-px` 是 form-field gutter 概念(uiSize),**不**用於 overlay footer——footer 屬 overlay chrome,padding 走 layoutSpace 家族。
 
 ---
 
@@ -186,13 +188,13 @@ Overlay family 的 header title typography 依「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` / `HoverCard` / `Tooltip` |
+| **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):
+**世界級對照**(7 家 DS 同 split): <!-- @benchmark-unverified -->
 | DS | Modal title | Non-modal popover title |
 |----|-------------|------------------------|
 | Material M3 | Headline 24 / body 16 | Smaller 14-16 |
@@ -215,7 +217,7 @@ Overlay family 的 header title typography 依「modal vs non-modal」分級,**
 
 ## 為什麼 SurfaceHeader 是 padding-based(而非 fixed-h)(2026-04-22 設計原則)
 
-**SurfaceHeader 永遠 padding-based**(`py-tight`,**無** min-h)。Header 高度 = `max(title line-height, button slot)+ 2×py`,**slot 設計為 ≤ title line-height** 讓 title 主導 → header 高度 = title 決定。**Slot 透過 `--chrome-slot-h` CSS var 參數化**(default `var(--field-height-xs)` = 24 = body-lg 24,Dialog/Sheet 自然 48 ✓;Popover override `1.25rem` = 20 ≤ body 21,自然 ~45 輕一級)。Q10 修法不該動 header min-h 而動 button 佔位。SurfaceFooter 同 trick(若內含 unbounded)。**語義宣告**:
+**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(「這個操作無法復原」補充說明)。
 
@@ -229,19 +231,19 @@ Overlay family 的 header title typography 依「modal vs non-modal」分級,**
 - **會** → padding-based(SurfaceHeader 或自刻 py-tight)
 - **不會** → fixed-h(`h-[var(--chrome-header-height)]`)
 
-**完整 canonical + 世界級對照**:`tokens/uiSize/uiSize.spec.md`「消費 --chrome-header-height 的 2 種實作 pattern」節
+**完整 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 20 / title 小一級 / density 鎖 md);Dialog / Sheet 是「heavy commitment chrome」(chrome 48 / slot 24)。Per-surface body+footer button/field default size 跟「輕量 vs heavy」分化對應。
+> **背景**: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 雙派分明依「浮層密度」分。
+> **依據**: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 → 20 slot(輕)| **sm**(輕量 dense info)| inline-action sm/md = **16+18** | **sm** |
+| **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** |
@@ -263,13 +265,13 @@ Overlay family 的 header title typography 依「modal vs non-modal」分級,**
 
 ## 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 佔位縮回 xs(24)** via 負 margin。
+**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 L362)| Trick 套用 | Layout 佔位 | Dialog/Sheet header (slot 24)| Popover header (slot 20)|
+| 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, 20) + py-tight = **45** |
+| **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,視覺重量該配得上」**。
@@ -280,13 +282,15 @@ Overlay family 的 header title typography 依「modal vs non-modal」分級,**
 // button.tsx ── 自動標記 data-unbounded
 const unboundedAttr = resolvedVariant === 'text' || dismiss ? { 'data-unbounded': 'true' } : {}
 
-// overlay-surface.tsx ── slot 透過 CSS var 參數化(2026-05-04 v3 Q10)
+// 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,var(--field-height-xs))-var(--field-height-sm))/2)]'
+  '[&_[data-unbounded]]:my-[calc((var(--chrome-slot-h,calc(var(--font-body-lg-size)*1.5))-var(--field-height-sm))/2)]'
 
-// SurfaceHeader default → slot = field-height-xs (24)
-// PopoverHeader override → className "[--chrome-slot-h:1.25rem]" (20)
-// 公式 = (slot - native) / 2 ──  md unbounded sm: (24-28)/2 = -2px / Popover (20-28)/2 = -4px
+// 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
 ```
 
 **覆蓋範圍**:
@@ -304,9 +308,11 @@ const CHROME_UNBOUNDED_SLOT =
 ```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-dismiss`,不套負 my → 自然長高
+// 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)
@@ -314,20 +320,35 @@ const CHROME_UNBOUNDED_SLOT =
 ```
 
 **Consumer 實際高度範例**:
-- Dialog header 只有 title + close X(sm + `data-dismiss`)→ layout 佔位 24 → header = 48 md / 56 lg ✓
-- Dialog header 有 refresh/share/close 全 data-dismiss sm → 全部 layout 佔位 24 → header 仍 48/56
-- Dialog header 塞 primary sm(無 data-dismiss)→ primary layout 佔 28 → header = 52 md(自然長)
+- 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 判斷
+
 ---
 
 ## Viewport-aware scroll chain invariant(2026-05-04 K11 升 SSOT)
 
-> **背景**:Popover / HoverCard / Dialog / Sheet content 設 `max-h-[var(--radix-*-available-height)] flex flex-col overflow-hidden`,讓 viewport 太小時 header/footer 永遠 in-viewport,body 壓縮 scroll。但**中間任何 wrapper div 沒 forward `flex flex-col h-full` 就斷鏈**,SurfaceBody flex-1 失效,body 不會 scroll。
+> **背景**:Popover / HoverCard / Dialog / Sheet content 設 `max-h-[var(--radix-{popover|hover-card|dialog}-content-available-height)] flex flex-col overflow-hidden`,讓 viewport 太小時 header/footer 永遠 in-viewport,body 壓縮 scroll。但**中間任何 wrapper div 沒 forward `flex flex-col h-full` 就斷鏈**,SurfaceBody flex-1 失效,body 不會 scroll。
 >
-> **真實 bug(2026-05-04)**:Filter / Sort panel 內 wrapper div 設 `w-[640px]` 無 flex-col → user 縮視窗時 body 不 scroll,內容被 clip。NameCard 之所以 work 因為它直接是 PopoverContent 唯一 child(無 wrapper)+ 自設 max-h flex-col。
+> **真實 bug(2026-05-04)**:Filter / Sort panel 內 wrapper div 設 `w-[640px]` 無 flex-col → user 縮視窗時 body 不 scroll,內容被 clip。ProfileCard 之所以 work 因為它直接是 PopoverContent 唯一 child(無 wrapper)+ 自設 max-h flex-col。
 
 **Invariant**:從 `*Content`(浮層 root)到 `SurfaceBody` 之間的**所有中間 wrapper 都必 `flex flex-col h-full min-h-0`**(K11 v2,2026-05-04)。`min-h-0` 必須 — flex item default `min-height: auto` 會讓 content 撐高度,`h-full` 失效;加 `min-h-0` 才能正確 shrink 到 PopoverContent max-h cap。
 
@@ -340,22 +361,7 @@ const CHROME_UNBOUNDED_SLOT =
 
 **禁止**:`w-[640px]` 單獨用(❌ 斷鏈)/ `flex flex-col h-full` 無 `min-h-0`(❌ flex item 不 shrink,scroll 失效)。
 
-**DS-wide consumer 必檢點**:`grep '<PopoverContent\|<HoverCardContent\|<DialogContent\|<SheetContent'` 內第一層 wrapper 是否含 `flex flex-col h-full`(若該 panel 用 SurfaceBody)。Hook `check_overlay_panel_scroll_chain.sh` 機械化攔截。
-
-**共通 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-dismiss` 套負 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 判斷
+**DS-wide consumer 必檢點**:`grep '<PopoverContent\|<HoverCardContent\|<DialogContent\|<SheetContent'` 內第一層 wrapper 是否含 `flex flex-col h-full`(若該 panel 用 SurfaceBody)。Hook `check_pattern_invariants.sh` C.1(原 `check_overlay_panel_scroll_chain.sh` 已 folded;2026-05-31 infra-audit 修 dangling ref)write-time 機械化警示(P1 WARN stderr,僅掃本次 edit fragment 不 block);DS-wide 全掃(上述 grep 必檢點)走 audit。
 
 ---
 
@@ -369,17 +375,38 @@ const CHROME_UNBOUNDED_SLOT =
 
 寫 Popover / Dialog / Sheet 內容必消費 `SurfaceHeader/Body/Footer`(或上層 `PopoverHeader/...`),**禁自刻 `<div className="px-loose ... border-(b|t)">` 取代**。
 
-**Why**:primitive 自帶 padding token + PopoverHeader auto close X(line 72)+ PopoverTitle typography + `data-popover-body` autofocus 標記;自刻 = padding/border/close X/title 大小 4 向 drift 起點(對齊 mindset #2)。
+**Why**:primitive 自帶 padding token + PopoverHeader auto close X(popover.tsx:104-109,`!hideClose` 條件渲染)+ PopoverTitle typography + `data-popover-body` autofocus 標記;自刻 = padding/border/close X/title 大小 4 向 drift 起點(對齊 mindset #2)。
 
-**Hook**:`.claude/hooks/check_overlay_handcraft.sh` 攔此 pattern;escape hatch `// overlay-handcraft-allow: <reason>` 同/前行。
+**Hook**:`.claude/hooks/post_edit_dispatcher.sh`(原 `check_overlay_handcraft.sh` 已 folded;2026-05-31 infra-audit 修 dangling ref)攔此 pattern;escape hatch `// overlay-handcraft-allow: <reason>` 同/前行。
 
 ---
 
+## 兩欄 dialog 組合 canonical(2026-07-10 user 拍板:組合,不做元件)
+
+「左內容 + 右 metadata」兩欄 dialog(工作項詳情類)**是產品層組合,不收進 DS 元件**——對齊
+Atlassian(modal-dialog 無宣告式兩欄 API,官方以 composition 範例示範)與 MUI(Dialog 無 split
+API,欄由 layout primitive 組)。DS 只 codify 組合鐵律(違規簽名由 consumer 防線
+`check_consumer_app_invariants.sh` r3 機械攔):
+
+1. **各欄自帶 `<ScrollArea>` 獨立捲動**——禁兩欄共用單一 ScrollArea / 共用一條捲軸(每欄
+   套上方「Body overflow canonical」模板,padding 進 viewport 內層 div)。
+2. **divider = 右欄(`<aside>`)自持 `border-l border-divider`,貫穿 body 頂到底**——非獨立
+   div、非只切半高。
+3. **欄底 footer(如 comment composer)釘在所屬欄內**(欄內 `SurfaceFooter` chrome),
+   非 dialog 全寬 footer——對齊 Atlassian 官方兩欄範例把 ModalFooter 巢狀進左欄。
+4. **header 維持全寬**,分欄從 body 才開始。
+
+**Archetype**(照抄結構,禁憑記憶手刻):WM `WorkItemDetailDialog.tsx`(產品實證,2026-07-08
+拍板落地)/ DS 內部同構先例 `file-viewer.tsx` InfoPanel(`<aside class="w-80 shrink-0 flex-col
+border-l border-divider">`)/ Atlassian `modal-dialog/examples/101-full-height-illustration.tsx`
+(per-column `flex:1 + minHeight:0 + overflow auto`)。完整研究引文 →
+`.claude/planning/2026-07-10-dialog-split-body-proposal.md`(元件化提案被 user 否決的紀錄)。
+
 ## 不屬本 primitive 的職責
 
 - **Close 按鈕渲染**:由 consumer(Dialog / Sheet / Popover)自己包 `<Button iconOnly dismiss>` 在 Header 內,綁各自 Radix Close primitive。SurfaceHeader 本身不渲染 close,避免 pattern 與 consumer 的職責耦合。
 - **viewport-fill 高度邏輯**:Dialog 特有(填滿 viewport - inset),由 DialogContent 自行計算 `height: calc(100vh - inset*2)`,與 Body 協作 `flex-1 overflow-y-auto`。
-- **radius / border / shadow / bg**:浮層外殼職責,由 Dialog / Popover 的 Content 自己套(都套同一組 token:`bg-surface-raised` / `border-border` / `rounded-lg` / `shadow-[var(--elevation-200)]`——這部分 CLAUDE.md 已經寫明對齊規則,不另外抽 primitive)。
+- **radius / border / shadow / bg**:浮層外殼職責,由 Dialog / Popover 的 Content 自己套(都套同一組 token:`bg-surface-raised` / `border-border` / `rounded-lg` / `shadow-[var(--elevation-200)]`——由本段記錄共同 consumer contract,並遵循 `packages/design-system/ds-canonical/rules/ui-development.md`「Token 命名 4 條硬規則」,不另外抽 primitive)。
 
 ---
 
@@ -387,7 +414,7 @@ const CHROME_UNBOUNDED_SLOT =
 
 overlay-surface 是 **layout pattern**(`SurfaceHeader` / `SurfaceBody` / `SurfaceFooter`),不持有互動行為 — a11y 大宗在 consumer overlay primitive(Dialog / Sheet / Popover / HoverCard)上,由 Radix 處理:
 
-- **Role + ARIA**:Radix `Dialog.Content` / `Popover.Content` / `Sheet.Content` 已自帶 `role="dialog"` + `aria-modal`(modal only)+ `aria-labelledby`(Title)+ `aria-describedby`(optional Description)
+- **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)
 - **Esc / 點外面關閉**:Radix 處理(可被 `onEscapeKeyDown` / `onPointerDownOutside` 攔截)
 - **AutoFocus on open**:consumer 自管 `onOpenAutoFocus`(Popover 範例:`handlePopoverOpenAutoFocus` 找 body 第一個 interactive 元素,跳過 close X 避免 tooltip leak)
@@ -401,6 +428,16 @@ overlay-surface 是 **layout pattern**(`SurfaceHeader` / `SurfaceBody` / `Surfac
 - **Toast / Alert**(Family 2 List item 視覺對齊):那是 row-item layout 不是 surface-section,不要套本 pattern。
 - **Tooltip**(純文字短提示):無結構化需求,不包 Header/Body/Footer。
 - **HoverCard**(自由組合互動浮層):目前 consumer 自行組合內容,視未來是否引入 Header/Body/Footer 需求再納入 consumer。
+- **近親分界**:固定高度 app chrome(Sidebar header / toolbar / top bar)屬 **Chrome header(Fixed-h)家族**,用 `<ChromeHeader>` 非 SurfaceHeader——跨家族契約 SSOT 見 `patterns/header-canonical/header-canonical.spec.md`。
+
+## 常見誤解
+
+| 誤解 | 正解 |
+|------|------|
+| 「Dialog / Sheet body 直接 wrap SurfaceBody」 | 否——走 ScrollArea canonical(見「Body overflow canonical」) |
+| 「list 場景需要 `flush` variant」 | 已撤回;用 className override + 自管 list wrapper(見「List-as-region」) |
+| 「SurfaceHeader 自帶 close X」 | 否——close 由 consumer 包 `<Button iconOnly dismiss>`(見「不屬本 primitive 的職責」) |
+| 「SurfaceFooter 也套 unbounded slot trick」 | 否——footer 慣例放 bounded action buttons,僅 padding + border-t |
 
 ---
 
@@ -414,15 +451,14 @@ overlay-surface 是 **layout pattern**(`SurfaceHeader` / `SurfaceBody` / `Surfac
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `app-shell.spec.md`
 - `coachmark.spec.md`
+- `dialog.spec.md`
 - `element-anatomy.spec.md`
-- `notice.spec.md`
-- `sheet.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
-- `app-shell.spec.md`
+- `file-item.spec.md`
 - `header-canonical.spec.md`
 - `motion.spec.md`
+- `popover.spec.md`
+- `sheet.spec.md`
+- `time-picker.spec.md`
+- `uiSize.spec.md`

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

@@ -0,0 +1,132 @@
+// @story-baseline: patterns/header-canonical/header-canonical.stories.tsx#Overview — SurfaceHeader 段(title text-body-lg font-medium + dismiss size=sm)+ components/Dialog/dialog.stories.tsx footer 檔式(取消 tertiary + primary CTA)
+//
+// Internal Pattern 參照 story(對標 patterns/header-canonical 的 anatomy 參照定位)。
+// SurfaceHeader / SurfaceBody / SurfaceFooter 是 @internal primitive——end-user 用
+// DialogHeader / SheetHeader / PopoverHeader 等 wrapper,不直接 import;
+// 本頁給 DS contributor 看「overlay 三段式結構 + padding / 分隔線契約」長什麼樣。
+import type { Meta, StoryObj } from '@storybook/react'
+import { expect, within } from '@storybook/test'
+import type { ReactNode } from 'react'
+import { X } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import { SurfaceHeader, SurfaceBody, SurfaceFooter } from './overlay-surface'
+import { Button } from '@/design-system/components/Button/button'
+
+const meta: Meta = {
+  title: 'Design System/Internal Patterns/Overlay Surface',
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: `
+**@internal** — Dialog / Sheet / Popover / Coachmark 共用的浮層結構 primitive(SurfaceHeader / SurfaceBody / SurfaceFooter),統一 padding(\`px-loose py-tight\`)+ 分隔線(\`border-divider\`)語言,消除各 overlay 自寫 chrome 的漂移空間。
+
+end-user 不直接 import——用 DialogHeader / SheetHeader / PopoverHeader 等 consumer wrapper;本頁是 DS contributor 的結構參照。
+
+完整規則:\`packages/design-system/src/patterns/overlay-surface/overlay-surface.spec.md\`(padding-based header canonical / unbounded slot trick / ScrollArea canonical / dismiss size canonical)
+        `,
+      },
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj
+
+/** 模擬 consumer Content 外殼——radius / border / shadow / bg 是浮層外殼職責,
+ *  由 Dialog / Popover 的 Content 自己套(spec「不屬本 primitive 的職責」段 token 組)。 */
+function Shell({ children, className }: { children: ReactNode; className?: string }) {
+  return (
+    <div
+      className={cn(
+        'overflow-hidden rounded-lg border border-border bg-surface-raised shadow-[var(--elevation-200)]',
+        className,
+      )}
+    >
+      {children}
+    </div>
+  )
+}
+
+/** 1. 三段式結構 — Header(border-b)/ Body / Footer(border-t)各自的 padding 契約。
+ *  對標 Dialog「邀請成員」場景;header title = modal-tier typography(text-body-lg font-medium)。 */
+export const ThreePartStructure: Story = {
+  name: '三段式結構',
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <Shell className="w-[420px]">
+        <SurfaceHeader>
+          <h2 className="flex-1 truncate text-body-lg font-medium text-foreground">邀請成員加入專案</h2>
+          <Button iconOnly dismiss size="sm" startIcon={X} aria-label="關閉" />
+        </SurfaceHeader>
+        <SurfaceBody>
+          <p className="text-body text-foreground">
+            輸入 Email 即可邀請成員加入「Acme 品牌改版」專案。
+          </p>
+          <p className="mt-2 text-caption text-fg-secondary">
+            被邀請者會收到通知信,接受後自動取得專案的檢視與留言權限。
+          </p>
+        </SurfaceBody>
+        <SurfaceFooter>
+          <Button variant="tertiary">取消</Button>
+          <Button variant="primary">寄出邀請</Button>
+        </SurfaceFooter>
+      </Shell>
+      <p className="max-w-[420px] text-caption text-fg-muted">
+        三段共用 px-loose / py-tight;Header 自畫 border-b、Footer 自畫 border-t。Header 是
+        padding-based(title 可換行、chrome 隨內容長高),dismiss 按鈕 native size 保 sm、
+        layout 佔位由 unbounded slot trick 縮回 title 行高 → header 自然閉合 48px。
+      </p>
+    </div>
+  ),
+}
+
+/** 2. 內文捲動 — 定高浮層下 header / footer 固定、body 內捲。
+ *  Shell 需 flex flex-col(viewport-aware scroll chain:中間 wrapper 斷鏈 = body 不捲,spec K11 invariant)。 */
+export const BodyScroll: Story = {
+  name: '內文捲動',
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <Shell className="flex h-[280px] w-[420px] flex-col">
+        <SurfaceHeader>
+          <h2 className="flex-1 truncate text-body-lg font-medium text-foreground">服務條款更新</h2>
+          <Button iconOnly dismiss size="sm" startIcon={X} aria-label="關閉" />
+        </SurfaceHeader>
+        <SurfaceBody
+          tabIndex={0}
+          role="region"
+          aria-label="服務條款更新內容"
+        >
+          <div className="flex flex-col gap-3 text-body text-foreground">
+            <p>1. 資料保存期限由 30 天調整為 90 天,到期後自動匿名化。</p>
+            <p>2. 新增歐盟區域資料中心選項,既有工作區可在設定頁遷移。</p>
+            <p>3. API 免費額度調整為每月 10,000 次呼叫,超額部分依用量計費。</p>
+            <p>4. 子處理商清單新增兩家 CDN 供應商,完整清單見信任中心。</p>
+            <p>5. 帳單爭議申訴窗口由 14 天延長為 30 天。</p>
+            <p>6. 本次更新於 2026 年 8 月 1 日生效,繼續使用即視為同意。</p>
+          </div>
+        </SurfaceBody>
+        <SurfaceFooter>
+          <Button variant="tertiary">稍後再讀</Button>
+          <Button variant="primary">我已閱讀並同意</Button>
+        </SurfaceFooter>
+      </Shell>
+      <p className="max-w-[420px] text-caption text-fg-muted">
+        SurfaceBody 恆套 flex-1 min-h-0 overflow-y-auto:定高(或 viewport 太小)時 header / footer
+        永遠可見、body 內捲。注意:Dialog / Sheet 正式 consumer 的 body 走 ScrollArea canonical
+        (跨 OS 捲軸一致),此處為 primitive 裸展示。
+      </p>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    const scrollRegion = canvas.getByRole('region', {
+      name: '服務條款更新內容',
+    })
+
+    await expect(scrollRegion.scrollHeight).toBeGreaterThan(scrollRegion.clientHeight)
+    await expect(scrollRegion).toHaveAttribute('tabindex', '0')
+    scrollRegion.focus()
+    await expect(scrollRegion).toHaveFocus()
+  },
+}

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

@@ -1,9 +1,11 @@
 import * as React from 'react'
 import { cn } from '@/lib/utils'
+// W2 tabsSlot wrapper 契約 SSOT 在 header-canonical(跨家族 W-rule owner);SurfaceHeader 消費同一 const 不 hardcode。
+import { HEADER_TABS_SLOT_WRAPPER_CLASS } from '@/design-system/patterns/header-canonical/chrome-header'
 
 /**
- * @internal — DS-internal primitive(2026-05-23 per `.claude/rules/ui-development.md` Public vs Internal canonical)。
- * end-user app 直接 import 無 functioning UI;由 Dialog / Sheet / Popover / HoverCard / Coachmark 等 DS overlay 元件 wrap 消費。
+ * @internal — DS-internal primitive(2026-05-23 per `packages/design-system/ds-canonical/rules/ui-development.md` Public vs Internal canonical)。
+ * end-user app 直接 import 無 functioning UI;由 Dialog / Sheet / Popover / Coachmark 等 DS overlay 元件 wrap 消費(HoverCard 不消費 — 2026-07-04 grep 0 import,spec「何時不用」同步)。
  *
  * Overlay Surface primitives — Dialog / Popover / Sheet 共用結構化 sub-components。
  *
@@ -49,18 +51,30 @@ import { cn } from '@/lib/utils'
 // 時標記)的 **native size 不變**(sm: 28 md / 32 lg),但 **layout 佔位** via 負 `my` 縮成 `--chrome-slot-h`。
 //
 // **Slot height = header title 的 line-height**(讓 button 不 dominate,title 自然撐 header)
-//   - Default `var(--field-height-xs)` = 24,匹配 Dialog/Sheet text-body-lg (16 × 1.5 = 24)
-//   - Popover/Coachmark override `--chrome-slot-h: 1.25rem` (20),匹配 text-body (14 × 1.5 ≈ 21,floor 20)
+//   - Default 衍生自 title typography:`calc(var(--font-body-lg-size)*1.5)` = 16×1.5 = 24(Dialog/Sheet title = text-body-lg)。
+//     2026-06-16:從寫死 `var(--field-height-xs)`(巧合也=24)改為衍生 → title 字級若改,slot 自動跟、不靠巧合(M17 SSOT;
+//     1.5 = typography.spec body 行高常數,非 token 故 inline,若 body 行高改 1.3 須同步此處)。
+//   - Popover-tier(title = text-body)走 `COMPACT_HEADER_SLOT`(見下)= calc(--font-body-size×1.5) = 14×1.5 = 21
+//     (= PopoverTitle text-body line-box,衍生非寫死;2026-06-16 從各自寫死 1.25rem/20 巧合值收斂進 SSOT)
 //
-// Header 永遠 padding-based(無 min-h),但因 slot ≤ title line-height,header 高度由 title 主導:
+// Header 永遠 padding-based(無 min-h),但因 slot = title line-box,header 高度由 title 主導:
 //   - Dialog: max(24 title, 24 slot) + py-tight(12*2)= 48 ✓ chrome-header-height
-//   - Popover: max(21 title, 20 slot) + py-tight(12*2)= 45 ✓ 自然輕量
-// Q10 穩定性:title-only / title+button / refresh in/out 全 case header 高度 = title + py(slot 不 dominate)
+//   - Popover: max(21 title, 21 slot) + py-tight(12*2)= 45 ✓ 自然輕量
+// Q10 穩定性:title-only / title+button / refresh in/out 全 case header 高度 = title + py(slot=title,不超過)
 //
 // 負 my 公式:(slot - native) / 2,density-aware:
 //   Dialog md: (24 - 28) / 2 = -2px;  lg: (24 - 32) / 2 = -4px
-//   Popover md: (20 - 28) / 2 = -4px
-const CHROME_UNBOUNDED_SLOT = '[&_[data-unbounded]]:my-[calc((var(--chrome-slot-h,var(--field-height-xs))-var(--field-height-sm))/2)]'
+//   Popover md: (21 - 28) / 2 = -3.5px(sub-pixel,可接受)
+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)]'
+
+/**
+ * 輕量浮層 header 的 slot override —— **SSOT,禁各自 inline**(2026-06-16 收斂)。
+ * Popover-tier header(title = PopoverTitle `text-body`)的 slot = body line-box = `calc(--font-body-size×1.5)` = 21,
+ * 衍生自 title typography → title 字級改,slot 自動跟(取代舊各自寫死的 1.25rem / 20 巧合值)。
+ * 消費者(同設計邏輯,皆 raw SurfaceHeader + PopoverTitle):PopoverHeader / DataTable sort·filter panel /
+ * FileItem upload-manager。Default slot(Dialog/Sheet,title = text-body-lg)= 24,在 CHROME_UNBOUNDED_SLOT fallback。
+ */
+export const COMPACT_HEADER_SLOT = '[--chrome-slot-h:calc(var(--font-body-size)*1.5)]'
 
 export interface SurfaceHeaderProps
   extends React.HTMLAttributes<HTMLDivElement> {
@@ -76,8 +90,10 @@ export interface SurfaceHeaderProps
    * Tabs row slot(2026-05-18 加 per header-canonical.spec.md W2/W4 真實能用 + user-mandated fix)。
    * 提供時 SurfaceHeader 自動 column 結構:
    *   row 1 = children(title + actions/dismiss,px-loose py-tight)
-   *   row 2 = tabsSlot 包在 `<div px-loose border-b border-divider>`
-   *           ↑ wrapper 提供 W2 padding inheritance + 全寬 paint(W1 視覺一條線)
+   *   row 2 = tabsSlot 包在 `HEADER_TABS_SLOT_WRAPPER_CLASS` wrapper(v4:wrapper 自身
+   *           無 px / 無 border;`[&_[data-slot=tabs-list]]` 注入 px-loose,寬度 TabsList
+   *           各 overflow 模式自帶,border-b 延展全寬 — W1 視覺一條線。
+   *           詳 chrome-header.tsx HEADER_TABS_SLOT_WRAPPER_CLASS 註解)
    *
    * Consumer 傳:`tabsSlot={<TabsList>...</TabsList>}`,TabsContent 仍放 DialogBody 內。
    * `<Tabs>` root 必須 wrap 整 DialogContent(Radix TabsList ↔ TabsContent 同 root 連動)。
@@ -118,13 +134,15 @@ export const SurfaceHeader = React.forwardRef<
             - v1: wrapper border + TabsList border = 雙線(W1 違反)
             - v2: wrapper px-loose + TabsList w-full inside = border 只跨 dialog - 2×px-loose
                  (不到 dialog 邊 user 抓「分隔線寬度應該要填滿整個 dialog」)
-            - v3(本):wrapper 不 inset,TabsList 自己 px-loose 內 padding inset triggers
+            - v3:wrapper 不 inset,TabsList 自己 px-loose 內 padding inset triggers
                   → TabsList border-b 延展全 dialog 寬,triggers 對齊 header content
-            對齊既有 `tabs.spec.md:199`「TabsList 自身 border-b border-border 延展全 header 寬,因
-            TabsList wrapper 是 block-level full-width」+ `:187-189`「selected 底線從 TabsList
-            gray border 位置長出來」+ GitHub Primer UnderlineNav / Ant Design line type / Mantine
-            default 共識(全派 TabsList 自畫 full-width underline)。*/}
-        <div className="[&>[role=tablist]]:w-full [&>[role=tablist]]:px-[var(--layout-space-loose)]">
+            - v4(2026-07-30):選取機制改 `data-slot="tabs-list"` attribute contract
+                  (beta.86 overlay 包裹層破 direct-child;詳 chrome-header.tsx 註解)
+            對齊既有 `tabs.spec.md`「Underline 與 TabsList border 的視覺關係」段「selected 底線從
+            TabsList 的 gray border 位置長出來」(token = border-divider,tabs.tsx TABS_LIST_BASE)
+            + GitHub Primer UnderlineNav / Ant Design line type / Mantine default 共識
+            (全派 TabsList 自畫 full-width underline)。*/}
+        <div className={HEADER_TABS_SLOT_WRAPPER_CLASS}>
           {tabsSlot}
         </div>
       </div>
@@ -133,7 +151,7 @@ export const SurfaceHeader = React.forwardRef<
 
   // Padding-based(預設) — Dialog/Sheet 用 body-lg title (16/24)，自然撐 max(24 title, 24 button slot) = 24
   // → header = 24 + py-tight 12×2 = 48 chrome-header-height ✓ 穩定無需 min-h
-  // Popover 等輕量 chrome 走 PopoverHeader override(min-h-10 + py-2 = 40,內 24 匹配 button slot)
+  // Popover 等輕量 chrome 走 COMPACT_HEADER_SLOT(slot = calc(--font-body-size×1.5)=21 = title line-box,無 min-h / 無 py override)：max(21 title, 21 slot) + py-tight 12×2 = 45（見上方 L57）
   //
   // withTabs=true(無 tabsSlot,backward compat):移除 border-b,consumer 自畫
   return (
@@ -166,6 +184,7 @@ export const SurfaceBody = React.forwardRef<
     ref={ref}
     className={cn(
       'flex-1 min-h-0 overflow-y-auto',
+      'focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-ring',
       'px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]',
       className,
     )}

package/src/patterns/resize-handle/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './resize-handle'