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

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)
@@ -166,10 +168,12 @@ Form validation 的 ARIA / 鍵盤行為(對齊 WCAG 3.3.1 Error Identification +
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `checkbox.spec.md`
 - `combobox.spec.md`
 - `date-picker.spec.md`
 - `field-controls.spec.md`
 - `field.spec.md`
 - `link-input.spec.md`
+- `select.spec.md`
 - `textarea.spec.md`
 - `time-picker.spec.md`

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>
     )

package/src/components/FileUpload/file-upload.spec.md

@@ -22,7 +22,7 @@ benchmark:
 
 ## 定位
 
-FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點擊觸發檔案選取浮窗。負責「上傳觸發 + 拖放偵測」,不負責「已上傳檔案清單顯示」(那是 `FileItem` 的職責)。
+FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點擊觸發檔案選取浮窗。核心職責是「上傳觸發 + 拖放偵測」;它**不 own 單筆檔案列的視覺規格**(狀態圖示 / 縮圖 / 進度條 / 列排版屬 `FileItem` 的 SSOT),但**可 orchestrate 內建清單**——透過 `files` prop 內部組合 `FileItem` 渲染已上傳清單(dual-path,見「Props 行為」與「禁止事項」);consumer 自組 `FileItem` 清單亦合法。
 
 **實作基礎**:自建 — native HTML5 `<input type="file">` + drag-and-drop event(dragenter/dragover/dragleave/drop)+ DOM-level state 切換。無 external primitive,因為 Radix 沒 File Upload 對應 primitive,其他 UI kit 的 file upload 多數也是自建這層。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
@@ -146,7 +146,8 @@ FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點
 - `role="button"` + `tabIndex=0`(disabled 或 loading 時 `-1`)
 - Enter / Space 鍵觸發檔案選取浮窗(模擬 click)
 - `aria-disabled={true}` 當 disabled
-- `<input type="file">` 以 `className="hidden"`(`display:none`)隱藏 — 移出無障礙樹、不可聚焦;互動由外層 `role="button"` wrapper 承載。Accessible name 來自 wrapper 內 Empty 的 title + description 文字(name-from-content),非 input 本身
+- `<input type="file">` 以 `className="hidden"`(`display:none`)隱藏 — 移出無障礙樹、不可聚焦;互動由外層 `role="button"` wrapper 承載
+- **Accessible name(name-from-content + custom children 例外)**:預設(未傳 children)時 name 來自 wrapper 內 `<Empty>` 的 title + description 文字,非 input 本身。**但 `children` 會整個覆寫預設結構**——若 consumer 傳入**只有 icon / branding 圖像、無可見文字**的 children,`role="button"` wrapper 就失去 accessible name(SR 讀不出用途)。此情況 consumer **必須**在 `<FileUpload>` root 傳 `aria-label`(經 `{...props}` spread 到 wrapper div),或確保 children 內含可見文字。dropzone 與 button 兩 variant 同理
 
 ---
 

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

