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

package/src/tokens/radius/radius.stories.tsx

@@ -0,0 +1,87 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { Button } from '@/design-system/components/Button/button'
+import { Plus } from 'lucide-react'
+
+const meta: Meta = {
+  title: 'Design System/Tokens/Radius',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: `
+圓角系統。四個選項,對應四種尺寸情境。
+
+完整規則:\`packages/design-system/src/tokens/radius/radius.spec.md\`
+        `,
+      },
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj
+
+
+export const Overview: Story = {
+  name: '總覽',
+  render: () => (
+    <div className="max-w-2xl space-y-8">
+      {/* rounded-xs */}
+      <div>
+        <div className="flex items-baseline gap-3 mb-3">
+          <code className="text-caption font-medium">rounded-xs</code>
+          <span className="text-caption text-fg-muted">2px — 極小 indicator(≤ 10px)</span>
+        </div>
+        <div className="flex flex-wrap gap-3 items-center">
+          <div aria-hidden="true" className="rounded-xs bg-primary h-2 w-2" />
+          <div aria-hidden="true" className="rounded-xs bg-success h-2 w-2" />
+          <div aria-hidden="true" className="rounded-xs bg-error h-2 w-2" />
+          <span className="text-caption text-fg-muted ml-2">Chart legend swatch(8×8 色塊):md 4px 在 8×8 上接近 50% 圓,xs 2px 保留「色塊」而非「膠囊」語意</span>
+        </div>
+      </div>
+
+      {/* rounded-md */}
+      <div>
+        <div className="flex items-baseline gap-3 mb-3">
+          <code className="text-caption font-medium">rounded-md</code>
+          <span className="text-caption text-fg-muted">4px — 一般元件</span>
+        </div>
+        <div className="flex flex-wrap gap-3 items-center">
+          <Button variant="primary" startIcon={Plus}>Button</Button>
+          <div className="rounded-md border border-border bg-surface px-3 h-field-sm flex items-center text-body text-fg-muted w-40">Input</div>
+          <div className="rounded-md bg-muted px-2 h-6 flex items-center text-caption font-medium">Tag</div>
+          <div className="rounded-md border border-border bg-surface p-3 text-caption text-fg-muted">Card</div>
+        </div>
+      </div>
+
+      {/* rounded-lg */}
+      <div>
+        <div className="flex items-baseline gap-3 mb-3">
+          <code className="text-caption font-medium">rounded-lg</code>
+          <span className="text-caption text-fg-muted">8px — 浮層 / 容器</span>
+        </div>
+        <div className="rounded-lg border border-border bg-surface-raised p-4 max-w-xs" style={{ boxShadow: 'var(--elevation-200)' }}>
+          <p className="text-body font-medium mb-1">Popover</p>
+          <p className="text-caption text-fg-muted">Modal、Popover、Dropdown 等浮層使用 rounded-lg。</p>
+        </div>
+      </div>
+
+      {/* rounded-full */}
+      <div>
+        <div className="flex items-baseline gap-3 mb-3">
+          <code className="text-caption font-medium">rounded-full</code>
+          <span className="text-caption text-fg-muted">9999px — Pill / 圓形</span>
+        </div>
+        <div className="flex gap-3 items-center">
+          <div className="rounded-full bg-primary h-8 w-8 flex items-center justify-center text-white text-caption font-medium">A</div>
+          <span
+            className="rounded-full inline-flex items-center justify-center h-5 min-w-5 px-1.5 text-white text-footnote font-medium leading-none"
+            style={{ background: 'var(--notification)' }}
+          >3</span>
+          <div className="rounded-full bg-[var(--primary-subtle)] text-[var(--primary)] px-3 h-6 flex items-center text-caption font-medium">Badge</div>
+        </div>
+      </div>
+    </div>
+  ),
+}

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

