@qijenchen/design-system 0.1.0-beta.61 → 0.1.0-beta.63

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

@@ -8,6 +8,7 @@ import { Select } from '@/design-system/components/Select/select'
 import { Input } from '@/design-system/components/Input/input'
 import { NumberInput } from '@/design-system/components/NumberInput/number-input'
 import { Button } from '@/design-system/components/Button/button'
+import { OPERATOR_REGISTRY } from '@/design-system/components/DataTable/filter-operators'
 
 const meta: Meta<typeof FieldControlGroup> = {
   title: 'Design System/Components/FieldControlGroup/展示',
@@ -42,7 +43,7 @@ const CURRENCIES = [
 ]
 
 /* ── 電話輸入(國碼 + 號碼)── */
-export const Phone_NumberInput: Story = {
+export const PhoneNumber: Story = {
   name: '電話',
   render: () => {
     const [code, setCode] = React.useState('+886')
@@ -75,7 +76,7 @@ export const Phone_NumberInput: Story = {
 }
 
 /* ── 金額輸入(幣別 + 數字)── */
-export const Currency_Amount: Story = {
+export const CurrencyAmount: Story = {
   name: '金額',
   render: () => {
     const [currency, setCurrency] = React.useState('TWD')
@@ -105,7 +106,7 @@ export const Currency_Amount: Story = {
 }
 
 /* ── 搜尋 + 提交按鈕 ── */
-export const Search_Submit: Story = {
+export const SearchSubmit: Story = {
   name: '搜尋與提交',
   render: () => {
     const [q, setQ] = React.useState('')
@@ -133,13 +134,12 @@ const FILTER_FIELDS = [
   { value: 'category', label: '類別' },
   { value: 'stock', label: '庫存' },
 ]
-const STRING_OPS = [
-  { value: 'contains', label: '包含' },
-  { value: 'is', label: '等於' },
-  { value: 'starts_with', label: '開頭為' },
-]
+// op 選項消費 OPERATOR_REGISTRY SSOT(DataTable/filter-operators.ts;audit dim 32 — 禁 hardcode op 字串)
+const STRING_OPS = OPERATOR_REGISTRY.string
+  .filter((o) => o.valueShape === 'text')
+  .map((o) => ({ value: o.op, label: o.label }))
 
-export const FilterRow_RealUsage: Story = {
+export const FilterRow: Story = {
   name: '篩選列（資料表進階篩選實例）',
   render: () => {
     const [field, setField] = React.useState('name')

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

@@ -116,13 +116,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 is cascade-only(passes through to children Field controls,
-// not own visual variants),so sizes:{} matches spec frontmatter (no sizes declared)。
+// **No own sizes** — size prop 目前為 no-op(不傳遞給 children,無 Context Provider /
+// 無 cloneElement;children 尺寸自管,見上方 docblock「Size」段 + spec「FCG `size` prop 目前為 no-op」),
+// so sizes:{} matches spec frontmatter (no sizes declared)。
 export const fieldControlGroupMeta = {
   component: 'FieldControlGroup',
   family: 'self-contained',
   variants: {},
-  sizes: {},  // self-contained wrapper, sizes cascade to children only
+  sizes: {},  // self-contained wrapper;size prop no-op(children 尺寸自管)
   states: ['default', 'children-hover', 'children-focus', 'children-disabled'],
   tokens: {
     bg: [],  // structural wrapper has no own bg

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

@@ -47,7 +47,7 @@ export const Overview: Story = {
                 ['name', 'string', '必填', '檔名'],
                 ['mode', "'compact' | 'rich'", "'compact'", 'compact=Paperclip 16px icon / rich=Avatar 48px 縮圖'],
                 ['status', "'uploading' | 'completed' | 'error'", '—', '上傳狀態(不傳=已上傳靜態)'],
-                ['progress', 'number', '—', '上傳進度 0-100(uploading 時顯示 bar)'],
+                ['progress', 'number', '—', '上傳進度 0-100(有 status 時顯示 bar;completed 強制 100%)'],
                 ['description', 'ReactNode', '—', 'rich 任意場景 / compact 只有 error 才顯示。ReactNode — 可含 inline clickable link(如「View log」)'],
                 ['thumbnailSrc', 'string', '—', 'rich mode 的縮圖 URL(圖片類檔案)'],
                 ['actions', 'ReactNode', '—', 'suffix actions(例:delete / cancel button)'],
@@ -127,7 +127,7 @@ export const ColorMatrix: Story = {
                 <Td mono>uploading</Td>
                 <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--foreground" size="sm" /><span className="font-mono">--foreground</span></span></Td>
                 <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--fg-secondary" size="sm" /><span className="font-mono">--fg-secondary</span></span></Td>
-                <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--primary" size="sm" /><span className="font-mono">--primary(inProgress)</span></span></Td>
+                <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--info" size="sm" /><span className="font-mono">--info(inProgress)</span></span></Td>
                 <Td>—(只顯示 bar)</Td>
               </tr>
               <tr>
@@ -149,16 +149,6 @@ export const ColorMatrix: Story = {
         </div>
       </div>
 
-      <div>
-        <H3>視覺對照(rich mode)</H3>
-        <div className="flex flex-col gap-2 max-w-lg">
-          <FileItem name="Q1-marketing-report.pdf" description="2.4 MB · 已上傳" mode="rich" />
-          <FileItem name="brand-guidelines.pdf" description="1.2 MB · 上傳中 45%" status="uploading" progress={45} mode="rich" />
-          <FileItem name="Q2-forecast.xlsx" description="上傳成功 · 3.8 MB" status="completed" progress={100} mode="rich" />
-          <FileItem name="legacy-data.csv" description="上傳失敗 · 網路中斷" status="error" mode="rich" />
-        </div>
-      </div>
-
       <div>
         <H3>Container background(per mode,**無 hover-bg**)</H3>
         <Desc>
@@ -199,7 +189,7 @@ export const ModeMatrix: Story = {
 
       <div>
         <H3>compact（預設）— Paperclip 16px icon 在左</H3>
-        <Desc>掃描模式(text-caption),資訊密度高。適合批次上傳的 logs / CSV / JSON。Description 只在 error 才顯示。</Desc>
+        <Desc>掃描模式(text-body + leading-compact;desc 為 text-caption,兩 mode 統一),資訊密度高。適合批次上傳的 logs / CSV / JSON。Description 只在 error 才顯示。</Desc>
         <div className="flex flex-col gap-1 max-w-lg">
           <FileItem name="users.csv" mode="compact" status="completed" progress={100} />
           <FileItem name="orders.json" mode="compact" status="uploading" progress={42} />
@@ -214,7 +204,7 @@ export const ModeMatrix: Story = {
           <table className="text-caption border-collapse">
             <thead><tr><Th>Mode</Th><Th>Prefix</Th><Th>Typography</Th><Th>Description</Th><Th>使用場景</Th></tr></thead>
             <tbody>
-              <tr><Td mono>compact（預設）</Td><Td>Paperclip 16px</Td><Td>掃描模式(text-caption)</Td><Td>只有 error 才顯示</Td><Td>批次上傳、一般檔案</Td></tr>
+              <tr><Td mono>compact（預設）</Td><Td>Paperclip 16px</Td><Td>掃描模式(text-body;兩 mode 統一 scanning)</Td><Td>只有 error 才顯示</Td><Td>批次上傳、一般檔案</Td></tr>
               <tr><Td mono>rich</Td><Td>Avatar 48px square</Td><Td>掃描模式(text-body;兩 mode 統一 scanning)</Td><Td>任何場景</Td><Td>圖片、文件、需要預覽</Td></tr>
             </tbody>
           </table>
@@ -245,7 +235,7 @@ export const SizeMatrix: Story = {
               </tr>
             </thead>
             <tbody>
-              <tr><Td>Prefix</Td><Td mono>Paperclip 16px(foreground)</Td><Td mono>Avatar 48px square(縮圖或 fallback)</Td></tr>
+              <tr><Td>Prefix</Td><Td mono>Paperclip 16px(fg-muted)</Td><Td mono>Avatar 48px square(縮圖或 fallback)</Td></tr>
               <tr><Td>Row 高度(無 bar)</Td><Td mono>px-3 py-2(content 1lh)</Td><Td mono>content col minHeight 48(avatar)+ py-3</Td></tr>
               <tr><Td>Typography</Td><Td mono>text-body leading-compact(掃描模式)</Td><Td mono>text-body leading-compact(掃描模式;兩 mode 統一 scanning)</Td></tr>
               <tr><Td>Description</Td><Td>僅 error 才顯示</Td><Td>任何場景都可顯示</Td></tr>
@@ -263,7 +253,7 @@ export const SizeMatrix: Story = {
         <div className="grid grid-cols-2 gap-6">
           <div>
             <div className="text-caption text-fg-muted mb-2 font-mono">mode="compact"</div>
-            <div className="flex flex-col gap-0 max-w-sm border border-border rounded-md">
+            <div className="flex flex-col gap-1 max-w-sm">
               <FileItem name="Q1-report.pdf" mode="compact" status="completed" progress={100} />
               <FileItem name="users.csv" mode="compact" status="completed" progress={100} />
               <FileItem name="products.xlsx" mode="compact" status="uploading" progress={62} />
@@ -310,7 +300,7 @@ export const StateBehavior: Story = {
           <table className="text-caption border-collapse">
             <thead><tr><Th>Status</Th><Th>Progress bar 色</Th><Th>Status icon</Th></tr></thead>
             <tbody>
-              <tr><Td mono>uploading</Td><Td mono>bg-primary</Td><Td>—</Td></tr>
+              <tr><Td mono>uploading</Td><Td mono>bg-info</Td><Td>—</Td></tr>
               <tr><Td mono>completed</Td><Td mono>bg-success(100%)</Td><Td>CircleCheck(text-success)</Td></tr>
               <tr><Td mono>error</Td><Td mono>bg-error(寬度 = consumer 傳入 progress)</Td><Td>XCircle(text-error)</Td></tr>
               <tr><Td>(無 status)</Td><Td>無 bar</Td><Td>—</Td></tr>

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

@@ -43,19 +43,19 @@ export const UsageGuidance: Story = {
       <p>適合 FileItem 的真實業務場景(點擊跳轉「展示」頁範例):</p>
       <ul className="space-y-1">
         <li>
-          <LinkTo kind="Design System/Components/FileItem/展示" name="Rich"><span className="text-primary hover:underline font-medium cursor-pointer">Rich</span></LinkTo>
+          <LinkTo kind="Design System/Components/FileItem/展示" name="豐富樣式"><span className="text-primary hover:underline font-medium cursor-pointer">圖片 / 設計稿上傳 — 需要縮圖預覽(豐富樣式)</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/FileItem/展示" name="Compact"><span className="text-primary hover:underline font-medium cursor-pointer">Compact</span></LinkTo>
+          <LinkTo kind="Design System/Components/FileItem/展示" name="緊湊樣式"><span className="text-primary hover:underline font-medium cursor-pointer">CSV / JSON 批次匯入的密集清單(緊湊樣式)</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/FileItem/展示" name="懸停替換"><span className="text-primary hover:underline font-medium cursor-pointer">Hover 替換</span></LinkTo>
+          <LinkTo kind="Design System/Components/FileItem/展示" name="懸停替換"><span className="text-primary hover:underline font-medium cursor-pointer">上傳完成後滑入整列、狀態 icon 換成下載鈕(懸停替換)</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/FileItem/展示" name="已上傳"><span className="text-primary hover:underline font-medium cursor-pointer">已上傳</span></LinkTo>
+          <LinkTo kind="Design System/Components/FileItem/展示" name="已上傳"><span className="text-primary hover:underline font-medium cursor-pointer">工單 / 訊息附件的已上傳靜態檔案</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/FileItem/展示" name="緊湊 混合"><span className="text-primary hover:underline font-medium cursor-pointer">Compact 混合</span></LinkTo>
+          <LinkTo kind="Design System/Components/FileItem/展示" name="緊湊 混合"><span className="text-primary hover:underline font-medium cursor-pointer">同一批次混合上傳中 / 完成 / 失敗狀態的清單</span></LinkTo>
         </li>
       </ul>
       <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見 <code>Vs*Rule</code> stories)。</p>
@@ -121,7 +121,7 @@ export const ModeRule: Story = {
 
       <Rule
         title="compact — 批次上傳的一般檔案（CSV / JSON）"
-        note="左側 Paperclip 16px icon,掃描模式(text-caption),資訊密度高。適合一次顯示 10+ 檔案的 batch upload 清單"
+        note="左側 Paperclip 16px icon,掃描模式(text-body + leading-compact,desc 為 text-caption;兩 mode 統一),資訊密度高。適合一次顯示 10+ 檔案的 batch upload 清單"
       >
         <div className="flex flex-col gap-1">
           <FileItem
@@ -161,7 +161,7 @@ export const StatusProgressRule: Story = {
   render: () => (
     <div>
       <Rule
-        title="uploading — progress bar primary 色 + 百分比 description"
+        title="uploading — progress bar info 色 + 百分比 description"
         note="上傳中清楚展示進度,讓使用者知道「多久能好」而不是只看到一個等待狀態"
       >
         <FileItem

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

@@ -319,19 +319,9 @@ upload-manager 的 completed(100% bar + ✓)屬「剛完成的 upload session」
   {files.map(f => <FileItem key={f.id} mode="rich" {...f} />)}
 </div>
 
-// ✅ Compact 無 status(form attachment,靜態灰底)
+// ✅ Compact 一律 gap-1(無 status / 有 status / mixed 上傳中+已存附件 都同此 wrapper,見上表)
 <div className="flex flex-col gap-1">
-  {files.map(f => <FileItem key={f.id} mode="compact" {...f} />)}
-</div>
-
-// ✅ Compact 有 status only(全有 status,uploading/error/completed)
-<div className="flex flex-col gap-1">
-  {files.map(f => <FileItem key={f.id} mode="compact" status={f.status} progress={f.progress} {...f} />)}
-</div>
-
-// ✅ Compact mixed 上傳中 + 已存附件(email 草稿、舊附件 + 新上傳)
-<div className="flex flex-col gap-1">
-  {allFiles.map(f => <FileItem key={f.id} mode="compact" status={f.isUploading ? 'uploading' : undefined} {...f} />)}
+  {files.map(f => <FileItem key={f.id} mode="compact" status={f.isUploading ? 'uploading' : undefined} {...f} />)}
 </div>
 
 // ❌ 反例:list 加外框 + overflow-hidden(雙重 card / 強制邊框相黏)
@@ -341,7 +331,7 @@ upload-manager 的 completed(100% bar + ✓)屬「剛完成的 upload session」
 ```
 
 **Clickable → 下載 / 預覽 canonical**(AR15):
-- FileItem 提供 `onClick` prop,consumer 傳入即進 clickable 模式(hover + cursor + keyboard)
+- FileItem 提供 `onClick` prop,consumer 傳入即進 clickable 模式(僅滑鼠可點 + `cursor-pointer`;刻意不加整列 keyboard 焦點 / hover-bg — 見「A11y 預設」nested-interactive rationale 與「Hover 行為 canonical」)
 - 兩種 surface 都可以用 `onClick`(upload-manager 可跟 `onDownload` hover-swap 並存)
 - consumer 決定具體行為(download / FileViewer),元件只提供 row 可點擊能力
 
@@ -396,7 +386,7 @@ Consumer 自行組合。按 `patterns/element-anatomy/item-anatomy.spec.md`「Pr
 - `mode="rich"` → `var(--field-height-xs)`(24 固定,與 Button xs iconOnly 同)
 - `mode="compact"` → `var(--field-height-xs)`(24,同 rich;compact 靠 status slot wrapper 的 `[&>[data-unbounded]]:my-[calc((1lh-var(--field-height-xs))/2)]` 把 24 footprint 收斂到 1lh,不撐高 row,視覺 / touch target 仍 24)
 
-Passive status icon 置中於 action-sized 容器,hover 時 active action 填滿同一容器。這讓 flex gap token 測量的是**兩個同尺寸 action slot 之間的真實 gap**,不被 hover bg overflow 吃掉——status slot 尺寸 = 同 size delete slot,gap token 才能如實呈現;歷史 bug 細節見 CLAUDE.md `# 失敗記憶索引`。
+Passive status icon 置中於 action-sized 容器,hover 時 active action 填滿同一容器。這讓 flex gap token 測量的是**兩個同尺寸 action slot 之間的真實 gap**,不被 hover bg overflow 吃掉——status slot 尺寸 = 同 size delete slot,gap token 才能如實呈現;歷史 bug 細節見 `.claude/skills/design-system-audit/references/historical-bugs.md`。
 
 世界級 DS 的幾何鐵律:**同一 flex 列的互動元素必須有統一 box 尺寸**,gap token 才能如實呈現。
 
@@ -412,16 +402,7 @@ Passive status icon 置中於 action-sized 容器,hover 時 active action 填滿
   mode="rich"
   name="report.pdf"
   status="completed"
-  onDownload={() => downloadFile(id)}   // hover ✓ → ↓
-  actions={<Button size="xs" iconOnly variant="text" startIcon={Trash2} onClick={del} aria-label="刪除" />}
-/>
-
-<FileItem
-  mode="compact"
-  name="backup.json"
-  status="error"
-  description="There's something wrong."
-  onRetry={() => retryUpload(id)}        // hover ✗ → ⟲
+  onDownload={() => downloadFile(id)}   // hover ✓ → ↓;error 場景同理:onRetry → hover ✗ → ⟲
   actions={<Button size="xs" iconOnly variant="text" startIcon={Trash2} onClick={del} aria-label="刪除" />}
 />
 ```
@@ -451,6 +432,7 @@ Passive status icon 置中於 action-sized 容器,hover 時 active action 填滿
 |------|------|------|
 | **FileItem** | 單一檔案 row primitive — 顯示一個檔案的 name / status / progress / actions | List 內的單筆 / detail / preview / message attachment |
 | **FileUpload** | Dropzone + file list orchestrator — 拖放區 + 多 FileItem 排列 + 上傳狀態管理 | 完整上傳流程入口 |
+| **FileViewer** | 檔案內容預覽 overlay — FileItem `onClick` 的預設開啟目標 | 點 row 後的檔案全幅預覽 |
 
 **判斷**:
 
@@ -470,6 +452,18 @@ Passive status icon 置中於 action-sized 容器,hover 時 active action 填滿
 - ❌ **不混用 rich + compact 在同一 list**(詳「Invariant 1」)— 高度差破壞 row rhythm,prefix 視覺語言衝突。
 - ❌ **不用 FileItem 做下載進度**(瀏覽器原生下載 UX 已足夠)— FileItem 為 upload narrative 設計,download progress 走自訂元件。
 
+**常見誤解**:FileItem 該有 hover-bg → 永不(三型態 permanent-anchored,見「Hover 行為 canonical」);status 會染整 row 底色 → 只升階 progress bar / status icon / description(見「Inspector 與矩陣的教學分工」);`surface` 影響進度條 → 進度條只看 `status`(見「可下載狀態 canonical」)。
+
+---
+
+## 邊界案例
+
+- **超長檔名**: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 支援需另案。
+- **Dark mode**:走 semantic token 自動 adapt。無 `disabled` prop(展示型 row,非 form control)。
+
 ---
 
 ## Inspector 與矩陣的教學分工
@@ -489,3 +483,9 @@ ColorMatrix 已建:展示 status × 元素(filename / description / progress bar
 - `../TreeView/tree-view.spec.md` — 階層 file structure 場景
 - `../ProgressBar/progress-bar.spec.md` — ProgressBar SSOT(FileItem consumes ProgressBar for upload bar)
 - `../../tokens/color/color.spec.md` — Track 底色（`bg-secondary` 使用原則）
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `file-upload.spec.md`

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

@@ -86,6 +86,8 @@ export const Overview: Story = {
                 ['accept', 'string', '—', 'MIME filter,支援 .pdf / image/* / application/pdf'],
                 ['maxSize', 'number', '—', '單檔最大 bytes;超過進 onReject'],
                 ['disabled', 'boolean', 'false', '完全停用(語意 token bg-disabled + cursor-not-allowed;互動由 handler isBlocked guard 擋,非 pointer-events-none)'],
+                ['variant', "'dropzone' | 'button'", "'dropzone'", '觸發外觀:dropzone 大拖放區(drag + click)/ button 緊湊按鈕(click-only,form-friendly)'],
+                ['buttonLabel', 'string', "'Choose file'", "variant='button' 的按鈕文字"],
                 ['title', 'string', "'Click or drag file here to upload'", '預設結構(Empty)的主標題'],
                 ['description', 'string', '單/多檔字串自動切換', '預設結構(Empty)的副標題'],
                 ['children', 'ReactNode', '—', '傳入則整個覆寫預設 Empty 結構(consumer 完全客製)'],
@@ -290,8 +292,8 @@ export const SizeMatrix: Story = {
           由 Empty 元件 擁有(主檔)(`../Empty/empty.spec.md`)。
           <br />
           <strong>空間大小由 consumer 以 wrapper width / min-height 控制</strong>
-          ——如需窄版擺在表單欄位旁,改用小 Button + hidden input 模式
-          (見「設計原則 / 何時用大 Dropzone vs 小 Button」)。
+          ——如需窄版擺在表單欄位旁,改用 `variant="button"`
+          (見「設計原則」UsageGuidance「表單內 inline field」)。
         </Desc>
         <div className="overflow-x-auto">
           <table className="text-caption border-collapse">

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

@@ -2,7 +2,7 @@
 import React from 'react'
 import LinkTo from '@storybook/addon-links/react'
 import type { Meta, StoryObj } from '@storybook/react'
-import { Paperclip, X } from 'lucide-react'
+import { X } from 'lucide-react'
 import { FileUpload } from './file-upload'
 import { FileItem } from '@/design-system/components/FileItem/file-item'
 import { Button } from '@/design-system/components/Button/button'
@@ -64,16 +64,16 @@ export const UsageGuidance: Story = {
       <p>適合 FileUpload 的真實業務場景(點擊跳轉「展示」頁範例):</p>
       <ul className="space-y-1">
         <li>
-          <LinkTo kind="Design System/Components/FileUpload/展示" name="單檔上傳"><span className="text-primary hover:underline font-medium cursor-pointer">單檔上傳</span></LinkTo>
+          <LinkTo kind="Design System/Components/FileUpload/展示" name="單檔上傳"><span className="text-primary hover:underline font-medium cursor-pointer">履歷 / 大頭貼等單檔上傳</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/FileUpload/展示" name="批次上傳"><span className="text-primary hover:underline font-medium cursor-pointer">批次上傳</span></LinkTo>
+          <LinkTo kind="Design System/Components/FileUpload/展示" name="批次上傳"><span className="text-primary hover:underline font-medium cursor-pointer">相簿照片 / 多檔附件批次上傳</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/FileUpload/展示" name="內建 files 屬性"><span className="text-primary hover:underline font-medium cursor-pointer">內建 files 屬性</span></LinkTo>
+          <LinkTo kind="Design System/Components/FileUpload/展示" name="內建 files 屬性"><span className="text-primary hover:underline font-medium cursor-pointer">上傳後直接顯示進度清單(內建 files 屬性)</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/FileUpload/展示" name="自訂內容"><span className="text-primary hover:underline font-medium cursor-pointer">自訂內容</span></LinkTo>
+          <LinkTo kind="Design System/Components/FileUpload/展示" name="自訂內容"><span className="text-primary hover:underline font-medium cursor-pointer">品牌化上傳區 — 自訂 dropzone 內容</span></LinkTo>
         </li>
       </ul>
       <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見 <code>Vs*Rule</code> stories)。</p>
@@ -127,8 +127,8 @@ export const UsageGuidance: Story = {
       </Rule>
 
       <Rule
-        title="✅ 表單內 inline field — 用小 Button + hidden input"
-        note="form 裡和其他 field 並列時,大 dropzone 會破壞欄位節奏。對照:Jira issue 附件按鈕、Stripe 發票上傳欄位——小按鈕不喧賓奪主。"
+        title='✅ 表單內 inline field — 用 FileUpload variant="button"'
+        note="form 裡和其他 field 並列時,大 dropzone 會破壞欄位節奏;variant=&quot;button&quot; 與 dropzone 共用同一套上傳邏輯(hidden input / accept / maxSize / onReject)。對照:Jira issue 附件按鈕、Stripe 發票上傳欄位——小按鈕不喧賓奪主。"
       >
         <div className="flex flex-col gap-3 w-full">
           <Field>
@@ -139,20 +139,18 @@ export const UsageGuidance: Story = {
             <FieldLabel>申請人身分證</FieldLabel>
             <div className="flex items-center gap-2">
               <Input className="flex-1" placeholder="A123456789" />
-              <Button variant="tertiary" size="md" startIcon={Paperclip}>
-                附上照片
-              </Button>
+              <FileUpload variant="button" buttonLabel="附上照片" accept="image/*" onUpload={noop} />
             </div>
           </Field>
         </div>
-        <Label>↑ 「附上照片」內部是 `&lt;input type="file" hidden /&gt;` + button.onClick</Label>
+        <Label>↑ 「附上照片」= FileUpload variant="button"——與 dropzone 同上傳邏輯,只是觸發外觀緊湊化</Label>
       </Rule>
 
       <Rule
         title="❌ form 裡塞大 dropzone"
         note="上下欄位高度落差太大,使用者視覺節奏被打斷——這是 form field 不該出現的體積。"
       >
-        <Label warn>⚠️ form 內 inline 上傳欄位,不要用 FileUpload</Label>
+        <Label warn>⚠️ form 內 inline 上傳欄位,不要用大 dropzone(改 variant="button")</Label>
       </Rule>
     </div>
     </div>

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

@@ -1,7 +1,13 @@
 ---
 component: FileUpload
 family: self-contained
-variants: {}
+variants:
+  dropzone:
+    when: "預設 — 大型 dashed 拖放區;「拖放有價值」+ 主要上傳區(drag + click)"
+    world-class: ["Ant Upload.Dragger", "Polaris DropZone"]
+  button:
+    when: "form 內單欄 / 空間省 / 與其他 field 並列 — 緊湊 Button 觸發(click-only)"
+    world-class: ["Ant Upload(button list)"]
 sizes: {}
 traits:
   - hasInteractiveStates
@@ -50,12 +56,12 @@ FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點
 
 ## 四狀態視覺(world-class dropzone 慣例)
 
-| data-state | 情境 | 視覺(2026-06-03 修正)|
+| data-state | 情境 | 視覺 |
 |------------|------|------|
 | `idle`(預設) | 使用者未互動 | dashed `border-border`（**元件邊框 `--border`,非 `--divider` 分隔線**）+ surface 底 |
-| `hover` = `drag-over`（**統一,2026-06-03 Q2-A 純 border-driven,對齊 Ant Dragger `colorPrimaryHover`**)| 游標懸停 / 拖檔進入 | **`border-primary`**（只變邊框）+ 底維持 surface（不變 bg）。state 信號靠邊框,非底色;兩態同視覺 |
-| `loading`（**deferred**）| `loading` prop 為 true | **2026-06-03 deferred：其唯一用途(無清單單檔/頭像替換)場景未定義,已從 showcase 移除為 3-state(idle/drag-over/disabled);prop 在 tsx 保留供未來。** 行為:CircularProgress 取代內容;`cursor-progress`（Q4:不加 `pointer-events-none`,互動由 isBlocked guard 擋）;aria-busy=true。有清單的 flow 進度一律走 FileItem 自身的 progress bar（uploading status）—— FileUpload 內建 list 仍 `surface=form`(dropzone 非獨立浮層 upload manager,見 file-item.spec.md「upload-manager 浮層面板 composition」)|
-| `disabled` | `disabled` prop 為 true | **語意 token（Q3,非 opacity — dashed outline surface 走 DS outline-disabled 慣例,3/4 世界級 Ant/Polaris/Carbon 用 token）**:`bg-disabled` 底 + 邊框不變色 + 文字/icon → `fg-disabled`(由 `<Empty disabled>` 控,icon-circle 維持 muted)+ `cursor-not-allowed`(**Q4 移除 pointer-events-none 後生效**)|
+| `hover` = `drag-over`（**統一,純 border-driven,對齊 Ant Dragger `colorPrimaryHover`**)| 游標懸停 / 拖檔進入 | **`border-primary`**（只變邊框）+ 底維持 surface（不變 bg）。state 信號靠邊框,非底色;兩態同視覺 |
+| `loading`（**deferred**）| `loading` prop 為 true | **Deferred:其唯一用途(無清單單檔/頭像替換)場景未定義,showcase 僅呈現 3-state(idle/drag-over/disabled);prop 在 tsx 保留供未來。** 行為:CircularProgress 取代內容;`cursor-progress`(不加 `pointer-events-none`,互動由 isBlocked guard 擋);aria-busy=true。有清單的 flow 進度一律走 FileItem 自身的 progress bar（uploading status）—— FileUpload 內建 list 仍 `surface=form`(dropzone 非獨立浮層 upload manager,見 file-item.spec.md「upload-manager 浮層面板 composition」)|
+| `disabled` | `disabled` prop 為 true | **語意 token(非 opacity — dashed outline surface 走 DS outline-disabled 慣例,3/4 世界級 Ant/Polaris/Carbon 用 token)**:`bg-disabled` 底 + 邊框不變色 + 文字/icon → `fg-disabled`(由 `<Empty disabled>` 控,icon-circle 維持 muted)+ `cursor-not-allowed`(移除 `pointer-events-none` 後生效)|
 
 **State 優先序**:`disabled > loading > drag-over > idle`。disabled 最硬(完全不可用),loading 次之(處理中,user 要等),drag-over 最柔(互動中),idle 預設。
 
@@ -77,6 +83,8 @@ FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點
 
 **兩 variant 共用** `onUpload` / `onReject` / `accept` / `maxSize` / `files` 清單渲染;**都可放進 `<Field>` control slot**。對齊 Ant `Upload`(button list)vs `Upload.Dragger`(dropzone)。M21 prop-variant test 過(同上傳行為、不同觸發外觀、value 結構同 `File[]`)。
 
+**vs 直接用 `<Button>`**:Button 只有觸發外觀、無上傳邏輯(hidden input / accept / maxSize / onReject);任何檔案上傳一律 FileUpload,空間緊湊才選 `variant="button"`。
+
 > **FileUpload 常出現在 form**(`*Excel file` 欄位等)—— `variant` 只決定「觸發外觀大小」,**非「form vs 非 form」**;兩者都常在 form 裡。
 
 ## children 插槽 vs 預設結構
@@ -95,11 +103,15 @@ FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點
 ## Props 行為
 
 - `onUpload(files)`: 使用者選取或拖放檔案,**過濾後**回傳 `File[]`
-- `onReject(files, reason)`: 被 `maxSize` / `accept` 擋下的檔案(consumer 可據此顯示 Toast / Alert)
+- `onReject(files, reason)`: 被擋下的檔案;`reason` 值域 `'size'`(超過 maxSize)/ `'type'`(不符 accept)。同次選取兩類各觸發一次。rejected 檔案的 UI 展示由 consumer 決定(Toast / Alert / FileItem `status="error"`),FileUpload 本身不渲染拒絕訊息
 - `multiple`: 預設 `false`(單檔);若 `false` 且使用者拖多檔,**只取第一個**交給 `onUpload`(不拋錯,符合 Ant Design 慣例)
 - `accept`: MIME filter,同時支援副檔名(`.pdf`)、通配(`image/*`)、完整 MIME(`application/pdf`)
 - `maxSize`: 單檔最大 bytes;超過靜默忽略(consumer 若要錯誤訊息,監聽 `onReject`)
-- `disabled`: 完全停用(互動由 `isBlocked` guard 擋 + `cursor-not-allowed`;Q4 移除 `pointer-events-none` 後不再靠它擋)
+- `disabled`: 完全停用(互動由 `isBlocked` guard 擋 + `cursor-not-allowed`;已移除 `pointer-events-none`,不再靠它擋)
+- `files`: uploaded / uploading 檔案清單(`FileUploadStatus[]`:id / name / size? / progress? / status? / description? / thumbnailSrc?)。傳入 → drop zone 下方渲染列表,每項經 `FileItem`(status 對應:uploading = progress bar / completed = ✓ / error = ✗);不傳 → 不顯示。consumer 持 state(progress / status),FileUpload 只負責渲染
+- `fileListMode`: 清單每項顯示模式;預設 `'compact'`(單行),`'rich'` 含 thumbnail / size / progress bar
+- `onRemove(id)`: 清單移除 callback;有值 → 每項右側顯示 X 移除鈕(ARIA label 由 `removeAriaLabel` 模板客製,預設「移除 {name}」),無 → view-only
+- `variant` / `buttonLabel`: 見「兩種觸發外觀」段
 
 ---
 
@@ -116,6 +128,16 @@ FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點
 
 ---
 
+## 邊界案例
+
+- **超長檔名**:`files` 清單經 FileItem 渲染,label 單行 truncate(ellipsis)— 詳 `file-item.spec.md`「邊界案例」
+- **多檔拖放 + `multiple=false`**:只取過濾後第一個檔交給 `onUpload`,不拋錯(見「Props 行為」)
+- **空選取(0 檔)**:不觸發任何 callback;`files={[]}` 不渲染清單(等同不傳)
+- **maxSize / accept 全擋下**:`onUpload` 不觸發,只觸發 `onReject`
+- Disabled / loading 見「四狀態視覺」;dark mode / density 由 semantic token 自動處理
+
+---
+
 ## A11y 預設
 
 - `role="button"` + `tabIndex=0`(disabled 時 `-1`)
@@ -129,6 +151,13 @@ FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點
 
 - `../FileItem/file-item.spec.md` — 已上傳檔案的 list row 渲染(配對元件)
 - `../Empty/empty.spec.md` — 本元件預設 children 消費,「icon + title + description」SSOT
-- `../Button/button.spec.md` — 小按鈕式上傳的替代方案
+- `../Button/button.spec.md` — `variant="button"` 消費的觸發元件(見「兩種觸發外觀」)
 - Ant Design `Upload.Dragger` 原始參考 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 - Polaris `DropZone` 原始參考 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `empty.spec.md`
+- `file-item.spec.md`

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

@@ -193,7 +193,7 @@ const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
                 onRemove ? (
                   // Collection remove(per-file)— 不是 dismiss surface,故不套 `dismiss` prop。
                   // 視覺與 dismiss 一致(text variant + fg-muted dim)— 對齊 inline-action.spec.md
-                  // 「Dismiss canonical — X close only」(section L204);L229 明文:onRemove callback 不觸發 dismiss prop。
+                  // 「Dismiss canonical — X close only」+「dismiss prop 觸發條件」段:onRemove callback 不觸發 dismiss prop。
                   <Button
                     iconOnly
                     variant="text"
@@ -288,7 +288,8 @@ const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
           'border-border bg-surface',
           // hover = drag-over 統一(2026-06-03 Q2-A 純 border-driven,對齊 Ant Dragger colorPrimaryHover):
           // 兩者都 → primary 邊框,底色維持 surface(不變 bg)。state 信號靠邊框,非底色。
-          'hover:border-primary data-[state=drag-over]:border-primary',
+          // 2026-06-11 R2(M5 狀態疊加):hover 變 primary 僅限 idle/error —— disabled/loading 維持原邊框(spec「disabled 邊框不變色」)
+          'data-[state=idle]:hover:border-primary data-[state=drag-over]:border-primary',
           // loading(2026-06-03 Q4:移除 pointer-events-none — 它會讓 cursor-progress 失效;
           // 互動已由 handleClick + drag/key handlers 的 isBlocked guard 擋,不需 pointer-events-none)
           'data-[state=loading]:cursor-progress',
@@ -359,7 +360,8 @@ export const fileUploadMeta = {
   component: 'FileUpload',
   family: null, // non-family composite / overlay / layout
   variants: {
-
+    dropzone: { purpose: '大型 dashed 拖放區(預設)— 拖放有價值 + 主要上傳區(drag + click)' },
+    button: { purpose: '緊湊 Button 觸發 — form 內單欄 / 空間省(click-only)' },
   },
   sizes: {
 

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

@@ -104,7 +104,7 @@ export const Overview: Story = {
               </div>
               {/* Viewport + InfoPanel */}
               <div className="flex-1 min-h-0 flex">
-                <div className="flex-1 bg-canvas flex items-center justify-center relative">
+                <div className="flex-1 bg-overlay flex items-center justify-center relative">
                   <span className="text-body-lg text-fg-secondary">② Viewport — renderer 渲染區(flex-1)</span>
                   <span className="absolute left-6 top-1/2 -translate-y-1/2 text-caption text-fg-muted">← prev</span>
                   <span className="absolute right-6 top-1/2 -translate-y-1/2 text-caption text-fg-muted">next →</span>
@@ -150,7 +150,7 @@ export const Overview: Story = {
               <tr>
                 <Td mono>Viewport</Td>
                 <Td>永遠顯示</Td>
-                <Td mono>flex-1, bg-canvas</Td>
+                <Td mono>flex-1(無自身 bg;bg-overlay 透出)</Td>
                 <Td>renderer 渲染區;prev/next arrow 絕對定位於左右</Td>
               </tr>
               <tr>
@@ -377,7 +377,7 @@ export const Inspector: Story = {
                 <tr>
                   <Td>Viewport 背景</Td>
                   <Td>
-                    <TokenCell token="--canvas" display="bg-canvas" />
+                    <TokenCell token="--overlay" display="bg-overlay 透出(自身無 bg)" />
                   </Td>
                 </tr>
                 <tr>
@@ -467,7 +467,7 @@ export const ColorMatrix: Story = {
         <H3>Chrome 鎖 dark 的理由</H3>
         <Desc>
           FileViewer 是「內容展示 chrome」,viewer 本身是獨立沉浸式 context——類比 Tooltip 永久 dark、
-          全螢幕影片播放器 UI 永遠暗色。Dark 底 + bg-canvas 讓圖片 / media 顯色最自然
+          全螢幕影片播放器 UI 永遠暗色。Dark 底 + 半透明 bg-overlay backdrop 讓圖片 / media 顯色最自然
           (亮底會跟任何含白色邊緣的圖片打架);rollback 到 light theme 會讓圖片與 chrome 產生
           色溫衝突。實作:DialogPrimitive.Content 內包 &lt;div data-theme="dark"&gt;,子元件 token
           自動解析為 dark 值,不影響背景頁面 theme。
@@ -488,9 +488,9 @@ export const ColorMatrix: Story = {
             <div className="flex">
               <div
                 className="flex-1 flex items-center justify-center"
-                style={{ height: 180, backgroundColor: 'var(--canvas)' }}
+                style={{ height: 180, backgroundColor: 'var(--overlay)' }}
               >
-                <span className="text-body text-fg-secondary">Viewport — bg-canvas</span>
+                <span className="text-body text-fg-secondary">Viewport — 無自身 bg(bg-overlay 透出)</span>
               </div>
               <aside className="w-56 bg-surface-raised border-l border-divider flex items-center justify-center">
                 <span className="text-body text-fg-secondary">InfoPanel — bg-surface-raised</span>
@@ -525,9 +525,9 @@ export const ColorMatrix: Story = {
               <tr>
                 <Td>Viewport 背景</Td>
                 <Td>
-                  <TokenCell token="--canvas" display="bg-canvas" />
+                  <TokenCell token="--overlay" display="bg-overlay 透出(自身無 bg)" />
                 </Td>
-                <Td>近黑底,讓 media 顯色</Td>
+                <Td>viewer 自身不畫 viewport bg;半透明遮罩透出,media 周圍近黑</Td>
               </tr>
               <tr>
                 <Td>Toolbar / InfoPanel / Filmstrip</Td>
@@ -813,14 +813,19 @@ export const StateBehavior: Story = {
               </tr>
               <tr>
                 <Td>Zoom in</Td>
-                <Td mono>滾輪 / + / = / ZoomInput</Td>
+                <Td mono>+ / = 鍵 / ＋ 按鈕</Td>
                 <Td>下一個 preset(10/25/50/75/100/125/150/200/400)</Td>
               </tr>
               <tr>
                 <Td>Zoom out</Td>
-                <Td mono>反向滾輪 / -</Td>
+                <Td mono>- 鍵 / − 按鈕</Td>
                 <Td>上一個 preset</Td>
               </tr>
+              <tr>
+                <Td>連續 / 任意值</Td>
+                <Td mono>滾輪(step 0.03)/ ZoomInput 打字</Td>
+                <Td>multiplicative 連續縮放,任意 %(非 preset;spec「Wheel step canonical」);ZoomInput preset menu 才跳 preset</Td>
+              </tr>
               <tr>
                 <Td>Reset 100%</Td>
                 <Td mono>0 key</Td>
@@ -1116,7 +1121,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">{"詳 `fileviewer.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=\"檔"}</p>
+      <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>
     </div>
   ),
 }