@qijenchen/design-system 0.1.0-beta.61 → 0.1.0-beta.63

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

@@ -63,7 +63,7 @@ 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)
@@ -76,9 +76,9 @@ benchmark:
 
 **Canonical**:Chrome header brand mark avatar = **24px,density-fixed,row-size-fixed**。
 
-對齊 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)。設計理由:avatar 是品牌識別 mark,視覺穩定優於 density 緊鬆 / row size 調整(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 收合對齊公式消費
@@ -112,7 +112,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。)
 
 ---
 
@@ -131,9 +133,9 @@ benchmark:
 **世界級對照**:
 - 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 走「container 畫 border + tabs 不畫」(`<Box sx={{ borderBottom: 1 }}><Tabs>...</Tabs></Box>`)— 本 DS reject 此方向,理由:tabs underline 需 base line(MUI 2px indicator 浮空是另一派視覺語言,跨派遷移成本高且既有 spec 已 codify Primer 派)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
 ### Rule W2:Tabs 水平 padding 對齊 header(by inheritance,不重複設)
 
@@ -189,9 +191,9 @@ 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`:`--chrome-header-height` L50/L98、`--tab-height-lg` 同檔;`globals.css` 僅 21 行 aggregator,不定義此 token)— 這是「lg tabs 取代 chrome header」的 SSOT linkage 鐵證。**禁止任何一方獨自調整**(動 chrome-header-height 必同步 tab-height-lg,反之同)。
 
@@ -212,7 +214,7 @@ 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。
 
@@ -220,6 +222,8 @@ ChromeHeader / SurfaceHeader 新增 `tabsSlot?: ReactNode` prop。提供時自
 
 **規則**: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 超寬溢出**:header 內 TabsList 溢出處理走 `components/Tabs/tabs.spec.md`「Overflow 模式」(`TabsList` `overflow` prop:none / scroll / menu),非本 SSOT scope。
+
 **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。
 
 ---
@@ -279,7 +283,7 @@ ChromeHeader / SurfaceHeader 新增 `tabsSlot?: ReactNode` prop。提供時自
 ## 禁止事項
 
 - ❌ 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)
@@ -289,7 +293,7 @@ ChromeHeader / SurfaceHeader 新增 `tabsSlot?: ReactNode` prop。提供時自
 
 ## A11y 預設
 
-- 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**(與 L96 Element canonical 一致)
+- 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 家族)
@@ -308,3 +312,12 @@ ChromeHeader / SurfaceHeader 新增 `tabsSlot?: ReactNode` prop。提供時自
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `app-shell.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

@@ -68,7 +68,7 @@ export const SingleRow = () => (
       <Separator orientation="vertical" className="h-6 mx-1" />
       <Button iconOnly dismiss size="sm" startIcon={X} aria-label="關閉" />
     </ChromeHeader>
-    <div className="p-6 text-body text-fg-muted">文件預覽內容區…</div>
+    <div className="p-6 text-body text-fg-secondary">文件預覽內容區…</div>
   </Panel>
 )
 
