@qijenchen/design-system 0.1.0-beta.83 → 0.1.0-beta.84

package/src/patterns/action-bar/action-bar.stories.tsx

@@ -35,8 +35,11 @@ const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }
   <p className={`text-footnote leading-normal ${warn ? 'text-error font-medium' : 'text-fg-muted'}`}>{children}</p>
 )
 
+/* 2026-07-14 Dim 90 修:Action Bar 無 production container,本檔 toolbar frame 是主要參考
+   實作 — 水平內距原本 px-4 / px-3 hardcode(不隨 layout density 縮放且三處不一致),統一改
+   chrome 水平內距 canonical `px-[var(--layout-space-loose)]`(對齊 chrome-header.tsx 同 token)。 */
 const ToolbarFrame = ({ title, children }: { title: string; children: React.ReactNode }) => (
-  <div className="flex items-center justify-between w-full px-4 min-h-[52px] border border-border rounded-lg bg-surface">
+  <div className="flex items-center justify-between w-full px-[var(--layout-space-loose)] min-h-[52px] border border-border rounded-lg bg-surface">
     <span className="text-body font-bold text-foreground shrink-0 mr-4">{title}</span>
     {children}
   </div>
@@ -317,7 +320,7 @@ export const Dividers: Story = {
             </ButtonGroup>
           </ToolbarFrame>
           <Label>靠右對齊 — 有框業務操作接無框工具操作，視覺差異已足夠，不加分隔線</Label>
-          <div className="flex items-center w-full px-4 h-[52px] border border-border rounded-lg bg-surface">
+          <div className="flex items-center w-full px-[var(--layout-space-loose)] h-[52px] border border-border rounded-lg bg-surface">
             <ButtonGroup>
               <Button variant="primary" size="sm" startIcon={Plus}>新增</Button>
               <Button variant="tertiary" size="sm" startIcon={Download}>匯出</Button>
@@ -421,7 +424,7 @@ export const Overflow: Story = {
         title="群組溢出（例外）— 各群組各自管理，只在合併選單會讓使用者困惑時才用"
         note="當多個群組的低頻操作領域差異大到「放進同一個選單使用者會搞不清這是哪個群組的」時，才讓各群組各自管理溢出。每個群組溢出的右側必須加分隔線（群組溢出邊界）。以 Rich Text Editor 為例：文字格式、插入元素、歷史操作三個群組功能差異極大，合併選單語意混亂"
       >
-        <div className="flex items-center w-full px-3 h-[52px] border border-border rounded-lg bg-surface">
+        <div className="flex items-center w-full px-[var(--layout-space-loose)] h-[52px] border border-border rounded-lg bg-surface">
           <ButtonGroup>
             {/* 群組 A：文字格式 + 溢出 */}
             <Button variant="text" size="sm" iconOnly startIcon={Bold} aria-label="粗體" />

package/src/patterns/element-anatomy/inline-action.spec.md

@@ -27,6 +27,8 @@
 | focus-visible | `outline: 2px solid var(--ring)` | — |
 | 宿主 disabled | 不渲染 inline action | — |
 
+**Loading(明文 N/A)**:inline action **無 loading 態**——icon 級靶子沒有空間承載 spinner 且換渲會位移幾何,故不設 `aria-busy` / spinner surface。async 動作(row approve / retry / API delete)兩條路:(a) 觸發後由宿主層呈現 in-flight 結果(row pending 樣式 / Toast / optimistic update);(b) 需要使用者可感知的進行中狀態 → **升級為 `<Button loading>`**(Button spec「loading」段:CircularProgress + 自動 disabled + `aria-busy`),不用 inline action。double-trigger 防護由 consumer handler 冪等 / 重入 guard 承擔(對齊 `form-validation.spec.md`「Double-submit 防護」)。
+
 **Overlay trigger canonical**(2026-04-29 訂 / 2026-05-02 改 / 2026-05-05 prop 化):trigger 透過 `asChild` 作 DropdownMenu / Popover / Tooltip / HoverCard trigger 時,Radix 自動 set `data-state="open"`,**trigger 維持 host hover 樣式**直到浮層關閉。對齊**狀態極簡派**(shadcn / Radix Themes / Material — 不另開 4th token);避免 state 增生 + 跨 host(neutral / colored)規則同步。
 
 **2026-05-05 修正:overlay vs in-place 語意分離**。`Radix Collapsible.Trigger` 也 emit 同 `data-state="open"`,但語意完全不同(展開內容**接在下方非 floating**,user 不需追溯)。原 `ItemInlineActionButton` 將規則**無條件**套用於所有 `data-state=open`,造成 Sidebar collapsible group label 的 chevron 展開時殘留 hover bg(2026-05-05 user reported)。修正:`ItemInlineActionButton` 加 `overlayTrigger?: boolean` prop,**default `false`**。consumer 顯式宣告:

package/src/patterns/element-anatomy/item-anatomy.spec.md

@@ -173,6 +173,8 @@ rg 'grid-cols-\[[0-9]+px_1fr\]' packages/design-system/src -g '*.tsx'
 - **Size variants**: sm / md / lg 跟 `--field-height-*` family 一致
 - **Icon 尺寸控制**: 用 `ICON_SIZE` 常數 `{ sm: 16, md: 16, lg: 20 }` 對齊 `--field-height-*`,並**透過 `size` prop 直接傳給 Lucide icon**(不要用 CSS selector 如 `[&>svg]:size-4`——當 icon 被包在 `h-[1lh]` wrapper 裡時,`>` 直接子選擇器失效,Lucide 會 fallback 到 24px 預設)。MenuItem / TreeView / SidebarMenuButton 都這樣做,新元件照抄
 - **Row header(分組標題)**: 用 `MenuItem header={true}` 模式,`font-medium text-fg-muted pointer-events-none` + 與 items **完全相同**的 row geometry(同 px / 同 py / 同 text size)
+- **Row header 計數 suffix**(2026-07-08 WM 戰役 codify,user 拍板):分組標題帶總數時 = **標題靠左、純數字靠右**(space-between,即 suffix slot 位置 `ml-auto`)。數字規格走既有 suffix value canonical(下方 metadata 表「fg-muted、字體大小與 label 相同」)+ `font-normal` + `tabular-nums`;count = 0 不渲染。**禁**把 count 串進 label 字串相鄰放(「Unstarted (2)」— 6 家世界級無一家括號串接:Primer CounterLabel / Ant Badge / Atlassian Badge 皆結構化 slot);字串層(aria-label / 純文字匯出)可用括號形。互動導覽元素(tab / segmented / sidebar item)的計數仍走 `badge` slot(tabs.spec.md「badge 傳達計數」),不適用本條。
+- **可收合 section header 組合 canonical**(2026-07-08 R3-7 拍板 + 2026-07-10 codify 進 DS;**組合非元件** — SectionHeader 留產品客製,但 layout 全消費本 canonical):(1) chevron = **title 後的 suffix inline action**(非 prefix、非獨立按鈕群);(2) 可選 description 與 title 間距用 `--item-gap-label-desc-*` token;(3) endSlot(操作鈕)只有 title 一行時垂直置中;(4) 同構標題列 ≥ 2 份必抽共用元件(WM `SectionHeader.tsx` 錨例 — Description / Attachments / Child work items 三份同構收斂)。手刻簽名(Chevron + justify-between + 可點且無共用元件)由 consumer 防線攔(escape `@section-header-ok:`)。
 
 ### Prefix 垂直對齊:`items-start` + `h-[1lh]` wrapper(**永遠這樣**,不要做例外)
 
@@ -427,7 +429,14 @@ MenuItem 承載 Switch 時,**整列 row 的 click = toggle 這個 control**(不
 ```tsx
 // ✅ Canonical:row click 與 suffix Switch 同步 toggle(row 可點擊、Switch 視覺反映狀態)
 // (DropdownMenuItem 無任意 suffix slot——trailing 互動 control 用 MenuItem endContent)
-<MenuItem endContent={<Switch checked={dark} tabIndex={-1} aria-hidden />} onClick={() => setDark(!dark)}>
+// row = 唯一 ARIA owner:role="menuitemcheckbox" + aria-checked 讓 AT 感知 on/off
+//(Switch aria-hidden 後,沒有這兩個屬性 toggle 狀態對 SR 完全隱形)
+<MenuItem
+  role="menuitemcheckbox"
+  aria-checked={dark}
+  endContent={<Switch checked={dark} tabIndex={-1} aria-hidden />}
+  onClick={() => setDark(!dark)}
+>
   Dark mode
 </MenuItem>
 
@@ -438,7 +447,7 @@ MenuItem 承載 Switch 時,**整列 row 的 click = toggle 這個 control**(不
 </MenuItem>
 ```
 
-**Switch 實作細節**:放 suffix 時 Switch 應 `tabIndex={-1}` + `aria-hidden`(或去掉自己的 click handler),讓 **row 成為唯一互動靶子**、Switch 純視覺反映狀態。Radix `DropdownMenuCheckboxItem` 的 Checkbox 就是這模式(checkmark 是視覺,整列是 trigger)。Switch 類比採用同樣規則。
+**Switch 實作細節**:放 suffix 時 Switch 應 `tabIndex={-1}` + `aria-hidden`(或去掉自己的 click handler),讓 **row 成為唯一互動靶子**、Switch 純視覺反映狀態。**同時 row 必須自己宣告可感知的 checked state**——`role="menuitemcheckbox"`(或 `"switch"`)+ `aria-checked`;Switch 被 aria-hidden 後,漏宣告 = toggle 狀態對 screen reader 完全隱形。Radix `DropdownMenuCheckboxItem` 就是這模式(checkmark 純視覺,整列 row 帶 role=menuitemcheckbox + aria-checked)。Switch 類比採用同樣規則。
 
 **何時用 suffix Switch vs Field horizontal**:
 
@@ -538,7 +547,7 @@ Apple Mail / Gmail / iOS Settings / Material 3 / Atlassian DSP / Polaris Resourc
 
 **關鍵**:consumer 可以自由選擇「小 avatar + description」——那是完全合法的組合,此時 avatar inline 對齊第一行 label,description 從第二行自然往下。沒有「有 desc 就必須用 block 尺寸」的規則。此自由度屬裸 `<ItemAvatar>` 組合;MenuItem 的 AvatarData API 不暴露此選擇(自動推導,見上 scope 註)。
 
-**程式化規則**(scope:**row context only** — Sidebar / SelectMenu / TreeView / Combobox / Menu 等 row primitive 子樹內):consumer **必須**用 `<ItemAvatar>` / `<ItemIcon>` helper 元件,**禁止** `import { AVATAR_SIZE }` 手動查表,更**禁止**硬寫 `<Avatar size={N} />`。
+**Helper 程式化封裝 + review 防線**(scope:**row context only** — Sidebar / SelectMenu / TreeView / Combobox / Menu 等 row primitive 子樹內):consumer **必須**用 `<ItemAvatar>` / `<ItemIcon>` helper 元件(helper 自動查 `RowSizeContext` 對表 = 程式化封裝),**禁止** `import { AVATAR_SIZE }` 手動查表,更**禁止**硬寫 `<Avatar size={N} />`(兩條禁令現無機械 hook 閘,靠 review 防線把關)。
 
 **Scope 例外:Chrome header 不是 row context**(per `header-canonical.spec.md` 4.5):chrome header 有自己的 spec-level avatar canonical = 24px(density-fixed / row-size-fixed),用 raw `<Avatar size={24}>` + `--chrome-header-avatar-size` CSS token。Chrome header avatar 不參與 row anatomy 對齊機制(無 sm/md/lg row size lookup 需求)。詳 `header-canonical.spec.md` 4.5「Chrome header avatar SSOT」段。
 
@@ -829,8 +838,8 @@ World-class benchmark(6 家 DS):
 (2026-05-31 重構後依 mode/size 選對應後綴變體 `--item-gap-label-desc-<reading|scanning>[-lg]`,bare token 已不存在;見上方「兩種閱讀模式」SSOT 段。)
 
 **Enforcement**:
-- Hook `check_item_content_primitive.sh`(2026-04-23)P1 warn:component .tsx 出現硬寫 `mt-0.5` / `gap-0.5` 提示改 token / primitive
-- Consumer 刻意 hard-code 加 `// @item-gap-exempt: <reason>` 豁免 + rationale 在 spec
+- Hook `check_item_content_primitive.sh`(2026-04-23 加)已 retired(→ `.claude/hooks/retired/`,無現役 write-time 機械閘);硬寫 `mt-0.5` / `gap-0.5` 現靠 audit-time 掃描 + mindset #2(優先消費既有 token / primitive)把關
+- Consumer 刻意 hard-code 加 `// @item-gap-exempt: <reason>` 豁免 + rationale 在 spec(marker 現無 hook 消費者,保留作 review 註記)
 
 **兩種模式的唯一差異是行高。** Description 在所有模式都降一級字體——label 是要辨識的目標，description 是補充，尺寸差有助快速區分。
 

package/src/patterns/element-anatomy/item-anatomy.stories.tsx

@@ -15,12 +15,14 @@ import { Avatar, type AvatarData } from '@/design-system/components/Avatar/avata
 import { ProfileCard, ProfileCardDefaultActions } from '@/design-system/components/ProfileCard/profile-card'
 
 /** Person avatar hover canonical helper — avatar.spec.md DS-wide rule:
- *  profile-card.spec.md 重要資訊 canonical(status / statusMessage / fields 皆必含) */
+ *  profile-card.spec.md 重要資訊 canonical(status / statusMessage / fields 皆必含)
+ *  真實人像(2026-07-08 sweep):固定 u= key 保 determinism(對齊 avatar.stories.tsx pravatar 慣例)*/
+const avatarSrc = (name: string, px = 96) => `https://i.pravatar.cc/${px}?u=${name.toLowerCase().replace(/\s+/g, '-')}`
 const personHover = (name: string, subtitle?: string) => (
   <ProfileCard
     name={name}
     subtitle={subtitle ?? 'Design｜D-0042｜EMP-1001'}
-    avatar={{ alt: name }}
+    avatar={{ src: avatarSrc(name), alt: name }}
     status="online"
     statusMessage="Out of Office: Back on Monday!"
     actions={<ProfileCardDefaultActions />}
@@ -1034,10 +1036,10 @@ export const AlignmentThreshold = {
 
           {/* Live example */}
           <MenuFrame width={360}>
-            <MenuItem size="md" avatar={{ alt: "Alice", color: "indigo" as const, hoverCard: personHover("Alice Chen", "Design team lead") }} description="Design team lead">
+            <MenuItem size="md" avatar={{ src: avatarSrc("Alice Chen", 64), alt: "Alice", color: "indigo" as const, hoverCard: personHover("Alice Chen", "Design team lead") }} description="Design team lead">
               Alice Chen
             </MenuItem>
-            <MenuItem size="md" avatar={{ alt: "Bob", color: "yellow" as const, hoverCard: personHover("Bob Wang", "Backend engineer") }} description="Backend engineer">
+            <MenuItem size="md" avatar={{ src: avatarSrc("Bob Wang", 64), alt: "Bob", color: "yellow" as const, hoverCard: personHover("Bob Wang", "Backend engineer") }} description="Backend engineer">
               Bob Wang
             </MenuItem>
           </MenuFrame>

package/src/patterns/element-anatomy/item-anatomy.tsx

@@ -77,15 +77,16 @@ export const ICON_SIZE: Record<RowSize, number> = {
  * - **block**(有 description,avatar 跨越 label + desc 兩行)→ 對齊文字塊中心
  *   sm: 32, md: 32, lg: 40
  *
- * **用法**:所有 row primitive 的 consumer(包含 `asChild` pattern 的 Sidebar / Tree
- * consumer)**必須**從本 module import 這個常數,**不可硬寫 `size={24}`**。
- * 硬寫會讓 sm 變體的 avatar 尺寸錯誤、跟 ICON_SIZE 對齊規則脫鉤。
+ * **用法**:row context 的 consumer(包含 `asChild` pattern 的 Sidebar / Tree
+ * consumer)**必須**用 `<ItemAvatar>` / `<ItemIcon>` helper 元件(自動查
+ * RowSizeContext 對表),**禁止** `import { AVATAR_SIZE }` 手動查表、**不可硬寫
+ * `size={24}`** — 硬寫會讓 sm 變體的 avatar 尺寸錯誤、跟 ICON_SIZE 對齊規則脫鉤。
+ * 詳 item-anatomy.spec.md「Helper 程式化封裝 + review 防線」段。
  *
  * ```tsx
- * import { AVATAR_SIZE } from "@/design-system/patterns/element-anatomy/item-anatomy"
+ * import { ItemAvatar } from "@/design-system/patterns/element-anatomy/item-anatomy"
  *
- * const { size } = useSidebar()  // RowSize
- * <Avatar size={AVATAR_SIZE.inline[size]} />
+ * <ItemAvatar alt="Alan" color="blue" />  // 自動查 AVATAR_SIZE.inline[rowSize]
  * ```
  *
  * Canonical 消費者:MenuItem 直接 import 本檔 `AVATAR_SIZE`(menu-item.tsx,消費 .block/.inline;re-export 已完成,MenuItem 無內部查表)。

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

@@ -30,6 +30,7 @@ benchmark:
 **何時不用(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
 
@@ -233,10 +234,10 @@ ChromeHeader / SurfaceHeader 新增 `tabsSlot?: ReactNode` prop。提供時自
 
 ### Layer 1 — Token shared
 
-兩家族 consume 同組 CSS variable(機械對齊):
-- `--chrome-header-height`(uiSize.css:55,103)
-- `--layout-space-loose` / `--layout-space-tight`
-- `--divider-color`
+兩家族連動 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 連動)
 

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

@@ -361,7 +361,7 @@ const CHROME_UNBOUNDED_SLOT =
 
 **禁止**:`w-[640px]` 單獨用(❌ 斷鏈)/ `flex flex-col h-full` 無 `min-h-0`(❌ flex item 不 shrink,scroll 失效)。
 
-**DS-wide consumer 必檢點**:`grep '<PopoverContent\|<HoverCardContent\|<DialogContent\|<SheetContent'` 內第一層 wrapper 是否含 `flex flex-col h-full`(若該 panel 用 SurfaceBody)。Hook `check_pattern_invariants.sh` C.1(原 `check_overlay_panel_scroll_chain.sh` 已 folded;2026-05-31 infra-audit 修 dangling ref)機械化攔截。
+**DS-wide consumer 必檢點**:`grep '<PopoverContent\|<HoverCardContent\|<DialogContent\|<SheetContent'` 內第一層 wrapper 是否含 `flex flex-col h-full`(若該 panel 用 SurfaceBody)。Hook `check_pattern_invariants.sh` C.1(原 `check_overlay_panel_scroll_chain.sh` 已 folded;2026-05-31 infra-audit 修 dangling ref)write-time 機械化警示(P1 WARN stderr,僅掃本次 edit fragment 不 block);DS-wide 全掃(上述 grep 必檢點)走 audit。
 
 ---
 
@@ -381,6 +381,27 @@ const CHROME_UNBOUNDED_SLOT =
 
 ---
 
+## 兩欄 dialog 組合 canonical(2026-07-10 user 拍板:組合,不做元件)
+
+「左內容 + 右 metadata」兩欄 dialog(工作項詳情類)**是產品層組合,不收進 DS 元件**——對齊
+Atlassian(modal-dialog 無宣告式兩欄 API,官方以 composition 範例示範)與 MUI(Dialog 無 split
+API,欄由 layout primitive 組)。DS 只 codify 組合鐵律(違規簽名由 consumer 防線
+`check_consumer_app_invariants.sh` r3 機械攔):
+
+1. **各欄自帶 `<ScrollArea>` 獨立捲動**——禁兩欄共用單一 ScrollArea / 共用一條捲軸(每欄
+   套上方「Body overflow canonical」模板,padding 進 viewport 內層 div)。
+2. **divider = 右欄(`<aside>`)自持 `border-l border-divider`,貫穿 body 頂到底**——非獨立
+   div、非只切半高。
+3. **欄底 footer(如 comment composer)釘在所屬欄內**(欄內 `SurfaceFooter` chrome),
+   非 dialog 全寬 footer——對齊 Atlassian 官方兩欄範例把 ModalFooter 巢狀進左欄。
+4. **header 維持全寬**,分欄從 body 才開始。
+
+**Archetype**(照抄結構,禁憑記憶手刻):WM `WorkItemDetailDialog.tsx`(產品實證,2026-07-08
+拍板落地)/ DS 內部同構先例 `file-viewer.tsx` InfoPanel(`<aside class="w-80 shrink-0 flex-col
+border-l border-divider">`)/ Atlassian `modal-dialog/examples/101-full-height-illustration.tsx`
+(per-column `flex:1 + minHeight:0 + overflow auto`)。完整研究引文 →
+`.claude/planning/2026-07-10-dialog-split-body-proposal.md`(元件化提案被 user 否決的紀錄)。
+
 ## 不屬本 primitive 的職責
 
 - **Close 按鈕渲染**:由 consumer(Dialog / Sheet / Popover)自己包 `<Button iconOnly dismiss>` 在 Header 內,綁各自 Radix Close primitive。SurfaceHeader 本身不渲染 close,避免 pattern 與 consumer 的職責耦合。

package/src/styles/tokens.css

@@ -25,6 +25,9 @@
 
    ═══════════════════════════════════════════════════════════════════════ */
 
+/* Overlay 進出場動畫 utilities(tw-animate-css;7 浮層消費)*/
+@import "tw-animate-css";
+
 @import './../tokens/color/primitives.css';
 @import './../tokens/color/semantic.css';
 @import './../tokens/typography/typography.css';

package/src/tokens/README.md

@@ -26,7 +26,7 @@
 |---|---|---|
 | `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 |
+| `motion/`(`--motion-delay-*`)| **Internal primitive** — DS overlay 元件內部消費,consumer 不直接用 | Tooltip / HoverCard / Avatar / OverflowIndicator 的 hover open / close delay;consumer 用元件預設,不直接讀 token |
 
 **Internal token 規則**(`uiSize/` / `motion/` 適用):
 - **不必補 Storybook stories**(consumer 不直接看;審查 grep 結果:`src/app` + `src/explorations` 0 個檔案直接消費 uiSize token,2026-05-17 verified)

package/src/tokens/color/color.spec.md

@@ -113,12 +113,12 @@ disabled 元件內的所有子元素必須呈現 disabled 狀態:
 
 ### 兩種 disabled 策略:何時用哪個
 
-系統有**兩種** disabled 視覺處理方式,判準是「**顏色是否是 semantic state 的唯一視覺載體**」:
+系統有**兩種** disabled 視覺處理方式,判準是「**顏色是否是 semantic state 的主視覺載體**」:
 
 | 策略 | 何時用 | 消費者 | 做法 |
 |---|---|---|---|
 | **灰階 token swap** | State 由形狀 / 位置 / icon / 文字 等**非顏色載體**承載,顏色只是美學 | Button、Checkbox、Input、Slider、Tag | 每個元素換到 disabled 對應的灰階 token(`bg-disabled` / `text-fg-disabled` / `bg-border` 等) |
-| **`opacity-disabled`** | State **完全只靠顏色區分**(形狀在 on/off 之間沒有差異),灰階化會丟失 state 辨識 | **Switch** | Root 層套 `opacity-disabled`,保留原有顏色身分,透過透明度均勻降級 |
+| **`opacity-disabled`** | State **主要靠顏色區分**(殘餘線索如 thumb 位移 / 小 icon 在灰階低對比下太弱),灰階化會使 state 辨識大幅下降 | **Switch** | Root 層套 `opacity-disabled`,保留原有顏色身分,透過透明度均勻降級 |
 
 **具體判準(寫新元件時問自己)**:
 1. 在 disabled 狀態下,使用者需要辨識的 state 資訊是什麼?
@@ -229,7 +229,7 @@ Icon 色彩 canonical 的 SSOT 住 `patterns/element-anatomy/item-anatomy.spec.m
   | 底色 | 文字色 | 原因 |
   |------|--------|------|
   | `bg-warning`（yellow-6，滿版） | `text-on-emphasis-dark`（`black-a85`，深色） | 黃色亮度高，白字對比不足，必須用深色（通用亮底深字 token，非 warning 專屬；定義見下「`--on-emphasis` / `--on-emphasis-dark` 配對」段） |
-  | `bg-warning-subtle`（淡黃） | `text-[yellow-7]`（step-7） | subtle 底色夠淺，深一階的黃色文字可辨識（見「文字色 Step 原則」） |
+  | `bg-warning-subtle`（淡黃） | `text-warning-text`（semantic，= `--color-yellow-7` step-7） | subtle 底色夠淺，深一階的黃色文字可辨識（見「文字色 Step 原則」）；Notice / Alert code 消費的即是此 semantic utility，不硬寫 primitive 色名 |
 
 ### Indicator — Notification
 

package/src/tokens/color/color.stories.tsx

@@ -8,7 +8,7 @@ const meta: Meta = {
     docs: {
       description: {
         component: `
-色彩 token 系統。元件只使用語義 token，不直接引用原始色票。
+色彩 token 系統。互動 / 狀態語意一律使用語義 token；categorical 靜態多色場景（Tag / Avatar / Calendar event）依 spec 直接消費 primitive 色票（見 color.spec.md「消費規則」）。
 
 完整規則：\`packages/design-system/src/tokens/color/color.spec.md\`
         `,
@@ -85,7 +85,7 @@ export const Primitives: Story = {
     docs: {
       description: {
         story:
-          '原始色票（Layer 1）。元件**不得直接使用**，一律透過語義 token。\n\n' +
+          '原始色票（Layer 1）。互動 / 狀態語意**不得直接使用** primitive，一律透過語義 token；例外：Tag / Avatar / Calendar 等 categorical 多色區分場景直接消費 primitive（color.spec.md「消費規則」）。\n\n' +
           '**已映射為語義 token 的色相：** blue → primary、deep-orange → error + notification、green → success、yellow → warning\n\n' +
           '**其餘色相（orange、amber、lime、turquoise、indigo、purple、magenta、red）** 保留給 data visualization、categorization tag、avatar 等需要多色區分的場景。',
       },
@@ -223,7 +223,7 @@ export const Semantic: Story = {
     docs: {
       description: {
         story:
-          'Primary = 互動入口（按鈕、連結）。Info = 系統狀態（in-progress、active）。subtle 為淡底填充，用於 tag、banner、checked 背景。',
+          'Primary = 互動入口（按鈕、連結）。Info = 系統狀態（in-progress、active）。subtle 為淡底填充，用於 badge、banner、checked 背景（Tag 的多色淡底走 categorical primitive step-1，非 semantic subtle，見「原始色票」）。',
       },
     },
   },

package/src/tokens/density/density.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react'
+import { Button } from '@/design-system/components/Button/button'
 
 const meta: Meta = {
   title: 'Design System/Tokens/Density',
@@ -178,7 +179,7 @@ export const LayoutSpace: Story = {
   parameters: {
     docs: {
       description: {
-        story: '版面間距 token。用於頁面側邊、header 內距、底部留白。',
+        story: '版面間距 token。用於頁面側邊、header 內距、內容到 action buttons 的結論留白。',
       },
     },
   },
@@ -187,7 +188,10 @@ export const LayoutSpace: Story = {
       <ColHeader cols={LS_COLS} />
       <TokenRow attr="data-layout-space" cols={LS_COLS} token="--layout-space-loose"  md="16px" lg="24px" desc="頁面側邊、內容區外層" isSolid={false} />
       <TokenRow attr="data-layout-space" cols={LS_COLS} token="--layout-space-tight"  md="12px" lg="16px" desc="Header 上下內距" isSolid={false} />
-      <TokenRow attr="data-layout-space" cols={LS_COLS} token="--layout-space-bottom" md="48px" lg="48px" desc="頁面底部留白" isSolid={false} />
+      {/* 2026-07-14 audit Dim 68:bottom ≠ 通用「頁面底部留白」— layoutSpace.spec.md 定義為
+          「結論留白:內容到 action buttons(commitment 前視覺暫停)」;無 action 的容器底依
+          bounded / unbounded / element 用 loose / 0 / tight(spec 規則 4)*/}
+      <TokenRow attr="data-layout-space" cols={LS_COLS} token="--layout-space-bottom" md="48px" lg="48px" desc="內容 → action buttons 結論留白" isSolid={false} />
     </div>
   ),
 }
@@ -223,9 +227,18 @@ export const PageLayout: Story = {
             ))}
           </div>
         </div>
+        {/* 2026-07-14 audit Dim 68:bottom 是「內容 → action buttons」結論留白(layoutSpace.spec.md
+            規則 4 line 1)— 原 demo 把它畫成無 action 的通用頁尾 band = 教錯用法。補 action row
+            讓 48px 留白真的落在 content 與 commitment 之間。 */}
         <div style={{ height: 'var(--layout-space-bottom)', borderTop: '1px dashed var(--border)' }}
           className="flex items-center justify-center">
-          <span className="text-caption text-fg-muted">bottom space</span>
+          <span className="text-caption text-fg-muted">bottom 48 — 內容 → action 結論留白</span>
+        </div>
+        <div
+          className="flex justify-end"
+          style={{ padding: `0 var(--layout-space-loose) var(--layout-space-tight)` }}
+        >
+          <Button variant="primary">儲存變更</Button>
         </div>
       </div>
     )

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

@@ -2,7 +2,7 @@
 
 # LayoutSpace 設計原則
 
-Layout Space 定義頁面與容器的巨觀間距 token,隨 density 自動縮放(透過 `data-density` 或 `data-layout-space`)。
+Layout Space 定義頁面與容器的巨觀間距 token,隨 density 自動縮放(透過 `data-density` 或 `data-layout-space`)。另 **co-locate 一組 item 級 micro token** `--item-gap-label-desc-*`(label ↔ description 2px gap,概念 owner = `patterns/element-anatomy`,見下「Co-located:item-gap tokens」)。
 
 ## Token 表
 
@@ -12,6 +12,8 @@ Layout Space 定義頁面與容器的巨觀間距 token,隨 density 自動縮放
 | `--layout-space-tight` | 12px | 16px | 緊湊間距:Header → element、functional 交互的元素之間 |
 | `--layout-space-bottom` | 48px | 48px | 結論留白:內容到 action buttons(commitment 前視覺暫停)|
 
+**Co-located:item-gap tokens** — `layoutSpace.css` 另定義 `--item-gap-label-desc-{reading,reading-lg,scanning,scanning-lg}`(皆 2px):**非**巨觀 layout token,是 item 內 label ↔ description 的 typography-mode-aware micro gap;設計 SSOT 在 `item-anatomy.spec.md`「Label ↔ Desc 間距」段,本檔只是 CSS 住所。修改值 / 加 mode → 走 item-anatomy spec。
+
 **為什麼 bottom 不隨 density 變**:48px 是「結論前的留白」— content 到 action buttons 的視覺暫停。跟 density 無關(不論 compact 或 comfortable,使用者都需要「commitment 前」的節奏)。
 
 ---

package/src/tokens/motion/motion.css

@@ -1,30 +1,42 @@
 /**
- * Motion tokens — hover delay tier system.
+ * Motion tokens — 統一 `--motion-*` family(2026-07-11 unify + 加進出場動畫 token)。
  *
- * 2026-05-18 ship per user 拍板 #3A(3-tier hover delay token + 確保命名世界級)。
+ * Naming convention(對齊 token-system.spec.md 規則 1 family-scoped + Material `md-sys-motion-*`
+ * / Polaris `p-motion-*` / Carbon motion 三家 namespace 共識):
+ *   --motion-<measurement>-<variant>
+ *   grep `--motion-` 即抓齊全 motion family。
  *
- * Naming convention:
- *   --hover-delay-{tier}
+ * ── 2 個 sub-measurement family ──
  *
- * Tier semantics 對齊 world-class consensus(see motion.spec.md「世界級對照」段):
- *   - plain  → passive hint  | Tooltip 文字提示    | 500ms  | Material 3 / Apple HIG / shadcn-Radix default 主流共識
- *   - rich   → rich preview  | HoverCard / ProfileCard | 700ms  | 含 fetch / multi-section,避免列表掃視誤觸發
- *   - close  → universal exit| 全部關閉延遲          | 200ms  | UX research consensus accidental-hover 容錯
+ * (A) delay(何時開/關 — hover open/close 延遲;Radix delayDuration/openDelay/closeDelay 吃 JS 鏡像)
+ *   - plain 500ms → Tooltip 純文字提示(被動 hint,對齊 Material 3 / Apple HIG / shadcn-Radix 主流)
+ *   - rich  700ms → HoverCard / ProfileCard 內容預覽(含 fetch,避免列表掃視誤觸發)
+ *   - close 200ms → 全 overlay 關閉延遲(close ≤ open UX 共識,user 誤滑出可回來)
+ *   (2026-05-18/20 user 拍板 #3A;原名 `--hover-delay-*`,2026-07-11 統一前綴為 `--motion-delay-*`)
  *
- * 2026-05-20 user 拍板「太快很容易干擾人」+ B 選項(plain 500 / rich 700):
- *   - plain 200 → 500ms:對齊 Material 3 plain tooltip 500ms + Apple HIG ~500ms + shadcn-Radix default 500ms
- *     主流共識(MUI 100ms / Ant 100ms 是 fast-tier 例外);200ms 偏快會打擾滑過列表的 user
- *   - rich 300 → 700ms:HoverCard 含 fetch + multi-section(ProfileCard avatar / actions),
- *     需 user「真停留」才觸發;300ms 列表掃視易觸發 N 次 fetch
- *   - close 200ms 維持:close delay ≤ open delay UX 共識(user 誤滑出可回來)
- *
- * Rationale 命名:不用 component name(`tooltip` 太特定)、不用純數字(`delay-200` 用值不用語意)、
- * 不用孤立縮寫(`hd-fast` 跨人不可讀)。`plain` / `rich` / `close` 對齊 Material rich-tooltip 公開文件 +
- * DS 既有 `compact / rich` mode 詞彙一致(per `# 命名與語言一致性` 命名 3 test)。
+ * (B) 進出場動畫(fade/zoom/slide 的 duration / easing / 幾何 — CSS 驅動,由 tw-animate-css 消費)
+ *   全部世界級實證(見 motion.spec.md「世界級對照」+ planning/2026-07-11-overlay-motion-tokens.md):
+ *   - duration-overlay 150ms:輕量浮層(Tooltip/Popover/HoverCard/DropdownMenu)。
+ *       Material short3 / Carbon moderate-01 / Polaris 150 / tw-animate-css 預設 **四家一致**。
+ *   - duration-surface 250ms:模態面板(Dialog/Sheet/FileViewer,面積大位移遠 → 慢一階)。
+ *       Material medium1 / Polaris 250 / Carbon moderate-02(240)。
+ *   - easing-enter cubic-bezier(0,0,0,1):進場減速(Material standard-decelerate,企業級中性沉穩)。
+ *   - easing-exit  cubic-bezier(0.3,0,1,1):出場加速(Material standard-accelerate)。
+ *   - enter-distance 0.5rem(8px):slide 位移,沿用現行 slide-*-2 = shadcn/Radix canonical。
+ *   - enter-scale 0.95:zoom scale,沿用現行 zoom-95 = shadcn default。
  */
 
 :root {
-  --hover-delay-plain: 500ms;
-  --hover-delay-rich: 700ms;
-  --hover-delay-close: 200ms;
+  /* (A) delay */
+  --motion-delay-plain: 500ms;
+  --motion-delay-rich: 700ms;
+  --motion-delay-close: 200ms;
+
+  /* (B) 進出場動畫 */
+  --motion-duration-overlay: 150ms;
+  --motion-duration-surface: 250ms;
+  --motion-easing-enter: cubic-bezier(0, 0, 0, 1);
+  --motion-easing-exit: cubic-bezier(0.3, 0, 1, 1);
+  --motion-enter-distance: 0.5rem;
+  --motion-enter-scale: 0.95;
 }

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

@@ -23,15 +23,15 @@ benchmark:
 
 Hover delay token 是「hover 觸發 → 延遲 N ms → overlay 顯示」的延遲時間(對齊 token 名 `delay` 術語)。**目的不是動畫長度,是「user 真的想看」過濾器** — 短暫滑過不該觸發 expensive overlay(ProfileCard fetch 資料 / Tooltip 視覺擾動)。
 
-**Scope 邊界**:本 token 系統僅管 hover open / close 延遲;overlay 開啟後的 fetch loading 視覺(skeleton / 留空)屬各 consumer 元件 spec(HoverCard / ProfileCard),不在 motion token scope。
+**Scope**:motion token 統一在 `--motion-*` 前綴下,兩個 sub-family:(A)**delay**(hover 開/關延遲,見下)(B)**進出場動畫**(overlay fade/zoom/slide 的 duration/easing/幾何,見「進出場動畫 token」段)。overlay 開啟後的 fetch loading 視覺(skeleton / 留空)屬各 consumer 元件 spec,不在 motion token scope。
 
 ## 三層 tier 系統
 
 | Token | 值 | 用於 | 為何 |
 |---|---|---|---|
-| `--hover-delay-plain` | `500ms` | Tooltip 純文字提示 | 被動 hint,需 user「真停留」才觸發,避免滑過列表時 N 次視覺擾動。對齊 Material 3 plain tooltip 500ms / Apple HIG ~500ms / shadcn-Radix default 500ms 主流共識 | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
-| `--hover-delay-rich` | `700ms` | HoverCard / ProfileCard 內容預覽 | 含 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}` 值 |
+| `--motion-delay-plain` | `500ms` | Tooltip 純文字提示 | 被動 hint,需 user「真停留」才觸發,避免滑過列表時 N 次視覺擾動。對齊 Material 3 plain tooltip 500ms / Apple HIG ~500ms / shadcn-Radix default 500ms 主流共識 | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+| `--motion-delay-rich` | `700ms` | HoverCard / ProfileCard 內容預覽 | 含 avatar / fields / actions 的 rich content(可能含 fetch)。User 必須「真的想看」才停留 700ms,避免列表掃視時誤觸發 N 個 fetch waterfall |
+| `--motion-delay-close` | `200ms` | 所有 overlay 關閉 | Mouse leave 後給 200ms 緩衝(user 可能誤滑出再回來)。對齊 UX 共識「close delay ≤ open delay」+ 既有 Avatar `closeDelay={200}` 值 |
 
 ## 為何不用單一值 / 為何不沿用過去 200ms
 
@@ -45,11 +45,11 @@ Hover delay token 是「hover 觸發 → 延遲 N ms → 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 |
+| Icon-only Button → 顯示文字提示 | `--motion-delay-plain` | 純文字輔助 |
+| Avatar / Username → 顯示完整人物卡 | `--motion-delay-rich` | 含 fetch + multi-section content |
+| OverflowIndicator → 顯示隱藏列表 | `--motion-delay-plain` | 純列表展開,無 fetch |
+| Tag / Chip → 顯示說明 | `--motion-delay-plain` | 純文字 |
+| 任何 overlay 關閉延遲 | `--motion-delay-close` | universal |
 | Click-triggered Popover / Dialog | — | N/A,click 不適用 hover delay |
 | Tooltip 鍵盤 focus 觸發 | — | N/A,直接顯示(對齊 WAI-ARIA APG) |
 
@@ -61,18 +61,18 @@ Hover delay token 是「hover 觸發 → 延遲 N ms → overlay 顯示」的延
 
 ### Anti-pattern 避免命名
 
-- ❌ `--hover-delay-tooltip` / `--hover-delay-hovercard` — 元件名綁定 → 新元件(Popover variant)用哪個?
+- ❌ `--motion-delay-tooltip` / `--motion-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` — HoverCard openDelay / closeDelay 消費 `HOVER_DELAY_RICH_MS` / `HOVER_DELAY_CLOSE_MS`(原硬寫 300/200,migrate 到 token)
-- `components/HoverCard/hover-card.tsx` — Root 預設 `openDelay`=`--hover-delay-rich` / `closeDelay`=`--hover-delay-close`(Radix HoverCard 無 Provider;2026-06-11 落地,原宣稱與 code 脫鉤)
-- `components/Tooltip/tooltip.tsx` — Radix Provider 預設 delayDuration override 為 `--hover-delay-plain`
-- `components/ProfileCard/profile-card.tsx`(consumer of HoverCard)— 繼承 `--hover-delay-rich`
-- `components/OverflowIndicator/overflow-indicator.tsx`(consumer)— 用 `--hover-delay-plain`
+- `components/Avatar/avatar.tsx` — HoverCard openDelay / closeDelay 消費 `MOTION_DELAY_RICH_MS` / `MOTION_DELAY_CLOSE_MS`(原硬寫 300/200,migrate 到 token)
+- `components/HoverCard/hover-card.tsx` — Root 預設 `openDelay`=`--motion-delay-rich` / `closeDelay`=`--motion-delay-close`(Radix HoverCard 無 Provider;2026-06-11 落地,原宣稱與 code 脫鉤)
+- `components/Tooltip/tooltip.tsx` — Radix Provider 預設 delayDuration override 為 `--motion-delay-plain`
+- `components/ProfileCard/profile-card.tsx`(consumer of HoverCard)— 繼承 `--motion-delay-rich`
+- `components/OverflowIndicator/overflow-indicator.tsx`(consumer)— 用 `--motion-delay-plain`
 - 任何 future overlay hover consumer 必 import 此 token(per M17 SSOT 必可傳播)
 
 ## 世界級對照
@@ -103,3 +103,20 @@ Hover delay token 是「hover 觸發 → 延遲 N ms → overlay 顯示」的延
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `hover-card.spec.md`
+
+## 進出場動畫 token(2026-07-11 加,user 拍板)
+
+Overlay(Tooltip/Popover/HoverCard/DropdownMenu/Dialog/Sheet/FileViewer)的 fade/zoom/slide 進出場動畫,值統一 token 化(原各元件硬寫 zoom-95/slide-2/duration-300 = M17 假 SSOT)。由 tw-animate-css(Tailwind v4,= shadcn 官方機制)的 `--tw-duration`/`--tw-ease` 變數綁定;共用 SSOT = `overlay-motion.ts`(overlayMotion/surfaceMotion)。
+
+| Token | 值 | 用於 | 世界級對照 |
+|---|---|---|---|
+| `--motion-duration-overlay` | `150ms` | 輕量浮層(Tooltip/Popover/HoverCard/DropdownMenu) | Material short3 / Carbon moderate-01 / Polaris 150 / tw-animate-css 預設 **四家一致** |
+| `--motion-duration-surface` | `250ms` | 模態面板(Dialog/Sheet/FileViewer,面積大位移遠→慢一階) | Material medium1 / Polaris 250 / Carbon moderate-02(240) |
+| `--motion-easing-enter` | `cubic-bezier(0,0,0,1)` | 進場(減速,快起平滑落定) | Material standard-decelerate(企業級中性沉穩) |
+| `--motion-easing-exit` | `cubic-bezier(0.3,0,1,1)` | 出場(加速) | Material standard-accelerate |
+| `--motion-enter-distance` | `0.5rem`(8px) | slide 位移 | shadcn/Radix canonical(= 現行 slide-*-2) |
+| `--motion-enter-scale` | `0.95` | zoom scale | shadcn default(= 現行 zoom-95) |
+
+**幾何原型分層(正當差異,不強行抹平)**:輕量 popup = fade+zoom+slide-side(8px);模態置中 = fade+zoom+slide-center(Dialog/FileViewer);邊緣抽屜 = slide-edge 100%、正當無 zoom(Sheet)。統一的是**時長/曲線/reduced-motion 守衛**(motion-reduce:animate-none 全 7 浮層),非幾何原型(對齊 Material standard-vs-emphasized / Carbon productive-vs-expressive tier 分層)。
+
+**a11y**:prefers-reduced-motion 下 `motion-reduce:animate-none` 全 7 浮層統一關進出場動畫(overlay-motion SSOT 保證,無漏)。