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

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

@@ -70,7 +70,7 @@ Semantic token 直接指向 primitive（無中間層）。
 **注意（categorical `red` vs semantic `--error` vs primitive `deep-orange` 三者獨立）**：
 - `--error` = `--color-deep-orange-6`（primitive `deep-orange`，hue 38）—— semantic 狀態色,用於錯誤訊息。
 - Tag / Avatar / Calendar 的 categorical `red` variant = `--color-red-*`（品牌紅家族 hue 25,與 `--brand` `#DF3232` 同族）。
-- **三者無映射關係**：`red`（categorical 色相 hue 25）≠ `deep-orange`（primitive hue 38）≠ `--error`（semantic = deep-orange）。categorical 色相 1:1 對 `--color-{hue}-*`,零 offset（SSOT `tokens/categorical-color.ts`)。2026-06-04 修正原「red variant 接 deep-orange」offset。
+- **三者無映射關係**：categorical `red`（hue 25）≠ `deep-orange`（primitive hue 38）≠ `--error`（semantic = deep-orange）。categorical 色相 1:1 對 `--color-{hue}-*`,零 offset（SSOT `tokens/categorical-color.ts`)。2026-06-04 修正原「red variant 接 deep-orange」offset。
 
 Tailwind utility 透過 `@theme inline` 橋接 semantic token，元件寫 `bg-primary` 或 `bg-error` 即可。Tag / Avatar 使用 CSS 變數任意值（`bg-[var(--color-blue-6)]`）。
 
@@ -174,6 +174,8 @@ Semantic token 按**載體類型**分成四個 family,**family 之間的 token
 
 ## Icon 色彩原則
 
+Icon 色彩 canonical 的 SSOT 住 `patterns/element-anatomy/item-anatomy.spec.md`「Icon 色彩原則」——核心規則:icon 代表內容/類別 → 與 label 同色;icon 純指示方向 → `fg-muted`;disabled 統一 `fg-disabled`。本檔不重述(Rule-of-3 pointer)。
+
 ## 語義色
 
 ### Action — Primary
@@ -225,7 +227,7 @@ Semantic token 按**載體類型**分成四個 family,**family 之間的 token
 
   | 底色 | 文字色 | 原因 |
   |------|--------|------|
-  | `bg-warning`（yellow-6，滿版） | `text-on-emphasis-dark`（`black-a85`，深色） | 黃色亮度高，白字對比不足，必須用深色（通用亮底深字 token，非 warning 專屬） |
+  | `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 原則」） |
 
 ### Indicator — Notification
@@ -455,7 +457,7 @@ Dark mode 覆寫：hover/active 方向反轉（hover → step-7，active → ste
 - 跨 mode 一致的方向（dark mode 必須 swap step 號）
 - 但 Tag 的「藍」≠ semantic primary（解耦：改 primary 不應影響 Tag）
 
-直接用 primitive `--color-blue-5/-7` 不行——dark mode 公式互換會方向顛倒。所以擴展 semantic 互動 token 模式到所有 8 個非語意色相。
+直接用 primitive `--color-blue-5/-7` 不行——dark mode 公式互換會方向顛倒。所以擴展 semantic 互動 token 模式到全部 12 個 categorical 色相(SSOT `tokens/categorical-color.ts` `CATEGORICAL_HUES`)。
 
 #### 嚴格限制
 
@@ -657,7 +659,7 @@ Dark mode 覆寫：hover/active 方向反轉（hover → step-7，active → ste
 
 **跟 `bg-neutral-hover` / `bg-neutral-active` 的區別**:neutral 系列表達**互動**狀態(hover / 選中);muted / secondary 表達**結構性的靜態層級** — 即使沒有互動,它永遠是這個顏色。
 
-**邊界 — component disabled bg 不走 muted**:Button / Input / Checkbox 等元件 disabled state 走 `--bg-disabled` semantic,不是 `--muted`(同值 neutral-2 但不同 owner — `--bg-disabled` 是 component-state token,`--muted` 是 surface-non-interactive token,per L169「同值不同語意拆 token」rule)。
+**邊界 — component disabled bg 不走 muted**:Button / Input / Checkbox 等元件 disabled state 走 `--bg-disabled` semantic,不是 `--muted`(同值 neutral-2 但不同 owner — `--bg-disabled` 是 component-state token,`--muted` 是 surface-non-interactive token,per「為什麼同值仍分兩個 token」段 rule)。**Readonly state 同理但用自己的 token `--bg-readonly`**(2026-06-10):readonly ≠ disabled(可聚焦/選取/提交,僅不可改值,per Carbon「navigable but not operable」),不借 `--bg-disabled` 名;也不走 `--muted`(readonly 是互動元件 state,非 Skeleton 類靜態 surface)。三者同值 neutral-2、owner 獨立,可分離演進。
 
 ```tsx
 <Skeleton className="h-4 w-32" />            {/* bg-muted — placeholder 語意 */}
