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

package/src/tokens/motion/motion.stories.tsx

@@ -0,0 +1,196 @@
+// @story-baseline: components/HoverCard/hover-card.stories.tsx#LinkPreview — 延遲體感 demo 消費真實 consumer(Button iconOnly auto-Tooltip + HoverCard 預設 delay),非手刻浮層
+import type { Meta, StoryObj } from '@storybook/react'
+import { Download } from 'lucide-react'
+import { Button } from '@/design-system/components/Button/button'
+import {
+  HoverCard,
+  HoverCardTrigger,
+  HoverCardContent,
+} from '@/design-system/components/HoverCard/hover-card'
+
+const meta: Meta = {
+  title: 'Design System/Tokens/Motion',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: `
+Motion token 系統。\`--motion-*\` 統一前綴下**兩個 sub-family**(2026-07-11 Phase 1-4 起;原「唯一家族 = hover delay」敘述已過時):
+
+**(A) delay 3-tier**(「hover 觸發 → 延遲 N ms → overlay 顯示」)——目的不是動畫長度,是「user 真的想看」過濾器。
+
+**(B) 進出場動畫**(overlay fade/zoom/slide 的 duration / easing / 幾何)——\`--motion-duration-{overlay,surface}\` + \`--motion-easing-{enter,exit}\` + \`--motion-enter-{distance,scale}\`,由 tw-animate-css 的 \`--tw-duration\` / \`--tw-ease\` 變數綁定;共用 SSOT = \`overlay-motion.ts\`(overlayMotion / surfaceMotion)。
+
+完整規則:\`packages/design-system/src/tokens/motion/motion.spec.md\`
+
+**JS mirror**:Radix props(\`delayDuration\` / \`openDelay\` / \`closeDelay\`)只吃 number 不認 CSS var,故 consumer 消費 \`motion.ts\` 的 \`MOTION_DELAY_PLAIN_MS\` / \`MOTION_DELAY_RICH_MS\` / \`MOTION_DELAY_CLOSE_MS\`(與 \`motion.css\` 同值鏡像)。
+        `,
+      },
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj
+
+
+function DelayRow({ token, value, usage, consumers }: {
+  token: string; value: string; usage: string; consumers: string
+}) {
+  return (
+    <div className="grid items-center gap-x-6 gap-y-1 border-b border-border py-4 last:border-0"
+      style={{ gridTemplateColumns: '200px 80px 1fr 220px' }}>
+      <div>
+        <code className="block text-caption font-medium text-fg-secondary">{token}</code>
+      </div>
+      <div className="text-caption font-mono text-fg-muted">{value}</div>
+      <div className="text-body text-foreground">{usage}</div>
+      <div className="text-caption text-fg-muted">{consumers}</div>
+    </div>
+  )
+}
+
+
+export const Overview: Story = {
+  name: '總覽',
+  render: () => (
+    <div className="max-w-4xl">
+      <h2 className="text-h3 mb-2">Hover Delay Tokens</h2>
+      <p className="text-body text-fg-secondary mb-6">
+        三層 tier:<code>plain</code>(被動文字提示)/ <code>rich</code>(含 fetch 的內容預覽,門檻更高)/
+        <code>close</code>(通用關閉緩衝)。命名對齊 Material 3「plain / rich tooltip」術語 +
+        DS 既有 <code>compact / rich</code> mode 詞彙。
+      </p>
+
+      <DelayRow
+        token="--motion-delay-plain"
+        value="500ms"
+        usage="純文字提示——被動 hint,user 真停留才觸發,避免滑過列表時 N 次視覺擾動"
+        consumers="Tooltip / OverflowIndicator"
+      />
+      <DelayRow
+        token="--motion-delay-rich"
+        value="700ms"
+        usage="內容預覽——含 fetch / multi-section,避免列表掃視誤觸發 fetch waterfall"
+        consumers="HoverCard / ProfileCard / Avatar"
+      />
+      <DelayRow
+        token="--motion-delay-close"
+        value="200ms"
+        usage="通用關閉緩衝——mouse leave 後 200ms 內移回不會關(誤滑出容錯)"
+        consumers="所有 hover overlay"
+      />
+
+      {/* 2026-07-14 Dim 68 修:補 (B) 進出場動畫 sub-family 展示 — 原頁只列 delay,
+          與 motion.css / motion.spec.md 兩 sub-family 現況 drift(「系統無 duration/easing token」已過時)。
+          世界級對照值 cite:tokens/motion/motion.spec.md#L113-L116 表(m3.material.io/styles/motion/easing-and-duration
+          + carbondesignsystem.com/guidelines/motion/overview,spec frontmatter benchmark 段)。 */}
+      <h2 className="text-h3 mb-2 mt-10">進出場動畫 Tokens</h2>
+      <p className="text-body text-fg-secondary mb-6">
+        Overlay fade/zoom/slide 的 duration / easing / 幾何,由 tw-animate-css 的
+        <code>--tw-duration</code> / <code>--tw-ease</code> 變數綁定;共用 SSOT =
+        <code>overlay-motion.ts</code>(overlayMotion / surfaceMotion)。世界級對照見
+        <code>motion.spec.md</code>「進出場動畫 token」表。
+      </p>
+
+      <DelayRow
+        token="--motion-duration-overlay"
+        value="150ms"
+        usage="輕量浮層進出場(對照表 cite: motion.spec.md#L113)"
+        consumers="Tooltip / Popover / HoverCard / DropdownMenu"
+      />
+      <DelayRow
+        token="--motion-duration-surface"
+        value="250ms"
+        usage="模態面板進出場——面積大、位移遠,慢一階(對照表 cite: motion.spec.md#L114)"
+        consumers="Dialog / Sheet / FileViewer"
+      />
+      <DelayRow
+        token="--motion-easing-enter"
+        value="0,0,0,1"
+        usage="進場減速曲線——快起、平滑落定(對照表 cite: motion.spec.md#L115)"
+        consumers="所有 overlay 進場"
+      />
+      <DelayRow
+        token="--motion-easing-exit"
+        value="0.3,0,1,1"
+        usage="出場加速曲線(對照表 cite: motion.spec.md#L116)"
+        consumers="所有 overlay 出場"
+      />
+      <DelayRow
+        token="--motion-enter-distance"
+        value="0.5rem"
+        usage="slide 進場位移(沿用現行 slide-*-2 幾何,cite: motion.css#L24)"
+        consumers="slide 型進場 overlay"
+      />
+      <DelayRow
+        token="--motion-enter-scale"
+        value="0.95"
+        usage="zoom 進場 scale(沿用現行 zoom-95 幾何,cite: motion.css#L25)"
+        consumers="zoom 型進場 overlay"
+      />
+
+      <p className="text-caption text-fg-muted mt-6">
+        實際 CSS 值見 <code>packages/design-system/src/tokens/motion/motion.css</code>;
+        JS number 鏡像見同目錄 <code>motion.ts</code>;tier 選擇表(何時用哪 token)見 <code>motion.spec.md</code>。
+      </p>
+    </div>
+  ),
+}
+
+
+/* 延遲體感 — 用真實 consumer 展示三個 token 的實際時序(非模擬動畫):
+   Tooltip 走全域 TooltipProvider delayDuration=500(= plain);
+   HoverCard Root 預設 openDelay=700 / closeDelay=200(= rich / close)。 */
+export const DelayFeel: Story = {
+  name: '延遲體感',
+  render: () => (
+    <div className="flex max-w-2xl flex-col gap-8">
+      <section className="flex flex-col gap-2">
+        <div className="text-body font-medium text-foreground">plain(500ms)— 工具列 icon 按鈕的文字提示</div>
+        <p className="text-caption text-fg-secondary">
+          hover 下方按鈕停留 500ms 才出現 tooltip;快速滑過不觸發。移開後 tooltip 立即依全域
+          Provider 收合節奏消失。
+        </p>
+        <div>
+          <Button iconOnly variant="text" size="sm" startIcon={Download} aria-label="下載簡報" />
+        </div>
+      </section>
+
+      <section className="flex flex-col gap-2">
+        <div className="text-body font-medium text-foreground">rich(700ms)+ close(200ms)— 留言裡的人名預覽卡</div>
+        <p className="text-caption text-fg-secondary">
+          rich 內容(可能含 fetch)門檻比 plain 高 200ms——必須「真的想看」才停留 700ms;
+          移開後 200ms 內移回卡片不會關(close 緩衝)。
+        </p>
+        <p className="text-body leading-relaxed">
+          這版 onboarding 流程的視覺稿請找
+          {/* defaultOpen:讓 visual snapshot 看得到卡片(M15 OpenSnapshot);移開再 hover 即體驗 700/200ms 時序 */}
+          <HoverCard defaultOpen>
+            <HoverCardTrigger asChild>
+              <a
+                href="#"
+                onClick={(e) => e.preventDefault()}
+                className="text-primary underline underline-offset-2 mx-1 cursor-pointer"
+              >
+                陳美惠
+              </a>
+            </HoverCardTrigger>
+            <HoverCardContent
+              className="bg-surface-raised border border-border rounded-lg p-4"
+              style={{ boxShadow: 'var(--elevation-200)', width: 260 }}
+            >
+              <div className="flex flex-col gap-1">
+                <div className="text-body font-medium text-foreground">陳美惠</div>
+                <div className="text-caption text-fg-secondary">產品設計師 · Design Platform</div>
+                <div className="text-footnote text-fg-muted">台北 · GMT+8 · 上班時間 10:00–19:00</div>
+              </div>
+            </HoverCardContent>
+          </HoverCard>
+          確認,她負責這一季的設計系統整合。
+        </p>
+      </section>
+    </div>
+  ),
+}

