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

package/src/components/Menu/menu-item.principles.stories.tsx

@@ -0,0 +1,81 @@
+// @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 type { Meta, StoryObj } from '@storybook/react'
+import LinkTo from '@storybook/addon-links/react'
+
+const meta: Meta = {
+  title: 'Design System/Internal/Menu/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── WhenToUse — 何時使用 Menu ──────────────────────
+
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / VsItemAnatomyRule(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>適合 Menu 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          <LinkTo kind="Design System/Internal/Menu/展示" name="基本"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">信箱資料夾切換選單(收件匣 / 草稿 / 已傳送)— 純文字選項</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Internal/Menu/展示" name="前置圖示 + 說明文字"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">通知偏好設定選單 — 前置圖示 + 說明文字</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Internal/Menu/展示" name="頭像"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">指派負責人選單 — 人員頭像列</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Internal/Menu/展示" name="頭像 + 說明文字"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">跨部門選人 — 頭像 + 部門說明文字</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Internal/Menu/展示" name="多選"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">通知管道多選(電子郵件 / 推播 / Slack)</span></LinkTo>
+        </li>
+      </ul>
+      <p className="text-fg-muted mt-3">判斷不確定時:先確認情境是否屬於上面這些「在選單裡挑一個或多個選項」的場景;若不是(例如是可編輯的表單欄位、或需要大塊內容的列表行),改用對應的近親元件,下方「vs 近親元件」段有說明。</p>
+    </div>
+
+      {/* vs 近親元件 */}
+      <div className="prose prose-sm max-w-prose">
+      <p className="font-medium">vs 近親元件</p>
+      <p>MenuItem 是「選單選項列」這個樣式的實際元件;它的排版規則(左側圖示/頭像、文字、右側標記怎麼對齊)與選單選項、列表項、檔案項等共用同一套設計準則。</p>
+      <ul>
+        <li><strong>MenuItem(本元件)</strong>—實際畫出選單一列的元件</li>
+        <li><strong>選項列共用設計準則</strong>—文件層級的規範,定義所有同類列(選單選項 / 列表項 / 檔案項)共通的排版規則</li>
+      </ul>
+      <p className="text-fg-muted">要改的是排版規則(各類列共通)→ 改設計準則文件;要改的是這個元件本身的行為 → 改 MenuItem 元件。</p>
+    </div>
+    </div>
+  ),
+}
+
+// ── CompositionRules — MenuItem 三個 consumer pattern(對齊 Polaris「Related」+ Radix「Use within」)──────
+
+export const CompositionRules: Story = {
+  name: '組合規則',
+  render: () => (
+    <div className="flex flex-col gap-12">
+      <div className="prose prose-sm max-w-prose">
+        <p>MenuItem 是選單選項列的共用排版元件,由以下三類選單元件包起來使用,不會直接寫在產品頁面裡:</p>
+
+        <h4>Pattern 1 — DropdownMenu + MenuItem(action menu)</h4>
+        <p>使用者點擊觸發某個 action(複製 / 刪除 / 重新命名)→ <LinkTo kind="Design System/Components/DropdownMenu/展示" name="基本"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">DropdownMenu</span></LinkTo>(Radix 控制 open / close + keyboard nav,MenuItem 提供 row layout)。</p>
+
+        <h4>Pattern 2 — SelectMenu(Popover + Command + MenuItem)— form value 選擇</h4>
+        <p>使用者選一個 / 多個值寫回 form → <LinkTo kind="Design System/Components/Select/展示" name="四模式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Select</span></LinkTo> / <LinkTo kind="Design System/Components/Combobox/展示" name="四模式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Combobox</span></LinkTo>(內部已組合 SelectMenu + cmdk + MenuItem)。</p>
+
+        <h4>Pattern 3 — ContextMenu + MenuItem(右鍵選單,未來)</h4>
+        <p>右鍵觸發 contextual action → 預留消費者(Radix ContextMenu + MenuItem 同 layout primitive)。</p>
+
+        <p className="text-fg-muted">禁止:在產品頁面裡自己用 <code>&lt;div&gt;</code> 拼一列選單(像 <code>&lt;div className="flex px-2 py-1.5"&gt;</code>)— 一律透過上方的 MenuItem 系選單元件(DropdownMenu / SelectMenu 等,內部消費 MenuItem),才能確保所有選單列的對齊與間距一致。MenuItem 本身是 internal 排版元件,在產品頁面直接裸用會失去外層選單的無障礙 / 鍵盤 / 焦點管理(詳 spec「何時用 / 何時不用」)。各區塊的對齊規則(左側圖示/頭像在 24px 內對齊、文字往下堆疊、右側標記可有可無)由選項列共用設計準則統一規範。</p>
+      </div>
+    </div>
+  ),
+}

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

