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

package/src/tokens/elevation/elevation.stories.tsx

@@ -0,0 +1,99 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import React from 'react'
+
+const meta: Meta = {
+  title: 'Design System/Tokens/Elevation',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: `
+陰影系統。兩個層級對應兩種「浮起高度」，用 CSS 變數 \`box-shadow\` 實現。Light / dark mode 自動切換。
+
+完整規則：\`packages/design-system/src/tokens/elevation/elevation.spec.md\`
+
+**⚠️ \`--elevation-200\` 的容器必須搭配 \`bg-surface-raised\`（不透明）。**
+        `,
+      },
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj
+
+
+function SectionLabel({ children }: { children: React.ReactNode }) {
+  return (
+    <p className="mb-3 text-caption font-medium uppercase tracking-wider text-fg-muted">
+      {children}
+    </p>
+  )
+}
+
+
+export const Overview: Story = {
+  name: '總覽',
+  render: () => (
+    <div className="space-y-8">
+      <div>
+        <SectionLabel>elevation-100 — Card</SectionLabel>
+        <div className="flex flex-wrap gap-8">
+          <div
+            className="flex h-24 w-48 flex-col items-start justify-end rounded-md border border-border bg-surface p-4"
+            style={{ boxShadow: 'var(--elevation-100)' }}
+          >
+            <code className="text-caption font-medium">--elevation-100</code>
+            <span className="text-caption text-fg-muted">靜止狀態</span>
+          </div>
+          <div
+            className="flex h-24 w-48 flex-col items-start justify-end rounded-md border border-border bg-surface p-4"
+            style={{ boxShadow: 'var(--elevation-100-hover)' }}
+          >
+            <code className="text-caption font-medium">--elevation-100-hover</code>
+            <span className="text-caption text-fg-muted">hover / 拖拽</span>
+          </div>
+        </div>
+      </div>
+
+      <div>
+        <SectionLabel>elevation-200 — Modal / Popover / Dropdown</SectionLabel>
+        <div className="flex flex-wrap gap-8">
+          <div
+            className="flex h-24 w-48 flex-col items-start justify-end rounded-lg border border-border bg-surface-raised p-4"
+            style={{ boxShadow: 'var(--elevation-200)' }}
+          >
+            <code className="text-caption font-medium">--elevation-200</code>
+            <span className="text-caption text-fg-muted">靜止狀態</span>
+          </div>
+          <div
+            className="flex h-24 w-48 flex-col items-start justify-end rounded-lg border border-border bg-surface-raised p-4"
+            style={{ boxShadow: 'var(--elevation-200-hover)' }}
+          >
+            <code className="text-caption font-medium">--elevation-200-hover</code>
+            <span className="text-caption text-fg-muted">hover 狀態</span>
+          </div>
+        </div>
+      </div>
+
+      <div>
+        <SectionLabel>層級對比 — Card 在下，Popover 浮在上</SectionLabel>
+        <div className="relative flex h-52 w-full max-w-lg items-center justify-center rounded-md bg-canvas">
+          <div
+            className="absolute left-8 top-8 h-28 w-40 rounded-md border border-border bg-surface p-3"
+            style={{ boxShadow: 'var(--elevation-100)' }}
+          >
+            <span className="text-caption text-fg-muted">Card（100）</span>
+          </div>
+          <div
+            className="absolute bottom-6 right-6 h-28 w-44 rounded-lg border border-border bg-surface-raised p-3"
+            style={{ boxShadow: 'var(--elevation-200)' }}
+          >
+            <span className="text-caption text-fg-muted">Popover（200）</span>
+          </div>
+        </div>
+      </div>
+    </div>
+  ),
+}

package/src/tokens/layoutSpace/layoutSpace.css

@@ -13,7 +13,7 @@
      備註:本 DS「配對」(uiSize.spec.md)專指 Tag↔Field 等**元件 size 配對**,
      跟本 token 表達的「label + desc typography 組合」不同概念,勿混淆。 */
   --item-gap-label-desc-reading:     2px;  /* reading:    body(14/1.5)    + body(14/1.5) — SelectionItem sm-md / Switch sm-md / DescriptionList / item-anatomy reading row */
