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

package/src/components/DropdownMenu/dropdown-menu.principles.stories.tsx

@@ -0,0 +1,341 @@
+// @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.
+// @story-trait-allow: missing-opensnapshot — 原則頁多個 inline dropdown demo 只為承載規則說明(rule note),
+// forced defaultOpen 會讓 ~10 個浮層互疊;overlay open-state 快照由 dropdown-menu.anatomy.stories.tsx
+// StateBehavior(defaultOpen)canonical 涵蓋(對齊 hover-card.principles.stories.tsx 同 rationale)。
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import {
+  MoreVertical, Copy, Trash2, Share2, Download,
+  ArrowUp, Filter,
+} from 'lucide-react'
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSeparator,
+  DropdownMenuGroup,
+  DropdownMenuLabel,
+} from './dropdown-menu'
+import { Button } from '@/design-system/components/Button/button'
+
+const meta: Meta = {
+  title: 'Design System/Components/DropdownMenu/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+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-3 max-w-md">{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>
+)
+
+// ── WhenToUse — 何時使用 DropdownMenu ──────────────────────
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / VsSelectMenuRule / GroupVsSeparatorRule(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>適合 DropdownMenu 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          <LinkTo kind="Design System/Components/DropdownMenu/展示" name="群組"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">群組 — 帳號選單(個人資料 / 設定 / 登出分組)</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/DropdownMenu/展示" name="後綴"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">後綴 — 收件匣未讀數 badge、外開連結提示</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/DropdownMenu/展示" name="子選單"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">子選單 — 主題切換(淺色 / 深色 / 跟隨系統)</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/DropdownMenu/展示" name="勾選項"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">勾選項 — 表格顯示欄位切換</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/DropdownMenu/展示" name="單選"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">單選 — 檔案清單排序方式</span></LinkTo>
+        </li>
+      </ul>
+      <p className="text-fg-muted mt-3">判斷不確定時:先看「選完之後畫面是否需要保留選中狀態」——需要就改用 Select / SelectMenu。下方的「DropdownMenu vs 選值元件」與「群組 vs 分隔線」範例提供更完整的對照。</p>
+    </div>
+
+      {/* vs 近親 — VsSelectMenuRule — 原 VsSelectMenuRule */}
+      <div>
+      <Rule
+        title="DropdownMenu — 執行動作，選完即關閉"
+        note="典型場景：卡片右上角 ⋮ 三點選單（複製、刪除、分享）。使用者選一個動作、立即執行、選單消失。value 不保留（沒有「選中狀態」）"
+      >
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button variant="tertiary" size="sm" iconOnly startIcon={MoreVertical} aria-label="更多操作" />
+          </DropdownMenuTrigger>
+          <DropdownMenuContent>
+            <DropdownMenuItem startIcon={Copy}>複製</DropdownMenuItem>
+            <DropdownMenuItem startIcon={Share2}>分享</DropdownMenuItem>
+            <DropdownMenuItem startIcon={Download}>匯出</DropdownMenuItem>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem startIcon={Trash2} className="text-error">刪除</DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+        <Label>↑ 執行動作：複製 / 分享 / 刪除，選完關閉，畫面沒有「選中狀態」</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 選值（值要留下）：用 Select / SelectMenu"
+        note="「使用者選某個狀態」「選某個類別」這類選完後值留在 field 裡的場景是選值，用 Select。DropdownMenu 點完就關閉沒有 value 可留"
+      >
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button variant="tertiary">選擇狀態</Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent>
+            <DropdownMenuItem>待處理</DropdownMenuItem>
+            <DropdownMenuItem>進行中</DropdownMenuItem>
+            <DropdownMenuItem>已完成</DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+        <Label warn>↑ 點完選單就關，但「目前選了什麼狀態」沒有視覺保留 → 用 Select</Label>
+      </Rule>
+
+      <Rule
+        title="判斷法：「選完之後畫面需要保留選中狀態嗎？」"
+        note="需要 → Select / SelectMenu；不需要（點完即執行動作）→ DropdownMenu"
+      >
+        <Label>一句話判斷:點完後使用者還需要看到「目前選了什麼」就用 Select / SelectMenu;只是觸發一個動作、選完即關閉就用 DropdownMenu。</Label>
+      </Rule>
+    </div>
+
+      {/* vs 近親 — GroupVsSeparatorRule — 原 GroupVsSeparatorRule */}
+      <div>
+      <Rule
+        title="DropdownMenuGroup — 包裝同類 items 自動分隔（推薦 default）"
+        note="相鄰 Group 之間自動出現 border-divider 分隔線,不需手動加 Separator。對齊 MenuGroup 的 auto-separation 理念,consumer 零手動"
+      >
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button variant="tertiary">帳號選單</Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent>
+            <DropdownMenuGroup>
+              <DropdownMenuLabel>我的帳號</DropdownMenuLabel>
+              <DropdownMenuItem>個人資料</DropdownMenuItem>
+              <DropdownMenuItem>設定</DropdownMenuItem>
+            </DropdownMenuGroup>
+            <DropdownMenuGroup>
+              <DropdownMenuLabel>團隊</DropdownMenuLabel>
+              <DropdownMenuItem>切換 workspace</DropdownMenuItem>
+              <DropdownMenuItem>邀請成員</DropdownMenuItem>
+            </DropdownMenuGroup>
+            <DropdownMenuGroup>
+              <DropdownMenuItem className="text-error">登出</DropdownMenuItem>
+            </DropdownMenuGroup>
+          </DropdownMenuContent>
+        </DropdownMenu>
+        <Label>↑ 三個 DropdownMenuGroup 自動透過 border-divider 分隔,無需手動 Separator</Label>
+      </Rule>
+
+      <Rule
+        title="DropdownMenuSeparator — 明確手動插入分隔（特殊強調場景）"
+        note="Group 內部需要子分組、或強調某個分隔位置時使用。例:單一 Group 內最後一個破壞性動作前想明確加視覺分隔"
+      >
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button variant="tertiary">檔案操作</Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent>
+            <DropdownMenuGroup>
+              <DropdownMenuItem>複製</DropdownMenuItem>
+              <DropdownMenuItem>剪下</DropdownMenuItem>
+              <DropdownMenuItem>貼上</DropdownMenuItem>
+              <DropdownMenuSeparator />
+              <DropdownMenuItem className="text-error">永久刪除</DropdownMenuItem>
+            </DropdownMenuGroup>
+          </DropdownMenuContent>
+        </DropdownMenu>
+        <Label>↑ 同一 Group 內,手動 Separator 在刪除前強調視覺切分</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 用多個 Separator 手動模擬 Group"
+        note="既然 DropdownMenuGroup 自動處理,寫多個 Separator 就是重複勞動 + 容易漏掉或放錯位置"
+      >
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button variant="tertiary">❌ 手動 Separator</Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent>
+            <DropdownMenuLabel>我的帳號</DropdownMenuLabel>
+            <DropdownMenuItem>個人資料</DropdownMenuItem>
+            <DropdownMenuItem>設定</DropdownMenuItem>
+            <DropdownMenuSeparator />
+            <DropdownMenuLabel>團隊</DropdownMenuLabel>
+            <DropdownMenuItem>切換 workspace</DropdownMenuItem>
+            <DropdownMenuItem>邀請成員</DropdownMenuItem>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem className="text-error">登出</DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+        <Label warn>↑ 功能等價但每個分隔都要手寫 → 用 Group 更精確表達「語意分組」</Label>
+      </Rule>
+    </div>
+    </div>
+  ),
+}
+
+export const ItemTypeRule: Story = {
+  name: '項目類型選擇',
+  render: () => {
+    const [showStatus, setShowStatus] = React.useState(true)
+    const [showAssignee, setShowAssignee] = React.useState(true)
+    const [showDue, setShowDue] = React.useState(false)
+    const [sortBy, setSortBy] = React.useState('created')
+    return (
+      <div>
+        <Rule
+          title="Item — 執行一次性動作（選完關閉）"
+          note="複製、刪除、分享、開啟連結等動作。破壞性動作的 prefix icon 和 label 都用 text-error"
+        >
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button variant="tertiary">檔案操作</Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent>
+              <DropdownMenuItem startIcon={Copy} shortcut="⌘C">複製連結</DropdownMenuItem>
+              <DropdownMenuItem startIcon={Download} shortcut="⌘S">下載</DropdownMenuItem>
+              <DropdownMenuSeparator />
+              <DropdownMenuItem startIcon={Trash2} shortcut="⌫" className="text-error">刪除</DropdownMenuItem>
+            </DropdownMenuContent>
+          </DropdownMenu>
+        </Rule>
+
+        <Rule
+          title="CheckboxItem — 即時生效的 on/off toggle（選單保持開啟）"
+          note="顯示 / 隱藏欄位、篩選條件等。選了不關閉選單，讓使用者可一次切多個"
+        >
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button variant="tertiary" startIcon={Filter}>顯示欄位</Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent>
+              <DropdownMenuLabel>表格欄位</DropdownMenuLabel>
+              <DropdownMenuCheckboxItem checked={showStatus} onCheckedChange={setShowStatus}>狀態</DropdownMenuCheckboxItem>
+              <DropdownMenuCheckboxItem checked={showAssignee} onCheckedChange={setShowAssignee}>指派者</DropdownMenuCheckboxItem>
+              <DropdownMenuCheckboxItem checked={showDue} onCheckedChange={setShowDue}>到期日</DropdownMenuCheckboxItem>
+            </DropdownMenuContent>
+          </DropdownMenu>
+          <Label>↑ 即時套用的設定——改了立刻生效,選單保持開啟可繼續切</Label>
+        </Rule>
+
+        <Rule
+          title="RadioItem — 從互斥選項選一（選中後選單保持開啟）"
+          note="排序方式、檢視模式等只能選一個的設定。選中的那一項以選取底色（neutral-selected 背景）標示，不另畫圓點指示器"
+        >
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button variant="tertiary" startIcon={ArrowUp}>排序方式</Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent>
+              <DropdownMenuLabel>依以下排序</DropdownMenuLabel>
+              <DropdownMenuRadioGroup value={sortBy} onValueChange={setSortBy}>
+                <DropdownMenuRadioItem value="created">建立時間</DropdownMenuRadioItem>
+                <DropdownMenuRadioItem value="updated">最後更新</DropdownMenuRadioItem>
+                <DropdownMenuRadioItem value="priority">優先級</DropdownMenuRadioItem>
+              </DropdownMenuRadioGroup>
+            </DropdownMenuContent>
+          </DropdownMenu>
+          <Label>↑ 互斥選一——目前選中的項目以選取底色標示</Label>
+        </Rule>
+      </div>
+    )
+  },
+}
+
+export const DestructiveRule: Story = {
+  name: '破壞性動作規則',
+  render: () => (
+    <div>
+      <Rule
+        title="刪除等不可逆動作：prefix icon + label 都用 text-error"
+        note="prefix icon 是 label 的視覺延伸，與 label 同色才是一體。suffix shortcut 維持 fg-muted（提示性資訊不需跟 error 同色）"
+      >
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button variant="tertiary" size="sm" iconOnly startIcon={MoreVertical} aria-label="更多" />
+          </DropdownMenuTrigger>
+          <DropdownMenuContent>
+            <DropdownMenuItem startIcon={Copy}>複製</DropdownMenuItem>
+            <DropdownMenuItem startIcon={Share2}>分享</DropdownMenuItem>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem startIcon={Trash2} shortcut="⌫" className="text-error">
+              永久刪除
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+        <Label>↑ Trash icon + 「永久刪除」都 text-error；shortcut ⌫ 維持 fg-muted</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 只有 label 變紅，icon 保持 foreground"
+        note="icon 和 label 不同色 → 視覺上像兩個東西，破壞 item 的一體感。prefix icon 永遠跟 label 同色"
+      >
+        <Label warn>（錯誤範例）Trash icon 黑色 + 「刪除」紅色 → 視覺分裂</Label>
+      </Rule>
+
+      <Rule
+        title="不可逆動作用 Separator 跟一般動作隔開"
+        note="刪除 / 取消訂閱等放在選單底部、用 separator 隔開——減少使用者誤觸的可能"
+      >
+        <Label>見上方範例的 Separator 位置（刪除與其他動作中間）</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const SuffixRule: Story = {
+  name: '後綴使用規則',
+  render: () => (
+    <div>
+      <Rule
+        title="鍵盤快捷鍵 — canonical shortcut prop（靠右對齊列尾）"
+        note="使用者熟悉快捷鍵後可跳過選單直接按快捷鍵。shortcut 用 fg-muted 作為輔助資訊色,不搶 label 注意力。標準場景用 `shortcut` prop（走 MenuItem endContent flex slot,真正靠右對齊列尾);`<DropdownMenuShortcut>` child 僅為相容 shadcn 的 escape-hatch,會 inline 附加在 label 尾、不會靠右。"
+      >
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button variant="tertiary">檔案</Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent>
+            <DropdownMenuItem shortcut="⌘N">新增</DropdownMenuItem>
+            <DropdownMenuItem shortcut="⌘O">開啟</DropdownMenuItem>
+            <DropdownMenuItem shortcut="⌘S">儲存</DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </Rule>
+
+      <Rule
+        title="❌ Shortcut 和自訂後綴不混用（同一個 item 只用一種）"
+        note="同一個 item 既有 ⌘S 又有 badge 數量 → 視覺負擔過重，使用者無法一眼判斷哪個是重要資訊"
+      >
+        <Label warn>（錯誤範例）「儲存 [未儲存 3 項] ⌘S」→ 混用造成視覺衝突</Label>
+      </Rule>
+    </div>
+  ),
+}

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

@@ -19,18 +19,20 @@ benchmark:
 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 規格。
+**Layout Family**：本元件是 `patterns/element-anatomy/item-anatomy.spec.md` 所擁有的 **Family 1（Menu item layout）** 消費者。結構繼承其「Menu item layout」章節的 scanning-mode 規格。
 
 ### 與 SelectMenu 的區別
 
 SelectMenu 是**選值**(選完後值留在 field 裡),DropdownMenu 是**執行**(選完後觸發動作,選單關閉)。判斷標準:「選完之後,畫面上是否需要保留選中狀態?」需要 → SelectMenu;不需要 → DropdownMenu。
 
+心智模型:SelectMenu 的選單是 **field 的延伸**(使用者在「編輯欄位裡的值」,trigger 持續顯示當前值);DropdownMenu 的選單是**動作清單**(執行一次性動作後選單消失,畫面不留痕)。CheckboxItem / RadioItem 雖涉「選擇」,屬即時生效設定非選值(見「Item 類型」)。
+
 ---
 
 ## 何時用
 
 - **次要動作集合**：卡片右上角 `⋮` 三點選單（複製、刪除、分享、匯出）
-- **工具列的溢出動作**：ToolBar 放不下的次要操作集中在 more menu
+- **工具列的溢出動作**：Toolbar 放不下的次要操作集中在 more menu
 - **即時生效的設定 toggle**：顯示 / 隱藏欄位、排序方式、主題切換
 - **需要分群或子選單的動作清單**：export as PDF / CSV / JSON 這類多層結構
 
@@ -62,9 +64,15 @@ DropdownMenu                    ← Radix Root，管理開關狀態
       DropdownMenuSubContent    ← 子選單浮層
     DropdownMenuLabel           ← 群組標題（不可互動）
     DropdownMenuSeparator       ← 明確分隔線（consumer 手動放置）
-    DropdownMenuShortcut        ← 鍵盤快捷鍵提示（ml-auto 靠右）
+    DropdownMenuShortcut        ← 鍵盤快捷鍵提示 child(composition escape-hatch;canonical 用 item `shortcut` prop)
 ```
 
+**快捷鍵提示 API（兩條,擇一不混用）**：
+- **Canonical:`<DropdownMenuItem shortcut="⌘C">`** prop —— 渲染進 MenuItem `endContent` 正規後綴 slot(跟 badge / endIcon 同槽,gap / 對齊一致)。**標準場景一律用 prop。**
+- **Escape-hatch:`<DropdownMenuShortcut>` child** —— 保留以相容 shadcn DropdownMenuShortcut idiom(source:https://ui.shadcn.com/docs/components/dropdown-menu 的 `DropdownMenuShortcut` = `ml-auto` span,npm published API)。⚠️ 本 DS 的 MenuItem 把 children 塞進 ItemContent 的 label `<span>`(非 flex row),故 child 上的 `ml-auto` **不會靠右**——⌘N 只會 inline 附加在 label 文字尾端。要真正靠右對齊列尾的後綴,一律用上方 canonical `shortcut` prop。
+- 兩者**字體樣式統一**(`text-caption` + `tracking-shortcut` + `fg-muted`,與 CommandShortcut 一致),但**位置不等價**(prop 靠右對齊列尾;child inline 附加在 label 尾);**同一 item 只用一種**(見「禁止事項」)。
+- 為何不砍 child 只留 prop:`DropdownMenuShortcut` 是 npm published API(對齊 shadcn,fork repo 可能用),硬砍 = breaking;故保留為 escape-hatch,prop 為 canonical preferred。
+
 ### DropdownMenuGroup 的自動分隔
 
 `DropdownMenuGroup` 對齊 `MenuGroup` 的 group separation 設計語言——相鄰的 Group 自動透過 `border-divider` 分隔，**consumer 不需要自己加 `DropdownMenuSeparator`**。
@@ -82,7 +90,7 @@ DropdownMenu                    ← Radix Root，管理開關狀態
 | 邊界 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。
+**為什麼不直接套 `py-2`**：`DropdownMenuContent` 已有 `py-2` 提供 Content 邊界 padding（純視覺呼吸空間；Radix roving focus 依 collection refs + `element.focus()`，不讀 CSS padding，移除 py-2 不影響鍵盤導覽 / focus offset）。若 Group 再套 `py-2` 會 double padding。改用 `mt-2 pt-2` 只加在第二個 Group 起，視覺等價但不 double。
 
 兩種分隔機制的選擇：
 - **用 `DropdownMenuGroup` 包裝同類 items** → 自動分隔（零手動，跟 MenuGroup 理念一致）
@@ -96,7 +104,7 @@ DropdownMenu                    ← Radix Root，管理開關狀態
 |---|---|---|
 | **Item** | 執行一次性動作（複製、刪除、開啟連結） | 執行後關閉選單 |
 | **CheckboxItem** | 切換開關狀態（顯示/隱藏欄位） | 勾選/取消，選單保持開啟 |
-| **RadioItem** | 從互斥選項中選一（排序方式） | 選中後關閉選單 |
+| **RadioItem** | 從互斥選項中選一（排序方式） | 選中後選單保持開啟 |
 | **SubTrigger** | 展開下一層選單 | 不執行動作，展開子選單 |
 | **Label** | 群組標題，提供語義分類 | 不可互動 |
 | **Separator** | 視覺分隔，劃分邏輯群組 | 不可互動 |
@@ -113,9 +121,9 @@ CheckboxItem 和 RadioItem 雖然涉及「選擇」，但它們控制的是**即
 [prefix]  [label]  [suffix]
 ```
 
-- prefix：`DropdownMenuItemIcon` 包裹 startIcon，`h-[1lh]` 對齊第一行 label。icon 跟 label 同色（foreground）
+- prefix：由 `DropdownMenuItem` 的 `startIcon` prop 傳入，經 MenuItem 內部的 prefix 對齊容器（消費 item-anatomy 的 `itemPrefixAlignVariants`，`h-[1lh]` 對齊第一行 label）渲染。icon 跟 label 同色（foreground）
 - label：文字內容，`flex-1`
-- suffix：`DropdownMenuShortcut` 或自行組合的後綴容器，`ml-auto` 靠右。指示型 icon 用 `fg-muted`
+- suffix：canonical 走 item prop（`shortcut` / `badge` / `endIcon` → MenuItem `endContent` 正規 slot，真正靠右對齊列尾）；`DropdownMenuShortcut` child 僅相容用 escape-hatch（inline 附加在 label 尾、**不靠右**,見「快捷鍵提示 API」段）。指示型 icon 用 `fg-muted`
 
 padding 公式：`py = (field-height - 1lh) / 2`，單行時總高度等於同 size 的 Button / Input。
 
@@ -144,7 +152,7 @@ SubTrigger 的 ChevronRight 由元件自動渲染，不需手動加。子選單
 | 邊框 | `border border-border` |
 | 間距 | `sideOffset={8}`（見 `../Popover/popover.spec.md` SSOT） |
 | Align | **跟隨 trigger 位置:左 → `start` / 中 → `center` / 右 → `end`**,見 `../Popover/popover.spec.md`「Align 對齊 canonical(跨浮層 SSOT)」|
-| 最小寬度 | 跟隨觸發元件寬度 |
+| 最小寬度 | `max(180px, 觸發元件寬度)`——窄 trigger 時吃 180px 地板；可用 `minWidth` prop override |
 
 SubContent 使用相同規格，包括 sideOffset。
 
@@ -154,12 +162,14 @@ SubContent 使用相同規格，包括 sideOffset。
 
 透過 `DropdownMenuContent` 的 `size` prop 設定，經 SizeContext 向下傳遞，所有子項目自動套用。
 
-| Size | Label | Icon | Checkbox/Radio 控件 |
+| Size | Label | Icon | Checkbox 控件 |
 |---|---|---|---|
 | 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 |
 
+RadioItem 不渲染 radio 控件——選中以 `bg-neutral-selected` 背景高亮(見 `../Menu/menu-item.spec.md`「選中指示器」),故控件尺寸欄僅適用 CheckboxItem。
+
 DropdownMenu 是掃描模式——使用者快速瀏覽選項，所有尺寸使用 `leading-compact`。
 
 ---
@@ -171,8 +181,10 @@ DropdownMenu 是掃描模式——使用者快速瀏覽選項，所有尺寸使
 | 按鍵 | 行為 |
 |---|---|
 | `↑` `↓` | 移動焦點 |
+| `Home` / `End` | 跳到第一／最後一個 item（`PageUp` / `PageDown` 同） |
+| 首字 typeahead | 打字元自動跳到 **label 符合**的 item——children 為字串時元件自動 forward `textValue`,description / badge / shortcut 不進比對;複雜 children(非純字串)由 consumer 顯式給 `textValue` |
 | `Enter` / `Space` | 執行目前焦點的動作 |
-| `Escape` | 關閉選單（子選單先關子層） |
+| `Escape` | 關閉整個選單（含所有展開子層；Radix root close）。逐層收合用 `←` |
 | `→` | 展開子選單 |
 | `←` | 收合子選單，焦點回到 SubTrigger |
 
@@ -191,13 +203,13 @@ DropdownMenu 是掃描模式——使用者快速瀏覽選項，所有尺寸使
 - ❌ disabled item 不可有 hover 效果
 - ❌ Label 不可被點擊或取得焦點
 - ❌ 不要手動在 SubTrigger 內加 ChevronRight——元件自動渲染
-- ❌ 不要混用 Shortcut 和自訂後綴——同一個 item 只用一種後綴
+- ❌ 不要在同一 item 混用 `shortcut` prop 與 `<DropdownMenuShortcut>` child(兩條後綴 API 擇一;canonical 用 prop)——同一個 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 沒有的維度。
+Item-level default / hover / focused / selected / disabled **色彩**由 MenuItem primitive SSOT 擁有(`patterns/element-anatomy/item-anatomy.spec.md`「選擇 / 狀態視覺規則」),在本元件 `ColorMatrix` story 承載並直接引用 MenuItem token。**selected × highlighted 疊加**:owner = `item-anatomy.spec.md`「選中 × 互動疊加」格(2026-08-11 全家族統一)——**滑鼠 hover 釘住 `bg-neutral-selected` 不變;鍵盤反白(highlighted 且非 :hover)深一階 `bg-neutral-selected-focus`**(`not-hover:` 分流;2026-07-05 D4 原意即鍵盤 cursor,先前實作漏了滑鼠也觸發 highlighted 這條縫,且借用按壓專屬 `-active`,皆已糾正);**僅 RadioItem checked 走此 selected-bg 規則**(checked 底色套外層 Radix RadioItem)。CheckboxItem checked **不套 row bg**——checked 由內層 checkbox 控件表達,highlighted 時仍為 neutral-hover。DropdownMenu 的 `StateBehavior` story 展示**浮層層級特有的動態行為**:open / close 動畫(Radix `data-state` 驅動)、Submenu 展開 / 收起、CheckboxItem toggle(多選不 close)——這些是 item primitive 沒有的維度。
 
 ---
 
@@ -207,7 +219,8 @@ Item-level default / hover / focused / selected / disabled **色彩**由 MenuIte
 - **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)。
+- **Dark mode / density**:走 MenuItem + Popover SSOT 自動 adapt;density 繼承 page(不鎖;DropdownMenu item 高度 = field-height-{size} 隨 page density 變,鎖 md 會釘死 md-scale 對不上 lg 觸發點),SSOT 見 `tokens/density/density.spec.md`。
+- **大量 item(> 100)**:建議上游分頁 / 搜尋收斂或考慮 windowing(對齊 Ant Select / MUI Autocomplete 慣例);本元件無虛擬化——action menu 本不該長到這個量級,超過先重想資訊架構(選值場景改用 SelectMenu 系 + searchable)。
 
 ---
 
@@ -226,11 +239,16 @@ Item-level default / hover / focused / selected / disabled **色彩**由 MenuIte
 
 - Tab — focus trigger
 - Enter / Space / ↓ — 開啟
-- ↑/↓ — 導覽 items
-- Enter — 選擇
+- ↑/↓ — 導覽 items（Home/End 跳首尾項，PageUp/PageDown 同）
+- 首字 typeahead — 打字元自動跳到 label 符合的 item(比對 `textValue`,見「鍵盤操作」表)
+- Enter / Space — 選擇目前焦點的選項
 - Esc — 關閉
 
-**Focus**:Radix primitive 自管 focus trap / restoration / visible ring(`outline: 2px solid var(--ring)` per design-system focus-visible canonical)。
+**Focus**:Radix primitive 自管 focus trap / restoration。鍵盤導覽到的項目以 highlight **底色**標示(Radix `data-[highlighted]:bg-neutral-hover`,本元件刻意採 `data-highlighted` 而非 `:focus-visible` outline ring,跨瀏覽器一致 — 見 dropdown-menu.tsx docblock「Hover / highlight canonical」),不畫 `outline: 2px solid var(--ring)` 外框。**Trigger focus 指示**:非 asChild 裸用的 Trigger 顯示 Button focus canonical ring(`focus-visible:ring-2 ring-ring ring-offset-1`,SSOT = button.tsx);asChild 場景由子元件(通常 Button)自帶同款 ring。
+
+**ARIA composite scroll wrapper**:`DropdownMenuContent` 的 viewport-aware body 仍消費 `ScrollArea`,但 viewport 傳 `viewportTabIndex={null}` 完全省略 generic wrapper 的 `tabindex`。`role="menu"` 內的 focus owner 是 Radix roving-focus `menuitem*` family；額外 `div[tabindex]` 會破壞 required-children 結構。群組 Label 是正常可讀文字,使用 `fg-secondary`(非低對比的 `fg-muted`)。
+
+**Modal trigger focus**:modal menu 開啟時,Root 會把 Trigger 暫時設為 `tabIndex=-1`,與 Radix 對 app subtree 的 `aria-hidden` 同步；關閉後恢復 consumer 原 tab order。此規則由 DropdownMenu SSOT 統一負責,consumer 不各自追蹤 open state。`modal={false}` 不套用此調整。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
@@ -238,13 +256,13 @@ Item-level default / hover / focused / selected / disabled **色彩**由 MenuIte
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `account-menu.spec.md`
+- `action-bar.spec.md`
 - `command.spec.md`
+- `file-viewer.spec.md`
+- `menu-item.spec.md`
+- `popover.spec.md`
+- `select-menu.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`