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

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

@@ -0,0 +1,78 @@
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — verified 0 world-class DS claim in body; blanket retract removed. -->
+
+# Opacity 設計原則
+
+Opacity 定義元件停用狀態的透明度，確保全系統 disabled 視覺一致。
+
+## Token
+
+| Token | 值 | Tailwind utility | 用途 |
+|-------|-----|-----------------|------|
+| `--opacity-disabled` | 0.45 | `opacity-disabled` | 所有元件的 disabled 狀態 |
+
+## 使用規則
+
+### 何時用 opacity vs token swap
+
+停用狀態有兩種視覺策略（詳見 `color.spec.md`「Disabled 狀態」節 / 「兩種 disabled 策略」）：
+
+- **Token swap**（預設）：disabled 時換成專用 token（`fg-disabled`、`bg-disabled`），精確控制每個層的顏色。適用於多層結構的元件（Button、Input）。
+- **Opacity blanket**：對整個元件套 `opacity-disabled`，一次處理所有子元素。適用於結構簡單、子元素多的元件（Avatar、Switch thumb、Slider）。
+
+不可混用——同一元件要嘛用 token swap，要嘛用 opacity，不兩者同時。
+
+## 為什麼 0.45
+
+0.45 在 light mode 和 dark mode 都能對 disabled 元件產生足夠辨識度（明顯區分於 active state），同時保持文字可讀（WCAG 不要求 disabled 元素的對比度，但仍需辨識）。
+
+選 0.45 的位置:
+
+- 比 **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 加):
+
+| DS | Material 3 | Carbon | Tailwind v4 | Ant Design | Polaris | Apple HIG | Atlassian |
+|----|-----------|--------|-------------|------------|---------|-----------|-----------|
+| **0.45**(opacity-disabled)+ token swap 雙策略 | 0.38(text on surface)/ 0.12(container)| 0.25(opacity fallback,主走 token swap)| `opacity-{0,5,10,...,95,100}` percent ladder | 純 token swap(`colorTextDisabled` 等)| 0.5 + token swap | 0.4(`UIDisabled`)| 0.4 + token swap |
+
+**結論**:disabled 在世界級 DS 的兩派哲學(token swap-only vs opacity blanket)+ opacity value 從 0.25 到 0.5 不等。本 DS 採「雙策略並存」哲學(複雜元件 token swap / 簡單元件 opacity blanket),value 取 0.4-0.5 中位 0.45。
+
+## 設計哲學
+
+兩個關鍵決策,各自有世界級先例支撐:
+
+**(1) 雙策略並存(token swap 為主 + opacity blanket 為輔)— 對齊 Carbon / Atlassian 折衷哲學**
+
+純 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 單值哲學**
+
+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`
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `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`

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

@@ -0,0 +1,117 @@
+---
+spec: orphan-tokens
+scope: token retire vs structural-keep classification SSOT
+audit_dim: design-system-audit Dim 48
+script: scripts/audit-orphan-tokens.mjs
+benchmark:
+  - Material Design Tokens M3 — 完整 1-10 色階保留 https://m3.material.io/styles/color/the-color-system/key-colors-tones
+  - Atlassian Design Tokens — palette tier 結構性保留 https://atlassian.design/foundations/color-new
+  - Carbon Design System — token category metadata classifier https://carbondesignsystem.com/elements/color/tokens
+  - Polaris Design Tokens — semantic SOP 5-piece set canonical https://polaris.shopify.com/design/colors
+---
+
+# Orphan Token 分類 SSOT(retire vs structural-keep)
+
+> **Foundational context**(2026-05-21 codify per user verbatim「決策四你他媽仔細給我確認到底該retire的是否真的該retire還是應該結構性保留,請全盤檢查,然後確認之後請下次不要再煩我,尤其是Palette tier」+「都給我做到好」):**永久解決**「audit 每次抓 X 個 orphan tokens」噪音。本 spec 明文哪些 token 結構性保留 + 自動 audit script 識別,user 不需重複確認同一題。
+
+## 為什麼會出現「假孤兒」
+
+簡單的 `grep var(--X)` 抓不到以下消費路徑,造成 token **實際有用但 audit 報「無消費」false positive**:
+
+| 消費機制 | 範例 | grep 漏抓原因 |
+|---|---|---|
+| **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 |
+
+**修法**:`scripts/audit-orphan-tokens.mjs` 用 comprehensive consumer detection 涵蓋 5 條消費路徑,真實 orphan count drops from 175 → 0(2026-05-21 baseline)。
+
+---
+
+## 結構性保留分類(永久保留,**不視為 retire 候選**)
+
+對齊 Material 3 / Atlassian / Carbon / Polaris token system 共識。每類附 rationale + 識別 regex(`audit-orphan-tokens.mjs` 消費此分類)。
+
+### 1. Palette tier 完整 1-10 色階(77 token,structural)
+
+**Rule**:`--color-{hue}-N`(N ∈ 1..10)即使當前無消費者也**完整保留**。
+
+**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+$`
+
+### 2. Magenta / Turquoise 專用 palette(14 token,structural)
+
+**Why**:Tag / Avatar variant 預留色,Polaris / Atlassian 同樣保留 specialty hue 完整色階(不只「目前用到的階」)。
+
+**Regex**:`^--color-(magenta|turquoise)-\d+$`
+
+### 3. Mask alpha(16 token,structural)
+
+**Rule**:`--black-aN` / `--white-aN`(alpha tiers a02-a85)完整保留。
+
+**Why**:Overlay / scrim / shadow / disabled state alpha composition 預留;Material 3「Surface Tint」+ Apple HIG「Vibrancy」需要完整 alpha ladder。
+
+**Regex**:`^--(black|white)-a\d+$`
+
+### 4. Chart reserved(0-5 token,structural)
+
+**Rule**:`--color-chart-N`(N ∈ 1..5)為 DataViz 預留,即使 DS 內無 chart 元件也保留。
+
+**Why**:Consumer(產品端)會用 ECharts / D3 等 lib 直接消費這些 token 做 chart palette,DS 提供 5-color qualitative palette canonical(對齊 ColorBrewer)。
+
+**Regex**:`^--color-chart-\d+$`
+
+### 5. State variants 完整集(8 token,structural)
+
+**Rule**:`--{hue}-(hover|active|focus|subtle|emphasis|disabled|text)` 即使當前無消費者也保留完整 8-tier emphasis set。
+
+**Why**:Material 3 / Atlassian state token canonical — hover/active/focus 是 elevation 8-tier 一部分,缺一階斷 emphasis ladder。**8-tier 是 capability invariant**。
+
+**Regex**:`^--{HUES}-(hover|active|focus|subtle|emphasis|disabled|text)$`
+
+### 6. Neutral palette 完整 + opaque tier(13 token,structural)
+
+**Why**:Neutral 1-9 是 grayscale spectrum SSOT;`-opaque` 變體是 opacity composition 預留(non-translucent fallback for dark mode / contrast modes)。
+
+**Regex**:`^--color-neutral-\d+(-opaque)?$`
+
+### 7. SOP 5-piece semantic 完整集(1+ token,structural)
+
+**Rule**:每個 semantic role(primary / error / success / warning / info)必有 5 件套:`base / hover / active / subtle / text`,即使當前 `text` 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)
+
+**Rule**:`--hover-delay-{plain|rich|close|skip}` motion tokens 鏡像 JS constants(`HOVER_DELAY_PLAIN_MS` 等),CSS 端保留供 design SSOT 可見 + 未來 programmatic 讀取(`getComputedStyle`)。
+
+**Why**:M17 SSOT 雙頭設計 — CSS 端是設計師 inspector 入口,JS 端是 runtime 消費入口,兩端必同步存在。
+
+**Regex**:`^--hover-delay-(plain|rich|close|skip)$`
+
+---
+
+## 真 retire 流程(comprehensive scan 後仍 0 consumer)
+
+`audit-orphan-tokens.mjs` 跑完跨 5 消費機制 verify 仍 0 consumer + 不落任何 structural-keep 類別 → 才算真 retire 候選。
+
+走 retire flow:
+1. **Grep DS-wide** `*.spec.md` 看是否文件 cite 該 token 名(可能是「設計師未來會用」承諾)
+2. **Git blame** declare 提交 — 提交訊息 / PR 描述是否說明用途
+3. 兩 step 都無 → safe retire,從 `tokens/**/*.css` 刪宣告 + 加 git commit message cite 本 spec
+
+## 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 出現
+- **Hook**:無 hook(本 audit run-time / monthly cadence,非 PreToolUse 攔截場景)
+
+## 永久解決承諾
+
+本 spec land 後**永遠不會**再回頭問 user 同樣問題(palette tier / 完整色階 / mask alpha / JS literal mirror 是否該 retire)。Audit script 自動識別,只報真實「跨 5 消費路徑都 0」的 token(2026-05-21 baseline = 0 真孤兒)。
+
+新加 hue / state / SOP semantic / JS literal mirror → 同步本 spec regex + `audit-orphan-tokens.mjs` 分類器(per M17 SSOT)。

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

