@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

package/src/components/Command/command.spec.md

@@ -0,0 +1,181 @@
+---
+component: Command
+family: composite
+variants: {}
+sizes: {}
+traits:
+  - hasInteractiveStates
+  - isInternal
+benchmark:
+  - cmdk (shadcn Command base): github.com/pacocoursey/cmdk
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Command 設計原則
+
+## 定位
+
+Command 是**搜尋 + 鍵盤導覽的指令清單**——提供搜尋框、分組選項、鍵盤導覽、空狀態。多用於浮層選單內部（SelectMenu）或 Command Palette（Cmd+K）。
+
+**實作基礎**：shadcn passthrough——基於 cmdk + Radix Dialog（Command Palette 模式）。本 DS 保留 shadcn 原結構,視覺樣式以 inline Tailwind class 直接掛在 cmdk primitive 上（`command.tsx`），token 值對齊（非結構繼承）MenuItem / Input / Empty 的 canonical token——改 MenuItem 不會自動連動 Command。
+
+**分類**：Internal primitive——由 SelectMenu 消費（Select / Combobox / PeoplePicker 透過 SelectMenu 使用）。App 不直接使用 Command;若要 Command Palette 類 UX,用本檔 export 的 `CommandDialog`(cmdk + Radix Dialog 包裝,showcase「CommandPalette」story 消費)。
+
+**Layout Family**：非上述 family — composite / multi-section（多區塊組合，自 own layout）。
+
+---
+
+## 何時用
+
+- **SelectMenu 內部搜尋**：Select / Combobox / PeoplePicker 的 searchable 模式底層
+- **Command Palette（Cmd+K）**：全局跨頁搜尋、快速動作入口
+- **需要搜尋過濾 + 鍵盤導覽的選項清單**
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 不需要搜尋的短選項清單（< 6 項）| `DropdownMenu` | DropdownMenu 是操作選單，不含搜尋 |
+| 表單內的單選下拉 | `Select` | Select 自動判斷是否切到 SelectMenu 模式 |
+| 表單內的多選下拉 | `Combobox` | 同上 |
+| 人員選擇 | `PeoplePicker` | 專用人員選擇器（內部會消費 Command）|
+
+---
+
+## 消費者
+
+Command 通常由 `SelectMenu` 或自訂 Command Palette 元件消費——直接使用 Command 很少見，除非建立全新的搜尋清單 UI。
+
+---
+
+## 與 DropdownMenu 的分界
+
+**本節是 SSOT**——DropdownMenu / SelectMenu spec 反向引用此節。
+
+- **DropdownMenu**：**操作選單**——選完觸發動作（複製 / 刪除 / 匯出），選單關閉，選項通常 < 10 項
+- **Command**：**搜尋選值**——有 search input + 大量選項導覽，適合超過 10 項或需要鍵盤搜尋過濾的場景
+
+**判斷法**：問「選項數量 > 10 且使用者需要搜尋嗎？」
+
+- 是 → **Command / SelectMenu**
+- 否（少量、固定清單） → **DropdownMenu**
+
+## 與 SelectMenu 的分界
+
+- **SelectMenu**：Select / Combobox / PeoplePicker 的 searchable 浮層（**由 Field 觸發**,帶有 input field + 選中值回填）
+- **獨立 Command Palette**（Cmd+K）：也用 Command 但**不在 Field 觸發**——透過全域快捷鍵開啟,用於跨頁面搜尋 / 快速動作入口
+
+兩者底層都消費 Command。Field 場景用 SelectMenu（已處理 input binding）；非 Field 場景(Cmd+K)用 `CommandDialog`(cmdk + Radix Dialog 包裝)。
+
+---
+
+## 禁止事項
+
+- ❌ **不在短選單（< 6 項）用 Command**：多此一舉增加認知負擔,改用 DropdownMenu 或 RadioGroup
+- ❌ **Command 不當 form input**：它是選值浮層而非輸入框——表單內選值請用 Select / Combobox,它們會自動決定是否啟用 Command 模式
+- ❌ **Command 搜尋框不是 Field Control**：不對齊 Field size token（不配對 `--field-height-md`）——它是浮層內的搜尋輸入,走 Command 自身的尺寸規格
+- ⚠️ **Inline 嵌頁面 = 次要用法,必須自帶邊框容器**(2026-06-12 user 拍板放寬,原為全面禁止):主用法仍是浮層(SelectMenu 內部 / CommandDialog Cmd+K)——實際產品幾乎都走浮層形態。Inline 嵌頁面是原廠 documented 用法(cmdk README「Render this to show the command menu inline」;shadcn 預設範例即 inline 且包 `rounded-lg border`),允許但**必須自己包有邊框的容器**(rounded + border,對齊 shadcn 同款),且不可拿來替代 SelectMenu / Select(表單選值仍走它們)
+
+---
+
+## A11y 預設
+
+cmdk 自動處理：
+
+- **List 語意**：`role="listbox"` + `aria-activedescendant` 指向目前 highlight 項
+- **搜尋框**：`role="combobox"` + `aria-expanded` / `aria-controls` 指向 list
+- **鍵盤導覽**：cmdk 提供 ↑ / ↓ 移動 highlight、Enter 選取（另支援 vim-style Ctrl+n/p/j/k、Home/End）。cmdk 本身無 Esc handler — Esc 關閉僅在 `CommandDialog`(Cmd+K)模式由 Radix Dialog 的 DismissableLayer 提供;inline `<Command>` 模式按 Esc 無反應
+- **空狀態**：`<CommandEmpty>` 自動帶 `role="presentation"`,不干擾 screen reader 的 list 朗讀
+
+Consumer 無需額外處理 a11y,保留 cmdk 原結構 + 使用 `<CommandInput>` / `<CommandList>` / `<CommandItem>` 即可。
+
+---
+
+## 邊界案例
+
+- **Disabled item**:`<CommandItem disabled>` 透過 cmdk 內建支援,視覺繼承 MenuItem SSOT(`text-fg-disabled` + `aria-disabled=true` + 鍵盤導覽自動 skip + Enter 不觸發 onSelect)。skip 是「不進導覽清單」(cmdk `:not([aria-disabled="true"])` selector)— ↑/↓ 直接跳到下一個可選項,無中途 highlight。
+- **Group heading 不可選中**:heading 是 `aria-hidden` 裝飾 div(group container `role="presentation"`),不參與導覽與選取;SR 經 items wrapper `role="group"` + `aria-labelledby` 取得群組語意。
+- **Empty 後持續打字**:cmdk 每個 keystroke 重新過濾(`filtered.count` 驅動),`<CommandEmpty>` 持續顯示直到有 match;input 不鎖、不清空。
+- **Loading**:Command 本身非 async surface。async option fetch 應由 consumer(SelectMenu / Cmd+K palette)在外層處理 — 將 `<CommandList>` body 切換為 `<Empty icon={<CircularProgress size={48}/>}/>`(對齊 `empty.spec.md`「現有消費者」SelectMenu loading row SSOT,禁止事項見其「禁止事項」loading 條)。Command primitive 不獨立 own loading prop。
+- **Empty(no results)**:`<CommandEmpty>` 自動偵測 search filter result = 0 時渲;consumer 必傳 fallback 文案(預設 cmdk 不渲)。
+- **Dark mode / density**:Command 的 inline Tailwind class 直接消費 semantic token（`bg-neutral-hover` / `text-fg-muted` / `text-fg-disabled` 等），token 在 dark mode 自動切值——非透過 MenuItem / Input / Empty primitive 連動。density 不獨立 own（由 consumer SelectMenu 控）。
+
+---
+
+## 常見誤解
+
+- 「選單一律用 Command」— < 6 項、選完即觸發動作的操作選單是 `DropdownMenu`(見「與 DropdownMenu 的分界」)。
+- 「Command 搜尋框是 Field control」— 不對齊 `--field-height-*`(見「禁止事項」)。
+- 「cmdk `data-selected` = 持續選中態」— 它是鍵盤 / 指標的臨時 roving highlight,故用 `bg-neutral-hover` 而非 `bg-neutral-selected`(見「為何無 StateBehavior」)。
+
+---
+
+## 為何無 Inspector / ColorMatrix / SizeMatrix / StateBehavior
+
+Command 是 **internal primitive**(SelectMenu 底層消費,app 不直接使用,見本 spec「分類」段),視覺 token 對齊既有 primitive 的 canonical 值（inline 寫在 `command.tsx`,非結構消費 primitive):
+
+- **無 Inspector**:Command 無自己的決策性 prop(variant / size / severity),behavior 全部由 cmdk library 處理。該讓消費者 inspect 的是 **SelectMenu**(公開消費入口),不是 Command 本身。
+- **無 ColorMatrix**:Command 的視覺(`CommandItem` / `CommandGroup` / `CommandInput`;`CommandEmpty` 為純 className passthrough 無自帶 class)以 inline Tailwind class 直接消費 semantic token(`bg-neutral-hover` / `text-fg-muted` / `text-fg-disabled` 等,token 值對齊 MenuItem row / Input field 的 canonical 用法),無自己的色彩決策——色彩漂移由 token layer 控制(改 token 連動,改 MenuItem 不連動)。
+- **無 SizeMatrix**:Command 搜尋框與 list items 的尺寸由 **Menu block tier**(consumer SelectMenu 決定 compact / reading),Command 自身無 size prop(見本 spec「禁止事項」:Command 搜尋框不對齊 Field size token)。
+- **無 StateBehavior**:Command item 的 highlight / disabled 由 cmdk 的 `data-[selected]` / `data-[disabled]` attribute 觸發,樣式 inline 寫在 `command.tsx`(`data-[selected='true']:bg-neutral-hover` / `data-[disabled=true]:text-fg-disabled`)。**注意 cmdk `data-selected` 是「鍵盤 / 指標當前 active-highlight」(roving 臨時反白)而非 item-anatomy 的「持續選中態(persistent selected)」**,故刻意用 `bg-neutral-hover`(hover 色)而**非** `item-anatomy.spec.md` 的 `bg-neutral-selected`——對齊 VS Code / Raycast command palette 的臨時 highlight 慣例。Command 層級僅處理 search 過濾與鍵盤導覽,那是 cmdk behavior 不是視覺 state。
+
+對應 anatomy story:保留 `Overview`(展示 internal primitive 的 API surface——CommandInput / CommandList / CommandGroup / CommandItem / CommandEmpty)。深度視覺 / 尺寸對照請查 SelectMenu(consumer)與 MenuItem(item primitive)的 anatomy。
+
+---
+
+## 世界級對照
+
+對齊 M8(binary strict rule 必 ≥3 家世界級對照),「禁短選單用 Command」+「禁直接 app 使用」是本 spec 的 binary strict rule,以下為支撐 rationale。
+
+### Cmd-K palette 結構哲學
+
+| 維度 | 本 DS | Linear | Raycast | VS Code Quick Pick | macOS Spotlight | Notion Cmd+K | Slack Cmd+K |
+|------|-------|--------|---------|--------------------|-----------------|--------------|--------------|
+| Layout | **單欄 + grouped sections** | 單欄 + group | 單欄 + group + secondary action panel | 單欄 + multi-mode prefix(`> ` 命令 / `: ` 行)| 全螢幕 + multi-pane(blur background)| 單欄 + inline page preview | 單欄 + 切 tab(Search / Nav / Settings)|
+| Search input 位置 | **頂端** always visible | 頂端 always | 頂端 always | 頂端 always | 中央 hero | 頂端 always | 頂端 always |
+| 視覺 surface | Dialog overlay(`CommandDialog`)| Popover overlay | Standalone window | inline overlay(top-center)| Full-screen(blur)| Popover overlay | Popover overlay |
+| 觸發 shortcut | **Cmd+K**(Apple)/ Ctrl+K(Windows) | Cmd+K | Hotkey(default Option+Space)| Cmd+P / Cmd+Shift+P | Cmd+Space | Cmd+P / Cmd+/ | Cmd+K |
+| Empty state | `<CommandEmpty>` + 文案 | inline 「No results」 | inline 「No matching commands」 | inline 「No results」 | hides list | inline 「No results」 | inline 「No matches」 |
+| 多 mode | 無(單一搜尋語意)| 無(單一)| 無 | 有(prefix mode `>` `:` `@`)| 有(隱式 routing)| 無 | 有(tab)|
+
+### Primitive vs Consumer 分層
+
+| DS | 本 DS | cmdk lib | Radix UI | shadcn/ui | Material UI |
+|----|-------|----------|----------|-----------|--------------|
+| Internal primitive 命名 | **Command** | cmdk | (無此 primitive,用 `<Combobox>` + filter)| Command | `<Autocomplete>` 一體 |
+| Consumer wrapper 命名 | SelectMenu / Popover+Command(Cmd+K) | (consumer 自包)| Combobox | Combobox / Custom Cmd+K | Autocomplete |
+| 是否 app 直接用 | **禁(必透過 SelectMenu / Popover wrapper)**| 開放 | 開放 | 開放 | 開放 |
+
+## 設計哲學
+
+四個關鍵決策,各自有世界級先例支撐:
+
+**(1) 單欄 + grouped sections(non-multi-pane)— 對齊 Linear / Raycast / VS Code / Notion 多家共識** <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+macOS Spotlight 的 multi-pane / blur background 適合 system-level launcher(全 OS 範圍 routing),但 disruptive — 不適合 inline 元件場景(SelectMenu 內嵌 Cmd-K 模式)。Linear / Raycast / VS Code 共識「單欄 + group」適合 productivity tool 內嵌使用,且 cmdk lib(shadcn/Vercel)default 結構符合此哲學。
+
+捨棄 multi-pane 的代價是「無 inline preview 直觀度」(Spotlight 可預覽檔案內容),但 DS 場景是命令清單非檔案 browser,接受。
+
+**(2) Search input always visible at top — 對齊 Linear / Raycast / Notion / VS Code 共識** <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+input always visible 提示使用者「這是 search-driven」,對齊 input-first mental model。捨「only on focus 才出現 input」(節省垂直空間)的代價是「無法 list 看完再搜尋」,但 Cmd-K 場景 default 預期 search,不是 list browse。
+
+**(3) Cmd+K(Apple)/ Ctrl+K(Windows)為觸發 shortcut — 對齊 Linear / Notion / Vercel / Slack / GitHub 共識** <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+Cmd-K 已成 productivity tool 的 universal idiom(Linear 推廣後 Notion / Vercel / Stripe / Slack 統一),使用者跨 app 預期一致。捨棄 Raycast 的 Option+Space(global launcher conflict)/ Spotlight Cmd+Space(macOS 內建衝突)/ VS Code Cmd+P(file-only,跟 Cmd+Shift+P 命令分流)的差異化代價接受 — 對齊主流 idiom 比差異化重要。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+**(4) Internal primitive 哲學 — app 不直接用 Command,必透過 SelectMenu / Popover+Command wrapper**
+
+cmdk / shadcn / Radix 默認開放 app 直接消費 primitive — 但本 DS 走 Material `<Autocomplete>` 一體 / Polaris 一體封裝哲學,把 search + popover + value-binding 包進 SelectMenu(form context)或 Popover+Command wrapper(global Cmd+K)。
+
+捨棄「app code 直接 import Command 客製」的代價是「自由度受限」(無法在 app 內客製 cmdk filter logic),但 DS 一致性更重要 — 若 SelectMenu / Popover+Command 不夠用,回 DS 開新 wrapper 而不是繞過抽象層(對齊 SSOT 消費 canonical M1)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+---
+
+## 相關
+
+- `../SelectMenu/select-menu.spec.md` — 主要消費者（Select / Combobox / PeoplePicker 的 searchable 浮層）
+- `../DropdownMenu/dropdown-menu.spec.md` — 不需搜尋的操作選單
+- `../Dialog/dialog.spec.md` — Command Palette 的浮層容器(`CommandDialog` 內部 wrap Radix Dialog)
+- cmdk library — 底層搜尋與鍵盤導覽實作

