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

package/src/patterns/header-canonical/header-canonical.spec.md

@@ -1,7 +1,7 @@
 ---
 pattern: header-canonical
-internal: true
-scope: cross-component header SSOT (chrome + overlay families)
+family: self-contained  # 跨元件 header 規則 SSOT,非 row element
+scope: cross-component header anatomy + 設計原則(公開 Pattern,對標 item-anatomy)— chrome + overlay families
 benchmark:
   - GitHub Primer PageHeader: https://primer.style/components/page-header/react — hasBorder auto-suppress when Navigation slot contains UnderlineNav
   - Ant Design Tabs: https://ant.design/components/tabs — "Large size tabs are usually used in page header, and small size could be used in Modal"
@@ -13,7 +13,28 @@ benchmark:
 
 # Header Canonical 設計原則
 
-> **Foundational SSOT rationale**(cap 800):本 pattern 統一**所有 header 家族**(chrome page header + overlay header)的視覺契約 — border ownership / padding / 高度策略 / tabs 連動 / dismiss canonical。6 個 consumer(`SidebarHeader` / `FileViewer Toolbar+InfoPanel` / `DialogHeader` / `SheetHeader` / `PopoverHeader` / 未來 Drawer)pointer 指向本 SSOT,**禁各自 hardcode**。
+> **Foundational SSOT rationale**(cap 800):本 pattern 統一**所有 header 家族**(chrome page header + overlay header)的視覺契約 — border ownership / padding / 高度策略 / tabs 連動 / dismiss canonical。consumer(`SidebarHeader` / `FileViewer Toolbar+InfoPanel` / `AppShell PageHeader+GlobalHeader` / `DialogHeader` / `SheetHeader` / `PopoverHeader` / `CoachmarkHeader` / 未來 Drawer)pointer 指向本 SSOT,**禁各自 hardcode**。
+
+## 選哪個 header(decision — 做任何 header 前先回答這題)
+
+> 本段是「該用哪個 header」的單一決策入口(對標 `item-anatomy.spec.md` 的判斷流程,讓人 / AI 遇到任何 header 設計先走這裡、確認判斷正確才動)。**判準是「這個 header 坐在哪種 surface 上」,不是「長得像不像一條橫列」。**
+
+**先問一題:這個 header 所在的 surface 是「常駐 app chrome」還是「浮層 overlay」?**
+
+| 你的場景 | 用 | 家族 |
+|---|---|---|
+| **常駐 app chrome**:AppShell page top / global header、Sidebar header、FileViewer toolbar、固定在版面上的工具列 | **`<ChromeHeader>`**(`patterns/header-canonical/chrome-header`)| **B. Fixed-height** |
+| **浮層 overlay 標題列**:Dialog / Sheet / Popover / Coachmark 等 overlay 頂部(多數用 `DialogHeader`/`SheetHeader`/`PopoverHeader` consumer wrapper,底層是 SurfaceHeader)| **`<SurfaceHeader>`**(`patterns/overlay-surface`)| **A. Padding-based** |
+| 用一整排 **Tabs 直接「取代」整個 header**(無獨立標題列)| **standalone `<Tabs size="lg">`**(tab 高 = chrome-header-height,見 W3 C)| —(tabs 即 chrome)|
+
+**何時不用(when NOT to use)— 最常見誤判**:
+- ❌ **chrome 與 overlay 搞混**:看 surface 本身是常駐 chrome 還是浮層,不看視覺像不像。**邊界案例**:Sidebar 內彈出的 flyout / popover header = **overlay → SurfaceHeader**,不因為它長在 sidebar 裡就當 chrome。
+- ❌ 純內容區小標題(section heading)→ 用 typography(`text-h6` 等),不是 header primitive
+- ❌ **Dialog / 浮層內「不可關閉的 side pane」標題**(如 detail dialog 右欄 metadata 欄的「General info」)→ 走 typography,不消費 header primitive。**判準一句話:「這個 pane 能不能自己被關掉」**(2026-07-08 user 拍板 codify)—— **可獨立 dismiss**(自帶 close、自帶 ScrollArea、旁有等高 chrome 需對齊,如 FileViewer InfoPanel:I 鍵 + close X)→ `<ChromeHeader>`;**不可關閉** = pane 標題只是 content 的一部分 → 純 typography,間距跟著 layoutSpace 原則走(不 flush、無 border-b、隨內容捲動)。反例先例:DatePicker TimePickerSidePanel 同層級 caption 不消費 header primitive(date-picker.spec.md「TimePickerSidePanel header 下方無 divider」段)。外部對照:Carbon SidePanel(https://github.com/carbon-design-system/ibm-products/blob/main/packages/ibm-products-styles/src/components/SidePanel/_side-panel.scss)/ Material side sheet(https://github.com/material-components/material-components-android/blob/master/docs/components/SideSheet.md)皆「有 close affordance 才有正式 header + divider」;Jira issue view 右欄僅輕量 group heading。
+- ❌ 列表 row / menu item → 走 `item-anatomy`,不是 header
+- ❌ 卡片內標題列 → Card 自己的 header 區,不套本 pattern
+
+**機械防呆**(讓 AI 即使誤判也被擋):手刻 chrome header(`h-[var(--chrome-header-height)] border-b`)→ `_chrome_header_handcraft` 攔;手刻 overlay header(`px-loose + border-b border-divider` 簽名)→ `check_story_invariants.sh R9` BLOCKER。命名前綴(`chrome-` / `overlay`-surface)本身自帶 surface 語意,讀到名字即知用途。
 
 ## 定位
 
@@ -43,22 +64,22 @@ benchmark:
 
 ### 3. Vertical rhythm
 
-- **A 家族**:`py-[var(--layout-space-tight)]`(md=8px / lg=12px)+ `data-unbounded` slot trick → 實際高度對齊 `--chrome-header-height`
+- **A 家族**:`py-[var(--layout-space-tight)]`(md=12px / lg=16px)+ `data-unbounded` slot trick → 實際高度對齊 `--chrome-header-height`
 - **B 家族**:`h-[var(--chrome-header-height)]`(md=48px / lg=56px)+ `items-center`
 
 ### 4. Dismiss icon button(close X)
 
 - **Token**:`<Button iconOnly size="sm" dismiss />`(28px @ md / 32px @ lg)
-- **永遠 size="sm"**(不論家族 / density):chrome / overlay header 內 button 一律 sm
+- **永遠 size="sm"**(不論家族 / density):chrome / overlay header 內 button 一律 sm。**廣化(2026-06-12 user 拍板)**:header 內**所有 field-height 控件**(Button / Input / Select / SegmentedControl / Combobox 等)一律 `sm`,禁混雜不同 field height(Tabs 跟齊 chrome 高度,唯一例外 = 「Tabs 取代整個 header」的 standalone `size="lg"`,見上方表)
 - 對齊 既有 `dialog.tsx:132-153` + `sheet.tsx:122-139` + `popover.tsx:87-110`(Dialog/Sheet/Popover 已內建 close X)
 
-### 4.5 Chrome header avatar SSOT(2026-05-21 codify per user directive)
+### 4.5 Chrome header avatar SSOT(2026-05-21 codify per user directive;2026-06-17 擴涵 account entry)
 
-**Canonical**:Chrome header brand mark avatar = **24px,density-fixed,row-size-fixed**。
+**Canonical**:Chrome header avatar = **24px,density-fixed,row-size-fixed**。涵蓋同一條 chrome header 內**兩種** avatar,皆 24px:**(a) 品牌 mark**(WorkspaceBrand,左)+ **(b) 帳號入口 account entry**(primary-header globalHeader 右側的個人設定 avatar)。同一條 chrome header 內所有 avatar 尺寸一致。
 
-對齊 5 家世界級共識(Linear / Notion / Figma / Slack / Polaris chrome header brand mark 皆固定 24px,不 density-scale 也不 row-size-scale)。設計理由:avatar 是品牌識別 mark,視覺穩定優於 density 緊鬆 / row size 調整(button 跟 density 走 touch target 邏輯,avatar 不該綁同邏輯)。
+對齊 5 家世界級共識(Linear / Notion / Figma / Slack / Polaris chrome header brand mark 皆固定 24px,不 density-scale 也不 row-size-scale;GitHub 20 / Atlassian small 24 / Linear 右上帳號 avatar 同屬此小尺寸區間)。設計理由:chrome header avatar(品牌或帳號)是身份識別 mark,視覺穩定優於 density 緊鬆 / row size 調整;**帳號入口雖可互動,互動感由 focus ring + hover 提供,不靠把 avatar 放大到 field height**(button 跟 density 走 touch target 邏輯,avatar 不綁同邏輯)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
-**Chrome header 不是 row context**:無 sm/md/lg row size lookup 需求 → chrome header 內 avatar 用 **raw `<Avatar size={24}>`**,**不用 `<ItemAvatar>`**(後者是 row primitive anatomy helper,scope 是 row context — 詳 `item-anatomy.spec.md:535` scope 限定段)。
+**Chrome header 不是 row context**:無 sm/md/lg row size lookup 需求 → chrome header 內 avatar 用 **raw `<Avatar size={24}>`**,**不用 `<ItemAvatar>`**(後者是 row primitive anatomy helper,scope 是 row context — 詳 `item-anatomy.spec.md`「Scope 例外:Chrome header 不是 row context」段)。
 
 **程式表達**(local pattern token,對齊 `data-table.css` 既有 local-token 先例):
 - CSS:`--chrome-header-avatar-size: 1.5rem`(`header-canonical.css`)— 供 SidebarHeader 收合對齊公式消費
@@ -67,9 +88,10 @@ benchmark:
 **Consumer rule**:
 - 在 chrome header 內放 avatar → **必用 raw `<Avatar size={24}>`**,**禁用 `<ItemAvatar>`**(會誤啟動 row anatomy lookup)
 - SidebarHeader 收合對齊公式必消費 `var(--chrome-header-avatar-size)`,**禁** hardcode 24
-- WorkspaceBrand demo 即此 pattern 的 reference implementation(`_demo-helpers.tsx:WorkspaceBrand`)
+- WorkspaceBrand demo 即此 pattern 的 reference implementation(`components/AppShell/_demo-helpers.tsx:WorkspaceBrand`)
+- **帳號入口(account entry)同規則**:primary-header globalHeader 右側的個人設定 avatar 也用 raw `<Avatar size={24}>`(reference:`components/AccountMenu/account-menu.tsx`,2026-07-30 F9 升 public 元件;demo wrapper 在 `_demo-helpers.tsx`)。放置 / 開帳號選單 / 邊距對稱 canonical 見 `../../components/AppShell/app-shell.spec.md`「帳號入口(Account entry)放置 SSOT」段。
 
-**Sync invariant**:`--chrome-header-avatar-size` CSS 值 + `<Avatar size={24}>` JS literal + `AVATAR_SIZE.inline.md = 24`(`item-anatomy.tsx:93`)三者必同 24px 值。改 spec canonical 時 grep `--chrome-header-avatar-size` + `chrome header avatar canonical` keyword 找全 sync 點。
+**Sync invariant**:`--chrome-header-avatar-size` CSS 值 + `<Avatar size={24}>` JS literal(WorkspaceBrand `_demo-helpers.tsx` + AccountMenu `components/AccountMenu/account-menu.tsx` 兩處)+ `AVATAR_SIZE.inline.md = 24`(`item-anatomy.tsx:94`,L93 是 `export const AVATAR_SIZE = {` 宣告開頭)必同 24px 值。改 spec canonical 時 grep `--chrome-header-avatar-size` + `chrome header avatar canonical` keyword 找全 sync 點。
 
 ### 5. Title typography
 
@@ -92,7 +114,9 @@ benchmark:
 - `_demo-helpers.tsx:131` PageHeader 自刻 `<header>` + `bg-surface` → migrate 消費 ChromeHeader + 保 `bg-surface`(top-level 合法)
 - `sidebar.stories.tsx:113` Sidebar IconCollapse demo 自刻 header + `bg-surface` → 後續一併 migrate(同 PageHeader 路徑)
 
-**Element canonical**(2026-05-20):ChromeHeader 內部用 `<header>` element(非 `<div>`)。HTML5 spec 允許 sectional content 多次 `<header>`(`role="banner"` 只 page top 一個,sectional 內 default `<header>` 不自動有 banner role)。統一 element contract 消除「何時用 header / 何時用 div」consumer drift。
+### 7. Element contract(實作層,2026-05-20)
+
+ChromeHeader 內部用 `<header>` element(非 `<div>`)。HTML5 spec 允許 sectional content 多次 `<header>`(`role="banner"` 只 page top 一個,sectional 內 default `<header>` 不自動有 banner role)。統一 element contract 消除「何時用 header / 何時用 div」consumer drift。(與規則 6 背景所有權是兩個層級:6 是設計原則,本條是 code contract。)
 
 ---
 
@@ -104,16 +128,16 @@ benchmark:
 
 **規則**:**Header 是 semantic owner**(「這 surface 需要 bottom border 分區」是 header 的概念決定),**Paint owner 隨 state 變**:
 - `withTabs={false}` → header 自畫(`border-b border-divider`)
-- `withTabs={true}` → header **auto-suppress 自己的 paint**,**TabsList 自身的 `border-b border-border` 接管實際 paint**(視覺同一條線)
+- `withTabs={true}` → header **auto-suppress 自己的 paint**,**TabsList 自身的 `border-b border-divider` 接管實際 paint**(視覺同一條線;`TABS_LIST_BASE` tabs.tsx:116 用 `border-divider` neutral-4,同 Dialog/Sheet/Popover/Sidebar header)
 
 **這不是 reject user 直覺**(「border 該由 header 自己畫」)— 而是把「誰負責這條線存在」和「誰實際 paint」拆開。User 直覺 = semantic ownership 正確;DS 實作 = withTabs 時 delegate paint 給 TabsList,因為 tabs selected underline 是「從 1px gray border 長出 2px primary」設計 idiom(`tabs.spec.md:185-187`),paint owner 不在 tabs 會讓 underline 失去 base line。
 
 **世界級對照**:
 - GitHub Primer PageHeader verbatim:「`hasBorder` defaults true,**but border NOT rendered if Navigation child contains UnderlineNav**;UnderlineNav itself provides bottom border」(`primer.style/components/page-header/react`)
 - 我們既有 spec:`tabs.spec.md` 「出現在 Dialog / Sidebar / 任何 header」段「Consumer 把 Tabs 放在 header 區域內、移除 header 自己的 `border-b`,讓 Tabs 接管」
-- 我們既有禁止:`tabs.spec.md:258`「Dialog/Sidebar header 內不得同時有 header `border-b` 和 TabsList `border-b`——會出現雙線」
+- 我們既有禁止:`tabs.spec.md`「禁止事項」段「Dialog / Sidebar header 內不得同時有 header `border-b` 和 TabsList `border-b`——會出現雙線」
 
-**Counter-pattern(reject)**:Material UI 走「container 畫 border + tabs 不畫」(`<Box sx={{ borderBottom: 1 }}><Tabs>...</Tabs></Box>`)— 本 DS reject 此方向,理由:tabs underline 需 base line(MUI 2px indicator 浮空是另一派視覺語言,跨派遷移成本高且既有 spec 已 codify Primer 派)。
+**Counter-pattern(reject)**:Material UI 採 parent-owned separator、Tabs 只負責 active indicator；本 DS 不採此方向。既有契約把 separator 與 active indicator 視為 TabsList 的同一組狀態邊界，改成 parent-owned 會同時更換責任歸屬與既有 consumer contract。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
 ### Rule W2:Tabs 水平 padding 對齊 header(by inheritance,不重複設)
 
@@ -123,15 +147,17 @@ benchmark:
 
 ChromeHeader / SurfaceHeader 新增 `tabsSlot?: ReactNode` prop。提供時自動 **column mode**:
 - Row 1:children(title + close X / actions)— 跟 single-row 模式同 padding,但 border-b 撤掉
-- Row 2:tabsSlot 包在 `<div className="[&>[role=tablist]]:w-full [&>[role=tablist]]:px-[var(--layout-space-loose)]">`(wrapper 本身**不** inset,只用 CSS arbitrary variant 給 TabsList 注入 `w-full` + 內 padding)
-  - **TabsList 全 dialog 寬**(`w-full`)→ 自身 `border-b border-border` 延展全 dialog 寬 = W1 視覺一條線
-  - **TabsList 內 padding-x = px-loose** → triggers 從 px-loose 內邊起,對齊 header content row(W2 alignment 達成)
+- Row 2:tabsSlot 包在 `<div className={HEADER_TABS_SLOT_WRAPPER_CLASS}>`(= `[&_[data-slot=tabs-list]]:px-[var(--layout-space-loose)]`,`chrome-header.tsx` 單一 SSOT const;wrapper 本身**不** inset,只用 CSS arbitrary variant 對契約元素注入內 padding)
+  - **選取契約 = `data-slot="tabs-list"` attribute(v4,2026-07-30)**:`tabs.tsx` 三種 overflow 模式(none / scroll / menu)的 `role=tablist` 元素(TabsPrimitive.List)皆自標 `data-slot="tabs-list"`(對齊 shadcn v4 tabs.tsx `data-slot` idiom,https://github.com/shadcn-ui/ui/blob/main/apps/v4/registry/new-york-v4/ui/tabs.tsx + DS 既有 `data-unbounded` 標記式契約);wrapper 用 descendant selector,不依賴 DOM 深度(beta.86 overlay 包裹層教訓,見下 v1-v4 歷史)
+  - **TabsList 全 dialog 寬 = TabsList 自帶,wrapper 不注入寬度**:none 模式 `w-full`(tabs.tsx 自帶)→ 自身 `border-b border-divider` 延展全 dialog 寬 = W1 視覺一條線;scroll / menu 模式 `min-w-full`(border 隨溢出內容成長;blanket `w-full` 會把 border 截在可視寬 → **禁**由 wrapper 注入寬度)
+  - **TabsList 內 padding-x = px-loose** → triggers 從 px-loose 內邊起,對齊 header content row(W2 alignment 達成;三種 overflow 模式同享)
   - Selected trigger 2px primary 真 overlay TabsList 1px gray border(`tabs.spec.md:187-189` canonical)
 
-**v1/v2 反 pattern**(歷史錨):
+**v1/v2/v3 反 pattern**(歷史錨):
 - v1(2026-05-18 initial):wrapper 加 `border-b border-divider` + TabsList 自身 `border-b border-border` 共存 → 雙線(色不同 + 1px box gap)
 - v2(2026-05-18 mid):wrapper px-loose + TabsList w-full inside → border 只跨 dialog - 2×px-loose(沒到 dialog 邊)
-- v3(本):wrapper 不 inset,TabsList 自己 padding inset triggers + 全 dialog 寬 border ✓
+- v3(2026-05-18):wrapper 不 inset,TabsList 自己 padding inset triggers + 全 dialog 寬 border ✓ — 但選取機制 = `[&>[role=tablist]]` direct-child **結構**選擇器,綁死 tablist 深度
+- v4(本,2026-07-30 regression fix):beta.86 Tabs inlineAction axe 正規修(fc2a3a5c)給 TabsList 包 `<div class="relative">` overlay 層 → v3 direct-child 選擇器全滅、px-loose 靜默消失(W2 regression);且 scroll / menu 模式 tablist 深度本就 >1,v3 從未命中。改 `data-slot="tabs-list"` attribute contract + descendant selector — 顯式契約免疫 DOM 重構,三種 overflow 模式齊套;寬度改由 TabsList 各模式自帶(w-full / min-w-full),wrapper 不再注入 ✓
 
 **W2 spec 註**:原 W2「TabsList 不設左右 padding,繼承 parent header padding」描述假設 ChromeHeader single-row 模式;**column mode 下實作機制改為 CSS arbitrary variant 注入 TabsList 內 padding**(不是 by-inheritance 從 wrapper)。Selected primary overlay full-width gray 共識(GitHub Primer UnderlineNav / Ant Design line type / Mantine default)需要 TabsList 自畫 full-width border。
 
@@ -161,7 +187,7 @@ ChromeHeader / SurfaceHeader 新增 `tabsSlot?: ReactNode` prop。提供時自
 - ❌ 在 TabsContent 上加 padding(會跟 DialogBody canonical px-loose pt-tight pb-bottom 重複)
 - ❌ Backward-compat `withTabs={true}` 無 tabsSlot 場景:header 自己抑制 border-b,但 consumer 需自管 Tabs row layout — 不推薦(除非從 layout template 來)
 
-**Verify**:`scripts/runtime-verify-header-canonical-tabs.mjs` playwright probe W1/W2/W4 pixel-quantified(title vs first tab left Δ ≤ 1px / flush gap ≤ 1px / row 2 border = 1px)。
+**Verify**:write-time 由 `chrome_header_dispatcher.sh` 經 lib helper(`_tab_lg_chrome_header_equal.sh` + `_header_with_tabs_border.sh`,2026-05-31 升 exit 2 BLOCK)把關;pixel-quantified visual probe 走 `/visual-audit --scope=changed`(無專屬 runtime-verify script)。
 
 **Rationale**:對齊 Carbon verbatim「first label should always align to other content in the space」(`carbondesignsystem.com/components/tabs/usage`)。「by inheritance 不重複設」是 GitHub Primer + Material UI 隱含 idiom — tabs container 不主動畫 padding,讓外層 container 統一管。
 
@@ -169,13 +195,13 @@ ChromeHeader / SurfaceHeader 新增 `tabsSlot?: ReactNode` prop。提供時自
 
 | Header family | Tabs size | Rationale |
 |---|---|---|
-| **A. Overlay header(Padding-based)** | `sm`(32/40)| 對齊 Ant verbatim「small size could be used in Modal」;overlay 內 close X 也是 sm 統一 |
+| **A. Overlay header(Padding-based)** | `sm`(32/40)| 對齊 Ant verbatim「small size could be used in Modal」;overlay 內 close X 也是 sm 統一 | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 | **B. Chrome header(Fixed-h)** | `sm`(32/40)| chrome 內 buttons 全部 sm(real grep:`Sidebar / FileViewer toolbar / InfoPanel` 所有 buttons size=sm),tabs 跟齊 |
-| **C. Standalone(tabs 取代 chrome header)** | `lg`(48/56)| Tabs 直接取代 header 用,**tab 高 = chrome-header-height 像素相等**(48/56)— Ant verbatim「Large size tabs are usually used in page header」 |
+| **C. Standalone(tabs 取代 chrome header)** | `lg`(48/56)| Tabs 直接取代 header 用,**tab 高 = chrome-header-height 像素相等**(48/56)— Ant verbatim「Large size tabs are usually used in page header」 | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
-**Token alignment 強連動**:`--tab-height-lg` md=48 / lg=56 與 `--chrome-header-height` md=48 / lg=56 **像素完全相等**(`uiSize.css:36-79` + `globals.css:37-45`)— 這是「lg tabs 取代 chrome header」的 SSOT linkage 鐵證。**禁止任何一方獨自調整**(動 chrome-header-height 必同步 tab-height-lg,反之同)。
+**Token alignment 強連動**:`--tab-height-lg` md=48 / lg=56 與 `--chrome-header-height` md=48 / lg=56 **像素完全相等**(皆定義於 `uiSize.css`:`--chrome-header-height` L55/L103、`--tab-height-lg` 同檔;`globals.css` 僅 21 行 aggregator,不定義此 token)— 這是「lg tabs 取代 chrome header」的 SSOT linkage 鐵證。**禁止任何一方獨自調整**(動 chrome-header-height 必同步 tab-height-lg,反之同)。
 
-**Enforcement = assert,不 CSS alias**(per M31 codex 比稿 Step 5):`uiSize.css` 的 `--tab-height-*` 有 `data-ui-size="md"` reset selector(component-size scope),`--chrome-header-height` 是 layout/density token(app-chrome scope)— alias 會把兩個不同 scope 綁死。**機制**:保留 duplicated literals + Phase 3 hook `check_tab_lg_chrome_header_equal.sh` parse 兩 CSS file 提取 md/lg 值 assert equality → 任一方獨自改 = BLOCKER。
+**Enforcement = assert,不 CSS alias**(per M31 codex 比稿 Step 5):`uiSize.css` 的 `--tab-height-*` 有 `data-ui-size="md"` reset selector(component-size scope),`--chrome-header-height` 是 layout/density token(app-chrome scope)— alias 會把兩個不同 scope 綁死。**機制**:保留 duplicated literals + `chrome_header_dispatcher.sh` → `lib/_tab_lg_chrome_header_equal.sh`(2026-05-31 升 exit 2 BLOCK)parse CSS 提取 md/lg 值 assert equality → 任一方獨自改 = BLOCKER。
 
 ### Rule W4:Tabs row 與 header content row 為 flush stack(無 negative margin)
 
@@ -192,15 +218,17 @@ ChromeHeader / SurfaceHeader 新增 `tabsSlot?: ReactNode` prop。提供時自
 **Rationale**:
 - Header 內 tabs 對應 button-sm → tabs sm(W3 已 cover)
 - 獨立 chrome-replacement tabs → tabs lg(W3 已 cover)
-- 中間階梯(md=40)無清楚場景 — 多家世界級 DS(Material / MUI / Primer / Polaris)只有 1 個 default size(無 sm/md/lg 階梯)= sweet spot 只需 2 tier
+- 中間階梯(md=40)無清楚場景 — 多家世界級 DS(Material / MUI / Primer / Polaris)只有 1 個 default size(無 sm/md/lg 階梯)= sweet spot 只需 2 tier <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
 **Conservative path**:token 不刪(避免 breaking change 與 stories 維護成本);spec 明寫 future tier。
 
-### Rule W6:Default tabs size 為 sm(Phase 2 visual audit gate,不 P0)
+### Rule W6:Default tabs size 為 sm(已 land)
+
+**規則**:Tabs `cva defaultVariants.size = 'sm'` — **已 land**(`tabs.tsx:135` TabsList param `size = 'sm'` + `:394` trigger cva `defaultVariants.size = 'sm'`,inline comment「2026-05-17 從 'md' 改 'sm'」)。
 
-**規則**:Tabs `cva defaultVariants.size = 'sm'`(本 SSOT 提議目標 default;**Phase 2 production code 改動,經 visual audit 過 baseline diff 才 land**)。
+**邊界 — tabs 超寬溢出**:header 內 TabsList 溢出處理走 `components/Tabs/tabs.spec.md`「Overflow 模式」(`TabsList` `overflow` prop:none / scroll / menu),非本 SSOT scope。
 
-**Rationale**:既有 default = `md`(`tabs.tsx:127` TabsList + `:377` trigger cva,grep production consumer = 0 個 `<Tabs>` 在非 stories code)。Production blast radius 低 — 但 stories / anatomy demo 大量縮高 → 必過 visual baseline diff 再 land。**禁直接 P0 改 production**;Phase 2 排序:(1) 改 cva default → (2) 跑 `npm run build-storybook` → (3) Playwright baseline diff → (4) update stories labels → (5) merge。
+**Rationale**:overlay / chrome / dense toolbar 用 sm(tab 高 32/40)對齊 Ant「small size could be used in Modal」。production consumer 主要在 stories;cva default 改 sm 已過 visual baseline diff merge。
 
 ---
 
@@ -208,11 +236,11 @@ ChromeHeader / SurfaceHeader 新增 `tabsSlot?: ReactNode` prop。提供時自
 
 ### Layer 1 — Token shared
 
-兩家族 consume 同組 CSS variable(機械對齊):
-- `--chrome-header-height`(globals.css:37,45)
-- `--layout-space-loose` / `--layout-space-tight`
-- `--divider-color`
-- `--tab-height-sm` / `--tab-height-lg`(uiSize.css:36-38,58-60)
+兩家族連動 token 清單(各 token 標注實際消費者;非全部兩家族交集):
+- `--chrome-header-height`(uiSize.css:55,103)— B 家族 tsx 直接消費(chrome-header.tsx);A 家族不直接消費,靠 padding 算式對齊(24 + 2×tight = 48;等式由 overlay-surface.tsx anatomy 註解 + `lib/_tab_lg_chrome_header_equal.sh` W3 assert 守)
+- `--layout-space-loose`(兩家族 px)/ `--layout-space-tight`(僅 A 家族 py;B 家族 fixed-height 無 py)
+- `--divider`(semantic.css:333;兩家族經 `border-divider` utility 消費)
+- `--tab-height-sm` / `--tab-height-lg`(uiSize.css:41-43 md default + 99-101 lg-density override)
 - `--field-height-sm`(button sm 透過 button family 連動)
 
 ### Layer 2 — Spec pointer
@@ -225,7 +253,7 @@ ChromeHeader / SurfaceHeader 新增 `tabsSlot?: ReactNode` prop。提供時自
 - `components/Popover/popover.spec.md`
 - `tokens/uiSize/uiSize.spec.md`「消費 --chrome-header-height」段
 
-### Layer 3 — Primitive consumption(Phase 2,等 user 拍板)
+### Layer 3 — Primitive consumption(已 land;下列為原 Phase 2 提案內容,現況見段末)
 
 - A 家族:`SurfaceHeader` 已是 primitive(`overlay-surface.tsx:62-118`)— add `withTabs?: boolean` prop auto-suppress border
 - B 家族:**新建 `ChromeHeader` primitive**(`patterns/header-canonical/chrome-header.tsx`)— Sidebar / FileViewer / InfoPanel 全 migrate
@@ -235,36 +263,51 @@ ChromeHeader / SurfaceHeader 新增 `tabsSlot?: ReactNode` prop。提供時自
 <ChromeHeader
   withTabs?: boolean              // false (default) | true → auto-suppress border + delegate to TabsList
   tabsSlot?: ReactNode            // Tabs row(column mode + W1-W6 lockstep,2026-05-18 ship)
-  lockDensity?: 'inherit' | 'lg'  // 'inherit' (default) | 'lg' → 強制 chrome-header-height lg=56(viewer 等 fullscreen chrome)
+  lockDensity?: 'inherit' | 'lg'  // 'inherit' (default)。'lg' = 在 header 上設 data-density=lg;⚠️ 2026-06-15:density lock 應設在 surface 根而非 header(header 鎖、body 沒鎖 → 左緣不對齊,FileViewer 圖二教訓)→ 現無 consumer 使用,保留僅為 API 相容。見 density.spec.md 消費者清單 + anti-pattern
   leadingRail?: ReactNode         // 2026-05-21 ship per AppShell primary-header globalHeader:固定 width=sidebar-width-icon 的左 rail,內 justify-center 排列(toggle/logo 跟 sidebar 收合 icon center x 對齊)。對齊 GitHub global nav 左 logo 區 / Slack thin workspace rail 慣例。
 >
   {children}
 </ChromeHeader>
 ```
 
-**不開**:`density?: 'md'|'lg'` 自由 prop(M21 違反 — 任意 density 等於 cva-on-pattern,該由 density context 決定)。`lockDensity="lg"` 是 escape hatch 給 fullscreen viewer chrome(FileViewer 永遠 lg-equivalent design intent),其餘 consumer 走 `inherit`(跟 page density)。**Grep evidence**(production 重複 contract,非 premature abstraction):`sidebar.tsx:433` + `file-viewer.tsx:333,459` 全是 `flex items-center gap-2 shrink-0 h-[var(--chrome-header-height)] border-b border-divider px-[var(--layout-space-loose)]` 一模一樣手刻 → 過 M21 prop variant test 3 條(`<Sidebar>` 等近親 grep / 3 家世界級 page-header primitive / value 結構不同)。
+**不開**:`density?: 'md'|'lg'` 自由 prop(M21 違反 — 任意 density 等於 cva-on-pattern,該由 density context 決定)。`lockDensity="lg"` 原為 fullscreen viewer escape hatch,但 **2026-06-15 起無 consumer 使用**；FileViewer 已改為全 surface 繼承 page density。density lock 一律設在 **surface 根**而非 header primitive(見 `density.spec.md` anti-pattern)，其餘 consumer 走 `inherit`。`ChromeHeader` 的抽取依據是 Sidebar 與 FileViewer 曾重複擁有同一份 header contract；目前兩者皆直接消費此 primitive，實作位置見 `sidebar.tsx` / `file-viewer.tsx`，歷史 signature 留在 git history 而非 spec。
+
+### 空 children / action state 契約(rendering contract)
+
+**空 children**:`ChromeHeaderProps extends React.HTMLAttributes<HTMLElement>`,故 `children` 型別上 optional;但**實作恆渲染固定高度 row**(single-row `h-[var(--chrome-header-height)]` + `border-b`,`chrome-header.tsx:167-183`;`tabsSlot` 模式 row 1 亦恆渲染,`:113-122`)。因此:
+
+- **沒有 title / actions 時不要渲染 ChromeHeader**——空 children 只會留一條固定高度 + border 的空白 chrome row(`tabsSlot` 模式更明顯:tabs 上方多整行空白標題列)。consumer 條件渲染,有內容才掛 header,而非傳空殼。
+- **只有 tabs、無獨立標題列**的場景 → 用 standalone `<Tabs size="lg">`(tab 高 = chrome-header-height,見「選哪個 header」表 C 列),**不要**空 children + `tabsSlot` 硬撐。
+
+**Action loading / disabled 歸屬**:ChromeHeader 只負責 slot 排版,**不擁有**注入 action 的非同步狀態。header 內 Button / 控件的 `loading` / `disabled` 由 consumer 注入的元件自帶(如 `<Button loading>` 自畫 spinner),ChromeHeader 層**無** loading / disabled prop。故本 primitive 的 **Loading 驗證 = N/A**(排版 primitive,無自身 async state)。
 
 ### Layer 4 — Hook mechanical
 
-- `check_header_with_tabs_border.sh` — grep tsx 若 header 元件含 `<Tabs>` child 但未走 `withTabs` API → BLOCKER
-- `check_chrome_header_handcraft.sh` — grep 是否仍有 hardcoded `h-[var(--chrome-header-height)] border-b` 自刻 chrome header(該消費 ChromeHeader primitive)
+`chrome_header_dispatcher.sh` 依序 dispatch **4 個 lib helper**(完整清單 SSOT = dispatcher 本身,避免 spec drift):
+
+- `lib/_app_shell_primary_header_consistency.sh`(2026-05-31 exit 2 BLOCK)— primary-header layout 必傳 `globalHeader` prop,缺則 BLOCKER
+- `lib/_header_with_tabs_border.sh`(2026-05-31 exit 2 BLOCK)— grep tsx 若 header 元件含 `<Tabs>` child 但未走 `withTabs` API → BLOCKER
+- `lib/_tab_lg_chrome_header_equal.sh`(2026-05-31 exit 2 BLOCK,W3 pointer)— parse `uiSize.css` assert `--tab-height-lg` 像素等於 `--chrome-header-height`,任一方獨自改 → BLOCKER
+- `lib/_chrome_header_handcraft.sh`(WARN,Phase 3 才升 P0)— grep 是否仍有 hardcoded `h-[var(--chrome-header-height)] border-b` 自刻 chrome header(該消費 ChromeHeader primitive)
+- （以上皆 lib helper,經 `chrome_header_dispatcher.sh` 統一 dispatch;無 standalone `check_*.sh` 檔。前 3 個 SSOT-canonical deterministic helper exit 2 傳播真 block;`_chrome_header_handcraft` 維持 warn）
 
 ---
 
 ## 禁止事項
 
 - ❌ Header 內同時有 header `border-b` 和 TabsList `border-b`(雙線)— per W1
-- ❌ Tabs underline 用 `border-b-2` 在 trigger 上實作(雙線)— per `tabs.spec.md:246`
+- ❌ Tabs underline 用 `border-b-2` 在 trigger 上實作(雙線)— per `tabs.spec.md`「禁止事項」段(trigger 禁 `border-b-2`)
 - ❌ Negative margin 接 header 與 tabs row(脆弱 chain)— per W4
 - ❌ Hardcode `h-16` / `h-14` / `h-12` 自寫 chrome header 高度 — 必 `--chrome-header-height`
 - ❌ Header 內 close X 用 `size="md"` 或 `size="lg"`(real grep 100% sm)
-- ❌ Tabs default 寫 `size="md"`(W5 + W6)— 等 Phase 2 改 cva default = sm
+- ❌ Tabs default 覆寫回 `size="md"`(W5 + W6)— cva default 已是 sm,不該寫回 md
+- ❌ ChromeHeader children 塞 `flex-col` 第二行(title + 副標/description)— Chrome 家族永遠 single-row(上方「為什麼兩家族」段);頁面說明文字歸 content 區 page heading,非 chrome(2026-06-12 fork-drift 防線,同 sidebar.spec.md SidebarHeader 必單行條;registry antiPattern `chromeheader-subtitle-second-line` 機械攔)
 
 ---
 
 ## A11y 預設
 
-- Header 用 `<header>` semantic element(SR landmark)
+- Header 用 `<header>` semantic element;**僅 page-top top-level chrome header** 暴露 `role="banner"` landmark。nested 在 sectioning content(`<aside>` / `<section>` / overlay)內的 `<header>` 對 SR **不暴露 banner role**(per WAI-ARIA APG + MDN:`<header>` 只在最近 sectioning ancestor 為 `<body>` 時才是 banner)。ChromeHeader 是 layout primitive,**不硬塞 banner role**(與「7. Element contract」段一致)
 - Tabs 走 Radix Tabs(原生 `role="tablist" / role="tab" / aria-selected`)
 - Dismiss button `aria-label="關閉"`(close X)
 - 鍵盤:Tabs 左右方向鍵切換(Radix);Esc 觸發 dismiss(overlay 家族)
@@ -282,4 +325,15 @@ ChromeHeader / SurfaceHeader 新增 `tabsSlot?: ReactNode` prop。提供時自
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `account-menu.spec.md`
 - `app-shell.spec.md`
+- `density.spec.md`
+- `dialog.spec.md`
+- `file-viewer.spec.md`
+- `item-anatomy.spec.md`
+- `overlay-surface.spec.md`
+- `popover.spec.md`
+- `sheet.spec.md`
+- `sidebar.spec.md`
+- `tabs.spec.md`
+- `uiSize.spec.md`

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

@@ -0,0 +1,257 @@
+// @anatomy-exempt: Header Anatomy pattern story — 涵蓋 2 家族:B chrome(ChromeHeader,single-row / withTabs)+ A overlay(SurfaceHeader)。
+// （leadingRail slot 因專搭 sidebar,canonical demo 在 AppShell primary-header,不在此孤立展示。）
+// 內部 title 用 flex 排列是 header content 結構,非 list row,不走 item-anatomy MenuItem。
+//
+// 公開 Pattern anatomy 參照(對標 patterns/element-anatomy/item-anatomy.stories.tsx)。
+// 目的:做 header 相關元件時,人 / AI 看這支 story + header-canonical.spec.md 就知道 header 該怎麼結構,
+// 並直接消費 <ChromeHeader> primitive(或在 AppShell header slot 傳它)滿足需求。
+import type { Meta } from '@storybook/react'
+import type { ReactNode } from 'react'
+import {
+  FileText,
+  ZoomIn,
+  Download,
+  X,
+} from 'lucide-react'
+import { ChromeHeader } from '@/design-system/patterns/header-canonical/chrome-header'
+import { SurfaceHeader } from '@/design-system/patterns/overlay-surface/overlay-surface'
+import { Button } from '@/design-system/components/Button/button'
+import { Separator } from '@/design-system/components/Separator/separator'
+import {
+  Tabs,
+  TabsList,
+  TabsTrigger,
+  TabsContent,
+} from '@/design-system/components/Tabs/tabs'
+
+const meta: Meta = {
+  title: 'Design System/Patterns/Header Anatomy',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { description: { component: '頁面與浮層標頭的組合規則，統一標題、操作、分頁與導覽槽位。建立 AppShell、Dialog 或 Sheet 標頭時，用這裡的結構選型，避免各自手刻 chrome。' } },
+  },
+}
+export default meta
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Header Anatomy — 跨元件 chrome header 的結構契約(header-canonical.spec.md SSOT)
+
+   ChromeHeader 封裝的共同契約(所有型共享):
+   • 高度 = var(--chrome-header-height)(md 48 / lg 56),items-center 垂直置中
+   • 左右 padding = var(--layout-space-loose)(md 16 / lg 24),所有 slot 統一靠齊
+   • border-b border-divider(有 tabs 時自動移除,改由 TabsList 畫線)
+   • dismiss(close X)永遠 <Button iconOnly dismiss size="sm">,不論 density
+
+   consumer:Sidebar header / FileViewer Toolbar+InfoPanel / AppShell header slot / 未來 Drawer
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+/** 容器:把 header 放進一個有邊界的面板裡看(模擬實際 chrome 嵌在 surface 上)*/
+function Panel({ children }: { children: ReactNode }) {
+  return (
+    <div className="overflow-hidden rounded-md border border-divider bg-surface">
+      {children}
+    </div>
+  )
+}
+
+/** 1. Single-row — 最常見:標題 + 動作列(對標 FileViewer Toolbar / Sidebar header)*/
+export const SingleRow = () => (
+  <Panel>
+    <ChromeHeader>
+      <div className="flex min-w-0 flex-1 items-center gap-2">
+        <FileText size={16} className="shrink-0 text-foreground" aria-hidden />
+        <span className="truncate text-body-lg text-foreground" title="2026 Q1 財務報告.pdf">
+          2026 Q1 財務報告.pdf
+        </span>
+      </div>
+      {/* 右側按鈕 = children + flex(title flex-1 推開);排列遵循 action-bar:
+          動作群(放大/下載)── Separator ── dismiss(關閉)分群,buttons 全 size="sm"(chrome header canonical)*/}
+      <Button iconOnly variant="text" size="sm" startIcon={ZoomIn} aria-label="放大" />
+      <Button iconOnly variant="text" size="sm" startIcon={Download} aria-label="下載" />
+      <Separator orientation="vertical" className="h-6 mx-1" />
+      <Button iconOnly dismiss size="sm" startIcon={X} aria-label="關閉" />
+    </ChromeHeader>
+    <div className="flex flex-col gap-2 p-6 text-body text-fg-secondary">
+      <p className="text-caption text-fg-muted">陳雅婷 更新於 2026/04/18 · 12 頁 · 2.4 MB</p>
+      <p>本季合併營收 NT$4.82 億,較上季成長 8.2%;毛利率維持 41%。附錄含各區域損益與現金流量表。</p>
+    </div>
+  </Panel>
+)
+SingleRow.storyName = '單列(標題 + 動作列)'
+
+/** 2. withTabs — header 含分頁列(對標 FileViewer InfoPanel / 設定頁 header)。
+ *  傳 tabsSlot 自動進 column 結構:row1 = 標題列、row2 = TabsList 全寬畫線。 */
+export const WithTabs = () => (
+  <Panel>
+    <Tabs defaultValue="overview">
+      <ChromeHeader
+        tabsSlot={
+          <TabsList>
+            <TabsTrigger value="overview">概覽</TabsTrigger>
+            <TabsTrigger value="activity">活動</TabsTrigger>
+            <TabsTrigger value="files">檔案</TabsTrigger>
+          </TabsList>
+        }
+      >
+        <h2 className="flex-1 truncate text-body-lg font-medium text-foreground">
+          Acme 品牌改版專案
+        </h2>
+        <Button iconOnly dismiss size="sm" startIcon={X} aria-label="關閉" />
+      </ChromeHeader>
+      <TabsContent value="overview">
+        <div className="flex flex-col gap-1 p-6 text-body text-fg-secondary">
+          <p>負責人:林思妤 · 期程:2026/03–2026/06 · 狀態:設計中</p>
+          <p>將既有品牌識別全面翻新——logo、配色與元件庫,預計 Q2 上線。</p>
+        </div>
+      </TabsContent>
+      <TabsContent value="activity">
+        <div className="flex flex-col gap-1 p-6 text-body text-fg-secondary">
+          <p>陳柏宇 上傳了「新版 logo 提案 v3」· 2 小時前</p>
+          <p>林思妤 將狀態改為「設計中」· 昨天</p>
+          <p>Aisha Khan 留言:配色再往暖色調微調 · 3 天前</p>
+        </div>
+      </TabsContent>
+      <TabsContent value="files">
+        <div className="flex flex-col gap-1 p-6 text-body text-fg-secondary">
+          <p>品牌識別規範_v3.pdf · 8.1 MB</p>
+          <p>logo 原始檔.ai · 24 MB</p>
+          <p>配色對照表.xlsx · 320 KB</p>
+        </div>
+      </TabsContent>
+    </Tabs>
+  </Panel>
+)
+WithTabs.storyName = '含分頁列'
+
+/* 3-4. withTabs × overflow(scroll / menu)— header 分頁列在窄容器的溢出模式。
+   對標 Jira 專案設定頁:細分頁多到單行放不下(概覽/待辦清單/衝刺/看板/報表/版本/元件/權限/通知)。
+   Panel 限寬 420px + 9 個分頁強制觸發溢出;W2 契約(triggers 內縮 px-loose 對齊 header
+   content row)三種 overflow 模式同享,border 隨溢出內容延展(min-w-full,header-canonical.spec.md Rule W2)。
+   兩則共用同組分頁資料(同 tabs.stories.tsx OverflowScroll/OverflowMenu 精神),各教一種溢出機制。 */
+const projectSettingsTabs = [
+  { value: 'overview', label: '概覽', content: '負責人:張惟安 · 分類:客戶關係 · Scrum 流程已啟用' },
+  { value: 'backlog', label: '待辦清單', content: 'Backlog 42 項:預設排序 = 優先級,顯示 story point 欄位' },
+  { value: 'sprints', label: '衝刺', content: 'Sprint 18 進行中(04/14–04/28),完成 21 / 34 點' },
+  { value: 'board', label: '看板', content: '欄位:待處理 / 進行中 / 審查中 / 完成;WIP 上限 5' },
+  { value: 'reports', label: '報表', content: '燃盡圖 / 速度圖 / 累積流量圖,每週一自動寄送摘要' },
+  { value: 'releases', label: '版本', content: 'v2.4.0 規劃中(05/30 發布)· v2.3.1 已發布' },
+  { value: 'components', label: '元件', content: '前端 / API / 資料庫 / 通知服務,各自指派預設負責人' },
+  { value: 'permissions', label: '權限', content: '管理員 3 人 · 成員 24 人;訪客僅能檢視看板' },
+  { value: 'notifications', label: '通知', content: '議題指派與提及即時通知;摘要每日 09:00 寄送' },
+] as const
+
+/** 3. withTabs + overflow="scroll" — 窄 header 的分頁列單行橫向捲動(fade mask + 左右 arrow)。 */
+export const WithTabsOverflowScroll = () => (
+  <div className="w-[420px]">
+    <Panel>
+      <Tabs defaultValue="overview">
+        <ChromeHeader
+          tabsSlot={
+            <TabsList overflow="scroll">
+              {projectSettingsTabs.map((t) => (
+                <TabsTrigger key={t.value} value={t.value}>{t.label}</TabsTrigger>
+              ))}
+            </TabsList>
+          }
+        >
+          <h2 className="flex-1 truncate text-body-lg font-medium text-foreground">
+            CRM 平台 — 專案設定
+          </h2>
+          <Button iconOnly dismiss size="sm" startIcon={X} aria-label="關閉" />
+        </ChromeHeader>
+        {projectSettingsTabs.map((t) => (
+          <TabsContent key={t.value} value={t.value}>
+            <div className="p-6 text-body text-fg-secondary">{t.content}</div>
+          </TabsContent>
+        ))}
+      </Tabs>
+    </Panel>
+  </div>
+)
+WithTabsOverflowScroll.storyName = '含分頁列 — 溢出水平捲動'
+
+/** 4. withTabs + overflow="menu" — 窄 header 的分頁列 + 右側 ⌄ 導覽選單(show-all navigator)。 */
+export const WithTabsOverflowMenu = () => (
+  <div className="w-[420px]">
+    <Panel>
+      <Tabs defaultValue="overview">
+        <ChromeHeader
+          tabsSlot={
+            <TabsList overflow="menu">
+              {projectSettingsTabs.map((t) => (
+                <TabsTrigger key={t.value} value={t.value}>{t.label}</TabsTrigger>
+              ))}
+            </TabsList>
+          }
+        >
+          <h2 className="flex-1 truncate text-body-lg font-medium text-foreground">
+            CRM 平台 — 專案設定
+          </h2>
+          <Button iconOnly dismiss size="sm" startIcon={X} aria-label="關閉" />
+        </ChromeHeader>
+        {projectSettingsTabs.map((t) => (
+          <TabsContent key={t.value} value={t.value}>
+            <div className="p-6 text-body text-fg-secondary">{t.content}</div>
+          </TabsContent>
+        ))}
+      </Tabs>
+    </Panel>
+  </div>
+)
+WithTabsOverflowMenu.storyName = '含分頁列 — 溢出 ⌄ 導覽選單'
+
+/** Overview — header anatomy 兩型疊起來一次看完,每型上方標清「何時用 + 對標既有元件」。
+ *  注:ChromeHeader 另有 `leadingRail` slot,但它專為「跟 sidebar 收合 icon 對齊」而生(寬 = sidebar 收合寬),
+ *  只在有 sidebar 時有意義 → canonical demo 放 AppShell primary-header(leadingRail = <SidebarTrigger />),
+ *  不在此 generic header anatomy 孤立展示(2026-06-08 per user:孤立 demo 會誤導成通用 slot,且 icon 易被亂換)。*/
+export const Overview = () => (
+  <div className="flex flex-col gap-8">
+    <section className="flex flex-col gap-2">
+      <div className="text-body font-medium text-foreground">Single-row(標題 + 動作列)</div>
+      <div className="text-body-sm text-fg-secondary">
+        最常見的 chrome header。對標 FileViewer Toolbar / Sidebar header。border-b 自畫、px-loose、dismiss size=sm。
+      </div>
+      <SingleRow />
+    </section>
+    <section className="flex flex-col gap-2">
+      <div className="text-body font-medium text-foreground">withTabs(標題列 + 分頁列)</div>
+      <div className="text-body-sm text-fg-secondary">
+        header 內含分頁。對標 FileViewer InfoPanel。傳 tabsSlot,border 改由 TabsList 全寬畫一條線。
+      </div>
+      <WithTabs />
+    </section>
+    <section className="flex flex-col gap-2">
+      <div className="text-body font-medium text-foreground">A 家族 overlay(SurfaceHeader)— 浮層標題列</div>
+      <div className="text-body-sm text-fg-secondary">
+        Dialog / Sheet / Popover / Coachmark 的頂部標題列。高度 padding-based(由內容撐、對齊 chrome-header-height),跟
+        chrome 家族共用同一組契約:border-b、px-loose、dismiss size=sm、tabs 連動。consumer 多用 DialogHeader /
+        SheetHeader / PopoverHeader wrapper,此處用底層 SurfaceHeader 展示 anatomy。
+      </div>
+      <div className="overflow-hidden rounded-md border border-divider bg-surface-raised shadow-[var(--elevation-200)]">
+        <SurfaceHeader>
+          <h2 className="flex-1 truncate text-body-lg font-medium text-foreground">編輯專案設定</h2>
+          <Button iconOnly dismiss size="sm" startIcon={X} aria-label="關閉" />
+        </SurfaceHeader>
+        <div className="flex flex-col gap-3 p-6 text-body text-fg-secondary">
+          <div className="flex flex-col gap-0.5">
+            <span className="text-caption text-fg-muted">專案名稱</span>
+            <span className="text-foreground">Acme 品牌改版專案</span>
+          </div>
+          <div className="flex flex-col gap-0.5">
+            <span className="text-caption text-fg-muted">可見範圍</span>
+            <span className="text-foreground">團隊成員(12 人)</span>
+          </div>
+        </div>
+      </div>
+    </section>
+    <section className="flex flex-col gap-2">
+      <div className="text-body font-medium text-foreground">leadingRail — 見 AppShell（非此處）</div>
+      <div className="text-body-sm text-fg-secondary">
+        ChromeHeader 另有 leadingRail slot(寬 = sidebar 收合寬,專為跟 sidebar 收合 icon 對齊)。因它只在「有
+        sidebar」時有意義,canonical demo 放在 AppShell primary-header（leadingRail = SidebarTrigger）,不在此孤立展示。
+      </div>
+    </section>
+  </div>
+)
+Overview.storyName = '總覽'

package/src/patterns/header-canonical/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 './chrome-header'