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

package/src/tokens/uiSize/uiSize.css

@@ -24,6 +24,38 @@
   --field-height-md: 2rem;      /* 32px */
   --field-height-lg: 2.25rem;   /* 36px */
 
+  /* Field control vertical padding — 讓「單行的多行控件」與同 size 單行 Input 等高 SSOT。
+     公式 = (field-height − 1lh)/2 − 1px:`1lh` 在使用端解析成該元素自己的行高(text-body 21px /
+     text-body-lg 24px),`−1px` 補 border-box 內的上下各 1px 邊框——少了它三個 size 都會高 2px。
+     density 自動連動(引用 --field-height-*,lg density 覆寫後公式仍成立)。
+     消費者:Textarea edit base + fieldViewGeometry 多行 view(兩者相等 = InlineEdit 多行零跳契約,
+     由 scripts/inline-edit-view-geometry-invariant.mjs 機械鎖)。
+     DataTable cell 不消費此 token——cell 的 padding 載體無邊框,自有 --table-cell-py 公式。 */
+  --field-control-py-sm: calc((var(--field-height-sm) - 1lh) / 2 - 1px);
+  --field-control-py-md: calc((var(--field-height-md) - 1lh) / 2 - 1px);
+  --field-control-py-lg: calc((var(--field-height-lg) - 1lh) / 2 - 1px);
+
+  /* Action-region 群組分隔線幾何 — 線長 = 該列最高元件 − inset,不短於 min,垂直置中。
+     基準是「該列最高元件」而非容器:同一列的每條線因此必然等長(不參差),換一個尺寸階的控件
+     時線自動跟著走,比值維持 0.67–0.78,落在世界級 action bar 帶內(VS Code 0.73 /
+     Primer ActionBar 0.63 / JetBrains 0.77–0.86)。
+     inset 取 8px 是我們尺寸階唯一可行值:世界級「撐滿再減」的兩家(MUI variant="middle"、
+     Primer SegmentedControl)各減 16px,但他們最小控件 32px;套到我們 24px 的 xs 階只剩 8px,
+     比 Button 圖示(16px)還矮一半。
+     min 不是新常數,它就是本公式在最小控件階的取值(--field-height-xs 24px − inset 8px = 16px),
+     所以地板永遠不覆寫公式,只在「容器宣稱的高度比它自己的內容還矮」時把結果修回誠實值。
+     --field-height-xs 明文不隨 density 縮放,故 min 在任何密度都成立;16px 同時等於 Button 的
+     圖示尺寸(button.tsx:416),與 VS Code 工具列分隔線同值(actionbar.css height:16px,同檔
+     .codicon 亦 16px)。
+     消費者:ButtonDivider(唯一實作點)。由 scripts/test-action-divider-placement.mjs 機械鎖。 */
+  --action-divider-inset: 0.5rem; /* 8px — 兩端各 4px */
+  --action-divider-min: calc(var(--field-height-xs) - var(--action-divider-inset)); /* 16px */
+
+  /* Field horizontal padding — 固定 12px(不隨 size/density);form-context field 左右內距 SSOT。
+     跟 --table-cell-px(cell-context)同 -px 慣例;Input/Select/Combobox/DatePicker/TimePicker/Textarea
+     + tag 模式右緣 re-assert 全消費此 token(取代散落的 px-3 / inline 0.75rem,M17 SSOT 可傳播)。 */
+  --field-px: 0.75rem;          /* 12px */
+
   /* Table Row Height — DataTable */
   --table-row-sm: 2rem;         /* 32px */
   --table-row-md: 2.5rem;       /* 40px */
@@ -49,6 +81,25 @@
      不寫成 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));
+
+  /* AgentPanel — 智慧代理右側面板寬(2026-09-02;agent-panel.spec.md token table SSOT)
+     稿「Task-Desktop」全六畫面 rightSider 實測 400;命名同 --sidebar-width L4 layout 前例 */
+  --agent-panel-width: 25rem;      /* 400px 預設 */
+  --agent-panel-width-min: 22.5rem; /* 360px 拖拉下限(2026-09-02 user 拍板) */
+  --agent-panel-width-max: 40rem;   /* 640px 拖拉上限(= AppShell ASIDE_WIDTH_MAX;runtime 另 clamp ≤50vw) */
+
   /* 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 */
