@qijenchen/design-system 0.1.0-beta.95 → 0.1.0-beta.99

package/src/components/DropdownMenu/dropdown-menu.tsx

@@ -67,23 +67,65 @@ const radixItemClass = [
 ].join(' ')
 
 // ── Root ──
-const DropdownMenu = DropdownMenuPrimitive.Root
+// Radix modal menu 會在 open 時把 trigger 所在的 app subtree 設成 aria-hidden。瀏覽器仍可
+// 讓 subtree 內原本的 trigger 留在 sequential focus order，axe 因而正確報
+// aria-hidden-focus。由 Root SSOT 對所有 DropdownMenu 統一同步 trigger tab stop；Portal
+// 仍保留 React context，所以不需要 consumer/story 各自 patch。
+const DropdownMenuModalOpenContext = React.createContext(false)
+
+const DropdownMenu = ({
+  open,
+  defaultOpen,
+  onOpenChange,
+  modal = true,
+  ...props
+}: React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Root>) => {
+  const [uncontrolledOpen, setUncontrolledOpen] = React.useState(defaultOpen ?? false)
+  const resolvedOpen = open ?? uncontrolledOpen
+  const handleOpenChange = React.useCallback(
+    (nextOpen: boolean) => {
+      if (open === undefined) setUncontrolledOpen(nextOpen)
+      onOpenChange?.(nextOpen)
+    },
+    [onOpenChange, open],
+  )
+
+  return (
+    <DropdownMenuModalOpenContext.Provider value={modal && resolvedOpen}>
+      <DropdownMenuPrimitive.Root
+        open={open}
+        defaultOpen={defaultOpen}
+        onOpenChange={handleOpenChange}
+        modal={modal}
+        {...props}
+      />
+    </DropdownMenuModalOpenContext.Provider>
+  )
+}
+DropdownMenu.displayName = DropdownMenuPrimitive.Root.displayName
+
 const DropdownMenuTrigger = React.forwardRef<
   React.ElementRef<typeof DropdownMenuPrimitive.Trigger>,
   React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Trigger>
->(({ className, ...props }, ref) => (
-  <DropdownMenuPrimitive.Trigger
-    ref={ref}
-    // 2026-07-05:非 asChild 裸用需可見 focus 指示(WCAG 2.4.7)——原 `outline-none` 讓裸 Trigger
-    // 完全無 focus ring。消費 Button focus canonical(button.tsx buttonVariants base)。
-    // asChild+Button 場景同名 class 重複,無影響。
-    className={cn(
-      'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',
-      className,
-    )}
-    {...props}
-  />
-))
+>(({ className, tabIndex, ...props }, ref) => {
+  const modalOpen = React.useContext(DropdownMenuModalOpenContext)
+  return (
+    <DropdownMenuPrimitive.Trigger
+      ref={ref}
+      // modal open 時 trigger 位於 Radix aria-hidden subtree：移出 sequential focus order；
+      // 關閉時仍由 Radix programmatically focus，且恢復 consumer 原 tabIndex。
+      tabIndex={modalOpen ? -1 : tabIndex}
+      // 2026-07-05:非 asChild 裸用需可見 focus 指示(WCAG 2.4.7)——原 `outline-none` 讓裸 Trigger
+      // 完全無 focus ring。消費 Button focus canonical(button.tsx buttonVariants base)。
+      // asChild+Button 場景同名 class 重複,無影響。
+      className={cn(
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',
+        className,
+      )}
+      {...props}
+    />
+  )
+})
 DropdownMenuTrigger.displayName = DropdownMenuPrimitive.Trigger.displayName
 // DropdownMenuGroup — 對齊 MenuGroup 的 group separation 設計語言
 //
@@ -178,7 +220,7 @@ const DropdownMenuContent = React.forwardRef<
       <RowSizeProvider value={size}>
         {/* body 恆在 flex-1 ScrollArea 內:超過 clamped 高度即跨-OS 一致捲動(不吃寬度);
             短選單 flex-1 貼內容不塌(同 HoverCard/Popover/DataTable panel 已驗)。py-2 在內層,整 padded 區可捲。 */}
-        <ScrollArea className="flex-1 min-h-0">
+        <ScrollArea className="flex-1 min-h-0" viewportTabIndex={null}>
           <div className="py-2">{children}</div>
         </ScrollArea>
       </RowSizeProvider>
@@ -413,7 +455,7 @@ const DropdownMenuLabel = React.forwardRef<
         size={size}
         header
         role="presentation"
-        className="pointer-events-none"
+        className="pointer-events-none text-fg-secondary"
       >
         {children}
       </MenuItem>

