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

package/src/components/Chip/chip.spec.md

@@ -86,7 +86,7 @@ Filter chip 的「移除這個 filter」動作已由「再點一次 deselect」
 
 ### 為什麼不需要 checkmark-on-selected
 
-Material 3 filter chip 在 selected 時會把 startIcon 換成 `Check`。我們不做，因為視覺層已經用 **primary-hover border + text（底色維持 surface 不變）**明確表達 selected 狀態，再加 icon 是冗餘信號。
+Material 3 filter chip 在 selected 時會把 startIcon 換成 `Check`。我們不做，因為視覺層已經用 **primary border + text（底色維持 surface 不變）**明確表達 selected 狀態，再加 icon 是冗餘信號。
 
 ---
 
@@ -108,10 +108,12 @@ Chip **只有一個 size**，對應 `h-field-sm`（md density 28px / lg density
 |---|---|
 | **Default** | `bg-surface border-border text-fg-secondary`（未選文字用 neutral-8，對齊 SegmentedControl / Tabs 未選狀態；hover 才轉 `text-foreground`）|
 | **Hover**（未選）| `hover:border-border-hover`（對齊 Input / SegmentedControl hover 的 border 加深一階）|
-| **Selected** | `border-primary-hover text-primary-hover`，底色維持 `bg-surface` 不變（primary-hover 同時染 border + text，不染底色，跟 SegmentedControl 一致）|
+| **Selected** | `border-primary text-primary`，底色維持 `bg-surface` 不變（primary base 同時染 border + text，不染底色，跟 SegmentedControl 一致）|
+| **Hover（選中之上）** | `border-primary-hover text-primary-hover`——選中元素的 hover = 同色相升 hover 階（2026-07-06 拍板；Button pressed hover 家族 + Ant active hover 同派），**不用** neutral 灰底 |
 | **Disabled** | `cursor-not-allowed text-fg-disabled`，border 維持 `border-border` 不變色 |
+| **Disabled × Selected** | disabled 全滅（primary 描邊/染字一併退場 → `border-border text-fg-disabled`）——M24 state > emphasis，Checkbox checked+disabled 全滅同族（2026-07-07 補明文，原 code 只滅字不滅框 = 半滅已修） |
 
-Hover 和 selected 的色彩都對齊系統 canonical 規則，跟 SegmentedControl / Input / Tabs underline 使用同一套 primary-hover token，保持選中語意的視覺統一。
+選中色對齊系統選中 canonical（semantic.css「選中狀態」段 SSOT），跟 SegmentedControl / Tabs underline 使用同一套 **primary base** token——2026-07-06 user 拍板自 primary-hover 改 base（Ant / Atlassian / Material 三家實錘「瞬時弱、持續強」：hover 階專屬瞬時態，持續選中站 base）。**❌ 選中態不得用 primary-hover**（那是瞬時 hover 專用階）。
 
 ---
 
@@ -225,7 +227,7 @@ ColorMatrix 已建:展示 default / hover / selected / disabled 四狀態的 bg
 - Tab（再按一次）— 離開整組
 - Enter / Space — 切換選取
 
-**Focus**:整組 chip 採 roving tabindex——Tab 進入整組、方向鍵在組內移動焦點、再按 Tab 離開整組（不是 Dialog 那種把焦點鎖在裡面、Tab 無法離開的 focus trap）。focus-visible 時顯示 `2px solid var(--ring)` 焦點環。
+**Focus**:整組 chip 採 roving tabindex——Tab 進入整組、方向鍵在組內移動焦點、再按 Tab 離開整組（不是 Dialog 那種把焦點鎖在裡面、Tab 無法離開的 focus trap）。focus-visible 時顯示 focus ring（`focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1`,以 box-shadow 實作並 `outline-none`）。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
@@ -234,4 +236,5 @@ ColorMatrix 已建:展示 default / hover / selected / disabled 四狀態的 bg
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `badge.spec.md`
+- `pagination.spec.md`
 - `tag.spec.md`

package/src/components/Chip/chip.tsx

@@ -35,7 +35,7 @@ import {
  * ── State ──
  *   default   bg-surface border-border text-fg-secondary
  *   hover     border-border-hover text-foreground（對齊 Input / SegmentedControl）
- *   selected  bg-surface（不變） border-primary-hover text-primary-hover
+ *   selected  bg-surface（不變） border-primary text-primary
  *   disabled  cursor-not-allowed text-fg-disabled
  *
  * ── 詳見 chip.spec.md ──
@@ -56,14 +56,26 @@ const chipVariants = cva(
     'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',
     // hover（未選）：border 加深一階 + 文字轉深，對齊 Input / SegmentedControl hover
     'hover:border-border-hover hover:text-foreground',
-    // selected: 文字 + 邊框都用 primary-hover,底色維持 bg-surface 不變
-    //   ── pill 風格 canonical 選中規則,跟 SegmentedControl 完全一致:
-    //      primary-hover 同時染文字和線條;底色不改 (不用 primary-subtle)。
-    'data-[state=on]:border-primary-hover data-[state=on]:text-primary-hover',
+    // selected: 文字 + 邊框都用 primary base,底色維持 bg-surface 不變
+    //   ── pill 風格 canonical 選中規則,跟 SegmentedControl 完全一致(SSOT = semantic.css「選中狀態」段):
+    //      primary base 同時染文字和線條;底色不改 (不用 primary-subtle)。
+    //   2026-07-06 user 拍板:持續選中 hover 階 → base — Ant(pagination/tabs/input focus 全 base)/
+    //   Atlassian(selected = brand 同顆)/ Material 3(active tab = primary)三家實錘「瞬時弱、持續強」;
+    //   hover 階專屬瞬時態(hover/預覽),持續選中站 base。
+    'data-[state=on]:border-primary data-[state=on]:text-primary',
+    // 選中之上的 hover = 同色相升 hover 階(2026-07-06 user 拍板;Button pressed hover
+    // data-[state=on]:hover:text-primary-hover 家族 + Ant active 頁 hover = colorPrimaryHover
+    // 同派)。原本靠 CSS 平手 source-order 讓選中「碰巧」贏過未選 hover(靜止無回饋)= 脆弱,
+    // 顯式宣告一併解掉。
+    'data-[state=on]:hover:border-primary-hover data-[state=on]:hover:text-primary-hover',
     // disabled：cursor-not-allowed + 鎖 hover 不變色
     // 不用 pointer-events-none（否則 cursor-not-allowed 不會顯示）
     'disabled:cursor-not-allowed disabled:text-fg-disabled',
     'disabled:hover:border-border disabled:hover:text-fg-disabled',
+    // disabled × selected 疊加(2026-07-07 user 拍板統一;M24 state > emphasis:disabled 全滅,
+    // 選中的 primary 描邊/染字一併退場——原本只滅字不滅框 = 半滅,Checkbox checked+disabled 全滅同族)
+    'data-[state=on]:disabled:border-border data-[state=on]:disabled:text-fg-disabled',
+    'data-[state=on]:disabled:hover:border-border data-[state=on]:disabled:hover:text-fg-disabled',
   ]
 )
 
