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

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`

package/src/tokens/uiSize/uiSize.css

@@ -49,6 +49,19 @@
      不寫成 calc() 公式因為 lg 無法完美遵守(54 → 56 為了 8px grid 取整),hardcode 比假公式誠實。 */
   --chrome-header-height: 3rem; /* 48px */
 
+  /* Sidebar / Layout primitive sizing(2026-05-26 ship 進 published per consumer SSOT gap):
+     原本 declared in DS repo `src/globals.css`,沒進 npm-published tokens aggregator
+     → consumer install DS + import `@qijenchen/design-system/styles/tokens` 拿不到
+     → AppShell + Sidebar gap div 用 `var(--sidebar-width)` undefined → 解析 0px → flex 跑版
+     對齊 docs:`components/Sidebar/sidebar.spec.md` L613-614 token table
+     Why uiSize.css:layout primitive widths 是 ui sizing semantic 範疇(對齊 --field-height / --chrome-header)
+     */
+  --sidebar-width: 15rem;          /* 240px expanded sidebar */
+  --sidebar-width-min: 240px;      /* 最小寬,同時是 AppShell Aside floor(ASIDE_WIDTH_MIN) */
+  --sidebar-width-mobile: 18rem;   /* 288px mobile sheet 抽屜 */
+  --sidebar-menu-icon-size: 1rem;   /* 16px sm/md row(per ICON_SIZE.sm/md);size=lg 罕見 case 下方 override 1.25rem(20px) */
+  --sidebar-width-icon: calc(2 * var(--layout-space-loose, 1rem) + var(--sidebar-menu-icon-size));
+
   /* Tree Indent — TreeView + DataTable nested rows(SSOT,2026-05-04)
      公式:chevronSize + gap-2 = 16+8(sm/md)/ 20+8(lg)
      Consumer:TreeView depth indent / DataTable nested row depth indent */
@@ -67,6 +80,9 @@
 
 [data-ui-size="lg"],
 [data-density="lg"] {
+  /* Sidebar lg override(per src/globals.css 原 declaration:size=lg 罕見 case)*/
+  --sidebar-menu-icon-size: 1.25rem; /* 20px(lg)*/
+
   --field-height-sm: 2rem;      /* 32px */
   --field-height-md: 2.25rem;   /* 36px */
   --field-height-lg: 2.5rem;    /* 40px */

package/src/tokens/uiSize/uiSize.spec.md

@@ -0,0 +1,428 @@
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# UiSize 設計原則
+
+> **Foundational SSOT rationale**(cap 800,2026-04-25 approved):
+> 尺寸 token SSOT。定義 field-height family `md` default / chrome-header 選型 decision tree(fixed-h vs padding-based + 8 家對照)/ icon-only `calc` 公式。Button / Input / Select / Checkbox / Slider / Tabs 等皆消費,scope 本質 > 單一 token 檔。
+
+元件高度的語義 token，rem 單位。透過 `data-density`（或 `data-ui-size`）切換。
+
+## Field Height
+
+Button、Input、Checkbox/Radio SelectionItem 等互動元件。
+
+| Token | md density | lg density |
+|-------|-----------|-----------|
+| `--field-height-xs` | 1.5rem (24px) | 1.5rem (24px) — 固定 |
+| `--field-height-sm` | 1.75rem (28px) | 2rem (32px) |
+| `--field-height-md` | 2rem (32px) | 2.25rem (36px) |
+| `--field-height-lg` | 2.25rem (36px) | 2.5rem (40px) |
+
+### Field-height family 清單與共享 default（SSOT）
+
+**消費 `--field-height-*` token 的元件組成「field-height family」。這個 family 必須共享同一個 default size = `md`——違反即設計 bug。**
+
+#### Family 成員
+
+| 元件 | size prop | Default | 預設 token |
+|------|-----------|---------|-----------|
+| `Button` | xs / sm / md / lg | **`md`** | `--field-height-md` |
+| `Input` | sm / md / lg | **`md`** | `--field-height-md` |
+| `NumberInput` | sm / md / lg | **`md`** | `--field-height-md` |
+| `DatePicker` | sm / md / lg | **`md`** | `--field-height-md` |
+| `Select` | sm / md / lg | **`md`** | `--field-height-md` |
+| `Combobox` | sm / md / lg | **`md`** | `--field-height-md` |
+| `LinkInput` | sm / md / lg | **`md`** | `--field-height-md` |
+| `Textarea` | sm / md / lg | **`md`** | `--field-height-md` |
+| `Switch` | sm / md / lg | **`md`** | `--field-height-md` |
+| `Slider` | sm / md / lg | **`md`** | `--field-height-md`（只控容器外高，thumb/track 不變） |
+| `SegmentedControl` | xs / sm / md / lg | **`md`** | `--field-height-md` |
+| `Checkbox` | sm / md / lg | **`md`** | `--field-height-md`（控件 16/20px 對應） |
+| `RadioGroup` | sm / md / lg | **`md`** | `--field-height-md`（控件 16/20px 對應） |
+| `Rating` | sm / md / lg | **`md`** | `--field-height-md`(container 對齊,icon 走 icon tier 16/16/20) |
+| `TimePicker` | sm / md / lg | **`md`** | `--field-height-md`(Ant-style 時間選擇,對齊 DatePicker 家族) |
+| `Tag` | sm / md / lg | **`md`** | 自帶尺寸，透過 Field size 配對 |
+
+#### 單一尺寸消費者（不在 default-md 規則內）
+
+| 元件 | 固定 size | 理由 |
+|------|----------|------|
+| `Chip` | 固定 `h-field-sm`（28/32px） | Material 3 / Atlassian / Polaris 共識：filter chips 使用單一高度。不暴露 size prop |
+
+#### 偏離 field-height family 的 rationale 格式(canonical)
+
+任何元件的 size prop **偏離 field-height 對齊**(例:Checkbox 控件 sm/md 都是 16px、Rating 控件非 field-height、Switch 的 thumb 不跟 field-height 成比例等)或 **偏離 default md**(例:Chip 固定 sm),**必須在自己 spec.md 的「尺寸」章節下寫一個子標題固定格式**:
+
+```markdown
+### 為什麼不完全對齊 `--field-height-*`(或:為什麼不 default md)
+
+- **現況**:{sm/md/lg 實際數值或 token,e.g. sm=16px / md=16px / lg=20px(Checkbox)}
+- **Rationale**:{一句話說明偏離理由,指向世界級或 token spec 或 UX 約束}
+- **世界級對照**:{Polaris / Material / Ant / Atlassian 等中至少一個同樣這樣做的 DS}
+```
+
+**必須同時滿足**:
+1. 子標題必含「為什麼」三字(而非被動「尺寸不同」這類寫法),這樣 audit 可以 mechanical grep 「`### 為什麼不完全對齊`」或「`### 為什麼不 default md`」
+2. 三個欄位(現況 / Rationale / 世界級對照)**都要填**,缺一不可——特別是「世界級對照」不能省,mindset #1 要求對標
+3. 位置:必須在 spec 的「尺寸」主章節之下(不是埋在「何時不用」或「禁止事項」等其他章節)
+
+**現有已遵循此格式的元件**:Chip(本檔上表已寫,Material 3 / Atlassian / Polaris 共識)/ Checkbox / RadioGroup / Switch / Slider / Textarea / Rating(2026-04-21 批次補齊,五欄格式統一)
+**需補齊 rationale 段的元件**:(無 — Phase 2 已全部補齊)。未來新增偏離 field-height 的元件 → 必須按本格式寫,`/design-system-audit` 會 enforce。
+
+**audit hook 未來擴展**:若 cva `defaultVariants.size` 不是 `md`,或 `size` variants 的數值不命中 `--field-height-*`,hook 可要求 spec.md 必有符合格式的 rationale 段,否則 block merge(列為 post-Phase-2 可考慮加上的 mechanical gate)。
+
+#### 為什麼必須共享 default
+
+Consumer 寫 Form 或 Toolbar 時並排多個 field-height 元件：
+
+```tsx
+<Button>送出</Button>
+<Input />
+<Select options={...} />
+<SegmentedControl>...</SegmentedControl>
+```
+
+**所有元件不傳 size 時就自動對齊**——這是 consumer 的核心體驗。若 SegmentedControl 預設 sm 而 Button 預設 md，consumer 放著不管就會高度不一致，每個 consumer 都要記得手動傳 size，破壞「默認對齊」的承諾。
+
+#### 硬規則
+
+- **新增 field-height 消費者** → 必須 default `md`
+- **修改既有 `defaultVariants.size`** → 必須同步更新本表 + 元件 spec.md + tsx docblock + anatomy story 的 default 標記
+- **`defaultVariants.size` 跟 spec 聲稱不一致 = 設計 bug**，優先修 code 或 spec 使其對齊本表
+
+#### 歷史錯誤
+
+本專案曾發生 SegmentedControl 的 code defaults 是 `md`、spec + docblock 寫 `sm ★default` 的三方不一致（2026-04-18 修正）。避免方式：改 cva `defaultVariants` 前先讀本表，確認新值仍符合 family 約束。
+
+## Table Row
+
+DataTable 行高。density 切換統一 +0.5rem (+8px)。
+
+| Token | md density | lg density |
+|-------|-----------|-----------|
+| `--table-row-sm` | 2rem (32px) | 2.5rem (40px) |
+| `--table-row-md` | 2.5rem (40px) | 3rem (48px) |
+| `--table-row-lg` | 3rem (48px) | 3.5rem (56px) |
+
+---
+
+## 元件尺寸對應系統
+
+**`field-height-lg` 是尺寸切換點。** xs/sm/md 用同一組內部尺寸，lg 切換到較大的一組。
+
+| | xs / sm / md | **lg** |
+|---|---|---|
+| **Field 高度** | 24 / 28 / 32px | **36px** |
+| **Icon 尺寸** | 16px | **20px** |
+| **Checkbox / Radio** | sm/md (16px) | **lg (20px)** |
+| **字體** | text-body (14px) | **text-body-lg (16px)** |
+
+### 子元件補齊原則
+
+當子元件被父元件透過 size prop 消費時，子元件必須補齊父元件的所有 size 選項，即使值重複。消費端直接透傳 size，不做 mapping。
+
+已套用此原則的元件：Checkbox（sm=md=16px）、Radio（sm=md=16px）、Tag（lg=md=24px）。
+
+### 元件高度地板
+
+**field-height-xs（24px）是獨立互動元件的最小高度。** 任何可獨立存在的互動元件（Button、Input 等）不得使用比 field-height-xs 更小的高度。若空間不足以容納 24px，應重新檢視容器佈局，而非縮小元件。
+
+比 24px 更小的互動區域只存在於元件內部的 Inline Action（如 Tag dismiss、Field endAction），由宿主元件的 spec 定義規格。
+
+### Icon 尺寸 Tier
+
+系統有兩個 icon tier，由元件引用的 field-height token 決定：
+
+| 元件引用 | Icon | 控件（Checkbox/Radio） | 字體 |
+|---|---|---|---|
+| `field-height-xs / sm / md` | 16px | 16px（內部 icon 12px） | text-body |
+| `field-height-lg` | 20px | 20px（內部 icon 16px） | text-body-lg |
+
+這是離散的兩組配對，不存在中間值，不需要公式推導。判斷依據是元件自身的 size prop 對應到哪個 field-height token，與全域 density 設定無關（density 只負責等比放大 field-height 的 px 值）。
+
+**Stroke icon 尺寸的下限是 12px**（出現在 Checkbox 等指示器容器內部）。Filled indicator（如 Radio 的實心圓點）不受此限制——實心形狀在任何尺寸都清晰可辨。
+
+### 跨 regime pointer index(2026-05-18 codify per user audit「確保 SSOT 不偏移」)
+
+本 Icon Size Tier 段是 DS-wide icon size SSOT 的**主索引**。下列 7 個 carve-out 是別律 owner:
+
+| Carve-out owner | File | Rule | Rationale cite |
+|---|---|---|---|
+| Rating star | `components/Rating/rating.spec.md:84` | Identity scale `{sm:20, md:24, lg:24}` 不走 icon tier | Ant 20 / Material 24 / Airbnb 24 |
+| Avatar 內 icon | `components/Avatar/avatar.spec.md:165` | `round_even(size × 0.6)` formula | Material / Apple HIG |
+| Empty illustration | `components/Empty/empty.tsx:48` | Avatar 48 wrap → icon 28(Avatar formula derived)| Empty-state canonical |
+| FileViewer thumb | `components/FileViewer/file-viewer.tsx:621` | thumb 64 → icon 20(file-type indicator hardcode 無公式)| Thumbnail UI 慣例 |
+| CircularProgress | `components/CircularProgress/circular-progress.tsx:87` | `strokeWidth = max(2, size/10)` stroke ring 厚度非 icon | Geometric scaling |
+| Steps indicator icon | `components/Steps/steps.tsx:24` | `INDICATOR_ICON_SIZE {sm:0, md:16, lg:20}`(sm 因圓圈 8px 太小)| Indicator-internal |
+| Checkbox/Switch check | `components/Checkbox/checkbox.tsx:49` + `components/Switch/switch.tsx:73` | `{sm:12, md:12, lg:16}` form-control internal + stroke 下限 12 | iOS HIG / Material 3 / Polaris |
+
+**程式化 SSOT**:`patterns/element-anatomy/item-anatomy.tsx:66` `ICON_SIZE = {sm:16, md:16, lg:20}` 是本 tier 的 type-safe const。**Form control 透過 `tokens/uiSize/icon-size.ts` re-export entry import**(避 components→patterns 反向 dependency)。
+
+**新加 carve-out 流程**:必同時(1)在 owner spec 內部宣告 + cite(2)補本表 row。Audit dim 30 cross-doc consistency 抓 drift。
+
+### Tag ↔ Field 配對
+
+Tag 有自己的尺寸定義（見 `tag.spec.md`），與 Field 的配對透過 size 直接對應：
+
+| Field size | Tag size | Tag 高度 | Tag padding (四邊等距) |
+|---|---|---|---|
+| sm | sm | 20px | (field-height-sm - 1.25rem) / 2 |
+| md | md | 24px | (field-height-md - 1.5rem) / 2 |
+| lg | lg | 24px | (field-height-lg - 1.5rem) / 2 |
+
+---
+
+## Tab Height
+
+Tabs 導覽容器的高度。獨立於 field-height 和 table-row——tabs 是 navigation container，需要比 form control 更大的呼吸感。數值目前與 table-row 對齊，但概念獨立，未來任何一方調整都不牽動另一方。
+
+| Token | md | lg | 消費者 |
+|-------|----|----|--------|
+| `--tab-height-sm` | 32px | 40px | Dialog / Sidebar 內的 dense tabs |
+| `--tab-height-md` | 40px | 48px | **預設**，頁面主要 tabs |
+| `--tab-height-lg` | 48px | 56px | Page-level hero tabs |
+
+Tailwind：`h-tab-sm` / `h-tab-md` / `h-tab-lg`。
+
+## Chrome Header Height
+
+應用程式 chrome 區域(Sidebar header、app top bar、主內容 page header)的高度。**定義在 DS package `packages/design-system/src/tokens/uiSize/uiSize.css`**(2026-05-23 per Phase A Decision 1 從 consumer-app `src/globals.css` 搬入,user verbatim「決策一照你建議」— 為了 npm-package install 後 consumer 不需自設 token,符 M17 SSOT 鐵律)。雖然它是**跨佈局層級**的 token(跨多元件而非單一 component scope),DS package 自包避免 consumer 漏設造成 header 高度崩潰。
+
+**Cross-family canonical SSOT pointer**:chrome + overlay 兩 header 家族的完整視覺契約(border / padding / withTabs lockstep / size 對應 / Token equality enforcement)詳 `patterns/header-canonical/header-canonical.spec.md`。本節僅 codify token 本身定義 + consumer 清單。
+
+| Token | md | lg | 消費者 |
+|-------|----|----|--------|
+| `--chrome-header-height` | 48px | 56px | Sidebar header/footer、主內容 page header、app top bar、`--sidebar-width-icon`、**Overlay family chrome**(Dialog / Sheet / Popover / Coachmark header + footer,透過 `patterns/overlay-surface` 的 SurfaceHeader / SurfaceFooter `min-h-[var(--chrome-header-height)]`)、**Chrome family ChromeHeader primitive**(`patterns/header-canonical/chrome-header.tsx`,Sidebar / FileViewer Toolbar+InfoPanel 消費)|
+
+### Canonical 意圖(AR47,2026-04-21)
+
+**任何跨整個 app 的 chrome 區域(Sidebar header/footer、全域 top bar、主內容 page header)都用同一個 token,不自訂高度**。
+
+| ❌ 反例 | ✓ canonical |
+|---------|-------------|
+| `<header className="h-16">`(64px 硬寫) | `<header className="h-[var(--chrome-header-height)]">` |
+| Sidebar 48、top bar 56、page header 64(跨元件不一致) | 全部 `--chrome-header-height`(md=48 / lg=56),density 自動聯動 |
+
+### 為什麼 48 跟 56 是「同一個 token 不同密度」不是不一致
+
+**讀者常見誤解**:「Sidebar header 48px 但 XXX 56px → 沒共用?」
+**正解**:48 / 56 都是**同一個 `--chrome-header-height` token**,只是 **density mode 不同**:
+- 在 `<html data-density="md">`(預設)下 token resolve 到 48px
+- 在 `<html data-density="lg">` 下 token resolve 到 56px
+- 切換 density 時**整個 app 所有 chrome 高度同步變化**,不會有「Sidebar 48 但 top bar 56」的狀況
+- 若同時看到 48 與 56,**兩個消費者必須在不同 density context 下渲染**(例如 app 主區 md、某個工具區 lg) — 這是刻意的 density context 切換,不是 bug
+
+**驗證法**:在 DevTools 看兩個「似乎不一致」的 header,它們祖先 `html[data-density]` 值是否相同?
+- 相同 → 真有 bug,硬寫了數字繞過 token
+- 不同 → 其中一個元件在 density-override 情境,行為正確
+
+**為什麼 48 不 56 / 64**:
+- Material App Bar 56dp(mobile)/ 64dp(desktop);Airbnb 主站 header 80px;Shopify 64px
+- 本 DS 選 **48px @ md / 56px @ lg** 取「密集工具型產品」的下限(Linear / Figma / Notion 主 chrome 40-52px),給主內容區留更多 vertical space
+- 跟 Button-lg + Field-lg 高度(40 / 36)拉出視覺 hierarchy — chrome 高於任何 row control,但不壓迫內容
+
+### Chrome header 選型 canonical(2026-04-22 v5 整合,**DS-wide SSOT entry point**)
+
+**本節是 DS-wide chrome header 設計選型的入口**。任何新 chrome surface(modal / toolbar / sidebar / banner)的 header 實作都從這裡開始判斷。
+
+---
+
+#### Decision tree(必走)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Q: 這個 chrome header 的 title 有可能多行 /             │
+│    有 subtitle / 有 description 嗎?                        │
+└──────────────┬──────────────────────────────────────────────┘
+               │
+      ┌────────┴────────┐
+      │                 │
+      ▼                 ▼
+    不會               會 / 可能有
+      │                 │
+      ▼                 ▼
+ 【Fixed-height】     【Padding-based】
+  剛性宣告 chrome    彈性宣告 chrome
+  不會 grow          會隨內容 grow
+      │                 │
+      ▼                 ▼
+  h-[var(--chrome-      overlay family:
+   header-height)]     用 SurfaceHeader(見下)
+  + items-center       非 overlay:
+                       py-[var(--layout-space-tight)]
+                       + data-unbounded slot trick
+```
+
+---
+
+#### 2 種 pattern 對照
+
+| Pattern | CSS | 語義宣告 | 適用場景 |
+|---------|-----|---------|---------|
+| **Fixed-height**(剛性)| `h-[var(--chrome-header-height)]` + `items-center` | 「content 永遠單行固定結構,不會 grow」 | Sidebar / FileViewer toolbar / FileViewer InfoPanel / app top bar / page header |
+| **Padding-based**(彈性)| `py-[var(--layout-space-tight)]` + unbounded slot trick | 「content 可以 grow — title 多行 / subtitle / description」 | Dialog / Sheet / Popover / Coachmark header + footer |
+
+**兩個 pattern 在單行 content 下視覺等效都是 48/56,但語義不同 — 選錯違反元件設計意圖**。
+
+---
+
+#### 世界級對照(8 家 DS 同一 split pattern)
+
+| DS | Fixed-height 實例 | Padding-based 實例 |
+|----|-------------------|-------------------|
+| Material M3 | AppBar 56/64 dp | Dialog min-height + padding |
+| Polaris | TopBar 56px | Modal padding-based |
+| Atlassian | global nav / top bar | Modal padding |
+| Carbon(IBM)| UIShell 48px | Modal |
+| Ant Design | Layout.Header | Modal(支援 subtitle prop)|
+| Apple HIG | NavigationBar(compact)| Alert padding + NavBar large title grow |
+| GitHub Primer | PageHeader | Dialog padding |
+| VS Code / Figma | Activity Bar / toolbar | — |
+
+**結論**:我方 "fixed / padding split" 是 8/8 世界級共通 pattern。
+
+---
+
+#### 本 DS 當前分類
+
+- **Fixed-h**:Sidebar header/footer / FileViewer toolbar + InfoPanel header / app top bar(grep verify)
+- **Padding-based**(via SurfaceHeader/Footer):Dialog / Sheet / Popover / Coachmark header + footer
+- **獨立 banner family**(不屬 chrome canonical):Notice / Alert / Toast(`px-4 py-3` fixed)
+
+**一致性原則**:同元件不切換 pattern(FileViewer toolbar 永遠 fixed / Dialog 永遠 padding-based)。
+
+---
+
+#### Overlay family 的 padding-based 實作
+
+Overlay family 套 v5 `data-unbounded` slot trick(Button unbounded → SurfaceHeader 套負 my calc → 視覺 / a11y / 幾何同時對齊 chrome-header-height)。**完整細節**:`patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」。
+
+---
+
+#### 選錯的後果(驗證 decision tree 的重要性)
+
+- **Fixed-height 套到能 grow 的 chrome**(e.g. 把 Dialog 改 fixed-h 48):DialogDescription 被剪切 → 違反 modal 作為完整決策 context 的職責
+- **Padding-based 套到剛性 chrome**(e.g. 把 Sidebar header 改 padding-based):長 workspace 名稱時 chrome 跳動 → 違反 sidebar 剛性佈局職責
+- **overlay 用 xs dismiss(size 而非 layout-slot trick)**:touch target 變 24 違反 a11y,且 dismiss 按鈕尺寸與 overlay chrome 比例不協調 — v5 trick 同時保視覺 + a11y + 幾何
+
+---
+
+#### 新元件 chrome 建立 checklist
+
+建新 surface with chrome header 前必過:
+1. ☐ 跑 decision tree:title 會 grow 嗎?(有 multi-line / subtitle / description 可能性?)
+2. ☐ 選 pattern:fixed-h OR padding-based
+3. ☐ 若 fixed-h:用 `h-[var(--chrome-header-height)]` + items-center,不自訂高度
+4. ☐ 若 padding-based + overlay family:直接用 SurfaceHeader / SurfaceFooter primitive(繼承 v5 trick)
+5. ☐ 若 padding-based + 非 overlay(少見):自行 `py-tight` + `[&_[data-unbounded]]:my-[calc(...)]` CSS rule,並在 spec 記錄 rationale
+6. ☐ Dismiss button:overlay 用 `<Button dismiss size="sm" data-dismiss />`(native sm,trick 自動套);notification banner 用 `<Button dismiss size="xs" />`(family 特化)
+
+**SSOT 入口**(本節即入口):`tokens/uiSize/uiSize.spec.md`「Chrome header 選型 canonical」
+- Density lg 模式下 56px 對齊 Material 桌面 app bar 的舒適呼吸 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+---
+
+## Chrome 左右 inline padding
+
+→ SSOT `tokens/layoutSpace/layoutSpace.spec.md`「規則 1.1:Chrome inline padding canonical」(統一 `--layout-space-loose`,M8 8 家世界級對照 + 禁止事項)。
+
+---
+
+## Inline Action
+
+詳見 `patterns/element-anatomy/item-anatomy.spec.md`「Inline Action 設計規格」節。
+
+---
+
+## Icon-only 元件的 padding canonical(2026-04-25 重訂)
+
+**Idiom**:`aspect-square + p-0 + flex justify-center items-center`(Polaris / Atlassian 派)。
+**禁用**:padding-formula `(field-height - icon)/2` 派(magic numbers + 易漏扣 border)。
+
+### Canonical 配方
+
+```tsx
+const ICON_ONLY_BASE = 'aspect-square p-0 min-w-0 gap-0'
+
+// render
+className={cn(
+  baseVariants({ size }),    // 已含 h-field-X + flex items-center justify-center
+  iconOnly && ICON_ONLY_BASE,
+)}
+```
+
+`aspect-square` 鎖 width=height(從 `h-field-X` 來)。`p-0` override base 的 `px-3`。SVG flex-center 自動視覺置中。**0 magic number / 0 公式 / 0 border-deduction** — 任何 size / icon 都自然正方形。
+
+### 為什麼選 padding-free 派(2026-04-25 從 padding-formula 派切換)
+
+**舊 padding-formula 派的問題**:
+- `(field-height - icon)/2` 沒扣 `border 2px` → SVG 被 flex `min-w-0` 擠成 width<intrinsic 的不對稱(2026-04-25 user 在 Safari mobile 從 DS Devmode 抓到 14×16 bug)
+- 4 個 size 各自 hard-code icon-size magic number(16/20)與 border 2px → M17 SSOT violation
+- 公式須在每 host 重複(Button + SegmentedControl + 任何新 host)→ Rule-of-3 風險
+
+**Padding-free 派的優勢**:
+- `aspect-square` 從 `h-field-X` 計算 width,無 magic number
+- `p-0` + flex-center → SVG 自動置中,無公式
+- Border 厚度由 `border-box` 自然吸收(width 不被影響)
+- 對齊 **Polaris / Atlassian** 的 iconOnly idiom(2/4 家世界級派,另 2 家 Material/Ant 用 padding-based 屬不同設計取捨) <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+### 各 size 的 icon-size
+
+| Size | Icon size | 備註 |
+|------|-----------|------|
+| xs | 16px | 統一規則(2026-05-18 retire 過去 SegmentedControl xs=14 例外);對齊 Icon Size Tier L132-143 |
+| sm | 16px | |
+| md | 16px | |
+| lg | 20px | lg 切換到大 icon tier |
+
+icon-size 仍由 host(JS 常數 `ICON_SIZE` 或元件自管)透過 Lucide `size={iconSize}` prop 控,不走 CSS。
+
+### 適用元件
+
+目前已套用 padding-free idiom:**Button**、**SegmentedControl**。任何新增 iconOnly 互動元件必須使用 `ICON_ONLY_BASE` 配方,**禁用** padding-formula。
+
+### 反例(常見 anti-pattern)
+
+```tsx
+// ❌ 禁:magic-number padding 公式(舊 idiom,易漏扣 border)
+const ICON_ONLY_PX = {
+  sm: 'px-[calc((var(--field-height-sm)-16px)/2)]',  // 沒扣 border 2px → SVG 14×16
+  md: 'px-[calc((var(--field-height-md)-16px-2px)/2)]', // 即使扣了 still magic number
+}
+
+// ✅ 對:padding-free
+const ICON_ONLY_BASE = 'aspect-square p-0 min-w-0 gap-0'
+```
+
+---
+
+## Tailwind Bridge
+
+透過 `@theme inline` 橋接到 Tailwind spacing：
+
+```tsx
+<div className="h-field-md" />       /* = var(--field-height-md) */
+<div className="h-table-row-md" />   /* = var(--table-row-md) */
+```
+
+## 模式切換
+
+初始狀態在 `index.html` 設定：
+
+```html
+<html data-density="md">
+```
+
+動態切換：
+
+```ts
+document.documentElement.setAttribute('data-density', 'lg')
+```
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `app-shell.spec.md`
+- `breadcrumb.spec.md`
+- `popover.spec.md`