package/src/components/Field/field-context.ts

@@ -44,6 +44,11 @@ export interface FieldContextValue {
   required: boolean
   invalid: boolean
   size: FieldSize
+  /** `size` 是被決定過的(consumer 顯式傳 / control 宣告偏好)還是 Field 的預設 md。
+   *  預設 md 不得壓過 control 自己宣告的 fallback —— 詳 useResolvedFieldSize 與 field.spec.md。 */
+  sizeExplicit: boolean
+  /** Control 於掛載時宣告偏好尺寸(wrapper/HOC 遮蔽靜態 `fieldPreferredSize` 時的補位通道)。 */
+  registerPreferredSize?: (preferred: FieldSize) => void
   orientation: FieldOrientation
   controlLayout: FieldControlLayout
   hasFieldWrapper: true
@@ -166,7 +171,26 @@ export function useResolvedFieldSize<T extends string = FieldSize>(sizeProp?: T
   // generic T(預設 FieldSize)讓非-input 控件(SegmentedControl/Rating 的 'xs'|'sm'|'md'|'lg' 超集、各自 fallback)
   // 也走同一 SSOT resolution。fieldCtx.size/surfaceSize 為 FieldSize(T 的子集)→ widen cast 安全。
   // fallback 未傳預設 'md'(input-class 控件向後相容);Rating 傳 'xs'、SegmentedControl 傳 'md'。
-  return (sizeProp ?? (fieldCtx?.size as T | undefined) ?? (surfaceSize as T | undefined) ?? fallback ?? ('md' as T))
+  //
+  // 2026-07-28:Field 的 size 只有在 consumer 顯式指定、或 Field 已解析出 control 偏好時才算「決定過」
+  // (`sizeExplicit`)。否則那只是 Field 的預設 md,不該壓過控件自己宣告的 fallback ——
+  // 舊行為讓「InlineEdit 被包一層 wrapper」時靜默退回 md(詳 field.spec.md 偏好尺寸 SSOT)。
+  const contextSize = fieldCtx && fieldCtx.sizeExplicit ? (fieldCtx.size as T | undefined) : undefined
+  return (sizeProp ?? contextSize ?? fallback ?? (fieldCtx?.size as T | undefined) ?? (surfaceSize as T | undefined) ?? ('md' as T))
+}
+
+/**
+ * Control 向外層 Field 宣告偏好尺寸(render-time)。靜態 `fieldPreferredSize` 只有在 control 是
+ * Field 的**直接子元件**時才偵測得到;包 wrapper / `React.memo` / HOC 會遮蔽它。本 hook 讓 control
+ * 在掛載時主動註冊,Field 的**控件槽高度**因此也能跟上(控件本身的尺寸則由 `useResolvedFieldSize`
+ * 同步解析,不等這次註冊)。
+ */
+export function useRegisterFieldPreferredSize(preferred?: FieldSize | null): void {
+  const fieldCtx = React.useContext(FieldContext)
+  const register = fieldCtx?.registerPreferredSize
+  React.useEffect(() => {
+    if (preferred && register) register(preferred)
+  }, [preferred, register])
 }
 
 /**

package/src/components/Field/field-wrapper.tsx

@@ -388,5 +388,11 @@ export const fieldViewGeometry = (size: 'sm' | 'md' | 'lg', multiline?: boolean)
     size === 'sm' && 'min-h-[var(--field-height-sm)]',
     size === 'md' && 'min-h-[var(--field-height-md)]',
     size === 'lg' && 'min-h-[var(--field-height-lg)]',
-    multiline ? 'items-start py-2' : 'items-center',
+    // 多行 view py 必等於 Textarea edit py(同一 --field-control-py-* token),否則
+    // InlineEdit 多行 read↔edit 垂直跳位;scripts/inline-edit-view-geometry-invariant.mjs 機械鎖。
+    multiline && 'items-start',
+    multiline && size === 'sm' && 'py-[var(--field-control-py-sm)]',
+    multiline && size === 'md' && 'py-[var(--field-control-py-md)]',
+    multiline && size === 'lg' && 'py-[var(--field-control-py-lg)]',
+    !multiline && 'items-center',
   )

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

@@ -214,6 +214,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 的**直接子元件**時才偵測得到。包一層 wrapper 元件、`React.memo`、HOC 都會遮蔽 static，Field 退回 `md`，且 `fieldCtx.size` 在 `useResolvedFieldSize` 的優先序中**高於** control 自己的 fallback，因此 control 再也搶不回偏好尺寸。**Consumer 對策**：把 state 提升到 Field 外層讓 control 保持直接子元件，或顯式傳 `size`。**禁**：為了包 wrapper 而預期偏好仍然生效。
+
 ### Primitive 的 Field-aware 行為
 
 **Checkbox / Switch / RadioItem** 等 primitive 自己有 `label` / `description` props 可用於**獨立使用場景**（不在 Field 內），但在 Field context 內時：
@@ -335,7 +341,7 @@ Button 的 height 與 `field-height` 共用同一組 token,放進 inline control
 ## 邊界案例
 
 - **空 Field(無 control children)**:code 不擋——control area 渲染成空容器。Field 是佈局容器,無 control 即無意義,屬 consumer 誤用
-- **RTL**:未實作方向鏡像(horizontal label 欄固定在左、Switch `ml-auto` 推右皆以 LTR 設計);RTL 屬 DS-wide 決策,未定(與 Chip / Breadcrumb 同口徑)
+- **RTL**:不支援；全域 LTR-only compatibility contract 見 `packages/design-system/README.md#compatibility-matrix`。horizontal label / suffix alignment 不在本檔另立支援決策。
 
 ---
 
@@ -458,6 +464,7 @@ Field 內的資料輸入控件（Input / NumberInput / DatePicker / Select / Com
 - `field-control-group.spec.md`
 - `field-controls.spec.md`
 - `form-validation.spec.md`
+- `inline-edit.spec.md`
 - `input.spec.md`
 - `radio-group.spec.md`
 - `switch.spec.md`

package/src/components/Field/field.tsx

@@ -216,7 +216,16 @@ const Field = React.forwardRef<HTMLDivElement, FieldProps>(
 
     // 解析 size：consumer 顯式 > control primitive 偏好(如 InlineEdit='sm')> 預設 md
     //   (對齊 controlLayout 三層優先序;InlineEdit 進 Field 不指定 size 時自動收 sm)
-    const size: FieldSize = sizeProp ?? detectPreferredSize(controlNodes) ?? 'md'
+    // 靜態偵測只看得到直接子元件;包 wrapper / memo / HOC 時由 control 於掛載時註冊補位,
+    // 讓 Field 的控件槽高度也跟上(control 自身尺寸走 useResolvedFieldSize 同步解析)。
+    const [registeredSize, setRegisteredSize] = React.useState<FieldSize | null>(null)
+    const registerPreferredSize = React.useCallback((preferred: FieldSize) => {
+      setRegisteredSize((current) => (current === preferred ? current : preferred))
+    }, [])
+    const detectedSize = detectPreferredSize(controlNodes)
+    const resolvedPreferredSize = sizeProp ?? detectedSize ?? registeredSize
+    const size: FieldSize = resolvedPreferredSize ?? 'md'
+    const sizeExplicit = resolvedPreferredSize != null
 
     const contextValue = React.useMemo<FieldContextValue>(
       () => ({
@@ -230,11 +239,13 @@ const Field = React.forwardRef<HTMLDivElement, FieldProps>(
         required,
         invalid,
         size,
+        sizeExplicit,
+        registerPreferredSize,
         orientation,
         controlLayout,
         hasFieldWrapper: true,
       }),
-      [id, labelId, descriptionId, errorId, mode, variant, disabled, required, invalid, size, orientation, controlLayout]
+      [id, labelId, descriptionId, errorId, mode, variant, disabled, required, invalid, size, sizeExplicit, registerPreferredSize, orientation, controlLayout]
     )
 
     // Control area：兩種佈局模型,「第一行內容中線」都錨在 field-height/2,
@@ -426,6 +437,7 @@ const FieldLabel = React.forwardRef<HTMLLabelElement, FieldLabelProps>(
                 <button
                   type="button"
                   aria-label={info}
+                  // 弱化 icon hover 一階(inline-action.spec.md「Icon 色彩」;2026-07-30 前全 DS 唯一合規處)
                   className="inline-flex items-center text-fg-muted hover:text-fg-secondary bg-transparent border-0 p-0 cursor-pointer"
                 >
                   <InfoIcon size={16} aria-hidden />

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

@@ -53,14 +53,14 @@ export const Overview: Story = {
   ),
 }
 
-/* SizeMatrix */
+/* Export id 保留 corpus 穩定；此矩陣只改 child size，FieldControlGroup 本身沒有 size API。 */
 export const SizeMatrix: Story = {
-  name: '尺寸矩陣',
+  name: '子元件尺寸對齊',
   render: () => (
     <div className="flex flex-col gap-6 w-[420px]">
       {(['sm', 'md', 'lg'] as const).map(size => (
         <div key={size}>
-          <p className="text-caption text-fg-muted mb-2">size="{size}"</p>
+          <p className="text-caption text-fg-muted mb-2">children size="{size}"（group 無 size prop）</p>
           <FieldControlGroup block>
             <Select size={size} className="!w-[120px]" options={FIELDS} value="name" onChange={() => {}} aria-label="篩選欄位" />
             <Input size={size} className="flex-1" defaultValue="無線滑鼠" aria-label="篩選值" />

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

@@ -52,7 +52,6 @@ benchmark:
 
 ```ts
 interface FieldControlGroupProps extends HTMLAttributes<HTMLDivElement> {
-  size?: 'sm' | 'md' | 'lg'  // default 'md';目前為 no-op(FCG 不傳遞),size 由各 child 自管 — 見「Size cascade」
   block?: boolean             // 對齊 Ant Space.Compact `block`,默 false=inline-flex
 }
 ```
@@ -87,7 +86,7 @@ interface FieldControlGroupProps extends HTMLAttributes<HTMLDivElement> {
 
 ## Size
 
-**FCG `size` prop 目前為 no-op**:本元件只負責 border-collapse 接合(border / radius / z-index),不傳遞 size 給 children(無 Context Provider / 無 cloneElement)。Children 的尺寸完全由 child 自己決定 — 以下三種來源:
+**FCG 不暴露 `size` prop**:本元件只負責 border-collapse 接合(border / radius / z-index),不傳遞 size 給 children(無 Context Provider / 無 cloneElement)。未實作的 group-level size 不預佔 API。Children 的尺寸完全由 child 自己決定 — 以下三種來源:
 
 **繼承 Field 尺寸**(包進 Field 當 control slot):children 各自透過 `useFieldContext().size` 讀外層 `<Field>` 的 size(是 Field 的 context,不是 FCG 的)。
 ```tsx
@@ -100,7 +99,7 @@ interface FieldControlGroupProps extends HTMLAttributes<HTMLDivElement> {
 </Field>
 ```
 
-**Standalone 逐一設尺寸**:**逐一給每個 child 設 `size`**(設 `<FieldControlGroup size>` 無效)。
+**Standalone 逐一設尺寸**:**逐一給每個 child 設 `size`**。
 ```tsx
 <FieldControlGroup>
   <Select size="md" className="!w-[120px]" options={fields} />

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

@@ -158,4 +158,5 @@ export const FilterRow: Story = {
   },
 }
 
-/* @story-trait-rationale: AllSizes retired per F migration 2026-05-15 — anatomy.stories.tsx SizeMatrix auto-compile owns size showcase。 */
+/* @story-trait-rationale: AllSizes retired per F migration 2026-05-15 — anatomy.stories.tsx 的
+   ChildSizeAlignment 只展示 children 尺寸接合；FieldControlGroup 本身不擁有 size API。 */

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

@@ -9,7 +9,6 @@
 //
 import * as React from 'react'
 import { cn } from '@/lib/utils'
-import type { FieldSize } from '@/design-system/components/Field/field-context'
 
 /**
  * FieldControlGroup — 多個 Field controls 視覺接合成一個 input frame
@@ -26,10 +25,10 @@ import type { FieldSize } from '@/design-system/components/Field/field-context'
  * - z-index:default 2 / hover|focus|focus-within 3 / disabled 0
  * - Container `display: inline-flex`(Ant default)/ `block` prop → `display: flex; width: 100%`
  *
- * **Size**(FCG `size` 為 no-op — 不傳遞 size 給 children,無 Context Provider / 無 cloneElement;見 spec「Size」段):
+ * **Size**(FCG 不擁有 size API；不傳遞 size 給 children,無 Context Provider / 無 cloneElement;見 spec「Size」段):
  * - children 尺寸完全由 child 自己決定;FCG 只負責 border-collapse 接合(border / radius / z-index)
  * - Mode A:整個 FieldControlGroup 包進 Field 當 control slot,children 各自讀外層 `<Field>` 的 context size(是 Field 的 context,不是 FCG 的)
- * - Mode B:standalone 用,逐一給每個 child 設 `size`(設 `<FieldControlGroup size>` 無效)
+ * - Mode B:standalone 用,逐一給每個 child 設 `size`
  *
  * **Width 配置**(Ant Space.Compact W-A canonical):
  * - 子 controls 自管 width(`className="w-[140px]"` / `style={{width:120}}` / `flex-1` etc.)
@@ -62,14 +61,12 @@ import type { FieldSize } from '@/design-system/components/Field/field-context'
  */
 
 export interface FieldControlGroupProps extends React.HTMLAttributes<HTMLDivElement> {
-  /** no-op — FCG 不傳遞 size 給 children;Mode A 由 children 讀外層 Field context、Mode B 逐一給每個 child 設 size(見 spec「Size」段) */
-  size?: FieldSize
   /** Block 模式:width 100% 撐滿 parent(對齊 Ant Space.Compact `block` prop) */
   block?: boolean
 }
 
 const FieldControlGroup = React.forwardRef<HTMLDivElement, FieldControlGroupProps>(
-  ({ size: _size = 'md', block = false, className, children, ...props }, ref) => {
+  ({ block = false, className, children, ...props }, ref) => {
     return (
       <div
         ref={ref}
@@ -116,14 +113,14 @@ FieldControlGroup.displayName = 'FieldControlGroup'
 // Story auto-compile metadata — Phase 4 migration(2026-05-10 #12 task complete)
 // Per scripts/compile-stories.mjs --check。FieldControlGroup is self-contained
 // structural wrapper(border-collapse pattern for Field controls)。
-// **No own sizes** — size prop 目前為 no-op(不傳遞給 children,無 Context Provider /
-// 無 cloneElement;children 尺寸自管,見上方 docblock「Size」段 + spec「FCG `size` prop 目前為 no-op」),
+// **No own sizes** — 不暴露 size prop(不傳遞給 children,無 Context Provider /
+// 無 cloneElement;children 尺寸自管,見上方 docblock「Size」段),
 // so sizes:{} matches spec frontmatter (no sizes declared)。
 export const fieldControlGroupMeta = {
   component: 'FieldControlGroup',
   family: 'self-contained',
   variants: {},
-  sizes: {},  // self-contained wrapper;size prop no-op(children 尺寸自管)
+  sizes: {},  // self-contained wrapper;children 尺寸自管
   states: ['default', 'children-hover', 'children-focus', 'children-disabled'],
   tokens: {
     bg: [],  // structural wrapper has no own bg

package/src/components/FileItem/file-item.spec.md

@@ -459,7 +459,7 @@ Passive status icon 置中於 action-sized 容器,hover 時 active action 填滿
 - **超長檔名**:label 經 `ItemContent` 預設 `truncate` 單行截斷(ellipsis),不換行。
 - **過長 description**:自由換行不截斷(FileItem 未傳 `descriptionClamp`);rich 多行 desc 時 progress bar 隨內容下移並保 8px min gap(見 Rich layout invariant)。
 - **progress 精度**:傳入值直接顯示(rich 的 `%` 文字與 bar 同源),元件不四捨五入;`completed` 強制 100。
-- **RTL**:未特化——compact progress bar offset 用 physical `left/right`(見 `file-item.tsx`),RTL 支援需另案。
+- **RTL**:不支援；全域 LTR-only compatibility contract 見 `packages/design-system/README.md#compatibility-matrix`。compact progress offset 維持 physical direction。
 - **Dark mode**:走 semantic token 自動 adapt。無 `disabled` prop(展示型 row,非 form control)。
 
 ---

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

@@ -82,7 +82,7 @@ export const HoverSwap = {
         </div>
         {/* Rich border card list:無外框 + `gap-2`(item-anatomy「連續 item 貼邊合法性」) */}
         <div className="flex flex-col gap-2">
-          <FileItem mode="rich" name="Q1 營收報表.xlsx" status="completed"
+          <FileItem mode="rich" name="Q1 營收報表.xlsx" status="completed" data-visual-hover-target
             description="Uploaded to URL" thumbnailSrc="https://i.pravatar.cc/80?u=xls"
             onDownload={noop} actions={deleteBtn} />
           <FileItem mode="rich" name="合約草案 v3.pdf" status="error"

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

@@ -1,5 +1,6 @@
 // @story-trait-rationale: hasInteractiveStates 的 Disabled / States 由 anatomy.stories.tsx StateBehavior auto-compile owns(2026-05-15 F-migration);showcase 層展示真實上傳 / 自訂內容情境。
 import type { Meta } from '@storybook/react'
+import { within } from '@storybook/test'
 import { useState } from 'react'
 import { Image as ImageIcon, X } from 'lucide-react'
 import { FileUpload } from './file-upload'
@@ -116,6 +117,37 @@ export const WithFileList = {
   },
 }
 
+// beta.97 弱化 icon hover 一階的真實互動證據:
+// FileUpload 內建 files 清單自己渲染 remove Button,story 不以 className 模擬 hover。
+export const RemoveHoverState = {
+  name: '移除檔案懸停狀態',
+  tags: ['!autodocs'],
+  render: () => (
+    <div className="max-w-lg">
+      <FileUpload
+        title="上傳季度報告"
+        description="PDF,單檔最大 20 MB"
+        files={[
+          {
+            id: 'quarterly-report',
+            name: '2026-Q2-季度報告.pdf',
+            size: 2_500_000,
+            status: 'completed',
+          },
+        ]}
+        fileListMode="compact"
+        onRemove={noop}
+        onUpload={noop}
+      />
+    </div>
+  ),
+  play: async ({ canvasElement }: { canvasElement: HTMLElement }) => {
+    const canvas = within(canvasElement)
+    const remove = await canvas.findByRole('button', { name: '移除 2026-Q2-季度報告.pdf' })
+    remove.setAttribute('data-visual-hover-target', '')
+  },
+}
+
 // children 覆寫:Figma 匯入資產客製文案 / 品牌 logo
 export const CustomChildren = {
   name: '自訂內容',

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

@@ -208,7 +208,7 @@ const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
                       e.stopPropagation()
                       onRemove(f.id)
                     }}
-                    className="text-fg-muted hover:text-foreground"
+                    className="text-fg-muted hover:text-fg-secondary"
                   />
                 ) : undefined
               }

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

@@ -1124,7 +1124,7 @@ export const Accessibility = {
   render: () => (
     <div className="max-w-3xl text-body text-fg-secondary">
       <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
-      <p className="whitespace-pre-line">{"詳 `file-viewer.spec.md` 「A11y 預設」段。摘要:\n\nRadix DialogPrimitive 自動處理:\n-  role=\"dialog\" （Radix 1.1.x 不輸出 aria-modal 屬性;modal 隔離靠 focus trap + hideOthers 對背景兄弟樹加 aria-hidden,非 aria-modal）\n-  <DialogPrimitive.Title> (sr-only)自動成  aria-labelledby  目標——screen reader 開啟時讀「檔案檢視器:{file.name}」\n- Focus trap:焦點一旦進入 Content 即鎖在 viewer 內\n- Esc 關閉(Radix DismissableLayer,document capture-phase 監聽 → 即使焦點在 InfoPanel textarea 內按 Esc 仍會關閉整個 viewer);Backdrop click 關閉為自寫 geometric onClick handler(非 Radix outside-click — Content 為 fixed inset-0 全螢幕覆蓋,判斷 click 落在 img rect 外才關)\n\n自加的 a11y:\n- 所有 iconOnly button 皆有  aria-label (中文,跟 DS 其他元件風格一致)\n- Filmstrip  role=\"group\"  + thumb  <button>  +  aria-current (非 tablist:選圖導航非切 tabpanel)\n- InfoPanel 用  <aside aria-label=\"檔案詳細資訊\">  語意標記\n-  onOpenAutoFocus  preventDefault:僅取消 Radix 自動聚焦(焦點留在觸發按鈕、不主動移入 viewport);焦點實際進入 Content 後 FocusScope 才啟動 trap"}</p>
+      <p className="whitespace-pre-line">{"詳 `file-viewer.spec.md` 「A11y 預設」段。摘要:\n\nRadix DialogPrimitive 自動處理:\n-  role=\"dialog\" （Radix 1.1.x 不輸出 aria-modal 屬性;modal 隔離靠 focus trap + hideOthers 對背景兄弟樹加 aria-hidden,非 aria-modal）\n-  <DialogPrimitive.Title> (sr-only)自動成  aria-labelledby  目標——screen reader 開啟時讀「檔案檢視器:{file.name}」\n- Focus trap:開啟時 Content 本身取得焦點並立即鎖在 viewer 內\n- Esc 關閉(Radix DismissableLayer,document capture-phase 監聽 → 即使焦點在 InfoPanel textarea 內按 Esc 仍會關閉整個 viewer);Backdrop click 關閉為自寫 geometric onClick handler(非 Radix outside-click — Content 為 fixed inset-0 全螢幕覆蓋,判斷 click 落在 img rect 外才關)\n\n自加的 a11y:\n- 所有 iconOnly button 皆有  aria-label (中文,跟 DS 其他元件風格一致)\n- Filmstrip  role=\"group\"  + thumb  <button>  +  aria-current (非 tablist:選圖導航非切 tabpanel)\n- InfoPanel 用  <aside aria-label=\"檔案詳細資訊\">  語意標記\n- Content 固定 tabIndex=-1;onOpenAutoFocus 在 consumer 未取消時聚焦 fullscreen shell,不把焦點留在 aria-hidden 背景或誤觸第一個 toolbar tooltip"}</p>
     </div>
   ),
 }

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

@@ -370,7 +370,7 @@ Radix DialogPrimitive 自動處理:
 - 所有 iconOnly button 皆有 `aria-label`(中文,跟 DS 其他元件風格一致)
 - Filmstrip `role="group"` + `aria-label` + thumb `<button>` + `aria-current`(非 tablist;見「Filmstrip 規則」段理由)
 - InfoPanel 用 `<aside aria-label="檔案詳細資訊">` 語意標記
-- `onOpenAutoFocus={e => e.preventDefault()}` **僅取消** Radix 開啟時的自動聚焦(避免焦點跑進第一個 tabbable 觸發 tooltip);此 handler **不主動把焦點移入 viewport** —— 焦點停在觸發按鈕,直到 user 操作使焦點進入 Content,FocusScope 才啟動 trap。(known a11y gap:若要開啟即把焦點移入 viewer 需補 `tabIndex` + `ref.focus()`,屬 SSOT-affecting 待拍板)
+- `DialogContent` 固定 `tabIndex={-1}`；`onOpenAutoFocus` 先執行 consumer handler,若未被取消則阻止 Radix 把焦點送到第一個 toolbar control,並主動 `focus({ preventScroll: true })` fullscreen shell。開啟後焦點立即位於 viewer/FocusScope 內,不留在被 `aria-hidden` 的背景 trigger,也不因首個 icon button focus 而誤觸 tooltip。consumer 若有專屬初始焦點可在 handler 中 `preventDefault()` 後自行聚焦。
 
 ---
 

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

@@ -1,5 +1,6 @@
 import React from 'react'
 import type { Meta, StoryObj } from '@storybook/react'
+import { expect, waitFor } from '@storybook/test'
 import { FileViewer, type FileInfo } from './file-viewer'
 import { Button } from '@/design-system/components/Button/button'
 import { Image as ImageIcon, Paperclip, Camera, Figma } from 'lucide-react'
@@ -403,4 +404,10 @@ export const OpenSnapshot: Story = {
       />
     )
   },
+  play: async () => {
+    await waitFor(() => {
+      expect(document.activeElement).toHaveAttribute('role', 'dialog')
+      expect(document.activeElement).toHaveAttribute('tabindex', '-1')
+    })
+  },
 }

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

@@ -735,7 +735,7 @@ const DEFAULT_LABELS: Required<FileViewerLabels> = {
 export interface FileViewerProps
   extends Omit<
     React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>,
-    'onOpenChange'
+    'onOpenChange' | 'tabIndex'
   > {
   files: FileInfo[]
   initialIndex?: number
@@ -776,6 +776,7 @@ const FileViewer = React.forwardRef<HTMLDivElement, FileViewerProps>(function Fi
   onDownload,
   labels: labelsOverride,
   className,
+  onOpenAutoFocus,
   ...props
 }, ref) {
   const labels = React.useMemo(
@@ -793,6 +794,15 @@ const FileViewer = React.forwardRef<HTMLDivElement, FileViewerProps>(function Fi
     defaultValue: defaultOpen ?? false,
     onChange: onOpenChange,
   })
+  const contentRef = React.useRef<HTMLDivElement | null>(null)
+  const setContentRef = React.useCallback(
+    (node: HTMLDivElement | null) => {
+      contentRef.current = node
+      if (typeof ref === 'function') ref(node)
+      else if (ref) ref.current = node
+    },
+    [ref],
+  )
 
   // Index:uncontrolled fallback
   const [internalIndex, setInternalIndex] = React.useState(initialIndex)
@@ -949,7 +959,9 @@ const FileViewer = React.forwardRef<HTMLDivElement, FileViewerProps>(function Fi
           )}
         />
         <DialogPrimitive.Content
-          ref={ref}
+          ref={setContentRef}
+          {...props}
+          tabIndex={-1}
           className={cn(
             // Edge-to-edge fullscreen,無 inset / 無 radius(與一般 Dialog 差別的所在)
             'fixed inset-0 z-50 outline-none',
@@ -958,9 +970,15 @@ const FileViewer = React.forwardRef<HTMLDivElement, FileViewerProps>(function Fi
             'data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
             'data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95',
           )}
-          // 避免 Radix 自動把焦點送進 Content 的第一個 tabbable —— 我們要留給 viewport
-          onOpenAutoFocus={(e) => e.preventDefault()}
-          {...props}
+          // FileViewer 是 fullscreen content-consumption dialog：開啟即把焦點放到 shell，
+          // 讓 Radix FocusScope 立即接管、但不誤觸第一個 toolbar control/Tooltip。
+          // Consumer handler 可先取消；未取消時由本元件阻止 Radix default 並聚焦 Content。
+          onOpenAutoFocus={(event) => {
+            onOpenAutoFocus?.(event)
+            if (event.defaultPrevented) return
+            event.preventDefault()
+            contentRef.current?.focus({ preventScroll: true })
+          }}
         >
           {/* 鎖 dark subtree。Density 繼承 page(不另設 data-density)。
               header 高度透過 `--chrome-header-height` 自動 density-aware(md=48 / lg=56)。

package/src/components/InlineEdit/inline-edit.spec.md

@@ -74,6 +74,12 @@ InlineEdit 本體只給:**對齊盒(-mx orientation-aware)+ 委派 view 統一 f
 
 **尺寸預設 = `sm`**（2026-07-09 user 拍板）:view 態無邊框、視覺即純文字,尺寸過大會使版面鬆散;consumer 可傳 `size` 覆寫,標題場景另用 `readClassName` 疊大字級。
 
+**在 `<Field>` 內也是 `sm`**(2026-07-28 user 拍板):Field 的預設 `md` 是「沒人決定過」的預設值,不得壓過本元件宣告的 `sm`。實作雙通道 —— 靜態 `InlineEdit.fieldPreferredSize = 'sm'` 供 Field 直接子元件同步偵測,加上掛載時的 `useRegisterFieldPreferredSize('sm')` 補位(包 wrapper / `React.memo` / HOC 會遮蔽靜態);控件自身尺寸則由 `useResolvedFieldSize` 依 `sizeExplicit` 同步解析,不等註冊。**唯有 consumer 顯式 `size`(在 Field 或 InlineEdit 上)才覆寫**。機制與失效語意 owner → `Field/field.spec.md`「Control 偏好尺寸 SSOT」。
+
+**單行 view 恆一行**(2026-07-28 user 拍板):`multiline=false` 的 view 態溢出**不換行**,一律 ellipsis,且**截斷才顯 tooltip**顯示完整值(規則 owner:`Tooltip/tooltip.spec.md`「截斷文字 → tooltip」+ `truncated-text.spec.md`)。**實作 = `useTruncated` 自組而非 `<TruncatedText>`**:view 上疊著透明 Pressable(click-to-edit 入口)會吞掉內層所有 hover,tooltip trigger 必須掛在**整個 view 容器**、量測留在內層值 span —— 這正是 truncated-text.spec 對「trigger 需自控」場景指定的 escape(2026-07-28 user 實測抓到 primitive 直用時 tooltip 永不開)。委派 view(`renderRead`)同一條規則、同一個外層 Tooltip:委派控件自帶的截斷 tooltip(Input `<TruncatedText>` / Tag)trigger 在內層,editable 時同樣被 Pressable 攔截 —— 故外層容器 Tooltip 一併服務委派路徑:`useTruncated` 傳自訂 `measure`(`hooks/use-truncated.ts` options.measure 即為此類自訂策略開的口)走訪 wrapper 子樹,任一 `.truncate` 後代溢出即視為截斷;tooltip 內容 = wrapper 當下 DOM 的 `textContent`(完整格式化文字;非 string `T` 不可 `String(value)`)。`editable=false` 不渲染 Pressable → 委派控件自身 tooltip 可達,外層讓位不重複顯示。多行(`multiline`)維持 `pre-wrap` 忠實呈現。
+
+**多行 edit 高度隨內容**(2026-07-28 user 拍板):view 態高度由內容決定,edit 態必須同源,否則 read↔edit 跳高。預設 `Textarea autoSize`(`field-sizing: content`),consumer 以 `editMaxRows` 設上限、超過改捲動。與 DataTable cell 共用同一份 `autoSize` 實作(原本只有 cell 有呼叫端膠水 → 兩者漂移)。
+
 **核心不變量:view 態 hover = 背景 tint;view 態 focus = Field 藍框（`border-primary`）,與 edit 態同源。** hover（滑鼠懸停）用底色、focus（鍵盤選中）用藍框——藍框是 edit focus 的預覽,view→edit 一路都是藍框、不會 ring→框跳一下;靜止（無 hover/focus）則透明邊框不可見 = 純值。
 
 ## 型別化 view + 多行 + 鍵盤 SSOT（2026-07-09 L2）
@@ -172,3 +178,9 @@ InlineEdit 是 **composite 編排層**(view 對齊盒 + 隱形 Pressable + 動
 - ❌ 空值顯示唯讀展示的半形 `-` dash——InlineEdit 是可編輯欄位,空值 = placeholder 或空白
 - ❌ view 態語意標籤用 heading 時把它塞進 button——用隱形 Pressable 疊加,保留文件大綱
 - ❌ 用 disabled / 灰化表達鎖定——就地編輯無 disabled 態,鎖定 = `editable=false` 純 view 無入口、不灰化(見「editable 閘」)
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `field.spec.md`