-  --item-gap-label-desc-reading-lg:  2px;  /* reading-lg: body-lg(16/1.5) + body(14/1.5) — Dialog / Sheet / Empty / FileUpload / Coachmark / NameCard / SelectionItem lg / Switch lg */
+  --item-gap-label-desc-reading-lg:  2px;  /* reading-lg: body-lg(16/1.5) + body(14/1.5) — Dialog / Sheet / Empty / FileUpload / Coachmark / ProfileCard / SelectionItem lg / Switch lg */
   --item-gap-label-desc-scanning:    2px;  /* scanning:   body(14/1.3)    + caption(12/1.3) — FileItem compact+rich / MenuItem sm-md / Steps sm-md */
   --item-gap-label-desc-scanning-lg: 2px;  /* scanning-lg:body-lg(16/1.3) + body(14/1.3) — MenuItem lg / Steps lg */
 }

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

@@ -1,8 +1,8 @@
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline(M22(d) 顯式撤回;本檔 frontmatter 無 benchmark list,來源 URL 未補)。 -->
 
 # 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 前」的節奏)。
 
 ---
@@ -105,7 +107,7 @@ Pattern C 的視覺邏輯見 `overlay-surface.spec.md`「Hover bg 貼邊 chrome
 
 **核心**: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 -->
+世界級對齊:Material 3 / Polaris / Apple HIG / Atlassian 都按「relationship not type」決定 spacing。 <!-- @benchmark-unverified -->
 
 ### 規則 4:底部 — 拆兩個 distinct 概念
 
@@ -137,22 +139,36 @@ Pattern C 的視覺邏輯見 `overlay-surface.spec.md`「Hover bg 貼邊 chrome
 
 **為何 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 -->
+**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 -->
 
 **禁止**:硬寫 `px-4` / 自創值(`px-5`)/ 用 tight 當 chrome inline / 同 surface header/body/footer inline padding 不一致(三層左邊界必對齊)。
 
+**RTL**:本系統水平 padding 一律 `px-*`(左右對稱、無方向性),RTL 下行為不變;方向性 spacing(`ps-*`/`pe-*`)未使用。
+
+---
+
+## 該用 token(縮放)vs 刻意固定(magic number 合法)的邊界(2026-07-01 codify)
+
+**核心**:layout-space token(density-scaling)只管 **macro 結構間距**;**不是所有 px 都該 token 化**。硬把刻意固定值 token 化 = over-tokenize(反 pattern,跟「硬寫該縮放的 gap」同樣是 bug 的反面)。
+
+| 該用 layout-space token(density-scaling) | 刻意固定值 OK(magic number 合法) |
+|---|---|
+| 並列獨立 **區塊 / 卡片 / 表單欄位** 之間(規則 3 parallel = loose)| **同質 list 的列間距**(一串同類 rows,規則 3「同範疇 spec-own」)|
+| **Header → 內容**(規則 2 = tight)| **micro / icon / 控件內部** 間距(gap-1/2、icon padding)|
+| **Chrome 水平內距**(規則 6 = loose)| **為視覺平衡 / 對稱 刻意調的值**(設計裁量)|
+| **內容 → action button**(規則 4 = bottom 48)| **元件自身刻意固定**(如 FieldGroup 三級固定 gap,不隨 density)|
+
+**判準一句話**:是「並列/區塊/chrome/header→content/content→action 的 macro 結構間距、規則說該縮放」→ 用 token;是「list 列間距 / micro / 刻意固定 / 元件內部決定」→ magic number 合法,**不要 token 化**。
+
+**機械強制**:`check_layout_space_magic_numbers.sh` 只自動放行 `utility-registry.json#/spacing/canonical_micro_geometry` 能用同行或有界 nearby 證據證明的子集:inline item/control、semantic homogeneous list/list row、`role="toolbar"` control cluster、以及「group 語意 + 至少兩個 nearby Field/input」的規則 5 橫排 fields。只看到一般 `flex/grid/section gap-1/2`、或同行還混有 `p-/m-/space-*` magic 都仍 BLOCK；不新增 CSS/UI token。`check_escape_marker_abuse.sh` 共用同一 classifier,已被結構證明且不再繞 gate 的舊 micro marker 不消耗 ceiling。`check_tabs_content_chrome_body_double_gap.sh` Check 2 另抓「浮層 body 自身固定 macro gap」。其餘判斷題(這是並列還是 list?macro 還是 micro?)仍靠 **週期 LLM sweep**(`/design-system-audit` dim「layout-space macro 合規」)—— 不將無語意證據的 regex 擴張成全放行(否則會 over-flag 或漏掉真 macro)。
+
 ---
 
 ## 心智模型(三步推理 + 具體 self-questions)
 
 ### Step 1 — 判角色(對單一元素)
 
