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

package/src/components/Empty/empty.spec.md

@@ -0,0 +1,214 @@
+---
+component: Empty
+family: composite
+variants: {}
+sizes: {}
+traits:
+  - isStructural
+benchmark:
+  - Ant Design Empty: github.com/ant-design/ant-design/tree/master/components/empty
+  - Polaris EmptyState: github.com/Shopify/polaris/tree/main/polaris-react/src/components/EmptyState
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Empty 設計原則
+
+**空狀態視覺元件**——容器內沒有內容時的居中提示。Table、SelectMenu、Combobox、Page section 等所有需要空狀態的元件統一消費。
+
+## 定位
+
+一個 **layout pattern**(不是 field-level 元件)。它排列 icon / title / description / action 成居中垂直堆疊,間距走 layout-space token(density-aware)。
+
+預設只有 description——icon / title / action 全部可選。
+
+**Layout Family**：非上述 family — composite / multi-section（多區塊組合，自 own layout）。
+
+---
+
+## 何時用
+
+- **Table / list / grid 空狀態**：DataTable 查無資料、搜尋無結果
+- **SelectMenu / Combobox 下拉空**：「無選項」「找不到符合的項目」
+- **Page section 無內容**：dashboard widget 暫無資料、設定頁未建立任何項目
+- **初次引導**：讓使用者首次使用時知道「這裡會放什麼」+ 有 CTA 建立
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| Loading 中(資料還沒來) | `Skeleton` / `CircularProgress` | Empty 是「確定沒有」,Loading 是「還沒確定」 |
+| 錯誤 / 失敗狀態 | `Alert` + 重試按鈕 | Error 需要明確告知「發生什麼問題」+ 解決途徑，Empty 是中性提示 |
+| 整頁級別的 404 / 無權限 | 專屬錯誤頁面 | Empty 是容器內提示，整頁錯誤需要完整頁面佈局 |
+| Disabled 狀態 | 禁用元件本身 | Empty 是「沒東西」，disabled 是「不能操作」 |
+
+```
+         [Avatar 48px neutral + icon]     ← 可選
+          gap = --layout-space-tight
+        [Title 16px font-medium centered]  ← 可選
+         --item-gap-label-desc-reading-lg (2px)
+      [Description 14px fg-secondary centered]
+               w-full (no max-width)
+          gap = --layout-space-loose
+              [Action Button]              ← 可選
+```
+
+## Slots
+
+- **Icon**(`icon?: LucideIcon | ReactElement`,預設無):LucideIcon 會自動包 48px neutral Avatar + 28px icon;ReactElement 原樣渲染(consumer 可自帶 Illustration、ColorAvatar、CircularProgress)
+- **Title**(`title?: string`,預設無):主要標題,foreground + medium 字重,居中
+- **Description**(`description?: string`,預設無 — 但是唯一必有的 slot):說明文字,次要色、居中
+- **Action**(`action?: ReactNode`,預設無):CTA Button 或任何操作,居中
+
+## 間距
+
+固定值,不隨 density 變(Empty 是展示性元件,不是工作區域元件——展示性文字不跟 field-height tier 連動):
+
+- **Icon → Title/Desc**:視覺 → 文字過渡需充足呼吸空間(48px icon 尺寸不宜貼近文字)
+- **Title → Description**:緊密配對(同資訊塊,對齊 item-layout canonical 的 label ↔ desc gap)
+- **Description → Action**:資訊 → 行動的視覺暫停,引導使用者注意 CTA
+
+Outer padding 由 **consumer 容器** 決定(Table 空狀態需較大留白、SelectMenu dropdown 較緊湊、Page-level 最寬鬆)。
+
+## Typography
+
+- **Title**:body-lg + medium 字重 / foreground 色(主要閱讀重量)
+- **Description**:body tier / **`fg-muted` placeholder 等級色**(跟 input placeholder 同色,提示「這裡暫時沒內容」)
+
+完整 slot / gap / typography 的 class 與 px 對照見 anatomy `Overview`(Slot 與 Spacing)+ `SlotCombinations`(Slot 間距規則)stories。
+
+## 文字不限寬
+
+Description **不加 max-width**。文字撐滿容器,由容器 padding 控制行寬。文案設計者自己規劃換行(文案長度 = 設計的一部分),Empty 不該強制截斷。
+
+## 垂直定位(Consumer 容器的責任)
+
+Empty 只管**水平居中**。垂直定位由 consumer 的容器決定:
+
+| 容器類型 | 垂直定位 | 做法 |
+|---|---|---|
+| **有框**(Table / Dialog / Card,有明確 border 或 shadow 包圍) | **垂直置中** | 容器 `flex items-center justify-center min-h-[...]` |
+| **無框**(Page section,沒有外框線) | **頂部對齊 + generous padding** | 容器 `py-[calc(var(--layout-space-bottom)*2)]` |
+
+### 為什麼有框置中、無框不置中
+
+有框容器有明確的視覺邊界——使用者知道「這個框裡面是空的」。居中把 Empty 放在框的視覺重心,安定。
+
+無框容器沒有邊界——如果居中,Empty 會脫離頁面視覺中心,使用者不知道空的範圍有多大。頂部對齊 + `calc(var(--layout-space-bottom) * 2)` padding 讓 Empty 有固定位置,用留白空間本身創造「這裡是空的」的視覺重量,取代框線的作用。
+
+---
+
+## A11y 預設
+
+Empty 是 **non-interactive layout primitive**——本身無 ARIA role(讓 consumer 容器決定 region semantics)。但 consumer 應遵循以下慣例:
+
+| 場景 | Consumer 容器應加 | 為什麼 |
+|------|----------------|------|
+| Table / List 空狀態 | `<table aria-describedby={emptyId}>` 或在容器加 `aria-live="polite"` | screen reader 在資料載入完成時主動通知「無資料」(對齊 Polaris EmptyState pattern) | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+| Search / Filter 無結果 | container `aria-live="polite"` + 文案明確指向搜尋詞(「找不到符合『XXX』的結果」)| 對齊 Material `<NoOptions>` + Atlassian Empty Search idiom — 變動結果需 live region | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+| Page section 暫無內容 | `<section aria-labelledby={titleId}>` + `<h2>` 包 title slot | 對齊 WCAG 2.1 SC 2.4.6 標題明確語意 |
+| 初次引導(有 CTA) | Action Button 自帶 a11y;無需 Empty 層額外 ARIA | CTA 是真實互動 element,自己的 a11y 足夠 |
+
+**Title slot heading level**:Empty 不渲染 heading tag(`<h1>` / `<h2>`),只 `<div>` + 視覺 typography。Consumer 若需 heading semantic,在外層自包 `<h2>{title}</h2>` + 不傳 Empty 的 title prop(避免重複)。
+
+**Icon slot**:LucideIcon 自動渲染 `aria-hidden="true"`(decorative);ReactElement(自帶 Avatar / Illustration)由 consumer 控制 `aria-hidden` / `alt`(若是 `<img>` 必傳 `alt=""` 表示 decorative)。
+
+**Description 不需 live announcement**:Empty 本身是「靜態空狀態提示」(進入時就空),不是「動態變化結果」。動態變化(filter / search 結果切換)由 consumer 在容器層加 `aria-live`,不在 Empty 內。
+
+世界級對照:
+- **Polaris** `<EmptyState>`:容器層 `aria-labelledby` + heading 由 prop 控制 level(consumer 決定 `<h2>` / `<h3>`)
+- **Material** `<NoOptions>`(Autocomplete 內):容器自帶 `role="listbox"` + `aria-live="polite"` 通知無結果
+- **Carbon** `<EmptyState>`:無自帶 ARIA,文檔指引 consumer 在父容器設 `aria-describedby`
+
+本 DS 對齊 Carbon「primitive 不自帶 ARIA,consumer 控制」哲學——避免 Empty 強加 role 跟 consumer 容器衝突。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+---
+
+## 消費範例
+
+```tsx
+// Table 空狀態(最簡)
+<Empty description="沒有資料" />
+
+// SelectMenu 無結果
+<Empty icon={SearchX} description="找不到符合的結果" />
+
+// Page 首次引導(完整 slots)
+<Empty
+  icon={FolderOpen}
+  title="還沒有專案"
+  description="建立第一個專案來開始使用"
+  action={<Button>建立專案</Button>}
+/>
+
+// 自訂色彩(success result)
+<Empty
+  icon={<Avatar icon={CheckCircle} size={48} color="green" />}
+  title="已成功送出"
+  description="我們會盡快處理"
+/>
+
+// 自訂圖片
+<Empty
+  icon={<img src="/empty-illustration.svg" className="w-12 h-12" alt="" />}
+  description="尚無內容"
+/>
+```
+
+## 現有消費者改寫
+
+| 元件 | 現況 | 改為 |
+|---|---|---|
+| DataTable | inline `<div>` 硬寫 className | `<Empty description={emptyState} className="py-12" />` |
+| SelectMenu | — | `<Empty description="無選項" className="py-6" />` |
+| Combobox | — | `<Empty description="找不到結果" className="py-6" />` |
+
+## 禁止事項
+
+- ❌ 把 Empty 拿來顯示 loading state(無 description 又無 spinner)— Empty 是「確定沒有」語意,loading 用 `<Skeleton>` / `<CircularProgress>` 或 `<Empty icon={<CircularProgress />}/>` compose
+- ❌ 把 Empty 拿來顯示 error state(只有 description)— error 需明確 action(重試 / 報告 / 聯絡支援),用 `<Alert>` + 重試 button
+- ❌ Empty title / description 文案太抽象(「Nothing here」「No data」)— 應描述「缺什麼資料」+「為什麼空」+「下一步動作」(對齊 Polaris EmptyState / Carbon Empty State copy guideline) <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- ❌ Action button 用 destructive variant — Empty 是引導 onboarding 心境,destructive 視覺敵意衝突
+- ❌ 整頁 Empty 但無 action — user 困惑「我該做什麼」;若該頁本質無 action(等待後台 invite),改用 Alert/Notice 解釋
+
+## 為何無 Inspector / ColorMatrix / SizeMatrix / StateBehavior
+
+Empty 是 **pure layout primitive**(排列 icon / title / description / action 成居中垂直堆疊),不是互動元件,也不是 variant-driven 元件:
+
+- **無 Inspector**:Empty 的「關鍵決策」是 slot 組合(description only → full),已在 `SlotCombinations` story 呈現四種組合對照(最簡 → 輕引導 → 中引導 → full)。互動切換式 Inspector 不會比 slot composition 對照更有教學價值——consumer 需要的是「這四種場景怎麼選」。
+- **無 ColorMatrix**:Empty 自身不帶任何色彩,bg transparent,text color 全部走 semantic token(`text-foreground` / `text-fg-muted`)。Avatar icon 的色彩由 consumer 透過 `<Avatar color="...">` 決定,非 Empty 層級 variant。
+- **無 SizeMatrix**:Empty 無 `size` prop,垂直 padding 由 consumer 容器決定(Table `py-12` / SelectMenu `py-6` / Page `py-16`),固定間距不隨 density 變(展示性元件,見本 spec「間距」段)。
+- **無 StateBehavior**:Empty 是非互動展示元件,無 hover / focus / active / selected / disabled。CTA button 的互動狀態屬 Button 層級,不屬 Empty。
+
+對應 anatomy story:保留 `Overview` + 元件特有 `ScenarioMatrix`(常見業務場景) + 元件特有 `SlotCombinations`(slot 組合對照)。
+
+---
+
+## 相關
+
+- `../Avatar/avatar.tsx` — Icon 渲染實作
+- `../CircularProgress/circular-progress.spec.md` — Loading 狀態(非「空」而是「還沒來」;全頁 loading 可 `<Empty icon={<CircularProgress size={48}/>}/>` compose)
+- `../Alert/alert.spec.md` — Error 狀態（非中性空，是需處理的問題）
+- `../FileUpload/file-upload.spec.md` — **本元件 consumer**:FileUpload 預設 children 直接渲染 `<Empty icon={Upload} title description />`,共用 icon+title+desc SSOT
+- `../../tokens/typography/typography.spec.md` — Typography tier
+- `../../tokens/layoutSpace/layoutSpace.spec.md` — Layout-space token
+- `../../patterns/element-anatomy/item-anatomy.spec.md` — label → desc gap(token `--item-gap-label-desc-reading-lg` / primitive `<ItemContent>`)
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `carousel.spec.md`
+- `file-viewer.spec.md`
+- `select-menu.spec.md`
+- `skeleton.spec.md`
+- `tree-view.spec.md`
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `combobox.spec.md`
+- `command.spec.md`
+- `select.spec.md`
+- `sheet.spec.md`

