npm - @qijenchen/design-system - Versions diffs - 0.1.0-beta.10 → 0.1.0-beta.13 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (307) hide show

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

@@ -0,0 +1,127 @@
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — verified 0 world-class DS claim in body; blanket retract removed. -->
+# Density 設計原則
+Density 由**兩個獨立維度**構成,並配合一個 convenience attribute 同時控制兩者:
+| 維度 | 管的是 | attribute | 範例 |
+|------|--------|-----------|------|
+| **UI Size** | 元件**高度 / 內距**(Button / Input / SelectionItem / field-height / table-row) | `data-ui-size` | `md`(28px field)/ `lg`(32px field) |
+| **Layout Space** | 版面**間距 / 外框 padding**(section gutter / dialog body padding / form gap) | `data-layout-space` | `md`(tight gap)/ `lg`(loose gap) |
+| **Density**(convenience)| 一鍵同時切兩者 | `data-density` | `md` / `lg` |
+## 兩維度為何解耦(世界級對照)
+**Carbon Design System**:spacing scale 獨立於 component size([carbondesignsystem.com/elements/spacing](https://carbondesignsystem.com/elements/spacing/overview/))
+**GitHub Primer**:8px base unit scale 獨立於 control size([styleguide.github.com/primer](https://styleguide.github.com/primer/support/spacing/))
+**Atlassian**:spacing tokens 可單獨消費(partial decouple)
+**反例**(耦合):Material M3 / Polaris density 模式綁 control size + spacing — 無法「寬版面 + 標準 control」的場景。
+**我們走 decouple 流派**:解決 Dialog / overlay chrome 的痛點 — header 想要寬鬆呼吸(layout=lg),但不要被 button chrome 撐高(ui-size 跟 page 走 md)。
+## 預設同步(density convenience)
+日常使用:不管兩個維度,直接 `data-density` 一次切兩者:
+```html
+<html data-theme="light" data-density="md">
+```
+- **md**(預設):資訊密集的桌面 UI / form-heavy 頁面
+- **lg**:觸控裝置 / 需要更大點擊目標的情境
+`data-density` 內部等同同時設 `data-ui-size` + `data-layout-space` 相同 tier。CSS selectors 同時監聽 `[data-density="lg"], [data-ui-size="lg"]` 等(見 `uiSize.css` + `layoutSpace.css`)。
+## 解耦用法(canonical 情境)
+當需要「layout 寬鬆 + control 標準」時,**顯式設兩個 attribute**:
+### Canonical 情境 1 — 歷史備忘(Dialog 已撤回)
+**歷史:** Dialog 先前設 `data-layout-space="lg"` 給 header/body 寬鬆呼吸,但跟 `--chrome-header-height` canonical(md=48)衝突(強設 lg 會變 56)。**已於 2026-04-22 v5 撤回**,Dialog 全盤繼承 page density(跟 Sheet 對齊)。
+**本情境仍有效的使用時機**:若未來有新元件需要「page density = md 但此元件 chrome 要 lg padding」,可用 `data-layout-space="lg"`(不撐高 header 的 rationale 仍成立,前提是 chrome-header-height 對齊不是需求)。
+```tsx
+// 假設未來某元件需要 lg 呼吸 + page-default ui-size
+<SomeContent data-layout-space="lg">
+  <Button size="sm" />  {/* 仍是 28px md */}
+</SomeContent>
+```
+**實際 v5 canonical(Dialog / Sheet / Popover)**:
+- Dialog / Sheet:繼承 page density(無 override)
+- Popover / DropdownMenu / Tooltip / Sidebar:`data-density="md"` 鎖定(Portal 逃逸 + compact 語意)
+### Canonical 情境 2 — 單獨切 ui-size
+Product demo / stakeholder 觀感測試:
+```ts
+document.documentElement.setAttribute('data-ui-size', 'lg')
+// layout-space 仍 md — 看大 control 在密集 layout 裡是否合用
+```
+### Canonical 情境 3 — 局部覆蓋
+某 region 需要不同密度:
+```tsx
+<div data-layout-space="lg">
+  {/* 這個 region layout 寬鬆,control 跟外層 page 走 */}
+</div>
+```
+## 動態切換
+```ts
+// 一鍵(兩維度同步)
+document.documentElement.setAttribute('data-density', 'lg')
+// 解耦(獨立控制)
+document.documentElement.setAttribute('data-ui-size', 'lg')
+document.documentElement.setAttribute('data-layout-space', 'md')
+```
+## 判斷流程(寫新元件時)
+1. **元件是否有自己特定 density**?
+   - 否(繼承 page) → 不設任何 `data-*-size` attribute,所有 token 由 `html[data-density]` 繼承
+   - 是 → 看 Q2
+2. **需要 layout 跟 control 同步 density 嗎**?
+   - 是 → 用 `data-density="X"`(convenience)
+   - 否(想解耦) → 明示 `data-layout-space="X"` + / 或 `data-ui-size="Y"`
+3. **Portal 逃逸 subtree?**(Dialog / Popover / Sheet / DropdownMenu)
+   - Portal 到 body 的元件**不繼承 trigger 的 density** → 必自設(對齊 Meta-Pattern M3)
+## 消費者清單
+| 元件 | attribute 設置 | 用法理由 |
+|------|---------------|---------|
+| Dialog | 無(繼承 page,v5 校準)| 跟 Sheet 對齊;header 高度 = `--chrome-header-height` 自動對齊(md=48 / lg=56);原 `data-layout-space="lg"` 已於 2026-04-22 撤回(衝突 chrome-header canonical) |
+| Sheet | 無(繼承 page) | Sheet 繼承 page density,不 lock |
+| Popover | `data-density="md"` | Portal 逃逸,且 popover 語意「compact」兩維度同鎖 md |
+| DropdownMenu | `data-density="md"` | 同 Popover |
+| Tooltip | `data-density="md"` | 同 Popover |
+| Sidebar | `data-density="md"` | Sidebar 本身 compact(不管 page 是否 lg)|
+## Anti-patterns(禁止)
+- ❌ 元件同時設 `data-density` + `data-ui-size`(重複,以後者為準但混亂)
+- ❌ Overlay Portal 元件不自設 density(Portal 到 body 不繼承 trigger — 見 Meta-Pattern M3)
+- ❌ 為了追求表面一致性硬把 Dialog button 綁 lg ui-size(犧牲 header 高度 / strapline 彈性)
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+- `dialog.spec.md`
+- `dropdown-menu.spec.md`
+- `popover.spec.md`
+- `sheet.spec.md`
+- `sidebar.spec.md`
+- `tooltip.spec.md`
+- `uiSize.spec.md`

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

@@ -0,0 +1,81 @@
+# Elevation 設計原則
+Elevation 定義陰影層級，區分內容層（Card）和浮層（Modal/Popover）的視覺深度。
+兩個層級對應兩種「浮起高度」，用 CSS 變數實現，light / dark mode 自動切換。
+**不要用 Tailwind 的 `shadow-*`**，改用 CSS 變數：
+```tsx
+<div style={{ boxShadow: 'var(--elevation-100)' }} />
+<div style={{ boxShadow: 'var(--elevation-200)' }} />
+```
+## 層級
+| Token | 用途 | 對應元件 |
+|-------|------|----------|
+| `--elevation-100` | 頁面內容層，靜止 | Card |
+| `--elevation-100-hover` | 頁面內容層，hover / 拖拽 | 可拖拽 card |
+| `--elevation-200` | 浮層，靜止 | Modal、popover、dropdown、overlay drawer |
+| `--elevation-200-hover` | 浮層，hover | — |
+elevation-100 < elevation-200，數字越大浮起越高。
+## 與 Surface 的配對規則
+| Elevation | 必須搭配 | 原因 |
+|-----------|----------|------|
+| `--elevation-100` | `bg-surface` | 頁面內容層，半透明可接受 |
+| `--elevation-200` | `bg-surface-raised` | 浮層必須不透明，否則底層內容透出 |
+```tsx
+// ✅ 正確
+<div className="bg-surface rounded-md" style={{ boxShadow: 'var(--elevation-100)' }} />
+<div className="bg-surface-raised rounded-lg" style={{ boxShadow: 'var(--elevation-200)' }} />
+// ❌ 錯誤——浮層用了半透明 bg-surface
+<div className="bg-surface rounded-lg" style={{ boxShadow: 'var(--elevation-200)' }} />
+```
+## 浮層間距（sideOffset）
+所有從觸發元件彈出的浮層（Tooltip、Popover、SelectMenu、Dropdown、HoverCard、Coachmark）與觸發元件的間距統一 **8px**（`sideOffset={8}`）。
+不因浮層類型或位置而異——一致的間距讓使用者建立穩定的空間預期。
+**SSOT** → `tokens/elevation/overlay-geometry.ts` exports `OVERLAY_SIDE_OFFSET = 8` / `OVERLAY_COLLISION_PADDING = 8`。所有 primitive `default` 必 import 該 const(M17 SSOT 必可傳播);Radix `sideOffset` 接 number 不接 CSS var,因此用 JS const 共用,改值只動一處全部聯動。
+| 浮層類型 | sideOffset | 說明 |
+|---------|-----------|------|
+| Tooltip | 8px | TooltipContent 預設值 |
+| SelectMenu | 8px | PopoverContent sideOffset |
+| DropdownMenu | 8px | DropdownMenuContent sideOffset |
+| Popover | 8px | 通用浮層 |
+## 浮層共用樣式
+所有 elevation-200 浮層共用：
+| 屬性 | Token | 值 |
+|------|-------|-----|
+| 背景 | `bg-surface-raised` | 不透明，避免底層透出 |
+| 陰影 | `--elevation-200` | 浮層陰影 |
+| 圓角 | `rounded-lg` | 8px |
+| 邊框 | `border border-border` | 1px |
+| sideOffset | 8px | 與觸發元件的間距 |
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+- `slider.spec.md`
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+- `motion.spec.md`

package/src/tokens/layoutSpace/layoutSpace.spec.md ADDED Viewed

@@ -0,0 +1,314 @@
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+# LayoutSpace 設計原則
+Layout Space 定義頁面與容器的巨觀間距 token,隨 density 自動縮放(透過 `data-density` 或 `data-layout-space`)。
+## Token 表
+| Token | md | lg | 語意 |
+|-------|----|----|------|
+| `--layout-space-loose` | 16px | 24px | 主間距:容器水平 padding、parallel 元素 gap、bounded region 呼吸空間 |
+| `--layout-space-tight` | 12px | 16px | 緊湊間距:Header → element、functional 交互的元素之間 |
+| `--layout-space-bottom` | 48px | 48px | 結論留白:內容到 action buttons(commitment 前視覺暫停)|
+**為什麼 bottom 不隨 density 變**:48px 是「結論前的留白」— content 到 action buttons 的視覺暫停。跟 density 無關(不論 compact 或 comfortable,使用者都需要「commitment 前」的節奏)。
+---
+## 元件角色:`region` / `element`(scope-relative)
+**沒有元件級固定分類** — 角色是元件在「該層 layout」裡扮演的,不是元件本質。CSS `display` 跟此分類**無關**(避免撞名,2026-04 從 v1 `block` / `inline` 改為 `region` / `element`)。
+| 角色 | 定義 |
+|------|------|
+| **region** | 寬高占主要空間(寬度撐滿、高度通常 flex-1 撐剩餘)/ 視覺畫布 / 該層展示主角 |
+| **element** | 局部塊 / 控件感 / 寬高自然 |
+### region 子分類
+| 子類 | 條件 | 視覺邏輯 |
+|-----|------|---------|
+| **bounded** | 有視覺邊界:底色 / 邊框 / 明確上下分隔線(Card / Table with borders / Panel with chrome)| 邊界清楚,容器靠 outer padding 給 spacing |
+| **unbounded** | 無視覺邊界:純 vertical collection,**靠 list 自帶 py + item 自帶高度**撐起視覺平衡(Cmd+K menu / Sidebar nav / unstyled list)| 邊界由 list 自帶 py 完成,outer padding = 0 才視覺對稱 |
+### 判斷 3 題(scope-relative)
+每進一層 layout container 重新判斷該層的子元件:
+1. 該層占主要空間嗎?(寬+高占主導 → region;局部 → element)
+2. 視覺重量是「畫布」還是「控件」?
+3. 是該層展示主角,還是一塊區段?
+任何元件(list / table / code block / image / form section / chart / sidebar)都套同邏輯。例:
+- Page body 直接放 Table → Table = bounded region(該層展示主角 + 有 borders)
+- Cmd+K menu list → list = unbounded region(主角 + 無 chrome,自帶 py)
+- InfoPanel 內 DescriptionList → element(只是一塊,不主導)
+- Field 內 Textarea → 不獨立分類(Field 整體才是該層的 element)
+### Region 數量 invariant(2026-04-30 codified)
+**Container body(vertical stack)通常最多 1 個 region — 罕見會多**。理由:
+- region 多為 `flex-1` 撐剩餘 → 兩個並存競爭 flex space
+- Multi-functional-group 慣用 **list group 切分**(`item-anatomy.spec.md` group separator)或多個 element,不另增 region
+- **Unbounded + bounded 並存違 scroll affordance**:unbounded 無邊界 vs 內部 scroll 必須 bounded chrome 讓 user 知道可捲
+**多 region 慣用 horizontal layout**(left-right panes / grid columns,Sidebar + Main + InfoPanel)。Vertical 多 region 罕見場景 → 走規則 3 親疏判 + consumer compose。
+---
+## 親疏 3 級(替代 v1 簡單 block-adjacent)
+判斷兩元素的 spacing 規則前,先確定它們屬哪一級:
+| 級別 | 條件 | layout rule? |
+|------|------|------------|
+| **同範疇 / bundled component family** | 元件 spec 寫成 bundle 並定 inter-component spacing(FileUpload+FileList、Pagination 內部、Toolbar+ButtonGroup) | 元件 spec own,layout rule **跳過** |
+| **跨範疇 + 直接 functional 交互 / 依賴** | search → filter list / heading → labeled content / toolbar → table / form section heading → fields | 規則 3 = **tight** |
+| **跨範疇 + parallel / independent** | form fields stack(parallel inputs)/ unrelated sections / 兩個獨立 functional groups | 規則 3 = **loose** |
+「**Bundled component family**」客觀判斷:**有沒有 spec 文件把這些 components 寫成 bundle 並定義它們之間 spacing**(不是「同種類 component instance 多個」)。
+「**Functional 交互 / 依賴**」具體:操作後在畫面上有交互(value 驅動 display)/ labeling(命名 / 描述 group identity)/ context dependency。
+---
+## 6 條 Layout 規則
+### 規則 1:水平 padding(3 patterns 並存)
+| Pattern | padding 寫哪 | 適用場景 |
+|---------|------------|---------|
+| **A. 元件自帶**(`px-loose` on root) | 元件 root | 有視覺邊界(border / bg / shadow / chrome):Sidebar / SurfaceHeader / Toolbar / Card / Panel |
+| **B. 父層管**(consumer 或 wrapper) | 父層 div | 純 layout primitive 無邊界:Table / DescriptionList / DataTable(naked structure)|
+| **C. Item 自帶**(each item `px-loose`,list naked)| 每個 item | List with hover row,hover bg 需 flush 容器邊界:Cmd+K menu / DropdownMenu items / Sidebar nav |
+任何內容左右 padding 最終 = `loose`(對齊 inline 元件邊緣);**寫哪看元件本質**,不是 either-or。
+Pattern C 的視覺邏輯見 `overlay-surface.spec.md`「Hover bg 貼邊 chrome」(hover bg 0 gutter 貼邊 + content 由 item-px 推進)。
+### 規則 2:頂部(Header → 第一個元素)
+| 第一個元素 | Header → 該元素 |
+|-----------|--------------|
+| **bounded region**(table / card / panel)| `loose` |
+| **unbounded region**(自帶 py 的 list / nav stack)| **0**(讓 list 自帶 py 撐 spacing) |
+| **element**(input / button / alert) | `tight` |
+### 規則 3:元素間 gap(**只看親疏,role 無關**)
+| 親疏 | gap |
+|------|-----|
+| **同範疇 / bundled** | 元件 spec own(跳此 rule)|
+| **跨範疇 + functional 交互** | `tight` |
+| **跨範疇 + parallel** | `loose` |
+**核心**:gap 只看親疏不看 role(原 v1「block-adjacent 一律 tight」過機械,違 Gestalt proximity)。
+世界級對齊:Material 3 / Polaris / Apple HIG / Atlassian 都按「relationship not type」決定 spacing。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+### 規則 4:底部 — 拆兩個 distinct 概念
+**核心**:**「內容 → action button 前留白」跟「元件 → 容器底邊」是兩個不同 spacing 概念**,不可混為一談。
+| 情境 | gap | 概念 |
+|------|-----|------|
+| **任何最後內容 → action button**(inline / in SurfaceFooter / in chrome footer 內)| `bottom`(48)| **A. Commitment 前留白** — user 跨到決策 moment |
+| **bounded region → 容器底**(後無 action buttons) | `loose` | **B. Spatial 邊界** |
+| **unbounded region → 容器底**(後無 action buttons) | **0**(list 自帶 py 撐)| **B. Spatial 邊界** |
+| **element → 容器底**(後無 action buttons) | `tight` | **B. Spatial 邊界** |
+**Note**:Dialog body `pb-bottom 48` 是 line 1 的實作(預期後接 SurfaceFooter buttons,universal 套 48,**不是元件特例**)。「**底部 chrome band**」(Alert / BulkActionBar / Status bar / Footer)內含 action → 套 48;不含 → 套 loose(line 2)。
+### 規則 5:橫排 Input Gap(固定不隨 density)
+橫排並列的 input fields **固定 gap,不走 layout-space token**:
+| 關聯性 | Gap | 範例 |
+|---|---|---|
+| 緊密相關(同一組值的起迄)| `gap-2`(8) | Sleep start ↔ Sleep end |
+| 非緊密(不同組值並列)| `gap-4`(16) | Sleep 時段 ↔ Work 時段 |
+**為什麼固定**:這是 field 級 micro-spacing,跟容器級 macro-spacing 是不同維度。Field gap 由**內容語意**決定(緊密 vs 獨立),不由 density 決定。
+### 規則 6:Chrome 水平左右 padding(規則 1 specialization)
+**所有 chrome 表面**(SurfaceHeader / SurfaceFooter / SurfaceBody / Sidebar header / FileViewer toolbar+filmstrip+InfoPanel header / app top bar / page header)**水平左右** padding 統一 `px-[var(--layout-space-loose)]`(md=16 / lg=24,density-aware)。
+**為何 loose 而非 tight**:Chrome 是 surface 視覺邊界 + 內容呼吸區;`tight` 足夠 inline list item,chrome 需更穩定 anchor 讓 title / dismiss / actions 不貼邊。
+**M8 8 家世界級對照**(default density 共識 16px):Material 3 Top App Bar 16dp / Carbon UI Shell 16px / Polaris Page Header 16px / Atlassian Page Header 16px / Apple HIG macOS Toolbar 16-20pt / Linear / Notion / GitHub Primer / Figma 全 16px。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**禁止**:硬寫 `px-4` / 自創值(`px-5`)/ 用 tight 當 chrome inline / 同 surface header/body/footer inline padding 不一致(三層左邊界必對齊)。
+---
+## 心智模型(三步推理 + 具體 self-questions)
+### Step 1 — 判角色(對單一元素)
+問 3 題:
+1. 在該層 layout 占主導(寬度撐滿 + 高度 flex-1)嗎?
+2. 視覺重量是「畫布」(占據 layout)還是「控件」(局部塊)?
+3. 是該層展示主角(主導內容)嗎?
+多數 yes → **region**;反之 → **element**。
+若 region 再問 1 題:有視覺邊界(底色 / 邊框 / 上下分隔線)嗎?
+- 有 → **bounded**(Card / Table with borders / Panel)
+- 無 → **unbounded**(menu list / nav stack,自帶 py 撐)
+### Step 2 — 判範疇(對兩元素之間)
+問 2 題:
+1. 兩元素在 spec.md 裡寫成 bundle 並定 spacing 嗎?(eg FileUpload+FileList / Pagination 內部 / button-group + SurfaceFooter)
+   - **是 → 同範疇 / bundled** → 跳 layout rule,套元件 spec own
+   - 否 → 跨範疇,進下一題
+2. 兩元素有直接 functional 交互 / 依賴(操作驅動 / labeling / context dependency)嗎?
+   - **是 → 相關**(search→list / heading→content / toolbar→table)→ tight
+   - **否 → 不相關**(parallel / independent)→ loose
+### Step 3 — 套規則(下節決策表 + walkthrough 範例)
+---
+## 套規則決策表(具體查詢)
+「我要決定什麼?」找對應規則:
+| 想決定的 | 走哪條規則 | 看哪些變數 | 答案分支 |
+|---------|----------|----------|---------|
+| 容器水平左右 padding | **規則 1** | 元件有無視覺邊界? | 有 → A 元件自帶 `px-loose` / 無 → B 父層管 / list-with-hover-row → C item 自帶 |
+| Header → 第一個元素 gap | **規則 2** | 第一個元素 role | bounded region → `loose` / unbounded region → **0**(list 自帶 py 撐)/ element → `tight` |
+| 兩元素之間 gap | **規則 3** | 親疏 | 同範疇 → 元件 spec own(跳)/ 跨範疇相關 → `tight` / 跨範疇 parallel → `loose` |
+| 最後內容 → 容器底 | **規則 4** | (a) 後接 action button?(b) 元件 role | 後接 action → `bottom`(48,概念 A commitment 前留白)/ 否則看 role:bounded → `loose` / unbounded → **0** / element → `tight`(概念 B spatial 邊界)|
+| 橫排並列 input 之間 gap | **規則 5** | 內容語意緊密度 | 同組值起迄 → `gap-2`(8) / 不同組並列 → `gap-4`(16) |
+| Chrome 表面水平 padding | **規則 6** | (永遠) | `loose` |
+---
+## 具體推導 walkthrough(6 範例)
+### 範例 1:Dialog 內 form fields stack(Field A ↔ Field B)
+- **走規則**:規則 3(兩元素之間 gap)
+- **判親疏**:
+  - bundled?(在元件 spec 裡寫成 bundle 嗎?) → **否**(consumer-composed)→ 跨範疇
+  - functional 交互?A 不驅動 B,parallel siblings → **不相關**
+- **答**:`loose`(16/24)— 對齊 Material / Polaris / Apple HIG / Atlassian 共識 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+### 範例 2:Cmd+K menu 中 search input ↔ result list
+- **走規則**:規則 3
+- **判親疏**:
+  - bundled?Input + list 不在同 spec bundle → 跨範疇
+  - functional 交互?search value 驅動 list filter → **相關**
+- **答**:`tight`(12/16)
+### 範例 3:Header chrome → InfoPanel 內第一個 Field(說明)
+- **走規則**:規則 2(Header → 第一個元素)
+- **判 role**:Field = element(局部塊 / 控件感)
+- **答**:`tight`(12/16)
+### 範例 4:Cmd+K menu list 最後 row → menu 容器底
+- **走規則**:規則 4
+- **判**:後接 action button?**否** → 看 role:menu list = unbounded region(主導 + 自帶 py 撐)
+- **答**:**0**(概念 B spatial 邊界,list 自帶 py 撐)
+### 範例 5:Dialog body 最後 field → body 底
+- **走規則**:規則 4
+- **判**:後接 action button(在 SurfaceFooter 內)?**是** → 套 `bottom 48`
+- **答**:48(概念 A commitment 前留白)。`dialog.tsx:203` body 預設 `pb-bottom` 是此規則的實作(預期 body 後接 SurfaceFooter buttons),非 Dialog 例外
+### 範例 6:SurfaceFooter 內 [Cancel] ↔ [Save] gap
+- **走範疇判**(在規則 3 之前):
+  - bundled?**是**(`button-group.spec` + `overlay-surface.spec` 都自帶 button arrangement canonical = `gap-2`/8px)
+  - → 同範疇 / bundled 第一級,**layoutSpace 一般規則跳過**
+- **答**:`gap-2`(8)— 由 `button-group.tsx:51` / `overlay-surface.tsx:92`(SurfaceFooter)自帶 canonical own
+**注意**:規則 5「橫排並列」**只**適用 input fields(line 102 明文),不套 button group。Button spacing 屬 bundled-family canonical,不走 layoutSpace 一般 rule。
+---
+## 典型容器範例
+### Form 情境(Field stack 在 Dialog 內)
+```
+┌────────────────────────────────────┐
+│  Title                        [X]  │  ← SurfaceHeader (chrome, py-tight)
+├────────────────────────────────────┤
+│← tight ─────────────────────────→ │  ← Header → element (規則 2)
+│  ← loose → [Name input]   ← loose →│
+│← loose gap ─────────────────────→ │  ← 跨範疇 parallel form fields (規則 3 不相關)
+│  ← loose → [Description]  ← loose →│
+│← loose ─────────────────────────→ │
+│  ← loose → [Other field]  ← loose →│
+│← bottom 48 ────────────────────→  │  ← 最後內容 → action buttons (規則 4 line 1, 概念 A)
+├────────────────────────────────────┤  ← SurfaceFooter border-t
+│  ← loose → [Cancel] [Save] ← loose →│  ← Footer (chrome, py-tight)
+└────────────────────────────────────┘
+```
+### Page 情境(全頁 list / dashboard)
+```
+┌────────────────────────────────────┐
+│ ← loose → [Toolbar items] ← loose →│  ← Toolbar(自帶 py-tight,跨範疇 functional → table 規則 3 tight)
+│╔══════════════════════════════════╗│
+│║← loose → DataTable       ← loose →║│  ← bounded region(規則 1 內 px = loose)
+│╚══════════════════════════════════╝│
+│← loose ─────────────────────────→  │  ← bounded region → 底部 chrome band(規則 4)
+│ ← loose → [Alert hint]    ← loose →│  ← 底部 chrome band
+│ ← loose → [BulkActionBar] ← loose →│
+└────────────────────────────────────┘
+```
+---
+## 模式切換
+```html
+<html data-density="md">
+```
+```ts
+document.documentElement.setAttribute('data-density', 'lg')
+```
+單獨控制版面間距而不影響元件尺寸:
+```ts
+document.documentElement.setAttribute('data-layout-space', 'lg')
+```
+---
+## Notes
+- **不抽 universal LayoutBody / FormLayout primitive**:world-class(Material / Polaris / Atlassian / Carbon / Mantine)都「每元件 own variant + 共享 token」;規則 1-6 universal,角色 scope-relative 易誤封裝。獨特 chrome 已在 `overlay-surface.spec.md` + `action-bar.spec.md`
+- **List-as-region in overlay body**(2026-05-01 canonical):當 Dialog / Sheet / Popover body 內容 = unbounded list-as-region(menu / Cmd+K / nav)時,consumer 用 className override 撤掉 chrome padding(`<DialogBody className="!px-0 !pt-0 !pb-0">`)+ 自管 list outer wrapper(`<div className="py-2">`)+ item 自帶 `px-loose rounded-md`。**不做成 body variant**(`flush?: boolean`)— Material/Atlassian/Mantine/shadcn 都 consumer 自管,Polaris flush API scope 極窄;variant 不解決底層脆弱(加 1 row search/banner 就破功),反把 1 surface decision 拆兩 API。詳 `overlay-surface.spec.md`「List-as-region in overlay body」+ `dialog.tsx:165` JSDoc
+- **v1 → v6**(2026-04-30):block-adjacent 機械 → 親疏判 + bundled-family 分權 + region 二分(bounded/unbounded)+ 多 region 限制。詳 git + memory `feedback_layout_v6_canonical.md`
+---
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+- `description-list.spec.md`
+- `dialog.spec.md`
+- `empty.spec.md`
+- `file-viewer.spec.md`
+- `overlay-surface.spec.md`
+- `uiSize.spec.md`
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+- `app-shell.spec.md`

package/src/tokens/motion/motion.spec.md ADDED Viewed

@@ -0,0 +1,97 @@
+---
+component: motion
+family: token
+variants: {}
+sizes: {}
+traits: []
+benchmark:
+  - Material Design 3 motion tokens: m3.material.io/styles/motion/easing-and-duration
+  - Carbon Design System duration tokens: carbondesignsystem.com/guidelines/motion/overview
+  - Atlassian @atlaskit/tokens motion: atlassian.design/tokens/all-tokens#motion
+  - Radix Tooltip delayDuration: radix-ui.com/primitives/docs/components/tooltip
+  - MUI Tooltip enterDelay: mui.com/material-ui/api/tooltip
+---
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+# Motion tokens — hover delay 設計原則
+> **Foundational SSOT rationale**(2026-05-18 ship per user 拍板 #3A):跨 5+ overlay 消費者
+> (Tooltip / HoverCard / NameCard / Avatar / OverflowIndicator)的 hover 開啟 / 關閉延遲統一。
+## 定位
+Hover delay token 是「hover 觸發 → overlay 顯示」之間的等待時間。**目的不是動畫長度,是「user 真的想看」過濾器** — 短暫滑過不該觸發 expensive overlay(NameCard fetch 資料 / Tooltip 視覺擾動)。
+## 三層 tier 系統
+| Token | 值 | 用於 | 為何 |
+|---|---|---|---|
+| `--hover-delay-plain` | `500ms` | Tooltip 純文字提示 | 被動 hint,需 user「真停留」才觸發,避免滑過列表時 N 次視覺擾動。對齊 Material 3 plain tooltip 500ms / Apple HIG ~500ms / shadcn-Radix default 500ms 主流共識 |
+| `--hover-delay-rich` | `700ms` | HoverCard / NameCard 內容預覽 | 含 avatar / fields / actions 的 rich content(可能含 fetch)。User 必須「真的想看」才停留 700ms,避免列表掃視時誤觸發 N 個 fetch waterfall |
+| `--hover-delay-close` | `200ms` | 所有 overlay 關閉 | Mouse leave 後給 200ms 緩衝(user 可能誤滑出再回來)。對齊 UX 共識「close delay ≤ open delay」+ 既有 Avatar `closeDelay={200}` 值 |
+## 為何不用單一值 / 為何不沿用過去 200ms
+- **過去 200/300ms 偏快**(2026-05-18 ship,2026-05-20 user 抓「太快很容易干擾人」撤回):200ms plain 滑過列表 N 次觸發 Tooltip 視覺擾動;300ms rich 在含 fetch 的 HoverCard 場景列表掃視會打 N 次 server request waterfall。
+- **MUI/Ant 100ms 是 fast-tier 例外**:適合 form input help text 等「我就是要快」的 dense 場景,不適合通用 chrome tooltip。
+- **單一值** 失去 plain / rich 語意區分:NameCard 含 fetch + image + actions 應比 Tooltip(純文字)delay 長,單一值會讓 NameCard 滑過列表時整列誤觸發 fetch waterfall。
+- **過短**(< 100ms):每滑必觸發 → 視覺擾動 + 不必要 server request。
+- **過長**(> 1s):user 已不期待 overlay,等出來變干擾。
+## 何時用 / 何時不用
+| 場景 | 用哪 token | 為何 |
+|---|---|---|
+| Icon-only Button → 顯示文字提示 | `--hover-delay-plain` | 純文字輔助 |
+| Avatar / Username → 顯示完整人物卡 | `--hover-delay-rich` | 含 fetch + multi-section content |
+| OverflowIndicator → 顯示隱藏列表 | `--hover-delay-plain` | 純列表展開,無 fetch |
+| Tag / Chip → 顯示說明 | `--hover-delay-plain` | 純文字 |
+| 任何 overlay 關閉延遲 | `--hover-delay-close` | universal |
+| Click-triggered Popover / Dialog | — | N/A,click 不適用 hover delay |
+| Tooltip 鍵盤 focus 觸發 | — | N/A,直接顯示(對齊 WAI-ARIA APG) |
+## 命名 rationale(per `# 命名與語言一致性` 3 test)
+1. **既有 DS 詞彙**:`plain` / `rich` 對齊 FileItem `compact / rich` mode tier idiom(world-class richness gradient)
+2. **世界級 idiom**:Material 3 documentation 公開使用「plain tooltip」+「rich tooltip」術語(verified URL above) <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+3. **跨元件無語意衝突**:`plain` 不撞 cva variant(無元件用 `variant="plain"`);`rich` 跟 FileItem mode 同義(content density gradient)
+### Anti-pattern 避免命名
+- ❌ `--hover-delay-tooltip` / `--hover-delay-hovercard` — 元件名綁定 → 新元件(Popover variant)用哪個?
+- ❌ `--delay-200` / `--delay-300` — 用值不用語意 → 改值要 rename
+- ❌ `--motion-hover-fast` / `--motion-hover-slow` — fast/slow 在 hover 語境語意模糊(對 user 來說「fast」應該是 instant?)
+- ❌ `--hover-time` / `--mouseover-pause` — 自創縮寫,跨人不可讀
+## 消費者
+- `components/Avatar/avatar.tsx:299` — HoverCard openDelay / closeDelay(原硬寫 300/200,migrate 到 token)
+- `components/HoverCard/hover-card.tsx` — Radix Provider 預設 delayDuration override 為 `--hover-delay-rich`
+- `components/Tooltip/tooltip.tsx` — Radix Provider 預設 delayDuration override 為 `--hover-delay-plain`
+- `components/NameCard/name-card.tsx`(consumer of HoverCard)— 繼承 `--hover-delay-rich`
+- `components/OverflowIndicator/overflow-indicator.tsx`(consumer)— 用 `--hover-delay-plain`
+- 任何 future overlay hover consumer 必 import 此 token(per M17 SSOT 必可傳播)
+## 世界級對照
+| Framework | plain hint delay | rich preview delay |
+|---|---|---|
+| Material 3(plain vs rich tooltip 分流)| ~500ms | ~500ms+ |
+| Apple HIG / macOS native | ~500ms | — |
+| Radix Tooltip | 700ms(設保守避 mobile / touch 誤觸)| N/A(consumer 自定) |
+| shadcn(defer Radix) | 500ms(provider override)| N/A |
+| Polaris | 400ms | — |
+| Atlassian Tooltip | 300ms | — |
+| MUI / Ant Tooltip | 100ms(dense form input fast-tier) | — |
+| **DS canonical(本 spec)** | **500ms** | **700ms** |
+500ms 對齊 Material 3 / Apple HIG / shadcn 主流共識(三家集中在 500ms),避 MUI/Ant 100ms(form input fast-tier 不適通用 chrome)+ Radix 700(過保守)兩極端。Rich 700ms 比 plain 多 200ms 反映 fetch / multi-section content「真的想看」門檻。
+## 相關
+- `../elevation/elevation.spec.md` — overlay 視覺層(z-index)
+- `../../patterns/overlay-surface/overlay-surface.spec.md` — overlay 結構 SSOT
+- `../../components/Tooltip/tooltip.spec.md`(consumer)
+- `../../components/HoverCard/hover-card.spec.md`(consumer)
+- `../../components/Avatar/avatar.spec.md`(consumer)