@qijenchen/design-system 0.1.0-beta.145 → 0.1.0-beta.147

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

@@ -46,7 +46,7 @@ export const Overview: Story = {
               {[
                 ['name', 'string', '必填', '檔名'],
                 ['mode', "'compact' | 'rich'", "'compact'", 'compact=Paperclip 16px icon / rich=Avatar 48px 縮圖'],
-                ['surface', "'form' | 'upload-manager'", "'form'", '所在容器 context:form=rich 為 border card / upload-manager=rich 無邊框無 bg(面板自身是容器,avatar 作 item 邊界)+ padding 縮減。詳 spec「邊框 / 背景」「Padding」表'],
+                ['surface', "'form' | 'upload-manager'", "'form'", '所在容器 context:form=rich 為 border card / upload-manager=rich 無邊框無 bg(面板自身是容器,avatar 作 item 邊界);upload-manager 的列自帶左右 loose、上下 tight/2,鋪滿面板寬(面板 body 左右 0,2026-09-25 待辦總帳 B12)。詳 spec「邊框 / 背景」「Padding」表'],
                 ['status', "'uploading' | 'completed' | 'error'", '—', '上傳狀態(不傳=已上傳靜態)'],
                 ['progress', 'number', '0', '上傳進度 0-100(有 status 時顯示 bar;completed 強制 100%)'],
                 ['description', 'ReactNode', '—', 'rich 任意場景 / compact 只有 error 才顯示。ReactNode — 可含 inline clickable link(如「View log」)'],
@@ -54,7 +54,7 @@ export const Overview: Story = {
                 ['actions', 'ReactNode', '—', 'suffix actions(例:delete / cancel button)'],
                 ['onDownload', '() => void', '—', "hover-swap:status='completed' 時,滑鼠移上整列,綠勾 ✓ 換成下載 ↓。兩種 mode 都用 Button xs(24)iconOnly,符合列內操作 ≤ 24 上限"],
                 ['onRetry', '() => void', '—', "hover-swap:status='error' 時,滑鼠移上整列,紅叉 ✗ 換成重試 ⟲。幾何同上 — 兩種 mode 都用 Button xs(24)"],
-                ['onClick', '() => void', '—', '傳入後整個 item 變可點擊(cursor-pointer,無 hover bg——FileItem 設計準則:permanent-anchored 元件不加 hover-bg double-emphasis)'],
+                ['onClick', '() => void', '—', '傳入後整個 item 變可點擊:cursor-pointer + 滑過底色(卡片疊一層 / 小膠囊換 secondary-hover / 透明列換 neutral-hover);不傳就沒有滑過底色 —— 點了會有反應的才加(2026-09-25 待辦總帳 B12)'],
               ].map(([p, t, d, desc]) => (
                 <tr key={p}><Td mono>{p}</Td><Td mono>{t}</Td><Td mono>{d}</Td><Td>{desc}</Td></tr>
               ))}
@@ -102,7 +102,7 @@ export const ColorMatrix: Story = {
         <H3>Status × 元素 色彩矩陣</H3>
         <Desc>
           FileItem 本身無色彩變體——text 走 item-anatomy row primitive 共用 token
-          (`--foreground` / `--fg-secondary`);background 依 mode × surface 決定(rich + surface=form = `--surface` + border / rich + surface=upload-manager = 無邊框無 bg / compact 無 status = `--secondary` / compact 有 status = transparent),無 hover-bg(見下方 Container background table)。
+          (`--foreground` / `--fg-secondary`);background 依 mode × surface 決定(rich + surface=form = `--surface` + border / rich + surface=upload-manager = 無邊框無 bg / compact 無 status = `--secondary` / compact 有 status = transparent);滑過底色只在有 onClick 時出現(見下方 Container background table)。
           Status 才驅動色彩:progress bar 色(inProgress / success / error)+ status icon 色(check / X)+ description 色(error 時升階)。
         </Desc>
         <div className="overflow-x-auto mb-4">
@@ -151,9 +151,11 @@ export const ColorMatrix: Story = {
       </div>
 
       <div>
-        <H3>Container background(per mode,無 hover-bg)</H3>
+        <H3>Container background(per mode + 有 onClick 時的滑過)</H3>
         <Desc>
-          FileItem 設計準則(2026-04-23):永不顯示 hover-bg。各型態皆已 permanent-anchored(rich + surface=form = border card / rich + surface=upload-manager = avatar 作 item 邊界 / compact 無 status = bg-secondary / compact 有 status = 底部 progress bar),再加 hover-bg 是 double-emphasis 視覺雜。affordance 只靠 `cursor-pointer`(onClick 時)+ hover-swap icon fade。詳 spec「Hover 行為 canonical」。
+          只有點了會有反應(傳了 onClick)的 FileItem 才有滑過底色,沒傳就沒有(2026-09-25 待辦總帳 B12,取代 2026-04-23「永不顯示 hover-bg」)。
+          換上什麼色依平常底色配對(color.spec.md「Hover 換色配對總則」):「底」疊一層、自己的填色換下一階、透明換 neutral-hover。
+          列內按鈕的滑過色疊在列的滑過色上;不加按住那一階(待辦總帳 N4 未決)。詳 spec「滑過」段。
         </Desc>
         <div className="overflow-x-auto">
           <table className="text-caption border-collapse">
@@ -162,10 +164,13 @@ export const ColorMatrix: Story = {
             </thead>
             <tbody>
               <tr><Td mono>rich + surface=form(all status)</Td><Td><span className="inline-flex items-center gap-1.5"><Swatch value="--surface" size="sm" /><span className="font-mono">--surface</span> + border</span></Td><Td>card(border + rounded + bg-surface)——Slack / Notion attachment 慣例</Td></tr>
-              <tr><Td mono>rich + surface=upload-manager(all status)</Td><Td><span className="font-mono">無邊框無 bg(只留 rounded-md)</span></Td><Td>面板自身是容器,avatar 作 item 邊界。詳 spec「邊框 / 背景」表</Td></tr>
+              <tr><Td mono>rich + surface=upload-manager(all status)</Td><Td><span className="font-mono">無邊框無 bg、直角(列鋪滿面板寬)</span></Td><Td>面板自身是容器,avatar 作 item 邊界。詳 spec「邊框 / 背景」表</Td></tr>
               <tr><Td mono>compact 無 status</Td><Td><span className="inline-flex items-center gap-1.5"><Swatch value="--secondary" size="sm" /><span className="font-mono">--secondary</span>(= neutral-3)</span></Td><Td>靜態 pill,對齊 Badge low / ProgressBar track SSOT</Td></tr>
               <tr><Td mono>compact 有 status</Td><Td><span className="font-mono">transparent</span></Td><Td>底部 progress bar 作 permanent affordance(分隔線型)</Td></tr>
-              <tr><Td mono>hover(任意 mode)</Td><Td><span className="font-mono">無變化</span></Td><Td>permanent-anchored → 不加 hover-bg。cursor-pointer 作 affordance(onClick 時)</Td></tr>
+              <tr><Td mono>滑過:rich + surface=form + onClick</Td><Td><span className="inline-flex items-center gap-1.5"><Swatch value="--surface" size="sm" /><span className="font-mono">--surface</span> + 疊 <span className="font-mono">--neutral-hover</span>(bg-interaction-hover)</span></Td><Td>「底」不換色,疊一層</Td></tr>
+              <tr><Td mono>滑過:compact 無 status + onClick</Td><Td><span className="inline-flex items-center gap-1.5"><Swatch value="--secondary-hover" size="sm" /><span className="font-mono">--secondary-hover</span></span></Td><Td>自己的填色換成下一階,不借透明底的配對</Td></tr>
+              <tr><Td mono>滑過:透明的列(compact 有 status、upload-manager)+ onClick</Td><Td><span className="inline-flex items-center gap-1.5"><Swatch value="--neutral-hover" size="sm" /><span className="font-mono">--neutral-hover</span></span></Td><Td>透明底的配對;upload-manager 的列鋪滿面板寬</Td></tr>
+              <tr><Td mono>滑過:沒有 onClick</Td><Td><span className="font-mono">無變化</span></Td><Td>點了沒反應 → 不上色(B12);hover-swap 的鈕仍有自己的滑過色</Td></tr>
               <tr><Td mono>error</Td><Td><span className="font-mono">容器不變</span></Td><Td>只升階 description / bar / icon,不染容器——避免整 row 轉紅蓋過其他 metadata</Td></tr>
             </tbody>
           </table>
@@ -288,6 +293,10 @@ export const StateBehavior: Story = {
     <div className="flex flex-col gap-4 max-w-lg">
       <div>
         <H3>所有狀態對照</H3>
+        <Desc>
+          只有最後一張(static.pdf)傳了 onClick:游標移上去,卡片的白底不換、疊一層淡灰;游標再移到它的下載鈕上,鈕自己的淡灰再疊上去。
+          前三張沒有 onClick,點卡片本身沒反應,所以不上滑過底色(2026-09-25 待辦總帳 B12)。
+        </Desc>
         <div className="flex flex-col gap-2">
           <FileItem name="uploading.pdf" description="2.4 MB · 上傳中 60%" status="uploading" progress={60} mode="rich" actions={<Button variant="text" size="xs" iconOnly startIcon={X} aria-label="取消" />} />
           <FileItem name="completed.pdf" description="2.4 MB · 已上傳" status="completed" mode="rich" actions={<Button variant="text" size="xs" iconOnly startIcon={Download} aria-label="下載" />} />
@@ -328,7 +337,7 @@ export const Accessibility = {
         </li>
         <li>
           <strong className="text-foreground">狀態 icon 換成按鈕時的語音切換</strong>:滑鼠移上整列時,
-          被動的狀態 icon(綠勾 / 紅叉)會淡出換成操作按鈕(下載 / 重試)。被動 icon 對螢幕報讀軟體隱藏,
+          被動的狀態 icon(綠勾 / 紅叉)會立刻換成操作按鈕(下載 / 重試)。被動 icon 對螢幕報讀軟體隱藏,
           換上的操作按鈕自帶語音標籤,使用者不會聽到視覺切換的雜訊。
         </li>
         <li>
@@ -337,8 +346,9 @@ export const Accessibility = {
           只寫「下載」「刪除」缺檔名,螢幕報讀使用者無法分辨是哪一列。
         </li>
         <li>
-          <strong className="text-foreground">整列不可整塊鍵盤聚焦</strong>:為避免與列內操作按鈕互相干擾(巢狀互動),
-          整列不設成單一可聚焦按鈕;鍵盤使用者直接 Tab 到列內的操作按鈕。滑鼠仍可點擊整列觸發 onClick。
+          <strong className="text-foreground">整列不是一顆按鈕,但鍵盤到得了整列</strong>:為避免與列內操作按鈕互相干擾(巢狀互動),
+          列本身不設成按鈕;傳 onClick 時列裡鋪一顆看不見的整列按鈕(Tab / Enter / Space,名稱「開啟 檔名」),焦點框畫在列上,列內操作按鈕各自一站(file-item.spec.md「Row primary action 鍵盤可達」);滑鼠照樣點整列觸發 onClick。
+          放進 FileUpload 內建清單(有 onRemove)時,整串清單改成一個 Tab 停靠點:列本身拿焦點、↑↓ 換列、→ 進移除鈕(file-upload.spec.md「A11y 預設 › 檔案清單鍵盤」,待辦總帳 B9)。
         </li>
       </ul>
     </div>

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

@@ -5,6 +5,7 @@ import type { Meta, StoryObj } from '@storybook/react'
 import { X, Download, RotateCw } from 'lucide-react'
 import { FileItem } from './file-item'
 import { Button } from '@/design-system/components/Button/button'
+import { SurfaceBody } from '@/design-system/patterns/overlay-surface/overlay-surface'
 
 const meta: Meta = {
   title: 'Design System/Components/FileItem/設計原則',
@@ -147,13 +148,19 @@ export const StatusProgressRule: Story = {
         title="completed — 成功 icon + 100% 完成條"
         note="完成後保留 100% 綠色完成條(surface=upload-manager narrative —— 上傳狀態是重點,Dropbox / Google Drive 慣例),成功 icon 再加一層明確表達「完成」。檔案變可點擊(下載)"
       >
-        <FileItem
-          name="users-export.csv"
-          description="1.2 MB"
-          status="completed"
-          surface="upload-manager"
-          mode="rich"
-        />
+        {/* surface="upload-manager" 的列只在上傳管理器面板裡成立(列自帶左右 16px,面板 body 左右 0;B12)——
+            單獨放會多出內距、跟同頁其他範例對不齊,所以照 file-item.stories.tsx UploadManagerSurface 的面板組合包起來(M23(d)) */}
+        <div className="max-w-md flex flex-col rounded-lg border border-border bg-surface-raised shadow-[var(--elevation-200)]">
+          <SurfaceBody className="flex flex-col gap-0 !px-0 !py-[calc(var(--layout-space-tight)/2)]">
+            <FileItem
+              name="users-export.csv"
+              description="1.2 MB"
+              status="completed"
+              surface="upload-manager"
+              mode="rich"
+            />
+          </SurfaceBody>
+        </div>
       </Rule>
 
       <Rule

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

@@ -113,7 +113,7 @@ compact 為預設——多數 upload 清單是「快速掃視多檔」場景，
 item-anatomy「> 24 prefix + 有 desc」規則要求 prefix 對齊 content 塊**中心**(items-center)。
 FileItem rich **刻意不遵守**這條,使用 `items-start`(top-align),原因:
 
-> **當 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 的起點。
+> **當 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)
 
@@ -124,11 +124,11 @@ Avatar **固定 48px square**,不隨 content 高度變化。content(label + desc
 | Mode × surface | 規則 |
 |---|---|
 | compact(`surface=form` 預設) | `px-3 py-2`(FileItem 無 size prop,不走 `ROW_PADDING_BY_SIZE` 公式;`gap-2` 對齊 item-anatomy row) |
-| compact(`surface=upload-manager`) | **`py-2` 保留 + 左右 padding 拿掉**(`px-0`)。py 是**純文字列高來源**(無 avatar 撐高)不可拿;左右拿掉讓列對齊面板 loose L/R |
+| compact(`surface=upload-manager`) | **左右 = 列自帶 `--layout-space-loose`**;上 `tight/2`、下 `tight/2 + 0.5rem`(0.5rem = 原 `py-2` 的下緣:文字↔bar 6 + bar 2),bar 離列底 `tight/2`。**2026-09-25 待辦總帳 B12 推翻 06-03 的「`px-0`、左右交給面板」**:可點的列滑過底色要鋪到面板左右邊,gutter 只能由列自己帶(見下方「item 與容器分工」) |
 | rich(`surface=form` 預設) | `px-3 py-3` border card(py 固定,高度由 avatar 決定不走 row 公式)|
-| rich(`surface=upload-manager`) | **左右 + 上下 padding 全拿掉**(`px-0 py-0`)。**列高靠 avatar 48(content `minHeight`)**,卡片移除後 py 多餘 → 由面板 + gap 控制間距(2026-06-03 user 校準:rich 拿上下、compact 保留上下,因列高來源不同)|
+| rich(`surface=upload-manager`) | **左右 = 列自帶 `--layout-space-loose`、上下各 `tight/2`**(列高 = avatar 48 + tight)。06-03 的 `px-0 py-0` 同樣由 B12 推翻;上下補 `tight/2` 是為了滑過底色不貼縮圖(AI 推導) |
 
-**item 與容器分工**:item 只控「容器不該管的內距」—— compact `py-2`(純文字列高來源,無 avatar 撐高)/ rich `0`(列高靠 avatar 48);左右一律拿掉交給容器。**`surface=upload-manager` 浮層面板(容器)的左右 / 上下 padding / 列間 gap → 見「List wrapper canonical」的「upload-manager 浮層面板 composition」段**(SSOT 不在此重述,避免 drift)。
+**item 與容器分工**:判準是「誰負責左右 gutter」(`../../patterns/overlay-surface/overlay-surface.spec.md`「底部區域:按鈕列 vs 列式」)—— 列有整列滑過底色、要鋪到容器邊時,gutter 由列自己帶、容器給 0(`surface=upload-manager`);form 的列不鋪到容器邊,內距如上表。**`surface=upload-manager` 浮層面板(容器)的 padding / 列間 gap → 見「List wrapper canonical」的「upload-manager 浮層面板 composition」段**(SSOT 不在此重述,避免 drift)。
 
 ## 邊框 / 背景(AR15-21 canonical,2026-04-21 · 2026-04-22 擴充)
 
@@ -137,36 +137,24 @@ Avatar **固定 48px square**,不隨 content 高度變化。content(label + desc
 | Mode × surface | 容器視覺 | Rationale |
 |------|---------|-----------|
 | **rich + `surface=form`**（預設，表單/訊息附件）| `border border-divider rounded-md bg-surface` | Rich = 「檔案 card」自立輪廓——Slack / Notion / Linear attachment 慣例；邊框讓每 row 視覺獨立 |
-| **rich + `surface=upload-manager`**（Google Drive / Dropbox 背景上傳 box）| **無邊框 + 無 bg**（`rounded-md` 保留供 thumbnail 切角）；avatar 作每筆 item 視覺邊界 | box 自身已是容器 → card border 多餘＝雙層容器；avatar thumbnail 提供「每筆檔案」邊界節奏。2026-06-03 codify（原僅 L116 旁註「consumer 自己移除 border」，現 `surface` prop 機械化）|
+| **rich + `surface=upload-manager`**（Google Drive / Dropbox 背景上傳 box）| **無邊框 + 無 bg + 直角**(2026-09-25 B12 起列鋪滿面板寬,圓角碰到面板直邊會缺角,AI 推導;縮圖切角是 Avatar `shape="square"` 自己的圓角,不靠列);avatar 作每筆 item 視覺邊界 | box 自身已是容器 → card border 多餘＝雙層容器；avatar thumbnail 提供「每筆檔案」邊界節奏。2026-06-03 codify（原僅 L116 旁註「consumer 自己移除 border」，現 `surface` prop 機械化）|
 | **compact + 有 status**（uploading / error / upload-manager completed，有 progress bar）| 無背景、無邊框,只靠 progress bar 提供 affordance | 「正在發生」/「剛發生」的動態 narrative,progress 本身就是視覺焦點 |
 | **compact + 無 progress**(form attachment 靜態態) | `bg-secondary rounded-md`(= neutral-3 色) | 靜態清單(form / 訊息附件)背景色區隔出「檔案 row」邊界,跟純文字內容區分。**為何 `bg-secondary` 不 `bg-neutral-3`**:`--secondary` 是 semantic token 經 `@theme inline` 橋接成合法 Tailwind utility,`--color-neutral-3` 是 primitive token(僅 `:root` CSS var)不生成 utility,寫 `bg-neutral-3` 會 silent 失效。對齊 Badge low / ProgressBar track SSOT(同色) |
 
-### Hover 行為 canonical(2026-04-23)
+### 滑過(2026-09-25,待辦總帳 B12;取代 2026-04-23「FileItem 永不顯示 hover-bg」)
 
-**FileItem 永不顯示 hover-bg**,不論 mode / status / onClick。affordance 只靠 `cursor-pointer`(onClick 存在時)+ actions icon / hover-swap(status slot icon fade → action icon fade)。
+**只有點了會有反應(傳了 `onClick`)的 FileItem 才有滑過底色;沒傳就沒有。** user 原話:「要點了會有反應的才加，並確保加上去之後不會有任何視覺奇怪的地方，且按鈕的互動樣式也是自然疊加上去吧？用再亮一層這樣的措辭是否不夠精準？」換上什麼色依平常底色配對,規則住在 `../../tokens/color/color.spec.md`「Hover 換色配對總則」,本表只列 FileItem 的對應:
 
-**Rationale(permanent visual anchor → 不加 hover-bg double-emphasis)**:
-
-| Mode | 永久 visual anchor | 加 hover-bg 後果 |
-|------|-------------------|-----------------|
-| 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 重複 |
-
-三種型態**都已 anchored**,hover-bg 是多餘的視覺層。Cursor + click 本身已是足夠互動 affordance,世界級檔案 card / attachment 皆如此。
-
-**世界級對照**(M8 / M12 benchmark):
-
-| DS | File card / attachment hover 行為 | 跟本 canonical 對齊? |
-|----|----------------------------------|----------------------|
-| Slack file tile | border highlight,**無 bg 變化** | ✓ |
-| Notion file callout | **無 bg 變化**,action icons fade in | ✓ |
-| Figma file card | shadow lift,**無 bg 變化** | ✓ |
-| Gmail attachment chip | **無 bg 變化**,download icon fade in | ✓ |
-| Dropbox / Google Drive file **row**(flush transparent 無 permanent anchor) | **有** hover-bg | Opposite case(證明 canonical:anchored → 無、flush → 有) |
+| 型態 | 平常底色 | 有 `onClick` 時滑過 |
+|---|---|---|
+| rich `surface=form`(卡片) | `bg-surface`(「底」) | 底不換,疊一層 `hover:bg-interaction-hover` |
+| compact 無 status(小膠囊) | `bg-secondary` | 換成自己的下一階 `hover:bg-secondary-hover` |
+| compact 有 status、`surface=upload-manager` 的兩 mode | 透明 | 換成 `hover:bg-neutral-hover`;upload-manager 的列鋪滿面板寬(見「Padding」) |
 
-**跟 MenuItem / DataTable row 對比**(它們用 hover-bg):兩者是 **flush transparent row**(無 permanent bg / border),hover-bg 是唯一 affordance。FileItem 三種型態皆已 anchored → 反向 canonical。
+- **沒有 `onClick` 的不加**:上傳管理器裡只會在滑過時把 ✓ 換成下載鈕、點列本身沒反應的列也不加(待辦總帳 A3 → B12)—— 換位照舊,只有那顆鈕有自己的滑過色。
+- **列內按鈕**(刪除、下載、重試)滑過時換上自己的 `--neutral-hover`(半透明),疊在列的滑過色上,不寫特例;規則在 `color.spec.md`「巢狀滑過」段。
+- **不加按住那一階**:FileItem「按下深一階」是待辦總帳 N4 / F 模型 D3(2),尚未提問(AI 推導:不先替 user 決定)。
+- **撤回的舊理由**(「三型態皆常駐錨點,加底色 = 雙重強調」):有框、有常駐底色的附件卡可點時照樣換底色 —— [shadcn Attachment](https://github.com/shadcn-ui/ui/blob/98a1fe67b439324ddc857f47fbdce056600a4329/apps/v4/registry/bases/radix/ui/attachment.tsx#L9)(`has-[>a,>button]:hover:bg-muted/50`,放了整卡觸發層才換);不可點的清單列不加滑過層 —— [Material Web list item](https://github.com/material-components/material-web/blob/cbd34a8921915af94d5ef65c2a69eece41d5b4f3/list/internal/listitem/list-item.ts#L161-L169)(`type="text"` 不渲染 ripple)。舊對照表(Slack / Notion / Figma / Gmail)沒有任何來源,一併撤回。不可點也上色的另一派([Ant Design Upload 文字清單](https://github.com/ant-design/ant-design/blob/4f9fe53933922d69f89bcd79de9de87b5124f522/components/upload/style/list.ts#L20-L32))與上面 user 原話不符,不採用。
 
 **❌ 反例**:
 - Rich `surface=form` 無邊框 → 失去 card 自立輪廓,與一般 list item 無法區分,跟 MenuItem 混淆(`surface=upload-manager` 例外:面板自身是容器 + avatar 作邊界,rich 刻意無邊框,見上表)
@@ -188,7 +176,7 @@ Avatar **固定 48px square**,不隨 content 高度變化。content(label + desc
 | `status` | `uploading` / `error` / `completed`(**completed 持續保留不清除** = 此情境精髓) |
 | Progress bar | 隨 status 顯示;completed = 100% 完成條(不隱藏) |
 | Status icon | uploading 無 / completed 綠 ✓ / error 紅 ✗ |
-| hover 行為 | **status slot hover-swap**:✓ → Download ↓(icon button)觸發 `onDownload` |
+| hover 行為 | **status slot hover-swap**:✓ → Download ↓(icon button)觸發 `onDownload`;有 `onClick` 的列另有整列滑過底色(透明 → `neutral-hover`,鋪到面板左右邊),沒有 `onClick` 的列不上色(見「滑過」段) |
 | Row-click | optional `onClick` 讓整 row 可點 → 預設 FileViewer 開啟;可與 hover-swap 並存 |
 | Rich 容器 | **無邊框 + 無 bg**(面板自身是容器,avatar 作 item 邊界)。**2026-06-03 修正:原寫「border card 永遠」與 surface=upload-manager 無邊框矛盾** |
 | Compact 容器 | 無 bg(progress bar 提供 affordance) |
@@ -214,7 +202,7 @@ Avatar **固定 48px square**,不隨 content 高度變化。content(label + desc
 | `status` | 上傳中暫時 `uploading` / `error`;**靜態態 `undefined`**(清除) |
 | Progress bar | 上傳中顯示;靜態態無 |
 | Status icon | 同上 |
-| hover 行為 | `cursor-pointer`(永不顯示 hover-bg ——permanent-anchored 元件不加 double-emphasis) |
+| hover 行為 | 有 `onClick` 時 `cursor-pointer` + 滑過底色(卡片疊一層 / 小膠囊 `secondary-hover` / 有進度條的列 `neutral-hover`,見「滑過」段);沒有 `onClick` 不上色 |
 | Row-click | **`onClick` 為主要 affordance** → **預設 FileViewer 開啟**(consumer 決定,也可下載) |
 | Rich 容器 | `border card`(永遠) |
 | Compact 容器 | 靜態態 `bg-secondary`(灰底區隔「這是檔案 row」;= `--color-neutral-3` semantic 橋接名,見邊框 / 背景章節);上傳中有 bar 時無灰底 |
@@ -247,14 +235,14 @@ Description 是 ReactNode,**不限純文字**。常見場景:
   description={
     <>
       Network timeout.{' '}
-      <a href="#logs" className="underline hover:text-error-hover">View log</a>
+      <a href="#logs" className="underline">View log</a>
     </>
   }
   onRetry={noop}
 />
 ```
 
-視覺上 underline + hover 色變讓使用者知道「那段文字可點」。
+連結**沿用錯誤訊息的字色**、平常就有底線,**滑過不換色**(user 2026-09-26 選「乙 紅字 + 底線，滑過不變」)。底線是整句紅字裡唯一標出「這段可點」的訊號;滑過不必有變化(`../../ds-canonical/references/hit-area-canonical.md` 已同意的原則:點得到的地方不一定要有滑過變化)。**不可**寫 `hover:text-error-hover`:`--error-hover` 是紅色填色 `--error` 的配對,套在紅字上淺色會變淡(對比 7.2 → 3.3)、深色與 `--error-text` 同一格而完全不變。世界級同款:Polaris 放在 Banner 裡的 Link 自動 monochrome —— 「Makes the link color the same as the current text color and adds an underline」,平常與滑過都是 `color:inherit`([Link.out.css @13.9.5](https://cdn.jsdelivr.net/npm/@shopify/polaris@13.9.5/build/esnext/components/Link/Link.out.css))。顏色規則的例外寫在 `../../tokens/color/color.spec.md`「不該用 `--{hue}-text` 的場景」。
 
 ### 不可混用 invariants
 
@@ -273,33 +261,30 @@ upload-manager 的 completed(100% bar + ✓)屬「剛完成的 upload session」
 
 ## List wrapper canonical(多 item 間距)
 
-**規則:gap 由「item 視覺密度」決定** —— rich form(有邊框 card)`gap-2`(8px,邊框不相黏);rich `surface=upload-manager`(無邊框)`gap-[var(--layout-space-tight)]`(12px);compact(所有情境)`gap-1`(4px)。
+**規則:gap 由「item 視覺密度」決定** —— rich form(有邊框 card)`gap-2`(8px,邊框不相黏);compact form `gap-1`(4px);`surface=upload-manager`(兩 mode)`gap-0`,列間距改由列自帶的上下 `tight/2` 相加(2026-09-25 B12)。
 
 | Mode × surface | List wrapper gap | Rationale |
 |------|----------------|-----------|
 | **Rich + `surface=form`**(border card)| `gap-2`(8px) | card 邊框不相黏(standalone card invariant) |
-| **Rich + `surface=upload-manager`**(無邊框浮層面板)| `gap-[var(--layout-space-tight)]`(12px)| 卡片 + 48 縮圖列需垂直呼吸。**2026-06-03 圖五 user 校準:rich upload-manager 初版誤設 4px,已校正為 tight(12px)**,因 rich 列比 compact 大 |
-| **Compact**(所有情境)| `gap-1`(4px) | 統一 — 有 status only / 無 status only / mixed 都 gap-1(2026-04-23 user 指示簡化:原條件式「全上傳中 → 0 gap」是 consumer 心智負擔 + state 轉換時 fragile,故捨棄 0-gap)|
+| **`surface=upload-manager`**(rich + compact,無邊框浮層面板)| `gap-0` | 縮圖↔縮圖、bar↔下一列文字仍是 tight(12px):**2026-06-03 圖五 user 校準的 12px**(rich 初版誤設 4px 後校正)不變,只是從「列間 gap」改由兩列各自的上下 `tight/2` 相加得出 —— 可點的列滑過底色上下相接,不在兩列之間留一條沒上色的縫(B12,AI 推導) |
+| **Compact + `surface=form`** | `gap-1`(4px) | 統一 — 有 status only / 無 status only / mixed 都 gap-1(2026-04-23 user 指示簡化:原條件式「全上傳中 → 0 gap」是 consumer 心智負擔 + state 轉換時 fragile,故捨棄 0-gap)|
 
 **control→list gap(FileUpload 內建 list 消費)**:dropzone / button 控制項 ↔ 第一個 FileItem 的間距 = **同上 form gap 同值**(rich card 8px / compact bg-pill 4px),由 `file-upload.tsx` 依 `fileListMode` 套用。**FileUpload 內建 list 一律 `surface=form`**(dropzone 是表單上傳框,非獨立浮層 upload manager),故不套用下方 upload-manager 的 12px / 面板 padding。
 
 ### upload-manager 浮層面板 composition(Google Drive 右下角類獨立面板,**非** FileUpload dropzone)
 
-`surface=upload-manager` 的 FileItem list 裝在獨立浮層面板(header + 列表),item 拿掉的左右 / 上下邊距改由容器負責:
+`surface=upload-manager` 的 FileItem list 裝在獨立浮層面板(header + 列表);左右 gutter 由列自己帶、面板 body 給 0,上下由列與 body 各給一半(2026-09-25 B12):
 
 - **它是 popover-class 浮層 surface,但不是 Radix `<Popover>`**(常駐面板:不靠 trigger 開、不 outside-click 關、用 chevron 收合非 X dismiss)→ **不包 `<Popover>`**,而是直接消費 overlay-surface 三件套 primitive。
 - **殼 + header + body 全消費 overlay-surface SSOT(禁手刻)**:
   - 殼:消費 Popover-class surface contract(border / radius / elevation / raised surface)，但保持 persistent panel 語意；確切 utility 由對應 story / component source 擁有。
   - header:`<SurfaceHeader className={cn("justify-between", COMPACT_HEADER_SLOT)}>` + `<PopoverTitle>`(輕量浮層 header SSOT,slot 走 `COMPACT_HEADER_SLOT`=21 衍生自 text-body title;padding = px-loose py-tight + border-b + unbounded-slot 負 my trick)。
-  - body:**`<SurfaceBody>`(body SSOT,含 px-loose py-tight + flex-1 scroll 鏈)**,FileItem-specific padding 用 className override(見下)。**這不是「List-as-region」**:upload-manager 的 body 保留 `px-loose` chrome padding(List-as-region 的判定條件是 body 撤掉 chrome padding `!px-0`),故直接用 `SurfaceBody` 預設。判定條件的 owner 在 `../../patterns/overlay-surface/overlay-surface.spec.md`「List-as-region in overlay body」,本檔不複述。**scroll(consumer 注意)**:SurfaceBody 的 `flex-1 / overflow-y-auto` 只在 shell 有 `max-h` + `overflow-hidden` 時生效;常駐面板若檔案數可超 viewport,shell 須加 `max-h`(對齊 overlay-surface.spec.md「viewport-aware scroll」),demo 短內容不需。
+  - body:**`<SurfaceBody className="flex flex-col gap-0 !px-0 !py-[calc(var(--layout-space-tight)/2)]">`**(body SSOT 的 flex-1 scroll 鏈照用,padding 用 className override,見下)。左右 0 是「列式」(同 `../../patterns/overlay-surface/overlay-surface.spec.md`「誰負責左右 gutter」);它**仍不是**「List-as-region」—— 那個判定還要求上下也撤掉、清單外層自帶 `py-2`,owner 在同檔「List-as-region in overlay body」,本檔不複述。**scroll(consumer 注意)**:SurfaceBody 的 `flex-1 / overflow-y-auto` 只在 shell 有 `max-h` + `overflow-hidden` 時生效;常駐面板若檔案數可超 viewport,shell 須加 `max-h`(對齊 overlay-surface.spec.md「viewport-aware scroll」),demo 短內容不需。
   - **禁手刻**:header / body 必直接消費 overlay-surface primitives；另建等價 wrapper 會形成第二份 spacing 與 surface authority。Hook `check_story_invariants.sh R9` 機械攔截。
 
-- **左右**:`SurfaceBody` 預設 `px-[var(--layout-space-loose)]`(16px,item 內容左緣對齊 header 標題),不需 override。
-- **上下:目標 = 邊緣到 item「ink」(可見內容)距離 `var(--layout-space-tight)`(12px),兩 mode + 上下都一致**。通則:**容器該側 padding = 12 − item 在該側自己的留白(ink inset)**。
-  - **rich**:item 上下 ink inset 皆 0(avatar 頂、bar/content 底貼齊)→ 用 `SurfaceBody` 預設 `py-[var(--layout-space-tight)]`(12 / 12 對稱,不需 override)。
-  - **compact**:item 上方自帶 `py-2`(8px)→ top 補 `4`(4+8=12);**進度條 `absolute bottom-0` 貼 item 底、下方無留白(inset 0)**→ bottom 留 SurfaceBody 預設 `py-tight`(12,12+0=12)。故 compact 用 **`SurfaceBody className="!pt-1"`** override 成上下不對稱(top=4 / bottom=12)。**為何用 `!`(important)**:twMerge 不 strip SurfaceBody 基底 `py-[tight]`,非 important 的 `pt-1` 跟基底 `py` 競爭 top 看 Tailwind stylesheet 生成順序(非決定性 → 可能 silent 變 12);`!pt-1` 強制決定性勝。對齊 List-as-region `!px-0` SurfaceBody override 慣例。
-- **列間 gap**:套在 SurfaceBody className;值見上方「List wrapper canonical」gap 表(SSOT,不在此重述:rich upload-manager 12px / compact 4px)。
-- **為何 compact container 上下不對稱**(2026-06-03 圖一研究校準):compact 進度條 absolute 貼底,item 的 py-2 那 8px 落在「文字↔bar」之間、bar 下方無 padding;若上下都用同值 → 下邊距(bar→邊緣)只剩容器值、比上邊距(含 item 8px)小。故用「12 − ink inset」逐側補。世界級對照:密集 list / dropdown 容器上下 padding 慣例 4–8px(Atlassian space.050–100 / 8px-base 共識);此處目標 12px 是「邊緣→ink」視覺值(含 item 自身留白),非容器裸值。
+- **左右**:body `!px-0`,列自帶 `--layout-space-loose`(16px)→ item 內容左緣仍對齊 header 標題(x 與 06-03 相同),可點列的滑過底色則鋪到面板左右邊(`overlay-surface.spec.md` M11 state walk 三題:底色邊 = chrome 邊、內容對齊標題、內容離底色邊 ≥ loose)。**推翻 2026-06-03「左右交給面板」**:那時列沒有滑過底色;B12 後可點的列有了,底色若只到內容邊會貼著縮圖與文字(同檔「❌ 禁止:Item `px=0` 讓 content 直接觸 hover bg 邊」)。
+- **上下:目標不變 = 邊緣到 item「ink」(可見內容)、ink 到 ink 都是 `var(--layout-space-tight)`(12px)**,通則仍是「容器該側 padding = 12 − item 在該側自己的留白(ink inset)」。B12 後兩 mode 的列上下各自帶 `tight/2`(compact 的 bar 離列底 `tight/2`,見「Padding」)→ body 上下都給 `tight/2`、列間 gap 0,兩 mode 同一個 body 寫法;06-03 compact 的 `!pt-1` 上下不對稱(因 bar 貼列底)隨之取消。**為何用 `!`(important)**:沿用 List-as-region `!px-0` 與 06-03 `!pt-1` 的寫法 —— 覆寫的勝負不依賴 twMerge 對 arbitrary 值的分組判斷,也不依賴 Tailwind stylesheet 的生成順序。
+- **列間 gap**:套在 SurfaceBody className;值見上方「List wrapper canonical」gap 表(SSOT,不在此重述)。
 - Demo:`file-item.stories.tsx` 的 `UploadManagerSurface`(rich)/ `UploadManagerCompactSurface`(compact)。
 
 **Rich + Compact 不可混用**(見 Invariant 1 上方),故無「混用 gap」決策。
@@ -331,6 +316,7 @@ upload-manager 的 completed(100% bar + ✓)屬「剛完成的 upload session」
 - FileItem 提供 `onClick` prop,consumer 傳入即進 clickable 模式：滑鼠保留整列 hit area；鍵盤透過同層透明 native button 以 Tab / Enter / Space 觸發，並以 `actionAriaLabel`（預設「開啟 {name}」）命名。row 本身不加互動 role，避免包住 trailing actions 形成 nested-interactive。
 - 兩種 surface 都可以用 `onClick`(upload-manager 可跟 `onDownload` hover-swap 並存)
 - consumer 決定具體行為(download / FileViewer),元件只提供 row 可點擊能力
+- **為什麼是「列不互動 + 覆蓋控件」而不是「列自己是 button」**:因為本元件的列裡裝了必須被輔助科技讀到的結構——`ProgressBar`(自帶 `role="progressbar"`)、`Avatar`、以及 hover-swap 的 `<Button>`;依 `../../patterns/element-anatomy/item-anatomy.spec.md`「整列可點時,誰當那顆控件」表,這是**第二類**。Sidebar 的列只有文字與圖示,走**第一類**(列自己就是 `<button>`)。判準與規範逐字出處在該表,本檔不重述。
 
 ## ProgressBar
 
@@ -345,6 +331,22 @@ upload-manager 的 completed(100% bar + ✓)屬「剛完成的 upload session」
 
 改動進度條視覺(高度 / 色 / 動畫) → 去 ProgressBar 改,**本元件無本地 bar 實作**。
 
+### 焦點框 × 貼著列底的進度條(2026-09-26)
+
+**適用範圍**:只有 `surface="form"` 的 compact 列、而且有 `status`(進度條貼列底)。這種列拿到鍵盤焦點時(本元件的整列焦點框,或 FileUpload 清單列的焦點框),往內 2px 的焦點框底邊與 2px 的進度條落在同一條線上。`upload-manager` 的進度條離列底 `tight/2`、rich 的進度條在內容區,都碰不到框,不適用本段。
+
+**問題(實測)**:進度條本來就畫在框的**上面**,但它沒有把框蓋住 —— 軌道 `--secondary` 是半透明(淺色 6% 黑、深色 12% 白),框的藍從軌道透出來;填色 `--info` 又與框 `--ring` 同為 blue-6。聚焦時填色對軌道只剩 1.10:1(深色 1.17:1),平常是 4.55:1(深色 4.04:1);填色與框黏成一條,看不出進度從哪裡開始、到哪裡。
+
+**規則**:進度條留在框的上面(user 2026-09-26 選的方向,逐字:「我喜歡墊在鍵盤焦點上的方向，依此方向仔細研究怎樣最好」),框在**進度條那一段挖空**,連同進度條兩端各多挖 2px 的縫(挖空與縫寬是 AI 研究後的建議,user 同日回「我覺得方向可以，確保整個設計符合我們一致的設計語言且不違背世界級的設計就照你建議」)。聚焦時底邊讀起來是「框|縫|進度條|縫|框」。
+
+- **挖空,不是墊底色**:挖掉的地方露出的是真正在後面的東西(列自己的滑過色、卡片、面板、頁面),所以聚焦時進度條的每個像素與平常相同,任何底色上都對。墊一塊固定底色(例如 `--canvas`)只在那一種底上對:深色卡片上軌道會從平常的 `#383838` 變成 `#272727`;列正被滑過時也會少掉滑過色。改用「容器宣告自己底色」的變數也不行 —— 深色的 `--surface` 本身是白 8% 半透明,卡片放在浮層面板裡時真正的底是「面板 + 白 8%」,變數表達不了疊了幾層(實測軌道 `#383838` 對平常 `#4a4a4a`)。與 `../Avatar/avatar.spec.md`「頭像堆疊」選挖空、不畫外圈是同一個理由。
+- **縫 = `--stack-gap`(2px)**:與全域外描邊離元件的間隙、頭像堆疊的縫、步驟條外圈的縫同一個 token —— DS 把「疊在一起的兩樣東西分開」的縫都是它(`tokens/uiSize/uiSize.css`;設計理由住 `../Avatar/avatar.spec.md`「頭像堆疊」段,2026-09-26 抽成 token 前是 6 處字面值)。縫讓同色的藍分開:進度的起點(填色左端)與框的底邊之間隔著一道底色,不再黏成一條;進度條右端與框之間同樣留縫,兩端對稱。
+- **世界級對照**(一手原始碼,釘版本):同色的兩樣東西相鄰時,用一道底色的縫分開 —— Material 的線性進度條在填色與軌道之間留 4dp 的縫(MDC-Android 1.14.0 `app:indicatorTrackGapSize`:「size of the gap between the indicator and the track, 4dp by default」,[ProgressIndicator.md#L317-L325](https://github.com/material-components/material-components-android/blob/1.14.0/docs/components/ProgressIndicator.md#L317-L325)),而且那道縫是**不畫**,軌道從填色尾端加上縫之後才開始畫([DeterminateDrawable.java#L373-L391](https://github.com/material-components/material-components-android/blob/1.14.0/lib/java/com/google/android/material/progressindicator/DeterminateDrawable.java#L373-L391))—— 與本段的挖空同一種做法。IBM Carbon 的按鈕焦點框與主色填色同藍時,中間墊一道 `$background` 內線(`inset 0 0 0 $button-border-width $background`,[button/_mixins.scss#L133-L137 @v11.117.0](https://github.com/carbon-design-system/carbon/blob/v11.117.0/packages/styles/scss/components/button/_mixins.scss#L133-L137));那是固定底色 token,本段不採用固定底色的理由見上一條。
+- **怎麼做到**:框改畫在與列同形同大的 `::before`「框圖層」上(`FILE_ITEM_RING_LAYER_CLASS`),遮罩只挖這一層(`fileItemRingCutoutStyle`,位置與進度條同源 —— 都讀 `compactBarInset`)。框若畫在列本身,列是進度條的祖先,遮罩會連進度條一起挖掉。線寬、顏色、往內 2px、圓角全部照舊是 `focus-ring-inset`,不是第四種幾何(`ds-canonical/references/focus-canonical.md`「框怎麼畫」框圖層列)。FileUpload 的清單列用同一個框圖層與同一個遮罩(`../FileUpload/file-upload.spec.md`「A11y 預設 › 檔案清單鍵盤」)。
+- **代價(寫明)**:框的底邊在進度條那一段(含兩端縫)不畫,框在那一段由進度條本身接上;框的上、左、右三邊與底邊兩端(含圓角)完整。這是「進度條留在框上面」這個方向本身的代價,不是實作取捨。
+- **平常的樣子一個像素都不動**:框圖層只在聚焦時有東西可畫,遮罩也只作用在這一層;進度條的位置、顏色、高度都不變(user 2026-09-26:「我他媽不想要動到這邊的一般視覺」)。
+- 不走的其他改法(逐條對應的規則):聚焦時把填色換成別的顏色 → `focus-canonical.md`「一個項目只有一個指示器」且狀態色被改掉;框往內多退 → 同檔「只准三種幾何」禁手寫其他退距;聚焦時把進度條抬離框 → 不是 user 選的方向。
+
 ## Actions（suffix,row dedicated region canonical）
 
 Consumer 自行組合。按 `patterns/element-anatomy/item-anatomy.spec.md`「Predicate」+「Row action 絕對值 cap」,**row dedicated action 絕對值 cap = ≤ 24px,不隨 row tier 放大**。依 row 高度分兩種實作:
@@ -354,7 +356,7 @@ Consumer 自行組合。按 `patterns/element-anatomy/item-anatomy.spec.md`「Pr
 | Mode | 實作 | 尺寸 |
 |------|------|------|
 | `rich` | **Button iconOnly `size="xs"`**(24 固定,不隨 row 放大) | 24 |
-| `compact` | **Button iconOnly `size="xs"`**(同 rich;靠 suffix wrapper `[&>[data-unbounded]]:my-[calc((1lh-var(--field-height-xs))/2)]` trick 把 24 footprint 收斂到 1lh,不撐高 row,視覺 / touch target 仍 24) | 24 |
+| `compact` | **Button iconOnly `size="xs"`**(同 rich;靠 suffix wrapper `[&>[data-unbounded]]:my-[calc((1lh-var(--field-height-xs))/2)]` trick 把 24 footprint 收斂到 1lh,不撐高 row,視覺與命中區仍 24) | 24 |
 
 ```tsx
 // Rich + Compact 統一 → Button xs iconOnly 固定 24(≤ 24 cap)
@@ -381,7 +383,7 @@ Consumer 自行組合。按 `patterns/element-anatomy/item-anatomy.spec.md`「Pr
 
 **幾何一致性(2026-04-23 統一 canonical · row action ≤ 24 cap)**:status slot 容器大小 **= consumer 的 delete action 尺寸**,兩 mode 統一:
 - `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)
+- `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,視覺與命中區仍 24 —— 命中 ≡ 可視,owner = `ds-canonical/references/hit-area-canonical.md`;2026-09-24 把本檔兩處原文的「touch target」正名為命中區,本 DS 以滑鼠指標的精度為前提,尺寸不以觸控門檻推導)
 
 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`。
 
@@ -418,7 +420,7 @@ Passive status icon 置中於 action-sized 容器,hover 時 active action 填滿
 - **ProgressBar 整合(進度 context 帶檔名)**:消費的 `<ProgressBar>` 自帶 `role="progressbar"` + `aria-valuenow` / `aria-valuemax`(Radix Progress primitive 提供),本元件再傳 `aria-label={檔名 上傳進度}` 作 context;keyboard 不需 focus progress bar(被動指示器,非互動元素)。
 - **Action button labels**:Download / retry / remove 等 inline action 必傳 `aria-label`(中文 / consumer locale)— 「下載 report.pdf」/「重試上傳」/「移除附件」,單純「下載」/「刪除」缺檔名 context SR user 無法區分多 row。
 - **Status icon hover-swap a11y**:hover-swap 不改變 SR 語意 — passive status icon `aria-hidden`,active action button 自帶 `aria-label`,避免 SR user 收到視覺 swap 噪音。
-- **Row primary action 鍵盤可達且不 nested-interactive**:傳 `onClick` 時，row 保持非互動容器並保留整列 pointer hit area；另渲染與 trailing actions 同層的透明 full-row native button（pointer-events none，只承接 Tab / Enter / Space），focus-visible 由 row 外框顯示。`actionAriaLabel` 預設「開啟 {name}」且可由 consumer 覆寫。Primary button 與下載／重試／移除皆為 sibling，禁止把 row 本身改成 `role="button"` 包住互動後代。
+- **Row primary action 鍵盤可達且不 nested-interactive**:傳 `onClick` 時，row 保持非互動容器並保留整列 pointer hit area；另渲染與 trailing actions 同層的透明 full-row native button（pointer-events none，只承接 Tab / Enter / Space），focus-visible 的框畫在 row 上(往內畫的內描邊;form 的 compact 列有 `status` 時畫在 row 的 `::before` 框圖層、進度條那段挖空,見「焦點框 × 貼著列底的進度條」)。**為什麼是內描邊,理由是結構性的**:拿到焦點的是那顆 `opacity-0` 的透明整列 button,它自己畫不出框,所以指示器改畫在 row 上 —— 這正是 `ds-canonical/references/focus-canonical.md` 認可的「指示器畫在別的元素上,而且必須指得出承擔者」形狀,承擔者就是 row。而全域外描邊只作用在「被聚焦的那個元素」身上,套不到非焦點的 row;能掛在 row 上的只有 `focus-ring-inset` 與填色專用的 `focus-ring-inset-emphasis`,row 不是主色填色 → `focus-ring-inset`。**不是**因為四周淨空(表單的列間 4–8px;上傳管理器的列 2026-09-25 起鋪滿面板、列間 0 —— 兩種幾何都一樣用內描邊),**也不是**因為捲動容器會裁切(捲動與否明文不進判準)。幾何 SSOT = `ds-canonical/references/focus-canonical.md`「框怎麼畫」。`actionAriaLabel` 預設「開啟 {name}」且可由 consumer 覆寫。Primary button 與下載／重試／移除皆為 sibling，禁止把 row 本身改成 `role="button"` 包住互動後代。
 - **status / error 不額外加 row ARIA**:`status="uploading"` / `status="error"` 不在 row 上加 `aria-busy` / `role="status"` / `aria-live`;狀態由 progress bar 的 `role="progressbar"` 與 description 文字本身傳達。若 consumer 需要上傳完成 / 失敗的即時 announce,由外層上傳流程容器(FileUpload)統一管理 live region,避免每列各自宣告造成 SR 噪音。
 
 ---
@@ -449,7 +451,7 @@ 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」)。
+**常見誤解**:FileItem 一律有 / 一律沒有滑過底色 → 都不對,有 `onClick`(點了會有反應)才有(見「滑過」段);status 會染整 row 底色 → 只升階 progress bar / status icon / description(見「Inspector 與矩陣的教學分工」);`surface` 影響進度條 → 進度條只看 `status`(見「可下載狀態 canonical」)。
 
 ---
 
@@ -467,7 +469,7 @@ Passive status icon 置中於 action-sized 容器,hover 時 active action 填滿
 
 FileItem 決策維度是 `mode`(compact / rich)× `status`(uploading / completed / error / static)。anatomy 同時提供 `Inspector`(右側 Controls 即時切 `mode` / `status` / `progress` / `description` 試玩單值)與 `ColorMatrix` / `SizeMatrix` / `StateBehavior` 結構矩陣——兩者分工:Inspector 給「單一組合長怎樣」的即時試玩,矩陣給「跨 status 並排比對」的 side-by-side 決策。
 
-ColorMatrix 已建:展示 status × 元素(filename / description / progress bar / status icon)色彩矩陣,明示 status 只驅動 **progress bar + status icon + description** 升階,**不染容器背景**(避免整 row 轉紅蓋過其他 metadata)。容器本身無 hover-bg / selected / disabled state——FileItem 三型態皆 permanent-anchored,反向於 MenuItem / DataTable flush row 的 hover-bg primitive(詳「Hover 行為 canonical」段),且 interface 無 `disabled` prop。
+ColorMatrix 已建:展示 status × 元素(filename / description / progress bar / status icon)色彩矩陣,明示 status 只驅動 **progress bar + status icon + description** 升階,**不染容器背景**(避免整 row 轉紅蓋過其他 metadata)。容器本身沒有 selected / disabled state(interface 無 `disabled` prop);滑過底色只在有 `onClick` 時出現,由 `StateBehavior` 示範(詳「滑過」段)。
 
 ## 與 shadcn Attachment 的分界(2026-07-07 codify,目錄新增元件謂詞 anchor)
 

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

@@ -10,11 +10,12 @@ import { FileViewer, type FileInfo } from '@/design-system/components/FileViewer
 import { SurfaceHeader, SurfaceBody, COMPACT_HEADER_SLOT } from '@/design-system/patterns/overlay-surface/overlay-surface'
 import { PopoverTitle } from '@/design-system/components/Popover/popover'
 
-// 錯誤 description 範例(含 clickable "View log"):consumer 自由 ReactNode,通常用底線 link 表 clickable
+// 錯誤 description 範例(含 clickable "View log"):consumer 自由 ReactNode。
+// 連結沿用錯誤訊息的紅 + 底線、滑過不換色(user 2026-09-26 選「乙 紅字 + 底線，滑過不變」;file-item.spec.md「Description ReactNode 可含 clickable 元素」)
 const errorDescWithLog = (
   <>
     There&rsquo;s something wrong.{' '}
-    <a href="#" className="underline hover:text-error-hover" onClick={(e) => e.preventDefault()}>
+    <a href="#" className="underline" onClick={(e) => e.preventDefault()}>
       View log
     </a>
   </>
@@ -38,7 +39,8 @@ const keyboardOpen = fn()
 // **Row action 絕對值 cap = ≤ 24px,不隨 row tier 放大**。rich + compact 統一用
 // Button size="xs" iconOnly variant="text"(24 固定,≤ cap):
 // compact row 透過 FileItem 內部 suffix wrapper `[&>[data-unbounded]]:my-[calc((1lh-var(--field-height-xs))/2)]`
-// trick 讓 Button(24)layout footprint 收斂到 1lh(~18px)不撐高 row,觸控範圍仍 24。
+// trick 讓 Button(24)layout footprint 收斂到 1lh(~18px)不撐高 row,視覺與命中區仍 24
+// (命中 ≡ 可視,見 ds-canonical/references/hit-area-canonical.md;2026-09-24 把原文的「觸控範圍」正名為命中區)。
 // Trash/Delete 非 dismiss 語意(dismiss 嚴格 = X close overlay),不套 `dismiss` prop——
 // Button variant="text" 本來就 fg-muted,視覺已弱化(兩 mode 同)。
 // 詳 item-anatomy.spec.md「Predicate」+「Row action 絕對值 cap」
@@ -70,6 +72,15 @@ export const Rich = {
     action.focus()
     await userEvent.keyboard('{Enter}')
     await expect(keyboardOpen).toHaveBeenCalledTimes(1)
+
+    // 點同一列 trailing action 的刪除鈕:只該觸發刪除,**不得**連帶觸發整列 onClick。
+    // 2026-09-24 補。先前這支 play 只驗了鍵盤 Enter 那一條,於是「點刪除連帶把檔案開起來」
+    // 在我們自己的示範裡一路沒人看見 —— 那個洞不是沒人踩到,是**沒有人在量**。
+    // `action` 是覆蓋整列的隱形鈕,它的 parentElement 就是列本身;用它把搜尋範圍縮到同一列,
+    // 才不會抓到別列的刪除鈕(三列都有一顆)。
+    const row = action.parentElement as HTMLElement
+    await userEvent.click(within(row).getByRole('button', { name: '刪除' }))
+    await expect(keyboardOpen).toHaveBeenCalledTimes(1)
   },
 }
 
@@ -93,7 +104,8 @@ export const HoverSwap = {
     <div className="flex flex-col max-w-md gap-4">
       <div>
         <div className="text-caption text-fg-muted mb-2">
-          ↓ 游標移入任一 row:completed 綠 ✓ 變 Download ↓,error 紅 ✗ 變 Retry ⟲
+          ↓ 游標移入任一 row:completed 綠 ✓ 變 Download ↓,error 紅 ✗ 變 Retry ⟲。
+          這幾列沒有傳 onClick(點列本身沒反應),所以整列不上滑過底色,只有換上的那顆鈕有自己的滑過色(待辦總帳 B12)
         </div>
         {/* Rich border card list:無外框 + `gap-2`(item-anatomy「連續 item 貼邊合法性」) */}
         <div className="flex flex-col gap-2">
@@ -101,7 +113,7 @@ export const HoverSwap = {
             description="Uploaded to URL" thumbnailSrc="https://i.pravatar.cc/80?u=xls"
             onDownload={noop} actions={deleteBtn} />
           <FileItem mode="rich" name="合約草案 v3.pdf" status="error"
-            description="There's something wrong. View log"
+            description={errorDescWithLog}
             thumbnailSrc="https://i.pravatar.cc/80?u=pdf"
             onRetry={noop} actions={deleteBtn} />
         </div>
@@ -115,7 +127,7 @@ export const HoverSwap = {
           <FileItem mode="compact" name="data-2024-q1.csv" status="completed"
             onDownload={noop} actions={deleteBtnXs} />
           <FileItem mode="compact" name="backup-failed.json" status="error"
-            description={<>Network timeout. <a href="#" className="underline hover:text-error-hover" onClick={(e) => e.preventDefault()}>View log</a></>}
+            description={<>Network timeout. <a href="#" className="underline" onClick={(e) => e.preventDefault()}>View log</a></>}
             onRetry={noop} actions={deleteBtnXs} />
         </div>
       </div>
@@ -225,7 +237,7 @@ export const CompactMixed = {
       <FileItem mode="compact" name="圖片草稿.png" status="uploading" progress={40} actions={deleteBtnXs} />
       <FileItem mode="compact" name="回覆範本.docx" onClick={noop} actions={deleteBtnXs} />
       <FileItem mode="compact" name="backup-failed.json" status="error"
-        description={<>Network timeout. <a href="#" className="underline hover:text-error-hover" onClick={(e) => e.preventDefault()}>View log</a></>}
+        description={<>Network timeout. <a href="#" className="underline" onClick={(e) => e.preventDefault()}>View log</a></>}
         onRetry={noop} actions={deleteBtnXs} />
       <FileItem mode="compact" name="附件封面.pdf" onClick={noop} actions={deleteBtnXs} />
     </div>
@@ -242,14 +254,17 @@ export const CompactMixed = {
  * 沒傳就退回 passive 是給既有 consumer 的相容行為,不是這裡要示範的東西。
  * 寫成共用常數而不是「兩邊都記得傳」:**能力集合從此不可能只在其中一則出現**。
  */
-const UPLOAD_MANAGER_COMPLETED = { status: 'completed', onDownload: noop } as const
+// 完成的檔案可以點開(onClick),上傳中 / 失敗的不行 —— 同一個面板裡兩種列並存,示範「點了會有反應的列才有滑過底色」
+// (2026-09-25 待辦總帳 B12:user「要點了會有反應的才加…」)。上傳中還不能開是真實情境,不是示範取巧。
+const UPLOAD_MANAGER_COMPLETED = { status: 'completed', onDownload: noop, onClick: noop } as const
 const UPLOAD_MANAGER_ERROR = { status: 'error', onRetry: noop } as const
 
-// surface="upload-manager":Google Drive / Dropbox 上傳管理面板。面板組合 canonical(2026-06-03 圖五/圖一 user 校準):
-//   - 左右一律 loose(16px,對齊 header);上下目標「邊緣→item ink」= tight(12px),通則 container 該側 = 12 − item 該側留白
-//   - rich item 上下留白 0 → py-tight(12/12 對稱);compact 上留 8(item py)→ pt-1(4),下進度條貼底留 0 → pb-tight(12)
-//   - 列間 gap 反映密度:rich = tight(12px,卡片+48 縮圖)/ compact = 4px(密集文字列)
-//   - rich item 拿掉全部 padding(px-0 py-0,列高靠 avatar 48);左右交給面板,避免雙重 L/R。對比 surface=form 的 border card。
+// surface="upload-manager":Google Drive / Dropbox 上傳管理面板。面板組合 canonical(file-item.spec.md「upload-manager 浮層面板 composition」):
+//   - 2026-09-25 待辦總帳 B12 推翻 06-03 的「左右交給面板」:可點的列滑過底色要鋪到面板左右邊 → 列自帶左右 loose(16px,
+//     文字 x 與 06-03 相同、仍對齊 header 標題),面板 body 左右 0(判準 = overlay-surface.spec.md「誰負責左右 gutter」)
+//   - 上下目標不變:「邊緣→item ink」「ink→ink」= tight(12px)。兩 mode 的列上下各自帶 tight/2 → body 上下也給 tight/2、列間 gap 0
+//     (06-03 compact 的 !pt-1 上下不對稱隨之取消);滑過底色上下各留 tight/2,不貼縮圖、不貼進度條
+//   - 只有完成的列有 onClick(UPLOAD_MANAGER_COMPLETED),上傳中 / 失敗的列點了沒反應 → 不上滑過底色
 export const UploadManagerSurface = {
   name: '上傳管理器 · 豐富(無邊框)',
   render: () => (
@@ -260,12 +275,12 @@ export const UploadManagerSurface = {
         <div className="flex-1 min-w-0"><PopoverTitle>正在上傳 3 個項目</PopoverTitle></div>
         <Button iconOnly variant="text" size="sm" startIcon={ChevronDown} aria-label="收合" onClick={noop} />
       </SurfaceHeader>
-      {/* body 消費 overlay-surface SurfaceBody(非手刻;含 px-loose py-tight + flex-1 scroll 鏈)。
-          rich:py-tight(SurfaceBody 預設)+ gap-tight = 垂直對稱 12px */}
-      <SurfaceBody className="flex flex-col gap-[var(--layout-space-tight)]">
+      {/* body 消費 overlay-surface SurfaceBody(非手刻;flex-1 scroll 鏈照用)。左右 0、上下 tight/2、列間 0:
+          gutter 與另一半上下由列自己帶(B12,見上方註解);縮圖↔縮圖、邊緣↔縮圖仍是 12px */}
+      <SurfaceBody className="flex flex-col gap-0 !px-0 !py-[calc(var(--layout-space-tight)/2)]">
         <FileItem mode="rich" surface="upload-manager" name="Alan Profile.png" status="uploading" progress={40}
           description="5.7 MB of 7.5 MB" thumbnailSrc="https://i.pravatar.cc/80?u=alan" actions={deleteBtn} />
-        <FileItem mode="rich" surface="upload-manager" name="Q1 營收報表.xlsx" {...UPLOAD_MANAGER_COMPLETED}
+        <FileItem mode="rich" surface="upload-manager" name="Q1 營收報表.xlsx" {...UPLOAD_MANAGER_COMPLETED} data-visual-hover-target
           description="2.4 MB" thumbnailSrc="https://i.pravatar.cc/80?u=xls" actions={deleteBtn} />
         <FileItem mode="rich" surface="upload-manager" name="合約草案 v3.pdf" {...UPLOAD_MANAGER_ERROR}
           description={errorDescWithLog} thumbnailSrc="https://i.pravatar.cc/80?u=pdf" actions={deleteBtn} />
@@ -274,9 +289,9 @@ export const UploadManagerSurface = {
   ),
 }
 
-// surface="upload-manager" 的 compact list:左右 loose 16(同 rich,對齊 header);上下「不對稱」=「12 − item 該側留白」:
-// top !pt-1=4(item 自帶 py-2 的 8 + 4 = 12),bottom 12(進度條貼底、item 下方無留白);gap 只 4px(密集列)。
-// 對比 rich panel(item py-0 → 上下對稱 12 / gap 12),demo 兩 mode 密度差異。
+// surface="upload-manager" 的 compact list:body 寫法與 rich 相同(左右 0、上下 tight/2、列間 0),差別只在列本身 ——
+// compact 列上 tight/2、下 tight/2 + 8(文字↔bar 6 + bar 2),bar 離列底 tight/2(file-item.tsx「compact 內距」段)。
+// 對比 rich panel(列高 = 縮圖 48 + tight),demo 兩 mode 密度差異。
 export const UploadManagerCompactSurface = {
   name: '上傳管理器 · 緊湊(無邊框)',
   render: () => (
@@ -286,16 +301,14 @@ export const UploadManagerCompactSurface = {
         <div className="flex-1 min-w-0"><PopoverTitle>同步 3 個檔案</PopoverTitle></div>
         <Button iconOnly variant="text" size="sm" startIcon={ChevronDown} aria-label="收合" onClick={noop} />
       </SurfaceHeader>
-      {/* body 消費 SurfaceBody(px-loose + pb-tight 自 SSOT);compact 只 override top:`!pt-1`(4px,
-          item 文字上方自帶 8px → 4+8=12;bottom 留 SurfaceBody 預設 py-tight=12,因進度條貼底無留白)。
-          用 `!`(important)而非 `pt-1`:twMerge 不 strip 基底 py-[tight] → 非 important 時 top 12/4 競爭看
-          stylesheet 生成順序(非決定性);`!` 強制 top=4 決定性勝(對齊 List-as-region `!px-0` override 慣例)。
-          列間 gap-1(4px,密集列)。 */}
-      <SurfaceBody className="flex flex-col gap-1 !pt-1">
+      {/* body 同 rich 面板:左右 0、上下 tight/2、列間 0(B12)。用 `!` 沿用 List-as-region `!px-0` 慣例,
+          覆寫勝負不依賴 twMerge 分組與 stylesheet 生成順序。 */}
+      <SurfaceBody className="flex flex-col gap-0 !px-0 !py-[calc(var(--layout-space-tight)/2)]">
+        {/* 上傳中的列不能開(沒有 onClick)→ 不上滑過底色;與 rich 面板同一組能力(B12) */}
         <FileItem mode="compact" surface="upload-manager" name="季度報告.docx" status="uploading" progress={60}
-          onClick={noop} actions={deleteBtn} />
+          actions={deleteBtn} />
         <FileItem mode="compact" surface="upload-manager" name="客戶名單.csv" {...UPLOAD_MANAGER_COMPLETED}
-          onClick={noop} actions={deleteBtn} />
+          actions={deleteBtn} />
         <FileItem mode="compact" surface="upload-manager" name="封面.png" {...UPLOAD_MANAGER_ERROR}
           description={errorDescWithLog} actions={deleteBtn} />
       </SurfaceBody>