package/src/tokens/motion/motion.ts

@@ -1,17 +1,18 @@
 /**
- * Motion tokens — JS mirror of `motion.css` for Radix/JS API consumers.
+ * Motion tokens — JS mirror of `motion.css` delay tokens for Radix/JS API consumers.
  *
  * Radix primitive props(`delayDuration` / `openDelay` / `closeDelay`)期望 number ms,
- * 不認 CSS var。本 file 是 motion.css 對應 number value 鏡像;改值必同步兩處(或加 lint)。
+ * 不認 CSS var。本 file 是 motion.css `--motion-delay-*` 對應 number value 鏡像;改值必同步兩處。
+ * (進出場動畫 token 為純 CSS 驅動,由 tw-animate-css 消費,不需 JS 鏡像。)
  *
- * SSOT: `motion.css` + `motion.spec.md`。
+ * SSOT: `motion.css` + `motion.spec.md`。命名 2026-07-11 統一 `--motion-delay-*`(原 `--hover-delay-*`)。
  */
 
 /** 純文字提示(Tooltip)— passive hint。2026-05-20 200→500ms 對齊 Material 3 / Apple HIG / shadcn-Radix 主流 */
-export const HOVER_DELAY_PLAIN_MS = 500
+export const MOTION_DELAY_PLAIN_MS = 500
 