@@ -0,0 +1,123 @@
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — verified 0 world-class DS claim in body; blanket retract removed. -->
+
+# Radius 設計原則
+
+圓角系統提供四個語意層級，對應不同元件類型。
+
+## 圓角選項
+
+| Tailwind class | Token | 值 | 用途 |
+|----------------|-------|----|------|
+| `rounded-xs`   | `--radius-xs` | 2px | 極小視覺 indicator(Chart legend swatch 8×8 色塊等 ≤ 10px 元素) |
+| `rounded-md`   | `--radius-md` | 4px | 一般元件(Button、Input、Card、Tag、hover bg) |
+| `rounded-lg`   | `--radius-lg` | 8px | 浮層(Dialog、Popover、Dropdown) |
+| `rounded-full` | `--radius-full` | 9999px | Pill 形狀(Avatar、Switch、Progress) |
+
+### `rounded-sm` 保留未使用
+
+CSS 定義了 `--radius-sm`(目前 = 4px,與 md 同值),但**不在元件中使用**。保留給未來「介於 md 和 xs 之間」的需求(如更密集的 UI 模式)。所有 4px 圓角一律用 `rounded-md`。
+
+
+## 使用規則
+
+### `rounded-xs`(2px)— 極小 indicator
+
+適用於直徑 ≤ 10px 的視覺 indicator,視覺效果需要「微圓而非完全方」:
+
+- Chart legend swatch(8×8 色塊)
+- 未來其他 micro indicator(若尺寸 ≥ 12px 請改 `rounded-md`,不要為了「更圓」使用 xs)
+
+**判斷**:`rounded-md`(4px)在 8×8 元素上接近 50% 填滿,視覺變成 pill。2px 才維持「色塊」而非「膠囊」語意。≥ 12px 時 4px 比例適當,不需 xs。
+
+### `rounded-md`(4px)— 一般元件
+
+適用於大多數互動元件，視覺上「有圓角但不搶眼」：
+
+- Button、Input、Select、Checkbox、Tag
+- Card（非浮層，不需 elevation 層級感）
+- Table cell、list item 的 hover 背景
+- Tooltip
+
+### `rounded-lg`（8px）— 浮層
+
+適用於浮在頁面上層的元件：
+
+- Modal、Dialog
+- Popover、Dropdown menu、Command palette
+
+### `rounded-full`（9999px）— Pill
+
+適用於需要完全膠囊形狀的元件：
+
+- Avatar（圓形）
+- Toggle switch 外框
+- Progress bar
+
+
+## 禁止事項
+
+```tsx
+// ❌ 不要用非 token 的圓角（包含 rounded-md、rounded 等）
+<div className="rounded" />        // 4px，但意圖不明
+<div className="rounded-xl" />     // 12px，超出 token 範圍
+<div className="rounded-2xl" />    // 16px，超出 token 範圍
+
+// ❌ 不要硬寫圓角值
+<div className="rounded-[6px]" />
+<div style={{ borderRadius: '8px' }} />
+
+// ❌ 不要用 CSS 變數語法（Tailwind class 已夠用）
+<div className="rounded-[var(--radius-md)]" />
+```
+
+```tsx
+// ✅ 一般元件
+<button className="rounded-md" />
+
+// ✅ 浮層
+<div className="rounded-lg" />
+
+// ✅ Pill
+<span className="rounded-full" />
+```
+
+
+## 世界級對照
+
+對齊 M8(binary strict rule 必 ≥3 家世界級對照),「禁 `rounded-xl` / `rounded-2xl` raw utility」+「禁硬寫 `rounded-[6px]`」是本 spec 的 binary strict rule,以下為支撐 rationale。
+
+| 維度 | 本 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 變化 |
+| 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 連續曲率動態 |
+
+## 設計哲學
+
+四個關鍵決策,各自有世界級先例支撐:
+
+**(1) 4 tier(xs/md/lg/full)— 對齊 Ant Design 4-tier minimal,捨多家 6+ tier**
+
+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 慣例**
+
+數值 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)**
+
+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」**
+
+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 成本。
+