-問 3 題:
-1. 在該層 layout 占主導(寬度撐滿 + 高度 flex-1)嗎?
-2. 視覺重量是「畫布」(占據 layout)還是「控件」(局部塊)?
-3. 是該層展示主角(主導內容)嗎?
-
-多數 yes → **region**;反之 → **element**。
+跑上方「元件角色」節的**判斷 3 題**(占主導? / 畫布 vs 控件? / 展示主角?)— 多數 yes → **region**;反之 → **element**。
 
 若 region 再問 1 題:有視覺邊界(底色 / 邊框 / 上下分隔線)嗎?
 - 有 → **bounded**(Card / Table with borders / Panel)
@@ -195,7 +211,7 @@ Pattern C 的視覺邏輯見 `overlay-surface.spec.md`「Hover bg 貼邊 chrome
 - **判親疏**:
   - 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 -->
+- **答**:`loose`(16/24)— 對齊 Material / Polaris / Apple HIG / Atlassian 共識 <!-- @benchmark-unverified -->
 
 ### 範例 2:Cmd+K menu 中 search input ↔ result list
 
@@ -221,16 +237,16 @@ Pattern C 的視覺邏輯見 `overlay-surface.spec.md`「Hover bg 貼邊 chrome
 
 - **走規則**:規則 4
 - **判**:後接 action button(在 SurfaceFooter 內)?**是** → 套 `bottom 48`
-- **答**:48(概念 A commitment 前留白)。`dialog.tsx:203` body 預設 `pb-bottom` 是此規則的實作(預期 body 後接 SurfaceFooter buttons),非 Dialog 例外
+- **答**:48(概念 A commitment 前留白)。`dialog.tsx` DialogBody 預設 `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
+- **答**:`gap-2`(8)— 由 `button-group.tsx:51` / `overlay-surface.tsx` SurfaceFooter 自帶 canonical own
 
-**注意**:規則 5「橫排並列」**只**適用 input fields(line 102 明文),不套 button group。Button spacing 屬 bundled-family canonical,不走 layoutSpace 一般 rule。
+**注意**:規則 5「橫排並列」**只**適用 input fields,不套 button group(button spacing 屬 bundled-family canonical own,不走 layoutSpace 一般 rule)。
 
 ---
 
@@ -270,19 +286,20 @@ Pattern C 的視覺邏輯見 `overlay-surface.spec.md`「Hover bg 貼邊 chrome
 
 ---
 
-## 模式切換
+## 常見誤解
 
-```html
-<html data-density="md">
-```
+- ❌ **元素間 gap 硬寫 `gap-4`**:容器級 gap 走規則 3 token(`tight` / `loose`);固定 `gap-2` / `gap-4` 只限規則 5 橫排 input 與 bundled family 自帶 canonical
+- ❌ **Pattern C 場景把 padding 寫在 list 容器**:hover bg 需 flush 貼邊,padding 必須 item 自帶(規則 1C);寫在容器 = hover bg 縮一圈
+- ❌ **unbounded list 漏自帶 py**:規則 2 / 4 的「0」前提是 list 自帶 py 撐 spacing;漏 py = 內容貼 chrome 邊
 
-```ts
-document.documentElement.setAttribute('data-density', 'lg')
-```
+---
 
-單獨控制版面間距而不影響元件尺寸:
+## 模式切換
 
 ```ts
+// 全域 density(含 layout space)
+document.documentElement.setAttribute('data-density', 'lg')
+// 單獨控制版面間距而不影響元件尺寸
 document.documentElement.setAttribute('data-layout-space', 'lg')
 ```
 
@@ -292,7 +309,8 @@ document.documentElement.setAttribute('data-layout-space', 'lg')
 
 - **不抽 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`
+- **Tabs-in-chrome-body 單一 gap owner**(2026-07-01 canonical):`tabsSlot` 模式下 `TabsContent` 放進 `DialogBody`/`SheetBody`/`SurfaceBody`(自帶 `pt-/py-tight`)時**必 `className="mt-0"`** — chrome body 已擁有 header→content gap(規則 2「element → tight」),TabsContent 內建 `mt-tight` 會雙重疊加(md 24 / lg 32)。同「一軸單一 spacing owner」原則(`item-anatomy.spec.md`「垂直 padding 歸屬 / 禁雙重 padding」)。詳 `components/Tabs/tabs.spec.md`「出現在 Dialog」段 + hook `check_tabs_content_chrome_body_double_gap.sh`
+- **v1 → v6**(2026-04-30):block-adjacent 機械 → 親疏判 + bundled-family 分權 + region 二分(bounded/unbounded)+ 多 region 限制。詳 git 歷史(原 memory `feedback_layout_v6_canonical.md` 已 prune)
 
 ---
 
@@ -300,15 +318,10 @@ document.documentElement.setAttribute('data-layout-space', 'lg')
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `app-shell.spec.md`
 - `description-list.spec.md`