-/** 內容預覽(HoverCard / NameCard)— rich preview。2026-05-20 300→700ms 避免列表掃視誤觸發 fetch */
-export const HOVER_DELAY_RICH_MS = 700
+/** 內容預覽(HoverCard / ProfileCard)— rich preview。2026-05-20 300→700ms 避免列表掃視誤觸發 fetch */
+export const MOTION_DELAY_RICH_MS = 700
 
 /** 通用關閉延遲(所有 hover overlay)— accidental-hover 容錯 */
-export const HOVER_DELAY_CLOSE_MS = 200
+export const MOTION_DELAY_CLOSE_MS = 200

package/src/tokens/motion/overlay-motion.ts

@@ -0,0 +1,26 @@
+/**
+ * Overlay 進出場動畫 — 共用 duration / easing / reduced-motion SSOT(2026-07-11)。
+ *
+ * 消費 `motion.css` 的 `--motion-*` 動畫 token,經 tw-animate-css 的 `--tw-duration` / `--tw-ease`
+ * 變數綁定 → 7 浮層時長/曲線/無障礙守衛單一 SSOT,改 token 一處傳播全部(M17)。
+ *
+ * 幾何(fade / zoom / slide 距離方向)per-prototype 各自帶:
+ *   - 輕量浮層(Tooltip/Popover/HoverCard/DropdownMenu):fade + zoom-95 + slide-side-2(8px)
+ *   - 模態面板置中(Dialog/FileViewer):fade + zoom-95 + slide-center
+ *   - 邊緣抽屜(Sheet):slide-edge(100%),正當地無 zoom
+ * 本 module 只統一「時長 + 曲線 + reduced-motion」,不管幾何原型(對齊世界級 tier 分層)。
+ *
+ * Easing:進場減速(--motion-easing-enter)/ 出場加速(--motion-easing-exit),由 data-state gate。
+ */
+
+// enter=decelerate / exit=accelerate(對齊 Material standard-decelerate/accelerate 曲線)
+const EASING =
+  'data-[state=open]:[--tw-ease:var(--motion-easing-enter)] data-[state=closed]:[--tw-ease:var(--motion-easing-exit)]'
+// prefers-reduced-motion:關進出場動畫(無障礙,7 浮層統一 → 補齊 FileViewer 原缺口)
+const REDUCE = 'motion-reduce:animate-none'
+
+/** 輕量浮層(Tooltip / Popover / HoverCard / DropdownMenu)— 150ms */
+export const overlayMotion = `[--tw-duration:var(--motion-duration-overlay)] ${EASING} ${REDUCE}`
+
+/** 模態面板(Dialog / Sheet / FileViewer)— 250ms(面積大位移遠,慢一階) */
+export const surfaceMotion = `[--tw-duration:var(--motion-duration-surface)] ${EASING} ${REDUCE}`

package/src/tokens/opacity/opacity.spec.md

@@ -17,22 +17,24 @@ Opacity 定義元件停用狀態的透明度，確保全系統 disabled 視覺
 停用狀態有兩種視覺策略（詳見 `color.spec.md`「Disabled 狀態」節 / 「兩種 disabled 策略」）：
 
 - **Token swap**（預設）：disabled 時換成專用 token（`fg-disabled`、`bg-disabled`），精確控制每個層的顏色。適用於多層結構的元件（Button、Input）。
-- **Opacity blanket**：對整個元件套 `opacity-disabled`，一次處理所有子元素。適用於結構簡單、子元素多的元件（Avatar、Switch thumb、Slider）。
+- **Opacity blanket**：對整個元件套 `opacity-disabled`，一次處理所有子元素。適用於結構簡單、子元素多的元件（Avatar、Switch thumb、Rating）。Slider 屬灰階 token-swap 派,**不**用 opacity(`slider.spec.md`「Disabled 策略」反覆確認後的結論)。
 
 不可混用——同一元件要嘛用 token swap，要嘛用 opacity，不兩者同時。
 
+**Scope**:opacity 只負責 disabled 一個 role——error / warning 等 state 走 semantic color token 變色（`border-error` 等）、hover / active 走 `-hover` / `-active` token，皆無透明度變化（role 隔離，詳「設計哲學」(2)；全 DS production code 無 error-state opacity 用例）。**已 codify 的 reuse 例外**（reuse 同一 token，非新增 opacity role）：DataTable 整表 refresh loading（`data-table.spec.md`「狀態處理職責邊界」）與 drag source 半透（同 spec「Drag visual SSOT」+ `lib/drag-visual.ts`）。
+
 ## 為什麼 0.45
 