@@ -222,7 +222,11 @@ const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
       <div ref={ref} className={cn('w-full', hasFiles && 'flex flex-col')}>
       {variant === 'button' ? (
         // ── button variant:緊湊觸發(form-friendly,省空間),click-only(無拖放區)──
-        <div className={className} {...props}>
+        // consumer onClick 在此 wrapper div 承載(type = MouseEvent<HTMLDivElement>,對齊 FileUploadProps
+        // extends HTMLAttributes<HTMLDivElement>)。Button 觸發開檔會冒泡至此 → 同時觸發 consumer handler。
+        // 2026-07-17 修:onClick 於 L128 destructure 後未再 compose,button variant 靜默丟失公開 DOM prop
+        // (dropzone variant 經 handleClick 的 onClick?.(e) 正確 compose,button variant 漏接)。
+        <div className={className} onClick={onClick} {...props}>
           <input
             ref={inputRef}
             type="file"

package/src/components/FileViewer/file-viewer.anatomy.stories.tsx

@@ -710,7 +710,7 @@ export const SizeMatrix: Story = {
               <tr>
                 <Td>Body 垂直 padding</Td>
                 <Td mono>pt-[var(--layout-space-tight)] pb-[var(--layout-space-loose)]</Td>
-                <Td>非對稱:top tight / bottom loose(對齊 layoutSpace v6 規則 4「bounded region 容器底 = loose」)</Td>
+                <Td>非對稱:top tight / bottom loose(bounded region 容器底部留白較寬鬆,內容不貼底、捲動時收尾更透氣)</Td>
               </tr>
               <tr>
                 <Td>Section 間 gap</Td>

package/src/components/FileViewer/file-viewer.principles.stories.tsx

@@ -423,7 +423,7 @@ export const ReadOnlyRule: Story = {
 
         <Rule
           title="✅ readOnly — 其他人上傳的 / 公開公告 / 只讀 link 分享"
-          note="readOnly=true 時說明區依 DS Textarea readonly canonical:有值 → 可聚焦選取但不可改的 native readonly textarea;空值 → display div 顯 emptyDisplay(`-`,非 placeholder);onDescriptionChange 不觸發。故 readonly 無 description 時顯示 `-`,不會出現「為這個檔案加上說明...」的編輯誘導 placeholder"
+          note="readOnly=true 時說明區依 DS Textarea readonly canonical:有值 → 可聚焦選取但不可改的 native readonly textarea;空值 → view div 顯 emptyDisplay(`-`,非 placeholder);onDescriptionChange 不觸發。故 readonly 無 description 時顯示 `-`,不會出現「為這個檔案加上說明...」的編輯誘導 placeholder"
         >
           <Button variant="tertiary" startIcon={FolderOpen} onClick={() => setRoOpen(true)}>
             開啟公司公告(readOnly)

package/src/components/FileViewer/file-viewer.spec.md

@@ -140,7 +140,7 @@ FileViewer Toolbar 消費 `patterns/action-bar/action-bar.spec.md` 的**左中
 - **zoom** — 同一張檔案的微調(影響範圍:當前 renderer 的 transform state),影響最小
 - **info** — 切換附加資訊面板(影響範圍:layout,不破壞現有內容)
 - **download** — 把內容搬出 viewer(影響範圍:外部檔案系統,不可逆副作用)
-- **close** — 結束整個 viewing session(影響範圍:最大)。註:close = `setOpen(false)`,**僅卸載 `DialogContent` 子樹**;外層 FileViewer 元件恆掛載,shell state(zoom / infoOpen / index 等 `useState`)**保留** —— 重開同一檔沿用上次 zoom / infoOpen,非 fresh state
+- **close** — 結束整個 viewing session(影響範圍:最大)。註:close = `setOpen(false)`,**僅卸載 `DialogContent` 子樹**;外層 FileViewer 元件恆掛載,shell state(zoom / infoOpen 等 `useState`)**保留** —— 重開同一檔沿用上次 zoom / infoOpen,非 fresh state(**index 例外**:uncontrolled 時開啟即重置為 `initialIndex`,`file-viewer.tsx` 開啟 effect)
 
 ### Dismiss canonical(Close X)
 

package/src/components/FileViewer/file-viewer.stories.tsx

@@ -203,7 +203,7 @@ const figmaDesignFile: FileInfo[] = [
     mimeType: 'image/png',
     size: 2_840_000,
     description:
-      'Dashboard v2 最終設計稿 — 對齊 spec 2.3 節「Frozen columns + row actions」,可 zoom 看細節對齊。',
+      '營運儀表板 v2 最終設計稿 — 凍結欄與列操作已定案,可 zoom 檢視 spacing 與色彩細節。',
     metadata: {
       '設計師': 'Claire Wu',
       'Figma link': 'figma.com/file/xyz/Dashboard',

package/src/components/FileViewer/file-viewer.tsx

@@ -530,13 +530,13 @@ const InfoPanel = React.memo(function InfoPanel({
         {/* 檔案資訊 — 用 DS DescriptionList horizontal + divided(Google Drive /
             Notion file info panel 模式):
             - section header 用 FieldLabel 同款 typography 保視覺一致
-            - DescriptionList direction="horizontal" divided 提供 row 下底線
+            - DescriptionList orientation="horizontal" divided 提供 row 下底線
               對齊格線,key 長度不一也易讀
             - 不再手刻 dl/dt/dd — canonical 由 DS primitive own */}
         {/* heading → first-item gap = item → item gap(Gestalt proximity,見 description-list.spec.md) */}
         <div className="flex flex-col gap-[var(--layout-space-tight)]">
           <span className="text-body font-normal text-foreground">{labels.fileInfoHeading}</span>
-          <DescriptionList direction="horizontal" divided>
+          <DescriptionList orientation="horizontal" divided>
             <DescriptionItem label="檔名">{file.name}</DescriptionItem>
             <DescriptionItem label="類型">{file.mimeType || '-'}</DescriptionItem>
             {sizeText && (
@@ -775,6 +775,7 @@ const FileViewer = React.forwardRef<HTMLDivElement, FileViewerProps>(function Fi
   allowDownload = true,
   onDownload,
   labels: labelsOverride,
+  className,
   ...props
 }, ref) {
   const labels = React.useMemo(

package/src/components/HoverCard/hover-card.anatomy.stories.tsx

@@ -89,7 +89,7 @@ export const VisualVariants: Story = {
         <div className="flex items-center gap-6">
           <HoverCard>
             <HoverCardTrigger asChild>
-              <Button variant="tertiary" size="sm">hover 看 Card</Button>
+              <Button variant="tertiary" size="sm">Ada Chen</Button>
             </HoverCardTrigger>
             <HoverCardContent className="bg-surface-raised border border-border rounded-lg p-4 shadow-[var(--elevation-200)]">
               <div className="w-56">
@@ -108,11 +108,13 @@ export const VisualVariants: Story = {
         <div className="flex items-center gap-6">
           <HoverCard>
             <HoverCardTrigger asChild>
-              <Button variant="tertiary" size="sm">hover 看 Tooltip 樣式</Button>
+              <Button variant="tertiary" size="sm">+3 位協作者</Button>
             </HoverCardTrigger>
             <HoverCardContent className="bg-tooltip rounded-md px-3 py-2" data-theme="dark">
-              <div className="text-caption w-56">
-                深色樣式——常見於 OverflowIndicator 顯示溢出清單(+3 more 的 hover 展開)
+              <div className="text-caption w-56 flex flex-col gap-1">
+                <span>林思妤</span>
+                <span>陳柏宇</span>
+                <span>Aisha Khan</span>
               </div>
             </HoverCardContent>
           </HoverCard>

package/src/components/HoverCard/hover-card.principles.stories.tsx

@@ -97,7 +97,12 @@ export const UsageGuidance: Story = {
         >
           <HoverCard>
             <HoverCardTrigger asChild>
-              <a className="text-primary underline cursor-pointer inline-flex items-center gap-1">
+              <a
+                href="https://help.acme.com/user-manual"
+                target="_blank"
+                rel="noreferrer"
+                className="text-primary underline cursor-pointer inline-flex items-center gap-1"
+              >
                 使用者手冊 <ExternalLink size={12} />
               </a>
             </HoverCardTrigger>

package/src/components/HoverCard/hover-card.spec.md

@@ -22,7 +22,7 @@ Hover 觸發的**可互動浮層**，基於 Radix HoverCard。
 **分類**：Internal primitive——不進 root barrel front-door、不裸用;DS 內由 Avatar(`hoverCard`)/ OverflowIndicator / ProfileCard 場景組合消費;consumer 需要時可經 per-component subpath 包裝並自行確認後使用(`.claude/rules/ui-development.md`「Root barrel front-door 排除」SSOT,internal ≠ 禁用)(frontmatter `isInternal`:root barrel 排除,storybook `Design System/Internal/HoverCard`)。
 
 - **是**：hover 顯示可互動內容（按鈕、連結、可選取文字——**滑鼠互動**；鍵盤進不了卡片，見「A11y 預設」）的浮層容器，定位為滑鼠 / focus 使用者的補充閱讀 surface
-- **不是**：Tooltip（純文字提示、不可互動、hover 離開即消失）；也不是鍵盤可操作的互動浮層（那是 Popover）
+- **不是**：Tooltip（純文字提示、**內容不可互動**；指標可短暫移到浮層屬 WCAG 1.4.13 hoverable grace，非「立即消失」）；也不是鍵盤可操作的互動浮層（那是 Popover）
 
 **Layout Family**：非上述 family — composite / multi-section（多區塊組合，自 own layout）。
 
@@ -54,7 +54,7 @@ Hover 觸發的**可互動浮層**，基於 Radix HoverCard。
 |---|---|---|
 | 觸發 | hover | hover |
 | **內容可互動** | 是——限滑鼠（Radix 設 content 內 tabbable node 為 `tabindex="-1"`，鍵盤不可達，見「A11y 預設」） | 否（純文字） |
-| 停留行為 | 滑鼠移到浮層上不消失 | 滑鼠離開 trigger 即消失 |
+| 停留行為 | 滑鼠可移到浮層互動不消失 | 滑鼠可短暫移到浮層（WCAG 1.4.13 grace，`tooltip.tsx` 未設 `disableHoverableContent`），但內容不可互動 |
 | 視覺樣式 | 由 consumer 決定（亮色 card 或深色 tooltip 風格皆可） | 統一深色背景 |
 | 典型用例 | ProfileCard、內容預覽、溢出清單 | icon 用途、shortcut、截斷文字補全 |
 

package/src/components/HoverCard/hover-card.tsx

@@ -85,8 +85,10 @@ export const hoverCardMeta = {
   },
   states: ['default'],
   tokens: {
-    bg: ['bg-surface-raised'],
-    fg: ['--foreground'],
+    // 2026-07-16 deep-audit A.1b:清 Phase-1 佔位 — HoverCard 為純行為 primitive,
+    // Content 不套任何 bg/fg(spec「純行為 primitive」段);bg-surface-raised 屬 consumer(ProfileCard)。
+    bg: [],
+    fg: [],
     ring: [],
   },
 } as const

package/src/components/InlineEdit/inline-edit.anatomy.stories.tsx

@@ -0,0 +1,184 @@
+import * as React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { InlineEdit } from './inline-edit'
+import { Select } from '@/design-system/components/Select/select'
+import { Field, FieldLabel } from '@/design-system/components/Field/field'
+
+// 就地編輯無 disabled 態的世界級對照(cite,per M22):
+//   MUI X isCellEditable/cellMode https://mui.com/x/react-data-grid/editing/
+//   AG Grid editable https://www.ag-grid.com/react-data-grid/cell-editing/
+//   Atlassian inline-edit readView/editView https://github.com/pioug/atlassian-frontend-mirror/blob/main/design-system/inline-edit/src/internal/read-view.tsx
+//
+// InlineEdit 設計規格(anatomy)—— view ↔ edit 二態就地編輯 primitive。
+// Model A(2026-07-16):view 不自帶幾何 cva,委派控件 view mode / fieldViewGeometry helper;read↔edit 零跳。
+const meta: Meta<typeof InlineEdit> = {
+  title: 'Design System/Components/InlineEdit/設計規格',
+  component: InlineEdit,
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj<typeof InlineEdit>
+
+// ── shared UI ────────────────────────────────────────────────────────────────
+function Section({ title, children }: { title: string; children: React.ReactNode }) {
+  return (
+    <section className="mb-8">
+      <h3 className="mb-3 border-b border-divider pb-2 text-body-lg font-semibold text-foreground">{title}</h3>
+      {children}
+    </section>
+  )
+}
+function PropRow({ name, type, def, desc }: { name: string; type: string; def: string; desc: string }) {
+  return (
+    <tr className="border-b border-divider align-top">
+      <td className="py-2 pr-4 font-mono text-caption text-foreground">{name}</td>
+      <td className="py-2 pr-4 font-mono text-caption text-fg-secondary">{type}</td>
+      <td className="py-2 pr-4 font-mono text-caption text-fg-muted">{def}</td>
+      <td className="py-2 text-caption text-fg-secondary">{desc}</td>
+    </tr>
+  )
+}
+function Stateful({ value: initial, ...props }: Omit<React.ComponentProps<typeof InlineEdit>, 'onCommit'>) {
+  const [value, setValue] = React.useState(initial)
+  return <InlineEdit {...props} value={value} onCommit={setValue} />
+}
+
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => (
+    <div className="max-w-[720px]">
+      <Section title="定位">
+        <p className="text-body text-fg-secondary">
+          就地編輯 primitive:值平常以 <b>view 態</b>(純內容)呈現,滑鼠移入顯示灰底提示、點擊(或鍵盤 Enter)切成
+          <b> edit 態</b>(真正的 Field 控件)。與 DataTable cell 同一份就地編輯語義 —— 只有 <code>view ↔ edit</code> 兩態
+          + <code>editable</code> 判準閘,<b>無 disabled 態</b>(世界級就地編輯共識,cite 見檔頭)。
+        </p>
+      </Section>
+      <Section title="Model A —— view 幾何來源">
+        <p className="mb-2 text-body text-fg-secondary">
+          InlineEdit <b>不自帶</b> geometry cva(消 M17 重複)。view 幾何來源分兩路,read↔edit 零跳因兩態同一顆控件、只差 chrome:
+        </p>
+        <ul className="ml-5 list-disc text-body text-fg-secondary">
+          <li><b>值-格式化</b>(Select→Tag / 日期 / avatar):<code>renderRead</code> 委派 <code>{'<Control mode="view">'}</code>,
+            幾何 + 內部間距(多 tag gap / avatar↔label)皆由控件 view×default 提供。</li>
+          <li><b>純值 / 標題</b>(<code>as="h1"</code>):套 <code>fieldViewGeometry(size, multiline)</code> helper
+            (= view×default 幾何 SSOT:<code>px-field-px</code> + <code>min-h-field</code> + 多行 <code>py-2</code>)。</li>
+        </ul>
+      </Section>
+    </div>
+  ),
+}
+
+export const Inspector: Story = {
+  name: '屬性一覽',
+  render: () => (
+    <div className="max-w-[860px]">
+      <table className="w-full">
+        <thead>
+          <tr className="border-b-2 border-border text-left">
+            <th className="py-2 pr-4 text-caption font-semibold text-fg-muted">Prop</th>
+            <th className="py-2 pr-4 text-caption font-semibold text-fg-muted">型別</th>
+            <th className="py-2 pr-4 text-caption font-semibold text-fg-muted">預設</th>
+            <th className="py-2 text-caption font-semibold text-fg-muted">說明</th>
+          </tr>
+        </thead>
+        <tbody>
+          <PropRow name="value" type="T" def="—" desc="已提交的欄位值(view 顯示 / edit 初值)。泛型:string / number / string[] / PersonValue" />
+          <PropRow name="onCommit" type="(next: T) => void" def="—" desc="blur / Enter 且草稿有變更時提交" />
+          <PropRow name="editable" type="boolean" def="true" desc="false → view 無 hover 入口、無藍框、不可進 edit、不灰化(鎖定 = 純 view)" />
+          <PropRow name="renderRead" type="(v: T) => ReactNode" def="String(value)" desc="格式化 view;鐵律:渲染對應控件 mode='view',不可自刻" />
+          <PropRow name="renderEdit" type="(p) => ReactNode" def="Input/Textarea" desc="edit 控件(必 mode='edit');非 string 值必傳" />
+          <PropRow name="multiline" type="boolean" def="false" desc="Jira description 類:view 換行 + edit 用 Textarea(py-2 = Textarea)" />
+          <PropRow name="as" type="'span'|'h1'..'h6'|'p'|'div'" def="'span'" desc="view 語意標籤;標題保留文件大綱 a11y" />
+          <PropRow name="size" type="'sm'|'md'|'lg'" def="sm(fieldCtx cascade)" desc="接 fieldCtx.size;standalone fallback sm。靜態 fieldPreferredSize='sm' 讓外層 Field 自動收 sm" />
+          <PropRow name="label" type="string" def="—" desc="view 按鈕 aria-label(「編輯 {label}」)+ 控件 aria-label" />
+        </tbody>
+      </table>
+    </div>
+  ),
+}
+
+export const StateBehavior: Story = {
+  name: '狀態行為',
+  render: () => (
+    <div className="grid max-w-[720px] grid-cols-[140px_1fr] gap-x-6 gap-y-5">
+      <span className="text-body font-medium text-foreground">view(可編)</span>
+      <div><Stateful value="Fix flaky e2e test" label="標題" /></div>
+      <span className="text-body font-medium text-foreground">view(鎖定)</span>
+      <div><Stateful value="PROJ-482(系統產生)" label="編號" editable={false} /></div>
+      <span className="text-body font-medium text-foreground">多行</span>
+      <div><Stateful value={'第一行說明\n第二行說明(換行保留上下 padding)'} label="說明" multiline /></div>
+      <span className="text-body font-medium text-foreground">格式化(Tag)</span>
+      <div>
+        <Stateful
+          value="in-progress"
+          label="狀態"
+          renderRead={(v) => (
+            <Select mode="view" display="tag" size="sm" value={v as string} options={[
+              { value: 'in-progress', label: '進行中', tagVariant: 'blue' },
+              { value: 'done', label: '完成', tagVariant: 'green' },
+            ]} />
+          )}
+          renderEdit={(p) => (
+            <Select
+              autoFocus
+              display="tag"
+              size="sm"
+              defaultOpen
+              value={p.value as string}
+              aria-label={p['aria-label']}
+              options={[
+                { value: 'in-progress', label: '進行中', tagVariant: 'blue' },
+                { value: 'done', label: '完成', tagVariant: 'green' },
+              ]}
+              onChange={(next) => { p.onChange(next as string); p.commit() }}
+            />
+          )}
+        />
+      </div>
+      <span className="text-body font-medium text-foreground">空值</span>
+      <div><Stateful value="" label="負責人" placeholder="指派負責人…" /></div>
+    </div>
+  ),
+}
+
+// auto-sm 靠 Field 偵測 child 靜態 `fieldPreferredSize`(對齊 detectControlLayout 讀 fieldLayout)——
+//   **必 InlineEdit 為 Field 直接子**(包一層 wrapper 元件會遮蔽靜態,Field 偵測不到 → 退回 md)。
+function CascadeDemo() {
+  const [title, setTitle] = React.useState('Fix flaky checkout e2e test')
+  const [owner, setOwner] = React.useState('')
+  return (
+    <div className="w-[420px] rounded-lg border border-border bg-surface p-[var(--layout-space-loose)]">
+      {/* Field 偵測 InlineEdit 靜態 fieldPreferredSize='sm' → 未指定 size 自動收 sm;
+          vertical orientation → InlineEdit -mx 讓 view 值落 FieldLabel 同左緣 */}
+      <Field className="mb-4">
+        <FieldLabel>任務標題</FieldLabel>
+        <InlineEdit value={title} onCommit={setTitle} label="任務標題" />
+      </Field>
+      <Field>
+        <FieldLabel>負責人</FieldLabel>
+        <InlineEdit value={owner} onCommit={setOwner} label="負責人" placeholder="指派…" />
+      </Field>
+    </div>
+  )
+}
+export const InFieldCascade: Story = {
+  name: '包進表單欄位:尺寸自動收斂與左緣對齊',
+  render: () => <CascadeDemo />,
+}
+
+export const Accessibility: Story = {
+  name: '無障礙',
+  render: () => (
+    <div className="max-w-[640px] text-body text-fg-secondary">
+      <ul className="ml-5 list-disc space-y-1">
+        <li>view 疊隱形 <code>{'<button aria-label="編輯 {label}">'}</code> —— Tab 可聚焦、Enter/Space 進 edit;
+          與 <code>as="h1"</code> 分離(HTML 不允許 heading 巢狀於 button),標題大綱不破壞。</li>
+        <li>鍵盤 focus 顯 <code>border-primary</code> 藍框(<code>focus-visible</code>,僅鍵盤);滑鼠點擊不顯藍框。</li>
+        <li>結算焦點路徑分流:鍵盤 Enter/Esc → 焦點回 view 按鈕;滑鼠 blur → 純 view 不搶焦。</li>
+        <li><code>editable=false</code>:不渲染 Pressable,鍵盤跳過,語意 = 唯讀值(非 disabled)。</li>
+        <li>edit 態 = 真正的 Field 控件,繼承其 a11y(Input/Textarea/Select 各自 ARIA)。</li>
+      </ul>
+    </div>
+  ),
+}