@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

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

@@ -0,0 +1,465 @@
+<!-- @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 padding-free canonical。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 | <!-- @benchmark-unverified -->
+
+#### 偏離 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 約束。
+
+## 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)。
+
+| 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 | <!-- @benchmark-unverified -->
+| 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: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 |
+| 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)。
+
+**新加 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 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)
+
+**任何跨整個 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 <!-- @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,但不壓迫內容
+
+### 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 | <!-- @benchmark-unverified -->
+| 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/inline-action.spec.md`(獨立 SSOT,2026-04-24 自 item-anatomy 抽出)。
+
+---
+
+## 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 都自然正方形。
+
+**邊界(非 1:1 viewBox icon / RTL)**:容器寬恆等高、`p-0` 四邊對稱,flex 置中對任意 icon viewBox 比例與 RTL 方向皆不變形,無需特例。
+
+### 為什麼選 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'
+```
+
+---
+
+## 何時不用(反 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：
+
+```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`
+- `button.spec.md`
+- `header-canonical.spec.md`
+- `overlay-surface.spec.md`
+- `popover.spec.md`
+- `segmented-control.spec.md`
+- `selection-item.spec.md`
+- `slider.spec.md`
+- `token-system.spec.md`

package/src/tokens/utility-registry.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "./utility-registry.schema.json",
+  "_meta": {
+    "purpose": "Single SSOT for Tailwind utility allow/block — extracted from typography/radius/opacity/elevation/color spec.md 禁止 lists. Hook reads this(not grep spec.md)to enforce token-first discipline. New token additions or removals → update here first, spec.md cite registry.",
+    "owner": "packages/design-system/src/tokens/utility-registry.json",
+    "consumed_by": [
+      ".claude/hooks/check_opacity_token_usage.sh",
+      ".claude/skills/design-system-audit/references/audit-prompts.md Dim 5"
+    ],
+    "spec_sources": [
+      "packages/design-system/src/tokens/typography/typography.spec.md L91-105",
+      "packages/design-system/src/tokens/radius/radius.spec.md L57-71",
+      "packages/design-system/src/tokens/opacity/opacity.spec.md L53-57",
+      "packages/design-system/src/tokens/color/color.spec.md(hardcoded hex/rgb canonical)",
+      "packages/design-system/src/tokens/elevation/elevation.spec.md(shadow-{sm,md,lg,xl,2xl} 禁)"
+    ],
+    "rationale": "World-class DS(Atlassian @atlaskit/tokens / Carbon @carbon/themes / Ant ConfigProvider / Polaris polaris-tokens)用 registry + lint, 不靠 grep 各處 spec.md。Rule-of-3 violation 已存在(典型禁止 list 在 3 個 spec.md 各寫一份)— 本檔抽 SSOT。",
+    "exceptions": {
+      "_added": "2026-05-17 per audit Dim 47 codex 比稿後 codify;補 anatomy stories Inspector panel UI 跟 DS surface 分層 carve-out",
+      "anatomy_stories_inspector": {
+        "scope": "*.anatomy.stories.tsx — Inspector panel / Side legend / Section H3 decoration UI",
+        "allowed_utilities": ["tracking-wider", "font-semibold", "text-[10px]", "text-[11px]", "text-[12px]", "leading-none"],
+        "rationale": "Anatomy stories Inspector panel 是 storybook-internal 教學工具 UI(展示元件結構的 side legend / footnote / uppercase header),非 DS component surface。需視覺辨識(uppercase label + 寬 letter-spacing / 小字 metadata)跟 DS 主元件 typography 分層。對齊 Carbon storybook addon、Material storybook addon 共識:tool UI 不受 token-first 約束。`leading-none` 2026-05-21 D1 codex 抓 badge.anatomy L117/118 後加入(10-11px monospace inspector label 需要緊湊 line-height,跟 DS body/body-lg `leading-compact 1.3` 場景分層)。",
+        "audit_dim_53_fix": "Dim 47 sub-agent 抓 anatomy stories tracking-wider / font-semibold / text-[NN] / leading-none 多處違反 = false positive(本例外段 codify 後豁免)"
+      },
+      "token_stories_section_label": {
+        "scope": "packages/design-system/src/tokens/**/*.stories.tsx — SectionLabel helper(uppercase + wider tracking section header)",
+        "allowed_utilities": ["tracking-wider", "font-semibold"],
+        "rationale": "Token stories(color / typography / radius / elevation / opacity / uiSize / layoutSpace / density)是 token 展示 storybook,用 SectionLabel(`uppercase + tracking-wider`)分區 swatch 群組,跟 anatomy stories Inspector panel 同 storybook-internal teaching UI 性質,非 DS component surface。Phase A audit 2026-05-21 codify。"
+      },
+      "principles_stories_codepre": {
+        "scope": "*.principles.stories.tsx — <pre><code> code sample blocks",
+        "allowed_utilities": ["text-xs", "text-sm"],
+        "rationale": "Code sample 區塊用 <pre><code> + monospace font,需小字呈現程式碼 — 跟 DS prose 不同層級。Polaris / Carbon storybook code blocks 同樣使用 smaller font。"
+      },
+      "icon_as_text_and_numeric_in_circle": {
+        "scope": "Production tsx — icon-as-text / numeric-in-circle / single-line short text in fixed-h container",
+        "allowed_utilities": ["leading-none"],
+        "rule_one_liner": "icon-as-text / numeric-in-circle 一律用 `leading-none`(不用 `leading-compact`)",
+        "rationale": "2026-05-23 Path B codify per user verbatim「或是其實根本不用分?」+「照你建議」:統一 leading-none,不分 fixed-box vs derived-h。對齊 Material UI Avatar `line-height: 1` / Polaris Badge `line-height: 1` / Carbon Tag(不顯式設,等效 1)世界級共識。視覺驗證:固定高度容器 + items-center 主導,line-height 1.0 vs 1.3 vs 1.5 視覺零差別(playwright probe `scripts/probe-leading-migration.mjs` Steps step-number box delta = 0px)。廢除原 2026-05-21 F1 Badge 從 leading-none → leading-compact migration(over-engineered,違 mindset #1 不取巧不發明)+ 原 production_layout_positioning_anchor exception(改 affirmative canonical 不需 exception)。",
+        "current_consumers": [
+          "Badge/badge.tsx — count badge in fixed h-4 circle",
+          "Avatar/avatar.tsx — initial letter in fixed w-N h-N circle",
+          "OverflowIndicator/overflow-indicator.tsx — `+N` numeric in fixed h-5/h-6 circle",
+          "Steps/steps.tsx — step-number in fixed-diameter circle",
+          "Button/button.tsx:465 — overlayBadge inline-block positioning anchor(documented 2026-04-20)",
+          "Chart/chart.tsx:247 — recharts tooltip tight flex layout"
+        ],
+        "non_goal": "本 canonical 不適用 body / paragraph / heading typography(那些走 typography.allow `leading-compact` / `leading-normal` token)"
+      }
+    }
+  },
+  "typography": {
+    "allow": [
+      "text-h1", "text-h2", "text-h3", "text-h4", "text-h5", "text-h6",
+      "text-body", "text-caption", "text-helper", "text-label",
+      "leading-compact", "leading-normal",
+      "font-normal", "font-medium", "font-bold",
+      "tracking-shortcut"
+    ],
+    "block": {
+      "size_raw": ["text-xs", "text-sm", "text-base", "text-lg", "text-xl", "text-2xl", "text-3xl", "text-4xl", "text-5xl", "text-6xl", "text-7xl", "text-8xl", "text-9xl"],
+      "weight_raw": ["font-thin", "font-extralight", "font-light", "font-semibold", "font-extrabold", "font-black"],
+      "leading_numeric": "leading-{N}(use leading-compact / leading-normal token)",
+      "tracking_raw": ["tracking-tighter", "tracking-tight", "tracking-wide", "tracking-wider", "tracking-widest"],
+      "tracking_raw_rationale": "Block raw Tailwind tracking-* utility(unscoped letter-spacing leaks 跨元件不一致)。需要 wider letter-spacing 場景必 codify role-specific semantic utility — 例如 `tracking-shortcut`(鍵盤快捷鍵 hint,0.1em,對應 --tracking-shortcut token)。新 role 必走 typography.css 新增 `--tracking-<role>` + `@utility tracking-<role>`,再 allow 進本 registry。",
+      "inline_style": "style={{ fontSize: ..., lineHeight: ... }}",
+      "rationale_path": "packages/design-system/src/tokens/typography/typography.spec.md L91-105"
+    }
+  },
+  "radius": {
+    "allow": ["rounded-xs", "rounded-sm", "rounded-md", "rounded-lg", "rounded-full"],
+    "block": {
+      "out_of_range": ["rounded-xl", "rounded-2xl", "rounded-3xl"],
+      "ambiguous_default": "rounded(use rounded-md explicit)",
+      "arbitrary_value": ["rounded-[6px]", "rounded-[var(--radius-md)]"],
+      "inline_style": "style={{ borderRadius: ... }}",
+      "rationale_path": "packages/design-system/src/tokens/radius/radius.spec.md L57-71"
+    }
+  },
+  "opacity": {
+    "allow": ["opacity-0", "opacity-100", "opacity-disabled"],
+    "block": {
+      "numeric_tier": ["opacity-5", "opacity-10", "opacity-20", "opacity-25", "opacity-30", "opacity-40", "opacity-50", "opacity-60", "opacity-70", "opacity-75", "opacity-80", "opacity-90", "opacity-95"],
+      "arbitrary_value": "opacity-[0.N](use --opacity-disabled or token swap)",
+      "rationale_path": "packages/design-system/src/tokens/opacity/opacity.spec.md L53-57",
+      "philosophy": "Single semantic token(0.45)vs Tailwind multi-tier(對齊 Polaris / Material / Apple 單值哲學)"
+    }
+  },
+  "elevation": {
+    "allow": ["shadow-[var(--elevation-100)]", "shadow-[var(--elevation-100-hover)]", "shadow-[var(--elevation-200)]", "shadow-[var(--elevation-200-hover)]"],
+    "block": {
+      "tailwind_size": ["shadow-sm", "shadow", "shadow-md", "shadow-lg", "shadow-xl", "shadow-2xl", "shadow-inner"],
+      "rationale_path": "packages/design-system/src/tokens/elevation/elevation.spec.md",
+      "philosophy": "DS 採 2-tier elevation(100 / 200)語意而非 Tailwind size ladder"
+    }
+  },
+  "spacing": {
+    "allow_canonical": "對齊 spec(gap-2/3/4/6/8 等;layout-space token via var())",
+    "warn": {
+      "micro_gap": ["gap-px", "gap-0.5", "gap-1.5"],
+      "rationale": "<4px gap 通常違反 item-anatomy slot 幾何。Allow exception in spec.md(Skeleton bone / inline action 等)but flag for human review."
+    }
+  },
+  "sizing": {
+    "warn": {
+      "fraction": ["w-1/3", "w-2/3", "w-1/4", "w-3/4", "w-1/5", "w-2/5", "w-3/5", "w-4/5", "w-1/6", "w-5/6", "w-1/12", "w-5/12", "w-7/12", "w-11/12"],
+      "rationale": "Fraction width 通常 inside DS component = layout SSOT 漂移。Allow if component spec owns layout(eg. Field labelWidth 比例)but flag。"
+    }
+  },
+  "shadcn_alias": {
+    "block": {
+      "color_alias": ["bg-popover", "text-popover-foreground", "text-muted-foreground", "bg-accent", "text-accent-foreground", "bg-destructive", "bg-background", "text-background", "border-input"],
+      "rationale": "shadcn compat alias 不聯動 DS dark mode。改用 direct token(--surface-raised / --fg-muted / --error 等)",
+      "rationale_path": "CLAUDE.md `# 失敗記憶索引` shadcn compat alias 回流"
+    }
+  },
+  "primitive_color_as_utility": {
+    "block": {
+      "primitive_class": ["bg-neutral-1", "bg-neutral-2", "text-blue-6", "text-red-7", "border-blue-3"],
+      "rationale": "primitive 色名作 utility = 越過 semantic 層。用 semantic utility(bg-surface / text-fg-secondary 等)或 var() bracket(bg-[var(--color-blue-6)])"
+    }
+  }
+}