-0.45 在 light mode 和 dark mode 都能對 disabled 元件產生足夠辨識度（明顯區分於 active state），同時保持文字可讀（WCAG 不要求 disabled 元素的對比度，但仍需辨識）。
+0.45 在 light mode 和 dark mode 都能對 disabled 元件產生足夠辨識度（明顯區分於 active state）。「辨識」與「閱讀」是兩個不同要求：WCAG 2.1 SC 1.4.3 明文豁免 inactive UI component 的文字對比（無法定「可讀對比」門檻）；但 UX 上使用者仍須**辨識**出「這裡有一個控件、且目前停用」——0.45 服務的是辨識，不是閱讀。
 
-選 0.45 的位置:
+選 0.45 的位置: <!-- @benchmark-unverified -->
 
 - 比 **Material 0.38** 略亮(Material 在白底 dark text 0.38 太弱,DS 使用 lg / dark mode 共用一個值需折衷)
 - 比 **Apple iOS 0.4 / Atlassian 0.4** 稍亮(iOS 是 mobile-first 對比偏強,DS desktop 場景文字密集需更可辨識)
 - 比 **Polaris 0.5 / Tailwind 0.5** 稍暗(0.5 對 disabled 元件辨識度不足,容易誤判為 hover state)
 - **0.45 是 0.4-0.5 區間中位數**,跨 light / dark mode 都 robust
 
-世界級對照(2026-05-01 加):
+世界級對照(2026-05-01 加): <!-- @benchmark-unverified -->
 
 | DS | Material 3 | Carbon | Tailwind v4 | Ant Design | Polaris | Apple HIG | Atlassian |
 |----|-----------|--------|-------------|------------|---------|-----------|-----------|
@@ -44,35 +46,28 @@ Opacity 定義元件停用狀態的透明度，確保全系統 disabled 視覺
 
 兩個關鍵決策,各自有世界級先例支撐:
 
-**(1) 雙策略並存(token swap 為主 + opacity blanket 為輔)— 對齊 Carbon / Atlassian 折衷哲學**
+**(1) 雙策略並存(token swap 為主 + opacity blanket 為輔)— 對齊 Carbon / Atlassian 折衷哲學** <!-- @benchmark-unverified -->
 
 純 token swap(Material / Ant / Polaris):每元件每層 disabled 自己一個 token,精確但 token 數激增(Material 有 50+ disabled token);純 opacity blanket(早期 Bootstrap):一律 0.5 簡單但無法表達 multi-layer hierarchy(disabled Button 的 icon / label / border 三層該有不同程度 fade)。
 
 本 DS 採 Carbon-aligned 折衷:**多層結構元件用 token swap**(Button 有 fg / bg / border 各自 disabled token);**簡單元件用 opacity blanket**(Avatar / Switch thumb 一個視覺單位,opacity 0.45 一次處理所有子元素)。明文「不可混用」避免 disabled overlay 重疊產生「過度褪色」(0.45 × 0.45 = 0.2 不可讀)。
 
-**(2) Single tier 0.45 而非 Tailwind multi-tier opacity scale — 對齊 Polaris / Apple 單值哲學**
+**(2) Single tier 0.45 而非 Tailwind multi-tier opacity scale — 對齊 Polaris / Apple 單值哲學** <!-- @benchmark-unverified -->
 
 Tailwind 提供 `opacity-{5/10/20/30/40/50/60/70/80/90/95}` 百分比 ladder,但這是 utility scale 非 semantic role — 每個 consumer 自己挑值,跨元件不一致(A 用 opacity-50 / B 用 opacity-40 都 disabled)。
 
 本 DS 為 disabled 場景 single semantic token(`opacity-disabled = 0.45`),所有 disabled 用同一值 — 對齊 Polaris `opacity-disabled` / Material `disabled-on-surface` / Apple `UIDisabled` 「single semantic value for one role」哲學。捨棄 Tailwind multi-tier 的代價是「無法表達多層 hover/active fade」,但 hover / active 走 hover-bg / pressed-bg token,opacity 只負責 disabled,role 隔離。
 
-## 消費者
+## A11y（disabled 訊號不只透明度）
 
-Avatar、Sidebar、MenuItem、Slider、Switch、Steps、Chip。
+透明度是視覺輔助,不是 disabled 的唯一訊號:語意由 native `disabled` / `aria-disabled` attribute 傳達給輔助技術（SR 朗讀 unavailable,非依賴視覺）,並伴隨互動阻斷（無法觸發 / `cursor-not-allowed`）提供非色彩線索——色弱使用者不依賴 0.45 fade 也能辨識停用狀態。
 
-## 反向引用
+## 消費者
 