@@ -208,6 +220,29 @@ ScrollChipGroup.displayName = 'ScrollChipGroup'
 //
 // Fade mask 仍保留(reserveArrowWidth: 0),軟化內容硬邊。
 
+// ── getElementRef(Radix Slot idiom)──────────────────────────────────────────
+// 讀取 child element 既有 ref 而不觸發 React dev deprecation warning:
+// React ≤18 ref 在 element.ref;React 19 起移到 element.props.ref,錯誤側讀取會 fire warning
+// (以 getter 上的 isReactWarning 標記)。抄 Radix UI Slot 的偵測法:
+// https://github.com/radix-ui/primitives/blob/main/packages/react/slot/src/slot.tsx(getElementRef)
+// react-compose-refs 僅為 transitive dep(非 package.json 直接依賴),不直接 import — 最小 local 實作。
+function getElementRef(element: React.ReactElement): React.Ref<HTMLElement> | undefined {
+  // React <=18 dev:props.ref 掛 isReactWarning getter → 真 ref 在 element.ref
+  let getter = Object.getOwnPropertyDescriptor(element.props, 'ref')?.get
+  let mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning
+  if (mayWarn) return (element as unknown as { ref?: React.Ref<HTMLElement> }).ref
+  // React 19 dev:element.ref 掛 isReactWarning getter → 真 ref 在 props.ref
+  getter = Object.getOwnPropertyDescriptor(element, 'ref')?.get
+  mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning
+  if (mayWarn) return (element.props as { ref?: React.Ref<HTMLElement> }).ref
+  // production:兩處擇一
+  return (
+    (element.props as { ref?: React.Ref<HTMLElement> }).ref ??
+    (element as unknown as { ref?: React.Ref<HTMLElement> }).ref ??
+    undefined
+  )
+}
+
 // code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
 const MenuChipGroup = React.forwardRef<
   HTMLDivElement,
@@ -284,12 +319,22 @@ const MenuChipGroup = React.forwardRef<
     [groupType, groupValue, groupOnValueChange]
   )
 
