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

package/src/patterns/element-anatomy/element-anatomy.spec.md

@@ -0,0 +1,217 @@
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Element Anatomy 設計原則(4-Family Model Taxonomy)
+
+本檔是 design system 中 **element-level 結構分類系統**的頂層 governance doc——跨 pattern / cross-component。每個元件 spec 第一段**必須聲明 Layout Family**(1/2/3/4 或「非 family,self-contained / composite」)。
+
+**為什麼住 `patterns/element-anatomy/` 而非 DS 根目錄**:taxonomy 橫跨 patterns + components 兩個家:
+- Family 1+2(row 結構)→ runtime primitive 在同 folder `item-anatomy.{spec.md, tsx, stories.tsx}`
+- Family 3(pill 結構)→ SSOT pointer 到 `components/Button/button.spec.md`
+- Family 4(field control 結構)→ SSOT pointer 到 `components/Field/field-controls.spec.md`
+
+Taxonomy 跟 F1+F2 runtime primitive **co-locate 在同 folder** 是 `packages/design-system/src/README.md` L17 的 home governance 決策:**「即使跨 pattern 的 taxonomy(如 4-Family Model)也住在最相關的 pattern topic 資料夾內,folder = topic home,不需要頂層 flat 檔案」**。co-location 讓新 element 查 taxonomy 時,runtime primitive 就在隔壁,查閱效率最高。
+
+**與「layout」命名分家**:「anatomy」= element-level 結構分類;「layout」= page-level 版面(未來頁面設計原則的家)。世界級 DS 一致如此(Material Foundations > Layout = page grid / Polaris / Atlassian / Carbon 皆然)。
+
+---
+
+## 4 個可繼承的 Layout Family
+
+| Family | 用途 | 結構 | Sizes baseline | SSOT |
+|--------|------|------|----------------|------|
+| **1. Menu item anatomy** | Menu 容器內的掃視單列(scanning mode)| `[small icon/avatar 16-20px] [content: label 單行 + desc 選用] [small suffix]`, tight density, leading-compact | **sm / md / lg** | `patterns/element-anatomy/item-anatomy.spec.md`「Family 1: Menu item」章節 |
+| **2. List item anatomy** | 頁面上的閱讀式單列(reading mode)| `[larger icon/avatar 20-24px] [content: label + multi-line desc OK] [suffix action/button/counter]`, looser density, reading typography | **sm / md / lg** | `patterns/element-anatomy/item-anatomy.spec.md`「Family 2: List item」章節 |
+| **3. Pill anatomy** | 單行互動 pill(action trigger / data indicator)| `[startIcon?] [<span px-1>label</span>] [suffix badge/endIcon/dismiss]`, single-line, whitespace-nowrap | **sm / md / lg + 可選 xs** | `components/Button/button.spec.md`「Pill Layout」章節 |
+| **4. Field control anatomy** | 可編輯資料輸入(單行為主,Textarea 多行 variant) | `fieldWrapperStyles + [startIcon?] [<editable content>] [endAction?]`, **視覺對齊 Family 1** | **sm / md / lg** | `components/Field/field-controls.spec.md` |
+
+---
+
+## 尺寸 baseline 與合法偏離
+
+每個 Family 有明文 baseline sizes。消費元件**必須**實作 baseline,除非有合理理由偏離——偏離必須在元件 spec 明文記錄。
+
+| 偏離類型 | 範例 | 合理理由 |
+|---------|------|---------|
+| **單一固定 size** | Chip (`h-field-sm`) / Notice / Alert / Toast | 世界級共識(Material 3 filter chips / Material Banner):此類元件不需密度選擇 | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+| **Alias** | Tag lg=md=24px | 子元件補齊(discrete tier):consumer 傳 size 不 break,視覺等同 |
+| **Mode 取代 Size** | FileItem(`compact` / `rich`) | **結構變體**非密度變體——用 size 會誤導 |
+| **額外 xs**(Family 3 only) | Button / SegmentedControl xs | icon-only toolbar utility(24px 固定 不配對 Field) |
+
+違反但無理由 = 設計 bug,必須改 code 或補 spec 理由。
+
+---
+
+## Family 3 兩個 sub-profile(重要)
+
+同結構、不同 role、不同 padding / typography:
+
+| Sub-profile | 成員 | Padding | Typography | Cursor | 為什麼 |
+|-------------|------|---------|-----------|--------|------|
+| **Action trigger** | Button / SegmentedControl / Chip | 較鬆(xs=`px-2`, sm+=`px-3`) | 對應 size 的 font-medium | pointer | 需命中區 + 視覺重量搶點擊焦點 |
+| **Data indicator** | Tag | 較緊(`px-1` 所有 size) | font-normal | text | Passive 讀取,不搶焦點 |
+
+---
+
+## Size Pairing 規則(跨 Family)
+
+| Pairing | 意義 |
+|---------|------|
+| Tag md ↔ Field md / Tag sm ↔ Field sm | Tag 的 size 對應同名 Field size,視覺對齊 form 內字級 |
+| Button sm/md/lg ↔ Field sm/md/lg | Button 配對 Field 時 size 同名 |
+| Button xs = 獨立 utility | 不配對 Field,用於 toolbar compact button |
+| Family 4 視覺對齊 Family 1 | 讓 Select trigger + dropdown options 視覺連續 |
+
+---
+
+## Consumers 快速查
+
+| Family | Canonical | Consumers |
+|--------|-----------|-----------|
+| 1 Menu item | `MenuItem`(from `item-anatomy`) | `TreeItem`, `SidebarMenuButton`, `DropdownMenuItem`(重用 MenuItem), `SelectMenu` 內部 |
+| 2 List item | (無單一 canonical) | `StepItem`(例外:indicator 對齊), `FileItem`(icon 作邊界), `Notice` → `Alert/Toast`(視覺一致非語意), `SelectionItem` variant → `RadioGroup` / `Checkbox` group |
+| 3 Pill | `Button` | `SegmentedControlItem`, `Chip`, `Tag`(data indicator sub-profile) |
+| 4 Field control | `Input`(field-controls SSOT) | `NumberInput`, `DatePicker`, `Select`, `Combobox`, `LinkInput`, `PeoplePicker`, `Textarea`(multi-line variant) |
+
+---
+
+## 不進 Family Model 的元件
+
+不能舉一反三的不分類。**Composite 類再細分三子類**,因為三類的設計約束不同:
+
+### Self-contained primitive(獨立視覺 atom,無 slot 結構)
+
+Switch / Checkbox / Radio / Avatar / Badge / CircularProgress / ProgressBar / Skeleton / Separator
+
+各自獨立視覺,spec 直接描述自己結構。
+
+### Overlay-composite(浮層 composite,消費 overlay-surface pattern)
+
+Dialog / Sheet / Popover / Tooltip / HoverCard / Coachmark / Command / SelectMenu / DropdownMenu
+
+**共同約束**:
+- 結構化 chrome 浮層(Dialog / Sheet / Popover;Coachmark 經 `PopoverHeader`)消費 `patterns/overlay-surface/` 的 `SurfaceHeader` / `SurfaceBody` / `SurfaceFooter`(padding SSOT;實際 consumer 名單見 `overlay-surface.spec.md`「Consumers」)。menu 形浮層(Command / SelectMenu / DropdownMenu)走自有 menu surface canonical(`floatingLayerClass` + `py-2`);Tooltip(純文字 surface)與 HoverCard(behavior primitive,內容由 consumer 排)不消費 Surface*(2026-05-18 M18 anchor)
+- elevation 走 `--elevation-200`+ 的 overlay layer
+- dismiss 走 `onClose`(語意:關閉 overlay session,見 CLAUDE.md 命名 canonical)
+- 部分 overlay 有 modal vs non-modal 分流(Dialog / Sheet modal;Popover / HoverCard non-modal)
+- 在 dark-mode context(如 FileViewer chrome)中需支援 `data-theme="dark"` 子樹
+
+### Page-composite(頁面內 composite,無 overlay 性質)
+
+Tabs / Accordion / DataTable / Calendar / Carousel / Breadcrumb / Sidebar / ProfileCard / FileItem / FileUpload / FileViewer / OverflowIndicator
+
+**共同約束**:
+- 消費多個 row primitive 或 self-contained primitive
+- 不走 overlay-surface(沒有 elevation / dismiss)
+- 佈局 token 用 `--layout-space-*`(chrome / section)
+- 各自 own 內部 layout SSOT(例:DataTable 的 header row、Calendar 的 grid、Carousel 的 track + arrow)
+
+### Pure-wrapper(純行為 wrapper,無自己視覺)
+
+CheckboxGroup / RadioGroup / FieldGroup(若建)
+
+**共同約束**:
+- 自己**無視覺 chrome**(無 bg / border / radius)——僅渲染 `role="group"` layout 容器 + 提供 context(`CheckboxGroupContext` 等)給 descendant 同步 state;視覺由 descendant(Checkbox / RadioGroupItem / SelectionItem)承載
+- RadioGroup 註記:兼任 Field 家族「承載欄位值的互動控件」(見 `field-controls.spec.md`「哪些元件吃 `<Field disabled>` cascade」),有 display / empty mode 內容渲染,其 anatomy story 因此含 ColorMatrix / SizeMatrix
+- spec 應明文「本元件無自有視覺 chrome」;純 wrapper 的 anatomy story 最小集 = `Overview` + `Inspector`
+
+---
+
+### 判斷新 composite 時的流程
+
+寫新 composite spec 時先自問:
+1. 這是浮層(elevation / Portal / dismiss session)嗎? → **Overlay-composite**
+2. 這是頁面內多區塊 layout 嗎? → **Page-composite**
+3. 這本身無視覺、只是 context / state wrapper 嗎? → **Pure-wrapper**
+
+三題全否 → 應該是 Family 1/2/3/4 或 Self-contained primitive,而不是 composite。
+
+---
+
+## 允許的跨 Family 視覺對齊
+
+Family 4 的 Input / Select 視覺對齊 Family 1 的 menu-item(高度、字體、icon size)——但兩個 family **各自 own SSOT**。這是「視覺對齊」非「結構繼承」。
+
+---
+
+## Field Composition(不在 family 但相關)
+
+`components/Field/field.spec.md` 描述 **form field composition pattern**——Field 容器如何包 Family 4 control + label + help。不同 scope 的 pattern(composition 非 element anatomy),不列入 4-Family。
+
+---
+
+## 新元件判斷流程
+
+1. **垂直列表裡?** → Family 1(menu 容器)/ Family 2(頁面)——分界看「容器 + 閱讀模式」:浮層 menu 內掃視選擇 = Family 1(scanning),頁面上閱讀內容 = Family 2(reading);深度規格詳 `item-anatomy.spec.md` Family 1 / Family 2 章節
+2. **單行可點擊 / 可讀的 pill?** → Family 3(action trigger or data indicator)
+3. **單行可編輯資料?** → Family 4(必須視覺對齊 Family 1)
+4. **都不是?** → **停下討論**——新 family 還是 self-contained
+
+CLAUDE.md `# 4-Family Layout Model` 留概要 + 判斷流程(每 session signal)。本檔 own 完整 taxonomy + Family 3 sub-profile + size pairing + consumers + exclusions。
+
+---
+
+## 視覺容器 breathing invariant(DS-wide canonical · 2026-04-22)
+
+**規則**(rule · 必遵守):
+
+> 任何**有明確視覺邊界的容器**(permanent `bg-*` / `border` / `shadow-*` 三者任一),**必有 inner padding**,不讓內容物(含 standalone card、pill、row、text 等任何 children)觸容器邊。
+
+**責任層**:**父容器(chrome)** — 子元件 `w-full` responsive 不變。
+
+**為什麼責任在父容器**:
+- 子元件不知道自己會住在哪個 chrome → 硬綁 max-w / margin 會破壞 responsive
+- 父容器知道自己的視覺 policy(bg/border/shadow 都是它的決策)→ 天然 SSOT
+- 子元件統一 `w-full` 扣掉父 padding 自動有 breathing
+
+**建議值**(guide · 非 strict):
+
+| Chrome 類型 | 建議 inner padding | 範例 |
+|------------|------------------|------|
+| 一般 chrome(Dialog / Sheet / Popover / Card body) | `--layout-space-loose`(16/24)/`--layout-space-tight`(12/16) | SurfaceBody 已 own canonical |
+| 側邊 chrome(Sidebar / Drawer section) | `--layout-space-tight` 到 `--layout-space-loose` | 視深度 |
+| Inline pill(Badge / Chip / Tag) | `px-1` / `px-2` | 對齊元件 size |
+| Form field control wrapper | `px-3`(固定,對齊 Field family)| fieldWrapperStyles |
+
+Consumer 自建 chrome-like div 帶 bg/border/shadow 時,參考上表或就近取 `--layout-space-*` token。**具體值允許偏離,但 breathing 本身必存在**。
+
+**世界級對照**(DS-wide 共識): <!-- @benchmark-unverified -->
+- Material Design 3:`<mat-card-content>` 16dp / `<mat-dialog-content>` 24dp / Drawer section padding
+- Polaris(Shopify):`<Page>` 16-20px / `<Card>` 16-20px / `<Modal>` 20px
+- Atlassian:`<Box padding="space.200">` / `<ModalBody>` 24px / Drawer body padding
+- Ant Design:`<Modal.Body>` 24px / `<Card.Meta>` inner padding
+- Apple HIG:Inset Grouped list group 16pt inset / Card 內容 16pt
+- Carbon(IBM):Tile / Modal 內容 16-32px padding
+
+無反例 — 6 家一致在 chrome 層提供 inner padding 當 SSOT。
+
+**反例(破圖)**:
+- Consumer 自建 `<div className="bg-surface-raised rounded-lg">{rich FileItem list}</div>` **無 padding** → rich card w-full 貼父 div 邊,card rounded 貼父 rounded 視覺「卡在一起」
+- Consumer 自建 `<div className="border rounded-md">{text}</div>` 無 padding → text 貼 border 邊,看似斷字
+- Chrome primitive 被 override 拿掉 padding(`<SheetBody className="p-0">`)後塞 card 元件 → 同上
+
+**Enforcement**:
+- Chrome primitive(SurfaceHeader / SurfaceBody / SurfaceFooter / Input wrapper / Field wrapper)**已 own canonical padding**,繼續守 SSOT
+- Consumer 自建的有視覺邊界 div → hook `check_container_breathing.sh` warn(grep `bg-*|border|shadow-*` 無 `p*-`)
+- Audit dim 新增:「consumer 自建 chrome 是否有 inner padding」
+
+**與既有規則的關係**:
+- `overlay-surface.spec.md` 「M11 state walk hover 檢查(三 invariant 必同時 ✓)」第 3 條(content 在 hover bg 內 breathing)= 本規則的**應用層 instance**(hover bg 也算「permanent」在該 state 內),非獨立規則
+- `.claude/rules/ui-development.md`「Padding source 分層規則」定 **padding 來源**(token / Tailwind / calc);本規則定 **padding 是否存在**(是 invariant)
+
+---
+
+## 相關
+
+- `patterns/element-anatomy/item-anatomy.spec.md` — Family 1+2 row anatomy deep SSOT + runtime primitive(`<MenuItem>` canonical + `<ItemIcon>` / `<ItemAvatar>` / `<ItemLabel>` / `<ItemSuffix>` / `<ItemInlineAction>` slot components)
+- `components/Button/button.spec.md` — Family 3 Pill anatomy SSOT
+- `components/Field/field-controls.spec.md` — Family 4 Field control anatomy SSOT
+- CLAUDE.md `# 4-Family Layout Model` — 每 session signal 的概要 + judgment flow
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `calendar.spec.md`
+- `field.spec.md`
+- `item-anatomy.spec.md`
+- `time-picker.spec.md`