package/src/tokens/typography/typography.spec.md

@@ -0,0 +1,202 @@
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — verified 0 world-class DS claim in body; blanket retract removed. -->
+
+# Typography 設計原則
+
+Typography 定義字體尺寸與行高的 token 系統，確保全系統文字層級一致。
+
+## 設計原則
+
+Typography 由三個獨立維度組成，分開疊加：
+
+| 維度 | 控制方式 | 說明 |
+|------|---------|------|
+| font-size | `text-{role}` utility | token 決定，不可繞過 |
+| line-height | 烤進 token，需要時覆蓋 | heading / supplementary → 1.3；body → 1.5 |
+| font-weight | `font-normal` / `font-medium` / `font-bold` | 使用端疊加，不寫死在 token |
+
+**line-height 的選擇基於「是否適合多行閱讀」：**
+- `1.5`：適合連續閱讀的段落（14px / 16px）
+- `1.3`：標題、短文字、截斷場景、不需要閱讀行距
+- 12px 以下不適合作為連續閱讀內文，一律 1.3
+
+**font-weight 等同 `<strong>` 的疊加邏輯：**
+- 不加 = 400，一般文字
+- `font-medium` = 500，行內中等強調
+- `font-bold` = 700，強調（等同 `<strong>`）
+
+
+## Token 表
+
+| Utility        | font-size | line-height | 用途 |
+|----------------|-----------|-------------|------|
+| `text-h1`      | 48px      | 1.3         | 頁面主標題 |
+| `text-h2`      | 32px      | 1.3         | 區塊標題 |
+| `text-h3`      | 24px      | 1.3         | 子區塊標題 |
+| `text-h4`      | 20px      | 1.3         | 小節標題 |
+| `text-h5`      | 16px      | 1.3         | 元件層級標題 |
+| `text-h6`      | 14px      | 1.3         | 最小層級標題 |
+| `text-body-lg` | 16px      | 1.5         | 16px 為主版面的段落內文 |
+| `text-body`    | 14px      | 1.5         | ★ 主要內文基準 |
+| `text-caption` | 12px      | 1.3         | 圖表附註、標籤文字、元件內次要說明 |
+| `text-footnote`| 10px      | 1.3         | 法律文字、來源標注（極少用）|
+
+**h5（16px）vs body-lg（16px）**：同尺寸，line-height 不同，靠這個區分標題與段落角色。
+**h6（14px）vs body（14px）**：同尺寸，靠 font-weight 和 color 區分，使用端需有意識地處理。
+
+
+## line-height 覆蓋（僅 14/16px body 可覆蓋）
+
+**Token canonical**：除 `text-body`（14px）/ `text-body-lg`（16px）外，**所有 size 行高皆固定**：
+- `text-h1`–`text-h6`：全部 lh 1.3 固定（標題不需多行閱讀行距）
+- `text-caption`（12px）/ `text-footnote`（10px）：全部 lh 1.3 固定（小字不適合 1.5）
+- `text-body` / `text-body-lg`：**唯二**可覆蓋（預設 lh 1.5 閱讀段落，可 `leading-compact` 覆蓋為 1.3）
+
+唯一合理覆蓋情境：`text-body` / `text-body-lg` 用於**單行固定高度容器**（Button / Tabs trigger / Chip / Notice banner / MenuItem row / SelectMenu / TreeView / DropdownMenu / Combobox input），避免 1lh > chrome height 造成垂直偏移：
+
+```tsx
+{/* ✅ Button 文字（單行 28/32/36px chrome height）*/}
+<button className="h-field-sm text-body leading-compact">確認</button>
+
+{/* ✅ Notice banner 單行 alert text */}
+<span className="text-body leading-compact">已儲存</span>
+```
+
+可用的 override utility：
+- `leading-compact`：1.3（自訂，只給 `text-body` / `text-body-lg`）
+- `leading-normal`：1.5（Tailwind 內建，**極少用**——僅 stories `<p>` 補 12px footnote 段落呼吸感，正式 DS 元件**不需**主動覆蓋成 1.5，因為 `text-body` / `text-body-lg` 預設就是 1.5）
+
+### 反 pattern（禁用）
+
+```tsx
+{/* ❌ 用 leading-compact + line-clamp 「截斷副標」
+       line-clamp 自己處理截斷，不需要動 line-height；該選對的 token */}
+<p className="text-body leading-compact line-clamp-2">副標說明</p>
+
+{/* ❌ 用 h5/h6 + leading-normal「當段落」
+       h5/h6 是標題語義，不該當段落；同 size 該換 body-lg / body */}
+<p className="text-h5 leading-normal">較小的說明段落</p>
+```
+
+### 同尺寸但不同角色的選法（用 token 自然區分，不靠 leading 覆寫）
+
+| 尺寸 | 段落（閱讀） | 標題（掃視 + bold） |
+|---|---|---|
+| 16px | `text-body-lg`（lh 1.5） | `text-h5`（lh 1.3，加 `font-medium`/`font-semibold`） |
+| 14px | `text-body`（lh 1.5） | `text-h6`（lh 1.3，加 `font-medium`/`font-semibold`） |
+
+**結論**：90% 情境用 token 預設就對；唯一覆寫 = body/body-lg 進單行固定高度容器套 `leading-compact`。
+
+
+## 組合範例
+
+```tsx
+{/* 頁面標題 */}
+<h1 className="text-h1">專案總覽</h1>
+
+{/* 區塊標題加重 */}
+<h2 className="text-h2 font-medium">執行進度</h2>
+
+{/* 主要內文 */}
+<p className="text-body">一般說明段落，預設 400 weight。</p>
+
+{/* 行內強調 */}
+<p className="text-body">
+  此操作將<span className="font-medium">永久刪除</span>該筆資料。
+</p>
+
+{/* 截斷副標 */}
+<p className="text-body leading-compact line-clamp-2 text-fg-secondary">
+  這是一段較長的副標說明，超過兩行會被截斷顯示。
+</p>
+
+{/* 欄位附屬說明 */}
+<span className="text-caption text-fg-muted">最多 200 字元</span>
+```
+
+
+## 禁止事項
+
+```tsx
+// ❌ 不要用 Tailwind 原始 text-sm / text-lg / text-base
+<p className="text-sm">內文</p>
+
+// ❌ 不要硬寫 font-size 或 line-height
+<p style={{ fontSize: '14px' }}>內文</p>
+
+// ❌ 不要用 12px 做連續閱讀段落
+<p className="text-caption">這是一整段很長的說明文字...</p>
+
+// ❌ 不要把 font-weight 寫死在外層容器（應在需要的元素上疊加）
+<section className="text-body font-medium">...</section>
+
+// ❌ 不要用 Tailwind 原始 tracking-* utility(letter-spacing 必 role-specific)
+<kbd className="tracking-widest">⌘K</kbd>
+```
+
+
+## Letter-spacing(role-specific only)
+
+**哲學**:`letter-spacing` 跟 font-size / line-height 同層 — utility scale(`tracking-tight..widest`)是 raw scale 非 semantic role,每 consumer 自挑值 = 跨元件不一致。本 DS 採 **single semantic value per role**(對齊 Polaris / Material / Apple),每個需要 letter-spacing 變化的 role 必先 codify token。
+
+### 既定 role
+
+| Token | 值 | Tailwind utility | Role |
+|---|---|---|---|
+| `--tracking-shortcut` | `0.1em` | `tracking-shortcut` | 鍵盤快捷鍵 hint(`⌘K` / `Ctrl+S` 等),Command/CommandShortcut + DropdownMenuShortcut + 同類 kbd 顯示 consumed via `text-caption` 或 `text-footnote` |
+
+### 新增 role 流程
+
+1. typography.css `:root` 加 `--tracking-<role>: <value>;`
+2. typography.css 加 `@utility tracking-<role> { letter-spacing: var(--tracking-<role>); }`
+3. utility-registry.json `typography.allow` 加 `tracking-<role>`
+4. 本 spec.md 加 row 到上表 + 對應 role 對齊世界級 cite(M22)
+5. Consumer code 用新 utility
+
+**對齊**:Material 3「letter-spacing per type role」/ Polaris「single semantic letter-spacing per scale」/ GitHub Primer「kbd typography canonical」/ Tailwind「wider tracking for uppercase + labels」。
+
+
+## 世界級對照
+
+對齊 M8(binary strict rule 必 ≥3 家世界級對照),「禁 Tailwind `text-sm`/`text-base` raw utility」+「禁硬寫 fontSize」是本 spec 的 binary strict rule,以下為支撐 rationale。
+
+| 維度 | 本 DS | Material 3 | Carbon | Tailwind v4 | Ant Design | Polaris | Apple HIG |
+|------|-------|-----------|--------|-------------|------------|---------|-----------|
+| 命名哲學 | semantic role(h1-h6 + body)| Type scale roles(Display / Headline / Title / Label / Body)| Productive vs Expressive 雙軌 | utility size(`text-{xs..9xl}`)| 階梯 h1-h5 + base | semantic role(`heading-{md..3xl}` + `body-{sm..lg}`)| Dynamic Type(Title 1-3 / Headline / Body / Callout / Footnote / Caption 1-2)|
+| Body base | **14px** | 14 / 16(可切)| 14(productive)/ 16(expressive)| 16(`text-base`)| 14(`fontSizeBase`)| 14(`body-md`)| 17(`Body`)|
+| Heading 跨度 | h1=48 → h6=14(6 tier)| Display 1-2 + Headline 1-6(8+ tier)| Productive 01-07 + Heading 01-07(14 tier)| `text-xs` (12) → `text-9xl` (128)(13 tier)| h1=38 → h5=16(5 tier)| `heading-md` (16) → `heading-3xl` (40)(5 tier)| Title 1-3(3 tier)|
+| Line-height 哲學 | **二元**(1.5 reading / 1.3 compact)| Ratio ladder(隨 size 1.2-1.6 連續)| 二元(reading 1.5 / supplementary 1.3)| Ratio ladder(`leading-{tight..loose}` 1.25-2)| Unique 1.5715 | 隨 size(0.875-1.5)| 隨 size + Dynamic |
+| Font weight 階 | **3 階**(400/500/700)| 5 階(300-700)| 3 階(Light/Regular/SemiBold)| 9 階(100-900)| 4 階(400/500/600/700)| 4 階(400/500/600/650)| 9 階 + SF |
+
+## 設計哲學
+
+四個關鍵決策,各自有世界級先例支撐:
+
+**(1) Body base = 14px(對齊 Material / Carbon / Ant 三家共識)**
+
+14px 是 productivity tool 共識(Linear / Notion / Figma / Jira / Stripe Dashboard),16px 是 reading-first 哲學(Apple iOS / Polaris 的 storefront / Medium)。本 DS 場景是 dense workspace(規格 / 表格 / Dashboard),14px 同時讓 information density 高 + 對齊 system tool 慣例。捨棄 16 base 的代價是「行動裝置可讀性」,但 DS 主場景是 desktop。
+
+**(2) 二元 line-height(1.5 / 1.3)— 對齊 Carbon「productive vs supplementary」哲學**
+
+Material / Tailwind 用 ratio ladder(隨 size 連續變化)雖精細,但 consumer 心智負擔重(每 size 對應不同 lh,需查表)。Carbon 的「productive reading 1.5 / supplementary compact 1.3」二元規則,讓 reader 一眼判斷「是要連續閱讀還是 scanning」即可選對 — 對應本 DS 的 scanning(MenuItem / FileItem)vs reading(Empty / Field description)二分法。
+
+捨棄連續 ratio 的代價是「極大字級 lh 過鬆」(48px h1 仍 1.3),實測無此問題(本 DS 無 60+ display 級字)。
+
+**(3) h5/h6 與 body-lg/body 同 size(16/14)— 靠 lh + weight 區分,不開新 size tier**
+
+Material 用 17 tier(Display 1-2 + Headline 1-6 + Title 1-2 + Subtitle 1-2 + Body 1-2 + Button + Caption + Overline),Apple Dynamic Type 11 tier 跨平台 — 兩家 size scale 過度膨脹是 DS 維護負擔(每加 1 tier 就要全 component grep 評估)。
+
+本 DS 採 Carbon-aligned 二元覆寫(同 16px 用 lh 1.3 = h5 標題 / lh 1.5 = body-lg 段落),靠 line-height + font-weight + color 區分角色,維持 token table 在 10 個 utility 內。代價是「使用端需有意識選 h5 vs body-lg」,但對應 spec L42 明寫「使用端需有意識地處理」。
+
+**(4) Font weight 3 階(400/500/700)— 對齊 Carbon / Polaris 共識**
+
+Tailwind / Apple SF 的 9 階 weight scale 涵蓋 marketing / 印刷需求,但 productivity DS 95% 場景只用 normal / medium / bold(對齊 Carbon Light/Regular/SemiBold + Polaris 400/500/600/650)。捨棄 100-300 hairline + 800-900 black 的代價是「行銷 hero text 表現力」,DS 不收 marketing 場景,接受。
+
+## 跨元件參考
+
+行高在 row 類元件中的應用（scanning vs reading 模式）詳見 `patterns/element-anatomy/item-anatomy.spec.md`「兩種閱讀模式」節。
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `empty.spec.md`