@@ -57,7 +108,7 @@
   --tree-indent-lg: 1.75rem;    /* 28px */
 
   /* DataTable Panel Widths — Sort manager / Filter panel cells(SSOT,2026-05-23 deep-audit Phase A.4 Decision 2 codify per user verbatim「決策二照你建議做」+「確保最SSOT最簡潔」)
-     Consumer:data-table-sort-manager.tsx / data-table-filter-panel.tsx
+     Consumer:data-table-sort-manager.tsx / data-table-filter-group.tsx(FilterRow;2026-07-14 拆檔自 filter-panel)
      不 density-scale(panels 是 floating layout,不該跟密度走)
      Naming aligned to family `--<component>-<part>-<size>`(per --field-height-* / --table-row-* / --tab-height-* precedent)*/
   --data-table-sort-panel-width: 30rem;       /* 480px — sort manager root container width */
@@ -67,6 +118,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 */
@@ -100,6 +154,11 @@
   --tab-height-md: 2.5rem;      /* 40px */
   --tab-height-lg: 3rem;        /* 48px */
 
+  /* 2026-07-16 dim 52 補洞:lg block(上方)有 override --chrome-header-height 3.5rem,
+     md-reset 原漏重設 → lg 祖先下 subtree lock md 時 chrome header 仍 56px,破 W3
+     像素相等恆等式(md-lock subtree 必須與 root md 逐 token 相等)。值 = :root md default。 */
+  --chrome-header-height: 3rem; /* 48px — md default */
+
   --tree-indent-sm: 1.5rem;     /* 24px — md default */
   --tree-indent-md: 1.5rem;     /* 24px — md default */
   --tree-indent-lg: 1.75rem;    /* 28px — md default */

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

@@ -3,7 +3,7 @@
 # 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 SSOT。定義 field-height family `md` default / chrome-header 選型 decision tree(fixed-h vs padding-based + 8 家對照)/ icon-only padding-free canonical。Button / Input / Select / Checkbox / Slider / Tabs 等皆消費,scope 本質 > 單一 token 檔。
 
 元件高度的語義 token，rem 單位。透過 `data-density`（或 `data-ui-size`）切換。
 
