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

package/src/components/DescriptionList/description-list.spec.md

@@ -0,0 +1,214 @@
+---
+component: DescriptionList
+family: composite
+variants: {}
+sizes: {}
+traits:
+  - isStructural
+benchmark:
+  - Ant Design Descriptions: github.com/ant-design/ant-design/tree/master/components/descriptions
+  - Polaris DescriptionList: github.com/Shopify/polaris/tree/main/polaris-react/src/components/DescriptionList
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# DescriptionList 設計原則
+
+唯讀 label + value 展示元件，用於呈現結構化的屬性資訊。HTML 語義為 `dl` + `dt` + `dd`，對齊 Atlassian、Shopify Polaris 慣例。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+## 定位
+
+- **是**：唯讀資訊展示（profile card 的欄位、detail panel 的屬性列表）
+- **不是**：表單輸入——需要編輯的 label + value 用 Field 系統（Input / Select 等）
+
+**Layout Family**：非上述 family — composite / multi-section（多區塊組合，自 own layout）。
+
+---
+
+## 何時用
+
+- **Profile / detail panel 的屬性列表**：使用者資料（Email / Phone / Role / Created at）
+- **NameCard 的 info fields**：HoverCard 內的次要資訊展示
+- **固定資訊展示**：產品規格、訂單明細、設定值（唯讀）
+- **HTML 語義為 `dl` + `dt` + `dd`**：對 screen reader 明確表達「屬性-值」關係
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 需要編輯的 label + value | `Field` 系統（`Input` / `Select` / `DatePicker` 等）| DescriptionList 是唯讀，編輯用 Field |
+| Table 式資料展示（多 row 相同結構）| `DataTable` | DescriptionList 是單實體屬性，Table 是多筆同結構 |
+| 單一 label + value（只有一組）| 自訂 layout | DescriptionList 設計為多組屬性；單組殺雞用牛刀 |
+| 需要 cell 編輯的表格 | `DataTable` + inline edit | DescriptionList 無 cell 編輯 |
+
+## 結構
+
+- `DescriptionList`：外層 `dl`，vertical 模式為 CSS grid、horizontal 模式為 flex column
+- `DescriptionItem`：一組 `dt`（label）+ `dd`（value），透過 context 知道當前 direction 自動切 layout
+
+## Direction(2026-04-20 新增)
+
+| direction | Layout | 典型情境 | 世界級對照 |
+|-----------|--------|---------|-----------|
+| `vertical`(預設)| label 在上 / value 在下 | NameCard detail、sidebar 長 value(地址、bio) | Atlassian DescriptionList、Polaris DescriptionList |
+| `horizontal` | label 左 / value 右對齊 | **file info panel / 訂單詳情 / settings summary**(短 value 的 metadata 列) | Google Drive file info、Notion file panel、iOS Settings | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+**判斷法**:
+- value 預期長(多字、可能換行)→ vertical(讓 value 佔滿寬)
+- value 短(檔名、日期、大小、類型)+ 強調 label↔value 對應 → horizontal
+
+### divided(horizontal 專用)
+
+每個 item 下方加 `border-b border-divider`,rows 之間有視覺格線。**長列表 / key 長度不一**時建議開;短列表(< 4 rows)或單一相似長度 keys 不需要。
+
+```tsx
+// 短 metadata 列,無需 divider
+<DescriptionList direction="horizontal">
+  <DescriptionItem label="建立">2026-04-20</DescriptionItem>
+  <DescriptionItem label="修改">2026-04-20</DescriptionItem>
+</DescriptionList>
+
+// 檔案資訊 — 多 row + key 長度不一 → divided 對齊格線
+<DescriptionList direction="horizontal" divided>
+  <DescriptionItem label="檔名">Q1 財報分析.xlsx</DescriptionItem>
+  <DescriptionItem label="類型">application/vnd.xlsx</DescriptionItem>
+  <DescriptionItem label="大小">1.2 MB</DescriptionItem>
+</DescriptionList>
+```
+
+## Typography（閱讀模式）
+
+層級靠色彩區分，不靠字體大小：
+
+- **label (dt)**：`text-body`（14px）`text-fg-secondary`（neutral-8）
+- **value (dd)**：`text-body`（14px）`text-foreground`（neutral-9）
+- 兩者行高均為 1.5（閱讀模式）
+
+## 間距
+
+### Vertical direction
+
+- **label → value**(同 item 內):`--item-gap-label-desc-reading` token(2px)——極小間距,視覺上 label 與 value 緊密配對
+- **items 之間垂直 gap**:`gap-y-[var(--layout-space-tight)]`——density-aware,跟隨系統密度設定
+- **columns 之間水平 gap**:`gap-x-4`(16px)
+
+### Horizontal direction(divided=false)
+
+- **items 之間垂直 gap**:`mb-[var(--layout-space-tight)]` per item(last:mb-0)——density-aware,等同 vertical 的 items gap
+- label ↔ value 水平距離:`justify-between` + `gap-4`(最小 16px,content 之間拉開)
+
+### Horizontal direction(divided=true)
+
+- 每個 item `py-[var(--layout-space-tight)]`(density-aware,形成 cell-like row 高度)
+- 每個 item 底部 `border-b border-divider`,`last:border-b-0`——row 之間視覺格線,key 長度不一時易於對齊掃描
+- **何時開 divided**:長列表(≥ 4 rows)/ key 長度差異大(短 vs 長 label 並排易顯亂) → divided 可對齊格線;短列表(< 4 rows)且 key 長度相近 → 不需 divided(border 反而噪音)
+- **世界級對照**:Google Drive 詳細資訊面板 / Notion 檔案屬性 / iOS Settings list rows,divided 是 file info / settings 的 canonical 呈現 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+## Props
+
+### `direction`:vertical / horizontal
+
+見上「Direction」段。
+
+### `divided`:horizontal 專用 row divider
+
+見上「divided」段。
+
+### `cols`:grid 欄數(vertical 才生效)
+
+| 值 | 用途 |
+|---|---|
+| `1`(預設)| 垂直堆疊,適合窄容器(NameCard、sidebar detail)|
+| `2` | 兩欄並排,適合中等寬度(NameCard info fields)|
+| `3` | 三欄,適合寬容器(detail panel)|
+
+Horizontal 模式永遠單欄(label + value 排列就是橫向,不再有欄概念)。
+
+## Section heading 模式(consumer pattern)
+
+consumer 要在 DL 上方加 section heading(「基本資料」/「團隊資訊」等)時,**heading → first-item 的 gap 必須等於 item → item 的 gap**(都走 `var(--layout-space-tight)` density-aware token):
+
+```tsx
+<div>
+  <div className="text-body font-medium mb-[var(--layout-space-tight)]">基本資料</div>
+  <DescriptionList>
+    <DescriptionItem label="姓名">Ada Chen</DescriptionItem>
+    <DescriptionItem label="Email">ada.chen@example.com</DescriptionItem>
+  </DescriptionList>
+</div>
+```
+
+**為什麼相等**(Gestalt proximity canonical):heading 與下方 items 的關係是「擁有 / 歸屬」—— 相同距離讓視覺上 heading 與 items 形成一個群組。若拉大 gap(例 `mb-4`),heading 看似與 items「分離」,失去歸屬感;若縮小 gap(例 `mb-0`),heading 與 items 黏在一起無呼吸。
+
+**世界級對照**:iOS Settings / Notion properties / Ant Descriptions / Polaris Card.Section — heading 和 items 之間的 gap 皆與 item-item gap 相等(或近似)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+**Heading typography 建議**:`text-body font-medium text-foreground`(同 item label size,靠 weight 區分層級),不用加粗 / 放大 / 換色——讓 heading 是「標籤」不是「標題」。
+
+---
+
+## vs Field 系統
+
+| | DescriptionList | Field |
+|---|---|---|
+| 用途 | 唯讀展示 | 表單輸入（含 read-only mode） |
+| 語義 | `dl/dt/dd` | `label` + input control |
+| 互動 | 無 | 輸入、驗證、提交 |
+| 密度感知 | 垂直 gap 跟隨 layout-space | 高度、padding 跟隨 ui-size |
+
+---
+
+## 禁止事項
+
+- ❌ 不要把 DescriptionList 拿來做 Form field label——表單需要編輯的 label + control 對應關係由 `Field`(含 `FieldLabel`)承載;DL 是唯讀 `<dl>` 語意,沒有 `<label for>` 對 input 的綁定
+- ❌ 不要在同一資料卡內混用 Field 和 DescriptionList——同一 section 的 label / value 語意必須一致,否則 screen reader 會讀出混淆的 term/description 對話。要編輯用全 Field,要唯讀全 DL
+- ❌ 不要用 DescriptionList 展示多筆同結構資料(使用者清單、訂單清單)——DL 是單實體屬性列表,多筆用 `DataTable`
+- ❌ 不要在 `<dt>` / `<dd>` 內嵌互動元件(Button / Input)——DL 是 `<dl>` 唯讀語意,塞互動會破壞 SR 敘事流;需要互動改用 Field 或 action row
+- ❌ 不要覆寫 label / value typography token(例改 `<dt>` 成 `text-heading-sm`)——DL 層級靠色彩區分不靠 size,改 size 會破壞「屬性-值」對應感
+
+---
+
+## 無障礙
+
+- **語意 HTML**:外層 `<dl>`,每組內 `<dt>` 為 term、`<dd>` 為 description——screen reader 會讀成「term X, description Y」對話,明確表達屬性-值關係
+- **DT / DD 配對**:每個 `<dt>` 必須有對應的 `<dd>`(不可孤立),否則 SR 敘事會中斷;元件內建一組 `DescriptionItem` 強制配對,不分開暴露 `<dt>` / `<dd>` primitive
+- **空值呈現**:value 空時以 `—` 占位(由 consumer 填入或於 DL 內 normalize),`text-fg-muted` 降低視覺重量;SR 會讀出「長破折號」,比空 `<dd>` 更明確
+- **多欄 `cols > 1`**:視覺為 grid 欄位,但 DOM 順序為 item 順序——SR 仍依 DOM 敘事(term1 → desc1 → term2 → desc2),不依視覺欄位;設計時確保 DOM 順序符合語意分組
+- **長值換行**:value 內長字串(URL / ID)以 `break-words` 處理,避免撐破 grid;不強制單行 truncate,長內容保留可讀完整性
+- **列表識別**:預設 `<dl>` 有部分瀏覽器 SR 不視為 list,若需明確 list 語意,DL 根容器可搭配 `role="list"` + `<div role="listitem">`(目前預設不加,保留標準 `<dl>` 語意,consumer 可自行加 role 覆蓋)
+
+---
+
+## 為何無 Inspector / ColorMatrix / SizeMatrix
+
+DescriptionList 是**唯讀 label / value 資料呈現**(非互動 / 非 variant 驅動):
+
+- **無 Inspector**:DL 的決策維度是 columns(單欄 / 雙欄 / 多欄)已在 `ColsMatrix` 覆蓋。互動 Inspector 無進一步 prop(value 呈現由資料決定,非 prop 切換)。
+- **無 ColorMatrix**:DL 固定 semantic token(label `text-fg-secondary` / value `text-foreground`),無自己的色彩變體,dark mode 由 semantic token 自動切換。加 color variant 不符語意(DL 是資訊展示,非狀態載體)。
+- **無 SizeMatrix**:DL 無 size prop——垂直間距隨 `layout-space` token 感知 density(見「間距」段),但 label / value typography 走 reading mode 固定 tier,不提供 sm / md / lg 變體。不同 density 由 token 自動處理,非 prop 切換。
+
+對應 anatomy story:保留 `Overview` + `ColsMatrix`(元件特有 1 / 2 / auto 欄對照) + `StateBehavior`(空值 `—` / 長值 / 多行)。
+
+---
+
+## 邊界案例
+
+- **Disabled(action cell)**:DescriptionList 主體為唯讀資料呈現,本身無 disabled state;若 `<dd>` 內 consumer 嵌入 inline action(Button / Link),該 action 自行 own disabled,DL 不干預(token 走 Button SSOT)。
+- **Loading**:DL 非 async surface,無 loading prop。若 page-level data 載入中,consumer 應在 DL 外層用 `<Skeleton>`(每組 dt/dd 對應一條 skeleton line)取代;DL 本體不渲染 loading state。
+- **Empty(no items / empty value)**:no items → consumer 應 conditional 渲 `<Empty>` 取代 DL,不渲空 `<dl>`(SR 會讀「empty list」造成混淆);individual value 空 → 渲 `—`(em dash,`text-fg-muted`,已在「無障礙」段 codify)。
+- **Dark mode**:走 semantic token(`text-fg-secondary` / `text-foreground`)自動 adapt。
+- **Density**:垂直 gap 隨 `layout-space` token density-aware(見「間距」段),typography fixed reading mode tier 不變。
+
+---
+
+## 相關
+
+- `../Field/field.spec.md` — 表單輸入（需要編輯的對應元件）
+- `../DataTable/data-table.spec.md` — 多筆同結構資料（table 對應）
+- `../NameCard/name-card.spec.md` — NameCard info fields 的消費者
+- `../../tokens/layoutSpace/layoutSpace.spec.md` — 垂直 gap 的 density 感知 token
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `item-anatomy.spec.md`