-- `dialog.spec.md`
 - `empty.spec.md`
-- `file-viewer.spec.md`
 - `overlay-surface.spec.md`
+- `pagination.spec.md`
+- `token-system.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/layoutSpace/layoutSpace.stories.tsx

@@ -0,0 +1,76 @@
+import type { Meta, StoryObj } from '@storybook/react'
+
+const meta: Meta = {
+  title: 'Design System/Tokens/LayoutSpace',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: `
+版面間距 token 系統。定義 pattern 層級的「鬆 / 緊 / 底」間距,跟 \`--field-height\` 等元件 token 分層。
+
+完整規則:\`packages/design-system/src/tokens/layoutSpace/layoutSpace.spec.md\`
+
+**何時用 token vs Tailwind 數字 utility?**
+- pattern 結構間距(toolbar / surface header / row inside)→ token
+- 局部 fine-tune(icon 跟 label 距離,單 component 內)→ Tailwind \`gap-N\` OK
+        `,
+      },
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj
+
+
+function SpaceRow({ utility, mdValue, lgValue, usage }: {
+  utility: string
+  mdValue: string
+  lgValue: string
+  usage: string
+}) {
+  return (
+    <div className="grid items-center gap-x-6 gap-y-1 border-b border-border py-4 last:border-0"
+      style={{ gridTemplateColumns: '220px 80px 80px 1fr 100px' }}>
+      <div>
+        <code className="block text-caption font-medium text-fg-secondary">{utility}</code>
+      </div>
+      <div className="text-caption font-mono text-fg-muted">md: {mdValue}</div>
+      <div className="text-caption font-mono text-fg-muted">lg: {lgValue}</div>
+      <div className="text-body text-foreground">{usage}</div>
+      <div className="flex items-center justify-end">
+        <div aria-hidden="true" className="bg-primary h-6" style={{ width: mdValue }} />
+      </div>
+    </div>
+  )
+}
+
+
+export const Overview: Story = {
+  name: '總覽',
+  render: () => (
+    <div className="max-w-5xl">
+      <h2 className="text-h3 mb-2">Layout Space Tokens</h2>
+      <p className="text-body text-fg-secondary mb-6">
+        Pattern 層級間距 token,跟 density 連動(md / lg 兩個值)。下表展示 md density 預覽。
+      </p>
+
+      <SpaceRow utility="--layout-space-tight" mdValue="12px" lgValue="16px" usage="header / footer 上下 padding;緊密 inline gap" />
+      <SpaceRow utility="--layout-space-loose" mdValue="16px" lgValue="24px" usage="surface 左右 padding;tabs trigger gap;form field 間距" />
+      <SpaceRow utility="--layout-space-bottom" mdValue="48px" lgValue="48px" usage="Dialog / Sheet body 底部多一拍 + modal viewport inset(固定,不隨 density)" />
+
+      <h3 className="text-h5 mt-8 mb-2">使用規則</h3>
+      <ul className="list-disc pl-6 text-body text-fg-secondary space-y-1">
+        <li>跨範疇 + functional 交互 → <code>tight</code>(12/16);同範疇 / bundled → 元件 spec 自管</li>
+        <li>跨範疇 + parallel → <code>loose</code>(16/24)</li>
+        <li>容器最底部 → <code>bottom</code>(48 固定)</li>
+      </ul>
+
+      <p className="text-caption text-fg-muted mt-6">
+        實際 CSS 值見 <code>packages/design-system/src/tokens/layoutSpace/layoutSpace.css</code>;規則 6 條(親疏判)詳 spec.md。
+      </p>
+    </div>
+  ),
+}

package/src/tokens/motion/motion.css