package/src/components/Field/field-controls.spec.md

@@ -0,0 +1,338 @@
+---
+component: FieldControls
+traits:
+  - hasVariants
+  - hasSizes
+  - hasInteractiveStates
+  - isStructural
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Field Controls 設計原則
+
+> **Foundational SSOT rationale**(cap 800,2026-04-25 approved):
+> Family 4 (Field Control Layout) SSOT owner。Input / NumberInput / DatePicker / Select / Combobox / LinkInput / TimePicker / Textarea / PeoplePicker 等皆消費 `fieldWrapperStyles` / edit-readonly-disabled 三態 mode architecture / endAction 處理 / Display 子元件 pattern / Inline Action canonical(後者也 cascade 到 Sidebar / TreeView / DropdownMenu)。scope 本質 > 單一元件。
+
+> **注意**：此文件是 Field Controls（Input / NumberInput / DatePicker / Select / Combobox / LinkInput / PeoplePicker 等)**共用**的設計原則，與 `Field/field.spec.md`（表單 Layout 容器）**不是同一個東西**。
+>
+> - **Field Controls**（本文件）：具體的資料型別輸入元件，內部含 edit/readonly/disabled 三態 + 格式化 + DataTable Display 共用
+> - **Field**（`Field/field.spec.md`）：shadcn 風格的表單 Layout 容器（label + description + error），wrap 上述 Field Controls 元件
+
+**Layout Family**：本 spec 是 CLAUDE.md 4-Family Model **Family 4（Field Control Layout）的 SSOT**。結構 `fieldWrapperStyles + [startIcon?] [<editable content>] [endAction?]`，**視覺對齊 Family 1（Menu item layout）**——Select trigger 的高度 / 字體 / icon size 必須跟其 SelectMenu options 連續一致。Consumers: Input（canonical）, NumberInput, DatePicker, Select, Combobox, LinkInput, PeoplePicker。
+
+## 定位
+
+Field Controls 是資料輸入與顯示的基礎元件。每種資料類型（text、number、date、select...）對應一個元件，同時服務 Form 和 DataTable：
+
+- **Form**：用 Field Controls 的 edit / readonly / disabled 三態（在 Field 容器內）
+- **DataTable**：用 Field Controls 的 Display 子元件渲染 cell
+
+每個元件擁有該類型的格式化邏輯（唯一真實來源），Form 和 DataTable 消費同一份 code。
+
+---
+
+## 架構
+
+```
+Field/
+├── field.tsx               ← Field 佈局容器（label + control + desc + error）
+├── field.spec.md           ← Field 佈局容器設計原則
+├── field-controls.spec.md  ← 本文件
+├── field-types.ts          ← FieldMode、InlineActionConfig 共用型別
+├── field-wrapper.tsx       ← 共用 wrapper 樣式、bareInputStyles、EMPTY_DISPLAY
+├── Input/                  ← Input（含 mode="display"）
+├── NumberInput/            ← NumberInput（含 mode="display" + formatNumber）
+├── DatePicker/             ← DatePicker（含 mode="display" + formatDate）
+├── Select/                 ← Select（含 mode="display"）
+├── Combobox/               ← Combobox（含 mode="display"）
+├── LinkInput/              ← LinkInput（含 mode="display"）
+├── PeoplePicker/           ← PeoplePicker + PersonDisplay（cross-component primitive）
+└── Textarea/               ← Textarea（多行）
+```
+
+每個元件統一以 `mode` prop 切換樣態：
+1. **edit / readonly / disabled** — Form 用，可編輯 / 鎖定 / 不可用
+2. **`mode="display"`** — DataTable cell 用，純格式化顯示（取代過往的 `XxxDisplay` 子元件）
+
+---
+
+## Mode — 三種模式
+
+| Mode | 底色 | 邊框 | 文字色 | 用途 |
+|------|------|------|--------|------|
+| `edit` | surface | border（hover 深一階、focus primary） | foreground | 表單可編輯欄位 |
+| `readonly` | neutral-2 | 無 | foreground | 表單中不可編輯但可見的欄位 |
+| `disabled` | neutral-2 | 無 | fg-disabled | 表單中被停用的欄位 |
+
+三種模式共用同一個 wrapper 結構（`fieldWrapperStyles`），只有底色、邊框、文字色不同。
+
+### Loading state(async 驗證 / debounce fetch 中)
+
+Loading **不是第四個 mode**,是 `edit` mode 的子狀態,語義 = **editable 仍可輸入**(UX「邊改邊讀」:debounce search / async validation 場景中 user 常需要繼續打字修正,凍結輸入反而破壞心流)。
+
+**世界級流派選擇**(editable 派 vs readonly 派):
+
+| DS | Loading input 做法 | 流派 |
+|----|-------------------|------|
+| Ant Input.Search | **input 仍 editable**,suffix spinner;submit 另鎖 | editable |
+| Material TextField | readonly + suffix adornment loader | readonly |
+| Polaris TextField | readonly + helpText 提示 | readonly |
+| Carbon TextInput | readonly + inline Loading | readonly |
+| Atlassian TextField | disabled | disabled(少數派) |
+| Apple HIG UITextField | visual overlay only,不阻礙輸入 | editable |
+
+**本 DS 採 editable 派**(Ant / Apple HIG):
+- **UX 理由**:debounce 搜尋場景,user 邊打邊看建議,凍結一格會卡節奏;async validation 若第一次失敗,user 該能立即改,不是等 spinner 完才能動
+- **對照 readonly 派**:readonly 派適合「提交後驗證」的場景(e.g. 表單 submit → 驗證),本 DS 的 `loading` prop 用在 debounce / inline validation,editable 更 fit
+
+**實作 canonical(Input / NumberInput / Combobox 等 Field 元件)**:
+- API:`loading?: boolean` prop
+- 內部:`loading=true` → wrapper `aria-busy="true"` + **endAction slot 自動塞 `<CircularProgress size={iconSize}/>`**(與 `endAction` prop 互斥,loading 優先)
+- input **不進 readonly / disabled**,保持可編輯
+- CircularProgress 尺寸:程式化 `iconSize`(sm/md=16, lg=20),消費者不用再傳
+- CircularProgress 顏色:走預設 `text-primary`(表達「正在處理,請注意」)
+- startIcon(Search 等語義 icon)**不受 loading 影響**,保留原位置
+
+```tsx
+// 世界級 canonical:search field 在 loading 中,user 仍可修改關鍵字
+<Input startIcon={Search} loading placeholder="搜尋..." />
+// → search icon 在 prefix(保留語義身分)
+// → CircularProgress 在 endAction 位置(暫時狀態)
+// → input editable + aria-busy,user 可繼續輸入 / 修改
+```
+
+❌ 禁止手刻路線:
+```tsx
+// 絕對不寫
+<div className="relative">
+  <Input startIcon={Search} />
+  <div className="absolute right-3 top-1/2 -translate-y-1/2">
+    <CircularProgress size={16} />
+  </div>
+</div>
+```
+手刻 absolute 對齊容易跑掉(Field 元件內 loading 指示與既有 endAction 垂直對齊不一致)。一律用 `loading` prop。
+
+### disabled 的停用原因
+
+停用原因由外部承擔，不在 input 內放 info icon：
+- **Tooltip**：包住整個 Field 元件（wrapper `<div>` 不是 disabled 元素，可正常接收 hover）
+- **Form help text**：在 input 下方說明（Form 層負責）
+
+### 原生屬性覆蓋
+
+`disabled` 和 `readOnly` 原生 HTML 屬性會自動覆蓋 `mode` prop，避免衝突。
+
+---
+
+## Error — 正交於 mode
+
+Error 是 boolean prop，獨立於 mode。只在 `edit` 模式下有視覺效果（`border-error`）。
+
+- Error 視覺在 Field（input）層級：紅色邊框 + `aria-invalid`
+- Error 訊息在 Form 層級：help text 顯示在 input 下方
+- Field 不在尾部放狀態 icon（如 ⚠️）——邊框顏色已經傳達了 error 狀態
+
+Form wrapper 可透過 context 注入 `error` prop，消費者不需要在每個 Field 上手動傳。
+
+---
+
+## Size — 與 Button 對齊
+
+| Size | 高度 token | Tailwind | 字體 |
+|------|-----------|----------|------|
+| `sm` | `--field-height-sm` | `h-field-sm` | text-body |
+| `md` | `--field-height-md` | `h-field-md` | text-body |
+| `lg` | `--field-height-lg` | `h-field-lg` | text-body-lg |
+
+高度使用 `--field-height-*` semantic token（rem 單位），與 Button 共用同一組 token，同 size 的 Field 和 Button 並排時高度一致。
+
+---
+
+## Focus 行為
+
+`<input>` 元素在點擊和鍵盤 Tab 時都觸發 `:focus-visible`（瀏覽器規範：文字輸入永遠 focus-visible），CSS 無法區分。
+
+統一使用 `border-primary`（1px），不加 ring、不加粗。
+
+---
+
+## 點擊與游標原則
+
+### 點擊穿透
+
+Field 內部所有不會觸發獨立 action 的元素必須 `pointer-events-none`，讓點擊穿透到底層的 input/select，確保使用者點擊 Field 內任何位置都能 focus/activate。
+
+穿透（`pointer-events-none`）：startIcon、ChevronDown 下拉箭頭、tag 文字區域。
+不穿透：endAction（clear、toggle password）、tag dismiss button——這些有自己的 action。
+
+### 游標指引
+
+可點擊的元素必須有明確的 cursor 變化：
+- endAction、dismiss button → `cursor-pointer`
+- input / select → `cursor-text` / `cursor-pointer`（原生行為）
+- disabled → `cursor-not-allowed`
+
+## Icon 色彩原則
+
+跨元件統一規則（詳見 `item-anatomy.spec.md`）：**icon 代表內容/類別 → 與 label 同色；icon 純指示方向 → fg-muted（neutral-7）。**
+
+Field 內的具體套用：
+
+- **startIcon**（Search、Calendar）：`fg-muted`——指示 field 用途，不是 value
+- **ChevronDown 下拉箭頭**：`fg-muted`——指示可下拉
+- **代表 value 的 icon**（如狀態 icon）：**foreground**——icon 本身就是 value 的一部分
+- **disabled 時**：所有 icon 統一 `fg-disabled`
+
+## startIcon
+
+左側靜態 icon，輔助使用者理解 input 的用途（如 Search icon）。屬於 input 的視覺提示，不屬於 value。
+
+- 顏色 `fg-muted`（disabled 時 `fg-disabled`）
+- `aria-hidden`——純裝飾
+- 命名與 Button 的 `startIcon` 一致
+
+## 下拉箭頭（Select / Combobox）
+
+Select 和 Combobox 的最右側固定顯示 ChevronDown icon，指示可下拉選擇。
+
+- 顏色 `fg-muted`——指示意圖，不是 value
+- 不可互動（`pointer-events-none`）——下拉由 select 元素本身觸發
+- clearable 有值時：clear X 在左，ChevronDown 在右
+- 右側元素(clear + chevron)水平間距對齊 Field container padding token(具體值見 `field-wrapper.tsx`),跟 Input 一致
+
+## Select 顯示模式
+
+Select 支援兩種顯示模式（`display` prop）：
+
+| 模式 | edit | readonly / disabled | 適用場景 |
+|------|------|---------------------|---------|
+| `text`（預設） | 原生 select 純文字 + ChevronDown | 跟 Input 一致（純文字 + 標準 padding） | 狀態、類別等文字選項 |
+| `tag` | Tag + 隱藏 select overlay + ChevronDown | Tag + tagPadding | 需要視覺標記的選項（顏色標籤等） |
+
+`text` 模式可搭配 `startIcon`（代表 value 的圖示，如狀態 icon）。
+
+`tag` 模式的 edit 用 hidden select overlay(跟 Combobox 同模式),Tag 用 `pointer-events-none`,點擊穿透到 select。右側元素水平間距對齊 Field container padding token(見 `field-wrapper.tsx`)。
+
+tagPadding 只在有 Tag 時才套用。Placeholder/空值狀態使用 fieldWrapper 的標準 px-3 padding，確保文字與邊框有足夠間距。
+
+---
+
+## endAction（Inline Action）
+
+右側可互動元素，用於操作動作（清除內容、顯示密碼等）。
+
+使用宣告式 API：
+
+```tsx
+<Input endAction={{ icon: X, label: '清除', onClick: handleClear }} />
+```
+
+Field 內部用 `<ItemInlineAction>`(`item-layout.tsx` 共用元件)渲染 — 跟 Sidebar / TreeView / DropdownMenu 的 inline action **完全同一套** canonical 實作,不再有「每個 host 自己複製 18 行 button JSX」的漂移。
+
+- 共用規則見 `patterns/element-anatomy/item-anatomy.spec.md`「Inline Action 設計規格」節
+- Helper 規格與 API 見 `item-anatomy.spec.md` 的「Inline action 共用元件」節
+- Field host 必須傳 `size={size}` 給 `<ItemInlineAction>`(field 不在 `RowSizeContext` 內,需明確覆寫)
+
+Icon 色彩遵循 Inline Action 統一規則:預設 `fg-muted`,hover 時 `foreground`。
+
+- disabled / readonly 模式不渲染 endAction
+- 條件渲染即可——消失後不佔位,input 自然擴展
+- 下拉箭頭不屬於 endAction,屬於 Select / Combobox
+
+**特例:Tag dismiss**——Tag 的 dismiss button 需要 chromatic hover bg(跟 tag 的 solid variant 色相一致),不是中性的 neutral-hover,因此**沒有**用 `ItemInlineAction`,維持自己的內部 JSX。這是合理特例,見 `tag.tsx:104` 的詳細註解。
+
+**Escape hatch**(10% case config 表達不出時):每 Field host 提供 `endSlot?: React.ReactNode`,規則 SSOT 見 `patterns/element-anatomy/inline-action.spec.md`「Escape hatch」節。
+
+---
+
+## Display — 格式化顯示
+
+每個 Field 元件 export 一個 Display 子元件，負責把 raw value 格式化為可讀文字或 ReactNode。
+
+Display 的消費者：
+- **DataTable cell**：根據 `meta.type` 自動選擇對應的 Display 元件
+- **Field readonly 模式**：內部使用相同的格式化邏輯
+
+### null / undefined 值
+
+Display 模式統一顯示 em dash `—`，顏色 `text-fg-muted`。edit 模式顯示空白。
+
+此規則適用於所有 Field 類型，boolean 例外（顯示 unchecked 狀態）。
+
+### DataTable 整合
+
+DataTable 根據 column 的 `meta.type` 自動選擇 Display 元件：
+
+```tsx
+// 自動渲染——不需要手寫 cell
+col.accessor('price', {
+  header: 'Price',
+  meta: { type: 'currency', prefix: '$' },
+})
+
+// 客製化——有自訂 cell 時完全跳過 type → Display
+col.accessor('status', {
+  header: 'Status',
+  cell: (info) => <MyCustomBadge status={info.getValue()} />,
+})
+```
+
+兩者可在同一張 table 混用。
+
+---
+
+## 共享 contract(2026-05-12 Stream C — Selected renderer / Placeholder vocabulary / Cell surface)
+
+**(a) Selected value renderer**:rich display(avatar+name/icon+label)元件**必**提供 consumer renderer slot,**display/readonly/disabled/edit** 4 mode 共享同一 renderer(禁 edit-only)。`Select.selectedItemRenderer` / `Combobox.tagRenderer`(edit 已接;display path unify deferred 下 cycle)/ PeoplePicker 走 `PersonDisplay`+`MultiPersonDisplay`+`Combobox.tagRenderer`。對齊 MUI Autocomplete `renderValue` / Ant Select `tagRender`+`labelRender`+`optionRender` / MUI DataGrid `renderCell`+`renderEditCell` 共享 params。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+**(b) Placeholder vocabulary**(3 props 對 3 UI state,**不可混用**):
+- `placeholder` — trigger empty(沒選值,例「請選擇人員」)— Ant/Polaris/Carbon canonical
+- `searchPlaceholder` — search input hint(例「搜尋人員…」)— Ant `searchPlaceholder`
+- `emptyText`/`noResultsText` — filtered menu 無結果(例「沒有符合的人員」)— Ant `notFoundContent` / Material X `localeText.noResultsOverlayLabel`
+
+**禁**:wrapper 把 `emptyText`(search-empty)silent forward 成 `emptyPlaceholder`(trigger-empty);**Combobox `emptyPlaceholder` deprecated**,保留 1 cycle fallback,future `placeholder` 唯一 trigger source。Hook `check_field_controls_contracts.sh` (contract b) 機械強制。
+
+**(c) Cell surface metrics**:Field family 在 cell 內**禁** hardcode padding(`tagAreaPaddingLeftPx={isEmpty ? undefined : 8}` 反 pattern)。改 **`FieldSurface` context**(`'form' | 'toolbar' | 'table-cell'`):`useFieldSurface()` 取值,`<FieldSurfaceProvider surface="table-cell">` 自動套於 `cell-registry.resolveCellComponent`。Consumer 用 `surface === 'table-cell'` 顯式 query(取代 `variant === 'naked'` heuristic)。**risk mitigation**:`avatar.left = cell.left + computed(--table-cell-px)`,禁再加 magic 8px(double-count)。**Token scope**:`--table-cell-px/py` 是 DataTable-scoped metric(CSS 定義在 `data-table.css`,Field naked variant 是 DataTable cell substrate sub-component 故 cross-path reference 不算真 cross-component),per 2026-05-13 codex Q2 verdict + AG Grid `cellHorizontalPadding`(grid theme param)/ MUI X `cellClassName`(per-cell)/ Carbon spacing scale primitive(不升 cell padding 全域 token)idiom — **不**升 `tokens/layoutSpace/` canonical。對齊 AG Grid cellRendererSelector / Material X DataGrid 共享 params / Notion property type registry。Hook `check_field_controls_contracts.sh` (contract c) 機械強制。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+**(d) Default variant display = zero chrome SSOT**(2026-05-13 user 拍板 Path Ⅰ + codex V2 verdict):default `mode='display'` **必** zero chrome。Display 純展示語意,真要包 chrome 走 `readonly` 或 `showDisplayEndIcon=true` opt-in。**Impl**:`field-wrapper.tsx` + `textarea.tsx` compoundVariants `mode:'display'+variant:'default'` 加 `!px-0 !py-0`。對齊 Carbon read-only / Stripe display / Notion property / Polaris readonly。Hook `check_field_controls_contracts.sh` (contract d) propose。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+**(e) Display typography canonical**(2026-05-14 user I2 + codex M31 verdict):Field family display path **必** consume `fieldWrapperStyles` size variants typography token — `sm/md → text-body`(14px line-height 1.5)/ `lg → text-body-lg`(16px)。**禁**:LinkInput / Select / Combobox 非 D-path 的 bare-span 直接 render 無 font-size class(瀏覽器 default 字體);**必**包 `text-body` (sm/md) / `text-body-lg` (lg) class。對齊跨 Field family display 視覺尺寸統一(user 抓 LinkInput display 字體跟其他 Field 不一致 = SSOT 違反 漏接 typography token)。**Impl**:LinkInput / Select / Combobox / DatePicker / TimePicker non-D-path bare-span 加 size-aware text class。world-class cite:MUI X DataGrid `Typography` consistent / Atlassian @atlaskit/textfield size-prop typography token / Polaris TextField typographyToken size-aware。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+---
+
+## 表單驗證原則
+
+詳見 `Field/form-validation.spec.md`。
+
+## 禁止事項
+
+- ❌ 不在 disabled input 內放 info icon——停用原因由外部 Tooltip 或 Form help text 承擔
+- ❌ 不在 input 尾部放 error 狀態 icon——邊框顏色已傳達 error
+- ❌ endAction 不可傳入 ReactNode——使用 InlineActionConfig 宣告式 API
+- ❌ endAction 的 inline action 不可省略 `aria-label`（即 `label` 欄位）
+- ❌ Display 的 null 值不可顯示空白——統一使用 `—`（em dash）+ `text-fg-muted`
+- ❌ Field 的 readonly 模式不可用於 DataTable cell——readonly 有底色和 wrapper 開銷，table cell 用 Display 元件
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `checkbox.spec.md`
+- `circular-progress.spec.md`
+- `combobox.spec.md`
+- `data-table.spec.md`
+- `date-picker.spec.md`
+- `element-anatomy.spec.md`
+- `input.spec.md`
+- `link-input.spec.md`
+- `number-input.spec.md`
+- `people-picker.spec.md`
+- `rating.spec.md`
+- `segmented-control.spec.md`
+- `select.spec.md`
+- `slider.spec.md`
+- `switch.spec.md`
+- `textarea.spec.md`
+- `time-picker.spec.md`