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

package/src/components/Input/input.spec.md

@@ -0,0 +1,193 @@
+---
+component: Input
+family: 4
+variants: {}
+sizes: {}
+traits:
+  - hasInteractiveStates
+  - isInputLike
+benchmark:
+  - Ant Design Input: github.com/ant-design/ant-design/tree/master/components/input
+  - MUI TextField: github.com/mui/material-ui/tree/master/packages/mui-material/src/TextField
+  - Polaris TextField: github.com/Shopify/polaris/tree/main/polaris-react/src/components/TextField
+  - Carbon TextInput: github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/TextInput
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Input 設計原則
+
+## 定位
+
+Input 是**純文字**的輸入與顯示元件。格式化邏輯為 identity（value → value）——使用者打什麼就存什麼、顯示什麼。
+
+共用規則見 `../Field/field-controls.spec.md`。本文件只記錄 Input 特有的原則。
+
+**Layout Family**：CLAUDE.md 4-Family Model **Family 4（Field control layout）** 消費者。結構繼承 `components/Field/field-controls.spec.md` 的 `fieldWrapperStyles + [startIcon?] [<editable>] [endAction?]` 規格,視覺對齊 Family 1（Menu item）讓 SelectMenu trigger + options 連續一致。
+
+---
+
+## 何時用
+
+- **純文字資料**：姓名、標題、搜尋字串、slug、ID、隨意 label
+- **email / URL / password** 等特殊但仍屬「文字」的資料（搭配 `type="email" / "url" / "password"` + 適合的 `startIcon`）
+- **格式化邏輯是 identity** 的場景——value → value，不需要千分位、不需要 locale、不需要 picker
+- **單行** 輸入（多行用 Textarea）
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 數字 / 金額 / 百分比 | `NumberInput` | 需要千分位、prefix/suffix、locale、precision |
+| 日期 / 日期時間 | `DatePicker` | 需要原生 picker、`Intl.DateTimeFormat` 顯示 |
+| URL + 預覽 / open in new tab | `LinkInput` | 需要 URL 解析、favicon、外開按鈕 |
+| 多行文字（description、note、備註）| `Textarea` | Input 是單行 |
+| 密碼且需複雜性檢查 | `Input` + 外掛驗證 | Input 本身只負責輸入，驗證是 form 層 |
+
+---
+
+## startIcon 的使用場景
+
+startIcon 用於輔助使用者理解「這個 input 是做什麼的」，不是描述 value 的類型。
+
+| 適合 | 範例 |
+|------|------|
+| 搜尋 | `Search` |
+| Email | `Mail` |
+| 密碼 | `Lock` |
+| URL | `Globe` |
+
+startIcon 不隨 value 變化——它描述的是 input 的用途，不是 value 的狀態。
+
+---
+
+## endAction 的常見模式
+
+使用宣告式 API（`InlineActionConfig`），Field 自動根據 size 渲染：
+
+```tsx
+// 顯示/隱藏密碼
+<Input
+  endAction={{ icon: showPwd ? EyeOff : Eye, label: showPwd ? '隱藏密碼' : '顯示密碼', onClick: () => setShowPwd(!showPwd) }}
+/>
+
+// 清除內容（有值時才顯示）
+<Input
+  endAction={query ? { icon: X, label: '清除搜尋', onClick: () => setQuery('') } : undefined}
+/>
+```
+
+| 模式 | Icon | 行為 |
+|------|------|------|
+| 顯示/隱藏密碼 | `Eye` / `EyeOff` | toggle `type="password"` ↔ `type="text"` |
+| 清除內容 | `X` | 清空 value，有值時出現、清空後消失 |
+
+清除按鈕消失後不佔位——input 自然擴展。
+
+---
+
+## Display
+
+`<Input mode="display">` 是 identity 顯示：
+- 有值：原樣輸出
+- null / undefined / 空字串：`—`（em dash），`text-fg-muted`
+
+---
+
+## Loading
+
+`loading?: boolean`(Field SSOT,詳 `Field/field-controls.spec.md` L70-115):右側 endAction 自動顯 `<CircularProgress/>` + `aria-busy="true"`;input 維持可編輯(Ant Input.Search editable 派,反 Material readonly 派,適合 search debounce)。
+
+## 禁止事項
+
+- ❌ startIcon 不可隨 value 變化——它描述用途，不是狀態
+- ❌ 不可用 Input 顯示需要格式化的資料（數字、日期、貨幣）——用對應的 Field 元件
+
+---
+
+## 邊界案例
+
+- **Disabled**:`disabled` prop 由 Field SSOT own(`Field/field-controls.spec.md` State machine 段)。視覺 token:wrapper bg → `bg-fg-disabled-subtle`、text → `text-fg-disabled`(neutral-6,M24 state>emphasis canonical)、startIcon → `text-fg-disabled`、endAction button 自動 disabled、cursor → `cursor-not-allowed`、border 弱化、無 hover/focus ring。`readOnly` 與 `disabled` 視覺分離:readOnly 維持 default text color(可選取複製)、disabled 全面弱化(不可選)。
+- **Loading**:已 codify(見「Loading」段)。`loading=true` 時 endAction slot 自動切 `<CircularProgress/>`,input 仍可編輯(Ant Search 派 idiom)。
+- **Empty(no value)**:placeholder 走 `text-fg-muted`(neutral-7);`disabled + empty` 時 placeholder 切 `text-fg-disabled`(M24 state precedence)。
+- **Dark mode**:走 semantic token 自動 adapt,無 per-component override。
+- **Density**:`size` 由 Field SSOT(sm/md/lg)決定 height + padding;Input 不獨立 own density。
+
+---
+
+## Mode / Validation / a11y
+
+詳見 `../Field/field-controls.spec.md`(Mode / Validation)+ `../Field/form-validation.spec.md`(驗證時機)。
+
+---
+
+## Variant(visual chrome,正交於 mode)
+
+Input 有兩個 visual chrome variant,**獨立於 mode**(mode 是 state,variant 是 chrome look):
+
+| Variant | 視覺 | 適用場景 | 世界級對照 |
+|---------|------|---------|-----------|
+| `'default'`(預設) | bg-surface + 明顯 border + hover/focus 回饋 | 表單 / Field 內嵌 / 標準 edit UI | Material Input / Ant Input default |
+| `'bare'` | 透明 chrome,hover / focus 才出現 border;保留 padding / typography / height | **Toolbar inline editing**(FileViewer zoom input / chart config / rich text toolbar number input / Sidebar inline rename) | VS Code settings input / Figma toolbar number / Notion prop input |
+
+**判斷法**:Input 放在表單或 Field 內 → `default`;放在 Toolbar chrome 或 page-body inline → `bare`。
+
+**`bare` 使用情境的 canonical 要求**:
+- 外層 chrome 必須已提供「這是可編輯」的 affordance(Toolbar 的 icon / prop label / row structure);否則 user 看不到 input chrome 找不到可編輯位置
+- 保留 DS field-height(`h-field-sm/md/lg`)、typography、icon tier、error 視覺——**bare 只動 chrome 不動 sizing**
+
+**禁止**:
+- ❌ 在**表單** context 用 `bare`——表單需要明確的 field chrome 邀請輸入,bare 會失去 affordance
+- ❌ 拿 `bare` 來當「空白 div 替代品」——variant 不是拿掉視覺的工具,而是特定 chrome context 的 canonical
+
+---
+
+## Auto-width(AR46,2026-04-21)
+
+`autoWidth` prop:Input 寬度自動等於「內容寬(value / placeholder)+ startIcon + endAction + padding」,基於 CSS `field-sizing: content`(Chrome 123+ / Safari 17.4+)。
+
+| 屬性 | 行為 |
+|------|------|
+| `autoWidth={false}`(預設)| 走 Field canonical(w-full 或 Field wrapper 規則),寬度固定、跟欄位對齊 |
+| `autoWidth={true}` | wrapper 改 `inline-flex w-auto`;input 改 `field-sizing:content w-auto min-w-0`,寬度隨 value 文字變化 |
+
+**使用情境**:
+- **Inline edit**:FileViewer `ZoomInput`(輸入「100%」縮到三位數寬)、Figma toolbar number input、VS Code setting row
+- **Tag / Chip rename**:選中 chip 進入 inline edit,寬度跟 chip 內容保持視覺一致
+- **Spreadsheet-like cells**:內容寬度自動跟字數走
+
+**禁止**:
+- ❌ **表單 Field 內**——Field 欄位必須欄寬對齊,寬度隨值跳動會破壞 grid layout
+- ❌ **搭配 `variant="default"` 放在主表單區**——auto-width 預設搭 `variant="bare"`(toolbar inline 語意),default chrome 自動對齊 Field canonical
+
+**世界級對照**:VS Code settings inline input 用同 pattern;Notion property field、Airtable cell edit 皆 auto-size。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+---
+
+## 相關
+
+- `../NumberInput/number-input.spec.md` — 數值資料
+- `../DatePicker/date-picker.spec.md` — 日期
+- `../LinkInput/link-input.spec.md` — URL + 預覽 / 外開
+- `../Textarea/textarea.spec.md` — 多行文字
+- `../Field/field-controls.spec.md` — Field Control 共用規則（mode / size / endAction / error）
+
+## A11y 預設
+
+**ARIA / Pattern**:native `<input>` element 預設 a11y;Field wrapper 補 `aria-labelledby` / `aria-invalid` / `aria-describedby`。
+
+**Keyboard 行為**:
+
+- Tab — focus
+- 字母鍵 — 輸入
+- Esc — 清空(若 clearable + 有值)
+
+**Focus**:native input focus ring;DS focus-visible ring(`focus-visible:!border-primary`)由 Field wrapper 提供。
+
+**驗證**: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。若要手動補充,寫在本節之前。
+
+- `time-picker.spec.md`