package/src/patterns/element-anatomy/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './item-anatomy'

package/src/patterns/element-anatomy/inline-action.spec.md

@@ -0,0 +1,320 @@
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — verified 0 world-class DS claim in body; blanket retract removed. -->
+
+# Inline Action 設計原則(SSOT)
+
+**Layout Family**:non-family(hosted inline element,無 own layout — 由宿主 family 1/4 提供)。
+
+**定位**:嵌入在其他元件內部的互動觸發點(Tag dismiss / Field endAction / Row suffix action)。不是獨立 Button,由宿主元件渲染 + 控制。
+
+**本 spec 是 Inline Action 的獨立 SSOT**(2026-04-24 從 `item-anatomy.spec.md` 抽出,避免單一 spec 過長)。Row primitive 結構走 `item-anatomy.spec.md`;本 spec 含「確定用 Inline Action」後的完整視覺 / API / predicate / same-row consistency 規格。
+
+### 視覺規則
+
+1. **Icon 視覺尺寸跟隨宿主 tier**，排版以 icon 為準
+2. **平時透明**，視覺上等同靜態 icon
+3. **Hover 時顯示背景色區域**，提示可點擊。背景色區域 = icon + 2px（直徑，即每邊 +1px），不影響排版（用 absolute positioning 或 negative margin 溢出）
+
+### 互動狀態
+
+與 Button text variant 一致：
+
+| 狀態 | 背景 | 過渡 |
+|---|---|---|
+| 預設 | transparent | — |
+| hover | `bg-neutral-hover` | transition-colors |
+| active(mouse down) | `bg-neutral-active` | transition-colors |
+| **overlay 開啟**(`data-state=open`)| **同 host hover**(該元件 hover 什麼樣就維持) | transition-colors |
+| focus-visible | `outline: 2px solid var(--ring)` | — |
+| 宿主 disabled | 不渲染 inline action | — |
+
+**Overlay trigger canonical**(2026-04-29 訂 / 2026-05-02 改 / 2026-05-05 prop 化):trigger 透過 `asChild` 作 DropdownMenu / Popover / Tooltip / HoverCard trigger 時,Radix 自動 set `data-state="open"`,**trigger 維持 host hover 樣式**直到浮層關閉。對齊**狀態極簡派**(shadcn / Radix Themes / Material — 不另開 4th token);避免 state 增生 + 跨 host(neutral / colored)規則同步。
+
+**2026-05-05 修正:overlay vs in-place 語意分離**。`Radix Collapsible.Trigger` 也 emit 同 `data-state="open"`,但語意完全不同(展開內容**接在下方非 floating**,user 不需追溯)。原 `ItemInlineActionButton` 將規則**無條件**套用於所有 `data-state=open`,造成 Sidebar collapsible group label 的 chevron 展開時殘留 hover bg(2026-05-05 user reported)。修正:`ItemInlineActionButton` 加 `overlayTrigger?: boolean` prop,**default `false`**。consumer 顯式宣告:
+
+| Consumer 場景 | `overlayTrigger` |
+|---|---|
+| `<DropdownMenuTrigger asChild>` / `<PopoverTrigger asChild>` / `<TooltipTrigger asChild>` / `<HoverCardTrigger asChild>` | `true`(opt-in) |
+| `<CollapsiblePrimitive.Trigger asChild>` | `false`(default) |
+| 純 onClick handler / drag handle / dismiss X | `false`(default) |
+
+落實同源:`fieldWrapperStyles data-[state=open]:border-border-hover` 對 Combobox/DatePicker overlay trigger 仍正確(這些只用於 overlay 包覆)。Button 變體的 `data-[state=open]` 規則目前**未 prop 化**(latent — Button 從未被當 `Collapsible.Trigger` asChild 包覆,故無 active bug);若未來出現 Button 包覆 Collapsible 場景,同 prop 化處理。
+
+### Icon 色彩（按 host 分兩類,2026-04-21 D6 矛盾解）
+
+Inline action icon 色彩規則 **依 host 是否有自帶色彩分兩支**。共同精神:inline action 視覺融入 host — neutral host 的融入方式是「退到 muted」,colored host 的融入方式是「接收 host 色」。
+
+**預設（neutral host）**:預設 `fg-muted`,hover / active 時變 `foreground`
+- 適用:Field endAction（Input clear button）/ TreeItem inline action / Menu inline action / DropdownMenu trigger inline action 等 **neutral 容器內**的 inline action
+- 語意:utility icon 是輔助操作,預設退到背景,hover 時提示可操作
+
+**例外（colored host）**:**繼承 host 文字色**（非 `fg-muted`）
+- 適用:**Tag dismiss** / 未來任何 **宿主自帶 branded / categorical 色彩** 的 inline action
+- 語意:宿主 bg 有色（Tag subtle blue 底 + blue-text 文字）,inline action icon 用 `fg-muted` 會視覺不連貫（視覺斷裂 / 顏色不連貫）;繼承 host 文字色維持「一個整體視覺單元」
+- Hover / active 背景:跟 host 同色系的 hover / active token（例 Tag solid blue dismiss → `--blue-hover`）
+
+**判斷法**:宿主 bg 是 surface / transparent（neutral）→ 走預設;宿主有 branded / categorical 色彩 → 走 colored host 例外。
+
+**現況清單**:
+| Host | 規則分類 | Icon 色 |
+|------|---------|--------|
+| Field / Input / NumberInput / DatePicker / Combobox endAction | neutral host | `fg-muted` → `foreground` |
+| TreeItem / Menu / DropdownMenu inline action | neutral host | `fg-muted` → `foreground` |
+| Tag dismiss | colored host | 繼承 Tag 文字色 |
+
+### 尺寸對照
+
+| 宿主 | Icon 視覺 | Hover 背景 | 圓角 | 排版佔位 |
+|---|---|---|---|---|
+| Tag sm (20px) | 16px | 18px | rounded-md | 16px |
+| Tag md/lg (24px) | 16px | 18px | rounded-md | 16px |
+| Field sm/md | 16px | 18px | rounded-md | 16px |
+| Field lg | 20px | 22px | rounded-md | 20px |
+| TreeItem sm/md | 16px | 18px | rounded-md | 16px |
+| TreeItem lg | 20px | 22px | rounded-md | 20px |
+| Panel list row(visibility / sort / filter panels)| 16px | 18px | rounded-md | 16px |
+
+**Consumer wrapping rule**:當 consumer 包 `ItemInlineActionButton` 在 reserve slot(如 hover-reveal opacity wrapper),**reserve 寬度 = 排版佔位**(sm/md=16,lg=20),**禁止自訂為 24 / 28**(過大會在 cell 留 phantom space)。歷史:DataTable header reserve 24 → 16 修正(2026-04-29)。
+
+### 多個 Inline Action 並排
+
+當一個宿主有多個 inline action(如 Select 的 clear X + ChevronDown,或 TreeItem 的 ⋯ + ＋)時:
+
+- **間距**:`gap-2`(8px)——跟 fieldWrapperStyles 的元素間距一致(Select 的 clear X 和 ChevronDown 就是 gap-2)
+- **對齊**:全部垂直置中在同一行(`flex items-center`)
+- **出現時機**:全部一起出現(TreeItem 的 hover-reveal 是同時淡入所有 action,不逐個)
+
+### API 設計
+
+Inline action 由宿主元件渲染，消費者只需宣告 intent：
+
+```tsx
+// ❌ 舊：消費者自行決定 Button size、icon size
+<Input endAction={<Button size="xs" iconOnly startIcon={X} aria-label="清除" onClick={...} />} />
+
+// ✅ 新：宣告式，Field 自己根據 size tier 渲染
+<Input endAction={{ icon: X, label: '清除', onClick: handleClear }} />
+```
+
+Field 內部根據自己的 size 決定 icon 尺寸、hover 背景大小、視覺層級。消費者不需要知道這些。
+
+### 實作要求
+
+- 必須是 `<button>` 元素，不是 `<span>` + onClick
+- 必須有 `aria-label`
+- 必須有 `cursor-pointer`——可點擊的元素必須有明確的游標指引
+- 必須有 Tooltip（`label` 欄位同時作為 `aria-label` 和 tooltip 內容）——icon-only 控件沒有可見文字，tooltip 是使用者理解功能的唯一視覺提示
+- 宿主 disabled 時不渲染（不可操作就不該暗示可以操作）
+
+### Predicate:Inline Action vs Button iconOnly(canonical)
+
+DS 跨元件 icon action primitive 的 canonical。接到 icon 相關決策,跑下面決策樹。
+
+#### 三種 icon primitive 的身份
+
+| Primitive | 定義 | 實作 |
+|-----------|------|------|
+| **Decorative indicator** | 純視覺提示(點了不做事,host 是 click target)| Host 內 `<Icon aria-hidden pointer-events-none />` |
+| **Inline Action** | **可點擊的 icon**,embedded 在 host 內部(content flow / chrome padding)| `ItemInlineAction` / `ItemInlineActionButton`(詳下方 API 區)|
+| **Button** | **獨立按鈕**,有 chrome,可參與 action group | `<Button iconOnly />`(詳 button.spec.md)|
+
+#### 決策樹(3 步)
+
+```
+Q1. icon 點了要做事嗎?
+    ├─ 否 → Decorative indicator(host 內 <Icon aria-hidden />,本 spec 不討論)
+    └─ 是 ↓
+Q2. 位置在哪?
+    ├─ Host 內部(chrome padding / content flow / row inline suffix)→ Inline Action
+    ├─ Row 獨立 action slot(跟 content 視覺分開,有獨立 column/分隔線)→ 看 Q3
+    └─ Action group region(toolbar / chrome corner / standalone)→ Button
+Q3. Row 多大?
+    ├─ ≤ 24(compact / xs row)→ Inline Action(Button xs 24 填滿 row,無呼吸)
+    └─ ≥ 28(sm/md/lg row)→ Button iconOnly xs(固定 24,不隨 row 放大)
+```
+
+#### Row action 絕對值 cap(核心原則)
+
+**Row dedicated action 永遠 ≤ 24px**,不隨 row tier 放大。超過 24 action 會搶 content 視覺焦點,違反「資料 > 行動」的視覺階層。
+
+**世界級對照**:Material DataGrid / Polaris ResourceList / Atlassian Table / Ant Design Table / Apple HIG — **全部固定小尺寸 icon button**,不依 row height 放大 action。
+
+#### 3 條關鍵補充
+
+1. **Inline Action 不參與 action group 規則** — 沒有 Button 的 variant chrome / Separator 分群 / size 對稱要求;只是 host 內部 tap target
+2. **Button 必對齊 action group 規則** — 同 size、Separator 分群(詳 `patterns/action-bar.spec.md`)
+3. **Dismiss X(close)特殊弱化** — Inline Action default 已 `fg-muted`;Button 需加 `dismiss` prop 才 override(詳本 spec 下方 dismiss 節)
+
+#### Real case 表(所有 DS 用法一覽)
+
+| Host | Context | Primitive | Why |
+|------|---------|-----------|-----|
+| Input / NumberInput / Combobox clear X | Field chrome padding | Inline Action | Embedded |
+| Tag dismiss X | Pill body | Inline Action(colored host 繼承色)| Embedded |
+| Menu / TreeView / SidebarMenuButton / SelectionItem suffix | Row inline flow | Inline Action | Inline with content |
+| SidebarGroup header chevron | Aux toggle | Inline Action | Inline header toggle |
+| Select ChevronDown / DatePicker Calendar / Combobox ChevronDown | Field chrome(裝飾)| **Decorative**(不是 action)| Click falls through;host 是 trigger |
+| **FileItem compact**(row 24)| Row slot | Button xs iconOnly(`var(--field-height-xs)` 容器 + data-unbounded 收斂到 1lh)| 2026-04-23 user 統一 rich + compact 同 primitive,不撐高 row(見 file-item.tsx 註解)|
+| **FileItem rich**(row 56 sm/md rich)| Row slot | Button xs iconOnly(24 固定)| ≤ 24 cap,不放大 |
+| **DataTable header cell internal**(sort indicator / ⌄ menu / filter funnel / pin)| Header cell host internal | **Inline Action**(`ItemInlineActionButton` asChild for DropdownMenu)| Embedded inline,跟 label 一體 |
+| **DataTable body cell internal**(display endAction / clear / edit indicator)| Cell content host internal | **Inline Action**(自動繼承 Field family endAction)| Field display 元件已對齊 |
+| **DataTable row dedicated action column**(編輯 / 刪除 / 更多 ⋯)| Row dedicated column | Button xs iconOnly(24 固定)| ≤ 24 cap;有獨立 column divider 視覺分離 |
+| **Breadcrumb 中段折疊 ⋯**(`BreadcrumbEllipsis`)| BreadcrumbList row inline flow(host 內)| **Inline Action**(`ItemInlineActionButton` `size="md"` + `overlayTrigger` + asChild for DropdownMenuTrigger)| Embedded inline,跟 BreadcrumbLink 同 row;14-16px text row(compact tier);click 展開 DropdownMenu(2026-05-10 重寫,自刻 button retired)|
+| **Dialog / Sheet / Popover / Alert corner close** | Chrome corner | Button iconOnly `dismiss`(size sm)| Action group region |
+| **Toolbar commands**(FileViewer zoom / editor bold)| Toolbar | Button iconOnly(md 常見)| Action group region |
+| FileViewer / rich text editor formatting group | Toolbar action group | Button iconOnly 同 size + Separator | Action group 完整範例 |
+
+#### Content-role vs action-role 分層(附補充原理)
+
+Row 內元件分兩類,**size 規則不同**:
+- **Content-role**(display 資料):`<Input mode="display">` / Badge / Avatar / Tag → size 對應 row tier(sm row → sm)
+- **Action-role**(互動觸發):row action icon → **固定 ≤ 24**,不參與 content size-pair
+
+Row action 的 affordance 是「次要功能」,不是 primary CTA。Button chrome 過度強調;用 **Button xs 24 固定** 提供 command affordance 但不侵蝕 content hierarchy。
+
+### Same-row consistency rule(防混用)
+
+**同一 row 所有 icon action 必同一類**(不混 Inline Action + Button)— 消除 box size 不一致造成 gap 斷裂(InlineAction 16+18 vs Button text sm 28)。
+
+**範例(panel list row 內 inline action)**:
+```
+✅ DataTable column visibility row(panel list):
+[⋮⋮ drag] [label] [👁️ toggle]   ← 全 ItemInlineActionButton size=md(16+18 hover bg)
+
+❌ 混用 anti-pattern:
+[⋮⋮ ItemInlineActionButton] [label] [Button text sm Eye 28x28]  ← box size 不一致 gap 斷裂
+```
+
+**chrome corner action group(Alert / Toast / Dialog / Popover header corner)** 屬 **Button family**(action group region,不是 inline action)。Canonical 不在本 spec — 詳:
+- 尺寸:`patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」(overlay sm + v5 trick / banner xs explicit)
+- variant / divider:`patterns/action-bar/action-bar.spec.md`(corner action group)
+
+### 邊界案例
+
+- **帶可見文字 label 的觸發**:不是 Inline Action — Inline Action 必 icon-only(label 走 tooltip + `aria-label`,見「實作要求」);需要可見文字 → `Button`(text / tertiary)。
+- **Dark mode**:hover / active / fg 全走 semantic token(`--neutral-hover` 等)自動 adapt,Inline Action 不 own dark token;colored host 的繼承色由 host token 處理(見 `tag.spec.md`)。
+
+### Inline action 共用元件(`ItemInlineAction` / `ItemSuffix`)
+
+Canonical 實作於 `item-anatomy.tsx`,匯出 `ItemInlineAction` / `ItemSuffix`(從 `RowSizeContext` 自動查 icon size / hover bg / tooltip / aria-label / fg-muted → foreground 全內建)。
+
+```tsx
+// 單一 action
+<ItemInlineAction action={{ icon: X, label: '清除', onClick: handleClear }} />
+// 多個 + hover-reveal
+<ItemSuffix hoverReveal>{actions.map((a) => <ItemInlineAction action={a} />)}</ItemSuffix>
+```
+
+**Host 走宣告式 API**(`inlineActions?: InlineActionConfig[]` / `endAction?: InlineActionConfig` prop)— 不自刻 button JSX。已遷移:`SidebarMenuButton` / `Input` / `NumberInput`(2026-05-31 infra-audit 修 stale status:verify input.tsx/number-input.tsx 已用 endAction InlineActionConfig)、`Tag`(2026-05-01:宣告式 `onRemove` + 內部 `ItemInlineActionButton`,見 tag.tsx)。`LinkInput` / `Combobox` 屬下方「不適用清單」(右側 chrome 獨佔),內建 inline action 已直接消費 `ItemInlineAction` primitive——無 pending。
+
+### Dismiss canonical — X close only
+
+**Dismiss 語意嚴格定義**:「**關閉 surface / 忽略訊息**」— **只屬 X(close)icon**。
+
+**不是 dismiss 的情境**(常被誤判):
+- Trash / Delete / Remove — destructive action(破壞性移除),不是 dismiss
+- Clear — 欄位清空(value 設 empty,元件本身不關),不是 dismiss
+- 以上三者**禁止套 dismiss 弱化**
+
+**世界級對照**:
+- Dismiss:Material `IconButton` close / Polaris `Banner.onDismiss` / Ant Design `Alert.closable` / Apple HIG window close → 一律 icon = `X`
+- Destructive:Material `IconButton` Delete(red)/ Polaris `Button destructive` / 我們的 row Trash → 一般 primitive(無 dismiss 弱化)
+
+#### Dismiss X 的實作(按 position 決定)
+
+| 位置 | 實作 | 視覺弱化 |
+|------|------|---------|
+| Chrome corner(Dialog / Sheet / Popover / Alert / Toast / Coachmark 右上 X)| **Button iconOnly + `dismiss` prop**(Cat 3)| `dismiss` prop 套 fg-muted override |
+| Host chrome padding 內(Input clear X / Tag 內 X)| **Inline Action**(Cat 1)| default 已 fg-muted(內建)|
+| 獨立 standalone close(罕見)| **Button iconOnly + `dismiss` prop**(Cat 3)| `dismiss` prop 套 fg-muted override |
+
+#### `dismiss` prop 觸發條件(Button 限定)
+
+**明示**:`<Button dismiss />`(唯一機械觸發;Button 無 `onClose` / `onDismiss` prop)→ 觸發弱化 override(icon fg-muted → hover foreground;variant 強制 text)。語意判準:點擊語意 = X close 才用 dismiss
+
+**不觸發**:callback = `onRemove`(collection 操作)/ `onClear`(欄位清空)/ `onDelete` — 這些不是 dismiss 語意,Button 用對應 variant 即可
+
+#### Colored host 例外(Tag 內 X)
+
+Tag solid / branded color variant(`red / blue / orange`)→ Tag 內 X **繼承 host 文字色**(非 fg-muted),hover bg 配色相。詳「Icon 色彩原則」段。
+
+#### ❌ 禁止
+
+- 帶文字 label 的 Button 作 dismiss(「關閉」字按鈕)— 雙重 affordance
+- 自刻 `<button><X /></button>` — 繞過 `ItemInlineAction` / Button `dismiss` 的 a11y + 尺寸自動化
+- **Trash / Clear / Delete 套 `dismiss` prop** — 語意誤用,destructive 本身已有破壞性意涵不需再弱化
+- Button dismiss 用 `variant="primary/secondary/tertiary"` — `dismiss` prop 強制 `variant="text"`
+- Chrome corner close 用 Inline Action — corner 屬 action group region,必用 Button
+
+#### 第三方 managed 不是例外
+
+sonner toast auto-dismiss / Radix Dialog `DialogClose` wiring — 第三方只管 state logic(何時關),**我們渲染的視覺按鈕必套對應 canonical**(chrome corner → Button dismiss;chrome padding → Inline Action)。
+
+hook `check_story_invariants.sh` R1(原 `check_story_anatomy.sh` 規則 B,已 folded)已在 stories 層攔 label Button 作 dismiss。
+
+---
+
+## Escape hatch — config 表達不出時的 10% case
+
+**90% case 走 `InlineActionConfig` 宣告式 API**(host 根據 size tier 自動渲染 — 視覺一致 / a11y 內建 / drift 杜絕)。
+
+少數 config 結構表達不出的場景:
+- 自訂 popover trigger(DropdownMenuTrigger asChild + 自家 anchor)
+- 多 tier 動作(stepper button group / 多個 chevron)
+- 跟 host 自帶 chrome 互動的元素(如 Combobox 的 ChevronDown 不屬 endAction)
+
+**Canonical**:每個 inline-action host 必須提供 `xxxSlot?: React.ReactNode` 作 escape hatch:
+
+| Host family | Config prop | Escape hatch slot prop |
+|---|---|---|
+| Field family(Input / NumberInput / DatePicker / Combobox / LinkInput / TimePicker) | `endAction?: InlineActionConfig` | `endSlot?: React.ReactNode` |
+| Row family(TreeView.TreeItem / SidebarMenuButton)| `inlineActions?: InlineActionConfig[]` | `inlineActionsSlot?: React.ReactNode` |
+
+```tsx
+// ✅ 90% case
+<Input endAction={{ icon: X, label: '清除', onClick: handleClear }} />
+<TreeItem inlineActions={[{ icon: MoreVertical, label: '更多', onClick: ... }]} />
+
+// ✅ 10% case(escape hatch)
+<Input endSlot={<DropdownMenuTrigger asChild><MyChevron /></DropdownMenuTrigger>} />
+<TreeItem inlineActionsSlot={<MyCustomActionGroup />} />
+```
+
+**規則**:
+- Slot 跟 config 互斥(slot 優先,config 被忽略)
+- `disabled / readonly` 模式 / Sidebar `collapsible=icon` 模式跟 config 一致(slot 也要被相同條件隱藏)
+- Reveal 模式(`actionsReveal="hover"`)、絕對定位 chrome 跟 config 共用,consumer 不需重做
+- Padding budget(Sidebar)slot mode 預設按 1 icon 寬度預留,多 icon 寬度需 consumer 自控 className
+- 視覺一致性 by consumer — 但 **app-code 不可直接 import L3 primitive**(`ItemInlineActionButton` / `ItemInlineAction` / `RowSizeProvider`),由 `check_canonical_propagation.sh` E.2(原 `check_l3_primitive_import`,已 folded,P0 BLOCK)攔截。需要視覺一致 inline-action button 時,(a) 用 host 自帶 slot(此 escape hatch)、(b) 用 `<Button iconOnly variant="text" />`、(c) 走 spec rationale 例外申請
+
+**現況清單**(2026-04-25 補完):
+- ✅ `Input.endSlot`
+- ✅ `NumberInput.endSlot`
+- ✅ `TreeView.TreeItem.inlineActionsSlot`
+- ✅ `SidebarMenuButton.inlineActionsSlot`
+
+**不適用清單**:DatePicker / Combobox / Select / TimePicker / LinkInput 右側由元件自帶 chrome 獨佔(Calendar / ChevronDown / Clock / ExternalLink 等 intrinsic affordance),不開放 consumer 放置 endAction/endSlot — 這些元件的 inline-action 需求走**內建 clear X**(consumer 透過 `clearable` prop opt-in)或 `<Button iconOnly />` 放在 Field 外側。Escape hatch canonical 不涵蓋此類 host(本質上非 consumer-facing slot)。
+
+**世界級對照**: <!-- @benchmark-unverified -->
+- Material UI:`InputAdornment` ReactNode slot(無 config,純 escape hatch 派 — 我們的 90/10 比 Material 更有結構)
+- Polaris:`TextField.connectedRight` ReactNode 只接 Button,但無 config-based 簡化,API 一致性差
+- Ant Design:`Input.suffix` ReactNode slot,跟 Material 同派
+- Atlassian:`Textfield.elementAfterInput` ReactNode
+
+我們採「config-first + slot escape hatch」屬刻意 deviation,rationale:90% case 宣告式 API 阻止 visual drift / a11y 漏失;10% case 仍提供逃生口,不強迫 consumer fork 元件。
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `alert.spec.md`
+- `breadcrumb.spec.md`
+- `data-table.spec.md`
+- `field-controls.spec.md`
+- `item-anatomy.spec.md`
+- `overlay-surface.spec.md`
+- `popover.spec.md`
+- `sheet.spec.md`
+- `sidebar.spec.md`
+- `tag.spec.md`
+- `tree-view.spec.md`
+- `uiSize.spec.md`