@@ -755,6 +757,16 @@ CSS 變數在定義元素上解析。`:root` 的 `--foreground: var(--color-neut
 
 容器自身的樣式（如 tooltip 的 `bg-tooltip`）不受子 div 的 `data-theme` 影響——`data-theme` 在子 div 上，只影響子元素。
 
+## 常見誤解
+
+各誤解的完整推理已在本檔對應段落,此處彙整索引:
+
+- 「`--primary` 跟 `--info` 同色所以可互換」— 語義截然不同,status 元件混入 `--primary` 即 fail(見「Status」段 + `status-color-invariant.mjs`)。
+- 「`--fg-disabled` 剛好是我要的灰,拿來當 bg」— 跨 family 借用是 smell(見「fg token 不可當 bg 用」段 Slider case)。
+- 「`bg-muted` / `bg-secondary` 都是淡灰隨便選」— 前者 = 退化 / placeholder,後者 = 正常存在但退後一級(見「Static Subtle Background」段)。
+- 「`--neutral-active` / `--neutral-selected` 同值可合併」— transient vs persistent 語意獨立(見「active vs selected」段)。
+- 「categorical `red` = `--error`」— hue 25 vs deep-orange,完全無關(見「消費規則」注意事項)。
+
 ## 禁止事項
 
 ```tsx