@@ -39,7 +39,7 @@ Button、Input、Checkbox/Radio SelectionItem 等互動元件。
 | `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) |
+| `Rating` | xs / sm / md / lg | standalone **`xs`** / Field 內跟 Field size(md) | `--field-height-*`(container 對齊;icon 走 identity scale {xs:20, sm:20, md:24, lg:24} 非 icon tier — 偏離 rationale 詳 `rating.spec.md`「為什麼不 default md」+「為什麼不完全對齊 icon tier」段 + 本檔「跨 regime pointer index」carve-out row) |
 | `TimePicker` | sm / md / lg | **`md`** | `--field-height-md`(Ant-style 時間選擇,對齊 DatePicker 家族) |
 | `Tag` | sm / md / lg | **`md`** | 自帶尺寸，透過 Field size 配對 |
 
@@ -47,7 +47,7 @@ Button、Input、Checkbox/Radio SelectionItem 等互動元件。
 
 | 元件 | 固定 size | 理由 |
 |------|----------|------|
-| `Chip` | 固定 `h-field-sm`（28/32px） | Material 3 / Atlassian / Polaris 共識：filter chips 使用單一高度。不暴露 size prop |
+| `Chip` | 固定 `h-field-sm`（28/32px） | Material 3 / Atlassian / Polaris 共識：filter chips 使用單一高度。不暴露 size prop | <!-- @benchmark-unverified -->
 
 #### 偏離 field-height family 的 rationale 格式(canonical)
 
@@ -67,7 +67,7 @@ Button、Input、Checkbox/Radio SelectionItem 等互動元件。
 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。
+**需補齊 rationale 段的元件**:(無 — Phase 2 已全部補齊)。未來新增偏離 field-height 的元件 → 必須按本格式寫(三欄格式為本 spec 約定,非機械 enforce;`/design-system-audit` 僅經 audit-prompts 通用 rationale-grep + Rule B density flag 間接把關)。
 
 **audit hook 未來擴展**:若 cva `defaultVariants.size` 不是 `md`,或 `size` variants 的數值不命中 `--field-height-*`,hook 可要求 spec.md 必有符合格式的 rationale 段,否則 block merge(列為 post-Phase-2 可考慮加上的 mechanical gate)。
 
@@ -94,6 +94,20 @@ Consumer 寫 Form 或 Toolbar 時並排多個 field-height 元件：
 
 本專案曾發生 SegmentedControl 的 code defaults 是 `md`、spec + docblock 寫 `sm ★default` 的三方不一致（2026-04-18 修正）。避免方式：改 cva `defaultVariants` 前先讀本表，確認新值仍符合 family 約束。
 
+## Field Horizontal Padding
+
+Form-context field 控件的左右水平內距。**固定 12px,不隨 size / density 變化**——縱向才是 density 節奏;橫向是內容溝槽常數,對齊 field-height family 全控件。
+
+| Token | 值 | 說明 |
+|-------|-----|------|
+| `--field-px` | 0.75rem (12px) | form-context field 左右內距 SSOT;固定不隨 size / density |
+
+**消費者**:`Input` / `NumberInput` / `Select` / `Combobox` / `DatePicker` / `TimePicker` / `LinkInput` / `Textarea`(經 `fieldWrapperStyles` cva `px-[var(--field-px)]`)+ `PeoplePicker`(form-context inject `!px-[var(--field-px)]`)+ tag 模式右緣 re-assert(`paddingRight: var(--field-px)`,Select / Combobox readonly + edit)。
+
+**與 `--table-cell-px` 的關係**:同 `-px` 命名慣例。`--table-cell-px`(DataTable-scoped)預設 `var(--field-px)`(form / cell 同 12px content gutter SSOT),但仍是獨立 named token、可被 DataTable 單獨 override(per `components/Field/field-controls.spec.md` contract (c) scoped 決策)。
+
+**Why 固定不隨 density**:density 本質是縱向密度(一屏幾列);橫向管可讀性(字離格線距離),目的不同不綁。對齊 Ant Table(橫向 padding 不隨 density 變、縱橫分離)+ 全 DS field 控件 12px 常數。M17「SSOT 必可傳播」:散落的 `px-3` / inline `0.75rem` 全收斂進此 token。
+
 ## Table Row
 
 DataTable 行高。density 切換統一 +0.5rem (+8px)。
@@ -144,17 +158,18 @@ DataTable 行高。density 切換統一 +0.5rem (+8px)。
 
 ### 跨 regime pointer index(2026-05-18 codify per user audit「確保 SSOT 不偏移」)
 
-本 Icon Size Tier 段是 DS-wide icon size SSOT 的**主索引**。下列 7 個 carve-out 是別律 owner:
+本 Icon Size Tier 段是 DS-wide icon size SSOT 的**主索引**。下列 8 個 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 |
+| Rating star | `components/Rating/rating.spec.md:85` | Identity scale `{sm:20, md:24, lg:24}` 不走 icon tier | Ant 20 / Material 24 / Airbnb 24 | <!-- @benchmark-unverified -->
+| Avatar 內 icon | `components/Avatar/avatar.spec.md:160` | `round_even(size × 0.6)` formula | Material / Apple HIG |
+| Empty illustration | `components/Empty/empty.tsx:57` | Avatar 48 wrap → icon 28(Avatar formula derived)| Empty-state canonical |
+| FileViewer thumb | `components/FileViewer/file-viewer.tsx:552,637` | thumb 64 → icon 20(file-type indicator hardcode 無公式)| Thumbnail UI 慣例 |
+| CircularProgress | `components/CircularProgress/circular-progress.tsx:86` | `strokeWidth = max(2, round(size/10))` stroke ring 厚度非 icon | Geometric scaling |
+| Steps indicator icon | `components/Steps/steps.tsx:25` | `INDICATOR_ICON_SIZE {sm:0, md:16, lg:20}`(sm 因圓圈 8px 太小)| Indicator-internal |
+| Slider thumb/track | `components/Slider/slider.spec.md:86` | thumb 16 / track 4px 固定不隨 size 變(視覺 single tier)| Material 3 / iOS / Ant / Radix 固定 thumb | <!-- @benchmark-unverified -->
+| Checkbox/Switch check | `components/Checkbox/checkbox.tsx:52` + `components/Switch/switch.tsx:83` | `{sm:12, md:12, lg:16}` form-control internal + stroke 下限 12 | iOS HIG / Material 3 / Polaris | <!-- @benchmark-unverified -->
 
 **程式化 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)。
 
@@ -178,21 +193,21 @@ Tabs 導覽容器的高度。獨立於 field-height 和 table-row——tabs 是
 
 | 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 |
+| `--tab-height-sm` | 32px | 40px | **預設**(2026-05-17 從 md 改,per `header-canonical.spec.md` Rule W6)— overlay / chrome / dense toolbar tabs |
+| `--tab-height-md` | 40px | 48px | future tier(無 recommended use case,2026-05-17 從預設降級) |
+| `--tab-height-lg` | 48px | 56px | Page-level hero tabs(獨立 tabs 取代 chrome header,值 = `--chrome-header-height`) |
 
 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 高度崩潰。
+應用程式 chrome 區域(Sidebar header、app top bar、主內容 page header)共用的高度語義。Authority 定義在 DS package `packages/design-system/src/tokens/uiSize/uiSize.css`，確保 package consumer 不需重複宣告。這是跨佈局層級 token；本節擁有其語意與 consumer 清單，source 擁有確切宣告。
 
 **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 消費)|
+| `--chrome-header-height` | 48px | 56px | Sidebar header/footer、主內容 page header、app top bar、**Overlay family chrome**(Dialog / Sheet / Popover / Coachmark header + footer,透過 `patterns/overlay-surface` 的 SurfaceHeader / SurfaceFooter padding-based 公式自然閉合等值 48/56,**無 min-h 強鎖**(詳 overlay-surface.spec.md「Chrome dismiss size canonical」))、**Chrome family ChromeHeader primitive**(`patterns/header-canonical/chrome-header.tsx`,Sidebar / FileViewer Toolbar+InfoPanel 消費)|
 
 ### Canonical 意圖(AR47,2026-04-21)
 
@@ -217,7 +232,7 @@ Tailwind：`h-tab-sm` / `h-tab-md` / `h-tab-lg`。
 - 不同 → 其中一個元件在 density-override 情境,行為正確
 
 **為什麼 48 不 56 / 64**:
-- Material App Bar 56dp(mobile)/ 64dp(desktop);Airbnb 主站 header 80px;Shopify 64px
+- Material App Bar 56dp(mobile)/ 64dp(desktop);Airbnb 主站 header 80px;Shopify 64px <!-- @benchmark-unverified -->
 - 本 DS 選 **48px @ md / 56px @ lg** 取「密集工具型產品」的下限(Linear / Figma / Notion 主 chrome 40-52px),給主內容區留更多 vertical space
 - 跟 Button-lg + Field-lg 高度(40 / 36)拉出視覺 hierarchy — chrome 高於任何 row control,但不壓迫內容
 
@@ -270,7 +285,7 @@ Tailwind：`h-tab-sm` / `h-tab-md` / `h-tab-lg`。
 
 | DS | Fixed-height 實例 | Padding-based 實例 |
 |----|-------------------|-------------------|
-| Material M3 | AppBar 56/64 dp | Dialog min-height + padding |
+| Material M3 | AppBar 56/64 dp | Dialog min-height + padding | <!-- @benchmark-unverified -->
 | Polaris | TopBar 56px | Modal padding-based |
 | Atlassian | global nav / top bar | Modal padding |
 | Carbon(IBM)| UIShell 48px | Modal |
@@ -302,7 +317,7 @@ Overlay family 套 v5 `data-unbounded` slot trick(Button unbounded → SurfaceHe
 #### 選錯的後果(驗證 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 剛性佈局職責
+- **Padding-based 套到剛性 chrome**(e.g. 把 Sidebar header 改 padding-based):高度會變成內容驅動，違反 sidebar 的固定 chrome contract
 - **overlay 用 xs dismiss(size 而非 layout-slot trick)**:touch target 變 24 違反 a11y,且 dismiss 按鈕尺寸與 overlay chrome 比例不協調 — v5 trick 同時保視覺 + a11y + 幾何
 
 ---
@@ -324,13 +339,13 @@ Overlay family 套 v5 `data-unbounded` slot trick(Button unbounded → SurfaceHe
 
 ## Chrome 左右 inline padding
 
-→ SSOT `tokens/layoutSpace/layoutSpace.spec.md`「規則 1.1:Chrome inline padding canonical」(統一 `--layout-space-loose`,M8 8 家世界級對照 + 禁止事項)。
+→ SSOT `tokens/layoutSpace/layoutSpace.spec.md`「規則 6:Chrome 水平左右 padding(規則 1 specialization)」(統一 `--layout-space-loose`,M8 8 家世界級對照 + 禁止事項)。
 
 ---
 
 ## Inline Action
 
-詳見 `patterns/element-anatomy/item-anatomy.spec.md`「Inline Action 設計規格」節。
+詳見 `patterns/element-anatomy/inline-action.spec.md`(獨立 SSOT,2026-04-24 自 item-anatomy 抽出)。
 
 ---
 
@@ -353,6 +368,8 @@ className={cn(
 
 `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 都自然正方形。
 
