@qijenchen/design-system 0.1.0-beta.85 → 0.1.0-beta.86

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

@@ -4,7 +4,7 @@ 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, FieldError, FieldGroup } from './field'
+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'
@@ -141,33 +141,10 @@ export const UsageGuidance: Story = {
   ),
 }
 
-export const ResponsibilityRule: Story = {
-  name: 'Field 只負責佈局,不管資料',
-  render: () => (
-    <div>
-      <Rule
-        title="Field 的職責 — Layout + Context,不擁有資料邏輯"
-        note="Field 只負責:label / control / description / error 的空間關係 + 把 mode / disabled / required / invalid / id 透過 context 傳給子元件。與資料相關的一切(格式化、驗證、readonly 呈現、DataTable cell 顯示)住在 Field Control 元件本身"
-      >
-        <div className="max-w-sm">
-          <FieldGroup>
-            <Field required>
-              <FieldLabel>電子郵件</FieldLabel>
-              <Input type="email" placeholder="name@example.com" />
-              <FieldDescription>我們不會公開您的電子郵件</FieldDescription>
-            </Field>
-            <Field invalid>
-              <FieldLabel>密碼</FieldLabel>
-              <Input type="password" />
-              <FieldError>密碼必須至少 8 個字元</FieldError>
-            </Field>
-          </FieldGroup>
-        </div>
-        <Label>↑ Field 管 layout + required 星號 + error 顯示,Input 管 type=email / 驗證邏輯</Label>
-      </Rule>
-    </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: '方向 選擇',

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

@@ -32,7 +32,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 三態 + 格式化(`mode="display"` 渲染供 DataTable cell 共用)
+- **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`。
 
@@ -206,7 +206,7 @@ Field 透過 Context 暴露以下狀態給子元件（Primitive 可以透過 `us
 | `id` | FieldLabel 自動 `htmlFor`、Input 自動 `id` |
 | `descriptionId` | FieldDescription 的 id，Input 自動 `aria-describedby` |
 | `errorId` | FieldError 的 id，Input 自動 `aria-errormessage` |
-| `mode` | `edit` / `display` / `readonly` / `disabled`，Control 決定自己的視覺形態 |
+| `mode` | `edit` / `view` / `readonly` / `disabled`，Control 決定自己的視覺形態 |
 | `disabled` | Control 顯示 disabled 樣式 |
 | `required` | FieldLabel 自動渲染 `*`；Input 自動 `aria-required` |
 | `invalid` | Control 顯示 error 邊框；Input 自動 `aria-invalid` |
@@ -416,9 +416,9 @@ Field 內的資料輸入控件（Input / NumberInput / DatePicker / Select / Com
 | **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(--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 |
+| **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(v16,2026-07-08 user 拍板 A 案)** | naked-display branch + `showDisplayEndIcon?: boolean` opt-in(**default off,production 不再傳**)| **display 態零恆顯型別 icon** — editable affordance 統一 = L4 hover outline。Benchmark 6/6(Ant editable-cells 純文字+hover border / MUI X singleSelect display 純文字 / AG Grid 無內建 indicator / Atlaskit v2.0.0 移除 hover-pencil 後 9 版未回歸 / Notion / Airtable click-to-edit)display 態皆無恆顯 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,display 態照常渲染,恆顯**不**違反本條;本條管的是 affordance(chevron / pencil / outline)。前身 v15 恆顯制(2026-05-10/06-26 拍板)由本輪 benchmark 重判推翻。詳 `.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 統一)。
 

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

@@ -91,21 +91,21 @@ export const StateCascade: Story = {
           <Field mode="readonly" className="w-44"><FieldLabel>負責人</FieldLabel><Input value="王小明" onChange={() => {}} /></Field>
           <Field mode="readonly" className="w-44"><FieldLabel>同意條款</FieldLabel><Checkbox checked /></Field>
           <Field mode="readonly" className="w-44"><FieldLabel>已啟用</FieldLabel><Switch checked /></Field>
-          <Field mode="readonly" className="w-44"><FieldLabel>未勾選範例</FieldLabel><Checkbox /></Field>
+          <Field mode="readonly" className="w-44"><FieldLabel>行銷電子報</FieldLabel><Checkbox /></Field>
           <Field mode="readonly" className="w-44"><FieldLabel>付款方式</FieldLabel><RadioGroup value="card"><RadioGroupItem value="card" label="信用卡" /><RadioGroupItem value="cash" label="貨到付款" /></RadioGroup></Field>
           <Field mode="readonly" className="w-44"><FieldLabel>滿意度</FieldLabel><Rating value={4} aria-label="滿意度" /></Field>
           <Field mode="readonly" className="w-44"><FieldLabel>完成度</FieldLabel><Slider defaultValue={[40]} aria-label="完成度" /></Field>
         </div>
       </div>
       <div>
-        <p className="text-body-sm font-medium text-fg-secondary mb-3">{'<Field mode="display"> — 有展示態的控件自動切純展示（Select / DatePicker / Checkbox / Switch 修復後生效）'}</p>
+        <p className="text-body-sm font-medium text-fg-secondary mb-3">{'<Field mode="view"> — 有展示態的控件自動切純展示（Select / DatePicker / Checkbox / Switch 修復後生效）'}</p>
         <div className="flex flex-wrap gap-x-8 gap-y-4 max-w-3xl">
-          <Field mode="display" className="w-44"><FieldLabel>負責人</FieldLabel><Input value="王小明" onChange={() => {}} /></Field>
-          <Field mode="display" className="w-44"><FieldLabel>優先級</FieldLabel><Select options={CASCADE_PRIORITY} value="high" aria-label="優先級" /></Field>
-          <Field mode="display" className="w-44"><FieldLabel>截止日</FieldLabel><DatePicker value="2026-06-20" onChange={() => {}} /></Field>
-          <Field mode="display" className="w-44"><FieldLabel>數量</FieldLabel><NumberInput value={42} onChange={() => {}} /></Field>
-          <Field mode="display" className="w-44"><FieldLabel>已啟用</FieldLabel><Switch checked /></Field>
-          <Field mode="display" className="w-44"><FieldLabel>同意條款</FieldLabel><Checkbox checked /></Field>
+          <Field mode="view" className="w-44"><FieldLabel>負責人</FieldLabel><Input value="王小明" onChange={() => {}} /></Field>
+          <Field mode="view" className="w-44"><FieldLabel>優先級</FieldLabel><Select options={CASCADE_PRIORITY} value="high" aria-label="優先級" /></Field>
+          <Field mode="view" className="w-44"><FieldLabel>截止日</FieldLabel><DatePicker value="2026-06-20" onChange={() => {}} /></Field>
+          <Field mode="view" className="w-44"><FieldLabel>數量</FieldLabel><NumberInput value={42} onChange={() => {}} /></Field>
+          <Field mode="view" className="w-44"><FieldLabel>已啟用</FieldLabel><Switch checked /></Field>
+          <Field mode="view" className="w-44"><FieldLabel>同意條款</FieldLabel><Checkbox checked /></Field>
         </div>
       </div>
     </div>
@@ -143,7 +143,7 @@ export const Horizontal: Story = {
 // ── Horizontal 垂直對齊公式驗證 ─────────────────────────────────────────
 
 export const HorizontalLabelAlignment: Story = {
-  name: '水平:標籤垂直對齊公式驗證',
+  name: '水平:標籤與控件垂直對齊',
   render: () => (
     <div className="max-w-3xl flex flex-col gap-8">
       <div>
@@ -153,8 +153,8 @@ export const HorizontalLabelAlignment: Story = {
           這是 padding-top: calc((field-height - 1lh) / 2) 的基本情境。
         </p>
         <Field orientation="horizontal" labelWidth="160px">
-          <FieldLabel>短 label</FieldLabel>
-          <Input placeholder="input 中線應與 label 對齊" />
+          <FieldLabel>職稱</FieldLabel>
+          <Input placeholder="如:資深產品設計師" />
         </Field>
       </div>
 
@@ -165,8 +165,8 @@ export const HorizontalLabelAlignment: Story = {
           視覺上 label 從 input 中線往下延伸，而不是從 input 頂部開始。
         </p>
         <Field orientation="horizontal" labelWidth="160px">
-          <FieldLabel>這是一個會換行的很長的 label 用來驗證多行情境</FieldLabel>
-          <Input placeholder="input 中線應與 label 第一行對齊" />
+          <FieldLabel>緊急聯絡人手機(發生狀況時優先撥打)</FieldLabel>
+          <Input placeholder="如:0912-345-678" />
         </Field>
       </div>
 
@@ -177,18 +177,27 @@ export const HorizontalLabelAlignment: Story = {
           無需 JS 測量。
         </p>
         <div className="flex flex-col gap-3">
-          <Field orientation="horizontal" labelWidth="100px" size="sm">
-            <FieldLabel>sm size</FieldLabel>
-            <Input size="sm" placeholder="28px high" />
-          </Field>
-          <Field orientation="horizontal" labelWidth="100px" size="md">
-            <FieldLabel>md size</FieldLabel>
-            <Input size="md" placeholder="32px high" />
-          </Field>
-          <Field orientation="horizontal" labelWidth="100px" size="lg">
-            <FieldLabel>lg size</FieldLabel>
-            <Input size="lg" placeholder="36px high" />
-          </Field>
+          <div>
+            <div className="text-caption text-fg-muted mb-1">小尺寸 sm — 控件高 28px</div>
+            <Field orientation="horizontal" labelWidth="100px" size="sm">
+              <FieldLabel>電子郵件</FieldLabel>
+              <Input size="sm" placeholder="name@example.com" />
+            </Field>
+          </div>
+          <div>
+            <div className="text-caption text-fg-muted mb-1">中尺寸 md — 控件高 32px</div>
+            <Field orientation="horizontal" labelWidth="100px" size="md">
+              <FieldLabel>電子郵件</FieldLabel>
+              <Input size="md" placeholder="name@example.com" />
+            </Field>
+          </div>
+          <div>
+            <div className="text-caption text-fg-muted mb-1">大尺寸 lg — 控件高 36px</div>
+            <Field orientation="horizontal" labelWidth="100px" size="lg">
+              <FieldLabel>電子郵件</FieldLabel>
+              <Input size="lg" placeholder="name@example.com" />
+            </Field>
+          </div>
         </div>
       </div>
     </div>
@@ -279,31 +288,40 @@ export const SegmentedControlInField: Story = {
           整個欄位改尺寸時,分段控制器也會跟著一起縮放。
         </p>
         <FieldGroup>
-          <Field size="sm">
-            <FieldLabel>檢視模式（sm）</FieldLabel>
-            <SegmentedControl defaultValue="list">
-              <SegmentedControlItem value="list">清單</SegmentedControlItem>
-              <SegmentedControlItem value="board">看板</SegmentedControlItem>
-              <SegmentedControlItem value="calendar">行事曆</SegmentedControlItem>
-            </SegmentedControl>
-            <FieldDescription>切換內容呈現方式</FieldDescription>
-          </Field>
-          <Field size="md">
-            <FieldLabel>檢視模式（md）</FieldLabel>
-            <SegmentedControl defaultValue="list">
-              <SegmentedControlItem value="list">清單</SegmentedControlItem>
-              <SegmentedControlItem value="board">看板</SegmentedControlItem>
-              <SegmentedControlItem value="calendar">行事曆</SegmentedControlItem>
-            </SegmentedControl>
-          </Field>
-          <Field size="lg">
-            <FieldLabel>檢視模式（lg）</FieldLabel>
-            <SegmentedControl defaultValue="list">
-              <SegmentedControlItem value="list">清單</SegmentedControlItem>
-              <SegmentedControlItem value="board">看板</SegmentedControlItem>
-              <SegmentedControlItem value="calendar">行事曆</SegmentedControlItem>
-            </SegmentedControl>
-          </Field>
+          <div>
+            <div className="text-caption text-fg-muted mb-1">小尺寸 sm</div>
+            <Field size="sm">
+              <FieldLabel>檢視模式</FieldLabel>
+              <SegmentedControl defaultValue="list">
+                <SegmentedControlItem value="list">清單</SegmentedControlItem>
+                <SegmentedControlItem value="board">看板</SegmentedControlItem>
+                <SegmentedControlItem value="calendar">行事曆</SegmentedControlItem>
+              </SegmentedControl>
+              <FieldDescription>切換內容呈現方式</FieldDescription>
+            </Field>
+          </div>
+          <div>
+            <div className="text-caption text-fg-muted mb-1">中尺寸 md</div>
+            <Field size="md">
+              <FieldLabel>檢視模式</FieldLabel>
+              <SegmentedControl defaultValue="list">
+                <SegmentedControlItem value="list">清單</SegmentedControlItem>
+                <SegmentedControlItem value="board">看板</SegmentedControlItem>
+                <SegmentedControlItem value="calendar">行事曆</SegmentedControlItem>
+              </SegmentedControl>
+            </Field>
+          </div>
+          <div>
+            <div className="text-caption text-fg-muted mb-1">大尺寸 lg</div>
+            <Field size="lg">
+              <FieldLabel>檢視模式</FieldLabel>
+              <SegmentedControl defaultValue="list">
+                <SegmentedControlItem value="list">清單</SegmentedControlItem>
+                <SegmentedControlItem value="board">看板</SegmentedControlItem>
+                <SegmentedControlItem value="calendar">行事曆</SegmentedControlItem>
+              </SegmentedControl>
+            </Field>
+          </div>
         </FieldGroup>
       </div>
 
@@ -478,23 +496,35 @@ export const LabelWidth: Story = {
   name: '標籤寬度',
   render: () => (
     <div className="max-w-2xl flex flex-col gap-4">
-      <p className="text-caption text-fg-muted">labelWidth 支援任何 CSS length 值</p>
-      <Field orientation="horizontal" labelWidth="80px">
-        <FieldLabel>80px</FieldLabel>
-        <Input placeholder="short label column" />
-      </Field>
-      <Field orientation="horizontal" labelWidth="160px">
-        <FieldLabel>160px（預設常用）</FieldLabel>
-        <Input placeholder="typical settings form" />
-      </Field>
-      <Field orientation="horizontal" labelWidth="240px">
-        <FieldLabel>240px（寬 label 欄）</FieldLabel>
-        <Input placeholder="wide label column" />
-      </Field>
-      <Field orientation="horizontal" labelWidth="30%">
-        <FieldLabel>30%（比例）</FieldLabel>
-        <Input placeholder="percentage" />
-      </Field>
+      <p className="text-caption text-fg-muted">labelWidth 支援任何 CSS length 值(80px / 160px / 240px / 30% 等);同一表單依最長的 label 挑一個固定寬,讓控件起點對齊。</p>
+      <div>
+        <div className="text-caption text-fg-muted mb-1">labelWidth = 80px</div>
+        <Field orientation="horizontal" labelWidth="80px">
+          <FieldLabel>城市</FieldLabel>
+          <Input placeholder="如:台北市" />
+        </Field>
+      </div>
+      <div>
+        <div className="text-caption text-fg-muted mb-1">labelWidth = 160px(預設常用)</div>
+        <Field orientation="horizontal" labelWidth="160px">
+          <FieldLabel>公司統一編號</FieldLabel>
+          <Input placeholder="8 碼數字" />
+        </Field>
+      </div>
+      <div>
+        <div className="text-caption text-fg-muted mb-1">labelWidth = 240px(寬 label 欄)</div>
+        <Field orientation="horizontal" labelWidth="240px">
+          <FieldLabel>發票寄送電子郵件地址</FieldLabel>
+          <Input placeholder="billing@company.com" />
+        </Field>
+      </div>
+      <div>
+        <div className="text-caption text-fg-muted mb-1">labelWidth = 30%(比例)</div>
+        <Field orientation="horizontal" labelWidth="30%">
+          <FieldLabel>備註</FieldLabel>
+          <Input placeholder="選填" />
+        </Field>
+      </div>
     </div>
   ),
 }
@@ -531,9 +561,9 @@ export const WithSlider: Story = {
           </Field>
 
           <Field>
-            <FieldLabel>已鎖定</FieldLabel>
+            <FieldLabel>儲存空間配額</FieldLabel>
             <Slider defaultValue={[40]} disabled />
-            <FieldDescription>不可調整的範例</FieldDescription>
+            <FieldDescription>由系統管理員設定,無法自行調整</FieldDescription>
           </Field>
         </FieldGroup>
       </div>
@@ -602,9 +632,9 @@ export const SliderWithLiveNumberInput: Story = {
               max={200}
             />
           </div>
+          {/* Slider 與 NumberInput 透過 `h-field-md` 對齊高度——實作細節,不進使用者可見文案 */}
           <FieldDescription>
-            Slider 跟 NumberInput 同步——拖曳 slider 即時更新數字,改數字即時更新
-            slider。兩個元件高度透過 `h-field-md` 對齊。
+            拖曳滑桿或直接輸入數字都能即時調整縮放比例,範圍 0–200%。
           </FieldDescription>
         </Field>
       </div>
@@ -640,7 +670,7 @@ function UpdateProjectSettingsForm() {
         <Field required invalid={!!form.errors.name}>
           <FieldLabel>專案名稱</FieldLabel>
           <Input {...form.getInputProps('name')} />
-          <FieldDescription>改成「產品路線圖 Q3」可觸發 submit 業務驗證(名稱重複)</FieldDescription>
+          <FieldDescription>專案名稱不得與其他專案重複</FieldDescription>
           <FieldError>{form.errors.name}</FieldError>
         </Field>
         <Field required invalid={!!form.errors.ownerEmail}>
@@ -700,6 +730,7 @@ export const FormValidation: Story = {
         <p className="text-caption text-fg-muted max-w-80">
           按鈕沒改不亮;打字中不報錯(blur 才驗);已出錯欄位一編輯立即清 error;
           Escape 回復原值;空 submit / 格式錯 → anchor 到第一個錯誤欄位。
+          試著把名稱改成「產品路線圖 Q3」再儲存,會觸發「名稱重複」業務驗證。
         </p>
         <UpdateProjectSettingsForm />
       </div>

package/src/components/Field/field.tsx

@@ -1,5 +1,6 @@
 // code-quality-allow: file-size — foundational composite(Field + FieldLabel + FieldDescription + FieldError + context + 8 layout variants),拆檔會讓 Field 家族互相 import 循環
 import * as React from 'react'
+import { cva } from 'class-variance-authority'
 import { Info as InfoIcon } from 'lucide-react'
 import { cn } from '@/lib/utils'
 import { Tooltip, TooltipTrigger, TooltipContent } from '@/design-system/components/Tooltip/tooltip'
@@ -102,6 +103,20 @@ function detectControlLayout(controlNodes: React.ReactNode[]): FieldControlLayou
   return 'inline'
 }
 
+/**
+ * 偵測 control child 的偏好尺寸——control primitive 在自己的檔案掛 static `fieldPreferredSize`
+ * (如 InlineEdit = 'sm',view 態無邊框,md 過大會讓版面鬆散),Field 未顯式指定 size 時收此偏好。
+ * 對齊 detectControlLayout 讀 `type.fieldLayout` 的機制(first-declared-wins);全部缺宣告 → null。
+ */
+function detectPreferredSize(controlNodes: React.ReactNode[]): FieldSize | null {
+  for (const node of controlNodes) {
+    if (!React.isValidElement(node)) continue
+    const pref = (node.type as { fieldPreferredSize?: FieldSize } | null | undefined)?.fieldPreferredSize
+    if (pref) return pref
+  }
+  return null
+}
+
 // ── Field ───────────────────────────────────────────────────────────────────
 
 export interface FieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'id'> {
@@ -111,7 +126,7 @@ export interface FieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, '
    * 視覺外殼(2026-05-05)。
    * - `default`(預設)— 含 border + bg(一般 form input)
    * - `naked` — cell-as-input(@internal;不在公開 FieldVariant 型別 — 2026-07-14 收窄至 FieldVariantInternal;2026-07-09 `bare` 退役)。edit×naked 自畫 border-based state
-   *   machine(rest/hover/focus/error);display/readonly/disabled×naked 用 transparent border,host cell 提供視覺邊框
+   *   machine(rest/hover/focus/error);view×naked 用 transparent border,host cell 提供視覺邊框
    *
    * 透傳機制:Field 一次宣告,所有 child Field control 自動繼承(per-control prop override 可覆寫)。
    */
@@ -155,7 +170,7 @@ const Field = React.forwardRef<HTMLDivElement, FieldProps>(
       mode = 'edit',
       variant = 'default',
       orientation = 'vertical',
-      size = 'md',
+      size: sizeProp,
       required = false,
       disabled: disabledProp = false,
       invalid = false,
@@ -199,6 +214,10 @@ const Field = React.forwardRef<HTMLDivElement, FieldProps>(
     const controlLayout: FieldControlLayout =
       controlLayoutProp ?? detectControlLayout(controlNodes)
 
+    // 解析 size：consumer 顯式 > control primitive 偏好(如 InlineEdit='sm')> 預設 md
+    //   (對齊 controlLayout 三層優先序;InlineEdit 進 Field 不指定 size 時自動收 sm)
+    const size: FieldSize = sizeProp ?? detectPreferredSize(controlNodes) ?? 'md'
+
     const contextValue = React.useMemo<FieldContextValue>(
       () => ({
         id,
@@ -496,9 +515,22 @@ export interface FieldGroupProps extends React.HTMLAttributes<HTMLDivElement> {
   horizontalLabelWidth?: string
 }
 
+// gap variant 收進 cva(className-only 差異 → cva,per ui-development.md「cva 適用」);值仍走 Tailwind gap utility。
+const fieldGroupVariants = cva('flex flex-col min-w-0', {
+  variants: {
+    gap: {
+      compact: 'gap-3',
+      normal: 'gap-4',
+      loose: 'gap-6',
+    },
+  },
+  defaultVariants: {
+    gap: 'normal',
+  },
+})
+
 const FieldGroup = React.forwardRef<HTMLDivElement, FieldGroupProps>(
   ({ className, gap = 'normal', horizontalLabelWidth, ...props }, ref) => {
-    const gapClass = gap === 'compact' ? 'gap-3' : gap === 'loose' ? 'gap-6' : 'gap-4'
     const groupCtxValue = React.useMemo(
       () => ({ horizontalLabelWidth }),
       [horizontalLabelWidth],
@@ -507,7 +539,7 @@ const FieldGroup = React.forwardRef<HTMLDivElement, FieldGroupProps>(
       <FieldGroupContext.Provider value={groupCtxValue}>
         <div
           ref={ref}
-          className={cn('flex flex-col min-w-0', gapClass, className)}
+          className={cn(fieldGroupVariants({ gap }), className)}
           data-field-group=""
           {...props}
         />

package/src/components/Field/form-validation.spec.md

@@ -156,6 +156,8 @@ Form validation 的 ARIA / 鍵盤行為(對齊 WCAG 3.3.1 Error Identification +
 - **Required indicator**:label 的 `*` 為純視覺、對讀屏隱藏(`aria-hidden="true"`,field.tsx:395);required 語意由內部輸入控件的 `aria-required`(input.tsx:188)承擔,避免讀屏讀出「asterisk」語義不清
 - **Color-only error 警告**:error border 紅色之外必有文字訊息(WCAG 1.4.1 不僅靠顏色)— 由 `<FieldError>` 文字承擔;DS **不**在 input 內放 error 狀態 icon(見 `field-controls.spec.md`「禁止事項」)
 
+**空值 / Loading(明文 N/A)**:本 spec 是跨 Field 控件的驗證時機原則(非 UI 元件)——空值渲染與 loading 狀態分屬各控件 spec(SSOT → `field-controls.spec.md`「null / undefined 值」+「Loading state」段)。
+
 ## 相關
 
 - `field.spec.md` — Field wrapper 的 error 視覺 chrome(紅框 + error message slot)

package/src/components/Field/use-form-validation.ts

@@ -12,7 +12,7 @@
  * errors store / resetField;驗證「時機」由本 hook own(RHF 的 mode/reValidateMode 不外露)。
  *
  * ── 與 Field 家族的關係(engine-agnostic 分層,field.spec.md「定位」段)──
- * Field 保持純 layout + context(MUI FormControl 派,可用於 cell / display / 無引擎場景);
+ * Field 保持純 layout + context(MUI FormControl 派,可用於 cell / view / 無引擎場景);
  * 本 hook 住 form 層,錯誤經 consumer 一行 `<Field invalid={!!form.errors.x}>` 接入——
  * Field 層零耦合。這是「A 派的自由 + B 派的 DX」混合位置。
  *

package/src/components/FieldControlGroup/field-control-group.principles.stories.tsx

@@ -91,13 +91,13 @@ export const UsageGuidance: Story = {
         <ul className="text-body text-fg-secondary list-disc pl-5 space-y-1">
           <li>Children 同 size — 不混用 sm/md/lg(視覺高度需一致)</li>
           <li>Children 自管 width — fixed selects + flex input 是典型 pattern</li>
-          <li>Mode A(包進 Field):size 從 Field context 自動繼承,children 不傳 size</li>
+          <li>繼承 Field 尺寸(包進 Field):size 從 Field context 自動繼承,children 不傳 size</li>
           <li>Children scope:Input / NumberInput / Select / Combobox / DatePicker / Button(對齊 Ant 限定 list)</li>
         </ul>
       </section>
 
       <section>
-        <h2 className="text-body-lg font-bold mb-3">Mode A — 包進 Field 當 control slot</h2>
+        <h2 className="text-body-lg font-bold mb-3">繼承 Field 尺寸 — 包進 Field 當 control slot</h2>
         <Field>
           <FieldLabel>聯絡電話</FieldLabel>
           <FieldControlGroup block>
@@ -109,7 +109,7 @@ export const UsageGuidance: Story = {
       </section>
 
       <section>
-        <h2 className="text-body-lg font-bold mb-3">Mode B — Filter row 場景</h2>
+        <h2 className="text-body-lg font-bold mb-3">Standalone 逐一設尺寸 — Filter row 場景</h2>
         <FieldControlGroup block>
           <Select className="!w-[140px]" options={FIELDS} value="name" onChange={() => {}} aria-label="篩選欄位" />
           <Select className="!w-[120px]" options={OPS} value="contains" onChange={() => {}} aria-label="篩選運算子" />

package/src/components/FieldControlGroup/field-control-group.spec.md

@@ -89,7 +89,7 @@ interface FieldControlGroupProps extends HTMLAttributes<HTMLDivElement> {
 
 **FCG `size` prop 目前為 no-op**:本元件只負責 border-collapse 接合(border / radius / z-index),不傳遞 size 給 children(無 Context Provider / 無 cloneElement)。Children 的尺寸完全由 child 自己決定 — 以下三種來源:
 
-**Mode A**(包進 Field 當 control slot):children 各自透過 `useFieldContext().size` 讀外層 `<Field>` 的 size(是 Field 的 context,不是 FCG 的)。
+**繼承 Field 尺寸**(包進 Field 當 control slot):children 各自透過 `useFieldContext().size` 讀外層 `<Field>` 的 size(是 Field 的 context,不是 FCG 的)。
 ```tsx
 <Field size="lg">
   <FieldLabel>電話</FieldLabel>
@@ -100,7 +100,7 @@ interface FieldControlGroupProps extends HTMLAttributes<HTMLDivElement> {
 </Field>
 ```
 
-**Mode B**(standalone):**逐一給每個 child 設 `size`**(設 `<FieldControlGroup size>` 無效)。
+**Standalone 逐一設尺寸**:**逐一給每個 child 設 `size`**(設 `<FieldControlGroup size>` 無效)。
 ```tsx
 <FieldControlGroup>
   <Select size="md" className="!w-[120px]" options={fields} />
@@ -108,7 +108,7 @@ interface FieldControlGroupProps extends HTMLAttributes<HTMLDivElement> {
 </FieldControlGroup>
 ```
 
-**Mode C**(進 Popover,density 鎖 md):children 自然吃 md(Popover density canonical)。
+**Popover 鎖 md**(進 Popover,density 鎖 md):children 自然吃 md(Popover density canonical)。
 
 ## A11y 預設
 

package/src/components/FileItem/file-item.tsx

@@ -5,7 +5,7 @@ import { cn } from '@/lib/utils'
 import { Avatar } from '@/design-system/components/Avatar/avatar'
 import { Button } from '@/design-system/components/Button/button'
 import { ProgressBar } from '@/design-system/components/ProgressBar/progress-bar'
-import { ItemContent, ItemPrefix } from '@/design-system/patterns/element-anatomy/item-anatomy'
+import { ItemContent, ItemPrefix, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
 
 /**
  * FileItem — 檔案顯示 / 上傳進度
@@ -134,9 +134,8 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
     ) : null
 
     // suffix 對齊 label 第一行(item-anatomy「24px 閾值對齊規則」小 suffix canonical):
-    // icons 16 ≤ 24 屬小 suffix,統一 `h-[1lh]` inline,不因 desc wrap 改公式。
-    // 兩 mode 同公式,跟 item-anatomy 一致。
-    const suffixAlign = 'h-[1lh]'
+    // icons 16 ≤ 24 屬小 suffix,統一 h-[1lh] inline(由 ItemSuffix primitive 提供),
+    // 不因 desc wrap 改公式。兩 mode 同公式,跟 item-anatomy 一致。
 
     // Status slot 幾何(2026-04-23 user 統一):rich + compact 都用 `var(--field-height-xs)`(24)
     // 容器,裡面 Button xs iconOnly variant="text"(auto data-unbounded)。
@@ -181,11 +180,14 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
       </span>
     ) : null
 
+    // 2026-07-16 dim 39/DA3:消費 ItemSuffix primitive(照 Notice 2026-06-15 已遷模式)。
+    // ItemSuffix base geometry(h-[1lh] shrink-0 ml-auto flex items-center gap-2)= 原手刻
+    // div 的 flex items-center gap-2 shrink-0 h-[1lh];多出的 ml-auto 為 no-op(左鄰
+    // ItemContent 是 flex-1,已把 suffix 推到右緣)→ 像素相等。hoverReveal 預設 false,
+    // 不干擾本檔自有的 statusSlot hover-swap 機制(group-hover/row 系)。
     const suffix = (
-      <div
+      <ItemSuffix
         className={cn(
-          'flex items-center gap-2 shrink-0',
-          suffixAlign,
           // data-unbounded chrome-canonical trick:let Button xs (24) live inside h-[1lh]
           // wrapper(compact ~18.2 / rich ~18.2 scanning)without pushing row height。
           // 視覺/hit area 仍 24,layout footprint 收斂到 1lh。同 overlay-surface
@@ -201,7 +203,7 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
         )}
         {statusSlot}
         {actions}
-      </div>
+      </ItemSuffix>
     )
 
     // content row — 消費 ItemContent primitive(封裝 label + desc + mt-gap token SSOT)。

package/src/components/FileUpload/file-upload.principles.stories.tsx

@@ -166,10 +166,10 @@ export const MultipleRule: Story = {
         note="每個欄位只收一份檔案時用預設 multiple=false。世界級對照:LinkedIn 履歷上傳、Instagram 大頭貼、Notion page cover——使用者心智模型是「這個位置放一個檔案」。"
       >
         <FileUpload
-          accept=".pdf,.doc,.docx"
-          maxSize={5_000_000}
-          title="上傳履歷"
-          description="PDF / Word,最大 5 MB"
+          accept="image/png,image/jpeg"
+          maxSize={2_000_000}
+          title="上傳大頭貼"
+          description="PNG / JPG,最大 2 MB"
           onUpload={noop}
         />
         <Label>↑ 多拖幾個只取第一個,符合 Ant Upload.Dragger / Polaris DropZone 慣例</Label>
@@ -212,7 +212,7 @@ export const DivisionOfLaborRule: Story = {
       <div>
         <Rule
           title="✅ FileUpload 觸發 + FileItem 顯示"
-          note="FileUpload 只負責「拖放偵測 + 觸發選檔」,已上傳檔案清單由 consumer 用 FileItem map 渲染——兩個元件各司其職,職責清楚。這正是 Notion / Slack / Figma 的附件 flow 做法。"
+          note="本範例走 consumer 自組清單:FileUpload 負責拖放偵測 + 觸發選檔,已上傳清單由 consumer 用 FileItem map 渲染。DS 同時支援第二條路——把清單交給 FileUpload 的 files prop 內建渲染(見下一則規則);兩條路都合法,差別只在觸發與清單狀態由誰持有,重點是都不重畫 FileItem 內部視覺。這正是 Notion / Slack / Figma 的附件 flow 做法。"
         >
           <FileUpload
             multiple
@@ -253,9 +253,9 @@ export const DivisionOfLaborRule: Story = {
 
         <Rule
           title="❌ 不在 FileUpload 裡自己重刻 FileItem primitives"
-          note="2026-04-24 設計準則更新:DS 提供 dual path — FileUpload 可 own list via `files` prop(內部 compose `<FileItem>`);OR consumer 自組 `{files.map(f => <FileItem ... />)}`。禁止的是「自畫 status icon / thumbnail / progress bar / row layout 等 FileItem primitives 視覺規格」。世界級(Material / Ant / Carbon)都 own list composing 自家 FileItem primitive。"
+          note="DS 提供兩條清單管理路徑:一是把清單交給 FileUpload 的 files prop,由它內部組合 FileItem 渲染;二是 consumer 自己用 files.map 逐項渲染 FileItem。兩條路都合法,真正禁止的是「自己重畫 FileItem 的內部視覺規格」——狀態圖示、縮圖比例、進度條、列排版都屬 FileItem 的 SSOT。世界級(Material / Ant / Carbon)也都是自己擁有清單、組合自家的 FileItem primitive,不另刻一套。"
         >
-          <Label warn>⚠️ 要顯示清單 → 傳 `files` prop(DS built-in)OR 自組 FileItem map;但不要自己重畫 FileItem 內部結構</Label>
+          <Label warn>⚠️ 要顯示清單 → 傳 `files` prop(內建)或自組 FileItem map;但不要自己重畫 FileItem 內部結構</Label>
         </Rule>
       </div>
     )