@@ -774,16 +786,11 @@ SSOT → `.claude/references/structural-token-retention.md`(6 類保留 + sub-ag
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
-- `opacity.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
 - `chart.spec.md`
 - `date-grid.spec.md`
 - `file-item.spec.md`
 - `notice.spec.md`
+- `opacity.spec.md`
 - `progress-bar.spec.md`
 - `separator.spec.md`
 - `skeleton.spec.md`

package/src/tokens/color/semantic.css

@@ -328,6 +328,7 @@
   --neutral-hover:        var(--color-neutral-1);
   --neutral-active:       var(--color-neutral-2);
   --bg-disabled:          var(--color-neutral-2);
+  --bg-readonly:          var(--color-neutral-2);  /* readonly 鎖定欄位 chrome — 同值但獨立 owner(≠ disabled:可聚焦/選取/提交,僅不可改值);詳 color.spec.md Static Subtle 邊界 */
 
   /* Neutral Interactive — Selected state family
      ─────────────────────────────────────────────────────────────
@@ -515,6 +516,7 @@
   --color-neutral-hover:             var(--neutral-hover);
   --color-neutral-active:            var(--neutral-active);
   --color-disabled:                  var(--bg-disabled);
+  --color-readonly:                  var(--bg-readonly);
 
   /* Neutral Interaction — Selected state family */
   --color-neutral-selected:          var(--neutral-selected);

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

@@ -18,7 +18,7 @@ Density 由**兩個獨立維度**構成,並配合一個 convenience attribute
 
 **反例**(耦合):Material M3 / Polaris density 模式綁 control size + spacing — 無法「寬版面 + 標準 control」的場景。
 
-**我們走 decouple 流派**:解決 Dialog / overlay chrome 的痛點 — header 想要寬鬆呼吸(layout=lg),但不要被 button chrome 撐高(ui-size 跟 page 走 md)。
+**我們走 decouple 流派**:解決 Dialog / overlay chrome 的痛點 — header 想要版面間距寬鬆(layout-space=lg),但不要被 button chrome 撐高(ui-size 跟 page 走 md)。
 
 ## 預設同步(density convenience)
 
@@ -35,7 +35,7 @@ Density 由**兩個獨立維度**構成,並配合一個 convenience attribute
 
 ## 解耦用法(canonical 情境)
 
-當需要「layout 寬鬆 + control 標準」時,**顯式設兩個 attribute**:
+當需要「版面間距寬鬆(layout-space)+ 控件高度標準(ui-size)」時,**顯式設兩個 attribute**:
 
 ### Canonical 情境 1 — 歷史備忘(Dialog 已撤回)
 
@@ -108,20 +108,10 @@ document.documentElement.setAttribute('data-layout-space', 'md')
 | Tooltip | `data-density="md"` | 同 Popover |
 | Sidebar | 無(繼承 page) | Sidebar 是 inline chrome(非 Portal 逃逸),跟隨 page density;size="md" 在 density="lg" 下自動變 36px row(見 sidebar.spec.md「Row size 跟 density 的差別」)|
 
+**邊界:page density=lg 下的 Portal overlay**——Popover / DropdownMenu / Tooltip 在 `data-density="lg"` 的 page 上仍鎖 `md`(code:各 Content 自設 `data-density="md"`)。這不是漏接:Portal 到 body 本就不繼承 subtree density(M3),鎖 md 是 overlay「compact」語意的刻意設計(2026-04-22 v5 canonical)。
+
 ## Anti-patterns(禁止)
 
 - ❌ 元件同時設 `data-density` + `data-ui-size`(重複,以後者為準但混亂)
 - ❌ Overlay Portal 元件不自設 density(Portal 到 body 不繼承 trigger — 見 Meta-Pattern M3)
 - ❌ 為了追求表面一致性硬把 Dialog button 綁 lg ui-size(犧牲 header 高度 / strapline 彈性)
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
-- `dialog.spec.md`
-- `dropdown-menu.spec.md`
-- `popover.spec.md`
-- `sheet.spec.md`
-- `sidebar.spec.md`
-- `tooltip.spec.md`
-- `uiSize.spec.md`

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

@@ -1,3 +1,5 @@
+<!-- @benchmark-cited: D5 retrofit backfill 2026-06-10 — body world-class claims marked per-claim inline;對齊 token spec 家族 7/9 既有 marker 慣例(deep-audit A.0 抓漏)。 -->
+
 # Elevation 設計原則
 
 Elevation 定義陰影層級，區分內容層（Card）和浮層（Modal/Popover）的視覺深度。
@@ -16,11 +18,11 @@ Elevation 定義陰影層級，區分內容層（Card）和浮層（Modal/Popove
 | Token | 用途 | 對應元件 |
 |-------|------|----------|
 | `--elevation-100` | 頁面內容層，靜止 | Card |
-| `--elevation-100-hover` | 頁面內容層，hover / 拖拽 | 可拖拽 card |
+| `--elevation-100-hover` | 頁面內容層，hover / 拖拽 lift | —(目前無 DS 內建 consumer;預留給 consumer 的可拖拽 / hover-lift card,如 board card drag) |
 | `--elevation-200` | 浮層，靜止 | Modal、popover、dropdown、overlay drawer |
-| `--elevation-200-hover` | 浮層，hover | — |
+| `--elevation-200-hover` | 浮層，hover | —(同上,預留) |
 
-elevation-100 < elevation-200，數字越大浮起越高。
+elevation-100 < elevation-200，數字越大浮起越高。`*-hover` 兩枚為靜止 token 的「抬升一階」變體:元素被 hover / 拖起時切換,幾何(offset / blur)不變、只加深陰影 alpha(`tokens/color/primitives.css` 定義,light / dark 各一組)。
 
 ## 與 Surface 的配對規則
 
@@ -46,6 +48,8 @@ elevation-100 < elevation-200，數字越大浮起越高。
 
 **SSOT** → `tokens/elevation/overlay-geometry.ts` exports `OVERLAY_SIDE_OFFSET = 8` / `OVERLAY_COLLISION_PADDING = 8`。所有 primitive `default` 必 import 該 const(M17 SSOT 必可傳播);Radix `sideOffset` 接 number 不接 CSS var,因此用 JS const 共用,改值只動一處全部聯動。
 
+**視窗邊緣碰撞(邊界案例)**:浮層貼近 viewport 邊不足以容納時,Radix `avoidCollisions`(預設開)自動翻轉 / 平移,並與邊緣保持 `collisionPadding` = `OVERLAY_COLLISION_PADDING`(8px;Tooltip / Popover / DropdownMenu 皆接此 const)。例外:HoverCard 用 12(Radix / browser rounding 讓 visual padding 少 1-2px 的補償,見 `hover-card.tsx` 註解)。
+
 | 浮層類型 | sideOffset | 說明 |
 |---------|-----------|------|
 | Tooltip | 8px | TooltipContent 預設值 |
@@ -70,10 +74,5 @@ elevation-100 < elevation-200，數字越大浮起越高。
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `motion.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
 - `slider.spec.md`
 - `token-system.spec.md`

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

@@ -1,4 +1,4 @@
-<!-- @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 設計原則
 
@@ -105,7 +105,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 +137,19 @@ 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-*`)未使用。
+
 ---
 
 ## 心智模型(三步推理 + 具體 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 +192,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 +218,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 +267,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')
 ```
 
@@ -301,13 +299,8 @@ document.documentElement.setAttribute('data-layout-space', 'lg')
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `app-shell.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
 - `description-list.spec.md`
 - `empty.spec.md`
-- `file-viewer.spec.md`
+- `overlay-surface.spec.md`
 - `token-system.spec.md`
 - `uiSize.spec.md`

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

@@ -14,27 +14,29 @@ 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 / ProfileCard / Avatar / OverflowIndicator)的 hover 開啟 / 關閉延遲統一。
 
 ## 定位
 
-Hover delay token 是「hover 觸發 → overlay 顯示」之間的等待時間。**目的不是動畫長度,是「user 真的想看」過濾器** — 短暫滑過不該觸發 expensive overlay(ProfileCard fetch 資料 / Tooltip 視覺擾動)。
+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。
 
 ## 三層 tier 系統
 
 | Token | 值 | 用於 | 為何 |
 |---|---|---|---|
-| `--hover-delay-plain` | `500ms` | Tooltip 純文字提示 | 被動 hint,需 user「真停留」才觸發,避免滑過列表時 N 次視覺擾動。對齊 Material 3 plain tooltip 500ms / Apple HIG ~500ms / shadcn-Radix default 500ms 主流共識 |
+| `--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}` 值 |
 
 ## 為何不用單一值 / 為何不沿用過去 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。
+- **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,等出來變干擾。
@@ -66,8 +68,8 @@ Hover delay token 是「hover 觸發 → overlay 顯示」之間的等待時間
 
 ## 消費者
 
-- `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/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`
@@ -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,9 @@ Hover delay token 是「hover 觸發 → overlay 顯示」之間的等待時間
 - `../../components/Tooltip/tooltip.spec.md`(consumer)
 - `../../components/HoverCard/hover-card.spec.md`(consumer)
 - `../../components/Avatar/avatar.spec.md`(consumer)
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `hover-card.spec.md`

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,41 +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 隔離。
 
-## 消費者
-
-Avatar、Sidebar、MenuItem、Slider、Switch、Steps、Chip。
-
-## 反向引用
-
-- Disabled 策略選擇框架：`tokens/color/color.spec.md`
+## A11y（disabled 訊號不只透明度）
 
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
+透明度是視覺輔助,不是 disabled 的唯一訊號:語意由 native `disabled` / `aria-disabled` attribute 傳達給輔助技術（SR 朗讀 unavailable,非依賴視覺）,並伴隨互動阻斷（無法觸發 / `cursor-not-allowed`）提供非色彩線索——色弱使用者不依賴 0.45 fade 也能辨識停用狀態。
 
-> 本節由 `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`
+直接套用 `opacity-disabled` 的元件（grep 驗證 2026-06-11）：Avatar（Field disabled context self-dim）、Button（`aria-disabled` 分支）、MenuItem、Rating（disabled / loading 整塊）、Steps、Switch、Textarea（disabled 分支）、DataTable（drag source 半透 + 整表 refresh loading reuse，經 `lib/drag-visual.ts`）。
 
-## 被引用(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。若要手動補充,寫在本節之前。
+## 反向引用
 
-- `token-system.spec.md`
+- Disabled 策略選擇框架：`tokens/color/color.spec.md`

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**:
@@ -79,7 +84,7 @@ 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。
 
@@ -104,9 +109,15 @@ 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()`)
+- **Dim 48**(= `design-system-audit/SKILL.md` 的「Unused / orphan token detector」audit 維度)— 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 出現
 - **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,32 +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。
 
 捨棄連續 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 成本。
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
-- `token-system.spec.md`