-- Disabled 策略選擇框架：`tokens/color/color.spec.md`
+直接套用 `opacity-disabled` 的元件（grep 驗證 2026-07-16;Textarea 已全面 token-swap 化移除）：Avatar（Field disabled context self-dim）、Button（`aria-disabled` 分支）、MenuItem、Rating（disabled / loading 整塊）、Steps、Switch、DataTable（drag source 半透 + 整表 refresh loading reuse，經 `lib/drag-visual.ts`）、PersonDisplay（disabled 整塊,`person-display.tsx:137`）。
 
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
+非消費者（曾誤列）：Slider / Sidebar 走灰階 token swap；Chip 無 opacity 用例；Field wrapper blanket 已移除（Avatar self-dim 取代，見 field-wrapper.tsx 註解）。
 
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+## 反向引用
 
-- `avatar.spec.md`
-- `chip.spec.md`
-- `color.spec.md`
-- `menu-item.spec.md`
-- `sidebar.spec.md`
-- `slider.spec.md`
-- `steps.spec.md`
-- `switch.spec.md`
+- Disabled 策略選擇框架：`tokens/color/color.spec.md`

package/src/tokens/opacity/opacity.stories.tsx

@@ -0,0 +1,66 @@
+import type { Meta, StoryObj } from '@storybook/react'
+
+const meta: Meta = {
+  title: 'Design System/Tokens/Opacity',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: `
+透明度 token 系統。系統內唯一 opacity token = \`--opacity-disabled\`(disabled 狀態);其他透明度需求走 alpha 色階(\`--white-aN\` / \`--black-aN\`),不另開 opacity token。
+
+完整規則:\`packages/design-system/src/tokens/opacity/opacity.spec.md\`
+
+**禁:**\`opacity-{5..95}\` 數字 ladder 與 arbitrary \`opacity-[0.N]\`(走 token,不直接寫死);\`opacity-0\` / \`opacity-100\`(show / hide transition)與 \`opacity-disabled\` 為 utility-registry allow。
+        `,
+      },
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj
+
+
+function OpacityRow({ utility, value, usage }: { utility: string; value: 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: '180px 100px 1fr 200px' }}>
+      <div>
+        <code className="block text-caption font-medium text-fg-secondary">{utility}</code>
+      </div>
+      <div className="text-caption font-mono text-fg-muted">{value}</div>
+      <div className="text-body text-foreground">{usage}</div>
+      <div className="flex items-center gap-2">
+        <div
+          aria-hidden="true"
+          className="h-8 w-8 rounded bg-primary"
+          style={{ opacity: parseFloat(value) }}
+        />
+        <span className="text-caption text-fg-muted">preview</span>
+      </div>
+    </div>
+  )
+}
+
+
+export const Overview: Story = {
+  name: '總覽',
+  render: () => (
+    <div className="max-w-4xl">
+      <h2 className="text-h3 mb-2">Opacity Tokens</h2>
+      <p className="text-body text-fg-secondary mb-6">
+        本系統只定義 1 個 opacity token——<code>--opacity-disabled</code>(0.45,系統內唯一)。
+        其他透明度需求走 alpha 色階(<code>--white-aN</code> / <code>--black-aN</code>),不另開 opacity token;
+        值不隨 dark mode 切換(light / dark 共用 0.45)。
+      </p>
+
+      <OpacityRow utility="opacity-disabled" value="0.45" usage="所有元件的 disabled 狀態(token swap 為主、opacity blanket 為輔,詳 spec「使用規則」)" />
+
+      <p className="text-caption text-fg-muted mt-6">
+        實際 CSS 值見 <code>packages/design-system/src/tokens/opacity/opacity.css</code>;雙策略(token swap vs opacity blanket)與消費者清單見同目錄 <code>opacity.spec.md</code>。
+      </p>
+    </div>
+  ),
+}

package/src/tokens/orphan-tokens.spec.md

@@ -10,10 +10,15 @@ benchmark:
   - Polaris Design Tokens — semantic SOP 5-piece set canonical https://polaris.shopify.com/design/colors
 ---
 
-# Orphan Token 分類 SSOT(retire vs structural-keep)
+# Orphan Token 分類設計原則(retire vs structural-keep SSOT)
 
 > **Foundational context**(2026-05-21 codify per user verbatim「決策四你他媽仔細給我確認到底該retire的是否真的該retire還是應該結構性保留,請全盤檢查,然後確認之後請下次不要再煩我,尤其是Palette tier」+「都給我做到好」):**永久解決**「audit 每次抓 X 個 orphan tokens」噪音。本 spec 明文哪些 token 結構性保留 + 自動 audit script 識別,user 不需重複確認同一題。
 
+## Scope(何時用 / 何時不用)
+
+- **用**:DS 作者稽核 token bloat(retire vs structural-keep 判定)— `audit-orphan-tokens.mjs` + design-system-audit Dim 48 消費本分類,屬 DS-internal audit SSOT
+- **不用**:consumer 選 token 的使用指南 — 那是 `tokens/README.md` + 各 token spec 的職責
+
 ## 為什麼會出現「假孤兒」
 
 簡單的 `grep var(--X)` 抓不到以下消費路徑,造成 token **實際有用但 audit 報「無消費」false positive**:
@@ -23,7 +28,7 @@ benchmark:
 | **Tailwind `@theme inline` bridge** | `--spacing-field-md` → `h-field-md` class | Tailwind 在 build time 從 bridge 讀值轉 utility class,無 `var()` 語法 |
 | **`@utility` definition** | `@utility tracking-shortcut { letter-spacing: var(--tracking-shortcut) }` | 是定義,不是消費點 |
 | **Class-name match** | `text-primary-text` 對應 `--primary-text` | 走 Tailwind 命名約定 |
-| **JS literal mirror** | `motion.ts` export `HOVER_DELAY_RICH_MS = 700` 鏡像 `--hover-delay-rich` | JS 端 hardcode 數字 + import constant,不讀 CSS var |
+| **JS literal mirror** | `motion.ts` export `MOTION_DELAY_RICH_MS = 700` 鏡像 `--motion-delay-rich` | JS 端 hardcode 數字 + import constant,不讀 CSS var |
 
 **修法**:`scripts/audit-orphan-tokens.mjs` 用 comprehensive consumer detection 涵蓋 5 條消費路徑,真實 orphan count drops from 175 → 0(2026-05-21 baseline)。
 
@@ -39,7 +44,7 @@ benchmark:
 
 **Why**:Material 3「Key Colors & Tones」+ Atlassian「Full color spectrum」共識 — palette 是設計師調色盤 SSOT,缺中間階就斷層,新元件需消費中間色時不該 hot-add。**全色階是 capability,不是 cost**。
 
-**Regex**:`^--color-(amber|blue|brown|red|green|deep-orange|grey|indigo|lime|orange|pink|purple|teal|yellow|cyan)-\d+$`
+**Regex**:`^--color-(amber|blue|red|green|deep-orange|indigo|lime|orange|purple|yellow)-\d+$`
 
 ### 2. Magenta / Turquoise 專用 palette(14 token,structural)
 
@@ -47,9 +52,9 @@ benchmark:
 
 **Regex**:`^--color-(magenta|turquoise)-\d+$`
 
-### 3. Mask alpha(16 token,structural)
+### 3. Mask alpha(17 token,structural)
 
-**Rule**:`--black-aN` / `--white-aN`(alpha tiers a02-a85)完整保留。
+**Rule**:`--black-aN`(a02-a85,9 階)/ `--white-aN`(a04-a85,8 階)完整保留。
 
 **Why**:Overlay / scrim / shadow / disabled state alpha composition 預留;Material 3「Surface Tint」+ Apple HIG「Vibrancy」需要完整 alpha ladder。
 
@@ -79,19 +84,19 @@ benchmark:
 
 ### 7. SOP 5-piece semantic 完整集(1+ token,structural)
 
-**Rule**:每個 semantic role(primary / error / success / warning / info)必有 5 件套:`base / hover / active / subtle / text`,即使當前 `text` variant 無消費者也保留。
+**Rule**:每個 semantic role(primary / error / success / warning / info)必有 5 件套:`base / hover / active / subtle / text`;機械保護集另含 `emphasis / foreground / focus`(下方 Regex 共 7 後綴,與 `audit-orphan-tokens.mjs` 一致;無後綴 base 由消費者直接引用不在 regex 內)。即使當前 variant 無消費者也保留。
 
 **Why**:Consistency invariant — 缺 `-text` variant 設計時找不到「on-emphasis 文字色」會 hot-create,違反 SSOT。Polaris「Status colors complete set」canonical。
 
 **Regex**:`^--(primary|error|success|warning|info)-(active|hover|text|subtle|emphasis|foreground|focus)$`
 
-### 8. JS literal mirror(2 token,structural)
+### 8. JS literal mirror(3 token,structural)
 
-**Rule**:`--hover-delay-{plain|rich|close|skip}` motion tokens 鏡像 JS constants(`HOVER_DELAY_PLAIN_MS` 等),CSS 端保留供 design SSOT 可見 + 未來 programmatic 讀取(`getComputedStyle`)。
+**Rule**:`--motion-delay-{plain|rich|close}` motion tokens 鏡像 JS constants(`MOTION_DELAY_PLAIN_MS` / `MOTION_DELAY_RICH_MS` / `MOTION_DELAY_CLOSE_MS`),CSS 端保留供 design SSOT 可見 + 未來 programmatic 讀取(`getComputedStyle`)。
 
 **Why**:M17 SSOT 雙頭設計 — CSS 端是設計師 inspector 入口,JS 端是 runtime 消費入口,兩端必同步存在。
 
-**Regex**:`^--hover-delay-(plain|rich|close|skip)$`
+**Regex**:`^--motion-delay-(plain|rich|close)$`
 
 ---
 
@@ -104,10 +109,16 @@ benchmark:
 2. **Git blame** declare 提交 — 提交訊息 / PR 描述是否說明用途
 3. 兩 step 都無 → safe retire,從 `tokens/**/*.css` 刪宣告 + 加 git commit message cite 本 spec
 