@@ -21,21 +21,23 @@ benchmark:
 
 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 規格。
+**Layout Family**：本元件是 `patterns/element-anatomy/item-anatomy.spec.md` 所擁有的 **Family 1（Menu item layout）** 消費者。結構繼承其「Menu item layout」章節的 scanning-mode 規格。
 
 ---
 
 ## 結構
 
 ```
-prefix                       content               suffix
-[checkbox?] [icon? | avatar?]  [label + description?]  [tag?]
+prefix                                      content               suffix
+[checkbox?] [icon? | avatar? | content?]  [label + description?]  [tag?]
 ```
 
-- **Prefix**：checkbox（多選，由父層注入）+ startIcon 或 avatar（互斥）
+- **Prefix**：checkbox（多選，由父層注入）+ startIcon 或 avatar 或 startContent（三者互斥）
 - **Content**：label + 可選 description
 - **Suffix**：tag（ml-auto 靠右）
 
+**`startContent`（2026-07-10 加，WM TypeIcon 彩色徽章需求）**：LucideIcon / Avatar 表達不了的自訂 leading 視覺（類型徽章 = 彩底方塊 + glyph、status 組合點等）。**渲染在同一個 prefix 對齊容器內——佔位與排列邏輯跟 startIcon 一模一樣**（gap / 24px 閾值對齊 / shrink 全繼承 `itemPrefixAlignVariants` SSOT，零平行 layout），consumer 唯一責任是節點尺寸對齊 `ICON_SIZE[size]`（sm/md=16px、lg=20px）。與 `endContent` 對稱（同為自訂 ReactNode slot）。disabled 時容器套 `opacity-disabled`（對齊 `tag` / `endContent` 自訂節點同款處理;**與 `avatar` 不變暗的分界**:Avatar 有自己的 self-dim 體系〔`fieldCtx.disabled` 觸發,同一顆 `opacity-disabled` token,avatar.spec.md「Disabled」段〕,MenuItem 非 Field context 故不觸發;startContent 是任意 consumer 節點、無任何 DS context 可自 dim → 容器套 opacity 是唯一可靠機制。放頭像請用 `avatar` prop 非 startContent）。
+
 prefix icon 跟 label 同色（foreground），不是 fg-muted。詳見 item-anatomy.spec.md 的 Icon 色彩原則。
 
 ---
@@ -44,12 +46,12 @@ prefix icon 跟 label 同色（foreground），不是 fg-muted。詳見 item-ana
 
 所有 prefix 元素（checkbox、icon、avatar）共享同一個對齊容器。容器高度決定對齊行為：
 
-| prefix 最大高度 | 容器 | 對齊目標 |
+| prefix 最大高度 | 容器高度(原則) | 對齊目標 |
 |---|---|---|
-| ≤ 24px | `h-[1lh]` | 第一行 label 的垂直中心 |
-| > 24px | `h-[calc(1lh+var(--item-gap-label-desc)+desc_1lh)]` | label + gap + description 文字塊的垂直中心 |
+| ≤ 24px | 一行 label 高(inline) | 第一行 label 的垂直中心 |
+| > 24px | label + gap + 一行 description 的文字塊高(block) | 文字塊的垂直中心 |
 
-**SSOT**:對齊公式封裝於 `patterns/element-anatomy/item-anatomy.tsx` 的 `itemPrefixAlignVariants`(2026-04-23 重構)。MenuItem 消費此 primitive,不自建對齊邏輯;改 gap token(`--item-gap-label-desc`)或 font-size token 一處 → MenuItem 自動同步。
+**SSOT**:對齊公式(CSS calc 細節)封裝於 `patterns/element-anatomy/item-anatomy.tsx` 的 `itemPrefixAlignVariants`(2026-04-23 重構),spec 不重述公式。MenuItem 消費此 primitive,不自建對齊邏輯;改 gap token(`--item-gap-label-desc-scanning[-lg]`;bare token 已不存在,4 變體見 `layoutSpace.css`)或 font-size token 一處 → MenuItem 自動同步。
 
 **24px 是物理限制**——16px icon 在 24px 圓內仍可辨識(內部 icon 下限 12px),但在更小的容器中 icon 會低於可讀閾值。
 