package/src/tokens/token-system.spec.md

@@ -228,16 +228,13 @@ Tailwind v4 `@theme inline` 把 CSS variable 升級成 utility class。每 famil
 
 ---
 
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護。
-
-- `tokens/README.md`(Public vs Internal token 表 cross-reference)
-- `color/color.spec.md`(L1/L2 上游 SSOT)
-- `uiSize/uiSize.spec.md`(L3 Family + L4 Layout 上游 SSOT)
-- `layoutSpace/layoutSpace.spec.md`(L4 Layout 上游 SSOT)
-- `elevation/elevation.spec.md`(L1 co-location rationale)
-- `opacity/opacity.spec.md`(L1 classification)
-- `radius/radius.spec.md`(L3 Family classification)
-- `typography/typography.spec.md`(L3 Family classification)
-- `.claude/rules/ui-development.md`「Token 命名 4 條硬規則」(下游 lint-style summary)
+## 相關
+
+- `README.md`(tokens charter)— 檔案路徑 + Public vs Internal token 表
+- `color/color.spec.md` — L1/L2 色彩 family 具體規則(含 Tag / Avatar 直接消費 L1 的流派定位)
+- `uiSize/uiSize.spec.md` — L3 Family / L4 Layout 尺寸 token
+- `typography/typography.spec.md` — `--font-*` family
+- `elevation/elevation.spec.md` — `--elevation-*`(住 `color/primitives.css`,理由見「跨 family co-location 規則」)
+- `layoutSpace/layoutSpace.spec.md` — `--layout-space-*` 抽象 spacing rhythm
+
+---