+## 邊界案例
+
+- **Audit 間 token 重獲消費者(0 → N)**:audit 為每次執行的即時 snapshot(無跨次狀態),token 重獲消費後自動退出 retire 候選;無 deprecation period 機制
+- **新 structural-keep token**:不在 baseline → `--check` fail,需 `--update` 顯式 justify(防 regex 過寬 silent absorb;baseline 縮減不 fail)— baseline SSOT `scripts/audit-orphan-tokens.baseline.json`
+- **Dark-mode token mirror 驗證**:非本 audit scope — script 只驗「消費存在性」,不驗 light / dark 配對完整性
+
 ## Audit chain
 
-- **Dim 48** (`design-system-audit/SKILL.md`)— chain 本 spec + `audit-orphan-tokens.mjs --check`(not raw `grep var()`)
-- **CI**:`npm run audit:tokens`(future add to `package.json` scripts)— `node scripts/audit-orphan-tokens.mjs --check` fail = real orphan 出現
+- **Dim 48**(= `design-system-audit/SKILL.md` 的「Unused / orphan token detector」audit 維度)— chain 本 spec + `audit-orphan-tokens.mjs --check`(not raw `grep var()`)
+- **CI**:`release.yml` deterministic-gates step + `scripts/release-preflight.mjs` 直呼 `node scripts/audit-orphan-tokens.mjs --check` — fail = real orphan 出現
 - **Hook**:無 hook(本 audit run-time / monthly cadence,非 PreToolUse 攔截場景)
 
 ## 永久解決承諾

package/src/tokens/radius/radius.spec.md

@@ -27,7 +27,7 @@ CSS 定義了 `--radius-sm`(目前 = 4px,與 md 同值),但**不在元件中使
 - Chart legend swatch(8×8 色塊)
 - 未來其他 micro indicator(若尺寸 ≥ 12px 請改 `rounded-md`,不要為了「更圓」使用 xs)
 
-**判斷**:`rounded-md`(4px)在 8×8 元素上接近 50% 填滿,視覺變成 pill。2px 才維持「色塊」而非「膠囊」語意。≥ 12px 時 4px 比例適當,不需 xs。
+**判斷**(radius / 邊長比):4px 在 8×8 元素上 = 邊長 50%(radius 達半邊長即成 pill,類別色塊語意流失);2px = 25%,輪廓保持方形。≥ 12px 元素上 4px ≤ 33%,比例適當,不需 xs。
 
 ### `rounded-md`(4px)— 一般元件
 
@@ -57,7 +57,7 @@ CSS 定義了 `--radius-sm`(目前 = 4px,與 md 同值),但**不在元件中使
 ## 禁止事項
 
 ```tsx
-// ❌ 不要用非 token 的圓角（包含 rounded-md、rounded 等）
+// ❌ 不要用非 token 的圓角(bare rounded、rounded-xl、rounded-2xl 等)
 <div className="rounded" />        // 4px，但意圖不明
 <div className="rounded-xl" />     // 12px，超出 token 範圍
 <div className="rounded-2xl" />    // 16px，超出 token 範圍
@@ -81,15 +81,19 @@ CSS 定義了 `--radius-sm`(目前 = 4px,與 md 同值),但**不在元件中使
 <span className="rounded-full" />
 ```
 
+### 省略 radius 的行為(空值驗證)
+
+不寫 `rounded-*` → `border-radius: 0`(CSS 預設直角),不 fallback 任何 token;無圓角需求的元素本就不寫,不強制每元素標 radius。**有意**的圓角必用上表 4 tier class——bare `rounded`(Tailwind 預設 4px,意圖不明)與硬寫值由上方禁止事項擋。
+
 
 ## 世界級對照
 
-對齊 M8(binary strict rule 必 ≥3 家世界級對照),「禁 `rounded-xl` / `rounded-2xl` raw utility」+「禁硬寫 `rounded-[6px]`」是本 spec 的 binary strict rule,以下為支撐 rationale。
+對齊 M8(binary strict rule 必 ≥3 家世界級對照),「禁 `rounded-xl` / `rounded-2xl` raw utility」+「禁硬寫 `rounded-[6px]`」是本 spec 的 binary strict rule,以下為支撐 rationale。 <!-- @benchmark-unverified -->
 
 | 維度 | 本 DS | Material 3 | Carbon | Tailwind v4 | Ant Design | Polaris | shadcn/Apple |
 |------|-------|-----------|--------|-------------|------------|---------|--------------|