@@ -59,14 +61,19 @@ prefix icon 跟 label 同色（foreground），不是 fg-muted。詳見 item-ana
 
 ---
 
-## startIcon vs avatar
+## startIcon vs avatar vs startContent(怎麼選)
 
-| | `startIcon` | `avatar` |
-|---|---|---|
-| 型別 | `LucideIcon` | `AvatarData` |
-| 角色 | **描述**選項的性質（形容詞） | **代表**選項的身份（名詞） |
-| 尺寸 | 16/20px（icon tier，元件控制） | 由 description 決定：無 desc → 20/24/24px，有 desc → 32/32/40px |
-| 對齊 | 永遠 inline（≤ 24px） | 無 desc → inline；有 desc → block |
+**一句話判準:看內容「是什麼」,不是看喜好** —— 線性圖示 → `startIcon`;人/實體頭像 → `avatar`;其他任何自訂視覺 → `startContent`。每槽綁不同的自動行為,型別即理由:
+
+| | `startIcon` | `avatar` | `startContent` |
+|---|---|---|---|
+| 型別 | `LucideIcon` | `AvatarData` | `ReactNode` |
+| 角色 | **描述**性質（形容詞） | **代表**身份（名詞） | 圖示/頭像表達不了的視覺(類型徽章、狀態組合點) |
+| 尺寸 | 16/20px（**元件自動控**） | 由 description 決定：無 desc → 20/24/24px，有 desc → 32/32/40px(**元件自動推導**) | consumer 自理,對齊 `ICON_SIZE[size]` |
+| disabled | 自動 `fg-disabled` 換色 | 不變暗（自有 fieldCtx self-dim 體系） | 容器自動 `opacity-disabled` |
+| 對齊 | 永遠 inline（≤ 24px） | 無 desc → inline；有 desc → block | inline(同 startIcon 容器) |
+
+**為什麼三槽而不是一個 ReactNode 口**:合成一口(Atlassian `iconBefore: ReactNode` 式)會失去前兩槽的自動行為 —— 每個 consumer 都得自己記尺寸、自己處理 disabled、自己接 hoverCard = 漂移溫床。世界級同構:MUI List 正是三分 —— [`ListItemIcon`](https://mui.com/material-ui/api/list-item-icon/) 與 [`ListItemAvatar`](https://mui.com/material-ui/api/list-item-avatar/) 是**兩個獨立 wrapper 元件**、任意節點則直接放 —— 我們用 props 表達同一套分工。
 
 ### avatar 尺寸推導
 
@@ -150,6 +157,8 @@ Menu 的設計目的是「**快速掃視多個選項挑一個**」。垂直空
 | default | transparent | foreground | — |
 | hover | `--neutral-hover` | foreground | 滑鼠 hover |
 | selected（單選） | `--neutral-selected` | foreground | bg 高亮（不用 ✓ 勾號，避免影響 prefix 對齊） |
+| **selected × hover（疊加）** | `--neutral-selected`（**selected 勝,釘住不變**） | foreground | owner = `item-anatomy.spec.md`「選中 × 互動疊加」格(2026-08-11 全家族統一)。2026-07-04 Q2:bg 是唯一選中指示器,hover 不得洗掉;code = selected 時關 hover bg(menu-item.tsx)。對齊 Ant Menu `:not(-item-selected)` / VS Code list `:hover:not(.selected)` |
+| **selected × 鍵盤焦點（疊加）** | `--neutral-selected-focus`（深一階） | foreground | 同上 owner。鍵盤沒有游標,深一階即游標(WCAG 2.4.7)。**舊文勘誤(2026-08-11)**:先前寫 DropdownMenu「僅鍵盤 cursor 深化」用 `-active`——實作上 Radix 反白滑鼠也觸發(規範與實作不符),且 `-active` 是按壓專屬 token;現已全家統一:滑鼠釘住、鍵盤 `-focus` 深化,無消費者差異 |
 | selected（多選） | transparent | foreground | checkbox 勾選 |
 | disabled | transparent | `--fg-disabled` | disabled prop |
 
@@ -162,7 +171,7 @@ Menu 的設計目的是「**快速掃視多個選項挑一個**」。垂直空
 
 單選和 DropdownMenu RadioItem 統一用 `bg-neutral-selected`。不用 ✓ 勾號——勾號在 prefix 會影響群組內對齊。
 
-disabled 時所有元素（icon、checkbox、文字）統一 `fg-disabled`。
+disabled 時：文字（label / description）與 `startIcon` 套 `fg-disabled`；`checkbox` 套用自身 `disabled` 樣式（非 `fg-disabled`）；`tag` / `endContent` / `startContent` 容器套 `opacity-disabled`（自訂節點自帶配色、不能硬換字色,降透明是唯一通用機制;MUI 佐證:disabled MenuItem 整列 root 直接套 `opacity: disabledOpacity` 連 avatar 都 dim — 我們比它細粒度）；`avatar` 在 MenuItem 內不變暗（Avatar 僅在 disabled Field wrapper context 內自 dim，MenuItem 非 Field wrapper）。
 
 ### 浮層關閉行為
 
@@ -183,7 +192,7 @@ Menu item 的 prefix icon 跟 label 同色（foreground），不是 fg-muted。P
 
 ## Group
 
-群組由 `MenuGroup` 包裹，`py-2`（8px）上下內距。群組緊鄰群組，無額外間距。
+群組由 `MenuGroup` 包裹,`py-2`(8px)上下內距。群組緊鄰群組無額外 margin——相鄰群組由 `[&+&]:border-t border-divider` 自動分隔(上下 py-2 合計 16px 視覺間距;Pattern A,SSOT 見 `item-anatomy.spec.md`「Group auto-separation」)。
 
 ### Group Header
 
@@ -205,10 +214,10 @@ Menu item 的 prefix icon 跟 label 同色（foreground），不是 fg-muted。P
 
 ## 禁止事項
 
-- ❌ `startIcon` 和 `avatar` 不可同時使用
+- ❌ `startIcon` / `avatar` / `startContent` 三者不可同時使用（同一 prefix 位置）
 - ❌ 無 `description` 時不可使用 > 24px 的 avatar
 - ❌ disabled item 不可有 hover 效果
-- ❌ disabled item 內的所有子元件（icon、checkbox、文字）都必須呈現 disabled 狀態——fg-disabled 統一，checkbox 用 disabled 樣式
+- ❌ disabled item 內的子元件不可保持 enabled 外觀——文字 / `startIcon` 套 `fg-disabled`、`checkbox` 用自身 `disabled` 樣式、`tag` / `endContent` / `startContent` 套 `opacity-disabled`（`avatar` 在 MenuItem 內維持原樣，因 Avatar 僅在 disabled Field wrapper context 內自 dim）
 - ❌ header item 不可被選中
 - ❌ 不在 item 內放獨立互動元素（如 Button）——item 本身就是互動單位
 
@@ -216,14 +225,14 @@ Menu item 的 prefix icon 跟 label 同色（foreground），不是 fg-muted。P
 
 ## 何時用 / 何時不用
 
-**MenuItem 是 internal primitive**——不直接使用，透過 `SelectMenu` / `DropdownMenu` 等外層 menu 元件消費。
+**MenuItem 是 internal primitive**——不進 root barrel front-door、不裸用；一般透過 `SelectMenu` / `DropdownMenu` 等外層 menu 元件消費；consumer 自建 nav row 等場景可經 per-component subpath 包裝並自行確認後使用（`.claude/rules/ui-development.md`「Root barrel front-door 排除」SSOT，internal ≠ 禁用）。
 
 | 場景 | 正確做法 |
 |------|---------|
 | 建立操作選單（複製 / 刪除 / 分享）| 用 `DropdownMenu` + `DropdownMenuItem`（內部消費 MenuItem）|
 | 建立選值下拉（選項 + 搜尋）| 用 `SelectMenu`（內部消費 MenuItem）|
 | 建立右鍵選單 | 用未來的 `ContextMenu`（待開發）|
-| 直接在 JSX 中用 `<MenuItem>` | ❌ **禁止**——會失去 menu 外層的 Radix 無障礙 / 鍵盤 / 焦點管理 |
+| 直接在 JSX 中用 `<MenuItem>` | ❌ **禁止**——會失去 menu 外層的 Radix 無障礙 / 鍵盤 / 焦點管理。唯一例外:本元件**自身 stories** 的 internal 展示(demo 容器以 `role="listbox"` 滿足 a11y parent 要求,見 `menu-item.stories.tsx`),產品 code 無豁免 |
 
 ### 消費者
 
@@ -231,6 +240,20 @@ Menu item 的 prefix icon 跟 label 同色（foreground），不是 fg-muted。P
 - `../DropdownMenu/dropdown-menu.tsx` — 操作選單
 - 未來：ContextMenu、CommandPalette
 
+### 近親分界
+
+| | MenuItem(Family 1) | SelectionItem | List item(Family 2) |
+|---|---|---|---|
+| 場景 | 浮層選單 row,掃視挑一個 | form 內 Checkbox / Radio 的 label 佈局 | 內容列表 row,閱讀 |
+| Clamp 預設 | label / desc 各 1 行 | `'none'` 完整閱讀(SSOT 對照表見 `../Checkbox/checkbox.spec.md`「為什麼不像 MenuItem 強制截斷?」) | 依元件(如 FileItem) |
+| SSOT | `item-anatomy.spec.md`「Menu item layout」 | `../SelectionControl/selection-item.spec.md` | `item-anatomy.spec.md`「List item layout」 |
+
+### 常見誤解
+
+- 直接 `<MenuItem>` 進 JSX → ❌(失去外層 Radix / cmdk a11y,見上表)
+- 單選選中要加 ✓ 勾號 → ❌,DS 用 `bg-neutral-selected` 高亮(勾號影響 prefix 對齊,見「選中指示器」)
+- suffix 可塞大塊內容 → ❌,實作寫死 inline 對齊只支援 ≤24px(見「Suffix 對齊(實作限制)」)
+
 ---
 
 ## 為何無獨立 StateBehavior story
@@ -239,15 +262,16 @@ MenuItem 的狀態色(default / hover / selected / disabled)是**結構性的**
 
 獨立 StateBehavior story 會複製 ColorMatrix 內容——MenuItem 的 state 本身就是色彩表達,無額外「時序 / 動畫」可獨立呈現(不像 Accordion 有 expand/collapse 行為)。Inspector 已互動式展示 selected / disabled 單一 variant 的切換。
 
-對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix`(含完整狀態色矩陣) + `SizeMatrix`。
+對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix`(含完整狀態色矩陣)+ `SizeMatrix` + `Accessibility`。
 
 ---
 
 ## 邊界案例
 
-- **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。
+- **Disabled**:`disabled` prop 由 MenuItem primitive own;視覺 `text-fg-disabled`(neutral-6,M24 state>emphasis)、無 hover bg、`aria-disabled="true"`(巢狀 `role="presentation"` 用法時抑制、由外層 primitive 宣告,見「A11y 預設」)、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]`。
+- **極長 label / description**:預設各 clamp 1 行 truncate(見「Clamp 政策」),row 高度恆為兩種之一不被撐高。
 - **Dark mode**:走 semantic token 自動 adapt。
 - **Density**:`size` 由 consumer menu(`Menu` block-tier `compact` / `reading`)決定 row height + padding,MenuItem 自身不持 density state。
 
@@ -263,16 +287,18 @@ MenuItem 的狀態色(default / hover / selected / disabled)是**結構性的**
 
 ## A11y 預設
 
-**ARIA / Pattern**:對齊 [W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/) 對應 pattern。
+**ARIA / Pattern**:對齊 [W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/) 對應 pattern。直接使用時 MenuItem 預設渲染 `role="option"` + `aria-selected` / `aria-disabled`;consumer 把 MenuItem 巢狀在 Radix / cmdk 互動節點內時傳 `role="presentation"`,MenuItem 同步抑制 `aria-selected` / `aria-disabled`(presentation 節點不得掛 ARIA state;ARIA 單一 owner = 外層 primitive),僅保留 `data-selected` / `data-disabled` 供樣式。
 
-**Keyboard 行為**:
+**Keyboard 行為**(由外層選單元件提供,MenuItem 本身不實作任何 key handler,只渲染 row 視覺):
 
 - Tab — focus container
 - ↑/↓ — 導覽 items
 - Enter — activate
 - Esc — 關閉(若在 menu context)
 
-**Focus**:focus-visible ring 對齊 DS canonical(`outline: 2px solid var(--ring)`);focus management 由元件 own。
+以上鍵盤導覽由外層選單元件(SelectMenu 走 cmdk / DropdownMenu 走 Radix)own;MenuItem 為 internal layout primitive,不重複實作鍵盤行為。
+
+**Focus**:focus-visible 時以 `bg-neutral-hover` 背景高亮標示被聚焦的選項(cva base 為 `outline-none` + `focus-visible:bg-neutral-hover`),對齊 menu/listbox option active-highlight 慣例(Material `.Mui-focusVisible` 背景色 / Radix `data-highlighted` / cmdk `[data-selected]`),而非畫 outline ring;focus management 由外層元件 own。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
@@ -280,11 +306,8 @@ MenuItem 的狀態色(default / hover / selected / disabled)是**結構性的**
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `dropdown-menu.spec.md`
+- `item-anatomy.spec.md`
+- `select-menu.spec.md`
 - `selection-item.spec.md`
 - `sidebar.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