@@ -92,13 +92,13 @@ export const WithTabs = () => (
         <Button iconOnly dismiss size="sm" startIcon={X} aria-label="關閉" />
       </ChromeHeader>
       <TabsContent value="overview">
-        <div className="p-6 text-body text-fg-muted">「概覽」分頁內容…</div>
+        <div className="p-6 text-body text-fg-secondary">「概覽」分頁內容…</div>
       </TabsContent>
       <TabsContent value="activity">
-        <div className="p-6 text-body text-fg-muted">「活動」分頁內容…</div>
+        <div className="p-6 text-body text-fg-secondary">「活動」分頁內容…</div>
       </TabsContent>
       <TabsContent value="files">
-        <div className="p-6 text-body text-fg-muted">「檔案」分頁內容…</div>
+        <div className="p-6 text-body text-fg-secondary">「檔案」分頁內容…</div>
       </TabsContent>
     </Tabs>
   </Panel>
@@ -112,21 +112,21 @@ 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-muted">
+      <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-muted">
+      <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-muted">
+      <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。
@@ -136,12 +136,12 @@ export const Overview = () => (
           <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="p-6 text-body text-fg-muted">浮層內容區…(Dialog / Sheet / Popover body)</div>
+        <div className="p-6 text-body text-fg-secondary">浮層內容區…(Dialog / Sheet / Popover body)</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-muted">
+      <div className="text-body-sm text-fg-secondary">
         ChromeHeader 另有 leadingRail slot(寬 = sidebar 收合寬,專為跟 sidebar 收合 icon 對齊)。因它只在「有
         sidebar」時有意義,canonical demo 放在 AppShell primary-header（leadingRail = SidebarTrigger）,不在此孤立展示。
       </div>

package/src/patterns/horizontal-overflow/horizontal-overflow.spec.md

@@ -22,7 +22,7 @@ scope: utility primitives module (use-overflow-items hooks: useScrollEdges + use
 
 `ScrollArrow` 元件在 `Tabs/tabs.tsx` 和 `Chip/chip.tsx` **逐行 copy-paste**,`buildFadeMask` / `ARROW_BUTTON_WIDTH` / `SCROLL_PAGE_RATIO` 常數也是複製的。任何修改都要手動改兩處,是漂移溫床——實際上已經造成了一個 bug:
 
-**Chip 的 menu trigger 曾用 chip variant 的視覺語言(與可選 chip 同形狀),讓 menu trigger 與可選 chip 在 mental model 上無法區分——使用者預期點擊是選中,實際是打開選單。同期 Tabs 的 menu trigger 用 text button 正確表達「這是 overflow 工具」,兩個元件 overflow affordance 自相矛盾。**
+**Chip 的 menu trigger 曾漂移成可選 chip 的視覺語言,使用者無法區分「點擊 = 選中」與「點擊 = 打開選單」;同期 Tabs 正確用 text button 表達工具層——同一個 overflow affordance 在兩元件自相矛盾。**
 
 ### Canonical 規則
 
@@ -30,12 +30,21 @@ scope: utility primitives module (use-overflow-items hooks: useScrollEdges + use
 
 - 左右 scroll arrow → text button,ChevronLeft / ChevronRight
 - Menu trigger → text button,ChevronDown
-- **禁止**用 item 自身的視覺語言(chip 形狀、tab 底線等)來渲染 overflow trigger——overflow affordance 是「工具層」,不是「業務層」,不該跟內容爭視覺重量(對齊 `CLAUDE.md` 的「工具層必須是視覺重量最低的一層」原則)。
+- **禁止**用 item 自身的視覺語言(chip 形狀、tab 底線等)來渲染 overflow trigger——overflow affordance 是「工具層」,不是「業務層」,不該跟內容爭視覺重量(「工具層必須是視覺重量最低的一層」— 本 spec codify 此原則,owner SSOT 在此)。
 
 這條規則讓使用者看到向下 chevron 或向右 arrow 時,心智是一致的:「這是 overflow 的工具,不是可選內容」,不論這排 items 是什麼類型。
 
 ---
 
+## 何時用 / 近親分界 / 常見誤解 / A11y
+
+- **何時用**:任何「一排水平 items 可能塞不下容器」的 DS 元件要加 overflow affordance 時 import 本 module。scroll vs menu 模式的抉擇 SSOT 在 `tabs.spec.md`「Overflow 模式」表(none / scroll / menu 三策略 + 何時用),此處不重複
+- **何時不用 / 近親分界**:設計上拒絕 overflow 的元件不消費——SegmentedControl / Steps(見「消費者清單 Non-consumers」,各自 spec 明文)
+- **常見誤解**:「在新元件自刻 ScrollArrow / fade mask 比較快」——禁止(見「禁止事項」),copy-paste 漂移正是本 module 存在的歷史教訓
+- **A11y**:arrow / trigger 內建 `aria-label`(arrow 預設繁中、trigger 必填)+ iconOnly Button 自動 tooltip(見「元件保證行為」);menu 開啟後的 a11y 由消費者的 DropdownMenu(Radix)承擔
+
+---
+
 ## 提供的 primitive
 
 ### 常數
@@ -49,7 +58,7 @@ scope: utility primitives module (use-overflow-items hooks: useScrollEdges + use
 ### Helpers
 
 - `buildFadeMask({ canScroll, atStart, atEnd, reserveArrowWidth })`
-  回傳 `linear-gradient` 字串。`reserveArrowWidth` > 0 時 fade 會延伸到 arrow button 底下(Material 3 scrim 原理);= 0 時直接從邊緣 fade。
+  回傳 `linear-gradient` 字串。`reserveArrowWidth` > 0 時 fade 會延伸到 arrow button 底下(Material 3 scrim 原理);= 0 時直接從邊緣 fade。 <!-- @benchmark-unverified -->
 - `useScrollByPage(scrollRef)` → `(direction: 'left' | 'right') => void`
   點一次滑動 `clientWidth × SCROLL_PAGE_RATIO`,含 `behavior: 'smooth'`。
 
@@ -66,7 +75,7 @@ scope: utility primitives module (use-overflow-items hooks: useScrollEdges + use
   - 必填 `aria-label`(直接傳給 Button 的 `aria-label`,無 `label` alias;由消費者決定,例如「頁籤選單(共 5 個)」)
   - `forwardRef` + `...props` spread 讓 Radix `DropdownMenuTrigger asChild` 可以接管
 
-> **元件保證行為:auto-Tooltip**——`OverflowScrollArrow` 與 `OverflowMenuTriggerButton` 都是 `iconOnly` + string `aria-label` + 非 `asChild`,因此都會觸發 Button 內建的 auto-Tooltip wrap(button.tsx:491-498)。亦即 hover 時 arrow / trigger 會自動冒出對應 `aria-label` 的 tooltip(「向左捲動」/「向右捲動」/「頁籤選單(共 N 個)」),共享全域 `Tooltip` 的 delay 與 warm-up。`DropdownMenuTrigger asChild` 仍正常運作:Radix 的 `asChild` 由 Trigger 自身消費(套到 `OverflowMenuTriggerButton` 的 forwardRef),不會傳成 Button 的 `asChild` prop,所以 tooltip wrap 與 trigger 接管互不衝突。
+> **元件保證行為:auto-Tooltip**——`OverflowScrollArrow` 與 `OverflowMenuTriggerButton` 都是 `iconOnly` + string `aria-label` + 非 `asChild`,因此都會觸發 Button 內建的 auto-Tooltip wrap(`button.tsx` iconOnly auto-Tooltip wrap)。亦即 hover 時 arrow / trigger 會自動冒出對應 `aria-label` 的 tooltip(「向左捲動」/「向右捲動」/「頁籤選單(共 N 個)」),共享全域 `Tooltip` 的 delay 與 warm-up。`DropdownMenuTrigger asChild` 仍正常運作:Radix 的 `asChild` 由 Trigger 自身消費(套到 `OverflowMenuTriggerButton` 的 forwardRef),不會傳成 Button 的 `asChild` prop,所以 tooltip wrap 與 trigger 接管互不衝突。
 
 ### Hook re-export
 
@@ -158,6 +167,13 @@ return (
 
 ---
 
+## 邊界案例
+
+- **內容塞得下(`canScroll=false`)**:`buildFadeMask` 回傳 `undefined`(無 mask),消費者依 `canScroll` 條件不渲染 arrows / menu trigger(Tabs / Chip 組裝範例皆如此)——items 為 0 或恰好全部塞進容器同理,overflow affordance 完全不出現
+- **鍵盤操作**:arrow / trigger 都是標準 `<Button>`(Tab 聚焦、Enter / Space 觸發);menu 開啟後的 Escape / 方向鍵由消費者的 `DropdownMenu`(Radix)own,本 module 無自訂 keyboard handler
+
+---
+
 ## 禁止事項
 
 ❌ **禁止** copy `ScrollArrow` 到其他元件。要在新元件加 overflow → import 本 module 的 `<OverflowScrollArrow>`。
@@ -174,7 +190,7 @@ return (
 
 **Non-consumers**(2026-05-10 retire from「未來」清單 — prior prediction stale,spec 已明文不消費):
 - ~~`components/Steps/steps.tsx`~~ — `steps.spec.md:342`「水平空間不夠塞 content 區,強塞會破壞 stepper 的掃視節奏」+ L353「步驟 ≤ 5、水平空間充足」→ 設計上不 overflow
-- ~~`components/SegmentedControl/*`~~ — `segmented-control.spec.md:240`「**不支援 overflow / scroll**——若選項可能超出容器寬度,代表選錯元件了」+ L239「最多 5 個 item」→ 設計上拒絕 overflow
+- ~~`components/SegmentedControl/*`~~ — `segmented-control.spec.md`「規模限制與邊界案例」段「**不支援 overflow / scroll**——若選項可能超出容器寬度,代表選錯元件了」+「最多 5 個 item」→ 設計上拒絕 overflow
 
 新消費者必須加到這個清單,並且**只從本 module import** overflow 相關的 primitive,不允許自己複製。
 
@@ -183,7 +199,6 @@ return (
 ## 反向引用
 
 - `hooks/use-overflow-items.ts` — 底層 scroll / overflow 計算 hooks(本 module re-export)
-- `CLAUDE.md`「選擇 / 狀態視覺」規則 — 為什麼 overflow trigger 不該用 selection-like 視覺
 - `components/Button/button.tsx` — text variant 的 canonical 樣式
 - `components/DropdownMenu/dropdown-menu.spec.md` — menu item 的 selection 指示器規則
 
@@ -191,11 +206,6 @@ return (
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `chip.spec.md`
 - `file-viewer.spec.md`
 - `overflow-indicator.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
-- `chip.spec.md`

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

@@ -34,6 +34,7 @@ Dialog 和 Popover 的**結構化 sub-components 共用 primitive**——提供
 - **永遠套 `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:168 恆套)矛盾。consumer 依浮層類型:
   - **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`「狀態處理的職責邊界」)
 
 ---
 
@@ -112,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。
 
@@ -171,7 +172,6 @@ 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`
@@ -193,7 +193,7 @@ Overlay family 的 header title typography 依「modal vs non-modal」分級,**
 - **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 |
@@ -216,7 +216,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 **不**套 unbounded slot trick(`overlay-surface.tsx:177-191` 僅 padding + `border-t`,慣例放 bounded action buttons)。**語義宣告**:
+**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(「這個操作無法復原」補充說明)。
 
@@ -230,7 +230,7 @@ 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 對照」)
 
 ---
 
@@ -238,7 +238,7 @@ Overlay family 的 header title typography 依「modal vs non-modal」分級,**
 
 > **背景**: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」分化對應。
 >
-> **依據**: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 |
 |--|--|--|--|--|
@@ -305,9 +305,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)
@@ -315,13 +317,28 @@ 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)
@@ -343,21 +360,6 @@ const CHROME_UNBOUNDED_SLOT =
 
 **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)機械化攔截。
 
-**共通 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 判斷
-
 ---
 
 ## Control + List 視覺對稱原則 → SSOT 規則 3 補充
@@ -402,6 +404,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 |
 
 ---
 
@@ -416,20 +428,12 @@ overlay-surface 是 **layout pattern**(`SurfaceHeader` / `SurfaceBody` / `Surfac
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `app-shell.spec.md`
-- `header-canonical.spec.md`
-- `motion.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
 - `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。若要手動補充,寫在本節之前。
-
 - `file-item.spec.md`
+- `header-canonical.spec.md`
+- `motion.spec.md`
+- `popover.spec.md`
+- `sheet.spec.md`
+- `uiSize.spec.md`

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

@@ -78,8 +78,9 @@ 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(v3:wrapper 自身
+   *           無 px / 無 border;TabsList 自己 w-full + px-loose,border-b 延展全寬 —
+   *           W1 視覺一條線。詳 chrome-header.tsx v3 fix 註解)
    *
    * Consumer 傳:`tabsSlot={<TabsList>...</TabsList>}`,TabsContent 仍放 DialogBody 內。
    * `<Tabs>` root 必須 wrap 整 DialogContent(Radix TabsList ↔ TabsContent 同 root 連動)。

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

@@ -56,6 +56,8 @@ benchmark:
 
 ## 視覺 canonical(對齊 DataTable v11)
 
+取值依據: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 抓得到
 - **Visual line**:1px,positioned `right-[3px]` / `bottom-[3px]`,default full-extent
   - **idle**:`bg-divider`
@@ -80,6 +82,13 @@ benchmark:
 - Image crop 邊界(專用 `<ImageCropTool>` 領域)
 - Splitter pane (`resizable-panes` style)— 雙端 drag with linked state(future 評估抽 `<SplitPane>` 上層 primitive 消費本 handle)
 
+## 邊界案例
+
+- **Disabled**:仍渲染 1px line(`bg-divider`,無 hover affordance),但無 cursor、無 `select-none`、不掛 role / orientation / label(見 a11y 段)。disabled 切換不改 DOM 結構,只增減 attribute。
+- **拖到 min / max 卡住**:primitive 不持 width state(不耦合 drag math),邊界 clamp 與卡住回饋由 consumer 的 resize handler 管;`isResizing` 期間 line 維持 `bg-primary` 不另示警。
+- **同列多 handle 並存**(多欄 column resize):各 handle 為獨立 `<span>`,無互相協調;`-3px` outward offset 使相鄰欄命中區可能相接,先命中者(DOM 順序 / pointer target)收事件,衝突仲裁屬 consumer drag math。
+- **RTL**:未特化——命中區與 line 用 physical `left/right` 定位(`resize-handle.tsx`),RTL 鏡像需另案。
+
 ## Roadmap(用 user 既有的 v2 framing)
 
 | Phase | Scope | Status |
@@ -96,7 +105,7 @@ Phase 2-4 需獨立 RFC + 各別 user approval,本 spec 只 ship Phase 1 + 鎖
 | DS / Library | 命中區 | Line | Cursor | a11y |
 |---|---|---|---|---|
 | **AG Grid** | 7-8px | 1px primary on drag | col-resize | role="separator" |
-| **Material X-DataGrid** | column-separator(resize 命中區)~8px | 1px hairline(`MuiDataGrid-iconSeparator` 是純裝飾分隔 icon,非命中區也非 a11y 來源)| col-resize | aria-label "Resize column" |
+| **Material X-DataGrid** | column-separator(resize 命中區)~8px | 1px hairline(`MuiDataGrid-iconSeparator` 是純裝飾分隔 icon,非命中區也非 a11y 來源)| col-resize | aria-label "Resize column" | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 | **Notion(column / sidebar)** | ~6-8px | 1px line | col-resize | (DOM-only,無 role)|
 | **VS Code** | 8px(activity bar)| bg highlight on drag | col-resize | aria-label "Resize" |
 | **Figma** | 8px | 1px line | col-resize | role separator |

package/src/patterns/resize-handle/resize-handle.stories.tsx

@@ -4,7 +4,7 @@ import * as React from 'react'
 import { ResizeHandle } from './resize-handle'
 
 const meta: Meta<typeof ResizeHandle> = {
-  title: 'Design System/Patterns/ResizeHandle',
+  title: 'Design System/Patterns/Resize Handle',
   component: ResizeHandle,
   parameters: { layout: 'centered' },
 }
@@ -12,10 +12,10 @@ export default meta
 
 type Story = StoryObj<typeof ResizeHandle>
 
-// Demo column with resize handle on right edge
+// Demo:DataTable「訂單金額」欄頭右緣的 resize handle(spec 首要 consumer 場景)
 const ColumnDemo: React.FC<{ isResizing?: boolean; disabled?: boolean }> = ({ isResizing, disabled }) => (
   <div className="relative inline-block bg-surface border border-divider px-[var(--layout-space-loose)] py-2 w-[200px]">
-    <span className="text-body">Column header</span>
+    <span className="text-body font-medium">訂單金額</span>
     <ResizeHandle
       direction="horizontal"
       position="end"
@@ -31,7 +31,7 @@ export const Default: Story = {
   render: () => (
     <div className="flex flex-col gap-4">
       <ColumnDemo />
-      <p className="text-caption text-fg-muted">滑鼠移到右邊緣時,游標變成左右拖拉樣式,分隔線顏色加深提示可以拖拉</p>
+      <p className="text-caption text-fg-secondary">滑鼠移到右邊緣時,游標變成左右拖拉樣式,分隔線顏色加深提示可以拖拉</p>
     </div>
   ),
 }
@@ -41,7 +41,7 @@ export const Dragging: Story = {
   render: () => (
     <div className="flex flex-col gap-4">
       <ColumnDemo isResizing />
-      <p className="text-caption text-fg-muted">拖拉進行中時,整條分隔線變成主色高亮,讓使用者清楚知道正在調整尺寸</p>
+      <p className="text-caption text-fg-secondary">拖拉進行中時,整條分隔線變成主色高亮,讓使用者清楚知道正在調整尺寸</p>
     </div>
   ),
 }
@@ -51,7 +51,7 @@ export const Disabled: Story = {
   render: () => (
     <div className="flex flex-col gap-4">
       <ColumnDemo disabled />
-      <p className="text-caption text-fg-muted">停用時不顯示拖拉游標,輔助技術也會忽略此元件,分隔線維持原本的灰色</p>
+      <p className="text-caption text-fg-secondary">停用時不顯示拖拉游標,輔助技術也會忽略此元件,分隔線維持原本的灰色</p>
     </div>
   ),
 }
@@ -60,7 +60,7 @@ export const Vertical: Story = {
   name: '垂直方向',
   render: () => (
     <div className="relative bg-surface border border-divider px-[var(--layout-space-loose)] py-2 w-[300px] h-[120px]">
-      <span className="text-body">Panel body</span>
+      <span className="text-body">查詢結果面板</span>
       <ResizeHandle
         direction="vertical"
         position="end"

package/src/tokens/README.md

@@ -16,7 +16,9 @@
 
 ## 當前居民
 
-`color/` / `typography/` / `uiSize/` / `layoutSpace/` / `density/` / `elevation/` / `radius/` / `opacity/`
+`color/` / `typography/` / `uiSize/` / `layoutSpace/` / `density/` / `elevation/` / `radius/` / `opacity/` / `motion/`
+
+例外居民:`categorical-color.ts` 住 tokens/ 根層(非 folder)— `CATEGORICAL_HUES` 的 TypeScript SSOT,由 `color/color.spec.md` 指認(Tag / Avatar 等 categorical 色相消費)。
 
 ## Consumer scope:public vs internal token(2026-05-17 codified)
 
@@ -24,8 +26,9 @@
 |---|---|---|
 | `color/` / `typography/` / `radius/` / `elevation/` / `opacity/` / `layoutSpace/` / `density/` | **Public** — consumer-layer(`src/app` / `src/explorations`)直接消費 | UI 開發者寫 `text-body` / `bg-primary` / `--layout-space-loose` 等 |
 | `uiSize/`(`--field-height-*` / `--tab-height-*` / `--table-row-*` / `--tree-indent-*`)| **Internal primitive** — DS 內部 component 消費,consumer 不直接用 | Button / Input / Tabs / DataTable / TreeView 等 primitive 內部消費;consumer 用 `<Button size="sm">` 不用 `h-[var(--field-height-sm)]` |
+| `motion/`(`--hover-delay-*`)| **Internal primitive** — DS overlay 元件內部消費,consumer 不直接用 | Tooltip / HoverCard / Avatar / OverflowIndicator 的 hover open / close delay;consumer 用元件預設,不直接讀 token |
 
-**Internal token 規則**(`uiSize/` 適用):
+**Internal token 規則**(`uiSize/` / `motion/` 適用):
 - **不必補 Storybook stories**(consumer 不直接看;審查 grep 結果:`src/app` + `src/explorations` 0 個檔案直接消費 uiSize token,2026-05-17 verified)
 - 但仍有 `.spec.md` codify family / 命名 / 派生公式
 - 出現在 consumer-layer code = anti-pattern(該用 component prop 不該 raw token)