@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

package/src/components/Empty/empty.principles.stories.tsx

@@ -0,0 +1,314 @@
+// @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.
+// @principles-rationale: Merged WhenToUse + WhenNotToUse + NotLoadingNotErrorRule
+// into a single `UsageGuidance` story (3 sections — 何時用 / 何時不用 + 替代 / vs 近親)
+// per 2026-04-26 user mandate. NextActionRule / StructureRule / CopyRule kept as
+// separate principles.
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { SearchX, FolderOpen, Inbox, WifiOff } from 'lucide-react'
+import { Empty } from './empty'
+import { Button } from '@/design-system/components/Button/button'
+import { Alert } from '@/design-system/components/Alert/alert'
+import { Skeleton } from '@/design-system/components/Skeleton/skeleton'
+
+const meta: Meta = {
+  title: 'Design System/Components/Empty/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <section className="mb-12">
+    <h2 className="text-body-lg font-semibold text-foreground mb-3 pb-1 border-b border-divider">{title}</h2>
+    <div>{children}</div>
+  </section>
+)
+
+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-4">{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>
+)
+
+const Frame = ({ children, className }: { children: React.ReactNode; className?: string }) => (
+  <div className={`border border-border rounded-lg p-8 max-w-md ${className ?? ''}`}>{children}</div>
+)
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div>
+      <Section title="何時用">
+        <div className="prose prose-sm max-w-prose">
+          <p>適合 Empty 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+          <ul className="space-y-1">
+            <li>
+              <LinkTo kind="Design System/Components/Empty/展示" name="搜尋無結果"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">搜尋無結果</span></LinkTo>
+            </li>
+            <li>
+              <LinkTo kind="Design System/Components/Empty/展示" 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「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方「vs 近親」)。</p>
+        </div>
+      </Section>
+
+      <Section title="何時不用 + 替代">
+        <Rule
+          title="❌ 不用 Empty 做載入中狀態"
+          note="Empty 是「確定沒有」。載入中 → Skeleton / CircularProgress。Notion 首次開啟資料庫時先 Skeleton,載完才變 Empty 或有資料"
+        >
+          <Label warn>載入中 → Skeleton / CircularProgress,不是 Empty</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不用 Empty 做錯誤或失敗狀態"
+          note="Empty 是中性提示。錯誤改用 Alert + 重試按鈕。Stripe 付款失敗用 Alert,不用 Empty"
+        >
+          <Frame>
+            <Empty
+              icon={WifiOff}
+              title="沒有資料"
+              description="無法載入"
+              action={<Button variant="secondary">重新載入</Button>}
+            />
+          </Frame>
+          <Label warn>↑ 錯誤用 Empty 傳達不出「這是問題」的緊迫感 → 應改用 Alert variant=error</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不用 Empty 做整頁級 404 / 無權限"
+          note="整頁錯誤需要完整頁面佈局(navigation + hero 錯誤訊息)。Empty 是容器內提示。GitHub 的 404 頁是整頁設計"
+        >
+          <Label warn>整頁 404 → 專屬錯誤頁面設計,Empty 只用容器內</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不用 Empty 表達 disabled 狀態"
+          note="Disabled 是「禁用元件」的視覺,不是「沒內容」的提示。改用禁用該元件本身。Toggle off 的搜尋結果不用 Empty,而是禁用 SearchInput"
+        >
+          <Label warn>禁用 → disable 元件本身,不用 Empty</Label>
+        </Rule>
+      </Section>
+
+      <Section title="vs 近親 — Empty / Skeleton / Alert">
+        <Rule
+          title="Skeleton — 短暫 loading,不是 Empty"
+          note="Empty 代表「已經查過、確定沒有」;loading 是「還沒查完、不確定有沒有」。直接顯示 Empty 會讓使用者以為資料真的沒有,然後一秒後內容跳出來,視覺跳動破壞信任"
+        >
+          <Frame>
+            <div className="flex flex-col gap-3">
+              <Skeleton className="h-5 w-2/3" />
+              <Skeleton className="h-4 w-full" />
+              <Skeleton className="h-4 w-5/6" />
+            </div>
+          </Frame>
+          <Label>↑ 資料還在載入 → Skeleton 保留版面輪廓,不誤導「這裡沒東西」</Label>
+        </Rule>
+
+        <Rule
+          title="Alert — 錯誤 / 失敗,不是 Empty"
+          note="錯誤需要明確說明「發生什麼問題」+「如何解決」,並傳達可處理的語意。Empty 是中性的「暫時沒有」,沒辦法傳達錯誤的嚴重性"
+        >
+          <div className="max-w-md">
+            <Alert
+              variant="error"
+              title="連線中斷,無法載入最新資料"
+              description="請檢查網路連線後重試。你看到的是快取資料。"
+            />
+          </div>
+          <Label>↑ 錯誤用 Alert (variant=error) 明確標示問題 + 解決路徑</Label>
+        </Rule>
+
+        <Rule
+          title="判斷法"
+          note="使用者卡住但確定沒資料 → Empty;還在載入 → Skeleton;發生錯誤需要明確處理 → Alert"
+        >
+          <Frame>
+            <Empty
+              icon={SearchX}
+              title="找不到相符的任務"
+              description="試試其他關鍵字,或調整篩選條件"
+              action={<Button variant="tertiary">清除所有篩選</Button>}
+            />
+          </Frame>
+          <Label>↑ Empty 的代表案例:有結果預期、沒有結果、需要明確下一步</Label>
+        </Rule>
+      </Section>
+    </div>
+  ),
+}
+
+export const NextActionRule: Story = {
+  name: 'Empty 必須提示下一步動作',
+  render: () => (
+    <div>
+      <Rule
+        title="✅ 告訴使用者「接下來可以做什麼」"
+        note="空狀態是使用者卡住的時刻——此時最需要引導。action 不一定要是 primary button,但要讓使用者知道有明確出路(建立、重試、調整過濾)。世界級 SaaS(Jira / Notion / Linear)的空狀態都不是 dead-end"
+      >
+        <Frame>
+          <Empty
+            icon={FolderOpen}
+            title="還沒有任何專案"
+            description="建立第一個專案,開始規劃團隊工作"
+            action={<Button variant="primary">建立專案</Button>}
+          />
+        </Frame>
+        <Label>↑ 「建立專案」是明確下一步,使用者不會卡住</Label>
+      </Rule>
+
+      <Rule
+        title="✅ 搜尋無結果 → 調整篩選的出路"
+        note="搜尋 / 篩選無結果時,使用者卡在「我查不到東西」——action 應是「清除篩選」/「調整關鍵字」等可回退動作,不是建立新資料"
+      >
+        <Frame>
+          <Empty
+            icon={SearchX}
+            title="找不到相符的任務"
+            description="試試其他關鍵字,或調整篩選條件"
+            action={<Button variant="tertiary">清除所有篩選</Button>}
+          />
+        </Frame>
+      </Rule>
+
+      <Rule
+        title="❌ 純提示不給出路 — dead-end 空狀態"
+        note="只告訴使用者「沒資料」但不說接下來能做什麼,使用者卡住。即使是 table 空狀態,也應至少提示如何開始(建立 / 匯入 / 調整)"
+      >
+        <Frame>
+          <Empty icon={Inbox} description="沒有任何資料" />
+        </Frame>
+        <Label warn>
+          ↑ 「沒有資料」後沒有下一步 — 使用者不知道該做什麼
+        </Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const StructureRule: Story = {
+  name: '圖示 + 標題 + 說明 + 動作 結構',
+  render: () => (
+    <div>
+      <Rule
+        title="完整結構 — 越重要的初次引導,slot 越完整"
+        note="icon 快速建立情境、title 說明「這裡是什麼」、description 補充「怎麼用」、action 給下一步。首次引導(onboarding empty)通常需要完整 slot;日常空狀態(filter 無結果)可只有 icon + description"
+      >
+        <Frame>
+          <Empty
+            icon={FolderOpen}
+            title="還沒有任何專案"
+            description="建立第一個專案,邀請團隊成員協作追蹤進度"
+            action={<Button variant="primary">建立專案</Button>}
+          />
+        </Frame>
+      </Rule>
+
+      <Rule
+        title="最多一個 primary action"
+        note="Empty 是單一引導時刻,超過一個 primary 會讓使用者不知道先做什麼。若真的有多個並列動作,用 secondary + tertiary 配對 — 但盡量避免"
+      >
+        <Frame>
+          <Empty
+            icon={FolderOpen}
+            title="開始你的第一個專案"
+            description="從範本快速建立,或自己從零規劃"
+            action={
+              <div className="flex gap-2">
+                <Button variant="tertiary">從範本</Button>
+                <Button variant="primary">從零建立</Button>
+              </div>
+            }
+          />
+        </Frame>
+        <Label>↑ 兩個動作時,主要路徑仍只有一個 primary,次要用 tertiary</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 兩個 primary button 並存"
+        note="兩個 primary → 使用者無法辨識主次 → 決策疲勞"
+      >
+        <Frame>
+          <Empty
+            icon={FolderOpen}
+            title="還沒有專案"
+            description="選一個方式開始"
+            action={
+              <div className="flex gap-2">
+                <Button variant="primary">匯入資料</Button>
+                <Button variant="primary">建立新專案</Button>
+              </div>
+            }
+          />
+        </Frame>
+        <Label warn>↑ 兩個 primary 視覺重量相同,使用者無從判斷</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const CopyRule: Story = {
+  name: '文案具體化 — 不用 通用 字',
+  render: () => (
+    <div>
+      <Rule
+        title="✅ 具體情境 + 下一步動作"
+        note="title 告訴使用者「這個容器是什麼 + 為什麼空」;description 告訴「怎麼讓它不空」。文案與場景綁定,不可跨元件通用"
+      >
+        <Frame>
+          <Empty
+            icon={Inbox}
+            title="收件匣已清空"
+            description="所有訊息都處理完畢,可以好好休息了"
+          />
+        </Frame>
+      </Rule>
+
+      <Rule
+        title="✅ Onboarding 語氣 — 帶情境引導"
+        note="第一次使用的 empty 應該讓人「期待」而不是「遺憾」。對齊 Notion / Linear 的語氣 — 提供 context + 給出口"
+      >
+        <Frame>
+          <Empty
+            icon={FolderOpen}
+            title="還沒有任何專案"
+            description="建立第一個專案,邀請團隊成員協作追蹤進度"
+            action={<Button variant="primary">建立專案</Button>}
+          />
+        </Frame>
+      </Rule>
+
+      <Rule
+        title="❌ Generic 字串 — No data / Empty / 無資料"
+        note="「No data」「Empty」「無資料」是系統語言,不是使用者語言。這類文案讓 empty 看起來像是 bug 或 debug 訊息,而不是一個情境提示"
+      >
+        <Frame>
+          <Empty description="No data" />
+        </Frame>
+        <Label warn>↑ 使用者看不懂「No data」代表什麼——沒有哪個資料?要怎麼補?</Label>
+
+        <Frame>
+          <Empty icon={Inbox} title="Empty" description="No records found" />
+        </Frame>
+        <Label warn>↑ 「Empty / No records found」純技術語,不傳達使用者情境</Label>
+      </Rule>
+    </div>
+  ),
+}

package/src/components/Empty/empty.spec.md

@@ -0,0 +1,216 @@
+---
+component: Empty
+family: composite
+variants: {}
+sizes: {}
+traits:
+  - isStructural
+benchmark:
+  - Ant Design Empty: github.com/ant-design/ant-design/tree/master/components/empty
+  - Polaris EmptyState: github.com/Shopify/polaris/tree/main/polaris-react/src/components/EmptyState
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Empty 設計原則
+
+**空狀態視覺元件**——容器內沒有內容時的居中提示。Table、SelectMenu、Combobox、Page section 等所有需要空狀態的元件統一消費。
+
+## 定位
+
+一個 **layout pattern**(不是 field-level 元件)。它排列 icon / title / description / action 成居中垂直堆疊,間距固定不隨 density 變(見「間距」段)。
+
+預設只有 description——icon / title / action 全部可選。
+
+**Layout Family**：非上述 family — composite / multi-section（多區塊組合，自 own layout）。
+
+---
+
+## 何時用
+
+- **Table / list / grid 空狀態**：DataTable 查無資料、搜尋無結果
+- **SelectMenu / Combobox 下拉空**：「無選項」「找不到符合的項目」
+- **Page section 無內容**：dashboard widget 暫無資料、設定頁未建立任何項目
+- **初次引導**：讓使用者首次使用時知道「這裡會放什麼」+ 有 CTA 建立
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| Loading 中(資料還沒來) | `Skeleton` / `CircularProgress` | Empty 是「確定沒有」,Loading 是「還沒確定」 |
+| 錯誤 / 失敗狀態 | `Alert` + 重試按鈕 | Error 需要明確告知「發生什麼問題」+ 解決途徑，Empty 是中性提示 |
+| 整頁級別的 404 / 無權限 | 專屬錯誤頁面 | Empty 是容器內提示，整頁錯誤需要完整頁面佈局 |
+| Disabled 狀態 | 禁用元件本身 | Empty 是「沒東西」，disabled 是「不能操作」 |
+
+```
+      [Icon(Avatar 包覆)]   ← 可選
+      [Title]                ← 可選
+      [Description]          ← 唯一必有
+      [Action]               ← 可選
+```
+
+(全部居中垂直堆疊;間距原則見「間距」段,具體 class / px 對照見 anatomy stories)
+
+## Slots
+
+- **Icon**(`icon?: LucideIcon | ReactElement`,預設無):LucideIcon 會自動包 48px neutral Avatar + 28px icon;ReactElement 原樣渲染(consumer 可自帶 Illustration、ColorAvatar、CircularProgress)
+- **Title**(`title?: string`,預設無):主要標題,foreground + medium 字重,居中
+- **Description**(`description?: string`,預設無 — 但是唯一必有的 slot):說明文字,次要色、居中
+- **Action**(`action?: ReactNode`,預設無):CTA Button 或任何操作,居中
+
+## 間距
+
+固定值,不隨 density 變(Empty 是展示性元件,不是工作區域元件——展示性文字不跟 field-height tier 連動):
+
+- **Icon → Title/Desc**:視覺 → 文字過渡需充足呼吸空間(48px icon 尺寸不宜貼近文字)
+- **Title → Description**:緊密配對(同資訊塊,對齊 item-layout canonical 的 label ↔ desc gap)
+- **Description → Action**:資訊 → 行動的視覺暫停,引導使用者注意 CTA
+
+Outer padding 由 **consumer 容器** 決定(Table 空狀態需較大留白、SelectMenu dropdown 較緊湊、Page-level 最寬鬆)。
+
+## Typography
+
+- **Title**:body-lg + medium 字重 / foreground 色(主要閱讀重量)
+- **Description**:字級跟 `RowSizeContext` 對齊——standalone(無 context,fallback `md`)或 `sm`/`md` row 子樹 = body tier(14px);渲染在 `lg` 的 `RowSizeContext` 子樹(如 lg menu)內時自動升 body-lg(16px),對齊該 menu items 字級。色彩條件式:有 title / action 時走 **`fg-secondary`**(次要閱讀色,與 title 形成主次層級);孤身 description(無 title / action)時走 **`fg-muted` placeholder 等級色**(跟 input placeholder 同色,提示「這裡暫時沒內容」);disabled context 時走 `fg-disabled`
+
+完整 slot / gap / typography 的 class 與 px 對照見 anatomy `Overview`(Slot 與 Spacing)+ `SlotCombinations`(Slot 間距規則)stories。
+
+## 文字不限寬
+
+Description **不加 max-width**。文字置中(由 `items-center` 居中,span 收縮成內容寬度,非 w-full),行寬由容器 padding 控制。文案設計者自己規劃換行(文案長度 = 設計的一部分),Empty 不該強制截斷。
+
+## 垂直定位(Consumer 容器的責任)
+
+Empty 只管**水平居中**。垂直定位由 consumer 的容器決定:
+
+| 容器類型 | 垂直定位 | 做法 |
+|---|---|---|
+| **有框**(Table / Dialog / Card,有明確 border 或 shadow 包圍) | **垂直置中** | 容器 `flex items-center justify-center min-h-[...]` |
+| **無框**(Page section,沒有外框線) | **頂部對齊 + generous padding** | 容器 `py-[calc(var(--layout-space-bottom)*2)]` |
+
+### 為什麼有框置中、無框不置中
+
+有框容器有明確的視覺邊界——使用者知道「這個框裡面是空的」。居中把 Empty 放在框的視覺重心,安定。
+
+無框容器沒有邊界——如果居中,Empty 會脫離頁面視覺中心,使用者不知道空的範圍有多大。頂部對齊 + `calc(var(--layout-space-bottom) * 2)` padding 讓 Empty 有固定位置,用留白空間本身創造「這裡是空的」的視覺重量,取代框線的作用。
+
+## 邊界案例
+
+- **極長 description**:不截斷、不限寬,自然換行(見「文字不限寬」段)— 文案長度由文案設計者控制
+- **動態變空**(filter / search 從有結果 → 無結果):視覺與靜態空狀態完全相同,無轉場;consumer 容器加 `aria-live="polite"` 通知 SR(見「A11y 預設」)
+- **全 slot 缺值**:code 不擋空 render,但 description 是唯一必有 slot(見「Slots」段)— 無任何 slot 的 `<Empty>` 渲染成空容器,屬 consumer 誤用
+
+---
+
+## A11y 預設
+
+Empty 是 **non-interactive layout primitive**——本身無 ARIA role(讓 consumer 容器決定 region semantics)。但 consumer 應遵循以下慣例:
+
+| 場景 | Consumer 容器應加 | 為什麼 |
+|------|----------------|------|
+| Table / List 空狀態 | `<table aria-describedby={emptyId}>` 或在容器加 `aria-live="polite"` | screen reader 在資料載入完成時主動通知「無資料」(對齊 Polaris EmptyState pattern) | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+| Search / Filter 無結果 | container `aria-live="polite"` + 文案明確指向搜尋詞(「找不到符合『XXX』的結果」)| 對齊 Material `<NoOptions>` + Atlassian Empty Search idiom — 變動結果需 live region | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+| Page section 暫無內容 | `<section aria-labelledby={titleId}>` + `<h2>` 包 title slot | 對齊 WCAG 2.1 SC 2.4.6 標題明確語意 |
+| 初次引導(有 CTA) | Action Button 自帶 a11y;無需 Empty 層額外 ARIA | CTA 是真實互動 element,自己的 a11y 足夠 |
+
+**Title slot heading level**:Empty 不渲染 heading tag(`<h1>` / `<h2>`),只 `<div>` + 視覺 typography。Consumer 若需 heading semantic,在外層自包 `<h2>{title}</h2>` + 不傳 Empty 的 title prop(避免重複)。
+
+**Icon slot**:LucideIcon 自動渲染 `aria-hidden="true"`(decorative);ReactElement(自帶 Avatar / Illustration)由 consumer 控制 `aria-hidden` / `alt`(若是 `<img>` 必傳 `alt=""` 表示 decorative)。
+
+**Description 不需 live announcement**:Empty 本身是「靜態空狀態提示」(進入時就空),不是「動態變化結果」。動態變化(filter / search 結果切換)由 consumer 在容器層加 `aria-live`,不在 Empty 內。
+
+世界級對照:
+- **Polaris** `<EmptyState>`:容器層 `aria-labelledby` + heading 由 prop 控制 level(consumer 決定 `<h2>` / `<h3>`)
+- **Material** `<NoOptions>`(Autocomplete 內):容器自帶 `role="listbox"` + `aria-live="polite"` 通知無結果
+- **Carbon** `<EmptyState>`:無自帶 ARIA,文檔指引 consumer 在父容器設 `aria-describedby`
+
+本 DS 對齊 Carbon「primitive 不自帶 ARIA,consumer 控制」哲學——避免 Empty 強加 role 跟 consumer 容器衝突。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+---
+
+## 消費範例
+
+```tsx
+// Table 空狀態(最簡)
+<Empty description="沒有資料" />
+
+// SelectMenu 無結果
+<Empty icon={SearchX} description="找不到符合的結果" />
+
+// Page 首次引導(完整 slots)
+<Empty
+  icon={FolderOpen}
+  title="還沒有專案"
+  description="建立第一個專案來開始使用"
+  action={<Button>建立專案</Button>}
+/>
+
+// 自訂色彩(success result)
+<Empty
+  icon={<Avatar icon={CheckCircle} size={48} color="green" />}
+  title="已成功送出"
+  description="我們會盡快處理"
+/>
+
+// 自訂圖片
+<Empty
+  icon={<img src="/empty-illustration.svg" className="w-12 h-12" alt="" />}
+  description="尚無內容"
+/>
+```
+
+## 現有消費者
+
+| 元件 | 消費方式 | Padding 落點 |
+|---|---|---|
+| DataTable | 外層 `<div className="flex-1 flex items-center justify-center py-12">` 包 `<Empty description={emptyState} />`(有框置中) | wrapper div(非 Empty className) |
+| SelectMenu | `<Empty description={emptyText} className="py-6" />`(loading 時 `<Empty icon={<CircularProgress size={48}/>} className="py-6" />`) | Empty className |
+| Combobox | 透過 SelectMenu(dropdown 即 SelectMenu primitive)→ 無結果時顯 SelectMenu 的 `<Empty>` | 同 SelectMenu |
+
+## 禁止事項
+
+- ❌ 把 Empty 拿來顯示 loading state(無 description 又無 spinner)— Empty 是「確定沒有」語意,loading 用 `<Skeleton>` / `<CircularProgress>` 或 `<Empty icon={<CircularProgress />}/>` compose
+- ❌ 把 Empty 拿來顯示 error state(只有 description)— error 需明確 action(重試 / 報告 / 聯絡支援),用 `<Alert>` + 重試 button
+- ❌ Empty title / description 文案太抽象(「Nothing here」「No data」)— 應描述「缺什麼資料」+「為什麼空」+「下一步動作」(對齊 Polaris EmptyState / Carbon Empty State copy guideline) <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- ❌ Action button 用 destructive variant — Empty 是引導 onboarding 心境,destructive 視覺敵意衝突
+- ❌ 整頁 Empty 但無 action — user 困惑「我該做什麼」;若該頁本質無 action(等待後台 invite),改用 Alert/Notice 解釋
+
+## 為何無 ColorMatrix / SizeMatrix / StateBehavior
+
+Empty 是 **pure layout primitive**(排列 icon / title / description / action 成居中垂直堆疊),不是 variant-driven 元件,也無互動狀態:
+
+- **無 ColorMatrix**:Empty 自身不帶任何色彩,bg transparent,text color 全部走 semantic token(`text-foreground` title / `text-fg-secondary` description-with-title / `text-fg-muted` 孤身 description / `text-fg-disabled` disabled context)。Avatar icon 的色彩由 consumer 透過 `<Avatar color="...">` 決定,非 Empty 層級 variant。
+- **無 SizeMatrix**:Empty 無 `size` prop,垂直 padding 由 consumer 容器決定(Table `py-12` / SelectMenu `py-6` / Page `py-16`),固定間距不隨 density 變(展示性元件,見本 spec「間距」段)。
+- **無 StateBehavior**:Empty 是非互動展示元件,無 hover / focus / active / selected 互動狀態。CTA button 的互動狀態屬 Button 層級,不屬 Empty。**唯一例外是 disabled context state**(`disabled?: boolean` prop):非互動狀態,但元件支援——disabled 時 title / description 轉 `text-fg-disabled`、icon glyph 轉 fg-disabled(供 FileUpload disabled 等情境消費),不影響既有 consumer(預設 false)。
+
+**Inspector**:提供互動切換式 Inspector(右側 Controls 面板切換 icon / title / description / action),讓 consumer 即時查看 Empty 在不同 slot 組合下的呈現——slot 組合(description only → full)是 Empty 唯一的關鍵決策。
+
+對應 anatomy story:`Overview` + `Inspector`(互動切換)+ `Accessibility` + 元件特有 `ScenarioMatrix`(常見業務場景)+ 元件特有 `SlotCombinations`(slot 組合對照)。
+
+---
+
+## 相關
+
+- `../Avatar/avatar.tsx` — Icon 渲染實作
+- `../CircularProgress/circular-progress.spec.md` — Loading 狀態(非「空」而是「還沒來」;全頁 loading 可 `<Empty icon={<CircularProgress size={48}/>}/>` compose)
+- `../Alert/alert.spec.md` — Error 狀態（非中性空，是需處理的問題）
+- `../FileUpload/file-upload.spec.md` — **本元件 consumer**:FileUpload 預設 children 直接渲染 `<Empty icon={Upload} title description />`,共用 icon+title+desc SSOT
+- `../../tokens/typography/typography.spec.md` — Typography tier
+- `../../tokens/layoutSpace/layoutSpace.spec.md` — Layout-space token
+- `../../patterns/element-anatomy/item-anatomy.spec.md` — label → desc gap(token `--item-gap-label-desc-reading-lg` / primitive `<ItemContent>`)
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `carousel.spec.md`
+- `circular-progress.spec.md`
+- `combobox.spec.md`
+- `command.spec.md`
+- `file-upload.spec.md`
+- `file-viewer.spec.md`
+- `select-menu.spec.md`
+- `select.spec.md`
+- `sheet.spec.md`
+- `skeleton.spec.md`
+- `tree-view.spec.md`

package/src/components/Empty/empty.stories.tsx

@@ -0,0 +1,80 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { SearchX, WifiOff, Lock, Inbox } from 'lucide-react'
+import { Empty } from './empty'
+import { Button } from '@/design-system/components/Button/button'
+
+const meta: Meta<typeof Empty> = {
+  title: 'Design System/Components/Empty/展示',
+  component: Empty,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '空狀態視覺元件——icon + title + description + action 的居中垂直堆疊。預設只需 description,其他皆可選。',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof Empty>
+
+/* ── 搜尋無結果(Jira / Linear 慣例)─────────────────────────────────── */
+export const SearchNoResults: Story = {
+  name: '搜尋無結果',
+  render: () => (
+    <div className="border border-border rounded-lg p-8 max-w-md">
+      <Empty
+        icon={SearchX}
+        title="找不到相符的任務"
+        description="試試其他關鍵字,或調整篩選條件"
+        action={<Button variant="tertiary">清除所有篩選</Button>}
+      />
+    </div>
+  ),
+}
+
+/* ── 空清單 — Jira 無 task ────────────────────────────────────────── */
+export const NoTasks: Story = {
+  name: '空清單',
+  render: () => (
+    <div className="border border-border rounded-lg p-8 max-w-md">
+      <Empty
+        icon={Inbox}
+        title="這個 Sprint 還沒有任務"
+        description="從 backlog 拖拉任務進來,或直接建立新任務"
+        action={<Button variant="primary">建立任務</Button>}
+      />
+    </div>
+  ),
+}
+
+/* ── 錯誤無法載入(action-oriented)────────────────────────────────── */
+export const LoadFailure: Story = {
+  name: '錯誤無法載入',
+  render: () => (
+    <div className="border border-border rounded-lg p-8 max-w-md">
+      <Empty
+        icon={WifiOff}
+        title="連線中斷,無法載入資料"
+        description="請檢查網路連線後重試"
+        action={<Button variant="secondary">重新載入</Button>}
+      />
+    </div>
+  ),
+}
+
+/* ── 權限不足 ─────────────────────────────────────────────────────── */
+export const NoPermission: Story = {
+  name: '權限不足',
+  render: () => (
+    <div className="border border-border rounded-lg p-8 max-w-md">
+      <Empty
+        icon={Lock}
+        title="你沒有檢視這個專案的權限"
+        description="請聯絡專案擁有者要求存取,或返回你有權限的工作區"
+        action={<Button variant="tertiary">聯絡擁有者</Button>}
+      />
+    </div>
+  ),
+}