@@ -0,0 +1,241 @@
+<!-- @benchmark-cited: world-class layered token architecture — Polaris/Material/Atlassian/Carbon/Apple HIG (URLs in body table) -->
+
+# Token System 設計原則(SSOT,跨所有 token family)
+
+> **Foundational SSOT rationale**(cap 1200,per `AGENTS.md`「行數預算」的 foundational SSOT 例外 ≤ 800-1200):
+> 本 spec 是**所有 token family 共同遵循的上游 canonical**——5-layer 架構、命名 family-scoped 規則、token vs hardcode 判斷、cross-family co-location rationale、SSOT consumer scope。改變本 spec = 影響全 DS 30+ 元件 + 200+ token。改一處不對齊就 drift,所以集中在這裡為 SSOT;個別 family spec(color / typography / uiSize 等)只 codify 自家具體規則,不重述上游架構。
+
+## 架構流派定位
+
+業界世界級 DS 都採「**分層 token 架構**」(layered token architecture),底層 raw value,上層 semantic intent。各家命名不同但概念一致:
+
+| 流派 | 代表系統 | 層命名 | 對應我們 |
+|---|---|---|---|
+| **3-layer reference / system / component** | Material 3 | `md-ref-*` → `md-sys-*` → `md-comp-*` | Primitive / Semantic / Internal |
+| **2-layer base / semantic + token-per-component** | Polaris | `--p-color-blue-500` → `--p-color-bg-primary` | Primitive / Semantic |
+| **3-layer foundation / semantic / specific** | Atlassian DS | `color.text.brand` → 直接 raw oklch in foundation | Primitive / Semantic |
+| **2-layer global / alias + size scale** | Carbon | `$blue-60` → `$button-primary` | Primitive / Semantic |
+| **2-layer semantic + dynamic** | Apple HIG | `systemBlue` → `UIColor.label`(adaptive) | Primitive / Semantic |
+
+**我們選 5-layer**(Primitive / Semantic / Family / Layout / Internal),擴充 Material 3 流派加兩層處理結構化常數:
+- **Family**(Material 3 `md-sys-*` 子分支):cross-component 共用的具體尺寸 family(`--field-height-*` / `--table-row-*` / `--tab-height-*`)
+- **Layout**(Material `md-comp-layout` 對應):跨層佈局常數(`--layout-space-loose` / `--sidebar-width` / `--chrome-header-height`)
+- **Internal**(Material `md-comp-*` 對應):單元件內部不對 consumer 公開(目前 0 個——所有跨元件都 promote 到 Family,單元件 hardcode in tsx)
+
+`tokens/README.md`「Public vs Internal token」表 cross-reference 本 spec 此段。
+
+---
+
+## 5-Layer 架構
+
+| Layer | 抽象度 | 例子 | 居住檔案 | Consumer scope |
+|---|---|---|---|---|
+| **L1 Primitive** | 原始 raw value(無 mode 知識 / 無 component 知識) | `--color-blue-6` / `--color-neutral-9-opaque` / `--black-a45` / `--elevation-100` | `color/primitives.css` | **Internal**——只供 semantic 層 alias,或 Tag/Avatar 等「按色分類」元件直接消費(per `color.spec.md` 流派定位) |
+| **L2 Semantic** | 表達**意圖** / 封裝 mode swap | `--primary` / `--error` / `--canvas` / `--surface` / `--foreground` / `--fg-disabled` / `--bg-disabled` | `color/semantic.css` | **Public**——consumer 直接 `bg-primary` / `text-foreground` |
+| **L3 Family**(cross-component 共用尺寸) | family-scoped semantic value | `--field-height-md` / `--table-row-md` / `--tab-height-md` / `--tree-indent-md` | `uiSize/uiSize.css` | **Internal**——DS 內部 primitive 消費,consumer 用 `<Button size="sm">` 不直接寫 token |
+| **L4 Layout**(全 app 結構常數) | 全域 layout primitive 尺寸 | `--sidebar-width` / `--sidebar-width-mobile` / `--chrome-header-height` / `--layout-space-loose` | `uiSize/uiSize.css` + `layoutSpace/layoutSpace.css` | **Public**——AppShell / Sidebar / ChromeHeader 等 layout primitive 元件直接消費 |
+| **L5 Internal**(單元件內部) | 單元件 only | (目前 0 個) | — | 不開——若只 1 個 consumer hardcode in tsx 即可,2+ consumer 才升 L3/L4 |
+
+**Layer 判斷流程**:
+
+```
+新增值 / 公式 / 結構常數時 ──→
+  是 raw color/shadow/alpha 沒 component 意圖? ─→ L1 Primitive
+  是「意圖」/ semantic state? ─────────────────→ L2 Semantic(必經 L1 alias)
+  跨 component(Button/Input/Field 等都吃)? ──→ L3 Family
+  全 app 結構(AppShell / Header / Sidebar)? ─→ L4 Layout
+  單 component 內部? ─────────────────────────→ 不開 token,hardcode in tsx
+```
+
+---
+
+## Naming Convention(family-scoped,3 條硬規則)
+
+### 規則 1:`--<family>-<measurement>[-<size>]` 嚴格 family-scoped
+
+每個 token name 一定先帶 family prefix,讓 grep 即知「這 token 屬哪 family / 哪 layer」:
+
+| Family prefix | Layer | 範例 |
+|---|---|---|
+| `--color-*` | L1 Primitive | `--color-blue-6` / `--color-neutral-9-opaque` |
+| `--brand` / `--primary` / `--error` / `--info` / `--success` / `--warning` | L2 Semantic(色 family,history 沒寫 `--color-` 前綴是 Atlassian 流派 idiom) | `--primary-hover` / `--error-subtle` |
+| `--canvas` / `--surface*` / `--foreground` / `--fg-*` | L2 Semantic(shadcn idiom 沿用——surface tone family + fg state family 各自獨立) | `--canvas` / `--surface-raised` / `--fg-disabled` |
+| `--bg-*` | L2 Semantic(state pair family,跟 `--fg-*` 配對) | `--bg-disabled`(配 `--fg-disabled`) |
+| `--neutral-hover` / `--neutral-selected*` | L2 Semantic(neutral interaction family) | `--neutral-selected-hover` |
+| `--<hue>-hover` / `--<hue>-active` | L2 Semantic(色相互動 family) | `--blue-hover` / `--red-active` |
+| `--font-<role>-<measurement>` | L3 Family | `--font-h1-size` / `--font-body-size` |
+| `--field-height-<size>` / `--table-row-<size>` / `--tab-height-<size>` / `--tree-indent-<size>` | L3 Family | `--field-height-md` |
+| `--<part>-width` / `--<part>-height` / `--<part>-<measurement>` | L4 Layout | `--sidebar-width` / `--chrome-header-height` |
+| `--layout-space-<role>` | L4 Layout | `--layout-space-loose` / `--layout-space-tight` |
+| `--radius-<size>` | L3 Family(structural) | `--radius-md` |
+| `--elevation-<step>[-hover]` | L1 Primitive(住 primitives.css 跟色一起,理由見下) | `--elevation-100` / `--elevation-200-hover` |
+| `--opacity-<role>` | L1 Primitive(structural,單一值) | `--opacity-disabled` |
+| `--<part>-<measurement>-<size>` | L4 Layout(panel widths 等)| `--data-table-sort-panel-width` |
+
+### 規則 2:`--<size>` suffix 跟 family 共用 size vocabulary
+
+所有 size suffix 統一 `xs / sm / md / lg`(elevation 例外用 `100 / 200` Material idiom,因 elevation 不跟 density 走)。**禁** 自創 `tiny` / `small` / `regular` / `large` 等同義詞。
+
+### 規則 3:Tailwind utility bridge 命名同步
+
+每個 token 若提供 utility(`text-h1` / `bg-primary` / `h-field-md`)必經 `@theme inline` 或 `@utility`,utility 名 = token name 去 `--` 前綴 + 必要的 utility prefix(`bg-` / `text-` / `h-`)。**禁** 在 bridge 中改名(`--font-body-size` 不可橋成 `text-paragraph`)。
+
+---
+
+## Token vs Hardcode 判斷
+
+**標準:同值在 ≥ 2 處需要保持同步 → 必開 token。** 1 處 = hardcode + 註解 why(若非常識值);2+ 處 = token。
+
+### Token 化必過 3 題
+
+1. **這值會在 ≥ 2 處同步出現嗎?**(2 處不一定要 sync 也不算——須有「同步義務」,例如「Button 跟 Input 必同高」)
+2. **找得到既有 family 可鏡射嗎?**(命中 → 用既有 family 加 size variant;沒命中 → 走規則 1 命名,別自創孤立 family)
+3. **改值時所有 consumer 都該跟著變嗎?**(YES → token;NO → hardcode 因為各 consumer 各自意圖)
+
+任一 NO → hardcode in code + 註解 why。
+
+### Hardcode 合法情境
+
+- 單一 consumer 的 padding / gap / size(eg. Tooltip arrow `4px`)
+- 跟設計上下文耦合的值(eg. 圖表 axis tick gap)
+- 數學 / 物理常數(eg. `Math.PI`,動畫 `easing` 公式參數)
+
+**禁止以「省工」「之後再開」「先寫死試試」為由拒絕開 token。**(違 mindset #1)
+
+### Hardcode 必註解(若不是視覺常識值)
+
+```tsx
+// hardcode 24px:Tooltip arrow geometry,只此一處 consumer + 跟 Radix arrow lib 物理綁定
+<TooltipArrow width={24} />
+```
+
+---
+
+## 跨 family co-location 規則(2026-05-26 codify)
+
+某些 token 雖然名前綴看似屬一 family,但實際 co-located 在另一 family 檔案——**有意的依賴關係,不是命名 drift**:
+
+### Co-location 1:`--elevation-*` 住 `color/primitives.css`
+
+**Why**:elevation 跟 color 共用 light/dark mode 切換 trigger(`[data-theme="dark"]`)。把 elevation 跟 color primitives 放同一個 `[data-theme="dark"]` block,**改 mode 設定一處全聯動**;若拆出去 `elevation/elevation.css` 各有 dark override block → 兩處 mode trigger,容易「改 a 壞 b」。
+
+**對齊**:Material 3 `md-sys-elevation` 直接定義在 `theme` 範圍內(跟 color theme 同 root);Atlassian DS 「shadow + color in same theme primitive layer」;Polaris `--p-shadow-*` 與 `--p-color-*` 同住 theme css。
+
+**拆分例外條件**:若未來 elevation 需要獨立 dark mode trigger(eg. high-contrast mode 不變色但加重 shadow)→ 才拆。目前無此需求。
+
+### Co-location 2:`--canvas` / `--surface` 跟 `--bg-<state>` 是 **2 個 family**(不是 drift)
+
+| Family | 命名前綴 | 用途 | Sourced from |
+|---|---|---|---|
+| **Surface tone family** | `--canvas` / `--surface` / `--surface-raised` / `--surface-strong` / `--overlay` / `--tooltip` | 容器層級的**底色 tone**——不同 layer 不同視覺深度 | shadcn idiom(`--background` family),DS 沿用避免破壞 shadcn compat 命名 |
+| **State pair family** | `--bg-<state>` 配 `--fg-<state>` | 互動元件 disabled / hover / active **state 底色**——跟前景文字 state 成對 | DS 自家 idiom,確保 bg + fg 一定一對一 sync(`--bg-disabled` 配 `--fg-disabled`) |
+
+**Why 2 個 family**:Surface tone 是「容器深度」概念,跟 state 無關;State pair 是「元件當下互動 state」概念,跟容器深度無關。**強行統一**(eg. 命名全部 `--bg-canvas` / `--bg-disabled`)→ 失去語義邊界,consumer 寫 code 時不知該選哪個。
+
+**對齊**:Polaris `--p-color-bg`(tone family)vs `--p-color-bg-disabled`(state pair);Material 3 `md-sys-color-surface*`(tone)vs `md-sys-color-on-disabled`(state);Atlassian `color.background.neutral`(tone)vs `color.background.disabled`(state)— 三家世界級全部 2 family 拆,我們對齊。
+
+### Co-location 3:`--layout-space-*`(layoutSpace/)vs `--sidebar-*` / `--chrome-header-*` / `--*-panel-width`(uiSize/)
+
+**Layer 同為 L4 Layout**,但兩個 family 拆兩個檔案(`layoutSpace/` vs `uiSize/`):
+
+| Family | 檔案 | 用途 |
+|---|---|---|
+| `--layout-space-*` | `layoutSpace.css` | **抽象** spacing rhythm(loose / tight / bottom)——多 consumer 共用 |
+| `--item-gap-label-desc-*` | `layoutSpace.css`(co-located) | item 級 label ↔ desc micro gap——概念 owner = `item-anatomy.spec.md`,住 layoutSpace.css 因同屬 spacing token 家族(見 layoutSpace.spec.md「Co-located:item-gap tokens」) |
+| `--sidebar-*` / `--chrome-header-*` / `--data-table-*-width` | `uiSize.css` | **具體** layout primitive 尺寸——對應特定 layout primitive 元件 |
+
+**Why 拆**:抽象 spacing rhythm 改值 → 整 app rhythm 動;具體 primitive 尺寸改值 → 單個 primitive 動。兩個影響半徑不同,拆檔案讓 grep / blame 直接看出。
+
+### Co-location 4:`--opacity-disabled` 是 L1 Primitive 不是 L2 Semantic
+
+雖然名含「disabled」看似 semantic,但實際是**單一 structural value**(0.45)沒 mode swap、沒 hover/active variant——當 L1 Primitive 處理。`@utility opacity-disabled` 直接 expose 給 consumer。
+
+**對齊**:Atlassian Pragmatic guideline opacity scale 也住 primitive layer。
+
+---
+
+## Internal vs Public token(consumer scope)
+
+| Layer | Scope | Consumer who reads token? |
+|---|---|---|
+| **L1 Primitive** | Internal | Tag / Avatar(per color.spec.md 混合存取流派);其他禁直接 `--color-blue-6` |
+| **L2 Semantic** | **Public** | 所有 consumer(app / explorations / patterns)直接 `bg-primary` / `text-foreground` |
+| **L3 Family**(`--field-height-*` 等) | Internal | DS 內部 primitive(Button / Input / DataTable)消費;**consumer 必走 component prop**(`<Button size="sm">`)不直接 raw token |
+| **L4 Layout**(`--sidebar-width` / `--layout-space-*`) | **Public** | Layout primitive 元件(AppShell / Sidebar / ChromeHeader)+ consumer 寫自家 layout 直接消費 |
+| **L5 Internal** | Internal | 單 component 內部(目前 0 個) |
+
+**Stories 義務**:
+- Public token → **必補 Storybook stories**(色票 / 字級 / 間距對照展示)
+- Internal token → spec.md codify family 即可,**免 stories**(consumer 不直接看)
+
+`tokens/README.md`「Public vs Internal token」表 cross-reference 本段。
+
+---
+
+## 跨 family `@theme inline` bridge(Tailwind v4 spec)
+
+Tailwind v4 `@theme inline` 把 CSS variable 升級成 utility class。每 family CSS 檔末段必有 `@theme inline` block 橋接 token → utility:
+
+```css
+@theme inline {
+  --spacing-field-md: var(--field-height-md);   /* `h-field-md` utility */
+  --color-primary:    var(--primary);            /* `bg-primary` utility */
+}
+```
+
+**禁** 在 bridge 中改 token 值或重新命名(`--spacing-field-md = 32px` 直接 hardcode = drift);**必** 用 `var()` 引用既有 L1/L2 token。
+
+---
+
+## SSOT auto-sync 義務(2026-05-23 user 永久 directive)
+
+新增 / 改 / 廢 token 時:
+1. **Spec.md** codify rationale(本 spec 上游 + family spec.md 下游)
+2. **CSS file** 寫定義
+3. **Tailwind bridge** `@theme inline` / `@utility` 補完
+4. **Consumer 改寫**:若 rename / retire → grep DS-wide consumer 一次改完(M10 proactive scan)
+5. **Hook / audit** 對齊(若新 family invariant → 補 hook;若新 dim → 補 audit skill)
+6. **Stories**(if Public token)
+
+**禁** 留「下個 session 補 stories」「之後再 grep consumer」(M33 retired but principle absorbed by M20 sub-rule)。
+
+---
+
+## 世界級對照 citation
+
+| 概念 | 對應世界級 DS | source |
+|---|---|---|
+| 分層 token 架構 | Material 3 reference / system / component | <https://m3.material.io/foundations/design-tokens/overview> |
+| Primitive + Semantic 2-layer | Polaris `--p-color-*` | <https://polaris.shopify.com/tokens/colors> |
+| Semantic state token(hover / active / disabled) | Atlassian DS foundations | <https://atlassian.design/foundations/color-new> |
+| Family scoped naming(`--<family>-<size>`) | Carbon `$button-primary-active` | <https://carbondesignsystem.com/elements/color/tokens/> |
+| Adaptive token(light/dark co-location) | Apple HIG `UIColor.systemBlue` adaptive | <https://developer.apple.com/design/human-interface-guidelines/color> |
+| Surface tone vs state pair 2 family | Polaris `--p-color-bg` vs `--p-color-bg-disabled` | <https://polaris.shopify.com/tokens/colors> |
+| Elevation 跟 theme co-location | Material 3 `md-sys-elevation` in theme | <https://m3.material.io/styles/elevation/tokens> |
+
+---
+
+## 反 pattern(禁)
+
+| 禁 | 原因 |
+|---|---|
+| 自創新命名 family 不過 family-scoped 規則 | 1 個 token 屬 N 個 family = consumer 認知衝突 |
+| 1 處 hardcode 立即開 token | <2 處同步 = token 過度抽象,Linear/Polaris 都警告 token bloat |
+| 為 1 consumer 開 L3 Family token | Family 抽象服務 cross-component,1 consumer 該 hardcode in tsx |
+| 拆 elevation 出 primitives.css 另做 dark override | 兩處 mode trigger,「改 a 壞 b」(M10 違反) |
+| L2 Semantic 直接 raw oklch 不 alias L1 | 跳層 = 失去 primitive scale benefit + 改值要動兩處 |
+| L4 Layout token 不 publish 到 npm tokens aggregator | Consumer install DS 拿不到 → 跑版(2026-05-26 AppShell 事件 root cause) |
+| Internal token(`--field-height-*`)出現在 consumer code | 該走 component prop 不直接 raw token |
+
+---
+
+## 相關
+
+- `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
+
+---

package/src/tokens/typography/typography.css

@@ -113,6 +113,6 @@
 
 /* ── Letter-spacing semantic utility(對齊 single semantic value per role 哲學)──
    `tracking-shortcut`:鍵盤快捷鍵 hint(Command / DropdownMenuShortcut 等)。
-   禁 raw `tracking-(tight|wide|wider|widest|tighter)` per typography.spec.md L91-105
+   禁 raw `tracking-(tight|wide|wider|widest|tighter)` per typography.spec.md「禁止事項 + Letter-spacing」段(L118-156)
    + utility-registry.json block list。新增 role 需新 token + 新 @utility。 */
 @utility tracking-shortcut { letter-spacing: var(--tracking-shortcut); }

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

@@ -40,8 +40,9 @@ Typography 由三個獨立維度組成，分開疊加：
 | `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 區分，使用端需有意識地處理。
+> **10px a11y 用途限制**（2026-07-17）：`text-footnote` 僅限**非必要的附帶資訊**（法律細字、來源標注、storybook 註解）——目前全庫零正式元件消費，只用於 stories `<p>` 註解。**使用者需理解才能操作的資訊禁止只靠 10px**；任何 ≤12px 用途上線前須驗 200% 放大（WCAG 1.4.4）不裁切。視覺標題 ≠ 語義標題（一律用 `h1–h6`，WCAG 1.3.1）。
+
+**h5（16px）vs body-lg（16px）/ h6（14px）vs body（14px）**：同尺寸配對的統一判別法——line-height 區分角色（標題 1.3 / 段落 1.5），使用端再疊 font-weight / color 強化標題層級，需有意識地選擇（詳「同尺寸但不同角色的選法」）。
 
 
 ## line-height 覆蓋（僅 14/16px body 可覆蓋）
@@ -61,9 +62,11 @@ Typography 由三個獨立維度組成，分開疊加：
 <span className="text-body leading-compact">已儲存</span>
 ```
 
+單行保證由容器自身承擔（Button / SegmentedControl item 等套 `whitespace-nowrap`）——`leading-compact` 不處理 2 行以上的 label；多行截斷是 `line-clamp-*` + 預設行高的職責（見下方反 pattern）。
+
 可用的 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）
+- `leading-normal`：1.5（Tailwind 內建，**極少用**——僅 stories `<p>` 補 10px footnote 段落呼吸感，正式 DS 元件**不需**主動覆蓋成 1.5，因為 `text-body` / `text-body-lg` 預設就是 1.5）
 
 ### 反 pattern（禁用）
 
@@ -171,23 +174,23 @@ Typography 由三個獨立維度組成，分開疊加：
 
 四個關鍵決策,各自有世界級先例支撐:
 
-**(1) Body base = 14px(對齊 Material / Carbon / Ant 三家共識)**
+**(1) Body base = 14px(對齊 Material / Carbon / Ant 三家共識)** <!-- @benchmark-unverified -->
 
 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」哲學**
+**(2) 二元 line-height(1.5 / 1.3)— 對齊 Carbon「productive vs supplementary」哲學** <!-- @benchmark-unverified -->
 
 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**
+**(3) h5/h6 與 body-lg/body 同 size(16/14)— 靠 lh + weight 區分,不開新 size tier** <!-- @benchmark-unverified -->
 
 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 明寫「使用端需有意識地處理」。
+本 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」,但對應「同尺寸但不同角色的選法」判別法明寫「需有意識地選擇」。
 
-**(4) Font weight 3 階(400/500/700)— 對齊 Carbon / Polaris 共識**
+**(4) Font weight 3 階(400/500/700)— 對齊 Carbon / Polaris 共識** <!-- @benchmark-unverified -->
 
 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 場景,接受。
 
@@ -200,3 +203,4 @@ Tailwind / Apple SF 的 9 階 weight scale 涵蓋 marketing / 印刷需求,但 p
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `empty.spec.md`
+- `token-system.spec.md`

package/src/tokens/typography/typography.stories.tsx

@@ -0,0 +1,134 @@
+import type { Meta, StoryObj } from '@storybook/react'
+
+const meta: Meta = {
+  title: 'Design System/Tokens/Typography',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: `
+字體 token 系統。token 只定義 \`font-size\` 與 \`line-height\`，\`font-weight\` 由使用端疊加。
+
+完整規則：\`packages/design-system/src/tokens/typography/typography.spec.md\`
+        `,
+      },
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj
+
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function TypeRow({ utility, meta, sample }: { utility: string; meta: string; sample: string }) {
+  return (
+    <div className="grid items-baseline gap-x-6 gap-y-1 border-b border-border py-4 last:border-0"
+      style={{ gridTemplateColumns: '180px 1fr' }}>
+      <div>
+        <code className="block text-caption font-medium text-fg-secondary">{utility}</code>
+        <span className="text-caption text-fg-muted">{meta}</span>
+      </div>
+      <div className={utility}>{sample}</div>
+    </div>
+  )
+}
+
+
+// ── Stories ──────────────────────────────────────────────────────────────────
+
+export const TypeScale: Story = {
+  name: '字型尺寸',
+  parameters: {
+    docs: {
+      description: {
+        story: '所有 typography role 的視覺對照。font-weight 預設 400，line-height 已烤進各 token。',
+      },
+    },
+  },
+  render: () => (
+    <div className="max-w-2xl">
+      <TypeRow utility="text-h1"       meta="48px · lh 1.3" sample="頁面主標題 Page Title" />
+      <TypeRow utility="text-h2"       meta="32px · lh 1.3" sample="區塊標題 Section Heading" />
+      <TypeRow utility="text-h3"       meta="24px · lh 1.3" sample="子區塊標題 Subsection" />
+      <TypeRow utility="text-h4"       meta="20px · lh 1.3" sample="小節標題 Group Title" />
+      <TypeRow utility="text-h5"       meta="16px · lh 1.3" sample="元件層級標題 Component Heading" />
+      <TypeRow utility="text-h6"       meta="14px · lh 1.3" sample="最小層級標題 Inline Label" />
+      <TypeRow utility="text-body-lg"  meta="16px · lh 1.5" sample="16px 版面的段落內文。充足的行距讓視線流暢移動，適合較寬鬆的閱讀情境。" />
+      <TypeRow utility="text-body"     meta="14px · lh 1.5" sample="主要內文基準。產品中絕大多數的說明文字、列表內容、表單說明都使用這個尺寸。" />
+      <TypeRow utility="text-caption"  meta="12px · lh 1.3" sample="圖表附註、helper text、標籤文字" />
+      <TypeRow utility="text-footnote" meta="10px · lh 1.3" sample="法律文字、來源標注（極少用）" />
+    </div>
+  ),
+}
+
+
+export const FontWeight: Story = {
+  name: '字重',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'font-weight 不寫死在 token，由使用端疊加。' +
+          '`font-medium`（500）對應中等強調，`font-bold`（700）對應 `<strong>`。',
+      },
+    },
+  },
+  render: () => (
+    <div className="max-w-lg space-y-1">
+      {[
+        { label: '（預設）font-normal', cls: 'font-normal', weight: '400' },
+        { label: 'font-medium',         cls: 'font-medium', weight: '500' },
+        { label: 'font-bold',           cls: 'font-bold',   weight: '700' },
+      ].map(({ label, cls, weight }) => (
+        <div key={weight} className="flex items-baseline gap-6 border-b border-border py-3 last:border-0">
+          <div className="w-44 shrink-0">
+            <code className="text-caption font-medium text-fg-secondary">{label}</code>
+            <span className="ml-2 text-caption text-fg-muted">{weight}</span>
+          </div>
+          <p className={`text-body ${cls}`}>
+            此操作將永久刪除該筆資料，請確認後再繼續。
+          </p>
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+
+export const LineHeight: Story = {
+  name: '行高',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '`text-body` / `text-body-lg`（14/16px）唯二可覆蓋行高的 token，預設 1.5（閱讀段落），' +
+          '可 `leading-compact` 覆蓋為 1.3 — 唯一合理情境是「單行固定高度容器」' +
+          '（Button / Tabs trigger / Chip / Notice / MenuItem 等），避免 1lh > chrome height 造成垂直偏移。' +
+          'h1-h6 / caption / footnote 全 lh 1.3 固定不可覆蓋。',
+      },
+    },
+  },
+  render: () => (
+    <div className="grid max-w-2xl grid-cols-2 gap-6">
+      <div>
+        <code className="mb-2 block text-caption font-medium text-fg-secondary">
+          text-body · leading-normal (1.5)
+        </code>
+        <p className="text-body leading-normal rounded-md bg-neutral-hover p-4">
+          適合連續閱讀的段落內文。充足的行距讓眼睛在換行時容易找到下一行的起點，降低閱讀疲勞。
+        </p>
+      </div>
+      <div>
+        <code className="mb-2 block text-caption font-medium text-fg-secondary">
+          text-body · leading-compact (1.3)
+        </code>
+        <p className="text-body leading-compact rounded-md bg-neutral-hover p-4">
+          適合單行固定高度容器內文字（Button / Tabs trigger / Chip / Notice / MenuItem 等），避免 1lh 大於容器高度造成垂直偏移。
+        </p>
+      </div>
+    </div>
+  ),
+}

package/src/tokens/uiSize/icon-size.ts

@@ -17,7 +17,7 @@
  * `field-height-xs / sm / md` → icon **16px**
  * `field-height-lg`           → icon **20px**
  *
- * 詳 spec L132+ Icon Size Tier 段(stroke 下限 12px / Tag-Field 配對 / etc.)
+ * 詳 uiSize.spec.md「Icon 尺寸 Tier」段(段名指法免行號漂移;stroke 下限 12px / Tag-Field 配對 / etc.)
  *
  * ── Consumer 用法 ──
  * ```tsx
@@ -26,15 +26,14 @@
  * // sm/md → 16, lg → 20
  * <LucideIcon size={ICON_SIZE[size]} />
  *
- * // form control xs(field-height-xs 24)用 ICON_SIZE.sm(同 16,per spec L132 Tier)
+ * // form control xs(field-height-xs 24)用 ICON_SIZE.sm(同 16,per uiSize.spec.md「Icon 尺寸 Tier」段)
  * <LucideIcon size={size === 'xs' ? ICON_SIZE.sm : ICON_SIZE[size]} />
  * ```
  *
  * ── 防漂移 ──
  * 1. uiSize.spec.md「Icon Size Tier」段 codify 16/16/16/20 tier(text-based canonical)
  * 2. 本 const 程式化 SSOT(type-safe Record<RowSize, number>)
- * 3. Hook `check_icon_size_literal.sh`(write-time regex 攔非標準 literal)
- * 4. Audit Dim「Icon size literal compliance」DS-wide audit-time scan
+ * 3. Audit Dim「Icon size literal compliance」DS-wide audit-time scan(write-time hook 尚未實作 — 改靠 audit-time + mindset)
  *
  * ── Carve-out(不適用本 SSOT)──
  * - `rating.spec.md` Rating star 20/24/24(identity scale,cite Ant/Material/Airbnb)