package/src/components/Command/command.stories.tsx

@@ -0,0 +1,280 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { useState, useEffect } from 'react'
+import {
+  Search,
+  FileText,
+  Folder,
+  Settings,
+  User,
+  LogOut,
+  Plus,
+  MoonStar,
+  Sun,
+  Inbox,
+  Star,
+  Archive,
+  GitBranch,
+  Terminal,
+} from 'lucide-react'
+import {
+  Command,
+  CommandInput,
+  CommandList,
+  CommandEmpty,
+  CommandGroup,
+  CommandItem,
+  CommandSeparator,
+  CommandShortcut,
+  CommandDialog,
+} from './command'
+
+const meta: Meta = {
+  title: 'Design System/Internal/Command/展示',
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Command 是 cmdk 的 shadcn passthrough 搜尋 + 鍵盤導覽清單 primitive。App 層級**不直接使用** Command——透過 Select / Combobox / PeoplePicker 的 searchable 模式消費,底層自動切換到 SelectMenu(SelectMenu 包 Command)。唯一可以直接組合 Command 的場景是 Command Palette(Cmd+K)——跨頁全域搜尋與快速動作入口。',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Story 1:Command Palette(Cmd+K)— Linear / Notion / Figma 風格
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+const PaletteDemo = () => {
+  const [open, setOpen] = useState(false)
+
+  useEffect(() => {
+    const down = (e: KeyboardEvent) => {
+      if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault()
+        setOpen((prev) => !prev)
+      }
+    }
+    document.addEventListener('keydown', down)
+    return () => document.removeEventListener('keydown', down)
+  }, [])
+
+  return (
+    <div className="flex flex-col gap-3 max-w-xl">
+      <p className="text-caption text-fg-muted">
+        按下 <kbd className="font-mono bg-muted px-1.5 py-0.5 rounded">⌘K</kbd> (Mac) 或{' '}
+        <kbd className="font-mono bg-muted px-1.5 py-0.5 rounded">Ctrl+K</kbd> (Win) 開啟全域指令面板。
+      </p>
+      <button
+        type="button"
+        onClick={() => setOpen(true)}
+        className="inline-flex items-center gap-2 px-3 py-2 rounded-md border border-border bg-surface text-caption hover:border-border-hover cursor-pointer w-fit"
+      >
+        <Search size={14} className="text-fg-muted" />
+        <span className="text-fg-muted">搜尋或輸入指令…</span>
+        <kbd className="ml-4 font-mono text-footnote bg-muted px-1.5 py-0.5 rounded">⌘K</kbd>
+      </button>
+
+      <CommandDialog open={open} onOpenChange={setOpen}>
+        <CommandInput placeholder="搜尋 issue、人員,或輸入指令…" />
+        <CommandList>
+          <CommandEmpty>找不到符合的結果</CommandEmpty>
+
+          <CommandGroup heading="最近開啟">
+            <CommandItem onSelect={() => setOpen(false)}>
+              <FileText />
+              <span>PRD: 多工作區切換 v2</span>
+              <CommandShortcut>2 天前</CommandShortcut>
+            </CommandItem>
+            <CommandItem onSelect={() => setOpen(false)}>
+              <FileText />
+              <span>Q2 OKR roadmap</span>
+              <CommandShortcut>3 天前</CommandShortcut>
+            </CommandItem>
+            <CommandItem onSelect={() => setOpen(false)}>
+              <Folder />
+              <span>Platform / 監控</span>
+              <CommandShortcut>今天</CommandShortcut>
+            </CommandItem>
+          </CommandGroup>
+
+          <CommandSeparator />
+
+          <CommandGroup heading="快速動作">
+            <CommandItem onSelect={() => setOpen(false)}>
+              <Plus />
+              <span>建立 issue</span>
+              <CommandShortcut>⌘N</CommandShortcut>
+            </CommandItem>
+            <CommandItem onSelect={() => setOpen(false)}>
+              <GitBranch />
+              <span>切換分支…</span>
+              <CommandShortcut>⌘B</CommandShortcut>
+            </CommandItem>
+            <CommandItem onSelect={() => setOpen(false)}>
+              <Terminal />
+              <span>開啟終端機</span>
+              <CommandShortcut>⌃`</CommandShortcut>
+            </CommandItem>
+          </CommandGroup>
+
+          <CommandSeparator />
+
+          <CommandGroup heading="帳號">
+            <CommandItem onSelect={() => setOpen(false)}>
+              <User />
+              <span>個人資料</span>
+            </CommandItem>
+            <CommandItem onSelect={() => setOpen(false)}>
+              <Settings />
+              <span>偏好設定</span>
+              <CommandShortcut>⌘,</CommandShortcut>
+            </CommandItem>
+            <CommandItem onSelect={() => setOpen(false)}>
+              <LogOut />
+              <span>登出</span>
+            </CommandItem>
+          </CommandGroup>
+        </CommandList>
+      </CommandDialog>
+    </div>
+  )
+}
+
+export const CommandPalette: Story = {
+  name: '全域指令面板',
+  render: () => <PaletteDemo />,
+}
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Story 2:Inline Command(不在 Dialog 內,直接嵌入頁面)
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+export const InlineCommand: Story = {
+  name: '行內搜尋清單',
+  render: () => (
+    <div className="flex flex-col gap-3 max-w-md">
+      <p className="text-caption text-fg-muted">
+        Gmail-like 左側 sidebar 頂部搜尋清單——把 Command 直接鑲在頁面上,沒有 Dialog 外殼。
+      </p>
+      <div
+        className="rounded-lg border border-border bg-surface-raised overflow-hidden"
+        style={{ boxShadow: 'var(--elevation-100)' }}
+      >
+        <Command>
+          <CommandInput placeholder="搜尋信件或資料夾…" />
+          <CommandList>
+            <CommandEmpty>沒有符合的項目</CommandEmpty>
+            <CommandGroup heading="資料夾">
+              <CommandItem>
+                <Inbox />
+                <span>收件匣</span>
+                <CommandShortcut>124</CommandShortcut>
+              </CommandItem>
+              <CommandItem>
+                <Star />
+                <span>已加星號</span>
+                <CommandShortcut>8</CommandShortcut>
+              </CommandItem>
+              <CommandItem>
+                <Archive />
+                <span>封存</span>
+                <CommandShortcut>2,340</CommandShortcut>
+              </CommandItem>
+            </CommandGroup>
+            <CommandSeparator />
+            <CommandGroup heading="動作">
+              <CommandItem>
+                <Plus />
+                <span>撰寫新信</span>
+                <CommandShortcut>C</CommandShortcut>
+              </CommandItem>
+            </CommandGroup>
+          </CommandList>
+        </Command>
+      </div>
+    </div>
+  ),
+}
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Story 3:Theme switcher(純動作 command,無 form value 儲存)
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+const ThemeSwitcherDemo = () => {
+  const [theme, setTheme] = useState<'light' | 'dark'>('light')
+
+  return (
+    <div className="flex flex-col gap-3 max-w-md">
+      <p className="text-caption text-fg-muted">
+        純 action palette — 選中立即執行(切 theme),不保留 form value。
+      </p>
+      <div
+        className="rounded-lg border border-border bg-surface-raised overflow-hidden"
+        style={{ boxShadow: 'var(--elevation-100)' }}
+      >
+        <Command>
+          <CommandInput placeholder="切換外觀…" />
+          <CommandList>
+            <CommandEmpty>沒有符合的外觀</CommandEmpty>
+            <CommandGroup heading="外觀">
+              <CommandItem onSelect={() => setTheme('light')}>
+                <Sun />
+                <span>淺色模式</span>
+                {theme === 'light' && <CommandShortcut>當前</CommandShortcut>}
+              </CommandItem>
+              <CommandItem onSelect={() => setTheme('dark')}>
+                <MoonStar />
+                <span>深色模式</span>
+                {theme === 'dark' && <CommandShortcut>當前</CommandShortcut>}
+              </CommandItem>
+            </CommandGroup>
+          </CommandList>
+        </Command>
+      </div>
+    </div>
+  )
+}
+
+export const ThemeSwitcher: Story = {
+  name: '外觀切換器',
+  render: () => <ThemeSwitcherDemo />,
+}
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Story 4:空結果狀態
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+export const EmptyState: Story = {
+  name: '無結果狀態',
+  render: () => (
+    <div className="flex flex-col gap-3 max-w-md">
+      <p className="text-caption text-fg-muted">
+        搜尋框輸入不存在的字(例:"zzz"),CommandEmpty 顯示空狀態文案。
+      </p>
+      <div
+        className="rounded-lg border border-border bg-surface-raised overflow-hidden"
+        style={{ boxShadow: 'var(--elevation-100)' }}
+      >
+        <Command>
+          <CommandInput placeholder="試著輸入「zzz」看空狀態…" />
+          <CommandList>
+            <CommandEmpty>找不到符合「zzz」的結果,試試別的關鍵字。</CommandEmpty>
+            <CommandGroup heading="可用指令">
+              <CommandItem>
+                <FileText />
+                <span>新增文件</span>
+              </CommandItem>
+              <CommandItem>
+                <Settings />
+                <span>開啟設定</span>
+              </CommandItem>
+            </CommandGroup>
+          </CommandList>
+        </Command>
+      </div>
+    </div>
+  ),
+}

package/src/components/Command/command.tsx

@@ -1,4 +1,8 @@
 "use client"
+/**
+ * @internal — DS-internal 單元(per `.claude/rules/ui-development.md` Public vs Internal canonical;spec frontmatter `isInternal`)。
+ * 不進 root barrel front-door;由 SelectMenu(搜尋式選單引擎)等 DS 元件 wrap 消費,end-user app 請用 wrapper 元件。
+ */
 
 import * as React from "react"
 import { type DialogProps } from "@radix-ui/react-dialog"
@@ -25,13 +29,14 @@ const Command = React.forwardRef<
 Command.displayName = CommandPrimitive.displayName
 
 const CommandDialog = ({ children, ...props }: DialogProps) => {
-  // M2 verified 2026-04-25(cmdk/dist/index.js source):cmdk 於 DOM 上 emit
-  // `cmdk-group-heading=""` / `cmdk-group=""` / `cmdk-input-wrapper=""` / `cmdk-input=""` /
-  // `cmdk-item=""` attributes,下列 `[&_[cmdk-*]]:` attribute selectors 皆有對應真實 DOM。
+  // M2 verified 2026-04-25 / 2026-06-11 更正歸因(cmdk/dist source):cmdk 於 DOM 上 emit
+  // `cmdk-group-heading=""` / `cmdk-group=""` / `cmdk-input=""` / `cmdk-item=""` attributes;
+  // `cmdk-input-wrapper=""` 非 cmdk emit — 是本檔 CommandInput 自設的 wrapper div attribute(shadcn 慣例)。
+  // 下列 `[&_[cmdk-*]]:` attribute selectors 皆有對應真實 DOM。
   return (
     <Dialog {...props}>
       <DialogContent className="overflow-hidden p-0 shadow-[var(--elevation-200)]">
-        <Command className="[&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-fg-muted [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-group]]:px-2 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5">
+        <Command className="[&_[cmdk-group-heading]]:px-3 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-fg-muted [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-group]]:px-3 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-3 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5">
           {children}
         </Command>
       </DialogContent>
@@ -43,7 +48,7 @@ const CommandInput = React.forwardRef<
   React.ElementRef<typeof CommandPrimitive.Input>,
   React.ComponentPropsWithoutRef<typeof CommandPrimitive.Input>
 >(({ className, ...props }, ref) => (
-  <div className="flex items-center border-b px-3" cmdk-input-wrapper="">
+  <div className="flex items-center border-b border-divider px-3" cmdk-input-wrapper="">
     <Search className="mr-2 h-4 w-4 shrink-0 text-fg-muted" />
     <CommandPrimitive.Input
       ref={ref}
@@ -102,7 +107,7 @@ const CommandGroup = React.forwardRef<
   <CommandPrimitive.Group
     ref={ref}
     className={cn(
-      "overflow-hidden p-1 text-foreground [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:py-1.5 [&_[cmdk-group-heading]]:text-caption [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-fg-muted",
+      "overflow-hidden p-1 text-foreground [&_[cmdk-group-heading]]:px-3 [&_[cmdk-group-heading]]:py-1.5 [&_[cmdk-group-heading]]:text-caption [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-fg-muted",
       className
     )}
     {...props}
@@ -130,7 +135,7 @@ const CommandItem = React.forwardRef<
   <CommandPrimitive.Item
     ref={ref}
     className={cn(
-      "relative flex cursor-default gap-2 select-none items-center rounded-md px-2 py-1.5 text-body outline-none data-[disabled=true]:pointer-events-none data-[selected='true']:bg-neutral-hover data-[selected=true]:text-foreground data-[disabled=true]:text-fg-disabled [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+      "relative flex cursor-default gap-2 select-none items-center rounded-md px-3 py-1.5 text-body outline-none data-[disabled=true]:pointer-events-none data-[selected=true]:bg-neutral-hover data-[selected=true]:text-foreground data-[disabled=true]:text-fg-disabled [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
       className
     )}
     {...props}
@@ -159,7 +164,7 @@ CommandShortcut.displayName = "CommandShortcut"
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const commandMeta = {
   component: 'Command',
-  family: null, // non-family composite / overlay / layout
+  family: 'composite', // 對齊 command.spec.md frontmatter family: composite(SSOT)
   variants: {
 
   },

package/src/components/Command/index.ts

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

package/src/components/DataTable/cell-registry.tsx

@@ -33,7 +33,7 @@ import { LinkInput } from '@/design-system/components/LinkInput/link-input'
 import { Checkbox } from '@/design-system/components/Checkbox/checkbox'
 import { Button } from '@/design-system/components/Button/button'
 import type { PersonValue } from '@/design-system/components/PeoplePicker/person-display'
-import { FieldSurfaceProvider } from '@/design-system/components/Field/field-context'
+import { FieldSurfaceProvider, FieldSurfaceSizeProvider } from '@/design-system/components/Field/field-context'
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
@@ -119,9 +119,12 @@ function StringCell({ value, meta, mode, size, isDisabled, autoRowHeight, onComm
   //   - 互動(Input):Esc cancel / Enter commit / blur commit
   const v = value != null ? String(value) : ''
   if (mode === 'display') {
+    // size 必傳:DataTable cell 字級隨 size 變(sm/md text-body / lg text-body-lg),
+    // 對齊 Field family size→font SSOT(field-wrapper.tsx:60-64)。漏傳 → fallback md → lg 表格
+    // 字卡 14px 跟 Select/Date 等有傳 size 的 cell 不一致(2026-06-08 user 抓 frozen string 欄字偏小)。
     return autoRowHeight
-      ? <Textarea variant="naked" mode={displayOrDisabled(isDisabled)} value={v} className={clampClass} />
-      : <Input variant="naked" mode={displayOrDisabled(isDisabled)} value={v} />
+      ? <Textarea variant="naked" mode={displayOrDisabled(isDisabled)} value={v} size={size} className={clampClass} />
+      : <Input variant="naked" mode={displayOrDisabled(isDisabled)} value={v} size={size} />
   }
   if (autoRowHeight) {
     // 2026-05-14 I8 fix(per codex verdict + user 抓「edit cell shrink」):
@@ -171,12 +174,19 @@ function NumberCell({ value, meta, mode, size, isDisabled, onCommit, onCancel, o
   // currency 透過 columnType-aware prefix:type='currency' → 預設 '$'(可 override)
   const isCurrency = meta?.type === 'currency'
   const prefix = isCurrency ? (meta?.prefix ?? '$') : meta?.prefix
+  // React #310 fix:useState 必在 display early-return 前無條件呼叫。同一 memo'd cell instance
+  // 在 display↔edit 切換時被重用(render site 無 key={mode},data-table.tsx:1352),hook 數量不可變,
+  // 否則 Rules of Hooks violation → React #310 crash。對齊 combobox/select hoist pattern。
+  const initial = typeof value === 'number' ? value : null
+  const [localValue, setLocalValue] = React.useState<number | null>(initial)
   if (mode === 'display') {
     return (
       <NumberInput
         variant="naked"
         mode={displayOrDisabled(isDisabled)}
         value={value as number | null}
+        // size 必傳(同 StringCell)— currency/number cell 字級隨 DataTable size 變,對齊 Field SSOT。
+        size={size}
         prefix={prefix}
         suffix={meta?.suffix}
         precision={meta?.precision}
@@ -188,8 +198,7 @@ function NumberCell({ value, meta, mode, size, isDisabled, onCommit, onCancel, o
   // (`value={value ?? ''}`)— 若 NumberCell 以 `defaultValue` 傳入,NumberInput value=undefined → ''
   // empty。對齊 cell-as-input「edit mode 自動帶入 display 值」(對齊 Notion / Airtable 共識),
   // 改用 local state controlled。User typing → setLocalValue;blur/Enter → onCommit(localValue)。
-  const initial = typeof value === 'number' ? value : null
-  const [localValue, setLocalValue] = React.useState<number | null>(initial)
+  // (initial + useState 已 hoist 到 display-return 前 — 見上方 React #310 fix。)
   return (
     <NumberInput
       autoFocus
@@ -501,7 +510,11 @@ function buildCellWithSurface(Inner: ComponentType<CellComponentProps>, key: str
   const CellWithSurface = React.memo(function CellWithSurface(props: CellComponentProps) {
     return (
       <FieldSurfaceProvider surface="table-cell">
-        <Inner {...props} />
+        {/* 2026-06-08:把 table-density size 經獨立 surface-size context 注給 child Field controls,
+            漏傳 size 的 cell 也自動繼承(根治「新 cell 漏傳 size」class);size primitive 不破壞 memo identity。*/}
+        <FieldSurfaceSizeProvider size={props.size}>
+          <Inner {...props} />
+        </FieldSurfaceSizeProvider>
       </FieldSurfaceProvider>
     )
   })