-| Tier 數 | **4 tier**(xs/md/lg/full)+ 1 reserved sm | 6 tier(extra-small ~ extra-large + full) | 3 tier(0/1/2) | 7 tier(none/sm/md/lg/xl/2xl/3xl/full)| **4 tier**(XS/SM/Default/LG)| 6 tier(050/100/200/300/400/500/full)| 1 base + calc(shadcn)/ Squircle 連續曲率(Apple)|
-| 數值序列 | **2 / 4 / 8 / 9999** geometric × 2 | 4 / 8 / 12 / 16 / 28 額外 | 0 / 2px / 4px(token rem)| 2 / 4 / 6 / 8 / 12 / 16 / 24 | 2 / 4 / 6 / 8 | 2 / 4 / 6 / 8 / 12 / 16 | `--radius` × calc 變化 |
+| Tier 數 | **4 tier**(xs/md/lg/full)+ 1 reserved sm | 6 tier(extra-small ~ extra-large + full) | 3 tier(0/1/2) | 8 tier(xs/sm/md/lg/xl/2xl/3xl/4xl)+ none/full | **4 tier**(XS/SM/Default/LG)| 6 tier(050/100/200/300/400/500/full)| 1 base + calc(shadcn)/ Squircle 連續曲率(Apple)|
+| 數值序列 | **2 / 4 / 8 / 9999** geometric × 2 | 4 / 8 / 12 / 16 / 28 額外 | 0 / 2px / 4px(token rem)| 2 / 4 / 6 / 8 / 12 / 16 / 24 / 32 | 2 / 4 / 6 / 8 | 2 / 4 / 6 / 8 / 12 / 16 | `--radius` × calc 變化 |
 | Pill 方案 | `rounded-full` 9999px | `shape-corner-full` | 不顯式提供 | `rounded-full` 9999px | `borderRadiusOuter` ad-hoc | `border-radius-full` | 視 component shape |
 | 動態 shape | 無(靜態 4 tier)| Dynamic shape morphing(可動畫) | 無 | 無 | 無 | 無 | Apple 連續曲率動態 |
 
@@ -97,27 +101,26 @@ CSS 定義了 `--radius-sm`(目前 = 4px,與 md 同值),但**不在元件中使
 
 四個關鍵決策,各自有世界級先例支撐:
 
-**(1) 4 tier(xs/md/lg/full)— 對齊 Ant Design 4-tier minimal,捨多家 6+ tier**
+**(1) 4 tier(xs/md/lg/full)— 對齊 Ant Design 4-tier minimal,捨多家 6+ tier** <!-- @benchmark-unverified -->
 
 Material 3 / Polaris / Tailwind 6-7 tier 過細 — 每 tier 只差 2-4px,reader 視覺難分(「rounded-md 6px」vs「rounded-lg 8px」差 25% 但目視幾乎相同)。Carbon 3 tier(0/1/2)太極簡無法表達 elevation 層級(浮層 vs inline 同 radius 失去視覺 hierarchy)。
 
 本 DS 4 tier 是「視覺可區分 + 維護友善」最佳交集 — `xs(2)→ md(4)→ lg(8)→ full` 每跳一級數值翻倍,目視差異 ≥ 50%(Weber-Fechner law 知覺閾值),不會出現「rounded-md vs rounded-mdlg 哪個對」糾結。
 
-**(2) Geometric scale(2 / 4 / 8 doubling)— 對齊 Tailwind / Polaris 慣例**
+**(2) Geometric scale(2 / 4 / 8 doubling)— 對齊 Tailwind / Polaris 慣例** <!-- @benchmark-unverified -->
 
-數值 doubling 確保 reader 一眼感知「不同層級」(2→4→8 比 4→6→8 對比明顯)。對齊 Tailwind sm(2)/ md(4)/ lg(8) + Polaris 100(4)/ 200(6 — 偏離)/ 300(8) 的 powers-of-2 idiom。
+數值 doubling 確保 reader 一眼感知「不同層級」(2→4→8 比 4→6→8 對比明顯)。對齊 Tailwind v4 xs(2)/ sm(4)/ lg(8)(見上表數值序列)+ Polaris 100(4)/ 200(6 — 偏離)/ 300(8) 的 powers-of-2 idiom。
 
 捨棄連續 ratio(Material 4/8/12/16/28 等差 + 跳級)的代價是「中段 size 表現空間」(無 6px tier),DS 場景無此需求(中段需求都歸入 md=4)。
 
-**(3) `rounded-full` 9999px 而非 50%(對齊 Tailwind / Polaris)**
+**(3) `rounded-full` 9999px 而非 50%(對齊 Tailwind / Polaris)** <!-- @benchmark-unverified -->
 
 50% percentage 在「短矩形」(高 < 寬,如 horizontal Switch)變橢圓而非 pill — 9999px 確保任意 aspect ratio 都圓形(實際 capped 在 height/2)。對齊 Tailwind / Polaris 全 pill 慣例,避免短矩形 edge case。
 
-**(4) 保留 `--radius-sm` token 但不用 — 對齊 Material「reserve for future dense pattern」**
+**(4) 保留 `--radius-sm` token 但不用 — 對齊 Material「reserve for future dense pattern」** <!-- @benchmark-unverified -->
 
 CSS 定義 `--radius-sm = 4px`(目前同 md),component 強制 `rounded-md` 不引用 sm。為什麼留:未來若引入 dense mode(`density="compact"` 介於 md / xs 之間),可開新 sm tier 不破壞既有 xs/md/lg/full 命名階梯(避免 rename 引發全 DS grep refactor)。對齊 Material 3 的「extra-small reserved tier」哲學。
 
 捨棄「立即啟用 sm」的代價是命名空間預占,接受 — 命名穩定 > 短期 utility。
 
 捨棄「Apple Continuous Corner / Squircle」的代價是「平台一致性」(Apple HIG 用連續曲率非單一 radius,iOS 元件視覺更柔)— DS 是 cross-platform web,採 Material/Tailwind 標準 border-radius 對齊大多數 OS native 元件,避免引入 SVG path 額外 runtime 成本。
-