@qijenchen/design-system 0.1.0-beta.3 → 0.1.0-beta.32

package/src/components/DropdownMenu/dropdown-menu.spec.md

@@ -0,0 +1,241 @@
+---
+component: DropdownMenu
+family: 1
+variants: {}
+sizes: {}
+traits:
+  - hasInteractiveStates
+  - isOverlay
+benchmark:
+  - Radix DropdownMenu primitive: github.com/radix-ui/primitives/tree/main/packages/react/dropdown-menu
+  - Ant Design Dropdown: github.com/ant-design/ant-design/tree/master/components/dropdown
+  - Polaris ActionList: github.com/Shopify/polaris/tree/main/polaris-react/src/components/ActionList
+---
+
+# DropdownMenu 設計原則
+
+## 定位
+
+DropdownMenu 是按鈕觸發的**動作選單**——使用者從中選擇一個動作並立即執行。
+基於 Radix DropdownMenu（shadcn 包裝），item 佈局消費 MenuItem primitive。
+
+**Layout Family**：CLAUDE.md 4-Family Model **Family 1（Menu item layout）** 消費者。結構繼承 `patterns/element-anatomy/item-anatomy.spec.md`「Menu item layout」章節的 scanning-mode 規格。
+
+### 與 SelectMenu 的區別
+
+SelectMenu 是**選值**(選完後值留在 field 裡),DropdownMenu 是**執行**(選完後觸發動作,選單關閉)。判斷標準:「選完之後,畫面上是否需要保留選中狀態?」需要 → SelectMenu;不需要 → DropdownMenu。
+
+---
+
+## 何時用
+
+- **次要動作集合**：卡片右上角 `⋮` 三點選單（複製、刪除、分享、匯出）
+- **工具列的溢出動作**：ToolBar 放不下的次要操作集中在 more menu
+- **即時生效的設定 toggle**：顯示 / 隱藏欄位、排序方式、主題切換
+- **需要分群或子選單的動作清單**：export as PDF / CSV / JSON 這類多層結構
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 選值（選項留在 field 裡）| `Select` / `SelectMenu` | DropdownMenu 點完即關閉，不保留選中狀態 |
+| 主要 CTA（儲存、送出）| `Button` | 主要動作應該直接可見，不該隱藏在選單裡 |
+| 切換平行視圖 | `Tabs` / `SegmentedControl` | view 切換應該持續可見，不是 one-shot |
+| 少於 3 個動作 | 直接放 Button | 2 個動作用 menu 是多餘的藏匿 |
+| 複雜表單 / 多步驟流程 | `Dialog` / `Sheet` | menu item 是單次點擊動作，不承載流程 |
+
+---
+
+## 結構
+
+```
+DropdownMenu                    ← Radix Root，管理開關狀態
+  DropdownMenuTrigger           ← 觸發按鈕（通常是 Button）
+  DropdownMenuContent           ← 浮層容器，提供 size context
+    DropdownMenuGroup           ← 邏輯群組容器（自動分隔相鄰 Group，見下）
+      DropdownMenuItem          ← 基本動作項目
+      DropdownMenuCheckboxItem  ← 可勾選的切換項目（如顯示/隱藏欄位）
+    DropdownMenuRadioGroup      ← 單選群組容器
+      DropdownMenuRadioItem     ← 單選項目（如排序方式）
+    DropdownMenuSub             ← 子選單容器
+      DropdownMenuSubTrigger    ← 子選單觸發項目（自動附加 ChevronRight）
+      DropdownMenuSubContent    ← 子選單浮層
+    DropdownMenuLabel           ← 群組標題（不可互動）
+    DropdownMenuSeparator       ← 明確分隔線（consumer 手動放置）
+    DropdownMenuShortcut        ← 鍵盤快捷鍵提示（ml-auto 靠右）
+```
+
+### DropdownMenuGroup 的自動分隔
+
+`DropdownMenuGroup` 對齊 `MenuGroup` 的 group separation 設計語言——相鄰的 Group 自動透過 `border-divider` 分隔，**consumer 不需要自己加 `DropdownMenuSeparator`**。
+
+**設計語言**（跨 Menu-like 元件統一，SSOT 見 `../../patterns/element-anatomy/item-anatomy.spec.md`「Group auto-separation」）：
+- 每個 group 上下各 **8px padding**
+- 相鄰 group 之間用 **border-divider** 分隔
+- 兩個 group 之間視覺 gap = 8（上一 bottom）+ 8（下一 top）= **16px + border**
+
+**MenuGroup vs DropdownMenuGroup CSS 實作對照**（視覺結果 100% 等價，差別只是 padding 住在哪層）：
+
+| | MenuGroup | DropdownMenuGroup |
+|---|---|---|
+| CSS | `py-2 [&+&]:border-t [&+&]:border-divider` | `[&+&]:mt-2 [&+&]:pt-2 [&+&]:border-t [&+&]:border-divider` |
+| 邊界 padding 來源 | 每個 Group 自己的 py-2（Command.List 無 py） | Content 的 py-2（Group 不套 py-2 避免 double） |
+| Group 間 gap | 8 + 8 = 16 + border | 0 + 8 + 8 = 16 + border |
+
+**為什麼不直接套 `py-2`**：`DropdownMenuContent` 已有 `py-2` 提供 Content 邊界 padding（Radix 預期行為，移除會影響 trigger focus offset）。若 Group 再套 `py-2` 會 double padding。改用 `mt-2 pt-2` 只加在第二個 Group 起，視覺等價但不 double。
+
+兩種分隔機制的選擇：
+- **用 `DropdownMenuGroup` 包裝同類 items** → 自動分隔（零手動，跟 MenuGroup 理念一致）
+- **用 `DropdownMenuSeparator` 明確插入** → 明確控制分隔位置（如群組內部的子分組、破壞性動作前的強調分隔）
+
+---
+
+## Item 類型
+
+| 類型 | 用途 | 選中行為 |
+|---|---|---|
+| **Item** | 執行一次性動作（複製、刪除、開啟連結） | 執行後關閉選單 |
+| **CheckboxItem** | 切換開關狀態（顯示/隱藏欄位） | 勾選/取消，選單保持開啟 |
+| **RadioItem** | 從互斥選項中選一（排序方式） | 選中後關閉選單 |
+| **SubTrigger** | 展開下一層選單 | 不執行動作，展開子選單 |
+| **Label** | 群組標題，提供語義分類 | 不可互動 |
+| **Separator** | 視覺分隔，劃分邏輯群組 | 不可互動 |
+
+CheckboxItem 和 RadioItem 雖然涉及「選擇」，但它們控制的是**即時生效的設定**（toggle），不是「選一個值填回 field」。
+
+---
+
+## Item 佈局
+
+遵循 item-layout 設計原則：
+
+```
+[prefix]  [label]  [suffix]
+```
+
+- prefix：`DropdownMenuItemIcon` 包裹 startIcon，`h-[1lh]` 對齊第一行 label。icon 跟 label 同色（foreground）
+- label：文字內容，`flex-1`
+- suffix：`DropdownMenuShortcut` 或自行組合的後綴容器，`ml-auto` 靠右。指示型 icon 用 `fg-muted`
+
+padding 公式：`py = (field-height - 1lh) / 2`，單行時總高度等於同 size 的 Button / Input。
+
+---
+
+## Suffix 模式
+
+| Pattern | 內部 gap | 內容 | 用途 |
+|---|---|---|---|
+| **獨立後綴** | `gap-2` (8px) | `[badge?] [endIcon?]` | 狀態指示（未讀數）、導覽提示（ExternalLink） |
+| **子選單指示** | `gap-1` (4px) | `[value?] [badge?] [ChevronRight]` | 展開下一層，value 顯示目前狀態（如 "深色"） |
+
+SubTrigger 的 ChevronRight 由元件自動渲染，不需手動加。子選單指示中的 value 和 badge 是可選的——讓使用者不用展開就能看到下一層的目前狀態。
+
+---
+
+## 浮層規格
+
+所有 elevation-200 浮層共用同一套視覺規格：
+
+| 屬性 | Token |
+|---|---|
+| 背景 | `bg-surface-raised` |
+| 陰影 | `--elevation-200` |
+| 圓角 | `rounded-lg` (8px) |
+| 邊框 | `border border-border` |
+| 間距 | `sideOffset={8}`（見 `../Popover/popover.spec.md` SSOT） |
+| Align | **跟隨 trigger 位置:左 → `start` / 中 → `center` / 右 → `end`**,見 `../Popover/popover.spec.md`「Align 對齊 canonical(跨浮層 SSOT)」|
+| 最小寬度 | 跟隨觸發元件寬度 |
+
+SubContent 使用相同規格，包括 sideOffset。
+
+---
+
+## Size
+
+透過 `DropdownMenuContent` 的 `size` prop 設定，經 SizeContext 向下傳遞，所有子項目自動套用。
+
+| Size | Label | Icon | Checkbox/Radio 控件 |
+|---|---|---|---|
+| sm | `text-body leading-compact` (14px, 1.3) | 16px | 16px |
+| md | `text-body leading-compact` (14px, 1.3) | 16px | 16px |
+| lg | `text-body-lg leading-compact` (16px, 1.3) | 20px | 20px |
+
+DropdownMenu 是掃描模式——使用者快速瀏覽選項，所有尺寸使用 `leading-compact`。
+
+---
+
+## 鍵盤操作
+
+由 Radix DropdownMenu 提供：
+
+| 按鍵 | 行為 |
+|---|---|
+| `↑` `↓` | 移動焦點 |
+| `Enter` / `Space` | 執行目前焦點的動作 |
+| `Escape` | 關閉選單（子選單先關子層） |
+| `→` | 展開子選單 |
+| `←` | 收合子選單，焦點回到 SubTrigger |
+
+---
+
+## 破壞性動作
+
+刪除等不可逆動作的 **prefix icon 和 label 都使用 `text-error`**——prefix icon 是 label 的視覺延伸，與 label 同色。Suffix shortcut 維持 `fg-muted`。
+
+---
+
+## 禁止事項
+
+- ❌ 不要用 DropdownMenu 做選值——「選一個值填回 field」用 SelectMenu
+- ❌ 不要在 item 內放獨立互動元素（如 Button、Switch）——item 本身就是互動單位
+- ❌ disabled item 不可有 hover 效果
+- ❌ Label 不可被點擊或取得焦點
+- ❌ 不要手動在 SubTrigger 內加 ChevronRight——元件自動渲染
+- ❌ 不要混用 Shortcut 和自訂後綴——同一個 item 只用一種後綴
+
+---
+
+## StateBehavior(DropdownMenu 層級特有)
+
+Item-level default / hover / focused / selected / disabled **色彩**由 MenuItem primitive SSOT 擁有(`patterns/element-anatomy/item-anatomy.spec.md`「選擇 / 狀態視覺規則」),在本元件 `ColorMatrix` story 承載並直接引用 MenuItem token。DropdownMenu 的 `StateBehavior` story 展示**浮層層級特有的動態行為**:open / close 動畫(Radix `data-state` 驅動)、Submenu 展開 / 收起、CheckboxItem toggle(多選不 close)——這些是 item primitive 沒有的維度。
+
+---
+
+## 邊界案例
+
+- **Disabled trigger**:由 trigger Button 的 `disabled` prop 控,該 Button 自動繼承 disabled token(M24 state precedence);click trigger 不開 menu。
+- **Disabled item**:`<DropdownMenuItem disabled>`(Radix 內建支援),視覺繼承 MenuItem SSOT(`text-fg-disabled` + `aria-disabled=true` + 鍵盤導覽 skip + 不觸發 onSelect)。
+- **Loading(async submenu / async items)**:DropdownMenu primitive 不獨立 own loading prop。async submenu 場景應由 consumer 在 `<DropdownMenuSub>` 內條件性渲 `<DropdownMenuItem disabled>` + spinner label(如「載入中...」);或 fetch options 前先 disable 整個 menu trigger。完整 loading body 替換 pattern 屬 SelectMenu scope,不在 DropdownMenu scope。
+- **Empty(no items / async fetch result empty)**:consumer 應條件性渲 `<DropdownMenuItem disabled>` 顯示「無可用動作」字樣;不渲空 menu。
+- **Dark mode / density**:走 MenuItem + Popover SSOT 自動 adapt;density 預設 lock `md`(M3 portal subtree convention)。
+
+---
+
+## 相關
+
+- `../Menu/menu-item.spec.md` — 共用的 MenuItem primitive（prefix 對齊、尺寸、狀態）
+- `../SelectMenu/select-menu.spec.md` — 選值（選完留在 field 裡）的對應元件
+- `../Button/button.spec.md` — 通常作為 DropdownMenuTrigger
+- `../Dialog/dialog.spec.md` — 複雜流程時的改用選擇
+
+## A11y 預設
+
+**ARIA / Pattern**:繼承 Radix `dropdown-menu` primitive a11y 預設(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/dropdown-menu#accessibility)。
+
+**Keyboard 行為**:
+
+- Tab — focus trigger
+- Enter / Space / ↓ — 開啟
+- ↑/↓ — 導覽 items
+- Enter — 選擇
+- Esc — 關閉
+
+**Focus**:Radix primitive 自管 focus trap / restoration / visible ring(`outline: 2px solid var(--ring)` per design-system focus-visible canonical)。
+
+**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `density.spec.md`

package/src/components/DropdownMenu/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './dropdown-menu'

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

@@ -0,0 +1,204 @@
+---
+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 成居中垂直堆疊,間距走 layout-space token(density-aware)。
+
+預設只有 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 是「不能操作」 |
+
+```
+         [Avatar 48px neutral + icon]     ← 可選
+          gap = --layout-space-tight
+        [Title 16px font-medium centered]  ← 可選
+         --item-gap-label-desc-reading-lg (2px)
+      [Description 14px fg-secondary centered]
+               w-full (no max-width)
+          gap = --layout-space-loose
+              [Action Button]              ← 可選
+```
+
+## 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**:body tier / **`fg-muted` placeholder 等級色**(跟 input placeholder 同色,提示「這裡暫時沒內容」)
+
+完整 slot / gap / typography 的 class 與 px 對照見 anatomy `Overview`(Slot 與 Spacing)+ `SlotCombinations`(Slot 間距規則)stories。
+
+## 文字不限寬
+
+Description **不加 max-width**。文字撐滿容器,由容器 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 有固定位置,用留白空間本身創造「這裡是空的」的視覺重量,取代框線的作用。
+
+---
+
+## 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="尚無內容"
+/>
+```
+
+## 現有消費者改寫
+
+| 元件 | 現況 | 改為 |
+|---|---|---|
+| DataTable | inline `<div>` 硬寫 className | `<Empty description={emptyState} className="py-12" />` |
+| SelectMenu | — | `<Empty description="無選項" className="py-6" />` |
+| Combobox | — | `<Empty description="找不到結果" className="py-6" />` |
+
+## 禁止事項
+
+- ❌ 把 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 解釋
+
+## 為何無 Inspector / ColorMatrix / SizeMatrix / StateBehavior
+
+Empty 是 **pure layout primitive**(排列 icon / title / description / action 成居中垂直堆疊),不是互動元件,也不是 variant-driven 元件:
+
+- **無 Inspector**:Empty 的「關鍵決策」是 slot 組合(description only → full),已在 `SlotCombinations` story 呈現四種組合對照(最簡 → 輕引導 → 中引導 → full)。互動切換式 Inspector 不會比 slot composition 對照更有教學價值——consumer 需要的是「這四種場景怎麼選」。
+- **無 ColorMatrix**:Empty 自身不帶任何色彩,bg transparent,text color 全部走 semantic token(`text-foreground` / `text-fg-muted`)。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 / disabled。CTA button 的互動狀態屬 Button 層級,不屬 Empty。
+
+對應 anatomy story:保留 `Overview` + 元件特有 `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。若要手動補充,寫在本節之前。
+
+- `combobox.spec.md`
+- `command.spec.md`
+- `select.spec.md`
+- `sheet.spec.md`

package/src/components/Empty/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './empty'