package/src/components/LinkInput/link-input.spec.md

@@ -0,0 +1,130 @@
+---
+component: LinkInput
+family: 4
+variants: {}
+sizes: {}
+traits:
+  - hasInteractiveStates
+  - isInputLike
+benchmark:
+  - Ant Design Input: github.com/ant-design/ant-design/tree/master/components/input
+  - MUI TextField: github.com/mui/material-ui/tree/master/packages/mui-material/src/TextField
+---
+
+# LinkInput 設計原則
+
+## 定位
+
+LinkInput 是 **URL 的**輸入與顯示元件。外觀基於 Input，但 value 以藍色連結樣式呈現，可直接點擊開啟。核心互動差異：**點擊 value 是開啟連結，不是進入編輯**。
+
+共用規則見 `../Field/field-controls.spec.md`。本文件只記錄 LinkInput 特有的原則。
+
+**Layout Family**：CLAUDE.md 4-Family Model **Family 4（Field control layout）** 消費者。結構繼承 `components/Field/field-controls.spec.md` 的 `fieldWrapperStyles + [startIcon?] [<editable>] [endAction?]` 規格,視覺對齊 Family 1（Menu item）讓 SelectMenu trigger + options 連續一致。
+
+---
+
+## 何時用
+
+- **需要儲存的外部 URL**：網站連結、文件 URL、repo 地址、社群連結
+- **顯示時使用者希望直接點開**：在 readonly / table cell / 設定頁可點擊開啟
+- **需要 URL 格式驗證**（blur 時驗證 protocol + 結構）
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 純字串 slug（`my-project-name`）| `Input` | 不是完整 URL，不需驗證 protocol 與點擊開啟 |
+| Email 地址 | `Input` + `type="email"` | Email 不是 URL,`mailto:` 點擊體驗取決於 OS 設定,非核心需求 |
+| 內部 React Router 路徑 | `Input`（或自訂元件）| Router 路徑不是絕對 URL,LinkInput 的 protocol 驗證會 false reject |
+| Markdown 連結（顯示文字 + URL）| 自訂編輯器 | LinkInput 只處理 URL value,不處理 display text 搭配 |
+| URL 清單（多個 URL）| 多個 LinkInput 或自訂清單元件 | 單一 LinkInput 一次一個 URL |
+
+---
+
+## 兩種顯示狀態（edit mode 內）
+
+### Link 狀態
+
+有合法 URL 且未在編輯中時：
+- value 以 `text-primary` 藍色顯示，hover 加底線，點擊開啟連結
+- 右側 Pencil inline action 觸發編輯模式
+- 點擊 value 是開啟連結，不是編輯——這是 LinkInput 與 Input 的核心互動差異
+
+### Input 狀態
+
+正在編輯、無值、或 URL 格式不合法時：
+- 外觀與 Input 一模一樣（bareInput + placeholder）
+- blur 時驗證格式，合法則自動切回 link 狀態
+- 格式不合法維持 input 狀態 + error 邊框，直到格式正確
+
+---
+
+## 驗證
+
+遵循 Field 共用驗證標準（blur validation）：
+
+1. **blur 時驗證**——使用者離開 field 時才檢查格式
+2. **開始編輯時清除 error**——重新 focus 或開始打字時移除錯誤狀態
+3. **Enter 觸發 blur**——等同離開 field
+4. **Escape 取消編輯**——回復原值，不觸發驗證
+
+URL 格式要求：必須包含 `http://` 或 `https://` protocol。
+
+---
+
+## 空值
+
+沒有 URL 時直接顯示 placeholder 並允許輸入，不需要先按 Pencil——因為沒有連結可以開。
+
+---
+
+## readonly / disabled
+
+與其他 Field 一致：
+- readonly：顯示藍色連結（可點擊），無 Pencil action
+- disabled：連結灰化，不可點擊
+
+---
+
+## 禁止事項
+
+- ❌ 不在 link 狀態下讓點擊 value 進入編輯——點擊連結必須開啟連結
+- ❌ 不在打字過程中即時驗證格式——等 blur
+- ❌ 不省略 protocol（http/https）驗證——裸 domain 不是合法 URL
+
+---
+
+## 為何無 StateBehavior
+
+LinkInput 是 **Field Controls family 成員**——互動狀態(focus / invalid / disabled / readonly)完全繼承 `../Field/field-controls.spec.md` SSOT「Mode 狀態」。LinkInput 特有的狀態(edit 輸入 vs display link-chip)已在 `Overview` 中說明。重寫 StateBehavior = 與 field-controls SSOT 漂移。
+
+對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix` + `SizeMatrix`。互動 state 見 Input 的 `StateBehavior` + field-controls.spec.md。
+
+---
+
+## 相關
+
+- `../Input/input.spec.md` — 純文字 / slug / email 等非 URL 場景
+- `../Field/field-controls.spec.md` — Field Control 共用規則（mode / size / endAction / error）
+- `../Field/form-validation.spec.md` — blur 驗證標準
+
+## A11y 預設
+
+**ARIA / Pattern**:native `<input>` element 預設 a11y;Field wrapper 補 `aria-labelledby` / `aria-invalid` / `aria-describedby`。
+
+**Keyboard 行為**:
+
+- Tab — focus
+- 字母鍵 — 輸入
+- Esc — 清空(若 clearable + 有值)
+
+**Focus**:native input focus ring;DS focus-visible ring(`focus-visible:!border-primary`)由 Field wrapper 提供。
+
+**驗證**: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。若要手動補充,寫在本節之前。
+
+- `file-item.spec.md`
+- `textarea.spec.md`

package/src/components/Menu/menu-item.spec.md

@@ -0,0 +1,290 @@
+---
+component: MenuItem
+family: 1
+variants: {}
+sizes:
+  sm: {}
+  md: {}
+  lg: {}
+traits:
+  - hasInteractiveStates
+  - isInternal
+benchmark:
+  - Radix Menu primitive: github.com/radix-ui/primitives/tree/main/packages/react/menu
+  - Ant Design Menu: github.com/ant-design/ant-design/tree/master/components/menu
+  - Polaris ActionList: github.com/Shopify/polaris/tree/main/polaris-react/src/components/ActionList
+---
+
+# MenuItem 設計原則
+
+## 定位
+
+MenuItem 是所有 menu 類元件的**共用視覺佈局層**——處理 prefix 對齊、尺寸、狀態。SelectMenu、DropdownMenu、未來的 ContextMenu 等都消費它。它只負責 layout（padding、gap、prefix alignment、typography），互動行為由各 menu 的 Radix 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 規格。
+
+---
+
+## 結構
+
+```
+prefix                       content               suffix
+[checkbox?] [icon? | avatar?]  [label + description?]  [tag?]
+```
+
+- **Prefix**：checkbox（多選，由父層注入）+ startIcon 或 avatar（互斥）
+- **Content**：label + 可選 description
+- **Suffix**：tag（ml-auto 靠右）
+
+prefix icon 跟 label 同色（foreground），不是 fg-muted。詳見 item-anatomy.spec.md 的 Icon 色彩原則。
+
+---
+
+## Prefix 對齊——24px 閾值
+
+所有 prefix 元素（checkbox、icon、avatar）共享同一個對齊容器。容器高度決定對齊行為：
+
+| prefix 最大高度 | 容器 | 對齊目標 |
+|---|---|---|
+| ≤ 24px | `h-[1lh]` | 第一行 label 的垂直中心 |
+| > 24px | `h-[calc(1lh+var(--item-gap-label-desc)+desc_1lh)]` | label + gap + description 文字塊的垂直中心 |
+
+**SSOT**:對齊公式封裝於 `patterns/element-anatomy/item-anatomy.tsx` 的 `itemPrefixAlignVariants`(2026-04-23 重構)。MenuItem 消費此 primitive,不自建對齊邏輯;改 gap token(`--item-gap-label-desc`)或 font-size token 一處 → MenuItem 自動同步。
+
+**24px 是物理限制**——16px icon 在 24px 圓內仍可辨識(內部 icon 下限 12px),但在更小的容器中 icon 會低於可讀閾值。
+
+**無 description 時 prefix 上限 24px**——沒有文字塊可對齊,強制 inline。
+
+多行文字超過參考高度時，外層 `items-start` 讓 prefix Y 不隨文字下移。
+
+---
+
+## startIcon vs avatar
+
+| | `startIcon` | `avatar` |
+|---|---|---|
+| 型別 | `LucideIcon` | `AvatarData` |
+| 角色 | **描述**選項的性質（形容詞） | **代表**選項的身份（名詞） |
+| 尺寸 | 16/20px（icon tier，元件控制） | 由 description 決定：無 desc → 20/24/24px，有 desc → 32/32/40px |
+| 對齊 | 永遠 inline（≤ 24px） | 無 desc → inline；有 desc → block |
+
+### avatar 尺寸推導
+
+inline（無 description）= 對應 size 的 Tag 高度：
+
+| sm | md | lg |
+|---|---|---|
+| 20px | 24px | 24px |
+
+block（有 description）= `floor₈(1lh + 2px + desc_1lh)`：
+
+| sm | md | lg |
+|---|---|---|
+| 32px | 32px | 40px |
+
+---
+
+## Size
+
+單行高度對齊 field-height token，與 Button、Input 等互動元件等高。
+
+| Size | 高度 | Label | Description | Icon | Checkbox |
+|---|---|---|---|---|---|
+| sm | `h-field-sm` | `text-body leading-compact` | `text-caption` | 16px | 16px (sm) |
+| md | `h-field-md` | `text-body leading-compact` | `text-caption` | 16px | 16px (md) |
+| lg | `h-field-lg` | `text-body-lg leading-compact` | `text-body leading-compact` | 20px | 20px (lg) |
+
+所有文字使用 `leading-compact` (1.3)——選單選項是短文字，不需要閱讀行距。
+
+description 降一級：sm/md 的 label 14px → description 12px；lg 的 label 16px → description 14px。
+
+---
+
+## Suffix 對齊(實作限制)
+
+依 `item-anatomy.spec.md` 的對齊規則,suffix 應該套用 24px 閾值公式(跟 prefix 同公式但獨立判斷)。但 **MenuItem 的實作把 suffix 寫死成 `h-[1lh]` inline 對齊**——只支援 ≤24px 的小 suffix(Tag、ChevronRight、Badge、計數)。
+
+### 為什麼 hardcode
+
+選單選項的 suffix 99% 是小元素,不會超過 24px。為了避免每個 consumer 都要思考 suffix 對齊規則,MenuItem 直接套用最常見的 inline 對齊。
+
+### 限制
+
+如果你要塞大塊 suffix(thumbnail 40px、stacked badge、multi-line text),**MenuItem 會把它對齊到 label 第一行而不是文字塊中心**,視覺上會跟它修飾的對象失聯。
+
+### 解法
+
+需要大塊 suffix 的場景應該:
+
+1. **重新評估這個東西是不是 menu item**——如果 suffix 是大塊內容,可能需要 ListItem(列表行)而非 menu item
+2. **包一個 wrapper 元件**——consumer 自己組合 prefix + content + 大塊 suffix,套用 item-anatomy.spec.md 的完整 4-slot 規則
+3. 不要 hack `endContent` 塞大東西進去——layout 會壞
+
+---
+
+## Clamp 政策(Label / Description 行數)
+
+| Prop | 預設 | 理由 |
+|---|---|---|
+| `labelMaxLines` | `1` | 選項是供快速掃視的短文字，必須在一行內辨識完 |
+| `descMaxLines` | `1` | 與 label 對稱，維持掃視節奏；description 是補充說明，不是閱讀內容 |
+
+**為什麼 description 也預設 1 行?**
+
+Menu 的設計目的是「**快速掃視多個選項挑一個**」。垂直空間是寶貴的——選單通常要塞 5–20 個選項。如果 description 沒有 clamp,一個過長的 description 會把 item 撐高,破壞 row rhythm,使用者眼睛要重新校準。
+
+整個選單應該只有「**兩種 row 高度**」:
+- 無 description → `field-height`(單行 label)
+- 有 description → `field-height` + 2px + 一行 desc 高度
+
+不能讓 row 高度變成「label 1 行 + desc 1~N 行」這種不可預測的範圍。
+
+**Per-instance override**:consumer 若有合理理由(例如 settings 選單想顯示 2 行說明),可以顯式 `<MenuItem descMaxLines={2} ...>` 覆寫。要顯示完整不截,傳 `descMaxLines="none"`(不能傳 `undefined`,React props 的 destructure default 在 undefined 時會接管,fallback 到預設 `1`)。
+
+---
+
+## 狀態
+
+| 狀態 | 背景 | 文字 | 觸發方式 |
+|---|---|---|---|
+| default | transparent | foreground | — |
+| hover | `--neutral-hover` | foreground | 滑鼠 hover |
+| selected（單選） | `--neutral-selected` | foreground | bg 高亮（不用 ✓ 勾號，避免影響 prefix 對齊） |
+| selected（多選） | transparent | foreground | checkbox 勾選 |
+| disabled | transparent | `--fg-disabled` | disabled prop |
+
+### 選中指示器
+
+| 模式 | 選中指示器 |
+|---|---|
+| 單選 | `bg-neutral-selected` 背景高亮 |
+| 多選 | Checkbox 勾選 |
+
+單選和 DropdownMenu RadioItem 統一用 `bg-neutral-selected`。不用 ✓ 勾號——勾號在 prefix 會影響群組內對齊。
+
+disabled 時所有元素（icon、checkbox、文字）統一 `fg-disabled`。
+
+### 浮層關閉行為
+
+| 模式 | 選了之後 | 原因 |
+|---|---|---|
+| 單選 | **關閉浮層** | 選完就結束 |
+| 多選 | **不關閉** | 需要繼續勾選 |
+| DropdownMenu CheckboxItem | **不關閉** | 同多選邏輯 |
+| DropdownMenu 一般 Item | **關閉** | 執行動作後結束 |
+
+### Prefix icon 色彩
+
+Menu item 的 prefix icon 跟 label 同色（foreground），不是 fg-muted。Prefix icon 是 label 的視覺延伸。
+
+詳見 `item-anatomy.spec.md` 的 Icon 色彩原則。
+
+---
+
+## Group
+
+群組由 `MenuGroup` 包裹，`py-2`（8px）上下內距。群組緊鄰群組，無額外間距。
+
+### Group Header
+
+`header` prop 讓 item 變為群組標題：
+- `font-medium` (500)
+- `text-fg-muted` (neutral-7)
+- 不可選、不可 hover
+- 尺寸與一般 item 相同
+
+---
+
+## Footer（多選）
+
+`MenuFooter` 提供固定底部區域（`border-t` + `py-2`）。
+
+典型用途：「全選」checkbox item，使用 `checked="indeterminate"` 在部分選中時顯示 minus 圖示。
+
+---
+
+## 禁止事項
+
+- ❌ `startIcon` 和 `avatar` 不可同時使用
+- ❌ 無 `description` 時不可使用 > 24px 的 avatar
+- ❌ disabled item 不可有 hover 效果
+- ❌ disabled item 內的所有子元件（icon、checkbox、文字）都必須呈現 disabled 狀態——fg-disabled 統一，checkbox 用 disabled 樣式
+- ❌ header item 不可被選中
+- ❌ 不在 item 內放獨立互動元素（如 Button）——item 本身就是互動單位
+
+---
+
+## 何時用 / 何時不用
+
+**MenuItem 是 internal primitive**——不直接使用，透過 `SelectMenu` / `DropdownMenu` 等外層 menu 元件消費。
+
+| 場景 | 正確做法 |
+|------|---------|
+| 建立操作選單（複製 / 刪除 / 分享）| 用 `DropdownMenu` + `DropdownMenuItem`（內部消費 MenuItem）|
+| 建立選值下拉（選項 + 搜尋）| 用 `SelectMenu`（內部消費 MenuItem）|
+| 建立右鍵選單 | 用未來的 `ContextMenu`（待開發）|
+| 直接在 JSX 中用 `<MenuItem>` | ❌ **禁止**——會失去 menu 外層的 Radix 無障礙 / 鍵盤 / 焦點管理 |
+
+### 消費者
+
+- `../SelectMenu/select-menu.tsx` — 下拉選單浮層
+- `../DropdownMenu/dropdown-menu.tsx` — 操作選單
+- 未來：ContextMenu、CommandPalette
+
+---
+
+## 為何無獨立 StateBehavior story
+
+MenuItem 的狀態色(default / hover / selected / disabled)是**結構性的**——透過 variant(single / multi)× state 的二維矩陣呈現比時序互動更清楚。已在 `ColorMatrix` 用 TOKEN_MAP 完整矩陣覆蓋(單選 multi / 多選 single 各自的 4 state × bg / text / icon / desc token 對照)。
+
+獨立 StateBehavior story 會複製 ColorMatrix 內容——MenuItem 的 state 本身就是色彩表達,無額外「時序 / 動畫」可獨立呈現(不像 Accordion 有 expand/collapse 行為)。Inspector 已互動式展示 selected / disabled 單一 variant 的切換。
+
+對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix`(含完整狀態色矩陣) + `SizeMatrix`。
+
+---
+
+## 邊界案例
+
+- **Disabled**:`disabled` prop 由 MenuItem primitive own;視覺 `text-fg-disabled`(neutral-6,M24 state>emphasis)、無 hover bg、`aria-disabled="true"`、Enter / click 不觸發 onSelect、鍵盤導覽自動 skip(由 consumer SelectMenu / DropdownMenu / cmdk 處理)。已在「選擇 / 狀態視覺規則」段 codify。
+- **Loading**:MenuItem 為單一 row primitive 非 async surface,本身不擁有 loading prop。Async option list 的 loading 由 consumer(SelectMenu / Combobox / DropdownMenu)在 list body 替換為 `<Empty icon={<CircularProgress/>}/>`(SelectMenu SSOT)。
+- **Empty(label-only / icon-only)**:label 為必傳;若無 prefix icon / avatar / checkbox,layout 自動收斂為 `[label] [suffix?]`;若無 suffix(shortcut / endAction / chevron),收斂為純 `[label]`。
+- **Dark mode**:走 semantic token 自動 adapt。
+- **Density**:`size` 由 consumer menu(`Menu` block-tier `compact` / `reading`)決定 row height + padding,MenuItem 自身不持 density state。
+
+---
+
+## 相關
+
+- `../../patterns/element-anatomy/item-anatomy.spec.md` — MenuItem 的 row primitive 繼承規則（prefix / label / suffix 對齊）
+- `../Avatar/avatar.spec.md` — Prefix 的 Avatar 尺寸
+- `../Checkbox/checkbox.spec.md` — CheckboxItem 的視覺規則（DropdownMenu 使用）
+- `../SelectMenu/select-menu.spec.md` — 主要消費者之一
+- `../DropdownMenu/dropdown-menu.spec.md` — 另一個主要消費者
+
+## A11y 預設
+
+**ARIA / Pattern**:對齊 [W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/) 對應 pattern。
+
+**Keyboard 行為**:
+
+- Tab — focus container
+- ↑/↓ — 導覽 items
+- Enter — activate
+- Esc — 關閉(若在 menu context)
+
+**Focus**:focus-visible ring 對齊 DS canonical(`outline: 2px solid var(--ring)`);focus management 由元件 own。
+
+**驗證**: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。若要手動補充,寫在本節之前。
+
+- `selection-item.spec.md`
+- `sidebar.spec.md`
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `opacity.spec.md`