@@ -1,30 +1,59 @@
 /**
- * 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}
+ * ── 3 個 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 / NameCard | 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(NameCard avatar / actions),
- *     需 user「真停留」才觸發;300ms 列表掃視易觸發 N 次 fetch
- *   - close 200ms 維持:close delay ≤ open delay UX 共識(user 誤滑出可回來)
+ * (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。
  *
- * Rationale 命名:不用 component name(`tooltip` 太特定)、不用純數字(`delay-200` 用值不用語意)、
- * 不用孤立縮寫(`hd-fast` 跨人不可讀)。`plain` / `rich` / `close` 對齊 Material rich-tooltip 公開文件 +
- * DS 既有 `compact / rich` mode 詞彙一致(per `# 命名與語言一致性` 命名 3 test)。
+ * (C) 循環動態(repeatCount infinite 的呼吸/微光 loop — AgentPanel 家族引入,2026-09-02)
+ *   既有 easing-enter/exit 語意=單次進退場;循環動態的「起/收」是不同 measurement,故新增:
+ *   - easing-swell cubic-bezier(0.4,0.14,0.3,1):循環「起」段(吸氣/蓄勢)。
+ *       值=Carbon expressive 參考(carbondesignsystem.com motion/overview,productive/expressive 雙檔制)。
+ *   - easing-settle cubic-bezier(0.2,0,0.38,0.9):循環「收」段(吐氣/回落)。
+ *       值=Carbon productive 參考(同上)。
+ *   - duration-shimmer 2s:思考中文字微光週期(獨立於標誌 3s 一息家族)。
+ *       值=shadcn shimmer 逐字(ui.shadcn.com/docs/utils/shimmer:
+ *       `animation: tw-shimmer var(--shimmer-duration, 2s) linear infinite`;2026-09-02 實開頁複核)。
+ *   SMIL(SVG 動畫)無法消費 CSS var:agent-logo.tsx 內 keySplines 常數為 swell/settle
+ *   token 值的逐字鏡像(該檔檔頭註記;改值必同步兩處)。
  */
 
 :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;
+
+  /* (C) 循環動態 */
+  --motion-easing-swell: cubic-bezier(0.4, 0.14, 0.3, 1);
+  --motion-easing-settle: cubic-bezier(0.2, 0, 0.38, 0.9);
+  --motion-duration-shimmer: 2s;
 }

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

@@ -14,28 +14,30 @@ benchmark:
 
 <!-- @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 設計原則
+# Motion 設計原則
 
 > **Foundational SSOT rationale**(2026-05-18 ship per user 拍板 #3A):跨 5+ overlay 消費者
-> (Tooltip / HoverCard / NameCard / Avatar / OverflowIndicator)的 hover 開啟 / 關閉延遲統一。
+> (Tooltip / HoverCard / ProfileCard / Avatar / OverflowIndicator)的 hover 開啟 / 關閉延遲統一。
 
 ## 定位
 
-Hover delay token 是「hover 觸發 → overlay 顯示」之間的等待時間。**目的不是動畫長度,是「user 真的想看」過濾器** — 短暫滑過不該觸發 expensive overlay(NameCard fetch 資料 / Tooltip 視覺擾動)。
+Hover delay token 是「hover 觸發 → 延遲 N ms → overlay 顯示」的延遲時間(對齊 token 名 `delay` 術語)。**目的不是動畫長度,是「user 真的想看」過濾器** — 短暫滑過不該觸發 expensive overlay(ProfileCard fetch 資料 / Tooltip 視覺擾動)。
+
+**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 主流共識 |
-| `--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}` 值 |
+| `--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
 
 - **過去 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。
+- **MUI/Ant 100ms 是 fast-tier 例外**:適合 form input help text 等「我就是要快」的 dense 場景,不適合通用 chrome tooltip。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- **單一值** 失去 plain / rich 語意區分:ProfileCard 含 fetch + image + actions 應比 Tooltip(純文字)delay 長,單一值會讓 ProfileCard 滑過列表時整列誤觸發 fetch waterfall。
 - **過短**(< 100ms):每滑必觸發 → 視覺擾動 + 不必要 server request。
 - **過長**(> 1s):user 已不期待 overlay,等出來變干擾。
 
@@ -43,11 +45,11 @@ Hover delay token 是「hover 觸發 → 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) |
 
@@ -55,22 +57,22 @@ Hover delay token 是「hover 觸發 → overlay 顯示」之間的等待時間
 
 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)
+3. **跨元件無語意衝突**:`plain` 不撞 cva variant(無元件用 `variant="plain"`;Select / Combobox 另有 `display="plain"` prop value,屬不同 slot 且同「簡單呈現」語意方向,無認知衝突);`rich` 跟 FileItem mode 同義(content density gradient)
 
 ### 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: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`
+- `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 必可傳播)
 
 ## 世界級對照
@@ -86,7 +88,7 @@ Hover delay token 是「hover 觸發 → overlay 顯示」之間的等待時間
 | 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「真的想看」門檻。
+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「真的想看」門檻。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
 ## 相關
 
@@ -95,3 +97,25 @@ Hover delay token 是「hover 觸發 → overlay 顯示」之間的等待時間
 - `../../components/Tooltip/tooltip.spec.md`(consumer)
 - `../../components/HoverCard/hover-card.spec.md`(consumer)
 - `../../components/Avatar/avatar.spec.md`(consumer)
+## 進出場動畫 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 保證,無漏)。
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `hover-card.spec.md`