package/dist/components/NameCard/name-card.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"name-card.d.ts","sourceRoot":"","sources":["../../../src/components/NameCard/name-card.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B,OAAO,EAAU,KAAK,UAAU,EAAE,MAAM,0CAA0C,CAAA;AAMlF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,sBAAsB,+CAKlC,CAAA;AAqBD,KAAK,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;AAiBxD;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,eAAO,MAAM,2BAA2B,mCAAoC,CAAA;AAC5E,KAAK,uBAAuB,GAAG,OAAO,2BAA2B,CAAC,MAAM,CAAC,CAAA;AASzE,MAAM,WAAW,aAAc,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IACzE,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,aAAa,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC/B,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB;;;;OAIG;IACH,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,SAAS,CAAA;KAAE,EAAE,CAAA;IACpD;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,uBAAuB,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAA;IAC9E,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;IACvB,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAGD,QAAA,MAAM,QAAQ,sFAuKb,CAAA;AAKD,eAAO,MAAM,YAAY;;;;;;;;;;;CAef,CAAA;AAEV,OAAO,EAAE,QAAQ,EAAE,CAAA"}

package/dist/components/NameCard/name-card.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"name-card.js","sources":["../../../src/components/NameCard/name-card.tsx"],"sourcesContent":["// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.\nimport * as React from 'react'\nimport { MessageCircle, Phone, ChevronDown } from 'lucide-react'\nimport { cn } from '@/lib/utils'\nimport { Avatar, type AvatarData } from '@/design-system/components/Avatar/avatar'\nimport { Button } from '@/design-system/components/Button/button'\nimport { DescriptionList, DescriptionItem } from '@/design-system/components/DescriptionList/description-list'\nimport { ScrollArea } from '@/design-system/components/ScrollArea/scroll-area'\nimport { ItemContent } from '@/design-system/patterns/element-anatomy/item-anatomy'\n\n/**\n * NameCardDefaultActions — canonical 預設 action 組合\n *\n * ── 為什麼需要 export ──\n * NameCard 的 action 列在世界級 chat/contact app 是「關係型快速動作」的 canonical\n * (Slack / iMessage / LinkedIn / Figma 皆如此):**Chat / Message + Audio call**。\n * 跨 consumer(avatar.principles / name-card.stories / future product code)應該用\n * 同一組預設,避免每個範例各自發明 action 組合,讓 reader 誤以為 action 會隨情境自動變。\n *\n * ── 使用方式(hover context 必含 onViewMore,見 name-card.spec.md 「View more」節)──\n *   <NameCard name=\"...\" actions={<NameCardDefaultActions />} onViewMore={...} />\n *\n * ── 何時要換成自訂 action ──\n * - Single-action 情境(只要「傳訊息」)→ consumer 傳 `<Button>傳訊息</Button>`\n * - 特定情境的 action(管理員「撤銷邀請」/ HR「離職管理」)→ consumer 自訂\n * - 非人員關係動作(「訂購此商品」)→ 根本不應該用 NameCard\n *\n * Chat + Audio call 是 **default**,不是 **only**——consumer 可覆寫,但需有明確理由。\n */\nexport const NameCardDefaultActions = () => (\n  <>\n    <Button variant=\"tertiary\" size=\"sm\" startIcon={MessageCircle}>Chat</Button>\n    <Button variant=\"tertiary\" size=\"sm\" startIcon={Phone} endIcon={ChevronDown}>Audio call</Button>\n  </>\n)\n\n/**\n * NameCard — 人員 HoverCard 的內容元件\n *\n * ── Status 對齊 Avatar presence canonical(2026-04-20) ──\n * status type = `online | away | busy | offline`,跟 Avatar 的 presence prop 對齊\n * (世界級 Slack / Teams / Discord term);dot 色走 `--status-*` semantic token\n * (獨立於 success/error/warning,避免語義衝突)。\n *\n * ── Avatar 對齊 ──\n * 跟 FileItem rich 統一:右側 text column 用 justify-center + minHeight=avatar。\n * 短文字置中於 avatar,長文字(多行名字)自然撐高。\n *\n * ── Info fields ──\n * Status message / ID / Employee number 等唯讀屬性全部用 DescriptionList 家族\n * 承載(不手刻 dt/dd),canonical 由 DS primitive own。\n */\n\nconst AVATAR_SIZE = 64\n\ntype StatusType = 'online' | 'away' | 'busy' | 'offline'\n\n// Presence semantic tokens(見 color/semantic.css)——跟 Avatar status dot 共用\nconst STATUS_DOT_COLOR: Record<StatusType, string> = {\n  online: 'var(--status-online)',\n  away: 'var(--status-away)',\n  busy: 'var(--status-busy)',\n  offline: 'var(--status-offline)',\n}\n\nconst STATUS_LABEL: Record<StatusType, string> = {\n  online: 'Online',\n  away: 'Away',\n  busy: 'Busy',\n  offline: 'Offline',\n}\n\n/**\n * NameCard SSOT — 預設 field keys(v11 always-render canonical,2026-05-06)\n *\n * ── 為什麼 SSOT ──\n * User explicit rule:「所有 namecard 預設顯示的資訊都是要一樣完整的」。前 v10 props\n * 全 optional + body conditional render → consumer 漏傳 fields 視覺缺 section,每個範例\n * 各自不一致(同 person 在 DataTable / PeoplePicker / avatar.principles 看起來不同)。\n *\n * v11 canonical:NameCard **always** renders 4 default sections regardless of consumer 是否\n * 傳資料 — 缺 data → 對應 DescriptionItem 顯 `EMPTY_PLACEHOLDER`(\"—\"),section 結構不收合。\n * 視覺結構 SSOT 在此元件,不依賴 consumer。\n *\n * ── 對齊 world-class ──\n * Slack profile card / Linear member card / Notion person card / GitHub user card / Figma user card\n * 都是 fixed schema(role / email / location / department / department / pronouns 等),\n * 不會因為某 user 沒填 phone 整個 phone field 不見 — 缺 = 顯 `Not set` 或留白。\n *\n * ── 為什麼 placeholder 不 hide ──\n * Hide → consumer 不知道少傳 → 視覺漂移;Placeholder → 永遠看到「該欄該有」+ dev-warn 提示\n * consumer 補資料,自動防漂移(M19 ensure-canonical 對齊)。\n */\n// **2026-05-07 v15.7 user directive**:default render 只 `id` + `employeeNumber` 兩個。\n// Email / Phone / Department / Location 等其他 description 一律 opt-in by consumer 透過\n// `fields` array prop。對齊 user 明確「應該確保所有都只有這兩個,因為我並沒有要求你要選其他的」。\nexport const NAMECARD_DEFAULT_FIELD_KEYS = ['id', 'employeeNumber'] as const\ntype NameCardDefaultFieldKey = typeof NAMECARD_DEFAULT_FIELD_KEYS[number]\n\nconst DEFAULT_FIELD_LABEL: Record<NameCardDefaultFieldKey, string> = {\n  id: 'ID',\n  employeeNumber: 'Employee number',\n}\n\nconst FIELD_PLACEHOLDER = '—'\n\nexport interface NameCardProps extends React.HTMLAttributes<HTMLDivElement> {\n  name: string\n  avatar?: AvatarData\n  subtitle?: string\n  status?: StatusType\n  statusMessage?: React.ReactNode\n  actions?: React.ReactNode\n  /**\n   * Consumer 傳的 field 資料(partial)。預設 keys 走 `NAMECARD_DEFAULT_FIELD_KEYS` —\n   * email / phone / department / location 永遠 render(缺資料顯 `—`)。Consumer 想新增\n   * 自訂 field 直接傳入(在 default 之後 append),想 override default key value 也直接傳。\n   */\n  fields?: { label: string; value: React.ReactNode }[]\n  /**\n   * Default field 的真實值。Object key = NAMECARD_DEFAULT_FIELD_KEYS 之一。\n   * 缺 key → render placeholder。Dev mode 會 console.warn 提醒消費者補資料。\n   */\n  defaultFieldValues?: Partial<Record<NameCardDefaultFieldKey, React.ReactNode>>\n  onViewMore?: () => void\n  viewMoreLabel?: string\n}\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst NameCard = React.forwardRef<HTMLDivElement, NameCardProps>(\n  (\n    {\n      name,\n      avatar,\n      subtitle,\n      status,\n      statusMessage,\n      actions,\n      fields,\n      defaultFieldValues,\n      onViewMore,\n      viewMoreLabel = 'View more',\n      className,\n      ...props\n    },\n    ref,\n  ) => {\n    // v11 always-render canonical:default fields 永遠 render(缺資料顯 placeholder),\n    // consumer 自訂 fields 在 default 之後 append。Status section 也永遠 render(無 status\n    // 顯「Status not set」placeholder),統一視覺結構。\n    //\n    // **Dedup canonical(2026-05-07 v15.8 fix Bug E)**:consumer 的 `fields` array 若含\n    // label 撞 default(eg. 「ID」「Employee number」),consumer 值 win — defaults 那一行\n    // 跳過(否則 same label 連 render 兩次,如 default placeholder `—` + consumer 真值)。\n    // 這是遷移期 forgiving 行為:DEV warn 提示應改用 `defaultFieldValues`,但 production\n    // 不破壞既有 consumer。對齊 React `key` 唯一性 + Linear / Slack profile card 一 label\n    // 一 row idiom。\n    const allFields = React.useMemo(() => {\n      const consumerLabels = new Set((fields ?? []).map((f) => f.label))\n      const defaults = NAMECARD_DEFAULT_FIELD_KEYS\n        .map((key) => ({\n          label: DEFAULT_FIELD_LABEL[key],\n          value: defaultFieldValues?.[key] ?? FIELD_PLACEHOLDER,\n        }))\n        .filter((d) => !consumerLabels.has(d.label))\n      return fields && fields.length > 0 ? [...defaults, ...fields] : defaults\n    }, [defaultFieldValues, fields])\n\n    // Dev warn:consumer 透過 `fields` 傳 default key label(legacy pattern)→ 應改 `defaultFieldValues`\n    if (process.env.NODE_ENV !== 'production' && fields) {\n      const legacyEntry = fields.find((f) =>\n        Object.values(DEFAULT_FIELD_LABEL).includes(f.label as string),\n      )\n      if (legacyEntry) {\n        // eslint-disable-next-line no-console\n        console.warn(\n          `[NameCard] \"${name}\":legacy pattern — fields[].label=\"${legacyEntry.label}\" ` +\n          `is a default field. Migrate to defaultFieldValues={{ id, employeeNumber }} prop ` +\n          `to align with NAMECARD_DEFAULT_FIELD_KEYS canonical.`,\n        )\n      }\n    }\n\n    // Dev mode warn:consumer 沒傳 default field 任何 key → 提示補完(避免漂移成 placeholder-only)\n    if (process.env.NODE_ENV !== 'production' && !defaultFieldValues) {\n      // eslint-disable-next-line no-console\n      console.warn(\n        `[NameCard] \"${name}\":no defaultFieldValues passed — sections will render placeholders. ` +\n        `Pass at least { id, employeeNumber } via defaultFieldValues prop. ` +\n        `For other description items (email/phone/department/location etc),use \\`fields\\` prop array.`,\n      )\n    }\n\n    // Layout canonical(2026-04-23):Header + Actions 固定上,Body(status + fields)可捲動,\n    // View more 固定下。**NameCard 自己約束高度**,不依賴 consumer HoverCardContent 設 flex:\n    //   - `max-h-[var(--radix-hover-card-content-available-height,...)]`:HoverCard / Popover\n    //     context 自動繼承 Radix viewport-aware 變數;standalone 落到 100vh fallback\n    //   - 內部 `flex flex-col + overflow-hidden`:Header(shrink-0)+ Body(flex-1 min-h-0 ScrollArea)\n    //     + Footer(shrink-0)三層 chrome\n    // 世界級對照:Slack / Linear / GitHub / Notion hover-profile popover 皆此 chrome pattern。\n    return (\n      <div\n        ref={ref}\n        className={cn(\n          'w-[320px] flex flex-col overflow-hidden',\n          'max-h-[var(--radix-hover-card-content-available-height,var(--radix-popover-content-available-height,100vh))]',\n          className,\n        )}\n        {...props}\n      >\n        {/* ── HEADER(固定): profile + actions ── */}\n        <div className=\"shrink-0 flex flex-col\">\n          <div className=\"flex items-start gap-3 px-4 py-3\">\n            <Avatar\n              src={avatar?.src}\n              alt={avatar?.alt ?? name}\n              color={avatar?.color}\n              size={AVATAR_SIZE}\n              status={status}\n              className=\"shrink-0\"\n            />\n            {/* NameCard typography:label body-lg(16/1.5) + desc body(14/1.5) = reading mode + size=\"lg\"。\n                labelClassName escape hatch 加 font-medium(card context 語意)+ labelTruncate=false 允許 wrap。 */}\n            <ItemContent\n              label={name}\n              description={subtitle}\n              mode=\"reading\"\n              size=\"lg\"\n              labelTruncate={false}\n              labelClassName=\"text-body-lg font-medium text-foreground\"\n              className=\"justify-center\"\n              style={{ minHeight: AVATAR_SIZE }}\n            />\n          </div>\n\n          {/* Action buttons — 均分空間 + 填滿格子(canonical):多個 action 等寬瓜分容器,\n              單一 action 也撐滿容器。`grid grid-flow-col auto-cols-fr` + `[&>*]:w-full`。\n              世界級對照:iOS contact card / macOS contact / LinkedIn profile card 的 action row。 */}\n          {actions && (\n            <div className=\"grid grid-flow-col auto-cols-fr gap-2 px-4 pb-3 [&>*]:w-full\">\n              {actions}\n            </div>\n          )}\n        </div>\n\n        {/* ── BODY(可捲動,v12 status-conditional 2026-05-14):status + fields ──\n            **v12 rule**(per user 拍板「不應該顯示『狀態沒有被設定』,production 每 user 一定有\n            presence state,undefined 頂多是 loading transient 還沒讀到」):status undefined →\n            隱藏整 status badge + status message block(loading 期間 skip),禁 render「Status not\n            set」這種 placeholder(語義錯,user presence 不會「沒設定」)。**NameCard-specific 不外推\n            至 DS 其他元件**(FileItem / DescriptionList / DataTable cell 各自 placeholder 邏輯\n            unrelated)。Fields section 仍 always-render(info schema 性質)。 */}\n        <ScrollArea className=\"flex-1 min-h-0 border-t border-divider\">\n          {/* Status section:`status` defined 才 render(v12 conditional canonical) */}\n          {status && (\n            <div className=\"px-4 py-3 flex flex-col gap-3\">\n              <div className=\"flex items-center gap-2 px-3 py-2 bg-muted rounded-md\">\n                <span\n                  className=\"w-2.5 h-2.5 rounded-full shrink-0\"\n                  style={{ backgroundColor: STATUS_DOT_COLOR[status] }}\n                />\n                <span className=\"text-body\">{STATUS_LABEL[status]}</span>\n              </div>\n              {/* Status message — 只在 status defined 才 render(語意配對:status badge + status\n                  message 是一組;沒 status 就沒 status message)。缺 statusMessage 顯 placeholder。 */}\n              <DescriptionList>\n                <DescriptionItem label=\"Status message\">\n                  {statusMessage ?? <span className=\"text-fg-muted\">{FIELD_PLACEHOLDER}</span>}\n                </DescriptionItem>\n              </DescriptionList>\n            </div>\n          )}\n\n          {/* Fields section:status defined 才有 border-t separator;無 status section 時去除 border-t(因 ScrollArea 起點已有上方 border-t,不重疊) */}\n          <div className={cn('px-4 py-3', status && 'border-t border-divider')}>\n            <DescriptionList cols={2}>\n              {allFields.map((f) => (\n                <DescriptionItem key={f.label} label={f.label}>\n                  {f.value === FIELD_PLACEHOLDER\n                    ? <span className=\"text-fg-muted\">{FIELD_PLACEHOLDER}</span>\n                    : f.value}\n                </DescriptionItem>\n              ))}\n            </DescriptionList>\n          </div>\n        </ScrollArea>\n\n        {/* ── FOOTER(固定): View more,py-3 canonical(12px,比一般 link 按鈕多呼吸) ── */}\n        {onViewMore && (\n          <div className=\"shrink-0 border-t border-divider px-4 py-3\">\n            <Button variant=\"link\" size=\"sm\" onClick={onViewMore} className=\"w-full\">{viewMoreLabel}</Button>\n          </div>\n        )}\n      </div>\n    )\n  },\n)\nNameCard.displayName = 'NameCard'\n\n// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)\n// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs\nexport const nameCardMeta = {\n  component: 'NameCard',\n  family: null, // non-family composite / overlay / layout\n  variants: {\n\n  },\n  sizes: {\n\n  },\n  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],\n  tokens: {\n    bg: ['bg-muted'],\n    fg: ['text-foreground'],\n    ring: [],\n  },\n} as const\n\nexport { NameCard }\n"],"names":[],"mappings":"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"}