+**邊界(非 1:1 viewBox icon / RTL)**:容器寬恆等高、`p-0` 四邊對稱,flex 置中對任意 icon viewBox 比例與 RTL 方向皆不變形,無需特例。
+
 ### 為什麼選 padding-free 派(2026-04-25 從 padding-formula 派切換)
 
 **舊 padding-formula 派的問題**:
@@ -370,7 +387,7 @@ className={cn(
 
 | Size | Icon size | 備註 |
 |------|-----------|------|
-| xs | 16px | 統一規則(2026-05-18 retire 過去 SegmentedControl xs=14 例外);對齊 Icon Size Tier L132-143 |
+| xs | 16px | 統一規則(2026-05-18 retire 過去 SegmentedControl xs=14 例外);對齊本檔「Icon 尺寸 Tier」段 |
 | sm | 16px | |
 | md | 16px | |
 | lg | 20px | lg 切換到大 icon tier |
@@ -396,6 +413,20 @@ const ICON_ONLY_BASE = 'aspect-square p-0 min-w-0 gap-0'
 
 ---
 
+## 何時不用(反 pattern 總覽)
+
+散在各節的 ❌ 規則總索引(細節以 owner 段落為準):
+
+| ❌ 場景 | 正解 | Owner 段落 |
+|---|---|---|
+| 互動元件高度 < 24px | 重新檢視容器佈局,不縮元件 | 「元件高度地板」 |
+| chrome 區域硬寫高度(`h-16` 等) | `h-[var(--chrome-header-height)]` | 「Canonical 意圖(AR47)」 |
+| iconOnly 用 padding 公式 | `ICON_ONLY_BASE` padding-free | 「Icon-only 元件的 padding canonical」 |
+| Tabs 高度借用 field-height / table-row | `--tab-height-*`(概念獨立) | 「Tab Height」 |
+| 新 field-height 消費者 default ≠ md | default `md`;偏離必寫 rationale | 「硬規則」+「偏離 rationale 格式」 |
+
+---
+
 ## Tailwind Bridge
 
 透過 `@theme inline` 橋接到 Tailwind spacing：
@@ -423,16 +454,14 @@ document.documentElement.setAttribute('data-density', 'lg')
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `app-shell.spec.md`
+- `breadcrumb.spec.md`
 - `button.spec.md`
 - `dialog.spec.md`
+- `header-canonical.spec.md`
+- `overlay-surface.spec.md`
+- `popover.spec.md`
+- `segmented-control.spec.md`
 - `selection-item.spec.md`
 - `slider.spec.md`
-- `tree-view.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
-- `app-shell.spec.md`
-- `breadcrumb.spec.md`
-- `popover.spec.md`
+- `token-system.spec.md`

package/src/tokens/uiSize/uiSize.stories.tsx

@@ -0,0 +1,106 @@
+// @story-baseline: tokens/density/density.stories.tsx#UISize — token bar 展示慣例同源;本頁展示 size-tier 軸(xs/sm/md/lg + icon 兩 tier),density md/lg 軸在 Tokens/Density 不重複
+import type { Meta, StoryObj } from '@storybook/react'
+import { Download } from 'lucide-react'
+import { ICON_SIZE } from './icon-size'
+
+const meta: Meta = {
+  title: 'Design System/Tokens/UiSize',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: `
+元件高度的語義 token(rem 單位,尊重使用者瀏覽器字體設定)。\`--field-height-*\` 是核心家族——Button / Input / Select 等互動元件共享 **default \`md\`**;另有 table-row / tab-height / chrome-header 等家族(見 spec)。
+
+完整規則:\`packages/design-system/src/tokens/uiSize/uiSize.spec.md\`(family 成員清單 / default md 硬規則 / icon 兩 tier / chrome header 選型)
+
+**md ↔ lg density 軸**的對照展示在 \`Design System/Tokens/Density\`,本頁不重複;此處展示 **size tier 軸**(xs / sm / md / lg)與 icon 尺寸的離散配對。
+        `,
+      },
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj
+
+
+function HeightRow({ token, px, usage, isDefault }: {
+  token: string; px: string; usage: string; isDefault?: boolean
+}) {
+  return (
+    <div className="grid items-center gap-x-6 border-b border-border py-3 last:border-0"
+      style={{ gridTemplateColumns: '200px 160px 60px 1fr' }}>
+      <div>
+        <code className="block text-caption font-medium text-fg-secondary">{token}</code>
+        {isDefault && <span className="text-caption text-fg-muted">★ family default</span>}
+      </div>
+      <div
+        className="rounded-md bg-primary"
+        style={{ height: `var(${token})`, width: '100%' }}
+      />
+      <span className="text-caption font-mono text-fg-muted">{px}</span>
+      <span className="text-body text-foreground">{usage}</span>
+    </div>
+  )
+}
+
+function IconTierRow({ tier, iconPx, note }: { tier: string; iconPx: number; note: string }) {
+  return (
+    <div className="grid items-center gap-x-6 border-b border-border py-3 last:border-0"
+      style={{ gridTemplateColumns: '260px 120px 1fr' }}>
+      <code className="text-caption font-medium text-fg-secondary">{tier}</code>
+      <div className="flex items-center gap-2">
+        <Download size={iconPx} className="text-foreground" aria-hidden />
+        <span className="text-caption font-mono text-fg-muted">{iconPx}px</span>
+      </div>
+      <span className="text-body text-foreground">{note}</span>
+    </div>
+  )
+}
+
+
+export const Overview: Story = {
+  name: '總覽',
+  render: () => (
+    <div className="max-w-3xl">
+      <h2 className="text-h3 mb-2">Field Height</h2>
+      <p className="text-body text-fg-secondary mb-4">
+        Button / Input / Checkbox SelectionItem 等互動元件的高度。一般 field family 消費者
+        <strong>不傳 size 時預設 md</strong>——Form / Toolbar 並排多控件默認等高。
+        documented carve-outs 例外:Rating standalone 預設 xs(Field 內才跟 md)、
+        Chip 等單一尺寸消費者不在 default-md 規則內(uiSize.spec.md「單一尺寸消費者」段)。
+        下列為 md density 預設值(lg density 對照見 Tokens/Density)。
+      </p>
+
+      <HeightRow token="--field-height-xs" px="24px" usage="密集 UI 地板高度;固定不隨 density 縮放。獨立互動元件不得低於此高度" />
+      <HeightRow token="--field-height-sm" px="28px" usage="輕量浮層(Popover body / footer)內的控件尺寸" />
+      <HeightRow token="--field-height-md" px="32px" usage="Form / Dialog / 一般頁面的控件尺寸" isDefault />
+      <HeightRow token="--field-height-lg" px="36px" usage="需要更大點擊目標的場景;同時切換到大 icon tier(20px)" />
+
+      <h2 className="text-h3 mb-2 mt-10">Icon 尺寸兩 tier</h2>
+      <p className="text-body text-fg-secondary mb-4">
+        Icon 尺寸由元件引用的 field-height token 決定——離散兩組配對,無中間值、不需公式。
+        程式化 SSOT 是 <code>ICON_SIZE</code> 常數(本表直接消費真值渲染)。
+      </p>
+
+      <IconTierRow
+        tier="field-height-xs / sm / md"
+        iconPx={ICON_SIZE.sm}
+        note="搭配 text-body(14px);Checkbox / Radio 控件同 16px"
+      />
+      <IconTierRow
+        tier="field-height-lg"
+        iconPx={ICON_SIZE.lg}
+        note="搭配 text-body-lg(16px);Checkbox / Radio 控件同 20px"
+      />
+
+      <p className="text-caption text-fg-muted mt-6">
+        Stroke icon 下限 12px(僅出現在 Checkbox 等指示器內部);Rating / Avatar 等 8 個 carve-out
+        見 <code>uiSize.spec.md</code>「跨 regime pointer index」。table-row / tab-height /
+        chrome-header 等其餘 uiSize 家族與選型 decision tree 同見該 spec。
+      </p>
+    </div>
+  ),
+}