@qijenchen/design-system 0.1.0-beta.3 → 0.1.0-beta.32

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/token-system.spec.md

@@ -0,0 +1,243 @@
+<!-- @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 CLAUDE.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 共用 |
+| `--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 |
+
+---
+
+## 被引用(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)