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

package/src/components/Field/field.principles.stories.tsx

@@ -0,0 +1,255 @@
+// @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.
+// @principles-rationale: UsageGuidance merges WhenToUse + Vs*Rule into single 使用指引 story per refactor task (2026-04-26)
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Upload } from 'lucide-react'
+import { Field, FieldLabel, FieldDescription, FieldGroup } from './field'
+import { Input } from '@/design-system/components/Input/input'
+import { Select } from '@/design-system/components/Select/select'
+import { Button } from '@/design-system/components/Button/button'
+
+const meta: Meta = {
+  title: 'Design System/Components/Field/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+const Rule = ({
+  title, note, children,
+}: {
+  title: string; note?: string; children: React.ReactNode
+}) => (
+  <div className="mb-14">
+    <h3 className="text-body font-bold text-foreground mb-1">{title}</h3>
+    {note && <p className="text-caption text-fg-muted mb-5 max-w-[720px] leading-relaxed">{note}</p>}
+    <div className="flex flex-col gap-3 max-w-xl">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p className={`text-footnote leading-normal ${warn ? 'text-error font-medium' : 'text-fg-muted'}`}>{children}</p>
+)
+
+const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <section className="mb-12">
+    <h2 className="text-h3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
+    {children}
+  </section>
+)
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div>
+      <Section title="何時用">
+        <div className="prose prose-sm max-w-prose mb-8">
+          <p>適合 Field 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+          <ul className="space-y-1">
+            <li><LinkTo kind="Design System/Components/Field/展示" name="垂直"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">註冊 / 建立專案表單 — 引導式逐欄輸入(垂直佈局)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/Field/展示" name="水平"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">帳號設定 / 偏好設定頁 — 修改已知屬性(水平佈局)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/Field/展示" name="混合控制元件的高度對齊"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">同一表單混用 Input / Select / DatePicker 等控制元件</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/Field/展示" name="SegmentedControl 作為 Field 控制元件"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">少量互斥選項(計費週期、版面密度)用 SegmentedControl 當控制元件</span></LinkTo></li>
+          </ul>
+          <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方 vs 近親 段)。</p>
+        </div>
+      </Section>
+
+      <Section title="何時不用 + 替代方案">
+        <Rule
+          title="❌ Field 試圖承載資料型別邏輯"
+          note="別把「格式化數字」「處理日期」「搜尋選項」塞進 Field——這些是 Field Controls(NumberInput / DatePicker / Combobox)的責任。Field 不 wrap、不代理、不轉換它們的行為"
+        >
+          <Label warn>Field 試圖自己處理 number formatting → 複製 NumberInput 邏輯 → 違反 SRP + 漂移風險</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 把 form submit button 包在 Field 內"
+          note="破壞「Field = 資料容器」的心智模型。使用者掃 form 時看到每個 Field,submit 按鈕不該混入這個節奏"
+        >
+          <div className="max-w-sm">
+            <FieldGroup>
+              <Field required>
+                <FieldLabel>Email</FieldLabel>
+                <Input />
+              </Field>
+              <Field>
+                <FieldLabel>操作</FieldLabel>
+                <Button variant="primary">送出表單</Button>
+              </Field>
+            </FieldGroup>
+          </div>
+          <Label warn>↑ 「送出表單」不該是一個 Field,它是 form-level action,應該在 footer</Label>
+        </Rule>
+      </Section>
+
+      <Section title="vs 近親元件">
+        <Rule
+          title="Field — 表單輸入(可編輯)"
+          note="使用者要輸入 / 修改 / 提交的 form 場景。含 required、error、focus、驗證等 form state 機制"
+        >
+          <div className="max-w-sm">
+            <FieldGroup>
+              <Field>
+                <FieldLabel>Email</FieldLabel>
+                <Input defaultValue="user@example.com" />
+              </Field>
+              <Field>
+                <FieldLabel>時區</FieldLabel>
+                <Select
+                  options={[{ value: 'tw', label: '台北 (UTC+8)' }]}
+                  value="tw"
+                  onChange={() => {}}
+                />
+              </Field>
+            </FieldGroup>
+          </div>
+          <Label>↑ 可編輯的 profile settings</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 唯讀展示:用 DescriptionList"
+          note="「查看使用者資料」「訂單明細」這類純展示場景不該用 Field + readonly mode——DescriptionList 的 `dl / dt / dd` HTML 語義更適合唯讀屬性列表,a11y 也更清楚"
+        >
+          <div className="max-w-sm">
+            {/* horizontalLabelWidth:同表單 horizontal Field 必統一 label 寬(field.spec.md「FieldGroup horizontalLabelWidth cascade」)*/}
+            <FieldGroup horizontalLabelWidth="120px">
+              <Field orientation="horizontal">
+                <FieldLabel>Email</FieldLabel>
+                <Input mode="readonly" defaultValue="user@example.com" />
+              </Field>
+              <Field orientation="horizontal">
+                <FieldLabel>建立時間</FieldLabel>
+                <Input mode="readonly" defaultValue="2026-04-18" />
+              </Field>
+            </FieldGroup>
+          </div>
+          <Label warn>↑ 純展示用 Field + readonly → 浪費 Field 的 input 邏輯。改用 DescriptionList</Label>
+        </Rule>
+
+        <Rule
+          title="判斷法:「使用者會編輯這些值嗎?」"
+          note="會 → Field(含 readonly mode);永遠不會(純展示/唯讀資料)→ DescriptionList。完整對照見 field.spec.md「何時不用」+ description-list.spec.md「vs Field 系統」"
+        >
+          <Label>會編輯 → Field;只看 → DescriptionList</Label>
+        </Rule>
+      </Section>
+    </div>
+  ),
+}
+
+// ResponsibilityRule retired 2026-07-17 per audit Dim 24 —— 與 anatomy Overview「子元件責任邊界」
+// 責任表 + 逐字相同的 電子郵件/密碼 範例重複;職責原則亦已由上方 UsageGuidance「❌ Field 試圖承載
+// 資料型別邏輯」涵蓋(earn-existence 2-test 皆 NO)。UsageGuidance 使 principles universal-core 仍 ≥ 2,
+// 無 LinkTo 引用此 story,退役零斷鏈。
+
+export const OrientationRule: Story = {
+  name: '方向 選擇',
+  render: () => (
+    <div>
+      <Rule
+        title="Vertical(預設)— 主要表單場景,label 在控件上方"
+        note="建立 / 編輯表單、登入 / 註冊、精靈流程。每個 field 佔完整寬度,自然垂直堆疊"
+      >
+        <div className="max-w-sm">
+          <FieldGroup>
+            <Field required>
+              <FieldLabel>姓名</FieldLabel>
+              <Input placeholder="請輸入姓名" />
+            </Field>
+            <Field>
+              <FieldLabel>公司</FieldLabel>
+              <Input placeholder="選填" />
+            </Field>
+          </FieldGroup>
+        </div>
+        <Label>↑ Vertical 適合大多數表單場景</Label>
+      </Rule>
+
+      <Rule
+        title="Horizontal — Settings / 詳情頁,label 在控件左側"
+        note="已知屬性的修改介面(account settings、使用者偏好)。label + control 並排節省垂直空間,讓多個設定一目了然。label 固定寬度對齊縱向軸"
+      >
+        <div className="max-w-xl">
+          {/* horizontalLabelWidth:同表單 label 等寬 → 控件起點對齊(2026-06-10 user 抓本 story 違反自家 canonical)*/}
+          <FieldGroup horizontalLabelWidth="120px">
+            <Field orientation="horizontal" required>
+              <FieldLabel>電子郵件</FieldLabel>
+              <Input type="email" defaultValue="user@example.com" />
+            </Field>
+            <Field orientation="horizontal">
+              <FieldLabel>顯示名稱</FieldLabel>
+              <Input defaultValue="Ada Chen" />
+            </Field>
+            <Field orientation="horizontal">
+              <FieldLabel>時區</FieldLabel>
+              <Select
+                options={[
+                  { value: 'tw', label: '台北 (UTC+8)' },
+                  { value: 'jp', label: '東京 (UTC+9)' },
+                ]}
+                value="tw"
+                onChange={() => {}}
+              />
+            </Field>
+          </FieldGroup>
+        </div>
+        <Label>↑ Horizontal 適合 settings 頁 — label 縱向對齊、controls 並排</Label>
+      </Rule>
+
+      <Rule
+        title="判斷法:「欄位數量 + 垂直空間預算」"
+        note="表單 / 初次建立(空間充裕、引導性)→ vertical;settings / 修改(已知屬性、密集顯示)→ horizontal"
+      >
+        <Label>世界級 DS(Polaris / Material)的 settings 頁都用 horizontal,表單用 vertical</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const NotForFormActionsRule: Story = {
+  name: '表單動作 不是 Field 控制元件',
+  render: () => (
+    <div>
+      <Rule
+        title="Field 是資料輸入容器——不放 form submit / cancel"
+        note="「儲存」「取消」「頁面導覽」這類 form-level action 應該在 form 底部的 footer / action bar,不是包在 Field 內"
+      >
+        <div className="max-w-sm">
+          <FieldGroup>
+            <Field required>
+              <FieldLabel>專案名稱</FieldLabel>
+              <Input />
+            </Field>
+            <Field>
+              <FieldLabel>描述</FieldLabel>
+              <Input />
+            </Field>
+          </FieldGroup>
+          <div className="mt-4 flex gap-2 justify-end">
+            <Button variant="tertiary">取消</Button>
+            <Button variant="primary">儲存</Button>
+          </div>
+        </div>
+        <Label>↑ 儲存 / 取消在 form footer,不在 Field 內</Label>
+      </Rule>
+
+      <Rule
+        title="✅ 合法情況 — 產生 value 的 Button"
+        note="「上傳檔案」「選擇日期」「連接 OAuth」這類產生 field value 的動作 Button 可以當 control。判準:動作會產生這個 field 的 value → 合法;動作是 form 級別(submit / cancel / navigation)→ 不合法"
+      >
+        <div className="max-w-sm">
+          <Field>
+            <FieldLabel>頭像</FieldLabel>
+            <Button variant="tertiary" startIcon={Upload}>上傳圖片</Button>
+            <FieldDescription>支援 JPG / PNG,最大 2 MB</FieldDescription>
+          </Field>
+        </div>
+        <Label>↑ 上傳按鈕產生 avatar url value → 合法作為 Field control</Label>
+      </Rule>
+    </div>
+  ),
+}

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

@@ -8,7 +8,6 @@ variants: {}
 sizes: {}
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
 
 # Field 設計原則
 
@@ -21,9 +20,9 @@ Field 是**表單欄位的佈局容器**。只負責排版（label / control / d
 
 與資料相關的一切（格式化、驗證、readonly 呈現、DataTable cell 顯示）住在各個資料型別的 Control 元件本身（Input、NumberInput、Checkbox、Switch 等）。Field 不 wrap、不代理、不轉換它們的行為。
 
-**實作基礎**：自建——本 DS 的 form layout 設計。shadcn 的 `Form` 元件走 react-hook-form + Zod + 自己的 Field primitive（含 Controller），本 DS 不採用這套耦合設計：Field 只做 layout + context，驗證由 consumer 自選（本 DS 建議 zod，見 `form-validation.spec.md`），保持更輕量、更獨立的定位。
+**實作基礎**：自建——本 DS 的 form layout 設計。**拒絕的是 Field 層引擎耦合**（2026-07-03 精確化）：shadcn 的 `FormField` = react-hook-form `Controller` wrapper、脫離 RHF 不能用——本 DS 不採用，因 Field 同時是 DataTable cell 基底（naked variant）+ display/readonly 純展示載體，耦引擎會毒害非表單場景；Field 只做 layout + context（engine-agnostic，對齊 MUI FormControl / Carbon / Polaris 派）。**form 層另有可執行層** `useFormValidation`（基於 react-hook-form，wrapped 不外露，對齊 DS「基於 X」引擎慣例；見 `form-validation.spec.md`「可執行層」段）——引擎藏在 form 層 hook 內 ≠ Field 耦合，Field 經 `invalid` context 一行接入。
 
-**Layout Family**：Field **不屬於** 4-Family Model 的 element layout families——它是 form composition pattern（包 Family 4 control + label + description）。見 CLAUDE.md「系統內部 Layout — 4-Family Model」→「Field Composition」段落。
+**Layout Family**：Field **不屬於** 4-Family Model 的 element layout families——它是 form composition pattern（包 Family 4 control + label + description）。見 taxonomy owner `patterns/element-anatomy/element-anatomy.spec.md`「Field Composition(不在 family 但相關)」段。
 
 ---
 
@@ -32,7 +31,7 @@ Field 是**表單欄位的佈局容器**。只負責排版（label / control / d
 Field 和 Field Controls（Input / NumberInput / DatePicker / Select / Combobox / LinkInput / PeoplePicker / Textarea）是兩件事：
 
 - **Field**（本元件）：只管佈局 + 狀態 context
-- **Field Controls / Checkbox / Switch / RadioGroup**：管自己的資料型別 + edit/readonly/disabled 三態 + 格式化（XxxDisplay 供 DataTable 共用）
+- **Field Controls / Checkbox / Switch / RadioGroup**：管自己的資料型別 + edit/readonly/disabled 三態 + 格式化(`mode="view"` 渲染供 DataTable cell 共用)
 
 這麼拆的理由：**Checkbox 在 table cell、form field、settings row 應該是同一個 primitive**，不該為了進到 form 就被包一層 CheckboxField；form 的高度對齊由 Field 的 control area 負責，不由 primitive 本身負責。Field Controls 的詳細共用規則見 `Field/field-controls.spec.md`。
 
@@ -60,6 +59,16 @@ Field 和 Field Controls（Input / NumberInput / DatePicker / Select / Combobox
 
 子元件寫法採**扁平結構**（直接作為 Field children），Field 內部用 `displayName` 判別 slot 類型並自動組合。consumer 不需要包 wrapper。
 
+### Field 次要 action 的預留位置（canonical,尚未實作）
+
+Field 若需要次要 action（如「重設」「全選」「從範本帶入」），**唯一預留位置 = label 行最右端**（label 與 action 兩端對齊）：
+
+- 形式：超連結樣文字（link-like text），**字級與行高皆同 FieldLabel**（`text-body` 14px、同 label 的 leading）——同字級同行高即天然等高，這是「不增高」的機制核心（user 2026-08-05 確認）。
+- 硬約束：**不得增加 label 行高度**（避免 field 被撐高）。等高機制之外還需三個盒模型條件缺一不可：(1) **零垂直 padding、無固定高度盒**——禁用 DS `Button`（xs 也自帶 `h-field-xs` 固定盒 + 自身 leading，`button.tsx` xs variant），必須是純文字元素；(2) **單行 `whitespace-nowrap`**（換行即行盒 ×2）；(3) **hit target 以 pseudo-element／負 margin 擴大**，不得用 padding 滿足 a11y 觸控目標（underline／focus ring 不佔佈局，無礙）。
+- 此位置是 field 次要 action 的**專屬 slot**——禁止把次要 action 放在 control 下方、error 位置或 field 外圍（那些位置屬 description/error/表單層動作）。
+- 對齊世界級：Polaris TextField `labelAction`（https://polaris.shopify.com/components/selection-and-input/text-field 的「With label action」example；2026-08-05 WebFetch 驗證 prop 存在）。
+- 狀態：**2026-08-05 user 拍板記錄,尚未實作**。實作時走 `<FieldLabelAction>` 類 slot + `/component-quality-gate`；在那之前任何 story/產品範例**不得**自行發明次要 action 擺位（anchor：PeoplePicker 多人 story 曾把 play() 測試用「重設協作者」按鈕誤植為 control 下方的產品 UI,2026-08-05 移除）。
+
 ---
 
 ## 樣式規範（全部 codify 在 field.tsx，不依賴 consumer）
@@ -77,7 +86,9 @@ Field 和 Field Controls（Input / NumberInput / DatePicker / Select / Combobox
 | Horizontal 模式 label 與 control 的 gap | `gap-x-3`（12px） |
 | Control area（任何 size） | `min-h-field-{size}` + `flex items-center` |
 
-**Label / Description / Error 字體固定 `text-body`（14px），不隨 field size 變。** Field size 只影響 input 高度，不影響表單佈局元素的 typography。世界級系統（Material、Ant Design、Atlassian、Carbon、Polaris）都是固定 label/helper text size。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**Label / Description / Error 字體固定 `text-body`（14px），不隨 field size 變**——Field size 只影響 input 高度，不影響表單佈局元素的 typography。
+
+**為什麼固定**：label / helper 是跨 Field family 的結構文字；若跟 control size 一起縮放，同一表單會失去一致的 label hierarchy。
 
 ---
 
@@ -110,6 +121,8 @@ Label 在左、control + description + error 在右欄垂直堆疊。Label 與 c
 
 Horizontal 模式下 label 的欄寬由 `labelWidth` prop 控制（任何 CSS length 值），預設 `auto` 由 label 內容撐開。內部用 CSS variable `--field-label-width` 傳給 grid template column。
 
+**硬規則(2026-06-10 codify,user 確認)**:同一表單的多個 horizontal Field **必經 `FieldGroup horizontalLabelWidth` 統一 label 寬**(單行 `labelWidth` 覆寫)——禁各自 `auto` 造成控件起點不對齊(錨例:field.principles 原違反自家 idiom,圖示控件參差)。機制詳下方「FieldGroup horizontalLabelWidth cascade」段。
+
 ---
 
 ## Horizontal 模式 label 垂直對齊
@@ -125,7 +138,7 @@ Horizontal 模式下 label 的欄寬由 `labelWidth` prop 控制（任何 CSS le
 - label 第一行永遠對齊第一個 item 第一行
 - 實作:`padding-top: calc((field-height - 1lh)/2)`
 
-**為什麼分兩套**:曾試 `min-h + flex-center` 統一 → block + 長 label regression(justify-center 失效 + 跟 SelectionItem 公式錯位)。Inline / block 不同對齊語意模型,必分兩套。純 CSS 跨 size/density/字體自動連動,無 JS 測量。對齊 Atlassian DSP / Salesforce Lightning(Polaris 用 baseline 修正,類似)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**為什麼分兩套**:inline / block 是不同的對齊語意模型(固定高度可談整體中線 vs 多行群組只有第一行錨點),必分兩套。純 CSS 跨 size/density/字體自動連動,無 JS 測量。(附註・技術陷阱:曾試 `min-h + flex-center` 統一,出 block + 長 label regression——justify-center 失效 + 跟 SelectionItem 公式錯位,勿再嘗試)
 
 ---
 
@@ -136,7 +149,7 @@ Field 的 control area 有兩種佈局模型,涵蓋所有 control 類型。**核
 | Layout | Control area 樣式 | 適用 control |
 |---|---|---|
 | **inline**(預設) | `min-h-field-{size}` + `flex items-center` | Input / NumberInput / DatePicker / Select / Combobox / LinkInput / Textarea(單行使用)、Checkbox / Switch / 單一 Button(如 upload picker) |
-| **block** | `flex flex-col items-start` + `padding-top: calc((field-height - 1lh) / 2)`,**不設 min-h** | RadioGroup / CheckboxGroup / FileDropzone / RichTextEditor / inline DataTable 等多行/任意高度區塊 |
+| **block** | `flex flex-col items-start`,**不設 min-h、不加 padding-top**(第一行對齊由 block primitive 自帶 py 保證,見「如何宣告 block primitive」) | RadioGroup / CheckboxGroup / FileDropzone / RichTextEditor / inline DataTable 等多行/任意高度區塊 |
 
 ### 兩種模式的對齊幾何
 
@@ -157,11 +170,11 @@ Inline                            Block
 1. 第一個 Radio 往下掉,跟 label 第一行中線錯位
 2. FieldGroup 裡 inline / block field 並排時節奏斷掉
 
-正確做法是「**第一行對齊**」——後續 item 從第一行往下流,label 公式錨在第一行中線。Atlassian DSP / Polaris / Material 都是這個模型。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+正確做法是「**第一行對齊**」——後續 item 從第一行往下流,label 公式錨在第一行中線；如此 label anchor 不會隨 group item 數量改變。
 
 ### 為什麼 primitive 不自己變高
 
-**Checkbox / Switch / RadioGroupItem 的 primitive 保持原生尺寸**(16-20px),不為了 form 而被拉高。世界級系統(shadcn、Radix、Material、Atlassian)全部這樣做。理由: <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**Checkbox / Switch / RadioGroupItem 的 primitive 保持原生尺寸**(16-20px),不為了 form 而被拉高。理由:
 
 1. **Primitive 保持單一職責**——Checkbox 在 table cell、toolbar、menu 裡仍然是 16px,不受 form 高度污染
 2. **高度節奏由 Field 容器提供**——一次設定,所有 primitive 在任何 size / density 都自動對齊
@@ -181,7 +194,7 @@ block / inline 是**元件固有性質**(RadioGroup 永遠 block,Input 永遠 in
 ;(RadioGroup as unknown as { fieldLayout: 'block' }).fieldLayout = 'block'
 ```
 
-Field render 時讀第一個 control child 的 `type.fieldLayout`,缺則 `'inline'`。Consumer 完全無感(`<Field><RadioGroup>...</RadioGroup></Field>` 自動切 block)。
+Field render 時迭代**全部** control child 的 `type.fieldLayout`,**任一**宣告為 `'block'` 即整個 area 切 block(first-block-wins);全部缺宣告則 `'inline'`。Consumer 完全無感(`<Field><RadioGroup>...</RadioGroup></Field>` 自動切 block)。
 
 **為什麼這機制**:Consumer 傳 prop 易忘 → 歪;Field 內寫死白名單 → 跟 primitive 名稱耦合。Primitive 自宣告 = Field 0 耦合,新增 block primitive 只在自己檔案加 1 行。
 
@@ -189,7 +202,7 @@ Field render 時讀第一個 control child 的 `type.fieldLayout`,缺則 `'inlin
 
 **第一行對齊責任**:Field 的 block control area **不加 paddingTop**(避免跟 RadioGroup 自帶 `py = calc((field-height - 1lh) / 2)` double)。需 label 對齊的 block primitive 自行保證第一行位置(RadioGroup/CheckboxGroup 自帶 ✓;FileDropzone/RichTextEditor 自管)。
 
-**已宣告 block**:`RadioGroup`。新增 `CheckboxGroup` / `FileDropzone` 等同模式加 `fieldLayout = 'block'`。
+**已宣告 block**:`RadioGroup`、`CheckboxGroup`(checkbox-group.tsx:93)。新增 `FileDropzone` 等同模式加 `fieldLayout = 'block'`。
 
 ---
 
@@ -202,7 +215,7 @@ Field 透過 Context 暴露以下狀態給子元件（Primitive 可以透過 `us
 | `id` | FieldLabel 自動 `htmlFor`、Input 自動 `id` |
 | `descriptionId` | FieldDescription 的 id，Input 自動 `aria-describedby` |
 | `errorId` | FieldError 的 id，Input 自動 `aria-errormessage` |
-| `mode` | `edit` / `readonly` / `disabled`，Control 決定自己的視覺形態 |
+| `mode` | `edit` / `view` / `readonly` / `disabled`，Control 決定自己的視覺形態 |
 | `disabled` | Control 顯示 disabled 樣式 |
 | `required` | FieldLabel 自動渲染 `*`；Input 自動 `aria-required` |
 | `invalid` | Control 顯示 error 邊框；Input 自動 `aria-invalid` |
@@ -210,6 +223,12 @@ Field 透過 Context 暴露以下狀態給子元件（Primitive 可以透過 `us
 | `orientation` | FieldLabel 的垂直對齊策略（horizontal 模式套用 padding-top 公式） |
 | `hasFieldWrapper` | Primitive 讀到此旗標時應忽略自己的 label / description prop，由 FieldLabel / FieldDescription 接管 |
 
+### Control 偏好尺寸（`fieldPreferredSize`）SSOT
+
+Field 未收到顯式 `size` 時，依序取 **顯式 prop → control 宣告的 `fieldPreferredSize` → `md`**（`field.tsx` `detectPreferredSize`）。Control 以自身檔案的 static 宣告偏好（唯一現行宣告者 = InlineEdit `'sm'`，owner 句 `InlineEdit/inline-edit.spec.md`）。
+
+**解析時序**：control 是 Field 的直接子元件時，Field 可同步讀取 static 偏好。wrapper 元件、`React.memo` 或 HOC 會遮蔽 static，但 control 會在掛載時透過 `useRegisterFieldPreferredSize` 補註冊：control 自身以 fallback 同步解析為偏好尺寸，Field 的控件槽高度則在註冊後跟上。Consumer 在 Field 或 control 顯式傳入的 `size` 永遠優先，不會被註冊覆寫。
+
 ### Primitive 的 Field-aware 行為
 
 **Checkbox / Switch / RadioItem** 等 primitive 自己有 `label` / `description` props 可用於**獨立使用場景**（不在 Field 內），但在 Field context 內時：
@@ -243,7 +262,15 @@ Field 透過 Context 暴露以下狀態給子元件（Primitive 可以透過 `us
 - Disabled 時星號改為 `text-fg-disabled`（neutral-6），與 label 同步降色
 - 個別 FieldLabel 可用 `required` prop 覆寫 context 值
 
-**為什麼貼齊無 gap**：星號是 label 語意的一部分（WCAG 友善——screen reader 先讀 required 再讀 label），不是獨立視覺元素，所以不需要間距。
+**為什麼貼齊無 gap**:星號是 label 語意的一部分,不是獨立視覺元素,所以不需要間距(星號本身 `aria-hidden`,SR 的 required 資訊由控件 `aria-required` 承擔——見「A11y 預設」段)。
+
+## FieldLabel `info` icon(2026-06-10 文件化,對齊 field.tsx 既有實作)
+
+label 文字後可帶 info icon(ℹ)hover 出 tooltip 補充說明:`<FieldLabel info="說明文字">`。
+
+- **與 label 間距 `gap-1`(4px)**、InfoIcon **16px 固定**、色 `fg-muted` hover `fg-secondary`(field.tsx L391-416)
+- **disabled 時整顆不渲染**(L403)— info 是 action affordance(hover 互動),非類型身份 indicator,non-editable 隱藏
+- 設計定位:inline action pattern(補充工具,視覺退後)— label 的 primary interaction 是 input,info 是輔助
 
 ---
 
@@ -274,7 +301,7 @@ Field 透過 Context 暴露以下狀態給子元件（Primitive 可以透過 `us
 </FieldGroup>
 ```
 
-gap 三個語意層級(具體 gap token 見 `field.tsx` cva):
+gap 三個語意層級(具體 gap class map 見 `field.tsx` FieldGroup,`compact`→`gap-3` / `normal`→`gap-4` / `loose`→`gap-6`):
 
 | gap | 用途 |
 |---|---|
@@ -286,7 +313,7 @@ gap 三個語意層級(具體 gap token 見 `field.tsx` cva):
 
 同一畫面 / 同一 FieldGroup 內多個 horizontal Field **必須共用 label 欄寬度**。若每個 Field 各自傳 `labelWidth`(或省略 → 內容撐開),label 寬度會參差不齊,Switch / Input 的左邊緣不對齊,視覺上每一行「歪七扭八」。
 
-**世界級 idiom**:macOS System Settings / iOS Settings / GitHub Settings / Notion preferences / Figma 偏好設定——setting list 的 label 全部固定寬、control 全部右對齊,列與列對齊成可掃描的欄位格網。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+Setting list 的 label 欄固定寬、control 欄右對齊，使列與列形成可掃描的欄位格網；label 長度不得逐列改變 control 起點。
 
 `FieldGroup horizontalLabelWidth` 透過 React Context cascade 到所有子 Field(含 `vertical` 模式的 Field 不受影響——vertical 無 label 欄概念)。單一 Field 仍可用自己的 `labelWidth` prop 覆寫 group 預設(罕見 — 通常 group 預設就是 canonical)。
 
@@ -320,6 +347,13 @@ Button 的 height 與 `field-height` 共用同一組 token,放進 inline control
 
 ---
 
+## 邊界案例
+
+- **空 Field(無 control children)**:code 不擋——control area 渲染成空容器。Field 是佈局容器,無 control 即無意義,屬 consumer 誤用
+- **RTL**:不支援；全域 LTR-only compatibility contract 見 `packages/design-system/README.md#compatibility-matrix`。horizontal label / suffix alignment 不在本檔另立支援決策。
+
+---
+
 ## 禁止事項
 
 - ❌ 不得在 Field 內再包 Field——Field 不支援巢狀
@@ -344,7 +378,7 @@ Field 內的資料輸入控件（Input / NumberInput / DatePicker / Select / Com
 - **表單欄位的 label + control + description + error 標準佈局**：登入表單、設定頁、建立對話框
 - **需要 required 星號、disabled 狀態、invalid 驗證的統一行為**
 - **需要 `horizontal` / `vertical` 排版切換**：設定頁常用 horizontal（label 左 / control 右）
-- **多欄位垂直堆疊**：搭配 `FieldGroup` 管理 density-aware 間距
+- **多欄位垂直堆疊**：搭配 `FieldGroup` 統一管理欄位垂直間距（三級固定值 `compact` / `normal` / `loose`，刻意不隨 density 縮放；具體 gap map 見上方 gap 表）
 
 ## 何時不用
 
@@ -353,37 +387,36 @@ Field 內的資料輸入控件（Input / NumberInput / DatePicker / Select / Com
 | 唯讀資訊展示 | `DescriptionList` | Field 是表單容器，純展示用 `dl/dt/dd` 語義 |
 | 單一 Checkbox（勾選同意）without label 結構 | 直接 Checkbox + label prop | 單個 Checkbox 是 inline primitive，不需要 Field 佈局 |
 | DataTable cell 編輯（inline editable）| 直接放 Field Control | Field 是頁面表單佈局，table cell 空間受限 |
+| 把 Field 當輸入元件本身（常見誤解：「Field = form 輸入框」）| `Input` 等 Field Control | Field 只管佈局 + context，輸入行為住在 control（見「與 Field Controls 的職責切分」）|
 | 純 action 按鈕（submit / cancel / 頁面導覽）| 頁面 footer / toolbar | Field 是資料輸入容器，不放頁面級 action |
 | 巢狀 Field | ❌ 不支援 | Field 不支援巢狀，多欄位用 FieldGroup |
 
 ---
 
-## 為何無 Inspector
+## Anatomy stories
 
-Field 是**表單欄位容器**(label + helper + control + error 的佈局包裝),設計決策維度是 `orientation`(vertical / horizontal)× `size`(sm/md/lg)× `state`(required / invalid / disabled / readonly)× `color`——已由 `OrientationMatrix` / `SizeMatrix` / `StateBehavior` / `ColorMatrix` + 元件特有 `FieldGroupBehavior` 五張結構矩陣完整覆蓋。
-
-Inspector 對 container 類元件沒有對應教學價值——Field 本身不產生互動 affordance(互動由 Field Control 例如 Input / Select 處理),該 Inspect 的是 Field Control layer(已有各自元件的 Inspector)。重寫 Inspector = 複製 Input / Select 的 Inspector。
-
-對應 anatomy story:保留 `Overview` + `OrientationMatrix` + `SizeMatrix` + `StateBehavior` + `ColorMatrix` + 元件特有 `FieldGroupBehavior`。
+對應 anatomy story:`Overview` + `Inspector`(元件檢閱器——切 orientation / size / mode / required / invalid 即時 render)+ `OrientationMatrix` + `SizeMatrix` + `StateBehavior` + `ColorMatrix` + 元件特有 `FieldGroupBehavior` + `Accessibility`。
 
 ---
 
 ## Field state machine SSOT(v13.3)
 
-**Canonical**:**focus dominates everything**(M11 延伸:focus 勝 hover/open/error-rest)。Cursor in input = user 編輯中 = 永遠藍。對齊 Material 3 / Polaris / Ant Design 5 共識。SSOT 在 `field-wrapper.tsx` 三 compoundVariant — 改一處全 control + cell + 各 variant 跟動。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**Canonical**(2026-07-04 Q1 拍板修訂):**focus dominates everything — 除 error**。無 error 時 cursor in input = 藍;**有 error 時聚焦維持紅**(error 勝 focus 的「顏色」通道;修錯中不可失去 error 訊號)。開始編輯 → edit-clears-error(`useFormValidation`)→ 自然回 focus 藍。Benchmark 實查:MUI(error+focused 紅框加粗,OutlinedInput.js error rule 排 focused 後)/ Ant 5(`activeBorderColor: colorError` 紅框紅 glow,input/style/variants.ts)/ Polaris(紅 border 聚焦持續 + 獨立藍 outline,TextField.module.css)三家聚焦時 error 紅皆保留;唯一切藍的 Carbon 靠 in-field 紅 icon 補償(DS 無此通道故不採)。SSOT 全在 `field-wrapper.tsx` compoundVariants(**含 error** — 2026-07-04 起 `error` 為 cva 變體,原逐 control `border-error` 系列已 retire,控件只傳 `error` flag)。
 
 | State | Token | CSS |
 |---|---|---|
 | rest | `--border` | `border-border` |
 | hover(無 focus)| `--border-hover` | `hover:border-border-hover` |
-| **focus** | `--primary` | **`focus-within:!border-primary`**(`!important` 勝 data-state)|
+| **focus(無 error)** | `--primary` | **`focus-within:!border-primary`**(error:false compound;`!important` 勝 data-state)|
 | focus + hover | `--primary` | `focus-within:hover:!border-primary`(M11 AND case)|
 | open(無 focus)| `--border-hover` | `data-[state=open]:border-border-hover` |
-| error | `--error` | `focus-within:border-error focus-within:hover:border-error` |
+| **error(edit 全程,含聚焦)** | `--error` | `border-error hover:border-error-hover focus-within:!border-error focus-within:hover:!border-error`(error:true compound)|
+
+**Error × focus 疊加 canonical(2026-07-05 user 拍板「照 Mantine」)**:錯誤欄位聚焦時**視覺完全不變**(紅框同色同寬,無加深/加粗/ring/暈)。依據:DS 聚焦主機制 =「邊框換 primary 基準色、無第二訊號」,12 家實查中唯一同款機制的 Mantine(Input.module.css:focus 僅 border 換 primary-filled、outline none)在此題同樣選擇不變;保紅又加訊號的三家(MUI 粗 / Ant 暈 / Bootstrap 暈)前提是其一般聚焦本來就有該第二訊號可染紅,DS 無此前提。**已知代價(documented tradeoff,非 bug)**:無游標的觸發器(Select / DatePicker / TimePicker)error 聚焦時無視覺聚焦指示(文字框靠游標);Mantine 同款弱點。未來若升級全 DS 聚焦語言(一般態加第二訊號),本題應同步重議(錯誤態染紅該訊號,對齊 MUI/Ant/Bootstrap 結構)。D4 finding「error+focus 零 focus delta」據此結案為 user-拍板 intentional。
 
 副作用(自動達成 Ant「選後藍 / 取消灰」):選 option → Radix `onCloseAutoFocus` return focus → focus-within fires → 藍 / 點外取消 → focus 移外 → 灰。純 focus 機制無需 transient class。
 
-**反模式 ❌**:per-control `open && 'border-primary'`(Combobox/Select/PeoplePicker)/ `data-[state=open]:border-primary` — 已 v13.3 全 retire。`hook check_field_state_token_consume` write-time 攔。
+**反模式 ❌**:per-control `open && 'border-primary'`(Combobox/Select/PeoplePicker)/ `data-[state=open]:border-primary` — 已 v13.3 全 retire。hook `check_field_family_invariants.sh` A.3(原 check_field_state_token_consume)write-time 攔。
 
 ---
 
@@ -398,15 +431,15 @@ Inspector 對 container 類元件沒有對應教學價值——Field 本身不
 | **L1 Slot** | `patterns/element-anatomy/item-anatomy.tsx` | `<ItemPrefix>` / `<ItemSuffix>`(永遠 `h-[1lh]` 對齊第 1 行) |
 | **L2 Align** | `field-wrapper.tsx` `nakedCellRowModeAlign` | host cell `data-row-mode` propagate(autoRow→items-start / fixed→items-center)|
 | **L3 State machine** | **繼承 Field default v13.3**(↑ 上方 SSOT)| 不重定義 |
-| **L4 Display hover** | `field-wrapper.tsx` `nakedCellEditableDisplayHover` | editable cell display mode `outline-1 outline-offset:-1 outline-[var(--border-hover)]`(cell wrapper outline)。**v15.13 design intent(user-accepted 2026-05-07)**:hover ring 蓋 cell.borderRight。**known asymmetry**(2026-05-09 user 重抓):只 **right** 邊 outline 跟 cell own border-r 同位置覆蓋成 1 條;top/left/bottom 邊 outline 在 cell.outer 內 1px,grid lines(前 row border-b / 前 cell border-r / row 自己 border-b 在 cell.outer 外 1px)露出 → 視覺 4 邊不對稱。**Pending design decision**(等 user 拍板才 ship):4 邊都蓋(spec 1 selection-style)vs 4 邊都不蓋(spec 2 inset 1px)vs 維持現狀。三層 SSOT:state source = cell wrapper / paint owner = 混合(hover=cell / edit=Field)/ grid divider = DataTable own |
+| **L4 Display hover** | `field-wrapper.tsx` `nakedCellEditableDisplayHover` | editable cell view mode `outline-1 outline-offset:-1 outline-[var(--cell-hover-outline-color,var(--border-hover))]`(cell wrapper outline;2026-05-10 Slice D:spreadsheet overlay 啟用時 DataTable cell host 可 set `--cell-hover-outline-color: transparent` 抑制 outline、讓 overlay layer 接管 hover ring paint,fallback 即 `--border-hover` 既有行為不變)。**v15.13 design intent(user-accepted 2026-05-07)**:hover ring 蓋 cell.borderRight。**known asymmetry**(2026-05-09 user 重抓):只 **right** 邊 outline 跟 cell own border-r 同位置覆蓋成 1 條;top/left/bottom 邊 outline 在 cell.outer 內 1px,grid lines(前 row border-b / 前 cell border-r / row 自己 border-b 在 cell.outer 外 1px)露出 → 視覺 4 邊不對稱。**Pending design decision**(等 user 拍板才 ship):4 邊都蓋(spec 1 selection-style)vs 4 邊都不蓋(spec 2 inset 1px)vs 維持現狀。三層 SSOT:state source = cell wrapper / paint owner = 混合(hover=cell / edit=Field)/ grid divider = DataTable own |
 | **L5 Position(v14,2026-05-06 revert v12)** | naked compoundVariant flow | Field 留 layout flow,**不**用 `!absolute`(v12 absolute 跟 autoRowHeight 不相容)。視覺接受 cell `border-r grid` + Field border 2px 雙線;cell border-r divider 永遠保留(對齊 L4 Invariant divider-owner / editor-owner 分離)|
-| **L6 Cell trigger indicator(v15,2026-05-09)** | naked-display branch + `showDisplayEndIcon?: boolean` opt-in | DataTable cell-registry 顯式傳 `showDisplayEndIcon` → Field component 內部 `<ItemSuffix>` 渲對應 trigger icon(Select/Combobox/PeoplePicker → ChevronDown / DatePicker → CalendarIcon / TimePicker → Clock / LinkInput 例外無 suffix)。table 外用法不傳此 prop = 純展示無 icon。詳 `.claude/planning/cell-indicator-ssot-rfc.md`。|
+| **L6 Cell trigger indicator(v16,2026-07-08 user 拍板 A 案)** | naked-view branch + `showDisplayEndIcon?: boolean` opt-in(**default off,production 不再傳**)| **view 態零恆顯型別 icon** — editable affordance 統一 = L4 hover outline。Benchmark 6/6(Ant editable-cells 純文字+hover border / MUI X singleSelect view 純文字 https://mui.com/x/react-data-grid/editing/ / AG Grid 無內建 indicator https://www.ag-grid.com/react-data-grid/cell-editing/ / Atlaskit v2.0.0 移除 hover-pencil 後 9 版未回歸 https://github.com/pioug/atlassian-frontend-mirror/tree/main/design-system/inline-edit / Notion / Airtable click-to-edit)view 態皆無恆顯 icon;唯一反例 Google Sheets Chip/Arrow 為 spreadsheet 域可選檔位。prop 保留為 spreadsheet-flavored 消費端 opt-in 逃生門:傳 true → `<ItemSuffix>` 渲型別 icon(Select/Combobox/PeoplePicker → ChevronDown / DatePicker → Calendar / TimePicker → Clock / **LinkInput 例外 = wrapper-only 無 icon**)。cell-registry 現況:6 picker 站不傳;url 站傳 `isEditable === true`(取 wrapper chrome 對齊 edit Input,非 icon)。edit 態 chevron 照舊(edit-trigger 通道,不受此 prop 管)。**值內容 vs affordance 分層(2026-07-08 user Q2 拍板)**:值內容(`selectedItemRenderer` 輸出 / avatar / type icon 等語意呈現)歸 value renderer,view 態照常渲染,恆顯**不**違反本條;本條管的是 affordance(chevron / pencil / outline)。前身 v15 恆顯制(2026-05-10/06-26 拍板)由本輪 benchmark 重判推翻。詳 `.claude/planning/cell-indicator-ssot-rfc.md`(六家實查 SSOT)。|
 
 **前身 retire**:v4-v8 `outline-2` 平行 state(已下沉 L3)/ v9 border-only(focus 跟 open specificity tie)/ per-control `open && 'border-primary'`(v13.3 retire)/ `nakedCell{Hover,Focus,Open}Ring` 三 const / `nakedCell{Prefix,Suffix}Slot`(下沉 L1)/ **v12 `!absolute -inset-px` seamless grid**(2026-05-06 revert — autoRowHeight 不相容)/ **DataTable parallel `getEditIndicator`**(2026-05-09 D-path retire — 由 Field naked-display 透過 `showDisplayEndIcon` opt-in 自渲 ItemSuffix,跨元件 SSOT 統一)。
 
 **反模式 ❌**:naked 自寫 `outline-*` / `box-shadow inset` state ring(用 L3) / hardcode `<span h-[1lh]>` slot(用 L1)/ hardcode `items-center`(用 L2)/ per-control `open && 'border-primary'`(用 L3 SSOT)。
 
-**機械防漂移**:hooks `check_naked_row_mode_propagation` / `check_field_state_token_consume`(v13 升級)/ `check_inline_action_canonical_gap` / `check_row_slot_handcraft`(write-time)+ audit `/design-system-audit` Group N M36-M39。
+**機械防漂移**:hooks `check_field_family_invariants.sh`(A.1 naked row-mode propagation / A.3 Field state ring SSOT,原 standalone hooks 已 folded)+ `check_pattern_invariants.sh`(C.2 inline-action canonical gap / C.4 row slot handcraft)write-time 攔 + `/design-system-audit` 對應 audit dim。
 
 ## 相關
 
@@ -414,18 +447,19 @@ Inspector 對 container 類元件沒有對應教學價值——Field 本身不
 - `./form-validation.spec.md` — 表單驗證標準（blur 驗證、zod schema、error 顯示）
 - `../DescriptionList/description-list.spec.md` — 唯讀資訊展示（非表單）
 - `../../patterns/element-anatomy/item-anatomy.spec.md` — SelectionItem 佈局（Checkbox / Radio 放進 Field 時 block 模式的參照）
-- CLAUDE.md「元件 Props 命名原則」— Field 的 orientation / block control 宣告規則
 
 ## A11y 預設
 
 **ARIA / Pattern**:對齊 [W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/) 對應 pattern。
 
-**Keyboard 行為**:
+**Keyboard 行為**:Field 是純排版容器,不擁有任何鍵盤 handler,鍵盤行為全由內部 control 接管。
+
+- Tab — focus 移進內部 control(Input / Select / DatePicker 等)
+- Esc 取消編輯等行為由 control 本身或放置它的 host(如 DataTable cell)實作,**不在 Field**
 
-- Tab — focus internal control(Input / Select / DatePicker 等)
-- Esc — 取消 edit mode(若 cell-as-input)
+**Focus**:focus-visible ring 對齊 DS canonical(`outline: 2px solid var(--ring)`);Field 不搶焦點,focus 由內部 control 自管。
 
-**Focus**:focus-visible ring 對齊 DS canonical(`outline: 2px solid var(--ring)`);focus management 由元件 own。
+**SR 識別路徑**(由既有 aria 接線達成,見「FieldContext」與「驗證與 aria 屬性」段):focus 進 control 時 SR 可得完整資訊——label(`htmlFor`/`id` 連結)、required(control 的 `aria-required`)、invalid(`aria-invalid`)、description(`aria-describedby`)、error(`aria-errormessage`;`<FieldError role="alert">` 另在錯誤出現時即時播報)。required 星號本身 `aria-hidden`,SR 資訊來自 `aria-required` 非 `*` 字元。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
@@ -433,6 +467,14 @@ Inspector 對 container 類元件沒有對應教學價值——Field 本身不
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `data-table.spec.md`
+- `description-list.spec.md`
 - `element-anatomy.spec.md`
+- `field-control-group.spec.md`
+- `field-controls.spec.md`
+- `form-validation.spec.md`
+- `inline-edit.spec.md`
+- `input.spec.md`
 - `radio-group.spec.md`
+- `steps.spec.md`
 - `switch.spec.md`