-- `opacity.spec.md`

package/src/components/Menu/menu-item.stories.tsx

@@ -0,0 +1,242 @@
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { useState } from 'react'
+import { Mail, Star, Bell, Settings, Plus, Folder, FileText, BarChart3, Bug, Rocket } from 'lucide-react'
+import { MenuItem, MenuGroup, MenuFooter } from './menu-item'
+import { CAT_SOLID, type CategoricalHue } from '@/design-system/tokens/categorical-color'
+import { ProfileCard, ProfileCardDefaultActions } from '@/design-system/components/ProfileCard/profile-card'
+
+// DS-wide canonical:person avatar 必 hover → ProfileCard(含 status / statusMessage / fields
+// / actions / onViewMore,profile-card.spec.md 重要資訊)。demo helper:
+// 真實人像(2026-07-08 sweep):固定 u= key 保 determinism(對齊 avatar.stories.tsx pravatar 慣例)
+const avatarSrc = (name: string, px = 96) => `https://i.pravatar.cc/${px}?u=${name.toLowerCase().replace(/\s+/g, '-')}`
+const personHover = (name: string, subtitle?: string) => (
+  <ProfileCard
+    name={name}
+    subtitle={subtitle ?? 'Design｜D-0042｜EMP-1001'}
+    avatar={{ src: avatarSrc(name), alt: name }}
+    status="online"
+    statusMessage="Out of Office: Back on Monday!"
+    actions={<ProfileCardDefaultActions />}
+    fields={[
+      { label: 'ID', value: 'YHANAX' },
+      { label: 'Employee number', value: '1234567' },
+    ]}
+    onViewMore={() => {}}
+  />
+)
+
+const meta: Meta<typeof MenuItem> = {
+  title: 'Design System/Internal/Menu/展示',
+  component: MenuItem,
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj<typeof MenuItem>
+
+/** Menu 容器 — 模擬浮層外觀。demo 用 role='listbox' 滿足 MenuItem role='option' 的 parent 要求(axe aria-required-parent)。 */
+const MenuContainer = ({ children, width = 320 }: { children: React.ReactNode; width?: number }) => (
+  <div role="listbox" aria-label="Menu demo items" className="rounded-lg bg-surface-raised border border-border overflow-hidden"
+    style={{ boxShadow: 'var(--elevation-200)', width }}>
+    {children}
+  </div>
+)
+
+// ── 基本 ──
+
+export const Default: Story = {
+  name: '基本',
+  render: () => (
+    <MenuContainer><MenuGroup>
+      <MenuItem>收件匣</MenuItem>
+      <MenuItem>草稿</MenuItem>
+      <MenuItem>已傳送</MenuItem>
+    </MenuGroup></MenuContainer>
+  ),
+}
+
+// @story-history: WithStartIcon retired 2026-05-17 per audit Dim 24/25 strict re-run —
+//   違 story-rules.md L42 explicit ban「❌ WithStartIcon+WithEndIcon → ✓ WithIcon grid」。
+//   anatomy.stories.tsx Overview/Inspector/ColorMatrix/SizeMatrix(L218/276/395/572)已 cover startIcon。
+//   WithDescription(下)教 icon+description block layout 是 distinct teaching,保留。
+
+// ── startIcon + description ──
+
+export const WithDescription: Story = {
+  name: '前置圖示 + 說明文字',
+  render: () => (
+    <MenuContainer><MenuGroup>
+      <MenuItem startIcon={Mail} description="每日摘要信件">電子郵件通知</MenuItem>
+      <MenuItem startIcon={Bell} description="即時推播到裝置">推播通知</MenuItem>
+      <MenuItem startIcon={Settings} description="自訂通知偏好">進階設定</MenuItem>
+    </MenuGroup></MenuContainer>
+  ),
+}
+
+// ── Avatar（無 description → inline 20/24px）──
+
+export const AvatarInline: Story = {
+  name: '頭像',
+  render: () => (
+    <MenuContainer><MenuGroup>
+      <MenuItem avatar={{ src: avatarSrc('Alice Chen', 48), alt: "Alice Chen", color: "indigo", hoverCard: personHover('Alice Chen') }}>Alice Chen</MenuItem>
+      <MenuItem avatar={{ src: avatarSrc('Bob Wang', 48), alt: "Bob Wang", color: "magenta", hoverCard: personHover('Bob Wang') }}>Bob Wang</MenuItem>
+      <MenuItem avatar={{ src: avatarSrc('Carol Lin', 48), alt: "Carol Lin", color: "green", hoverCard: personHover('Carol Lin') }}>Carol Lin</MenuItem>
+    </MenuGroup></MenuContainer>
+  ),
+}
+
+// ── Avatar + description（block 32/40px) ──
+
+export const AvatarBlock: Story = {
+  name: '頭像 + 說明文字',
+  render: () => (
+    <MenuContainer><MenuGroup>
+      <MenuItem avatar={{ src: avatarSrc('Alice Chen', 64), alt: "Alice Chen", color: "indigo", hoverCard: personHover('Alice Chen', '設計部門') }} description="設計部門">Alice Chen</MenuItem>
+      <MenuItem avatar={{ src: avatarSrc('Bob Wang', 64), alt: "Bob Wang", color: "magenta", hoverCard: personHover('Bob Wang', '工程部門') }} description="工程部門">Bob Wang</MenuItem>
+      <MenuItem avatar={{ src: avatarSrc('Carol Lin', 64), alt: "Carol Lin", color: "green", hoverCard: personHover('Carol Lin', '行銷部門') }} description="行銷部門">Carol Lin</MenuItem>
+    </MenuGroup></MenuContainer>
+  ),
+}
+
+// ── startContent(自訂 leading 徽章;佔位排列 = startIcon 同容器,見 menu-item.spec.md「結構」)──
+
+/** 類型徽章 demo helper — 消費 CAT_SOLID token pair(彩底 + 深/白字由 token 決定);size-4 = ICON_SIZE sm/md */
+const TypeBadge = ({ hue, glyph: Glyph }: { hue: CategoricalHue; glyph: typeof FileText }) => (
+  <span aria-hidden className={`inline-flex size-4 shrink-0 items-center justify-center rounded-md ${CAT_SOLID[hue]}`}>
+    <Glyph className="size-3" strokeWidth={2.5} />
+  </span>
+)
+
+export const WithStartContent: Story = {
+  name: '自訂前綴內容',
+  render: () => (
+    // 工作項類型設定的左側導覽(Jira / Meegle type settings):類型徽章 = 彩底 + glyph,
+    // LucideIcon 表達不了 → startContent;selected = 目前編輯中的類型
+    <MenuContainer width={224}>
+      <MenuGroup>
+        <MenuItem size="sm" startContent={<TypeBadge hue="indigo" glyph={FileText} />} selected>Task</MenuItem>
+        <MenuItem size="sm" startContent={<TypeBadge hue="red" glyph={Bug} />}>Bug</MenuItem>
+        <MenuItem size="sm" startContent={<TypeBadge hue="turquoise" glyph={Rocket} />}>Release</MenuItem>
+        <MenuItem size="sm" startContent={<TypeBadge hue="purple" glyph={FileText} />} disabled>Epic（已停用）</MenuItem>
+      </MenuGroup>
+    </MenuContainer>
+  ),
+}
+
+// ── 狀態 ──
+
+export const States: Story = {
+  name: '狀態',
+  render: () => (
+    <MenuContainer><MenuGroup>
+      <MenuItem startIcon={Mail}>收件匣</MenuItem>
+      <MenuItem startIcon={Mail} selected>已星標（單選）</MenuItem>
+      <MenuItem startIcon={Mail} disabled>已封存</MenuItem>
+    </MenuGroup></MenuContainer>
+  ),
+}
+
+// ── 多選（checkbox）──
+
+const MultiSelectDemo = () => {
+  const [selected, setSelected] = useState<Record<string, boolean>>({
+    email: true, push: true, slack: false,
+  })
+  const toggle = (key: string) => setSelected((s) => ({ ...s, [key]: !s[key] }))
+  const allKeys = ['email', 'push', 'slack']
+  const checkedCount = allKeys.filter((k) => selected[k]).length
+  const allState = checkedCount === 0 ? false : checkedCount === allKeys.length ? true : ('indeterminate' as const)
+  const toggleAll = () => {
+    const next = allState !== true
+    setSelected(Object.fromEntries(allKeys.map((k) => [k, next])))
+  }
+
+  return (
+    <>
+      <MenuGroup>
+        <MenuItem checkbox checked={selected.email} startIcon={Mail} onClick={() => toggle('email')}>電子郵件</MenuItem>
+        <MenuItem checkbox checked={selected.push} startIcon={Bell} onClick={() => toggle('push')}>推播通知</MenuItem>
+        <MenuItem checkbox checked={selected.slack} startIcon={Settings} onClick={() => toggle('slack')}>Slack</MenuItem>
+        <MenuItem checkbox checked={false} disabled startIcon={Star}>SMS（已停用）</MenuItem>
+      </MenuGroup>
+      <MenuFooter>
+        <MenuItem checkbox checked={allState} onClick={toggleAll}>全部</MenuItem>
+      </MenuFooter>
+    </>
+  )
+}
+
+export const MultiSelect: Story = {
+  name: '多選',
+  render: () => <MenuContainer><MultiSelectDemo /></MenuContainer>,
+}
+
+// ── Group header ──
+
+export const Groups: Story = {
+  name: '群組',
+  render: () => (
+    <MenuContainer>
+      <MenuGroup>
+        <MenuItem header>最近使用</MenuItem>
+        <MenuItem startIcon={FileText}>Q3 產品路線圖.md</MenuItem>
+        <MenuItem startIcon={FileText}>客戶反饋整理</MenuItem>
+      </MenuGroup>
+      <MenuGroup>
+        <MenuItem header>所有專案</MenuItem>
+        <MenuItem startIcon={Folder}>設計系統升級 v2</MenuItem>
+        <MenuItem startIcon={Folder}>行銷活動 2026</MenuItem>
+        <MenuItem startIcon={BarChart3}>業務儀表板</MenuItem>
+      </MenuGroup>
+    </MenuContainer>
+  ),
+}
+
+// ── Creatable ──
+
+export const Creatable: Story = {
+  name: '可建立新項',
+  render: () => (
+    <MenuContainer><MenuGroup>
+      <MenuItem startIcon={Plus}>直接使用「新標籤」</MenuItem>
+    </MenuGroup></MenuContainer>
+  ),
+}
+
+// @story-history: AllSizes retired per F migration 2026-05-15 — anatomy.stories.tsx SizeMatrix auto-compile owns size showcase。
+// ── 完整範例 ──
+
+const FullExampleDemo = () => {
+  const [selected, setSelected] = useState<Record<string, boolean>>({
+    alice: true, bob: false,
+  })
+  const toggle = (key: string) => setSelected((s) => ({ ...s, [key]: !s[key] }))
+  const keys = ['alice', 'bob']
+  const checkedCount = keys.filter((k) => selected[k]).length
+  const allState = checkedCount === 0 ? false : checkedCount === keys.length ? true : ('indeterminate' as const)
+  const toggleAll = () => {
+    const next = allState !== true
+    setSelected(Object.fromEntries(keys.map((k) => [k, next])))
+  }
+
+  return (
+    <MenuContainer>
+      <MenuGroup>
+        <MenuItem header>成員</MenuItem>
+        <MenuItem checkbox checked={selected.alice} onClick={() => toggle('alice')} avatar={{ src: avatarSrc('Alice Chen', 64), alt: "Alice", color: "indigo" }} description="設計部門">Alice Chen</MenuItem>
+        <MenuItem checkbox checked={selected.bob} onClick={() => toggle('bob')} avatar={{ src: avatarSrc('Bob Wang', 64), alt: "Bob", color: "magenta" }} description="工程部門">Bob Wang</MenuItem>
+        <MenuItem checkbox checked={false} avatar={{ src: avatarSrc('Carol Lin', 64), alt: "Carol", color: "green" }} description="行銷部門" disabled>Carol Lin（已離職）</MenuItem>
+      </MenuGroup>
+      <MenuFooter>
+        <MenuItem checkbox checked={allState} onClick={toggleAll}>全部</MenuItem>
+      </MenuFooter>
+    </MenuContainer>
+  )
+}
+
+export const FullExample: Story = {
+  name: '完整範例',
+  render: () => <FullExampleDemo />,
+}