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

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

@@ -20,7 +20,7 @@ benchmark:
 
 **Layout Family**:self-contained(form composition layout-primitive,非 4-Family element layout — 對齊 frontmatter `family: self-contained`)。
 
-**多個 Field controls 視覺接合成一個 input frame**(border-collapse pattern)。對齊 ButtonGroup 同類接合 idiom — `<X>Group` 命名一致(X = button → ButtonGroup;X = field control → FieldControlGroup)。
+**多個 Field controls 視覺接合成一個 input frame**(border-collapse pattern)。命名對齊 ButtonGroup 的 `<X>Group` idiom(X = button → ButtonGroup;X = field control → FieldControlGroup),**但兩者機制不同**:ButtonGroup 是 gap 分離群組(`flex gap-2`,子按鈕之間留 8px),本元件才是 border-collapse 接合(負 margin 重疊 border,子無 gap)。
 
 **自建 + 理由**:無單一 Radix / shadcn 對應 primitive(shadcn 沒提供;Radix 沒對應)。對齊 [Ant `Space.Compact`](https://ant.design/components/space#spacecompact)(verified source)mechanism + [Bootstrap `.input-group`](https://getbootstrap.com/docs/5.3/forms/input-group/)(verified SCSS)idiom 自建。
 
@@ -46,7 +46,7 @@ benchmark:
 | `FieldGroup` | 多 Field 垂直堆疊 | gap 分離 | layout primitive |
 | **`FieldControlGroup`** | 多 control 橫向接合 | border collapse | layout primitive(本元件)|
 | `RadioGroup` / `CheckboxGroup` | 1 question 多 options | 各自獨立 | semantic group(ARIA role)|
-| `ButtonGroup` | 多 Button 接合 | border collapse | layout primitive(同 mechanism) |
+| `ButtonGroup` | 多 Button 分組 | gap 分離(`flex gap-2`) | layout primitive(**不同 mechanism**,非 border-collapse 接合) |
 
 ## API
 
@@ -149,6 +149,11 @@ interface FieldControlGroupProps extends HTMLAttributes<HTMLDivElement> {
 ```
 保留 global `bg-disabled`(neutral-2 灰底)— disabled state 視覺主要由 bg 承載。
 
+**⚠️ 選擇器覆蓋範圍(2026-07-13 誠實標註 — code 現況,非 uniform)**:disabled state 的兩道視覺處理走**不同選擇器、覆蓋不同 child 類型**,並非對所有 disabled 子一致生效:
+- **z-index 降 0**:`[&>*[disabled]]:z-0` + `[&>*:has([disabled])]:z-0` — 認**原生 `[disabled]` 屬性**。覆蓋 Button(原生 `<button disabled>`)、Input / NumberInput(wrapper 內含原生 `<input disabled>`,`:has()` 命中)。
+- **border-opaque override**:`[&>*[data-field-mode="disabled"]]` — 認 **Field 家族 wrapper 的 `data-field-mode="disabled"`**。覆蓋所有 Field controls(Select / Input / Combobox / DatePicker…)。
+- **覆蓋落差(已知)**:disabled **Select**(桌機自訂 trigger = `<div>`,無原生 `[disabled]`)→ 得 border-opaque 但**不降 z-0**;disabled **Button**(無 `data-field-mode`)→ 降 z-0 但**不得 border-opaque**。要讓兩道處理對所有 disabled 子一致覆蓋需統一兩選擇器(視覺行為改動 → 走設計拍板,非本文件範圍)。
+
 **為什麼用 `--border-opaque` 而非 `--border`**:`--border`(neutral-5 = 15% alpha)會跟 cell bg compositing — 灰底上 composite 略深(物理對比結果)。**`--border-opaque`** semantic token(其 primitive 後盾為 `--color-neutral-5-opaque`,solid #D9D9D9)不分 bg 永遠同色,divider 在 white edit cell 跟 grey disabled cell 上視覺完全一致。
 
 **Token 系統設計**:`--border-opaque` 在 `semantic.css` 新增(grep `--border-opaque:` 查定義行,不寫死行號避免漂移),語意「視覺等同 `--border` 但 alpha-immune」。對齊 [Ant Design `colorBorderSecondary`](https://ant.design/docs/react/customize-theme#seedtoken) solid idiom — Ant 用此 token 在 table 外框 + row divider(non-white bg 場景),跟 input alpha border 視覺層級分。
@@ -168,7 +173,7 @@ interface FieldControlGroupProps extends HTMLAttributes<HTMLDivElement> {
 ## 邊界案例
 
 - **子高度不一**:容器 `items-stretch`,但 field controls 自帶固定 `h-field-*`,不會被拉齊——混 size 即視覺高低差(故禁止,見禁止事項)
-- **某子 disabled、某子 edit**:機制上可行(disabled 子降 z-0 + K12 border 維持 divider),但語意一體應一致(見禁止事項);**全組 disabled** 走 K12 canonical(見 States)
+- **某子 disabled、某子 edit**:機制上可行(disabled 子降 z-0 + K12 border 維持 divider,實際覆蓋依 child 類型而異 — 見 K12「選擇器覆蓋範圍」note),但語意一體應一致(見禁止事項);**全組 disabled** 走 K12 canonical(見 States)
 - **極窄容器**:無特化處理——固定寬 children(`w-[Xpx]`)溢出容器、`flex-1` children 壓縮;子自管 width 的對價,consumer 自行配置
 - **單一 child**:radius 選擇器 `:first-child:not(:last-child)` 不命中,圓角完整保留(等同未包 group,但此時應直接用 Field)
 
@@ -186,7 +191,7 @@ interface FieldControlGroupProps extends HTMLAttributes<HTMLDivElement> {
 ## 相關
 
 - `../Field/field.spec.md` — FieldGroup(多 Field 垂直堆疊近親,gap 分離)的 home
-- `../Button/button-group.tsx` — 同 border-collapse mechanism 的 Button 版(無獨立 spec,機制同源)
+- `../Button/button-group.tsx` — 命名 idiom 近親(`<X>Group`);但 ButtonGroup 是 **gap 分離**(`flex gap-2`),非 border-collapse 接合,兩者機制不同(無獨立 spec)
 - `../Field/field-controls.spec.md` — children(Input / Select / DatePicker 等)共用 Field control 規則
 - `../Checkbox/checkbox.spec.md` / `../RadioGroup/radio-group.spec.md` — semantic group 近親(1 question 多 options,非本元件 scope)
 

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

@@ -16,7 +16,7 @@ import type { FieldSize } from '@/design-system/components/Field/field-context'
  *
  * **Naming rationale**(2026-05-04):
  * - Taxonomic 一致:FieldGroup(多 Field 堆疊)/ FieldControlGroup(多 control 接合)— scope 區分
- * - Idiom 一致:ButtonGroup(多 Button 接合)同 pattern,只是 X = field control
+ * - 命名 idiom 一致:與 ButtonGroup 共享 <X>Group 命名(X = field control);但**機制不同** — ButtonGroup 是 gap 分離群組(flex gap-2),本元件才是 border-collapse 接合(負 margin 重疊 border)
  * - 不撞 RadioGroup/CheckboxGroup(那是 1-question 多 options semantic group)
  *
  * **Behavior canonical**(verified Ant compact-item.ts L21-58):

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

@@ -72,7 +72,7 @@ export const Inspector: Story = {
     docs: { description: { story: '右側 Controls 切 props 即時 render,取代 Figma inspect。調整 `mode` / `status` / `progress` 看 compact vs rich 佈局與狀態 icon/進度條變化。' } },
   },
   args: {
-    name: 'Q1 行銷報告 PDF（範例檔）',
+    name: 'Q1 行銷報告.pdf',
     mode: 'rich',
     status: 'uploading',
     progress: 60,

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

@@ -19,7 +19,7 @@ benchmark:
 
 **實作基礎**：組合元件——Icon + Text + ProgressBar + Button，無 external primitive base。
 
-**Layout Family**：CLAUDE.md 4-Family Model **Family 2（List item layout）** 消費者。結構繼承 `patterns/element-anatomy/item-anatomy.spec.md`「List item layout」章節的 reading-mode 規格。FileItem 在 rich mode 用 avatar 作 item boundary。
+**Layout Family**：CLAUDE.md 4-Family Model **Family 2（List item layout）** 消費者。結構繼承 `patterns/element-anatomy/item-anatomy.spec.md`「List item layout」章節,兩 mode 皆採 scanning-mode 規格（見下「Typography」段:FileItem 固定傳 ItemContent `mode="scanning"`）。FileItem 在 rich mode 用 avatar 作 item boundary。
 
 **命名 rationale**：`compact / rich` 表達精簡 vs 完整內容呈現（對齊 Discord embed type='rich' / Slack rich preview / Notion rich text 世界級 idiom）。不叫 `lg/sm`——兩者是資訊量不同的展示策略，不是同一結構的尺寸縮放。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
@@ -114,7 +114,7 @@ compact 為預設——多數 upload 清單是「快速掃視多檔」場景，
 item-anatomy「> 24 prefix + 有 desc」規則要求 prefix 對齊 content 塊**中心**(items-center)。
 FileItem rich **刻意不遵守**這條,使用 `items-start`(top-align),原因:
 
-> **當 FileItem rich 被放在「檔案上傳管理 box」等 tight-stack 情境**(consumer 移除 border 並 0 gap 相連時),avatar 作為**每個 item 的視覺邊界引導**——若 avatar 中心對齊,連續 item 的 avatar 會擠在一起失去「每筆檔案一個 thumbnail」的視覺節奏。top-align 讓 avatar 明確標示每個 item 的起點。
+> **當 FileItem rich 被放在「檔案上傳管理 box」等 tight-stack 情境**(`surface=upload-manager` 無邊框、列間 `--layout-space-tight` 12px 緊貼時,見「List wrapper canonical」),avatar 作為**每個 item 的視覺邊界引導**——若 avatar 中心對齊,連續 item 的 avatar 會失去「每筆檔案一個 thumbnail」的視覺節奏。top-align 讓 avatar 明確標示每個 item 的起點。
 
 ### Avatar 尺寸(固定 48px)
 
@@ -150,7 +150,8 @@ Avatar **固定 48px square**,不隨 content 高度變化。content(label + desc
 
 | Mode | 永久 visual anchor | 加 hover-bg 後果 |
 |------|-------------------|-----------------|
-| rich | `border + rounded-md + bg-surface` 永遠 card | card + hover-bg = 雙層強調,視覺 heavy |
+| rich(`surface=form`) | `border + rounded-md + bg-surface` card | card + hover-bg = 雙層強調,視覺 heavy |
+| rich(`surface=upload-manager`) | Avatar 48 thumbnail 作 item 邊界(無邊框/無 bg,面板自身是容器) | thumbnail 已提供「每筆檔案」節奏,hover-bg 多餘 |
 | compact 無 status(靜態) | `bg-secondary rounded-md` 永遠 pill | pill bg + hover-bg neutral-hover 兩層相近灰,視覺雜 |
 | compact 有 status(uploading / error / completed with bar) | 底部 2px progress bar(分隔線型 permanent affordance) | bar + hover-bg 同時並存,affordance 重複 |
 
@@ -168,12 +169,8 @@ Avatar **固定 48px square**,不隨 content 高度變化。content(label + desc
 
 **跟 MenuItem / DataTable row 對比**(它們用 hover-bg):兩者是 **flush transparent row**(無 permanent bg / border),hover-bg 是唯一 affordance。FileItem 三種型態皆已 anchored → 反向 canonical。
 
-**反例**(本 session 修正):
-- 原 code `hoverClass = onClick ? 'cursor-pointer hover:bg-neutral-hover' : ''` → rich card 上 hover 多一層灰 bg 雙層強調;無 status pill 上 hover 加 `bg-neutral-hover` 跟 pill 底色近似造成視覺雜
-- 修為 `hoverClass = onClick ? 'cursor-pointer' : ''`
-
 **❌ 反例**:
-- Rich mode 無邊框 → 與一般 list item 無法區分,跟 MenuItem 混淆
+- Rich `surface=form` 無邊框 → 失去 card 自立輪廓,與一般 list item 無法區分,跟 MenuItem 混淆(`surface=upload-manager` 例外:面板自身是容器 + avatar 作邊界,rich 刻意無邊框,見上表)
 - Compact mode 靜態 item 無 bg → 純文字列,使用者不知這是「可點下載的檔案」
 - 外層 list wrapper 加邊框 / `overflow-hidden` → 雙重邊框(list 邊框 + item card 邊框)視覺干擾;並強制邊框相黏破壞 card 自立性(2026-04-22 user 糾正)
 

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

@@ -93,7 +93,7 @@ export const HoverSwap = {
       </div>
       <div>
         <div className="text-caption text-fg-muted mb-2">
-          同樣 pattern 在 compact mode:status slot 幾何與 delete action 一致(兩 mode 統一 Button xs 24),center 自動對齊
+          緊湊樣式也是同一套規則:狀態圖示與刪除鈕的大小、位置一致,垂直置中對齊
         </div>
         {/* Compact list 統一 gap-1(canonical 簡化) */}
         <div className="flex flex-col gap-1">
@@ -156,30 +156,41 @@ export const Clickable = {
     }
     return (
       <>
-        <div className="flex flex-col gap-2 max-w-md">
-          {attachmentFiles.map((f, i) => {
-            const isImage = i < 2 // 前兩個 rich card(有 thumbnail)
-            const sizeLabel = f.description ?? (f.size != null ? `${(f.size / 1024 / 1024).toFixed(1)} MB` : '—')
-            return isImage ? (
-              <FileItem
-                key={f.id}
-                mode="rich"
-                name={f.name}
-                description={sizeLabel}
-                thumbnailSrc={f.url}
-                onClick={() => openAt(i)}
-                actions={deleteBtn}
-              />
-            ) : (
-              <FileItem
-                key={f.id}
-                mode="compact"
-                name={f.name}
-                onClick={() => openAt(i)}
-                actions={deleteBtn}
-              />
-            )
-          })}
+        {/* 2026-07-14 Dim 68 修:原本同一 list 依檔案類型混 rich(圖片)+ compact(文件),
+            違反 file-item.spec.md「❌ 不混用 rich + compact 在同一 list」(Invariant 1 —
+            高度差破壞 row rhythm)。改拆兩個區段:圖片整組 rich、文件整組 compact,
+            同區段 mode 統一(spec 建議的分區段做法);FileViewer index 跨兩區段連續。 */}
+        <div className="flex flex-col gap-4 max-w-md">
+          <div className="flex flex-col gap-1.5">
+            <h3 className="text-caption font-medium text-fg-muted">圖片</h3>
+            <div className="flex flex-col gap-2">
+              {attachmentFiles.slice(0, 2).map((f, i) => (
+                <FileItem
+                  key={f.id}
+                  mode="rich"
+                  name={f.name}
+                  description={f.description ?? (f.size != null ? `${(f.size / 1024 / 1024).toFixed(1)} MB` : '—')}
+                  thumbnailSrc={f.url}
+                  onClick={() => openAt(i)}
+                  actions={deleteBtn}
+                />
+              ))}
+            </div>
+          </div>
+          <div className="flex flex-col gap-1.5">
+            <h3 className="text-caption font-medium text-fg-muted">文件</h3>
+            <div className="flex flex-col gap-1">
+              {attachmentFiles.slice(2).map((f, i) => (
+                <FileItem
+                  key={f.id}
+                  mode="compact"
+                  name={f.name}
+                  onClick={() => openAt(i + 2)}
+                  actions={deleteBtn}
+                />
+              ))}
+            </div>
+          </div>
         </div>
         <FileViewer files={attachmentFiles} open={open} onOpenChange={setOpen} index={index} onIndexChange={setIndex} />
       </>

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

@@ -112,7 +112,8 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
     const showDesc = isRich ? !!description : (status === 'error' && !!description)
 
     // Hover 行為 canonical(2026-04-23 user 校準):**FileItem 永不顯示 hover-bg**。
-    // 三種型態都有永久 visual anchor:rich = border card / compact 無 status = bg-secondary /
+    // 各型態都有永久 visual anchor:rich surface=form = border card / rich surface=upload-manager
+    // = avatar 48 thumbnail 作 item 邊界(無邊框)/ compact 無 status = bg-secondary /
     // compact 有 status = 底部 progress bar(分隔線型 affordance)——再加 hover-bg 是
     // double-emphasis,視覺雜。世界級共識(Slack / Notion / Figma / Gmail 皆無 hover-bg):
     // permanent-anchored 元件 hover 只靠 cursor + action icon fade / border highlight,
@@ -144,8 +145,8 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
     const slotHw = 'var(--field-height-xs)'
 
     const hoverAction =
-      status === 'completed' && onDownload ? { icon: Download, onClick: onDownload, label: '下載' } :
-      status === 'error' && onRetry        ? { icon: RotateCw, onClick: onRetry,    label: '重試' } :
+      status === 'completed' && onDownload ? { icon: Download, onClick: onDownload, label: `下載 ${name}` } :
+      status === 'error' && onRetry        ? { icon: RotateCw, onClick: onRetry,    label: `重試 ${name}` } :
       null
 
     const statusSlot = statusConfig ? (
@@ -237,9 +238,10 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
     // 底色同樣指向 `--color-neutral-3`。對齊 Badge low / ProgressBar track SSOT。
     const compactStaticBg = !progressBar ? 'bg-secondary' : ''
 
-    // ── rich(含縮圖完整呈現)——AR17 canonical:加邊框 + gap-2 ──
-    // Rich mode 是「檔案 card」風格,外框讓每個 row 視覺上是獨立 card
-    // (Slack / Notion / Linear attachment 慣例)
+    // ── rich(含縮圖完整呈現)——AR17 canonical:surface=form 加邊框 card / surface=upload-manager 無邊框 ──
+    // Rich surface=form 是「檔案 card」風格,外框讓每個 row 視覺上是獨立 card(Slack / Notion /
+    // Linear attachment 慣例);surface=upload-manager 無邊框,avatar 作 item 邊界(面板自身是容器,
+    // 見 file-item.spec.md「邊框 / 背景」表)
     if (isRich) {
       return (
         <div

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

@@ -164,8 +164,8 @@ export const Inspector: Story = {
               </div>
               <div className="flex items-center gap-1.5">
                 border:{' '}
-                <TokenCell token={state === 'drag-over' ? '--primary' : '--border'} />
-                <span className="text-fg-muted">(idle `--border` 元件邊框;hover=drag-over 統一 `--primary`,純 border-driven)</span>
+                <TokenCell token={state === 'drag-over' ? '--primary-hover' : '--border'} />
+                <span className="text-fg-muted">(idle `--border` 元件邊框;hover=drag-over 統一 `--primary-hover`(blue-5),純 border-driven)</span>
               </div>
               <div className="flex items-center gap-1.5">
                 icon glyph: <TokenCell token={state === 'disabled' ? '--fg-disabled' : '--foreground'} />
@@ -225,12 +225,12 @@ export const ColorMatrix: Story = {
                 <Td>
                   <TokenCell token="--foreground" />
                 </Td>
-                <Td>`--border` 元件邊框(非 `--divider`);hover → border 切 `--primary`(同 drag-over)</Td>
+                <Td>`--border` 元件邊框(非 `--divider`);hover → border 切 `--primary-hover`(同 drag-over)</Td>
               </tr>
               <tr>
                 <Td mono>drag-over = hover</Td>
                 <Td>
-                  <TokenCell token="--primary" />
+                  <TokenCell token="--primary-hover" />
                 </Td>
                 <Td>
                   <TokenCell token="--surface" />
@@ -238,7 +238,7 @@ export const ColorMatrix: Story = {
                 <Td>
                   <TokenCell token="--foreground" />
                 </Td>
-                <Td>hover 與 drag-over 統一:純 border-driven(只切 `--primary` 邊框,底色維持 surface,對齊 Ant Dragger)</Td>
+                <Td>hover 與 drag-over 統一:純 border-driven(只切 `--primary-hover` 邊框,底色維持 surface,對齊 Ant Dragger)</Td>
               </tr>
               <tr>
                 <Td mono>disabled</Td>
@@ -353,7 +353,7 @@ export const StateBehavior: Story = {
               <tr>
                 <Td mono>dragenter</Td>
                 <Td>檔案拖入區塊</Td>
-                <Td>`data-state="drag-over"`(border-primary;底色維持 surface,純 border-driven = hover)</Td>
+                <Td>`data-state="drag-over"`(border-primary-hover;底色維持 surface,純 border-driven = hover)</Td>
               </tr>
               <tr>
                 <Td mono>dragleave</Td>

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

@@ -76,7 +76,7 @@ export const UsageGuidance: Story = {
           <LinkTo kind="Design System/Components/FileUpload/展示" name="自訂內容"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">品牌化上傳區 — 自訂 dropzone 內容</span></LinkTo>
         </li>
       </ul>
-      <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見 <code>Vs*Rule</code> stories)。</p>
+      <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見本頁 <code>UsageGuidance</code>「vs 近親」段)。</p>
     </div>
 
       {/* 何時不用 / 替代元件 — 原 WhenNotToUse */}
@@ -90,13 +90,13 @@ export const UsageGuidance: Story = {
 
       <Rule
         title="❌ 不加 scale / shadow 等裝飾性 drag-over 信號"
-        note="drag-over 只用邊框顏色(border-primary,底維持 surface 不變 bg)傳達狀態。加 scale 會讓區塊在拖放瞬間晃動、使用者滑鼠與 drop target 錯位;加 shadow 和元件 elevation 體系衝突。"
+        note="drag-over 只用邊框顏色(border-primary-hover,底維持 surface 不變 bg)傳達狀態。加 scale 會讓區塊在拖放瞬間晃動、使用者滑鼠與 drop target 錯位;加 shadow 和元件 elevation 體系衝突。"
       >
         <div className="flex flex-col gap-2">
-          <div className="border-2 border-dashed border-primary bg-surface rounded-md p-[var(--layout-space-loose)] text-center text-caption text-fg-muted">
-            ✓ 僅改邊框顏色(dashed primary,底維持 surface)
+          <div className="border-2 border-dashed border-primary-hover bg-surface rounded-md p-[var(--layout-space-loose)] text-center text-caption text-fg-muted">
+            ✓ 僅改邊框顏色(dashed primary-hover,底維持 surface)
           </div>
-          <div className="border-2 border-dashed border-primary bg-surface rounded-md p-[var(--layout-space-loose)] text-center text-caption text-fg-muted scale-105 shadow-[var(--elevation-200)]">
+          <div className="border-2 border-dashed border-primary-hover bg-surface rounded-md p-[var(--layout-space-loose)] text-center text-caption text-fg-muted scale-105 shadow-[var(--elevation-200)]">
             ✗ scale + shadow — 視覺噪音,與 elevation 系統衝突
           </div>
         </div>

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

@@ -135,7 +135,7 @@ FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點
 - **空選取(0 檔)**:不觸發任何 callback;`files={[]}` 不渲染清單(等同不傳)
 - **maxSize / accept 全擋下**:`onUpload` 不觸發,只觸發 `onReject`
 - **同檔重選**(2026-07-05 D4):input value 於 dispatch 後清空 — 「上傳失敗修正後重選同檔」「刪除後重傳同檔」仍觸發 `onUpload`(瀏覽器對同路徑檔案不重發 change event,不清空則靜默無反應)
-- **拖曳滑過內部子元素**(2026-07-05 D4):pointer 移過 Empty 的 icon/title 時 drag-over 高亮不熄滅(dragleave 帶 relatedTarget guard,避免經典 drag-flicker)
+- **拖曳滑過內部子元素**(2026-07-06 深度計數):pointer 移過 Empty 的 icon/title 時 drag-over 高亮不熄滅 — dragenter/dragleave 成對 +1/−1 深度計數,計數 > 0 即維持高亮;不依賴 `e.relatedTarget`(Safari/WebKit 的 dragleave relatedTarget 恆 null,guard 法必失效,故已於 2026-07-06 廢棄換深度計數),避免經典 drag-flicker
 - **Disabled / loading 時拖檔 drop**(2026-07-05 D4):操作被吞掉 — 仍 `preventDefault` 擋瀏覽器預設「在當前 tab 開啟被丟檔案」的整頁導航,`onUpload` 不觸發
 - Disabled / loading 見「四狀態視覺」;dark mode / density 由 semantic token 自動處理
 

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

@@ -16,7 +16,7 @@ import { Button } from '@/design-system/components/Button/button'
  *
  * ── 4 狀態(2026-06-03 修正)──
  * idle     (default) — border-dashed border-border  bg-surface
- * hover = drag-over  — border-primary(統一,純 border-driven,底維持 surface)
+ * hover = drag-over  — border-primary-hover(統一,純 border-driven,底維持 surface;2026-07-06 對齊 Ant colorPrimaryHover)
  * loading            — CircularProgress;cursor-progress(無 pointer-events-none)
  * disabled           — bg-disabled + 文字 fg-disabled(語意 token,非 opacity)+ cursor-not-allowed
  *

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

@@ -826,7 +826,7 @@ export const StateBehavior: Story = {
               <tr>
                 <Td>連續 / 任意值</Td>
                 <Td mono>滾輪(step 0.03)/ ZoomInput 打字</Td>
-                <Td>multiplicative 連續縮放,任意 %(非 preset;spec「Wheel step canonical」);ZoomInput preset menu 才跳 preset</Td>
+                <Td>連續縮放,任意 %(非 preset;react-zoom-pan-pinch wheel = `scale + delta×step` 加法線性,非 multiplicative;spec「Wheel step canonical」);ZoomInput preset menu 才跳 preset</Td>
               </tr>
               <tr>
                 <Td>Reset 100%</Td>
@@ -903,7 +903,8 @@ export const StateBehavior: Story = {
       <div>
         <H3>Keyboard shortcut 對照</H3>
         <Desc>
-          Focus 在 input / textarea / contentEditable 時**全部不觸發**(避免打字被快捷鍵劫持)。
+          Focus 在 input / textarea / contentEditable 時,FileViewer 自管的快捷鍵(← → / +・−・0 / F / I)**全部不觸發**(避免打字被快捷鍵劫持)。
+          **例外:Esc** 由 Radix DismissableLayer 以 document capture-phase 監聽,不受此排除影響 —— 在 InfoPanel textarea 內按 Esc 仍會關閉整個 viewer。
           所有 keyboard 動作都有 toolbar button 對應(a11y + tablet / touch 可用性)。
         </Desc>
         <div className="overflow-x-auto">
@@ -1123,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\"  +  aria-modal=\"true\" \n-  <DialogPrimitive.Title> (sr-only)自動成  aria-labelledby  目標——screen reader 開啟時讀「檔案檢視器:{file.name}」\n- Focus trap:焦點鎖在 viewer 內\n- Esc 關閉(Radix DismissableLayer);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:避免焦點自動跑進第一個 tabbable(讓鍵盤從 viewport 開始)"}</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-  onOpenAutoFocus  preventDefault:僅取消 Radix 自動聚焦(焦點留在觸發按鈕、不主動移入 viewport);焦點實際進入 Content 後 FocusScope 才啟動 trap"}</p>
     </div>
   ),
 }

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

@@ -258,7 +258,7 @@ export const CloseButtonPositionRule: Story = {
       <div>
         <Rule
           title="✅ toolbar 順序 — zoom → info → download → close(影響力遞增)"
-          note="DS 設計準則三方交集:(1) action-bar「全局 primary 在最右」影響力遞增;(2) Notice dismiss X always rightmost;(3) Dialog close 靠右的跨平台慣例(macOS / Windows / Web 一致)。zoom 影響單檔 transform / info 影響 layout / download 搬內容出 viewer / close unmount 所有 state — 影響越大越右"
+          note="DS 設計準則三方交集:(1) action-bar「全局 primary 在最右」影響力遞增;(2) Notice dismiss X always rightmost;(3) Dialog close 靠右的跨平台慣例(macOS / Windows / Web 一致)。zoom 影響單檔 transform / info 影響 layout / download 搬內容出 viewer / close 卸載 DialogContent 子樹(shell state 保留於恆掛載外層)— 影響越大越右"
         >
           <Button variant="tertiary" startIcon={FolderOpen} onClick={() => setOpen(true)}>
             開啟 Dashboard 設計稿
@@ -423,13 +423,13 @@ export const ReadOnlyRule: Story = {
 
         <Rule
           title="✅ readOnly — 其他人上傳的 / 公開公告 / 只讀 link 分享"
-          note="readOnly=true 時 textarea 變 readOnly,onDescriptionChange 不觸發。placeholder 改為「尚無說明」讓無 description 時也不顯示「為這個檔案加上說明...」誘導編輯的文字"
+          note="readOnly=true 時說明區依 DS Textarea readonly canonical:有值 → 可聚焦選取但不可改的 native readonly textarea;空值 → display div 顯 emptyDisplay(`-`,非 placeholder);onDescriptionChange 不觸發。故 readonly 無 description 時顯示 `-`,不會出現「為這個檔案加上說明...」的編輯誘導 placeholder"
         >
           <Button variant="tertiary" startIcon={FolderOpen} onClick={() => setRoOpen(true)}>
             開啟公司公告(readOnly)
           </Button>
           <FileViewer files={publicFiles} open={roOpen} onOpenChange={setRoOpen} readOnly />
-          <Label>↑ 按 I 打開 info panel,textarea 不可編輯、focus 不進游標</Label>
+          <Label>↑ 按 I 打開 info panel;readonly 有值 = 可聚焦選取但不可改的 textarea,無值 = 顯 `-`</Label>
         </Rule>
 
         <Rule

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

@@ -20,7 +20,7 @@ benchmark:
 
 FileViewer 是**可延伸的網頁檔案預覽殼層(modal fullscreen)**——負責 overlay / toolbar / 鍵盤 / filmstrip / 詳細資訊面板一切 chrome,檔案本體由 **renderer registry** 按 file type 決定誰渲染。MVP 內建 `ImageRenderer` + `FallbackRenderer`,未來可透過 `registerFileRenderer()` 擴充 PDF / Video / Code 等 renderer 而不動 shell。
 
-**實作基礎**:自建 composite——直接消費 Radix `DialogPrimitive` 而非 DS 的 `<Dialog>` wrapper。原因:FileViewer 需要 edge-to-edge fullscreen(無 viewport inset / 無 rounded-lg / 無 maxWidth),這些全要覆寫 `<Dialog>` 預設。直接消費 Radix primitive 讓 shell 擁有完整 layout 控制權,同時保有 Radix focus trap / Esc / aria-modal 的結構優勢。內部消費 DS 元件:`<Button>` / `<Input>` / `<Empty>` / `<Separator>` / `<AspectRatio>` / `<Textarea>` / `<Field>`+`<FieldLabel>` / `<DescriptionList>` / `<ScrollArea>` / `<DropdownMenu>` / `<ChromeHeader>` / `ItemInlineActionButton` + `patterns/horizontal-overflow`。
+**實作基礎**:自建 composite——直接消費 Radix `DialogPrimitive` 而非 DS 的 `<Dialog>` wrapper。原因:FileViewer 需要 edge-to-edge fullscreen(無 viewport inset / 無 rounded-lg / 無 maxWidth),這些全要覆寫 `<Dialog>` 預設。直接消費 Radix primitive 讓 shell 擁有完整 layout 控制權,同時保有 Radix focus trap(FocusScope)/ Esc / modal 隔離(`hideOthers` 對背景兄弟樹加 `aria-hidden`;Radix `react-dialog@1.1.x` 不輸出 `aria-modal` 屬性)的結構優勢。內部消費 DS 元件:`<Button>` / `<Input>` / `<Empty>` / `<Separator>` / `<AspectRatio>` / `<Textarea>` / `<Field>`+`<FieldLabel>` / `<DescriptionList>` / `<ScrollArea>` / `<DropdownMenu>` / `<ChromeHeader>` / `ItemInlineActionButton` + `patterns/horizontal-overflow`。
 
 **Layout Family**:**非上述 family — composite / multi-region**(Toolbar + Viewport + 可選 InfoPanel + 可選 Filmstrip)。見下「Layout Family Rationale」段。
 
@@ -140,7 +140,7 @@ FileViewer Toolbar 消費 `patterns/action-bar/action-bar.spec.md` 的**左中
 - **zoom** — 同一張檔案的微調(影響範圍:當前 renderer 的 transform state),影響最小
 - **info** — 切換附加資訊面板(影響範圍:layout,不破壞現有內容)
 - **download** — 把內容搬出 viewer(影響範圍:外部檔案系統,不可逆副作用)
-- **close** — 結束整個 viewing session(影響範圍:最大,unmount 所有 state)
+- **close** — 結束整個 viewing session(影響範圍:最大)。註:close = `setOpen(false)`,**僅卸載 `DialogContent` 子樹**;外層 FileViewer 元件恆掛載,shell state(zoom / infoOpen / index 等 `useState`)**保留** —— 重開同一檔沿用上次 zoom / infoOpen,非 fresh state
 
 ### Dismiss canonical(Close X)
 
@@ -199,20 +199,38 @@ Shell 看到 `pageNumber` capability 時自動在 toolbar 顯示 page navigator(
 
 - 消費 `react-zoom-pan-pinch`(zoom + pan 行為 primitive,無 UI);世界級產品 Figma / Miro / PhotoSwipe 同流派 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 - **圖 render 走 natural size**(不 object-contain):transform scale 管實際顯示大小;避免 CSS pre-scale 跟 transform scale 雙重縮放導致 fit-to-* 算法混淆
-- **onLoad 自動 fit-to-page**(世界級 canonical:Figma / Preview.app / Acrobat 開圖預設 fit-page,非 100%)——renderer 計算 `min(cw/iw, ch/ih)` 對應的 zoom %(`image-renderer.tsx` computeFitScale),透過 `onZoomChange` 回報 shell 更新 UI 顯示真實倍率(例:40%) <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- **onLoad 自動 fit-to-page**(世界級 canonical:Figma / Preview.app / Acrobat 開圖預設 fit-page,非 100%)——renderer 計算 `min(cw/iw, ch/ih)` 對應的 zoom %(`image-renderer.tsx` computeFitScale),透過 `onZoomChange` 回報 shell 更新 UI 顯示真實倍率(例:40%)。**邊界**:fit scale 受 `MIN_SCALE = 10%` 下限與 `Math.floor` 夾制 —— 所需倍率 < 10% 的超大圖仍溢出(clamp 到 10%),floor 亦刻意留 ~1% under-fill 保對稱置中,故「完整可見」在極端尺寸為近似而非絕對 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 - **zoom = 100% 語義 = natural pixel size**(跟 Figma / Preview 一致),不是 CSS-contained 的 fit scale
 - Scroll wheel 縮放;`zoom > 100%` 時可拖曳 pan
-- **Wheel step canonical 為 `0.03`(每 tick ~3% scale delta)**——對齊 Figma / Preview.app / Photoshop 細緻度。原 0.1(10%)太粗,接近 Google Slides 離散慣例非世界級連續 zoom。library 內部 multiplicative 乘算 → log 視覺等距(符合「等距」需求)。註:原想加 `smoothStep: 0.005` 作 trackpad 細緻度,但當前 react-zoom-pan-pinch 版本型別不含該 key,**未啟用**;若需要升級到有此 prop 的版本或切 `smoothScroll` API <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- **Wheel step canonical 為 `0.03`(每 tick ~3% scale delta)**——對齊 Figma / Preview.app / Photoshop 細緻度。原 0.1(10%)太粗,接近 Google Slides 離散慣例非世界級連續 zoom。**react-zoom-pan-pinch@4 的 wheel zoom = `scale + delta × step` 加法線性**(`handleCalculateWheelZoom`,`dist/index.esm.js:1265`;**非** multiplicative/log —— 乘算 `scale × exp(delta×step)` 只用於 setup `smooth` 開啟時的按鈕 zoom path)。註:lib 型別**無** `smoothStep` / `smoothScroll` key(僅 setup-level `smooth?: boolean` 走按鈕 exp path、不影響 wheel);trackpad 平滑度目前無對應 wheel prop 可調 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 - **Zoom anchor(中心點)canonical**:
   - **Wheel zoom** — anchor 固定在 **cursor pointer 位置**(react-zoom-pan-pinch default,對齊 Figma / Photoshop / 瀏覽器 cmd-scroll canonical)。user 滑鼠指哪,zoom 就以那點為中心,內容不會「跑掉」 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
   - **± button zoom / preset / fit / input 打字**(沒 cursor 位置時)— 走 library canonical `api.centerView(targetScale, 200)`,自動處理 scale + 置中 + animation + bounds。**不自算 `setTransform`**(動畫期間讀 stale positionX 會漂)
   - **Fit to width / page** — 算 scale emit 回 shell,經由 `centerView` 重新置中
   - **100% 重設**(user 按 `0` 鍵;雙擊是 fit↔100% 條件式 toggle,見下「雙擊」bullet)— `centerZoomedOut: true` 讓 ≤100% 時自動 center,避免內容停在容器角落
-  - 結果:user 看哪,zoom 完 **看哪**,視覺焦點不漂移 — 世界級 media viewer 共識
+  - 結果:**wheel / pinch** 以指標為 anchor,zoom 完視覺焦點不漂移(世界級 media viewer 共識);**按鈕 / preset / fit / 輸入打字**走 `centerView`,焦點**重置為內容幾何中心**(非保持指標焦點)—— 兩條 zoom 路徑 anchor 行為不同
 - Min scale 10%,max scale 400%
 - **雙擊 = toggle fit-page ↔ 100%**(對齊 Apple Photos / Preview.app / Imgur / PhotoSwipe canonical):當前 zoom 在 fit-page ±5pt 內 → 跳 100% natural;否則 → 回 fit-page。`0` 鍵才是固定重設 100%(`file-viewer.tsx:863`),兩者不同(`image-renderer.tsx:144`)
 - 切換檔案時 shell **不重設 zoom**——把「下一張該怎麼初始化 zoom」的決定權交給 renderer:image-renderer 自己 watch `file.url` 變化 → reset loaded → onLoad → 重 fit-page(含 cache 命中時 `<img complete>` 主動觸發,避免 onLoad 不 fire 卡在上一張的 zoom)。原本 shell `setZoom(100)` 在 cache 命中時會卡 100% 不 fit,已移除
 
+### 畫布自適應(container resize reflow,2026-07-08 codify — 原只活在 code 註解)
+
+**單一咽喉點 invariant**:自適應監聽對象 = **畫布容器自身的 `ResizeObserver`**(`image-renderer.tsx`),**禁**改聽 `window resize` — 容器級觀察讓所有尺寸變化來源走同一條路,天然涵蓋、免逐源接線:
+
+| 尺寸變化來源 | 涵蓋方式 |
+|---|---|
+| 視窗 resize / RWD breakpoint | 容器跟著變 → observer fire |
+| InfoPanel 開合(`I` 鍵 / close X,右側 320px)| 同上 |
+| Filmstrip 顯示/隱藏(底部高度)| 同上 |
+| 裝置旋轉 / 瀏覽器縮放 | 同上 |
+| 檔案切換(prev/next)| 不走 observer — `file.url` watch → 重 fit-page(上一 bullet)|
+
+**Resize 時的行為分流**(rAF debounce 合併連續 fire):
+- **fit mode(fit-page / fit-width)** → 重算 fit scale 並套用(對齊 Apple Photos / Google Drive:留在 fit 意圖就跟著容器重排)
+- **manual zoom** → **scale 不變 + 視覺中心點保持**(對齊 Figma / Photoshop):以「舊容器中心對到的內容點」反推新 position(`setTransform` 同步無動畫),內容不因 InfoPanel 開合而偏移;禁 early-return 什麼都不做(2026-07-08 前的 gap:transform 座標是絕對值,容器變窄內容偏左)
+
+**Mode 追蹤**:`lastFitModeRef`(fit-page / fit-width / manual)— fit 請求與雙擊設定之,user wheel/pinch 打破為 manual;programmatic `centerView`/`setTransform` 期間以 flag 防誤標。
+
 ---
 
 ## ZoomInput 規則
@@ -257,11 +275,11 @@ Shell 看到 `pageNumber` capability 時自動在 toolbar 顯示 page navigator(
 - **寬度固定 w-80(320px)**——對齊 Figma right panel(320)的業界慣例;Google Photos 用 360 偏寬,FileViewer 走 Figma 偏窄以讓 viewport 多一些空間 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 - **Header 高度 = `--chrome-header-height`**(隨 page density:48 md / 56 lg)——與 Toolbar 等高,視覺對齊;消費 `<ChromeHeader>`(繼承 page,2026-06-15 移除 lockDensity)
 - **內容分兩區**:
-  - 「說明」Textarea(可編輯 / readOnly 依 `readOnly` prop)
+  - 「說明」Textarea:edit mode = 可編輯 native textarea;**readOnly mode 依 DS Textarea canonical 分兩態** —— **有值** → native `<textarea readOnly>`(仍可聚焦 / 選取 / 複製),**空值** → display `<div>` 顯 emptyDisplay(`-`;field-controls readonly canonical,非 placeholder)
   - 「檔案資訊」`<dl>`:檔名 / 類型 / 大小 / 自訂 metadata 條目
 - **預設關閉**,user 主動 toggle(I 鍵 or Info 按鈕);切檔案時 InfoPanel 保持同步顯示下一個 file 的資訊
 - **Description 變化持久化**:onBlur 時若 draft 與原值不同,呼叫 `onDescriptionChange(fileId, description)`;consumer 負責寫後端
-- **Readonly 時不觸發 onDescriptionChange**;placeholder 改為「尚無說明」
+- **Readonly 時不觸發 onDescriptionChange**;readonly 空值走 display `<div>` 顯 `-`(emptyDisplay),**placeholder(含 `descriptionPlaceholderReadOnly`「尚無說明」)在 readonly 不會顯示** —— placeholder 僅 edit mode 空值時出現(`descriptionPlaceholderEdit`)
 
 ---
 
@@ -291,7 +309,7 @@ Shell 看到 `pageNumber` capability 時自動在 toolbar 顯示 page navigator(
 | `F` | Fit to page | `capabilities.zoom === true` |
 | `I` | 切換 InfoPanel | 永遠 |
 
-**焦點在 input / textarea / contentEditable 時不觸發**——避免 user 打字時被快捷鍵劫持(寫入 description 打到 `-` 不應 zoom out)。
+**焦點在 input / textarea / contentEditable 時不觸發**——避免 user 打字時被快捷鍵劫持(寫入 description 打到 `-` 不應 zoom out)。此排除**僅適用 FileViewer 自管的快捷鍵**(← → / +・−・0 / F / I)。**例外 `Esc`**:由 Radix DismissableLayer 以 document capture-phase 監聽,不受此排除影響 —— 在 InfoPanel description textarea 內按 Esc 仍會關閉整個 viewer(未 blur 的 draft 不觸發持久化)。
 
 ---
 
@@ -342,17 +360,17 @@ Shell 看到 `pageNumber` capability 時自動在 toolbar 顯示 page navigator(
 ## A11y 預設
 
 Radix DialogPrimitive 自動處理:
-- `role="dialog"` + `aria-modal="true"`
+- `role="dialog"`(**不輸出 `aria-modal`**;`react-dialog@1.1.x` 只設 role / `aria-labelledby` / `aria-describedby`,modal 隔離改由下方 focus trap + `hideOthers` 的 `aria-hidden` 達成)
 - `<DialogPrimitive.Title>`(sr-only)自動成 `aria-labelledby` 目標——screen reader 開啟時讀「檔案檢視器:{file.name}」
-- Focus trap:焦點鎖在 viewer 內
-- Esc 關閉(Radix DismissableLayer 預設)
+- Focus trap:焦點**進入 Content 後**鎖在 viewer 內(FocusScope)
+- Esc 關閉(Radix DismissableLayer,document capture-phase 監聽)
 - Backdrop click 關閉**非** Radix outside-click:Content 為 `fixed inset-0` 全螢幕覆蓋整個 viewport、Overlay 是其後層 sibling,Radix outside-click 不會 fire。實際靠自寫 geometric onClick handler(判斷 click 座標是否落在 `<img>` rect 外 → 才關)
 
 自加的 a11y:
 - 所有 iconOnly button 皆有 `aria-label`(中文,跟 DS 其他元件風格一致)
 - Filmstrip `role="group"` + `aria-label` + thumb `<button>` + `aria-current`(非 tablist;見「Filmstrip 規則」段理由)
 - InfoPanel 用 `<aside aria-label="檔案詳細資訊">` 語意標記
-- `onOpenAutoFocus={e => e.preventDefault()}` 避免焦點自動跑進第一個 tabbable(讓鍵盤從 viewport 開始)
+- `onOpenAutoFocus={e => e.preventDefault()}` **僅取消** Radix 開啟時的自動聚焦(避免焦點跑進第一個 tabbable 觸發 tooltip);此 handler **不主動把焦點移入 viewport** —— 焦點停在觸發按鈕,直到 user 操作使焦點進入 Content,FocusScope 才啟動 trap。(known a11y gap:若要開啟即把焦點移入 viewer 需補 `tabIndex` + `ref.focus()`,屬 SSOT-affecting 待拍板)
 
 ---
 

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

@@ -374,8 +374,7 @@ export const FallbackUnknownType: Story = {
           開啟無 renderer 支援的檔案
         </Button>
         <p className="text-footnote text-fg-muted text-center max-w-[520px] leading-relaxed">
-          情境:專案備份 zip 檔案無對應 renderer,FallbackRenderer 兜底顯示檔名 +
-          「請下載檢視」訊息。Toolbar 隱藏 zoom controls(capabilities.zoom = false)。
+          情境:zip 等無法預覽的檔案,改顯示檔名和「請下載檢視」提示,工具列會自動隱藏縮放按鈕。
         </p>
         <FileViewer files={unknownFile} open={open} onOpenChange={setOpen} />
       </div>

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

@@ -48,6 +48,7 @@ import type {
   FileRendererCapabilities,
   FileRendererProps,
 } from './file-viewer-types'
+import { surfaceMotion } from "@/design-system/tokens/motion/overlay-motion"
 
 /**
  * FileViewer — 可延伸的網頁檔案 preview shell(modal fullscreen)
@@ -59,8 +60,8 @@ import type {
  *
  * ── 實作基礎 ──
  * 自建 composite,消費 DS primitives:
- *   - Radix DialogPrimitive(焦點 trap / Esc / aria-modal,保有 shadcn 結構優勢)
- *   - `<Empty>` / `<Button>` / `<Input variant="bare">` / `<AspectRatio>` / `<Textarea>` / `<DropdownMenu>`
+ *   - Radix DialogPrimitive(焦點 trap / Esc / modal 隔離靠 hideOthers aria-hidden — react-dialog@1.1.x 不輸出 aria-modal,保有 shadcn 結構優勢)
+ *   - `<Empty>` / `<Button>` / `<Input size="sm" autoWidth>`(ZoomInput,default variant)/ `<AspectRatio>` / `<Textarea>` / `<DropdownMenu>`
  *   - `patterns/horizontal-overflow`(filmstrip 溢出捲動)
  * 不用 DS 的 `<Dialog>` wrapper:因為 FileViewer 需要 edge-to-edge fullscreen
  * (無 viewport inset / 無 rounded-lg / 無 maxWidth),Dialog 的這些預設都要覆寫。
@@ -179,7 +180,7 @@ interface ZoomInputProps {
 }
 
 /**
- * ZoomInput — [−] [% input(bare)with ⌄ menu trigger] [+]
+ * ZoomInput — [−] [% input(default variant + autoWidth)with ⌄ menu trigger] [+]
  *
  * 世界級對照:Figma zoom control / Adobe Acrobat / Google Slides zoom。
  *
@@ -233,9 +234,13 @@ const ZoomInput: React.FC<ZoomInputProps> = ({ value, onChange, onFit, labels })
           — 靠 Radix asChild + ItemInlineActionButton:視覺是 Input + endAction,行為是 chevron-as-trigger
           — 完全對齊 user AR:「只有 inline action 能觸發選單,menu 對齊 inline action」 */}
       <DropdownMenu open={menuOpen} onOpenChange={setMenuOpen}>
+        {/* maxLength 限縮(2026-07-09 user 要求「找合理最大值避免無限輸入」):autoWidth 下輸入框寬度隨字數長,
+            無上限則可無限打字撐爆 toolbar。max 合法值「400%」= 4 字(對齊 ZOOM_PRESETS / ImageRenderer MAX_SCALE 400;
+            commitDraft 另 clamp 10–400),留 1 字編輯緩衝 → maxLength={5}。 */}
         <Input
           size="sm"
           autoWidth
+          maxLength={5}
           aria-label={labels.zoomInput}
           value={draft}
           onChange={(e) => setDraft(e.target.value)}
@@ -533,7 +538,7 @@ const InfoPanel = React.memo(function InfoPanel({
           <span className="text-body font-normal text-foreground">{labels.fileInfoHeading}</span>
           <DescriptionList direction="horizontal" divided>
             <DescriptionItem label="檔名">{file.name}</DescriptionItem>
-            <DescriptionItem label="類型">{file.mimeType || '—'}</DescriptionItem>
+            <DescriptionItem label="類型">{file.mimeType || '-'}</DescriptionItem>
             {sizeText && (
               <DescriptionItem label="大小">
                 <span className="tabular-nums">{sizeText}</span>
@@ -937,6 +942,7 @@ const FileViewer = React.forwardRef<HTMLDivElement, FileViewerProps>(function Fi
           data-theme="dark"
           className={cn(
             'fixed inset-0 z-50 bg-overlay',
+            surfaceMotion,
             'data-[state=open]:animate-in data-[state=closed]:animate-out',
             'data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
           )}
@@ -946,8 +952,10 @@ const FileViewer = React.forwardRef<HTMLDivElement, FileViewerProps>(function Fi
           className={cn(
             // Edge-to-edge fullscreen,無 inset / 無 radius(與一般 Dialog 差別的所在)
             'fixed inset-0 z-50 outline-none',
+            surfaceMotion,
             'data-[state=open]:animate-in data-[state=closed]:animate-out',
             '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()}