@qijenchen/design-system 0.1.0-beta.13 → 0.1.0-beta.131

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

@@ -0,0 +1,346 @@
+// @anatomy-exempt: anatomy specs / token 對照表格用 raw <table>,非業務資料表。業務資料表才用 <DataTable>。
+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 { H3, Desc, Td, Th, Swatch } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
+
+const meta: Meta<typeof FileItem> = {
+  title: 'Design System/Components/FileItem/設計規格',
+  component: FileItem,
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj<typeof FileItem>
+
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>Anatomy</H3>
+        <Desc>FileItem 是組合元件——Prefix(Avatar 或 Paperclip)+ Content(name + description + 可選 progress bar)+ 可選 Actions suffix。基於 item-layout pattern。</Desc>
+        <div className="flex flex-col gap-2 max-w-lg">
+          <FileItem
+            name="Q1-report.pdf"
+            description="2.4 MB · 上傳中 75%"
+            status="uploading"
+            progress={75}
+            mode="rich"
+          />
+          <FileItem
+            name="beach-photo.jpg"
+            description="4.8 MB"
+            mode="rich"
+            thumbnailSrc="https://i.pravatar.cc/112?img=3"
+          />
+        </div>
+      </div>
+
+      <div>
+        <H3>Props 速查</H3>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Prop</Th><Th>Type</Th><Th>Default</Th><Th>說明</Th></tr></thead>
+            <tbody>
+              {[
+                ['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」表'],
+                ['status', "'uploading' | 'completed' | 'error'", '—', '上傳狀態(不傳=已上傳靜態)'],
+                ['progress', 'number', '0', '上傳進度 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)'],
+                ['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)'],
+              ].map(([p, t, d, desc]) => (
+                <tr key={p}><Td mono>{p}</Td><Td mono>{t}</Td><Td mono>{d}</Td><Td>{desc}</Td></tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const Inspector: Story = {
+  name: '元件檢閱器',
+  parameters: {
+    docs: { description: { story: '右側 Controls 切 props 即時 render,取代 Figma inspect。調整 `mode` / `status` / `progress` 看 compact vs rich 佈局與狀態 icon/進度條變化。' } },
+  },
+  args: {
+    name: 'Q1 行銷報告.pdf',
+    mode: 'rich',
+    status: 'uploading',
+    progress: 60,
+    description: '2.4 MB · 上傳中',
+    thumbnailSrc: 'https://i.pravatar.cc/112?img=3',
+  },
+  argTypes: {
+    name: { control: 'text' },
+    mode: { control: 'radio', options: ['compact', 'rich'] },
+    status: { control: 'radio', options: [undefined, 'uploading', 'completed', 'error'] },
+    progress: { control: { type: 'range', min: 0, max: 100, step: 1 } },
+    description: { control: 'text' },
+    thumbnailSrc: { control: 'text' },
+  },
+  render: (args) => (
+    <div className="max-w-lg">
+      <FileItem {...args} />
+    </div>
+  ),
+}
+
+export const ColorMatrix: Story = {
+  name: '色彩對照表',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <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)。
+          Status 才驅動色彩:progress bar 色(inProgress / success / error)+ status icon 色(check / X)+ description 色(error 時升階)。
+        </Desc>
+        <div className="overflow-x-auto mb-4">
+          <table className="text-caption border-collapse min-w-[720px]">
+            <thead>
+              <tr>
+                <Th>Status</Th>
+                <Th>Filename text</Th>
+                <Th>Description text</Th>
+                <Th>Progress bar fill</Th>
+                <Th>Status icon</Th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr>
+                <Td mono>無 status(已上傳)</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>—(無 bar)</Td>
+                <Td>—</Td>
+              </tr>
+              <tr>
+                <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="--info" size="sm" /><span className="font-mono">--info(inProgress)</span></span></Td>
+                <Td>—(只顯示 bar)</Td>
+              </tr>
+              <tr>
+                <Td mono>completed</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="--success" size="sm" /><span className="font-mono">--success</span></span></Td>
+                <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--success" size="sm" /><span className="font-mono">CircleCheck text-success</span></span></Td>
+              </tr>
+              <tr>
+                <Td mono>error</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="--error-text" size="sm" /><span className="font-mono">--error-text(升階)</span></span></Td>
+                <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--error" size="sm" /><span className="font-mono">--error</span></span></Td>
+                <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--error" size="sm" /><span className="font-mono">XCircle text-error</span></span></Td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <div>
+        <H3>Container background(per mode,無 hover-bg)</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」。
+        </Desc>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead>
+              <tr><Th>Mode / State</Th><Th>Background</Th><Th>Rationale</Th></tr>
+            </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>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>error</Td><Td><span className="font-mono">容器不變</span></Td><Td>只升階 description / bar / icon,不染容器——避免整 row 轉紅蓋過其他 metadata</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const ModeMatrix: Story = {
+  name: '模式 對照（緊湊 vs 豐富）',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>rich — Avatar 48px square 在左</H3>
+        <Desc>掃描模式(text-body 14px + leading-compact 1.3;兩 mode 統一 scanning),資訊容量較高。適合圖片 / 文件 / 需要縮圖的場景。</Desc>
+        <div className="flex flex-col gap-2 max-w-lg">
+          <FileItem name="Q1-report.pdf" description="2.4 MB · 已上傳" mode="rich" />
+          <FileItem name="photo.jpg" description="4.8 MB" mode="rich" thumbnailSrc="https://i.pravatar.cc/112?img=3" />
+          <FileItem name="contract.pdf" description="1.2 MB · 上傳中 45%" status="uploading" progress={45} mode="rich" />
+        </div>
+      </div>
+
+      <div>
+        <H3>compact（預設）— Paperclip 16px icon 在左</H3>
+        <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} />
+          <FileItem name="products.xlsx" mode="compact" status="error" description="檔案格式不支援" />
+          <FileItem name="logs.txt" mode="compact" status="completed" progress={100} />
+        </div>
+      </div>
+
+      <div>
+        <H3>Mode 對照</H3>
+        <div className="overflow-x-auto">
+          <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-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>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const SizeMatrix: Story = {
+  name: '尺寸對照表',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>Mode 決定 density,不走 size prop</H3>
+        <Desc>
+          FileItem 沒有 size prop——兩種 mode(compact / rich)已經覆蓋所有密度需求。對齊
+          Dropbox / Google Drive / Linear 的檔案清單慣例:compact 是系統列表預設,rich 是 media-heavy
+          場景(照片、需要縮圖的場景)。Size tier 的區別在 mode 上已足夠表達。
+        </Desc>
+        <div className="overflow-x-auto mb-4">
+          <table className="text-caption border-collapse">
+            <thead>
+              <tr>
+                <Th>Dimension</Th>
+                <Th>compact(預設)</Th>
+                <Th>rich</Th>
+              </tr>
+            </thead>
+            <tbody>
+              <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>
+              <tr><Td>Progress bar</Td><Td mono>絕對定位 2px 在底</Td><Td mono>inline 4px,bar 底部對齊 avatar</Td></tr>
+              <tr><Td>Actions</Td><Td>右側 Button xs iconOnly(24 固定;靠列內 wrapper trick 不撐高列)</Td><Td>右側 Button xs iconOnly(24 固定,列內操作 ≤ 24 上限;多操作橫排)</Td></tr>
+              <tr><Td>使用場景</Td><Td>批次上傳、log 列表、CSV/JSON</Td><Td>圖片上傳、文件附件、需預覽的檔案</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <div>
+        <H3>同一批 5 個檔案:compact vs rich</H3>
+        <Desc>同樣 5 個檔案,兩種 mode 呈現的視覺密度差異——compact 可一目 5 行掃完,rich 需滾動且視覺重量高。</Desc>
+        <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-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} />
+              <FileItem name="logs.txt" mode="compact" status="error" description="檔案格式不支援" />
+              <FileItem name="invoice-2026.pdf" mode="compact" status="completed" progress={100} />
+            </div>
+          </div>
+          <div>
+            <div className="text-caption text-fg-muted mb-2 font-mono">mode="rich"</div>
+            <div className="flex flex-col gap-2 max-w-sm">
+              <FileItem name="Q1-report.pdf" description="2.4 MB · 已上傳" mode="rich" />
+              <FileItem name="users.csv" description="120 KB · 已上傳" mode="rich" />
+              <FileItem name="products.xlsx" description="1.2 MB · 上傳中 62%" mode="rich" status="uploading" progress={62} />
+              <FileItem name="logs.txt" description="檔案格式不支援" mode="rich" status="error" />
+              <FileItem name="invoice-2026.pdf" description="880 KB · 已上傳" mode="rich" />
+            </div>
+          </div>
+        </div>
+        <p className="text-footnote text-fg-muted mt-3">
+          選 mode 的 test:檔案是「資料 row」→ compact;是「內容物件」(圖片 / 附件)→ rich。
+        </p>
+      </div>
+    </div>
+  ),
+}
+
+export const StateBehavior: Story = {
+  name: '狀態行為',
+  render: () => (
+    <div className="flex flex-col gap-4 max-w-lg">
+      <div>
+        <H3>所有狀態對照</H3>
+        <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="下載" />} />
+          <FileItem name="error.pdf" description="網路中斷,請重試" status="error" mode="rich" actions={<div className="flex gap-1"><Button variant="text" size="xs" iconOnly startIcon={RotateCw} aria-label="重試" /><Button variant="text" size="xs" iconOnly startIcon={X} aria-label="移除" /></div>} />
+          <FileItem name="static.pdf" description="已儲存 · 1.2 MB" mode="rich" onClick={() => {}} actions={<Button variant="text" size="xs" iconOnly startIcon={Download} aria-label="下載" />} />
+        </div>
+      </div>
+
+      <div>
+        <H3>Progress bar 色彩</H3>
+        <div className="overflow-x-auto">
+          <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-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>
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+// ── Accessibility ─────────────────────────────────────────────────────────
+// 2026-05-17 ship per audit Dim 13(story-rules.md 6-canonical 含 Accessibility)
+export const Accessibility = {
+  name: '無障礙與鍵盤',
+  render: () => (
+    <div className="max-w-3xl text-body text-fg-secondary">
+      <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
+      <ul className="flex flex-col gap-2 list-disc pl-5">
+        <li>
+          <strong className="text-foreground">進度條有檔名 context</strong>:上傳進度條會自動帶上「檔名 + 上傳進度」的語音標籤,
+          螢幕報讀軟體唸出進度時使用者知道是哪個檔案。進度條本身為被動指示器,不需鍵盤聚焦。
+        </li>
+        <li>
+          <strong className="text-foreground">狀態 icon 換成按鈕時的語音切換</strong>:滑鼠移上整列時,
+          被動的狀態 icon(綠勾 / 紅叉)會淡出換成操作按鈕(下載 / 重試)。被動 icon 對螢幕報讀軟體隱藏,
+          換上的操作按鈕自帶語音標籤,使用者不會聽到視覺切換的雜訊。
+        </li>
+        <li>
+          <strong className="text-foreground">操作按鈕標籤要帶檔名</strong>:下載 / 重試 / 移除等列內操作,
+          consumer 必須傳語音標籤並帶上檔名(例:「下載 report.pdf」「重試上傳」),
+          只寫「下載」「刪除」缺檔名,螢幕報讀使用者無法分辨是哪一列。
+        </li>
+        <li>
+          <strong className="text-foreground">整列不可整塊鍵盤聚焦</strong>:為避免與列內操作按鈕互相干擾(巢狀互動),
+          整列不設成單一可聚焦按鈕;鍵盤使用者直接 Tab 到列內的操作按鈕。滑鼠仍可點擊整列觸發 onClick。
+        </li>
+      </ul>
+    </div>
+  ),
+}

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

@@ -0,0 +1,245 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+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'
+
+const meta: Meta = {
+  title: 'Design System/Components/FileItem/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+const Rule = ({
+  title, note, children,
+}: {
+  title: string; note?: string; children: React.ReactNode
+}) => (
+  <div className="mb-14">
+    <h3 className="text-body font-bold text-foreground mb-1">{title}</h3>
+    {note && <p className="text-caption text-fg-muted mb-5 max-w-[720px] leading-relaxed">{note}</p>}
+    <div className="flex flex-col gap-3 max-w-lg">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p className={`text-footnote leading-normal ${warn ? 'text-error font-medium' : 'text-fg-muted'}`}>{children}</p>
+)
+
+// ── WhenToUse — 何時使用 FileItem ──────────────────────
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / WhenNotToUse(2026-04-26 v3 canonical)
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div className="flex flex-col gap-12">
+      {/* 何時用 — 原 WhenToUse */}
+      <div className="prose prose-sm max-w-prose">
+      <p>適合 FileItem 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          <LinkTo kind="Design System/Components/FileItem/展示" name="豐富樣式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">圖片 / 設計稿上傳 — 需要縮圖預覽(豐富樣式)</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/FileItem/展示" name="緊湊樣式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">CSV / JSON 批次匯入的密集清單(緊湊樣式)</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/FileItem/展示" name="懸停替換"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">上傳完成後滑入整列、狀態 icon 換成下載鈕(懸停替換)</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/FileItem/展示" name="已上傳"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">工單 / 訊息附件的已上傳靜態檔案</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/FileItem/展示" name="緊湊 混合"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">同一批次混合上傳中 / 完成 / 失敗狀態的清單</span></LinkTo>
+        </li>
+      </ul>
+      <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見 <code>Vs*Rule</code> stories)。</p>
+    </div>
+
+      {/* 何時不用 / 替代元件 — 原 WhenNotToUse */}
+      <div>
+      <Rule
+        title="❌ 不用 FileItem 做純連結展示（已上傳檔案）"
+        note="FileItem 承載上傳狀態、進度、錯誤。靜態檔名列表改用 LinkInput 或純 <a> 連結。Google Drive 的「最近開啟」是檔案卡片，不用 FileItem"
+      >
+        <Label warn>靜態檔名 → LinkInput / &lt;a&gt;，FileItem 只用上傳流程</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 不用 FileItem 做下載進度"
+        note="FileItem 專為上傳設計。下載進度改用自訂 progress component 或瀏覽器原生下載 UI。Figma 的資源下載不用 FileItem"
+      >
+        <Label warn>下載進度 → 自訂或瀏覽器原生，FileItem 只管上傳</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 不用 FileItem 做相片 / 影片 gallery"
+        note="Gallery 需要 grid 佈局、大圖縮圖。FileItem 是清單單行。改用 grid / Carousel。Instagram 的相簿是 grid，不是 FileItem"
+      >
+        <Label warn>Gallery → grid / Carousel，FileItem 是上傳清單</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 不用 FileItem 表達資料夾階層"
+        note="FileItem 是平面列表。資料夾樹改用 TreeView。OneDrive 的資料夾結構用 TreeView，檔案列表用 FileItem"
+      >
+        <Label warn>資料夾樹 → TreeView，FileItem 是平面清單</Label>
+      </Rule>
+    </div>
+    </div>
+  ),
+}
+
+export const ModeRule: Story = {
+  name: '模式 選擇（緊湊 vs 豐富）',
+  render: () => (
+    <div>
+      <Rule
+        title="先問：使用者靠縮圖辨識，還是靠檔名快速掃視？"
+        note="mode 是資訊策略，不是大小 variant。只在縮圖會改變判斷時選 rich；其餘批次上傳與附件清單預設 compact，讀者才能用一致節奏掃視。"
+      >
+        <div className="grid gap-3 sm:grid-cols-2">
+          <div className="rounded-md border border-divider bg-surface p-4">
+            <p className="text-body font-medium text-foreground">rich：縮圖會幫助辨識</p>
+            <p className="mt-1 text-caption text-fg-muted">設計稿、照片或文件預覽；圖像內容比副檔名更能區分檔案。</p>
+          </div>
+          <div className="rounded-md border border-divider bg-surface p-4">
+            <p className="text-body font-medium text-foreground">compact：檔名與狀態是主要訊息</p>
+            <p className="mt-1 text-caption text-fg-muted">批次匯入、日誌或工單附件；使用者要快速掃描多筆進度與錯誤。</p>
+          </div>
+        </div>
+        <Label>完整的視覺與 token 對照請看「設計規格 / 模式對照」；這裡只負責選擇判斷。</Label>
+      </Rule>
+
+      <Rule
+        title="同一清單不混用 rich 與 compact"
+        note="兩種 mode 有不同列高與視覺錨點；混用會打斷掃視節奏，也讓使用者誤以為資料狀態不同。上傳中與已儲存附件可以共存，但應在同一 mode 內用 status 區分。"
+      >
+        <Label>先以整個工作流的閱讀任務選 mode，再用 status 表達每筆檔案的進度。</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const StatusProgressRule: Story = {
+  name: '上傳狀態與進度視覺',
+  render: () => (
+    <div>
+      <Rule
+        title="uploading — progress bar info 色 + 百分比 description"
+        note="上傳中清楚展示進度,讓使用者知道「多久能好」而不是只看到一個等待狀態"
+      >
+        <FileItem
+          name="large-backup.zip"
+          description="128 MB · 上傳中 42%"
+          status="uploading"
+          progress={42}
+          mode="rich"
+        />
+      </Rule>
+
+      <Rule
+        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"
+        />
+      </Rule>
+
+      <Rule
+        title="error — 錯誤 icon + error 訊息 description + 可重試"
+        note="失敗必須清楚告知原因——不只顯示「失敗」,要有具體錯誤訊息讓使用者知道怎麼修。compact 模式下 error 會強制顯示 description"
+      >
+        <FileItem
+          name="broken-file.pdf"
+          description="檔案損毀,請重新上傳"
+          status="error"
+          mode="rich"
+          actions={<Button variant="text" size="xs" iconOnly startIcon={RotateCw} aria-label="重試" />}
+        />
+      </Rule>
+
+      <Rule
+        title="無 status — 已上傳的靜態檔案"
+        note="上傳已完成且已保存,不需要進度 / 狀態標示。可傳 onClick 讓整個 item 變可點擊下載"
+      >
+        <FileItem
+          name="final-contract.pdf"
+          description="已簽署 · 2.1 MB"
+          mode="rich"
+          onClick={() => {}}
+          actions={<Button variant="text" size="xs" iconOnly startIcon={Download} aria-label="下載" />}
+        />
+      </Rule>
+    </div>
+  ),
+}
+
+export const ActionsRule: Story = {
+  name: '動作 使用',
+  render: () => (
+    <div>
+      <Rule
+        title="Uploading 時：Cancel action"
+        note="上傳進行中使用者應該可以取消。用 X icon 表達「取消上傳」"
+      >
+        <FileItem
+          name="massive-video.mov"
+          description="450 MB · 上傳中 12%"
+          status="uploading"
+          progress={12}
+          mode="rich"
+          actions={<Button variant="text" size="xs" iconOnly startIcon={X} aria-label="取消上傳" />}
+        />
+      </Rule>
+
+      <Rule
+        title="Error 時：Retry + Remove"
+        note="失敗時使用者需要兩個選項——重試(可能只是暫時網路問題)或移除(放棄這個檔案)"
+      >
+        <FileItem
+          name="failed-upload.pdf"
+          description="網路中斷,請重試"
+          status="error"
+          mode="rich"
+          actions={
+            <div className="flex gap-1">
+              <Button variant="text" size="xs" iconOnly startIcon={RotateCw} aria-label="重試" />
+              <Button variant="text" size="xs" iconOnly startIcon={X} aria-label="移除" />
+            </div>
+          }
+        />
+      </Rule>
+
+      <Rule
+        title="Completed 時：Download / View"
+        note="完成後使用者可以下載或查看。action 不必是 dismiss,重點在後續可能的動作"
+      >
+        <FileItem
+          name="report-final.pdf"
+          description="上傳完成 · 3.2 MB"
+          status="completed"
+          mode="rich"
+          actions={<Button variant="text" size="xs" iconOnly startIcon={Download} aria-label="下載" />}
+        />
+      </Rule>
+
+      <Rule
+        title="❌ 重要 action 只靠 hover 才出現"
+        note="「移除」「取消」這類影響資料的 action 必須 persistent visible,不能 hover 才顯示。觸控裝置無法 hover,會錯過關鍵動作"
+      >
+        <Label warn>hover-only actions 只適合純便利功能(如「複製連結」),關鍵動作永遠 visible</Label>
+      </Rule>
+    </div>
+  ),
+}