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

package/src/components/Dialog/dialog.stories.tsx

@@ -1,6 +1,7 @@
 // @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
 import { useState } from 'react'
 import type { Meta } from '@storybook/react'
+import { ChevronUp, ChevronDown, MoreVertical } from 'lucide-react'
 import {
   Dialog, DialogTrigger, DialogContent, DialogHeader, DialogBody, DialogFooter, DialogTitle, DialogClose,
 } from './dialog'
@@ -47,7 +48,7 @@ function NotificationSettings() {
         <DialogHeader>
           <DialogTitle>通知設定</DialogTitle>
         </DialogHeader>
-        <DialogBody className="!px-0 !pt-0 !pb-0">
+        <DialogBody className="!px-0 !pt-0 !pb-0">{/* @tabs-content-gap-ok: list-as-region canonical(body 撤 chrome padding、list wrapper py-2 own;非 tabs !pt-0 hack)*/}
           <div className="flex flex-col py-2">
             {items.map((n) => (
               // item-anatomy Family 2:[content: title + desc(--item-gap-label-desc-scanning gap)] [ItemSuffix: Switch]
@@ -239,7 +240,7 @@ export const LongContent = {
         {/* Body 放 list canonical(2026-05-01):body 撤 chrome padding(`!px-0 !pt-0 !pb-0`)+ list outer
             wrapper 自帶 `py-2`(menu group 8px breathing)+ item 自帶 `px-loose rounded-md`
             (hover bg flush 到 chrome 邊)。30 筆超出 viewport → 驗證預設高度(填滿)+ body 區捲動。 */}
-        <DialogBody className="!px-0 !pt-0 !pb-0">
+        <DialogBody className="!px-0 !pt-0 !pb-0">{/* @tabs-content-gap-ok: list-as-region canonical(body 撤 chrome padding、list wrapper py-2 own;非 tabs !pt-0 hack)*/}
           <div role="list" className="flex flex-col py-2">
             {MEMBERS.map((m, i) => (
               <MemberRow key={m.empNum} member={m} index={i} />
@@ -284,7 +285,7 @@ export const Destructive = {
 /**
  * ListBody — body 放 list 的 canonical pattern(Material / Polaris / Atlassian / Linear /
  * GitHub Primer 共識:overlay body 裝 list 時 body 不加 vertical padding,節奏源 = item 自己的 py)。
- * 我方 canonical(2026-05-01):`<DialogBody className="!px-0 !pt-0 !pb-0">` + list wrapper `py-2`
+ * 我方 canonical(2026-05-01):`<DialogBody className="!px-0 !pt-0 !pb-0">`(@tabs-content-gap-ok: list-as-region 文件範例,非 tabs !pt-0 hack)+ list wrapper `py-2`
  * + item 自帶 `px-loose rounded-md`。不加 `flush` variant — 加 1 row(search / banner)就破功,
  * 保留 chrome padding 較穩。以下三個範例對應不同 list-item tier(item-anatomy Family 2 / MenuItem)。
  */
@@ -301,7 +302,7 @@ export const ListBody = {
           <DialogHeader>
             <DialogTitle>成員列表</DialogTitle>
           </DialogHeader>
-          <DialogBody className="!px-0 !pt-0 !pb-0">
+          <DialogBody className="!px-0 !pt-0 !pb-0">{/* @tabs-content-gap-ok: list-as-region canonical(body 撤 chrome padding、list wrapper py-2 own;非 tabs !pt-0 hack)*/}
             <div role="list" className="flex flex-col py-2">
               {MEMBERS.slice(0, 6).map((m, i) => (
                 <MemberRow key={m.empNum} member={m} index={i} />
@@ -330,7 +331,7 @@ export const ListBody = {
           <DialogHeader>
             <DialogTitle>選擇標籤</DialogTitle>
           </DialogHeader>
-          <DialogBody className="!px-0 !pt-0 !pb-0">
+          <DialogBody className="!px-0 !pt-0 !pb-0">{/* @tabs-content-gap-ok: list-as-region canonical(body 撤 chrome padding、list wrapper py-2 own;非 tabs !pt-0 hack)*/}
             <div role="list" className="flex flex-col py-2">
               {['Bug', 'Feature', 'Improvement', 'Research', 'Documentation', 'Refactor', 'Test'].map((t) => (
                 // 小 item 純文字 label → 用 **MenuItem** primitive(世界級 Linear Cmd+K / Polaris OptionList
@@ -355,6 +356,66 @@ export const ListBody = {
   ),
 }
 
+/**
+ * 標頭操作(actions slot,2026-07-08 WM 戰役 codify — 關閉鈕分隔線 SSOT 化)
+ *
+ * 真實場景:任務詳情 modal(Jira / Linear / Asana 任務檢視)— header 級 prev / next 導覽
+ * + ⋮ 溢出選單,操作對象是「dialog 承載的這筆任務」本身(非欄位級、非 confirm/cancel)。
+ *
+ * - `<DialogHeader actions={…}>`:DS 自動在 actions 與內建 Close X 之間放 `<ButtonDivider>`
+ *   (action-bar.spec.md:281「最右側為關閉/解除按鈕 → 分隔線必須(誤觸保護)」;
+ *   幾何 = mx-1 於 gap-2 cluster → 12px 對稱)。**Consumer 禁自刻 cluster + divider**。
+ * - 按鈕 = `variant="text" iconOnly`(text 自動 data-unbounded,不撐高 48px chrome header;
+ *   對齊 action-bar「溢出按鈕一律最低視覺重量」)。
+ */
+export const HeaderActions = {
+  name: '標頭操作',
+  render: () => (
+    <Dialog defaultOpen>
+      <DialogTrigger asChild>
+        <Button variant="tertiary">開啟任務詳情</Button>
+      </DialogTrigger>
+      <DialogContent autoHeight maxWidth={520}>
+        <DialogHeader
+          actions={
+            <>
+              <Button variant="text" iconOnly size="sm" startIcon={ChevronUp} aria-label="上一筆任務" />
+              <Button variant="text" iconOnly size="sm" startIcon={ChevronDown} aria-label="下一筆任務" />
+              <Button variant="text" iconOnly size="sm" startIcon={MoreVertical} aria-label="更多操作" />
+            </>
+          }
+        >
+          <DialogTitle>WM-142 結帳流程改版</DialogTitle>
+        </DialogHeader>
+        <DialogBody>
+          <div className="flex flex-col gap-[var(--layout-space-loose)]">
+            <p className="text-body">
+              重新設計結帳步驟,將付款方式與發票資訊合併為單一步驟,預期提升行動端轉換率。
+            </p>
+            <div className="flex flex-col gap-2">
+              {[
+                ['指派人', 'Alan Chen'],
+                ['狀態', '進行中'],
+                ['截止日', '2026-07-18'],
+              ].map(([label, value]) => (
+                <div key={label} className="flex items-center gap-3">
+                  <span className="w-16 shrink-0 text-caption text-fg-secondary">{label}</span>
+                  <span className="text-body">{value}</span>
+                </div>
+              ))}
+            </div>
+          </div>
+        </DialogBody>
+        <DialogFooter>
+          <DialogClose asChild>
+            <Button variant="tertiary">關閉</Button>
+          </DialogClose>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  ),
+}
+
 /**
  * 標頭內含分頁(2026-05-18 從 patterns/header-canonical/header-canonical.stories.tsx 整合過來
  * per user「應該整合進去 dialog 吧?目前應該不需要獨立的 header canonical 資料夾來說明這些東西」)

package/src/components/Dialog/dialog.tsx

@@ -5,8 +5,10 @@ import { X as XIcon } from "lucide-react"
 
 import { cn } from "@/lib/utils"
 import { Button } from "@/design-system/components/Button/button"
+import { ButtonDivider } from "@/design-system/components/Button/button-group"
 import { SurfaceHeader, SurfaceFooter, type SurfaceHeaderProps } from "@/design-system/patterns/overlay-surface/overlay-surface"
 import { ScrollArea } from "@/design-system/components/ScrollArea/scroll-area"
+import { surfaceMotion } from "@/design-system/tokens/motion/overlay-motion"
 
 /**
  * Dialog (Modal) — Radix Dialog + 設計系統 token
@@ -22,7 +24,7 @@ import { ScrollArea } from "@/design-system/components/ScrollArea/scroll-area"
  *
  * ── 高度行為 ──
  * 預設：height 填滿 viewport（扣除 inset），body 捲動。防止動態內容跳動。
- * height="auto"：高度隨內容，超過 viewport 時 max-height 安全帽。
+ * autoHeight（boolean）：高度隨內容，超過 viewport 時 max-height 安全帽。
  */
 
 const Dialog = DialogPrimitive.Root
@@ -106,7 +108,8 @@ const DialogContent = React.forwardRef<
         className={cn(
           "fixed left-1/2 top-1/2 z-50 w-full -translate-x-1/2 -translate-y-1/2",
           "flex flex-col bg-surface-raised rounded-lg border border-border",
-          "data-[state=open]:animate-in data-[state=closed]:animate-out motion-reduce:animate-none",
+          surfaceMotion,
+          "data-[state=open]:animate-in data-[state=closed]:animate-out",
           "data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
           "data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95",
           "data-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%]",
@@ -129,35 +132,67 @@ const DialogContent = React.forwardRef<
 DialogContent.displayName = DialogPrimitive.Content.displayName
 
 // DialogHeader: SurfaceHeader + Close 按鈕(Dialog 特有)
-// justify-between 讓 children 與 Close 分左右;Close 用 Radix DialogPrimitive.Close 包裝。
+// Close 靠右由「第一 child flex-1 grow」達成(justify-between 已移除,見 return 註解);Close 用 Radix DialogPrimitive.Close 包裝。
 // 2026-05-18 audit gap fix:type 用 SurfaceHeaderProps 對齊 — DialogHeader 是 SurfaceHeader
-// 薄包裝,withTabs / lockDensity 等 props 透過 spread 已 forward,但 TS type 沒 expose
+// 薄包裝,withTabs / tabsSlot props 透過 spread 已 forward,但 TS type 沒 expose
 // 導致 consumer 不能用 `<DialogHeader withTabs>` 而只能寫 `as any` 繞。Type lift 修
 // per header-canonical.spec.md W1 跨 6 consumer 同契約。
+export interface DialogHeaderProps extends SurfaceHeaderProps {
+  /**
+   * Header 級操作 cluster(2026-07-08 WM 戰役 codify — 關閉鈕分隔線 SSOT 化)。
+   *
+   * 提供時 render 在 Close X 左側,DS 自動在 actions 與 Close 之間放 `<ButtonDivider>`
+   * (action-bar.spec.md:281「最右側為關閉/解除按鈕 → 分隔線必須(誤觸保護)」;
+   * 幾何 = ButtonDivider mx-1 於 gap-2 cluster → 12px 對稱,同 spec「分隔線幾何」段)。
+   *
+   * 用例:任務詳情 prev/next 導覽、header 級溢出選單(⋮)。
+   * Consumer 傳 `<Button variant="text" iconOnly …>`(text variant 自動 data-unbounded,
+   * 不撐高 chrome header)。**禁**在 children 內自刻 cluster + divider(分隔線落點歸 DS)。
+   */
+  actions?: React.ReactNode
+}
+
 const DialogHeader = React.forwardRef<
   HTMLDivElement,
-  SurfaceHeaderProps
->(({ className, children, ...props }, ref) => (
-  // 2026-05-18:className 不再硬加 justify-between(冗餘:row 1 是 flex items-center gap-2,
-  // 第一 child flex-1 grow 自然 push close X 靠右,跟 justify-between 同視覺)。
-  // 並且 column mode(tabsSlot 提供)justify-between 會把 row 1 / row 2 上下推開 = 破裂。
-  // tabsSlot via `...props` spread 自動 forward(type 來自 SurfaceHeaderProps)。
-  <SurfaceHeader
-    ref={ref}
-    className={className}
-    {...props}
-  >
-    <div className="flex-1 min-w-0">{children}</div>
-    {/* Dismiss X(chrome-slot canonical,v5):Button 本身 native sm(28 md / 32 lg,touch target 亦同),
-        但 `dismiss` prop 自動標 `data-unbounded`,SurfaceHeader CSS rule 對其套負 my 讓
-        layout 佔位 = 24(`data-dismiss` 僅作 openAutoFocus 排除 marker,與縮位無關),
-        header = 24 + 2×tight = 48 / 56 chrome-header-height ✓。
-        詳 overlay-surface.spec.md「Chrome dismiss size canonical」*/}
+  DialogHeaderProps
+>(({ className, children, actions, ...props }, ref) => {
+  // Dismiss X(chrome-slot canonical,v5):Button 本身 native sm(28 md / 32 lg,touch target 亦同),
+  // 但 `dismiss` prop 自動標 `data-unbounded`,SurfaceHeader CSS rule 對其套負 my 讓
+  // layout 佔位 = 24(`data-dismiss` 僅作 openAutoFocus 排除 marker,與縮位無關),
+  // header = 24 + 2×tight = 48 / 56 chrome-header-height ✓。
+  // 詳 overlay-surface.spec.md「Chrome dismiss size canonical」
+  const closeButton = (
     <DialogPrimitive.Close asChild>
       <Button data-dismiss iconOnly dismiss size="sm" startIcon={XIcon} aria-label="關閉" />
     </DialogPrimitive.Close>
-  </SurfaceHeader>
-))
+  )
+  return (
+    // 2026-05-18:className 不再硬加 justify-between(冗餘:row 1 是 flex items-center gap-2,
+    // 第一 child flex-1 grow 自然 push close X 靠右,跟 justify-between 同視覺)。
+    // 並且 column mode(tabsSlot 提供)justify-between 會把 row 1 / row 2 上下推開 = 破裂。
+    // tabsSlot via `...props` spread 自動 forward(type 來自 SurfaceHeaderProps)。
+    <SurfaceHeader
+      ref={ref}
+      className={className}
+      {...props}
+    >
+      <div className="flex-1 min-w-0">{children}</div>
+      {actions != null ? (
+        // actions 提供 → 右側一體 cluster:{actions} + ButtonDivider + Close。
+        // 分隔線 = 關閉保護 canonical(action-bar.spec.md:281),由 DS 放,consumer 零自刻。
+        // gap-2 + ButtonDivider mx-1 = 兩側 12px 對稱(action-bar.spec.md「分隔線幾何」)。
+        <div className="flex items-center gap-2 shrink-0">
+          {actions}
+          <ButtonDivider />
+          {closeButton}
+        </div>
+      ) : (
+        // 無 actions → 原結構(Close 直接是 SurfaceHeader child),行為零回歸
+        closeButton
+      )}
+    </SurfaceHeader>
+  )
+})
 DialogHeader.displayName = "DialogHeader"
 
 // DialogBody: flex-1 ScrollArea + chrome padding(對齊 overlay-surface SSOT + ScrollArea canonical)
@@ -169,7 +204,7 @@ DialogHeader.displayName = "DialogHeader"
 // 不再提供 `flush` variant(2026-05-01 移除,先前曾叫 `variant="list"`)。
 // **canonical pattern** = consumer 自管 list outer wrapper + 用 `className` override 撤掉 chrome padding:
 // ```tsx
-// <DialogBody className="!px-0 !pt-0 !pb-0">
+// <DialogBody className="!px-0 !pt-0 !pb-0">  ← @tabs-content-gap-ok: JSDoc 文件範例(list-as-region canonical,非 tabs !pt-0 hack)
 //   <div className="py-2">  {/* list outer wrapper 自帶 py-2(menu group canonical)*/}
 //     {items.map(item => <MenuItem className="px-[var(--layout-space-loose)] rounded-md" />)}
 //   </div>
@@ -187,7 +222,7 @@ const DialogBody = React.forwardRef<
   HTMLDivElement,
   React.ComponentPropsWithoutRef<typeof ScrollArea>
 >(({ className, children, ...props }, ref) => (
-  <ScrollArea ref={ref} data-dialog-body className="flex-1 min-h-0" {...props}>
+  <ScrollArea fillX ref={ref} data-dialog-body className="flex-1 min-h-0" {...props}>
     <div
       className={cn(
         "px-[var(--layout-space-loose)] pt-[var(--layout-space-tight)] pb-[var(--layout-space-bottom)]",

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

@@ -941,7 +941,7 @@ const StateBehaviorInner = () => {
         <span className="text-caption font-medium text-fg-secondary">行為規則</span>
         <ul className="text-caption text-fg-secondary space-y-1.5 ml-4 list-disc">
           <li>`DropdownMenuItem` 點擊即 close——這是「action 觸發即完成」語意。</li>
-          <li>`DropdownMenuCheckboxItem` 點擊**不 close**——多選語意,等使用者關 menu 才 commit。</li>
+          <li>`DropdownMenuCheckboxItem` 點擊**不 close**——每次勾選即時生效(onCheckedChange 即時 fire),menu 保持開啟只為讓使用者連續多選。</li>
           <li>`DropdownMenuSub` 永遠右側滑入,parent menu 保持展開——提供 breadcrumb 式認知流,使用者知道自己在哪層。</li>
           <li>Escape close 整個選單(含所有展開子層;Radix root close)。ArrowLeft 才逐層收合(焦點回 SubTrigger)。</li>
           <li>Portal render 到 body,`z-50` 確保不被 parent overflow 截斷。</li>

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

@@ -1,4 +1,7 @@
 // @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'
@@ -17,7 +20,6 @@ import {
   DropdownMenuSeparator,
   DropdownMenuGroup,
   DropdownMenuLabel,
-  DropdownMenuShortcut,
 } from './dropdown-menu'
 import { Button } from '@/design-system/components/Button/button'
 
@@ -313,17 +315,17 @@ export const SuffixRule: Story = {
   render: () => (
     <div>
       <Rule
-        title="DropdownMenuShortcut — 鍵盤快捷鍵（ml-auto 靠右）"
-        note="使用者熟悉快捷鍵後可跳過選單直接按快捷鍵。shortcut 用 fg-muted 作為輔助資訊色,不搶 label 注意力"
+        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>新增<DropdownMenuShortcut>⌘N</DropdownMenuShortcut></DropdownMenuItem>
-            <DropdownMenuItem>開啟<DropdownMenuShortcut>⌘O</DropdownMenuShortcut></DropdownMenuItem>
-            <DropdownMenuItem>儲存<DropdownMenuShortcut>⌘S</DropdownMenuShortcut></DropdownMenuItem>
+            <DropdownMenuItem shortcut="⌘N">新增</DropdownMenuItem>
+            <DropdownMenuItem shortcut="⌘O">開啟</DropdownMenuItem>
+            <DropdownMenuItem shortcut="⌘S">儲存</DropdownMenuItem>
           </DropdownMenuContent>
         </DropdownMenu>
       </Rule>

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

@@ -69,8 +69,8 @@ DropdownMenu                    ← Radix Root，管理開關狀態
 
 **快捷鍵提示 API（兩條,擇一不混用）**：
 - **Canonical:`<DropdownMenuItem shortcut="⌘C">`** prop —— 渲染進 MenuItem `endContent` 正規後綴 slot(跟 badge / endIcon 同槽,gap / 對齊一致)。**標準場景一律用 prop。**
-- **Escape-hatch:`<DropdownMenuShortcut>` child** —— 對齊 shadcn DropdownMenuShortcut idiom,供需手動 compose children 的少數場景(用 `ml-auto` 塞 children,繞過 endContent slot)。
-- 兩者**視覺統一**(`text-caption` + `tracking-shortcut` + `fg-muted`,與 CommandShortcut 一致);**同一 item 只用一種**(見「禁止事項」)。
+- **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 的自動分隔
@@ -90,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 理念一致）
@@ -123,7 +123,7 @@ CheckboxItem 和 RadioItem 雖然涉及「選擇」，但它們控制的是**即
 
 - prefix：由 `DropdownMenuItem` 的 `startIcon` prop 傳入，經 MenuItem 內部的 prefix 對齊容器（消費 item-anatomy 的 `itemPrefixAlignVariants`，`h-[1lh]` 對齊第一行 label）渲染。icon 跟 label 同色（foreground）
 - label：文字內容，`flex-1`
-- suffix：canonical 走 item prop（`shortcut` / `badge` / `endIcon` → MenuItem `endContent` 正規 slot）；`DropdownMenuShortcut` child 僅 escape-hatch（`ml-auto` 靠右，見「快捷鍵提示 API」段）。指示型 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。
 
@@ -209,7 +209,7 @@ DropdownMenu 是掃描模式——使用者快速瀏覽選項，所有尺寸使
 
 ## StateBehavior(DropdownMenu 層級特有)
 
-Item-level default / hover / focused / selected / disabled **色彩**由 MenuItem primitive SSOT 擁有(`patterns/element-anatomy/item-anatomy.spec.md`「選擇 / 狀態視覺規則」),在本元件 `ColorMatrix` story 承載並直接引用 MenuItem token。**selected × highlighted 疊加(2026-07-04 Q2 拍板)**:selected bg 勝 Radix `data-[highlighted]`(hover + keyboard cursor)— 對齊 MenuItem「selected 勝 hover」canonical(menu-item.spec.md 狀態表),`selected && 'data-[highlighted]:bg-neutral-selected'` override;CheckboxItem/RadioItem checked 同規則。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 疊加(2026-07-04 Q2 拍板)**:selected bg 勝 Radix `data-[highlighted]`(hover + keyboard cursor)— 對齊 MenuItem「selected 勝 hover」canonical(menu-item.spec.md 狀態表),`selected && 'bg-neutral-selected data-[highlighted]:bg-neutral-selected-active'` override(selected×highlighted 加深一階 `bg-neutral-selected-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 沒有的維度。
 
 ---
 

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

@@ -13,6 +13,7 @@ import {
   ICON_SIZE as ROW_ICON_SIZE,
   type RowSize,
 } from "@/design-system/patterns/element-anatomy/item-anatomy"
+import { overlayMotion } from "@/design-system/tokens/motion/overlay-motion"
 
 /**
  * DropdownMenu — Radix DropdownMenu + MenuItem visual layer
@@ -41,7 +42,8 @@ import {
 // ── Floating layer 共用樣式 ──
 const floatingLayerClass = [
   'z-50 overflow-hidden rounded-lg border border-border bg-surface-raised',
-  'data-[state=open]:animate-in data-[state=closed]:animate-out motion-reduce:animate-none',
+  overlayMotion,
+  'data-[state=open]:animate-in data-[state=closed]:animate-out',
   'data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
   'data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95',
   'data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2',
@@ -97,8 +99,10 @@ DropdownMenuTrigger.displayName = DropdownMenuPrimitive.Trigger.displayName
 // 的 8px,只需在第二個起的 group 加 8+8 = 16px gap + border)
 //
 // **視覺結果等同**:兩種實作的 visual output 一致,只是「padding 住在哪層」
-// 不同。不強制統一 CSS 表達式——DropdownMenuContent 的 py-2 是既有 Radix
-// 期望的行為,移除會影響 trigger 鍵盤導覽的 focus offset。
+// 不同。不強制統一 CSS 表達式——DropdownMenuContent 的 py-2 是純視覺 Content
+// 邊界 padding(Radix roving focus 依 collection refs + element.focus(),不讀
+// CSS padding;對齊 spec.md「為什麼不直接套 py-2」段)。Group 若再套 py-2 會
+// double padding,故 Group 用 mt-2/pt-2 只加在第二個起。
 const DropdownMenuGroup = React.forwardRef<
   React.ElementRef<typeof DropdownMenuPrimitive.Group>,
   React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Group>
@@ -423,7 +427,8 @@ const DropdownMenuSeparator = React.forwardRef<
 DropdownMenuSeparator.displayName = DropdownMenuPrimitive.Separator.displayName
 
 // ── RadioItem（單選，排序方式等）──
-// Radix handles checked state; visual用 MenuItem 的 selected highlight。
+// Radix handles checked state;checked 底色套在外層 Radix RadioItem 本身(parent-bg
+// pattern,詳下方 2026-05-31 #10 註解),內層 MenuItem 恆 !bg-transparent 讓它透出。
 interface DropdownMenuRadioItemProps
   extends React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.RadioItem> {
   /** Prefix icon(LucideIcon) */
@@ -467,12 +472,16 @@ const DropdownMenuRadioItem = React.forwardRef<
 })
 DropdownMenuRadioItem.displayName = DropdownMenuPrimitive.RadioItem.displayName
 
-// ── Shortcut（鍵盤快捷鍵提示，ml-auto 靠右）──
+// ── Shortcut（鍵盤快捷鍵提示 child;escape-hatch,不靠右）──
 // **Canonical 是 `<DropdownMenuItem shortcut="⌘C">`** prop —— 走 MenuItem `endContent` 正規後綴 slot
-// (跟 badge / endIcon 同槽、gap/對齊一致)。本 child 是 **composition escape-hatch**(對齊 shadcn
-// DropdownMenuShortcut idiom),供需手動 compose children 的少數場景;它用 `ml-auto` 塞在 children
-// 內(繞過 endContent slot)。**同一 item 只用一種,勿混用**(見 spec.md 禁止事項)。
-// 視覺統一:text-caption + tracking-shortcut + fg-muted(對齊 prop 後綴 + CommandShortcut)。
+// (跟 badge / endIcon 同槽、gap/對齊一致,真正靠右對齊列尾)。本 child 是 **composition
+// escape-hatch**(相容 shadcn DropdownMenuShortcut idiom = `ml-auto` span,source:
+// https://ui.shadcn.com/docs/components/dropdown-menu;npm published API 不砍)。⚠️ 在
+// DropdownMenuItem 內 children 會進 MenuItem ItemContent 的 label `<span>`(inline context,
+// 非 flex row),故 `ml-auto` **不生效、不會靠右**——只會 inline 附加在 label 文字尾;`ml-auto`
+// 僅在 consumer 自組 flex row 時生效。要靠右一律用 canonical `shortcut` prop。**同一 item
+// 只用一種,勿混用**(見 spec.md「快捷鍵提示 API」+ 禁止事項)。
+// 字體樣式統一:text-caption + tracking-shortcut + fg-muted(對齊 prop 後綴 + CommandShortcut);位置不等價。
 const DropdownMenuShortcut = ({ className, ...props }: React.HTMLAttributes<HTMLSpanElement>) => (
   <span
     className={cn('ml-auto text-caption text-fg-muted tracking-shortcut', className)}

package/src/components/Empty/empty.anatomy.stories.tsx

@@ -146,7 +146,7 @@ export const ScenarioMatrix: Story = {
       <div>
         <H3>Table 空資料</H3>
         <div className="border border-border rounded-lg p-8">
-          <Empty description="無資料" className="py-12" />
+          <Empty description="還沒有訂單" className="py-12" />
         </div>
       </div>
 

package/src/components/Empty/empty.spec.md

@@ -132,8 +132,8 @@ Empty 是 **non-interactive layout primitive**——本身無 ARIA role(讓 cons
 ## 消費範例
 
 ```tsx
-// Table 空狀態(最簡)
-<Empty description="沒有資料" />
+// Table 空狀態(最簡)——文案仍點出「缺什麼資料」,避免抽象的「無資料」(見「禁止事項」)
+<Empty description="還沒有訂單" />
 
 // SelectMenu 無結果
 <Empty icon={SearchX} description="找不到符合的結果" />

package/src/components/Field/field-context.ts

@@ -1,8 +1,9 @@
 import * as React from 'react'
-import type { FieldMode, FieldVariant } from './field-types'
+import type { FieldMode, FieldVariant, FieldVariantInternal, FieldWidth } from './field-types'
+import { EMPTY_DISPLAY } from './field-wrapper'
 
 // ── Types ──
-export type { FieldMode, FieldVariant }
+export type { FieldMode, FieldVariant, FieldVariantInternal, FieldWidth }
 export type FieldOrientation = 'vertical' | 'horizontal'
 export type FieldSize = 'sm' | 'md' | 'lg'
 export type FieldControlLayout = 'inline' | 'block'
@@ -29,7 +30,8 @@ export interface FieldContextValue {
   descriptionId: string
   errorId: string
   mode: FieldMode
-  /** 視覺外殼透傳(2026-05-05)。default = 含 border+bg;bare = 透明 variant,hover/focus reveal。
+  /** 視覺外殼透傳(2026-05-05)。default = 含 border+bg;naked = cell-as-input(edit×naked 自畫 border-based state machine;display/readonly/disabled×naked 用 transparent border 由 host cell 供邊框);`bare` 2026-07-09 退役;naked 2026-07-14 型別收窄至
+   *  FieldVariantInternal(@internal)— 公開 `<Field variant>` 只收 default,故本欄位維持 FieldVariant。
    *  child Field control 自動繼承,per-control prop override 可覆寫。詳 field-types.ts。 */
   variant: FieldVariant
   disabled: boolean
@@ -202,10 +204,12 @@ export function useResolvedFieldMode({
 }
 
 /**
- * Resolve Field control 的 **variant**(default / bare / naked 視覺外殼)— 2026-06-08 SSOT。
+ * Resolve Field control 的 **variant**(default / naked 視覺外殼;`bare` 2026-07-09 退役)— 2026-06-08 SSOT。
  * 優先序:顯式 prop > FieldContext.variant > 'default'。與既有各控件公式一字不差(Δ=0),統一以利 gate 強制。
+ * 2026-07-14 API 策展 E:入參 / 回傳 widen 為 FieldVariantInternal — naked 僅 DataTable cell-registry
+ * 經 @internal 通道傳入(公開 prop 型別 = FieldVariant,不含 naked)。
  */
-export function useResolvedFieldVariant(variantProp?: FieldVariant | null): FieldVariant {
+export function useResolvedFieldVariant(variantProp?: FieldVariantInternal | null): FieldVariantInternal {
   const fieldCtx = React.useContext(FieldContext)
   return variantProp ?? fieldCtx?.variant ?? 'default'
 }
@@ -232,3 +236,63 @@ export function FieldSurfaceSizeProvider({
 }): React.ReactElement {
   return React.createElement(FieldSurfaceSizeContext.Provider, { value: size }, children)
 }
+
+/**
+ * Table-cell 可編輯訊號(2026-07-08 user 拍板)— 獨立於 FieldSurfaceContext / FieldSurfaceSizeContext
+ * 的純 boolean context,由 host(DataTable cell registry)注入該 cell 是否可編輯,讓 useFieldEmptyDisplay
+ * 分流「可編輯 cell 空 display → 空白」vs「不可編輯 cell 空 display → '-'」。
+ * value = boolean primitive(stable when unchanged),不破壞 cell memo identity(同 TableScrollContext /
+ * FieldSurfaceSizeContext L119-121 canonical);絕不污染 FieldContext(useFieldContext() 在 cell 內仍 null)。
+ */
+const FieldSurfaceEditableContext = React.createContext<boolean>(false)
+
+export function FieldSurfaceEditableProvider({
+  isEditable,
+  children,
+}: {
+  isEditable: boolean
+  children: React.ReactNode
+}): React.ReactElement {
+  return React.createElement(FieldSurfaceEditableContext.Provider, { value: isEditable }, children)
+}
+
+/**
+ * 空值顯示分流(2026-07-08 user 拍板,verbatim「...都用"-"...我從頭到尾哪裡有說要用全形的」):
+ *
+ * | 情境                                           | 空值顯示 |
+ * |------------------------------------------------|----------|
+ * | table-cell **可編輯** 的 display 靜止態        | **空白 `''`**(不佔位,affordance = hover outline)|
+ * | table-cell **不可編輯**(readonly cell)        | **半形 `-`** |
+ * | standalone display / readonly / form / toolbar | **半形 `-`** |
+ *
+ * 收斂式:`surface==='table-cell' && isEditable ? '' : EMPTY_DISPLAY`。
+ * 可編輯 form / edit 輸入框走 native placeholder(不經此 hook)。boolean → unchecked / disabled →
+ * 同上文字 + text-fg-disabled(M24),各控件自理。
+ * 世界級對照:table-cell blank = MUI X / AG Grid / Ant core / Notion / Airtable grid 域共識;
+ * 非 table `-` = Ant ProTable `columnEmptyText`(見 field-wrapper.tsx EMPTY_DISPLAY 註)。
+ * SSOT 條文 → field-controls.spec.md「null / undefined 值」;全 Field family display/readonly/disabled
+ * 空值渲染必經此 hook,禁直接引 EMPTY_DISPLAY 常數(genre 分流會漏)。
+ */
+export function useFieldEmptyDisplay(): string {
+  const surface = useFieldSurface()
+  const isEditable = React.useContext(FieldSurfaceEditableContext)
+  return surface === 'table-cell' && isEditable ? '' : EMPTY_DISPLAY
+}
+
+/**
+ * 空值符號「-」顏色分流(2026-07-09 user 拍板 verbatim「「-」代表的是不可編輯只拿來供檢視的值
+ * 所以應該跟readonly 的value同樣顏色吧」):
+ *
+ * 「-」是「不可編輯、供檢視的值」→ 同 readonly value 色 = `text-foreground`
+ * (field-wrapper.tsx base `text-foreground`),**非** `text-fg-muted`(muted 是「可編輯 placeholder
+ * 提示」的裝飾語意;空值符號不是提示、是被檢視的值狀態)。
+ * disabled 態維持 `text-fg-disabled`(M24 disabled 顯著性 > foreground/muted,不可被蓋)。
+ *
+ * SSOT:全 Field family display/readonly/disabled 空值 span 消費此 helper,傳入已 resolve 的
+ * resolvedMode。純函式(非 hook)—— resolvedMode 已由 useResolvedFieldMode 解析(含控件自身
+ * disabled prop,context hook 讀不到);故以 resolvedMode 為入參,可條件呼叫、不受 Rules of Hooks 限制。
+ * 世界級對照:Ant read-only / Carbon read-only value = 正常前景色;placeholder 才 muted。
+ */
+export function fieldEmptyColorClass(resolvedMode: FieldMode): string {
+  return resolvedMode === 'disabled' ? 'text-fg-disabled' : 'text-foreground'
+}