package/src/components/Dialog/dialog.spec.md

@@ -0,0 +1,202 @@
+---
+component: Dialog
+family: composite
+variants: {}
+sizes: {}
+traits:
+  - isOverlay
+benchmark:
+  - Radix Dialog primitive: github.com/radix-ui/primitives/tree/main/packages/react/dialog
+  - Ant Design Modal: github.com/ant-design/ant-design/tree/master/components/modal
+  - MUI Dialog: github.com/mui/material-ui/tree/master/packages/mui-material/src/Dialog
+  - Polaris Modal: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Modal
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Dialog 設計原則
+
+## 定位
+
+Modal 對話框，基於 Radix Dialog。用於**需要使用者注意力、阻斷背景互動**的操作流程（建立、編輯、確認）。
+
+**Layout Family**：非上述 family — composite / multi-section（多區塊組合，自 own layout）。
+
+---
+
+## 何時用
+
+- **需要專注的操作流程**：建立 / 編輯複雜表單、多步驟精靈、付款結帳
+- **破壞性動作確認**：刪除、離開不儲存、登出多個裝置
+- **短暫但重要的資訊**：首次引導、重要公告必須被看到才能繼續
+- **需要阻斷背景互動的脈絡**：使用者必須完成或取消此流程才能回到頁面
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 短暫的操作回饋（成功 / 失敗訊息）| `Toast` | Dialog 會阻斷流程，Toast 非阻斷 |
+| 持久的頁面內通知 | `Alert` | Alert 是 inline 嵌入，不浮起 |
+| 側邊操作面板（不需完全阻斷）| `Sheet` | Sheet 從側邊滑入，視覺更輕、常搭配列表 detail |
+| 浮動的精簡選單 | `DropdownMenu` / `Popover` | Dialog 是 modal,DropdownMenu/Popover 是輕量浮層 |
+| Hover 才出現的輔助資訊 | `Tooltip` / `HoverCard` | Dialog 需要明確觸發,hover 不該是 modal 觸發 |
+| 手機全屏編輯 | `Sheet` (bottom / fullscreen) | Dialog 預設 viewport inset,行動裝置用 Sheet 更自然 |
+
+---
+
+## 結構
+
+```
+DialogContent (fixed, centered)
+├── DialogHeader (SurfaceHeader + Close X)
+│   ├── DialogTitle
+│   └── Close button (<Button iconOnly dismiss size="sm" startIcon={X} />)
+├── DialogBody (flex-1 ScrollArea wrap + inner padding div,pb-bottom)
+└── DialogFooter (SurfaceFooter alias)
+    └── Action buttons
+```
+
+**Padding SSOT**：Header / Body / Footer 的 padding + 分隔線由 `patterns/overlay-surface/overlay-surface.spec.md` own——Dialog 與 Popover 共用同一套 primitive，避免 token 漂移。Dialog 特有行為:Header 的 Close 按鈕;Body 用 `<ScrollArea>` wrap(viewport-fill 專用,SSOT 見 overlay-surface.spec.md 「Body overflow canonical」節 + `components/ScrollArea/scroll-area.spec.md`)。
+
+## Density(2026-04-22 v5 校準:繼承 page density,跟 Sheet 對齊)
+
+Dialog **繼承 page `data-density`**,不自設密度 attribute。這是 overlay primitive 的 canonical(跟 `components/Sheet/sheet.tsx` 對齊 — Sheet 不自設 density,繼承 page 層級 `html[data-density]`,見 sheet.tsx line 111 canonical)。
+
+**歷史備忘**:先前曾設 `data-layout-space="lg"` 給 header/body 寬鬆呼吸,但跟 `--chrome-header-height` canonical 衝突(md page dialog header 期望 48,強設 lg 會變 56)。**已於 2026-04-22 v5 撤回**,Dialog 全盤繼承 page density,header 高度 = `--chrome-header-height` 自動對齊(md=48 / lg=56)。
+
+**世界級對照**:
+- Polaris Modal:px 16(= md loose)
+- Material M3 Dialog:px 24(= lg loose)
+- Atlassian Dialog:px 24
+- 我方:跟隨 page density,md=16 / lg=24,兩端都在世界級 range 內。
+
+## Layout
+
+- **水平 padding**：`px-[var(--layout-space-loose)]`（header / body / footer 統一）
+- **Header / Footer 垂直 padding**：`py-[var(--layout-space-tight)]`
+- **Body 垂直 padding**：`pt-[var(--layout-space-tight)]` + `pb-[var(--layout-space-bottom)]`——底部留較大空間，視覺上不壓迫
+
+## Viewport Inset
+
+Modal 與 viewport 四邊保持 `--layout-space-bottom`（48px）最小間距。maxWidth 也受此限制：`min(maxWidth, 100vw - inset*2)`。
+
+## 高度行為
+
+| 模式 | 條件 | 行為 |
+|---|---|---|
+| **預設（填滿）** | 不傳 `autoHeight` | `height = 100vh - inset*2`，body 捲動。防止動態內容（載入資料、展開 section）造成 dialog 跳動 |
+| **autoHeight** | `autoHeight={true}` | 高度隨內容，超過 viewport 時 `max-height` 安全帽。適合內容量已知且穩定的 dialog（確認框、短表單） |
+
+## maxWidth
+
+預設 512px，consumer 可透過 `maxWidth` prop 調整。型別 `string | number`（傳 number 視為 px）。
+
+## 關閉按鈕
+
+> **跨家族 SSOT pointer**:DialogHeader 屬 **Padding-based overlay header 家族**;border / padding / dismiss size / withTabs(tabs 進 header 時 border auto-suppress)的跨家族視覺契約 SSOT 詳 `patterns/header-canonical/header-canonical.spec.md`。本節僅 codify Dialog 特有 close X size + chrome-unbounded rationale。
+
+永遠存在於 DialogHeader 右側。使用 `<Button data-dismiss iconOnly dismiss size="sm" startIcon={X} aria-label="關閉" />`，不可移除——使用者永遠需要明確的關閉手段。
+
+**Size canonical(v5 chrome-unbounded)**:Button native size **sm**(28 md / 32 lg),touch target 亦同。SurfaceHeader 的 `[data-unbounded]` CSS rule 自動對 text variant / dismiss 套負 my `calc((xs-sm)/2)` → **layout 佔位 = 24**(xs 固定)。效果:
+- Header 只有 title + close X → max layout = 24 → header = 24 + 2×tight = **48 md / 56 lg = `--chrome-header-height`** ✓
+- Header 塞 bounded primary(無 `data-unbounded`)→ header 自然長高
+
+**Canonical 來源**:Dialog 是 overlay chrome，corner close X 屬 action group region，必用 Button(非 Inline Action / 非自刻 button)。詳見 `patterns/element-anatomy/item-anatomy.spec.md`「Dismiss canonical」+ `patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」。
+
+## Title
+
+`text-body-lg font-medium truncate`——單行截斷，不換行。
+
+**Header 可成長**:Dialog 提供 `<DialogDescription>` primitive 作副標/補充說明(`mt-[var(--item-gap-label-desc-reading-lg)] text-body text-fg-secondary` — title body-lg 16 + desc body 14 → reading-lg token)。Consumer 傳 title + description 時 header 自然長高(這也是為何 Dialog / Sheet / Popover 的 SurfaceHeader 刻意 **padding-based 而非 fixed-h** — 宣告 chrome 可成長)。詳見 `patterns/overlay-surface/overlay-surface.spec.md`「為什麼 SurfaceHeader 是 padding-based」+ `tokens/uiSize/uiSize.spec.md`「消費 --chrome-header-height 的 2 種實作 pattern」。
+
+## Footer 按鈕
+
+預設 size `md`，與 Field 系統表單元件尺寸一致。按鈕靠右對齊（`justify-end`），間距 `gap-2`。
+
+## 視覺
+
+- **Overlay**：`bg-overlay`
+- **Shadow**：`elevation-200`（浮層級）
+- **圓角**：`rounded-lg`
+- **背景**：`bg-surface-raised`
+- **邊框**：`border-border`
+- **分隔線**（header / footer）：`border-divider`
+
+## 動畫
+
+- 進場：fade-in + zoom-in-95 + slide-in-from-center
+- 離場：fade-out + zoom-out-95 + slide-out-to-center
+
+## 狀態處理的職責邊界
+
+Dialog 是容器，無整體 disabled / loading / empty 狀態——這些屬於內容層的責任：
+
+| 狀態 | 處理方式 |
+|------|---------|
+| **Loading**(內容載入中) | Consumer 在 `DialogContent` 內渲染 Skeleton / CircularProgress,不是讓 Dialog 本身等待開啟 |
+| **Empty**（如步驟 dialog 還沒資料）| Consumer 在 content 區用 `Empty` primitive |
+| **Error**（操作失敗）| Consumer 在 content 區用 `Alert` |
+| **Disabled**（整個 dialog）| N/A——dialog 要麼開著（可互動）要麼關著（不存在）。要鎖操作請 disable 內部個別 Button / Field |
+
+**Dark mode**：由 semantic token（`bg-surface-raised` / `border-border`）自動切換，無自訂 palette。
+
+**Density**:Dialog **繼承 page density**(v5 校準,跟 Sheet 對齊),見上「Density」段。
+
+---
+
+## 禁止事項
+
+- ❌ **不在 Dialog 內 nested Dialog**：modal 疊 modal 會形成焦點陷阱地獄（使用者無法預測 Esc 關哪一層），複雜多步驟流程改用單一 Dialog + 內部步驟切換
+- ❌ **不用 Dialog 顯示非阻斷訊息**：成功 / 失敗的短暫回饋用 Toast；持續性系統狀態用 Alert。Dialog 的阻斷成本過高
+- ❌ **不把長 form wizard 塞 Dialog**：超過 3 步驟或表單高度接近全螢幕的流程改用獨立頁面或 Sheet，Dialog 不適合長時間停留
+- ❌ **不在 Dialog footer 把 primary action 放左側**：CTA 靠右（`justify-end`）是跨平台使用者期待（macOS / Windows / Web 主流皆如此），反向放置會降低可用性
+
+---
+
+## A11y 預設
+
+Radix Dialog 自動處理：
+
+- **Modal 語意**：`role="dialog"` + `aria-modal="true"`
+- **標題綁定**：`<DialogTitle>` 自動成為 `aria-labelledby` 指向對象，screen reader 開啟時讀出標題
+- **Focus trap**：焦點鎖在 Dialog 內，Tab 循環不逃出
+- **Esc 關閉**：按 Esc 自動關閉
+- **Focus return**：關閉時焦點返回 trigger 元素
+- **Overlay click**：點擊 overlay 關閉（可透過 `onPointerDownOutside` 阻止）
+
+Consumer 必須保留 `<DialogTitle>`——即使視覺不顯示，也要用 `VisuallyHidden` 包裹提供給 screen reader。
+
+---
+
+## 為何無 Inspector
+
+Dialog 是 modal 浮層元件,關鍵決策維度是 `maxWidth`(400/480/560/720)× `autoHeight` × `destructive` × open/close 行為——已由 `SizeMatrix`(maxWidth 4 檔) / `HeightBehavior`(viewport-fill vs autoHeight) / `DestructiveMatrix` / `StateBehavior`(open / close / ESC / overlay click) 四張矩陣 + `ColorMatrix`(layout + 視覺 token)完整覆蓋。互動 Inspector 切單一 open/close 不如結構性矩陣對照——Dialog 的正確用法是「照情境選 size / 選 autoHeight」,需要 side-by-side 比對決策。
+
+對應 anatomy story:保留 `Overview` + 元件特有 `HeightBehavior` / `DestructiveMatrix` + `SizeMatrix` + `StateBehavior` + `ColorMatrix`。
+
+---
+
+## 相關
+
+- `../Sheet/sheet.spec.md` — 側邊滑入的輕量替代（共用 Radix Dialog base）
+- `../Toast/toast.spec.md` — 非阻斷的短暫回饋
+- `../Alert/alert.spec.md` — 頁面內持久通知
+- `../Popover/popover.spec.md` — 輕量浮層（non-modal）
+- `../DropdownMenu/dropdown-menu.spec.md` — 浮動選單
+- `../Tooltip/tooltip.spec.md` — hover 輔助資訊
+- `../../patterns/overlay-surface/overlay-surface.spec.md` — Header / Body / Footer padding SSOT（Dialog + Popover 共用）
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `accordion.spec.md`
+- `coachmark.spec.md`
+- `file-viewer.spec.md`
+- `layoutSpace.spec.md`
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `density.spec.md`

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

@@ -0,0 +1,250 @@
+---
+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。若要手動補充,寫在本節之前。
+
+- `command.spec.md`
+- `sheet.spec.md`
+- `sidebar.spec.md`
+- `tree-view.spec.md`
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `density.spec.md`