-  const enhancedItems = items.map((child, i) =>
-    React.cloneElement(
+  // 2026-07-05 fix(deep-audit A.1b):原 cloneElement 直接以 registerItem 覆寫 child ref,
+  // consumer 傳給 Chip 的自有 ref 在 menu layout 會被靜默取代。改 compose — 同時餵
+  // registerItem(scrollIntoView 用)與 child 原 ref(對齊 Radix compose-refs idiom)。
+  const enhancedItems = items.map((child, i) => {
+    const childRef = getElementRef(child)
+    return React.cloneElement(
       child as React.ReactElement<{ ref?: React.Ref<HTMLElement> }>,
-      { ref: registerItem(i) }
+      {
+        ref: (el: HTMLElement | null) => {
+          registerItem(i)(el)
+          if (typeof childRef === 'function') childRef(el)
+          else if (childRef) (childRef as React.MutableRefObject<HTMLElement | null>).current = el
+        },
+      }
     )
-  )
+  })
 
   return (
     <div className="flex items-center gap-2">
@@ -342,16 +387,16 @@ MenuChipGroup.displayName = 'MenuChipGroup'
 export const chipMeta = {
   component: 'Chip',
   family: 3,
-  variants: {
-
-  },
+  // 2026-07-04 audit 填 Phase 2:Chip 單一視覺無 variant 軸(variants 留空為 intentional,非漏填)
+  variants: {},
   sizes: {
-
+    // 單一尺寸:h-field-sm(28/32 依 density)、icon 16、text-body、px-3(cva 真值)
+    sm: { fieldHeight: 28, iconSize: 16, typography: 'body' },
   },
-  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'], // selected = data-[state=on](primary-hover);cva 無 active 樣式
+  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'], // selected = data-[state=on](primary base,2026-07-06 拍板);cva 無 active 樣式
   tokens: {
     bg: ['bg-surface'],
-    fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground', 'text-primary-hover'],
+    fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground', 'text-primary'],
     ring: ['ring-ring'],
   },
 } as const

package/src/components/CircularProgress/circular-progress.anatomy.stories.tsx

@@ -170,7 +170,7 @@ export const Accessibility = {
   render: () => (
     <div className="max-w-3xl text-body text-fg-secondary">
       <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
-      <p className="whitespace-pre-line">{"本元件不可聚焦、無鍵盤互動(載入指示不接收鍵盤),但會依模式自動輸出對的 ARIA 給輔助技術:\n\n• 有 value(determinate)→ role=\"progressbar\",並帶 aria-valuenow / aria-valuemin=0 / aria-valuemax=100,螢幕報讀器會念出目前進度。\n• 無 value(indeterminate)+ 有傳 label 或 aria-label → role=\"status\",把 label 當作 aria-label 念出(例如「載入訂單資料中」)。\n• 無 value 且沒給任何 label → 標記 aria-hidden,交由外層容器(如 Button 的 aria-busy)負責語義。\n\n當把 CircularProgress 包進互動容器(Button / Card / Link)時,聚焦與鍵盤行為由容器決定。"}</p>
+      <p className="whitespace-pre-line">{"本元件不可聚焦、無鍵盤互動(載入指示不接收鍵盤),但會依模式自動輸出對的 ARIA 給輔助技術:\n\n• 有 value(determinate)→ role=\"progressbar\",並帶 aria-valuenow / aria-valuemin=0 / aria-valuemax=100,螢幕報讀器會念出目前進度。\n• 無 value(indeterminate)+ 有傳 label 或 aria-label → role=\"status\",把 label 當作 aria-label 念出(例如「載入訂單資料中」)。\n• 無 value 且沒給任何 label → 標記 aria-hidden,交由外層容器(如 Button 的 aria-busy)負責語義。\n\n動畫尊重 prefers-reduced-motion:偏好減少動態的使用者不會看到停止的圈(那會像卡住),indeterminate 旋轉改放慢至 3s/圈(預設 1s)——保留「進行中」訊號、降低前庭刺激(Material 流派)。\n\n當把 CircularProgress 包進互動容器(Button / Card / Link)時,聚焦與鍵盤行為由容器決定。"}</p>
     </div>
   ),
 }

package/src/components/CircularProgress/circular-progress.principles.stories.tsx

@@ -8,6 +8,7 @@ import { Search, Check } from 'lucide-react'
 import { CircularProgress } from './circular-progress'
 import { Button } from '@/design-system/components/Button/button'
 import { Skeleton } from '@/design-system/components/Skeleton/skeleton'
+import { Empty } from '@/design-system/components/Empty/empty'
 import { Input } from '@/design-system/components/Input/input'
 
 const meta: Meta = {
@@ -214,12 +215,13 @@ export const UsageScenarioRule: Story = {
         title="✅ 延遲加載浮層 / 全頁 overlay — 用 Empty compose"
         note="切換 workspace / 載入 dashboard 等需要阻擋互動的場景,走 Empty compose:<Empty icon={<CircularProgress size={48} />} title=... description=... />。不要自己手刻 absolute overlay"
       >
+        {/* 2026-07-04 audit:改消費 <Empty> compose(原手刻垂直堆疊與本則自教規則+spec Do 矛盾) */}
         <div className="border border-border rounded-lg w-96 h-40 flex items-center justify-center bg-muted/40">
-          <div className="flex flex-col items-center gap-3">
-            <CircularProgress size={48} aria-label="載入 dashboard" />
-            <p className="text-body font-medium">載入 dashboard 中</p>
-            <p className="text-caption text-fg-muted">Notion workspace 切換、Stripe dashboard 初載</p>
-          </div>
+          <Empty
+            icon={<CircularProgress size={48} aria-label="載入 dashboard" />}
+            title="載入 dashboard 中"
+            description="Notion workspace 切換、Stripe dashboard 初載"
+          />
         </div>
       </Rule>
     </div>

package/src/components/CircularProgress/circular-progress.spec.md

@@ -185,6 +185,8 @@ Track 色鎖 `var(--secondary)`(= neutral-3,與 ProgressBar track 一致)。
 | Indeterminate + 有 aria-label / label | `status` | `aria-label={aria-label ?? label}`(顯式 aria-label 優先,label 為 fallback) |
 | Indeterminate + 無 label | `aria-hidden=true` | 由父層 `aria-busy` 管理(Button 模式) |
 
+**動畫 × `prefers-reduced-motion`**:indeterminate 旋轉對 reduce 使用者**不停止**(loading 回饋仍需可見,停轉會像卡住),改放慢至 3s/圈(預設 1s;`circular-progress.tsx` 的 `motion-reduce:[animation-duration:3s]`,Material 流派)——保留「進行中」訊號、降低前庭刺激。對照 Skeleton 的 `motion-reduce:animate-none`(完全停止):占位塊靜止後仍是有效的靜態內容,語意不失,故兩元件策略不同。
+
 ---
 
 ## 視覺與幾何鐵律

package/src/components/CircularProgress/circular-progress.stories.tsx

@@ -5,7 +5,6 @@ import type { Meta, StoryObj } from '@storybook/react'
 import { Search, Upload } from 'lucide-react'
 import type { ColumnDef } from '@tanstack/react-table'
 import { CircularProgress } from './circular-progress'
-import { Button } from '@/design-system/components/Button/button'
 import { Input } from '@/design-system/components/Input/input'
 import { Empty } from '@/design-system/components/Empty/empty'
 import { DataTable } from '@/design-system/components/DataTable/data-table'
@@ -43,16 +42,9 @@ export const Default: Story = {
   ),
 }
 
-export const ButtonLoading: Story = {
-  name: '按鈕載入中',
-  render: () => (
-    <div className="flex items-center gap-3">
-      <Button variant="primary" loading>處理付款中</Button>
-      <Button variant="secondary" loading>儲存草稿</Button>
-      <Button variant="tertiary" loading>匯出 CSV</Button>
-    </div>
-  ),
-}
+// Retired 2026-07-04 audit Dim 24:`ButtonLoading` 全程只 demo `<Button loading>`(0 個直接 `<CircularProgress>`),
+// 跟 button.stories.tsx「載入中」重複且較弱(那邊有 原始→loading 對照 + iconOnly + startIcon 替換)。
+// Button loading 消費 CircularProgress 的關係由 spec「何時用」+ Size canonical 段記載,story home 在 Button。
 
 export const InlineAction: Story = {
   name: '行內操作',

package/src/components/Coachmark/coachmark.anatomy.stories.tsx

@@ -335,7 +335,7 @@ export const StateBehavior: Story = {
         <div>
           <H3>Focus / Esc / Click-outside(繼承 Popover)</H3>
           <Desc>
-            Coachmark 大部分行為繼承 Popover(Radix),但刻意抑制開啟時的自動 focus(onOpenAutoFocus preventDefault)——焦點停在 trigger,避免使用者還在讀 body 時 CTA 被 auto-focus 偷觸發;關閉時 return to trigger;Esc 關閉浮層(透過 Radix onOpenChange,效果等同退出,但不觸發 onSkip callback);預設 non-modal,使用者可忽略繼續主流程。
+            Coachmark 大部分行為繼承 Popover(Radix),但刻意抑制 CTA 自動 focus(onOpenAutoFocus preventDefault 後 focus content 容器本身)——避免使用者還在讀 body 時 CTA 被 auto-focus 偷觸發,Tab 第一下即達第一個 CTA(焦點不停 trigger,否則 non-modal focus-outside dismiss 會誤關閉浮層;2026-07-05 D4 修);關閉時 return to trigger;Esc 關閉浮層(透過 Radix onOpenChange,效果等同退出,但不觸發 onSkip callback);預設 non-modal,使用者可忽略繼續主流程。
           </Desc>
         </div>
       </div>
@@ -350,7 +350,7 @@ export const Accessibility = {
   render: () => (
     <div className="max-w-3xl text-body text-fg-secondary">
       <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
-      <p className="whitespace-pre-line">{"詳 `coachmark.spec.md` 「A11y 預設」段。摘要:\n\n-   焦點管理  :刻意抑制開啟時的自動 focus(onOpenAutoFocus preventDefault),焦點停在 trigger——避免 user 還在讀 body 時 CTA 被偷觸發;關閉時 return to trigger\n-   Esc 關閉  :預設啟用——user 按 Esc 透過 Radix onOpenChange 關閉浮層(效果等同退出),但不觸發 onSkip callback(Esc 是「關閉浮層」非「明確 skip」)\n-   ARIA  :trigger 自動  aria-expanded  /  aria-controls ,content  role=\"dialog\" (Radix 預設)\n-   Step 計數 tabular-nums  :螢幕閱讀器讀「2 of 3」語意清楚"}</p>
+      <p className="whitespace-pre-line">{"詳 `coachmark.spec.md` 「A11y 預設」段。摘要:\n\n-   焦點管理  :刻意抑制 CTA 自動 focus(onOpenAutoFocus preventDefault 後 focus content 容器本身)——避免 user 還在讀 body 時 CTA 被偷觸發;Tab 第一下即達第一個 CTA(焦點不停 trigger,否則 non-modal focus-outside dismiss 會誤關閉;2026-07-05 D4 修);關閉時 return to trigger\n-   Esc 關閉  :預設啟用——user 按 Esc 透過 Radix onOpenChange 關閉浮層(效果等同退出),但不觸發 onSkip callback(Esc 是「關閉浮層」非「明確 skip」)\n-   ARIA  :trigger 自動  aria-expanded  /  aria-controls ,content  role=\"dialog\" (Radix 預設)\n-   Step 計數 tabular-nums  :螢幕閱讀器讀「2 of 3」語意清楚"}</p>
     </div>
   ),
 }

package/src/components/Coachmark/coachmark.principles.stories.tsx

@@ -55,7 +55,7 @@ const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }
 
 const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
   <section className="mb-12">
-    <h2 className="text-heading-3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
+    <h2 className="text-h3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
     {children}
   </section>
 )

package/src/components/Coachmark/coachmark.spec.md

@@ -166,7 +166,7 @@ Previous(可選)→ Skip(可選)→ Next / Done。對齊 Ant Tour / Intercom con
 
 - **Previous 最左**——回到上一步(負方向,視覺權重低)
 - **Skip 中間**——exit escape hatch,tertiary 不搶焦點;**僅第一步顯示**(見 CTA 語義表)
-- **Next / Done 最右**——推進主動線(正方向,primary 視覺權重高);**Coachmark 抑制開啟時的自動 focus**(`onOpenAutoFocus` preventDefault,連 Radix 預設會 focus 的第一個 focusable 也一併抑制),避免使用者還在讀 body 時按 Enter 誤推進;想推進者自行 tab 到 CTA 再 Enter
+- **Next / Done 最右**——推進主動線(正方向,primary 視覺權重高);**Coachmark 抑制 CTA 自動 focus**(`onOpenAutoFocus` preventDefault 後 focus content 容器本身,非第一個 CTA),避免使用者還在讀 body 時按 Enter 誤推進;想推進者按一下 Tab 即達 CTA 再 Enter(焦點已在 content 內,不觸發 non-modal focus-outside dismiss;2026-07-05 D4 修)
 
 第 1 步通常無 Previous;最後步 Next 改 Done(由 `isLastStep` 控制)。單步驟 CTA 改 `'知道了'`。
 
@@ -178,7 +178,7 @@ Previous(可選)→ Skip(可選)→ Next / Done。對齊 Ant Tour / Intercom con
 |----|-------|------|
 | 浮層外殼 | 繼承 Popover(`bg-surface-raised` / `border-border` / `rounded-lg` / `--elevation-200`) | 改 Popover 自動跟進 |
 | Media 背景 | `bg-muted` | illustration / 透明 PNG 底色 |
-| Title | `text-body-lg font-medium text-foreground` | 比 Popover header 輕(Coachmark 無 header 分隔線) |
+| Title | `text-body-lg font-medium text-foreground` | body 主 title(16px),比 kind header 的 `PopoverTitle` 小標籤(`text-body` 14px)重一階——主教學訊息是視覺主角 |
 | Description | `text-body text-fg-secondary` | 主說明文字 |
 | Step 計數 | `text-body text-fg-secondary tabular-nums` | 跟 body 內文同字體;數字等寬,切換步驟不跳動 |
 | Body padding | `px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]` | overlay-surface SSOT(PopoverBody) |
@@ -203,7 +203,7 @@ Previous(可選)→ Skip(可選)→ Next / Done。對齊 Ant Tour / Intercom con
 
 ## A11y 預設
 
-- **焦點管理**:Coachmark **刻意抑制開啟時的自動 focus**(`onOpenAutoFocus` preventDefault),焦點停在 trigger——避免使用者還在讀 body 時 CTA 被 auto-focus 偷觸發(按 Enter 誤推進);想推進者自行 tab 到 CTA。關閉時焦點 return to trigger(Radix 預設 `onCloseAutoFocus`,未 override)
+- **焦點管理**:Coachmark **刻意抑制 CTA 自動 focus**(`onOpenAutoFocus` preventDefault 後 focus content 容器本身,對齊 `dialog.tsx` 的 `?? content` fallback canonical)——避免使用者還在讀 body 時 CTA 被 auto-focus 偷觸發(焦點在容器上按 Enter 無動作);Tab 第一下即達 content 內第一個 CTA。焦點**不**停在 trigger:non-modal Popover 焦點在 content 樹外時按 Tab 會觸發 focus-outside dismiss 誤關閉浮層,CTA 鍵盤永遠到不了(2026-07-05 D4 修;dismiss 機制詳 `popover.spec.md` A11y 段)。關閉時焦點 return to trigger(Radix 預設 `onCloseAutoFocus`,未 override)
 - **Esc 關閉**:預設啟用——user 按 Esc 透過 Radix `onOpenChange` 關閉浮層(效果等同退出),**不觸發 `onSkip` callback**(Esc 是「關閉浮層」非「明確 skip」;若需區分 Esc-退出 vs Skip-按鈕 的追蹤事件,consumer 在 Skip 按鈕的 `onSkip` 處理)
 - **ARIA**:trigger 自動 `aria-expanded` / `aria-controls`,content `role="dialog"`(Radix 預設)
 - **Step 計數 tabular-nums**:螢幕閱讀器讀「2 of 3」語意清楚

package/src/components/Coachmark/coachmark.tsx

@@ -34,9 +34,11 @@ import { OVERLAY_SIDE_OFFSET } from '@/design-system/tokens/elevation/overlay-ge
  *   3. **Multi step 中間 / 最後步**(有 `onPrev`):**Skip 不顯示**(使用者已投入進度,
  *      再給 Skip 會讓「放棄」入口與「回上一步」衝突 — Linear / Pendo / Shepherd.js
  *      同樣規則)。CTA = `isLastStep ? 'Done' : 'Next'`
- *   4. **抑制開啟時的自動 focus** — `onOpenAutoFocus` preventDefault,連 Radix 預設
- *      focus 第一個 focusable 也一併抑制(焦點停在 trigger),避免使用者還在讀 body 時
- *      按 Enter 誤推進。想推進者自行 tab 到 CTA 再 Enter(對齊 spec「A11y 預設」)。
+ *   4. **抑制 CTA 自動 focus,焦點落在 content 容器** — `onOpenAutoFocus` preventDefault
+ *      後 focus content 容器本身(非第一個 CTA),避免使用者還在讀 body 時按 Enter 誤推進;
+ *      Tab 第一下即達 content 內第一個 CTA。焦點不可停在 trigger:non-modal Popover 下
+ *      焦點在 DismissableLayer 外按 Tab 會觸發 focus-outside dismiss 誤關閉
+ *      (2026-07-05 D4;對齊 dialog.tsx handleOpenAutoFocus `?? content` fallback,見 spec「A11y 預設」)。
  *
  * ── 為什麼 Body+Footer 消費 overlay-surface ──
  * 避免 padding token 漂移:Dialog / Popover / Coachmark 三者共用同一套 Header/Body/Footer
@@ -150,10 +152,12 @@ const Coachmark = React.forwardRef<HTMLDivElement, CoachmarkProps>(
         ? KIND_TITLE[kind as 'tips' | 'new-features']
         : kind
 
-    // 2026-05-31 #6:PopoverContent(role=dialog)需 accessible name。dialog aria-labelledby 接可見標題
-    // (優先 headerTitle 的 PopoverTitle,否則 body title 的 h3);皆無則 aria-label fallback。
-    const titleId = React.useId()
-    const dialogLabelledBy = (headerTitle || title) ? titleId : undefined
+    // 2026-05-31 #6 / 2026-07-05 改消費 Popover 自動接線:PopoverContent(role=dialog)accessible name 三層 —
+    // 1. headerTitle → <PopoverTitle> 掛載時由 popover.tsx PopoverTitleContext 自動接 aria-labelledby(免手動)
+    // 2. 無 header 但有 body 主 title(<h3> 非 PopoverTitle,自動接線接不到)→ 仍手動接 aria-labelledby
+    // 3. 皆無 → aria-label fallback
+    const bodyTitleId = React.useId()
+    const bodyTitleLabelledBy = !headerTitle && title ? bodyTitleId : undefined
 
     return (
       <Popover open={open} defaultOpen={defaultOpen} onOpenChange={onOpenChange}>
@@ -166,10 +170,16 @@ const Coachmark = React.forwardRef<HTMLDivElement, CoachmarkProps>(
           className={cn('w-80 p-0 overflow-hidden', className)}
           // 禁止 Radix 開啟時自動 focus 第一個 focusable(預設會 focus Prev / Skip / Next),
           // Coachmark 的 CTA 不該被 auto-focus 偷觸發(user 可能還在讀 body,按 Enter 就推進)。
-          // 想推進的 user 自己 tab 到 CTA 即可。
-          onOpenAutoFocus={(e) => e.preventDefault()}
-          aria-labelledby={dialogLabelledBy}
-          aria-label={dialogLabelledBy ? undefined : '提示'}
+          // 2026-07-05 D4:preventDefault 後必 focus content 容器本身(FocusScope 容器自帶 tabIndex=-1)——
+          // 焦點若停在 trigger(DismissableLayer 外),non-modal Popover 按 Tab 即觸發 focus-outside
+          // dismiss 直接關閉,CTA 鍵盤永遠到不了;focus 容器後 Tab 第一下即達第一個 CTA,Enter 按在
+          // 容器上無動作(原「不誤推進」意圖保留;對齊 dialog.tsx handleOpenAutoFocus `?? content` fallback)。
+          onOpenAutoFocus={(e) => {
+            e.preventDefault()
+            ;(e.currentTarget as HTMLElement).focus({ preventScroll: true })
+          }}
+          aria-labelledby={bodyTitleLabelledBy}
+          aria-label={headerTitle || title ? undefined : '提示'}
           {...props}
         >
           {headerTitle && (
@@ -177,7 +187,7 @@ const Coachmark = React.forwardRef<HTMLDivElement, CoachmarkProps>(
             // **不 hideClose** — 對齊 Popover / Dialog / 所有 overlay 家族 canonical:header 必有 dismiss X
             // (user 可隨時關閉,跟 Skip / Done 是不同入口,canonical 重複不冗)
             <PopoverHeader>
-              <PopoverTitle id={titleId}>{headerTitle}</PopoverTitle>
+              <PopoverTitle>{headerTitle}</PopoverTitle>
             </PopoverHeader>
           )}
 
@@ -194,7 +204,7 @@ const Coachmark = React.forwardRef<HTMLDivElement, CoachmarkProps>(
             // 世界級參考:Notion / Linear / Figma onboarding tour 皆左對齊;Intercom Messenger 亦如是。
             <PopoverBody className="flex flex-col">
               {title && (
-                <h3 id={!headerTitle ? titleId : undefined} className="text-body-lg font-medium text-foreground">{title}</h3>
+                <h3 id={!headerTitle ? bodyTitleId : undefined} className="text-body-lg font-medium text-foreground">{title}</h3>
               )}
               {description && (
                 // title(body-lg 16)+ desc(body 14)→ reading-lg token(label tier 決定)

package/src/components/Combobox/combobox.anatomy.stories.tsx

@@ -306,7 +306,7 @@ export const Overview = {
             <thead><tr><Th>Prop</Th><Th>Type</Th><Th>Default</Th><Th>說明</Th></tr></thead>
             <tbody>
               {[
-                ['mode', "'edit'|'display'|'readonly'|'disabled'", "'edit'", 'FieldMode 四模式;disabled 原生屬性會自動覆蓋'],
+                ['mode', "'edit'|'display'|'readonly'|'disabled'", "'edit'", 'FieldMode 四模式;顯式傳入時永遠最優先,不被 disabled 覆蓋'],
                 ['size', "'sm'|'md'|'lg'", "'md'", '尺寸，與 Button 共用 field-height token'],
                 ['options', 'ComboboxOption[]', '—', '選項列表（extends SelectMenuOption：value / label / icon / avatar / description / disabled / group）'],
                 ['value', 'string[]', '[]', '已選中的值陣列'],
@@ -315,7 +315,7 @@ export const Overview = {
                 ['wrap', 'boolean', 'false', '換行模式——高度隨內容展開，Tags 自然換行'],
                 ['clearable', 'boolean', 'false', '有值時顯示 X clear all 按鈕'],
                 ['placeholder', 'string', '—', '無值時的提示文字；未傳時桌機 fallback 到 emptyPlaceholder（預設「選擇…」全形省略號），手機原生 select fallback「選擇...」'],
-                ['disabled', 'boolean', 'false', '原生 disabled，自動覆蓋 mode'],
+                ['disabled', 'boolean', 'false', '原生屬性；未傳 mode 時 resolve 為 disabled 樣式（顯式 mode prop 恆優先，見 useResolvedFieldMode）'],
               ].map(([p, t, d, desc]) => (
                 <tr key={p}><Td mono>{p}</Td><Td mono>{t}</Td><Td mono>{d}</Td><Td>{desc}</Td></tr>
               ))}
@@ -783,8 +783,8 @@ export const StateBehavior = {
           <div className="flex flex-col gap-1 text-[11px] text-fg-secondary">
             <span>1. useOverflowCount hook 量測 container 寬度與每個 tag 的自然寬度</span>
             <span>2. ResizeObserver 持續監聽容器變化</span>
-            <span>3. 量測在 useLayoutEffect 內 paint 前同步完成，超出的 tag 在繪製前就已隱藏，避免閃爍</span>
-            <span>4. 超出的 tag 用 DOM hidden 隱藏（非 display:none）</span>
+            <span>3. 量測在 useEffect 內首次 paint 後執行（確保 nested 場景所有 ref 已 attach），double-rAF 保證 layout 完成才量測；代價是可能 1-2 frame 閃爍，由 value-equal setState guard 收斂</span>
+            <span>4. 超出的 tag 以 DOM hidden attribute 隱藏（UA 樣式即 display:none；節點保留在 DOM，量測時先全部解除隱藏再計算）</span>
           </div>
         </div>
 

package/src/components/Combobox/combobox.spec.md

@@ -160,7 +160,7 @@ value 軸 controlled-only;open 軸方向相反 — **uncontrolled-only**:`defaul
 
 ## Internal API（PeoplePicker stack wrapper 私用，end-user 勿用）
 
-`tagWrapperClassName` / `overflowWrapperClassName` / `tagAreaGapPx` / `tagAreaPaddingLeftPx` / `visibleCountOverride` 是 Combobox overflow 量測層的內部 hook,只供 DS-internal wrapper(PeoplePicker avatar stack)用,已標 `@internal`。`tagAreaPaddingLeftPx` 目前無 active consumer(PeoplePicker 走 `!px-3` 路徑),保留供未來精準 padding 但新 consumer 請先評估。`overflowShape` 是 public typed enum(矩形/圓形 +N),不在此列。
+`tagWrapperClassName` / `overflowWrapperClassName` / `tagAreaGapPx` / `tagAreaPaddingLeftPx` / `visibleCountOverride` 是 Combobox overflow 量測層的內部 hook,只供 DS-internal wrapper(PeoplePicker avatar stack)用,已標 `@internal`。`tagAreaPaddingLeftPx` 目前無 active consumer(PeoplePicker 走 `!px-[var(--field-px)]` 路徑,`people-picker.tsx:371`),保留供未來精準 padding 但新 consumer 請先評估。`overflowShape` 是 public typed enum(矩形/圓形 +N),不在此列。
 
 ---
 

package/src/components/Combobox/combobox.tsx

@@ -1,5 +1,5 @@
 // @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.
-// @renderer-symmetry-allow: ComboboxTagStack(display path)接 consumer tagRenderer 是 Stream C 下 cycle 工作 — 2026-05-12 先 ship Issues 2/3/4 surgical fixes(placeholder vocabulary + cell surface metrics + placeholder truncate),tagRenderer display-path unify deferred per field-controls.spec.md 共享 contract a。當前 multi=1 顯示已透過 PeoplePicker tagRenderer 線 314 PersonDisplay SSOT 對齊;其他 Combobox consumer 走 default `<Tag>` 純文字 backward-compat。
+// @renderer-symmetry-allow: ComboboxTagStack(display path)接 consumer tagRenderer 是 Stream C 下 cycle 工作 — 2026-05-12 先 ship Issues 2/3/4 surgical fixes(placeholder vocabulary + cell surface metrics + placeholder truncate),tagRenderer display-path unify deferred per field-controls.spec.md 共享 contract a。當前 multi=1 顯示已透過 PeoplePicker tagRenderer(people-picker.tsx:426-444)PersonDisplay SSOT 對齊;其他 Combobox consumer 走 default `<Tag>` 純文字 backward-compat。
 // code-quality-allow: file-size — Combobox 含 NativeCombobox/CustomCombobox/useOverflowCount/OverflowTagList/ComboboxTagStack 5 子元件 + 共用 helpers,split-into-files 會破壞 measurement closures + 重複 type definitions。
 import * as React from 'react'
 import { X, ChevronDown } from 'lucide-react'
@@ -10,7 +10,7 @@ import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useRes
 import { Tag } from '@/design-system/components/Tag/tag'
 import { ItemInlineAction, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
 import { OverflowIndicator } from '@/design-system/components/OverflowIndicator/overflow-indicator'
-import { SelectMenu, type SelectMenuOption } from '@/design-system/components/SelectMenu/select-menu'
+import { SelectMenu, forwardKeyToListbox, useActiveDescendant, type SelectMenuOption } from '@/design-system/components/SelectMenu/select-menu'
 import { useIsTouchDevice } from '@/design-system/hooks/use-is-touch-device'
 import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
 
@@ -60,7 +60,7 @@ function useOverflowCount(
   const [state, setState] = React.useState({ visibleCount: totalCount, ready: !enabled })
   // 2026-05-18 Round 6 fix(per Codex M31 Round 6 H7 verdict + Step 5 共識):
   // `ofEl.offsetWidth` 在 expanded state(visibleCount === totalCount → overflow=0 →
-  // `OverflowIndicator` line 92 `return null` → ofEl wrapper empty)= 0,fallback 60;
+  // `OverflowIndicator` count≤0 早退 `return null` → ofEl wrapper empty)= 0,fallback 60;
   // 在 collapsed state(+N rendered)= 真實寬(~28-32px)。同 `available` 在兩 state 給
   // 不同 verdict → 臨界值區 `max(B+g+Q, B+g+O) ≤ available < B+g+F` 振盪。Cache last
   // non-zero measurement → measurement state-independent → oscillation 收斂。
@@ -168,7 +168,7 @@ function useOverflowCount(
       }
       if (ofEl) ofEl.hidden = count >= totalCount
       // 2026-05-18 A' fix functional setState value-equal guard(per Codex Round 3 verdict):
-      // sync calc 在 useLayoutEffect 內 + ResizeObserver re-fire 同時跑 → 若每次都 new object setState
+      // effect 內 calc 直跑 + ResizeObserver re-fire 同時跑 → 若每次都 new object setState
       // 觸發 re-render 即使值沒變,可能 cascade。回 prev 不更新 = avoid 抖動。
       setState(prev => (prev.visibleCount === count && prev.ready) ? prev : { visibleCount: count, ready: true })
     }
@@ -180,13 +180,13 @@ function useOverflowCount(
     //
     // 2026-05-16 Race close:capture rAF IDs + cancel on cleanup(原版 race I3 沒 close
     // 完;user 抓 path A 逐個 click vs path B 取消全選再全選 same length 不同 visible)。
-    // 2026-05-18 A' fix(per Codex Round 3 共識,user 拍板「執行」)— sync calc in useLayoutEffect:
-    // React 18 `useLayoutEffect` 在 DOM commit 後、瀏覽器繪製前同步跑,sync calc 在 paint 前
+    // 2026-05-18 A' fix(per Codex Round 3 共識,user 拍板「執行」)— effect fire 時 calc() 直跑
     // 完成 `el.hidden` 設定 + functional setState guard(value-equal 不更新 = 避免 ResizeObserver
-    // 抖動 cascade rerender)。double-rAF 改 fallback only(ResizeObserver / async update path)。
+    // 抖動 cascade rerender)。double-rAF 為 fallback path(ResizeObserver / async update path)。
     // 解 user verbatim「tag 過長 / 過多會先全顯再變 +N 閃動」root cause(per codex Round 3 cite
-    // `combobox.tsx:248 render 沒設 hidden + L129 calc imperative 寫 DOM`)。
-    // 對齊 React docs https://react.dev/reference/react/useLayoutEffect pre-paint guarantee。
+    // 「render 沒設 hidden + calc imperative 寫 DOM」)。
+    // 註:Round 3 原以 useLayoutEffect sync calc(paint 前設 hidden)實作;2026-05-18 Round 5
+    // 已改 React.useEffect after-paint(nested 場景 parent ref attach 時序,詳上方 Round 5 註解)。
     calc()
     let rafId1 = 0, rafId2 = 0
     const scheduleCalc = () => {
@@ -287,8 +287,9 @@ function OverflowTagList({ containerRef, items, size, wrap, renderTag, renderHid
 
   // 2026-05-18 A' fix(per Codex Round 3 共識,user 拍板「執行」)— 撤掉舊的 `style={{ opacity: ready ? 1 : 0 }}`
   // gate(掛在 `<span className="contents">` 上,但 CSS Display 3 spec 規定 `display:contents` 元素不產生 box,
-  // parent opacity 對 children 無效 → gate 從沒生效是 dead code)。Flicker 已改 sync calc in useLayoutEffect 解
-  // (L153 `calc()` 直跑,paint 前 hidden 設好)。`ready` state 保留供未來 instrumentation / debug,不再當 visual gate。
+  // parent opacity 對 children 無效 → gate 從沒生效是 dead code)。Flicker 由 `useOverflowCount` effect 內
+  // `calc()` 直跑(現 L190;2026-05-18 Round 5 改 useEffect after-paint + double-rAF guard,詳該 hook 註解)解。
+  // `ready` state 保留供未來 instrumentation / debug,不再當 visual gate。
   // 保留 `<span className="contents">` 維持 fragment-like rendering(parent JSX 期望 single child)。
   void ready  // intentional: ready 留供 future debug,目前無 consumer
   return (
@@ -389,6 +390,8 @@ export interface ComboboxProps {
   searchAriaLabel?: string
   /** Empty-selection placeholder text。Default: 「選擇…」 */
   emptyPlaceholder?: string
+  /** 搜尋無結果提示(2026-07-04 Q4 拍板接線)— forward SelectMenu primitive SSOT(default「沒有符合的選項」) */
+  emptyText?: string
   /** a11y:無 Field wrapper 時提供 role='combobox' 的 accessible name(axe aria-input-field-name) */
   'aria-label'?: string
   /** Initial open state(uncontrolled)— 對齊 Select.defaultOpen / Radix Popover canonical。
@@ -602,8 +605,8 @@ function NativeCombobox({
   ) : null
 
   return (
-    <div ref={__triggerRef} className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, size }), value.length > 0 && tagPadding[size], 'relative',
-      wrap && 'items-start py-1', error && ['border-error hover:border-error-hover', 'focus-within:border-error focus-within:hover:border-error'], className)}
+    <div ref={__triggerRef} className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, size, error }), value.length > 0 && tagPadding[size], 'relative',
+      wrap && 'items-start py-1', className)}
       style={{ paddingRight: 'var(--field-px)', ...(wrap ? { height: 'auto' } : undefined) }} data-field-mode="edit" data-error={error ? '' : undefined}
       onClick={(e) => { if (e.target === e.currentTarget) { selectRef.current?.showPicker?.(); selectRef.current?.focus() } }}>
       {/* 2026-05-18 F2 sync(per user verbatim「modifying 修好 PeoplePicker stack 後改壞 Combobox tag display」
@@ -644,6 +647,7 @@ function CustomCombobox({
   searchPlaceholder = '搜尋…', // i18n-allow: DS default
   searchAriaLabel = '搜尋選項', // i18n-allow: DS default
   emptyPlaceholder = '選擇…', // i18n-allow: DS default
+  emptyText,
   defaultOpen = false,
   onOpenChange,
   __triggerRef,
@@ -675,6 +679,9 @@ function CustomCombobox({
   // a11y: 為 listbox 容器(SelectMenu 內 PopoverContent)建立穩定 id,讓 trigger 的
   // aria-controls 能指向它(WAI-ARIA combobox pattern 要求)。React.useId 在 SSR/CSR 都穩定。
   const listboxId = React.useId()
+  // a11y(2026-07-05 D4):追蹤 cmdk active item id → searchIn='trigger' 搜尋 input 綁 aria-activedescendant
+  // (機制詳 select-menu.tsx useActiveDescendant docblock;必在 early return 前呼叫 — React #310 hook 順序)。
+  const activeOptionId = useActiveDescendant(listboxId, open)
 
   React.useEffect(() => { if (!open) setSearch('') }, [open])
 
@@ -731,11 +738,11 @@ function CustomCombobox({
       aria-required={fieldCtx?.required || undefined}
       aria-describedby={fieldCtx?.descriptionId}
       aria-errormessage={error ? fieldCtx?.errorId : undefined}
-      className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, size }), value.length > 0 && tagPadding[size], 'relative cursor-pointer',
+      className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, size, error }), value.length > 0 && tagPadding[size], 'relative cursor-pointer',
         wrap && 'items-start py-1',
         // 2026-05-06 v13.3 SSOT retire:per-control `open && 'border-primary'` 移除。Field default
-        // 統一處理 — open=灰深(data-state)/ focus=藍(focus-within !important)。改一處全 control 跟動。
-        error && ['border-error hover:border-error-hover', 'focus-within:border-error focus-within:hover:border-error'], className)}
+        // 統一處理 — open=灰深(data-state)/ focus=藍;2026-07-04 Q1:error 亦收進 error variant。
+        className)}
       style={{ paddingRight: 'var(--field-px)', ...(wrap ? { height: 'auto' } : undefined) }}
       data-field-mode="edit" data-error={error ? '' : undefined}
       // WAI-ARIA APG combobox 鍵盤開啟語意 — 對齊 sibling Select(select.tsx:593-598)。
@@ -745,6 +752,8 @@ function CustomCombobox({
       //   open 後不 preventDefault 讓方向鍵自由流向選單導覽)。
       // 純 additive:此 trigger 原無 onKeyDown,不覆寫既有 handler;open 邏輯仍走 setOpen SSOT。
       onKeyDown={(e) => {
+        // 2026-07-05 D4 P0:open 後 ArrowUp/Down/Enter 轉送 cmdk root(select-menu.tsx forwardKeyToListbox)
+        if (open && forwardKeyToListbox(listboxId, e)) return
         if (e.key === 'Enter' || e.key === ' ') {
           // 2026-06-11 P0 a11y(R2,同 select.tsx 修):Combobox 恆 searchable → 原 `!searchable`
           // guard 使 Enter/Space 永遠開不了(僅 ArrowDown 可)。正確 guard = !open。
@@ -782,6 +791,8 @@ function CustomCombobox({
                 // empty-state fallback to trigger placeholder canonical。
                 placeholder={items.length === 0 ? placeholder : ''} onClick={(e) => { e.stopPropagation(); setOpen(true) }}
                 aria-label={searchAriaLabel}
+                // a11y(2026-07-05 D4):cmdk active item id(useActiveDescendant)→ SR 播報方向鍵導覽中的 option
+                aria-activedescendant={activeOptionId}
                 className="flex-1 min-w-[60px] bg-transparent outline-none text-body leading-compact relative z-10" />
             ) : undefined} />
         ) : (
@@ -813,6 +824,7 @@ function CustomCombobox({
   return (
     <SelectMenu
       loading={loading}
+      emptyText={emptyText}
       options={menuOptions}
       value={value}
       onValueChange={onChange as (value: string | string[]) => void}
@@ -862,7 +874,8 @@ export const comboboxMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'active' 移除 — trigger 走 Field chrome(field-wrapper 無按壓態)、menu row 走 MenuItem(其 meta 無 active)(2026-07-07 詞彙統一 DS-wide 按壓訊號盤點:檔內 0 active: utility / 0 *-active token)。
+  states: ['default', 'hover', 'focus-visible', 'disabled'],
   tokens: {
     bg: ['bg-disabled', 'bg-transparent'],
     fg: ['text-fg-disabled', 'text-fg-muted'],

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

@@ -69,18 +69,16 @@ export const CompositionRules: Story = {
           <li><LinkTo kind="Design System/Components/PeoplePicker/展示" name="單人"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">PeoplePicker</span></LinkTo>——人員搜尋(如指派任務負責人)</li>
         </ul>
 
-        <h4>Pattern 2 — Popover + Command 組成 Command Palette(Cmd+K)</h4>
-        <p>需要「全域 keyboard 觸發 + 跨頁搜尋 / 動作」→ 自行組合 <code>Popover + Command</code>(對齊 Linear ⌘K / Raycast / VS Code Quick Pick):</p>
-        <pre className="text-xs"><code>{`<Popover open={cmdkOpen}>
-  <Command>
-    <CommandInput placeholder="輸入指令..." />
-    <CommandList>
-      <CommandGroup heading="動作">
-        <CommandItem>新建文件</CommandItem>
-      </CommandGroup>
-    </CommandList>
-  </Command>
-</Popover>`}</code></pre>
+        <h4>Pattern 2 — CommandDialog 組成 Command Palette(Cmd+K)</h4>
+        <p>需要「全域 keyboard 觸發 + 跨頁搜尋 / 動作」→ 用本 DS export 的 <code>CommandDialog</code>(cmdk + Radix Dialog 包裝,內部已包 Command),不自行組合浮層(對齊 Linear ⌘K / Raycast / VS Code Quick Pick):</p>
+        <pre className="text-xs"><code>{`<CommandDialog open={cmdkOpen} onOpenChange={setCmdkOpen}>
+  <CommandInput placeholder="輸入指令..." />
+  <CommandList>
+    <CommandGroup heading="動作">
+      <CommandItem>新建文件</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</CommandDialog>`}</code></pre>
         <p className="text-fg-muted">禁止:在產品端自己刻搜尋框 + 過濾清單 — 一律重用 Command,不要重造一份。</p>
       </div>
     </div>