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

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

@@ -0,0 +1,261 @@
+// @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 React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Trash2, AlertTriangle } from 'lucide-react'
+import {
+  Dialog,
+  DialogTrigger,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogBody,
+  DialogFooter,
+} from './dialog'
+import { Button } from '@/design-system/components/Button/button'
+import { Input } from '@/design-system/components/Input/input'
+
+const meta: Meta = {
+  title: 'Design System/Components/Dialog/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+const Rule = ({
+  title, note, children,
+}: {
+  title: string; note?: string; children: React.ReactNode
+}) => (
+  <div className="mb-14">
+    <h3 className="text-body font-bold text-foreground mb-1">{title}</h3>
+    {note && <p className="text-caption text-fg-muted mb-5 max-w-[720px] leading-relaxed">{note}</p>}
+    <div className="flex flex-col gap-3 max-w-md">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p className={`text-footnote leading-normal ${warn ? 'text-error font-medium' : 'text-fg-muted'}`}>{children}</p>
+)
+
+// ── WhenToUse — 何時使用 Dialog ──────────────────────
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / WhenNotToUse(2026-04-26 v3 canonical)
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div className="flex flex-col gap-12">
+      {/* 何時用 — 原 WhenToUse */}
+      <div className="prose prose-sm max-w-prose">
+      <p>適合 Dialog 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          <LinkTo kind="Design System/Components/Dialog/展示" name="表單"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">表單</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Dialog/展示" name="長內容"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">長內容</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Dialog/展示" name="危險操作"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">危險操作</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Dialog/展示" name="主體放清單"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">主體放清單</span></LinkTo>
+        </li>
+      </ul>
+      <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見 <code>Vs*Rule</code> stories)。</p>
+    </div>
+
+      {/* 何時不用 / 替代元件 — 原 WhenNotToUse */}
+      <div>
+      <Rule
+        title="Dialog 的 sweet spot — 需要使用者聚焦的操作流程、阻斷背景互動"
+        note="建立 / 編輯複雜表單、破壞性動作確認、重要公告。Overlay + 居中 modal 強制使用者完成或取消才能回到頁面"
+      >
+        <Dialog>
+          <DialogTrigger asChild>
+            <Button variant="primary">建立新專案</Button>
+          </DialogTrigger>
+          <DialogContent autoHeight maxWidth={480}>
+            <DialogHeader>
+              <DialogTitle>建立新專案</DialogTitle>
+            </DialogHeader>
+            <DialogBody>
+              <div className="space-y-3">
+                <Input placeholder="專案名稱" />
+                <Input placeholder="專案描述" />
+              </div>
+            </DialogBody>
+            <DialogFooter>
+              <Button variant="tertiary">取消</Button>
+              <Button variant="primary">建立</Button>
+            </DialogFooter>
+          </DialogContent>
+        </Dialog>
+      </Rule>
+
+      <Rule
+        title="❌ 操作結果短暫回饋：用 Toast"
+        note="儲存成功 / 刪除失敗等結果回饋是「短暫非阻斷」的——使用者不需要按「確定」關閉，也不該被流程打斷。Dialog 會阻斷流程，Toast 自動消失"
+      >
+        <Dialog>
+          <DialogTrigger asChild>
+            <Button variant="primary">❌ 「儲存成功」用 Dialog</Button>
+          </DialogTrigger>
+          <DialogContent autoHeight maxWidth={400}>
+            <DialogHeader>
+              <DialogTitle>儲存成功</DialogTitle>
+            </DialogHeader>
+            <DialogBody>
+              <p className="text-body">您的變更已儲存至伺服器</p>
+            </DialogBody>
+            <DialogFooter>
+              <Button variant="primary">確定</Button>
+            </DialogFooter>
+          </DialogContent>
+        </Dialog>
+        <Label warn>↑ 儲存成功應該 Toast 閃一下就消失，不該打斷使用者再按「確定」</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 持久性頁面通知：用 Alert"
+        note="「方案即將到期」「帳號未驗證」這類需要 persistent 顯示 + 使用者主動處理的訊息，Alert 嵌入在頁面中，不阻斷流程但持續可見"
+      >
+        <Dialog>
+          <DialogTrigger asChild>
+            <Button variant="primary">❌ 方案到期提示用 Dialog</Button>
+          </DialogTrigger>
+          <DialogContent autoHeight maxWidth={420}>
+            <DialogHeader>
+              <DialogTitle>方案即將到期</DialogTitle>
+            </DialogHeader>
+            <DialogBody>
+              <p className="text-body">您的方案將在 3 天後到期</p>
+            </DialogBody>
+          </DialogContent>
+        </Dialog>
+        <Label warn>↑ 到期提示每次進首頁都跳 Dialog → 反覆阻斷；應該用 Alert 持久 inline 通知</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 側邊工作流程：用 Sheet"
+        note="檢視某項目詳情、側邊 filter panel、編輯 inspector——這類與主頁面平行的工作，使用者仍需看到主頁 context。Sheet 從邊緣滑入、較輕，不完全阻斷視線"
+      >
+        <div className="text-footnote text-fg-muted">（範例：task 詳情側邊編輯 — 應該用 Sheet，不用 Dialog 完全阻斷主清單）</div>
+      </Rule>
+
+      <Rule
+        title="✅ 破壞性動作確認（Dialog 的典型用途）"
+        note="刪除、登出多裝置、放棄變更等動作必須 Dialog 確認——這種動作不該用 Toast（沒有確認流程）、不該用 Sheet（視覺不夠強調）、必須 modal 強制聚焦"
+      >
+        <Dialog>
+          <DialogTrigger asChild>
+            <Button variant="primary" danger startIcon={Trash2}>永久刪除專案</Button>
+          </DialogTrigger>
+          <DialogContent autoHeight maxWidth={440}>
+            <DialogHeader>
+              <DialogTitle>確定要永久刪除此專案？</DialogTitle>
+            </DialogHeader>
+            <DialogBody>
+              <p className="text-body">此動作無法復原，所有相關資料將一併刪除。</p>
+            </DialogBody>
+            <DialogFooter>
+              <Button variant="tertiary">取消</Button>
+              <Button variant="primary" danger>永久刪除</Button>
+            </DialogFooter>
+          </DialogContent>
+        </Dialog>
+      </Rule>
+    </div>
+    </div>
+  ),
+}
+
+export const HeightBehaviorRule: Story = {
+  name: '高度行為選擇',
+  render: () => (
+    <div>
+      <Rule
+        title="內容會載入、展開或變化：使用預設高度"
+        note="預先穩定 dialog 的可用高度，讓 body 獨立捲動，可避免異步資料或展開區塊使整個浮層上下跳動。設定面板、動態清單與未知長度的內容應保留預設值。"
+      >
+        <Label>判斷關鍵是「開啟後內容高度還會不會變」，不是當下看起來有幾行。</Label>
+      </Rule>
+
+      <Rule
+        title="內容已知且穩定：使用 autoHeight"
+        note="確認框、短表單與固定文案可讓浮層貼合內容，避免少量資訊佔滿視窗。若未來會加入異步 section，應回到預設高度，不要為當前快照選 autoHeight。"
+      >
+        <Label>「刪除專案？」這類單一決策適合 autoHeight；會增減區塊的設定流程不適合。</Label>
+      </Rule>
+
+      <Rule
+        title="內容長度不只是高度問題"
+        note="超過三步、需長時間停留，或使用者必須同時參照背景頁面的流程，應改用獨立頁面或 Sheet。Dialog 的 modal 阻斷成本不會因為可捲動就消失。"
+      >
+        <Label>高度 mode 只解決佈局穩定性；工作流載體仍要先在 Dialog、Sheet 與獨立頁面之間做選擇。</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const FooterActionRule: Story = {
+  name: '頁尾按鈕配對',
+  render: () => (
+    <div>
+      <Rule
+        title="Primary + Tertiary 是預設配對（儲存 + 取消 / 確認 + 取消）"
+        note="確認類動作用 primary，取消類動作用 tertiary。按鈕靠右對齊（justify-end），primary 在最右（使用者動線終點）"
+      >
+        <Dialog>
+          <DialogTrigger asChild>
+            <Button variant="tertiary">標準配對</Button>
+          </DialogTrigger>
+          <DialogContent autoHeight maxWidth={420}>
+            <DialogHeader>
+              <DialogTitle>儲存變更</DialogTitle>
+            </DialogHeader>
+            <DialogBody>
+              <p className="text-body">變更將儲存到雲端，其他協作者將看到更新。</p>
+            </DialogBody>
+            <DialogFooter>
+              <Button variant="tertiary">取消</Button>
+              <Button variant="primary">儲存</Button>
+            </DialogFooter>
+          </DialogContent>
+        </Dialog>
+      </Rule>
+
+      <Rule
+        title="破壞性動作：Primary + danger"
+        note="刪除 / 永久移除等動作用 primary + danger（立即且不可逆）。必須搭配 Cancel button 讓使用者反悔"
+      >
+        <Dialog>
+          <DialogTrigger asChild>
+            <Button variant="tertiary" startIcon={AlertTriangle}>刪除動作確認</Button>
+          </DialogTrigger>
+          <DialogContent autoHeight maxWidth={420}>
+            <DialogHeader>
+              <DialogTitle>確定要刪除？</DialogTitle>
+            </DialogHeader>
+            <DialogBody>
+              <p className="text-body">此動作無法復原。</p>
+            </DialogBody>
+            <DialogFooter>
+              <Button variant="tertiary">取消</Button>
+              <Button variant="primary" danger startIcon={Trash2}>永久刪除</Button>
+            </DialogFooter>
+          </DialogContent>
+        </Dialog>
+      </Rule>
+
+      <Rule
+        title="❌ 只有一顆「確定」按鈕的 Dialog 是反模式"
+        note="單一「確定」按鈕的 Dialog 等於強迫使用者 acknowledge 訊息——這類訊息應該用 Toast（短暫非阻斷）或 Alert（持久顯示）。Dialog 的阻斷成本太高"
+      >
+        <Label warn>↑ 改用 Toast 或 Alert，Dialog 保留給有決策 / 動作選擇的場景</Label>
+      </Rule>
+    </div>
+  ),
+}

package/src/components/Dialog/dialog.spec.md

@@ -12,7 +12,6 @@ benchmark:
   - Polaris Modal: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Modal
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
 
 # Dialog 設計原則
 
@@ -48,27 +47,27 @@ Modal 對話框，基於 Radix Dialog。用於**需要使用者注意力、阻
 
 ```
 DialogContent (fixed, centered)
-├── DialogHeader (SurfaceHeader + Close X)
+├── DialogHeader(消費 SurfaceHeader)
 │   ├── DialogTitle
-│   └── Close button (<Button iconOnly dismiss size="sm" startIcon={X} />)
-├── DialogBody (flex-1 ScrollArea wrap + inner padding div,pb-bottom)
-└── DialogFooter (SurfaceFooter alias)
+│   └── Close button(永遠存在,規格見「關閉按鈕」)
+├── DialogBody(scrollable——ScrollArea canonical,見下)
+└── DialogFooter(消費 SurfaceFooter)
     └── Action buttons
 ```
 
 **Padding SSOT**：Header / Body / Footer 的 padding + 分隔線由 `patterns/overlay-surface/overlay-surface.spec.md` own——Dialog 與 Popover 共用同一套 primitive，避免 token 漂移。Dialog 特有行為:Header 的 Close 按鈕;Body 用 `<ScrollArea>` wrap(viewport-fill 專用,SSOT 見 overlay-surface.spec.md 「Body overflow canonical」節 + `components/ScrollArea/scroll-area.spec.md`)。
 
-## Density(2026-04-22 v5 校準:繼承 page density,跟 Sheet 對齊)
+## Density(2026-06-16 定論:全繼承 page,不鎖)
 
-Dialog **繼承 page `data-density`**,不自設密度 attribute。這是 overlay primitive 的 canonical(跟 `components/Sheet/sheet.tsx` 對齊 — Sheet 不自設 density,繼承 page 層級 `html[data-density]`,見 sheet.tsx line 111 canonical)。
+Dialog **不自設任何 density attribute**,layout-space + ui-size 全繼承 page。效果:md page → body `px-loose`=16 / header `py-tight`=12(header 48);lg page → 24 / 16(header 56),隨 page。
 
-**歷史備忘**:先前曾設 `data-layout-space="lg"` 給 header/body 寬鬆呼吸,但跟 `--chrome-header-height` canonical 衝突(md page dialog header 期望 48,強設 lg 會變 56)。**已於 2026-04-22 v5 撤回**,Dialog 全盤繼承 page density,header 高度 = `--chrome-header-height` 自動對齊(md=48 / lg=56)。
+**為何不鎖(撤回本 session 一度加的 `data-layout-space="lg"`)**:本 `density.spec` 第 10 行親自定義 layout-space 管「dialog body padding」—— Dialog 若鎖死 layout-space,等於 override 我們自家 dial 對它點名要管的對象失效 = **自相矛盾**。有「同類 padding-density dial」的世界級 DS(SAP Fiori cozy/compact 做 `syncStyleClass` 專門把 page density 同步進 dialog;AWS Cloudscape compact「propagate to all components, in all view types」,例外只列 informational + tiny dropdown,modal 不在內)都讓 **modal 跟 page dial 走**,沒有一家把 modal 釘固定 tier。Material/Atlassian 的固定 24 是因為它們**沒有** density dial(其 24 = 我方 lg)。
 
-**世界級對照**:
-- Polaris Modal:px 16(= md loose)
-- Material M3 Dialog:px 24(= lg loose)
-- Atlassian Dialog:px 24
-- 我方:跟隨 page density,md=16 / lg=24,兩端都在世界級 range 內。
+**「modal 要寬鬆呼吸」怎麼滿足**:lg 產品自動拿 24(Material 級);md 產品本就要緊湊(資訊密集),16 是合格 modal padding(Polaris Modal = 16,世界級下限)。**「button 不撐高 header」**由 ui-size 繼承 page 解決(button = page sm),與 layout-space 鎖不鎖無關 → 故不需鎖。
+
+**Header 高度**:padding-based = title line-box 24 + `py-tight`×2 → md 48 / lg 56,**隨 page tier**(= `--chrome-header-height` 同 tier 對齊)。
+
+**世界級對照**:Material M3 / Atlassian 24(無 dial,= 我方 lg)/ Polaris 16(= 我方 md 下限)/ SAP Fiori + Cloudscape(有 dial → modal 跟 dial = 我方繼承)。
 
 ## Layout
 
@@ -84,30 +83,41 @@ Modal 與 viewport 四邊保持 `--layout-space-bottom`（48px）最小間距。
 
 | 模式 | 條件 | 行為 |
 |---|---|---|
-| **預設（填滿）** | 不傳 `autoHeight` | `height = 100vh - inset*2`，body 捲動。防止動態內容（載入資料、展開 section）造成 dialog 跳動 |
+| **預設（填滿）** | 不傳 `autoHeight` | viewport-bounded 固定高度，body 擁有捲動；動態內容不改變 dialog 外框幾何 |
 | **autoHeight** | `autoHeight={true}` | 高度隨內容，超過 viewport 時 `max-height` 安全帽。適合內容量已知且穩定的 dialog（確認框、短表單） |
 
 ## maxWidth
 
 預設 512px，consumer 可透過 `maxWidth` prop 調整。型別 `string | number`（傳 number 視為 px）。
 
+**邊界**:上限被 viewport inset 截斷 `min(maxWidth, 100vw - inset*2)`(見「Viewport Inset」);無下限 clamp——過小值不擋,內容溢出走 body 捲動,由 consumer 自負。
+
 ## 關閉按鈕
 
 > **跨家族 SSOT pointer**:DialogHeader 屬 **Padding-based overlay header 家族**;border / padding / dismiss size / withTabs(tabs 進 header 時 border auto-suppress)的跨家族視覺契約 SSOT 詳 `patterns/header-canonical/header-canonical.spec.md`。本節僅 codify Dialog 特有 close X size + chrome-unbounded rationale。
 
 永遠存在於 DialogHeader 右側。使用 `<Button data-dismiss iconOnly dismiss size="sm" startIcon={X} aria-label="關閉" />`，不可移除——使用者永遠需要明確的關閉手段。
 
-**Size canonical(v5 chrome-unbounded)**:Button native size **sm**(28 md / 32 lg),touch target 亦同。SurfaceHeader 的 `[data-unbounded]` CSS rule 自動對 text variant / dismiss 套負 my `calc((xs-sm)/2)` → **layout 佔位 = 24**(xs 固定)。效果:
-- Header 只有 title + close X → max layout = 24 → header = 24 + 2×tight = **48 md / 56 lg = `--chrome-header-height`** ✓
+**Size canonical(v5 chrome-unbounded)**:Button native size **sm**(隨 page density:28 md / 32 lg),touch target 亦同。SurfaceHeader 的 `[data-unbounded]` CSS rule 自動對 text variant / dismiss 套負 my → **layout 佔位 = title line-box**(slot 衍生自 `--font-body-lg-size`×1.5=24,見 `overlay-surface.spec.md` slot 段)。效果:
+- Header 只有 title + close X → max layout = 24 → header = 24 + 2×`py-tight`(隨 page:md 12 / lg 16)= **48 md / 56 lg**(= `--chrome-header-height` 同 tier 對齊)✓
 - Header 塞 bounded primary(無 `data-unbounded`)→ header 自然長高
 
-**Canonical 來源**:Dialog 是 overlay chrome，corner close X 屬 action group region，必用 Button(非 Inline Action / 非自刻 button)。詳見 `patterns/element-anatomy/item-anatomy.spec.md`「Dismiss canonical」+ `patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」。
+**Canonical 來源**:Dialog 是 overlay chrome，corner close X 屬 action group region，必用 Button(非 Inline Action / 非自刻 button)。詳見 `patterns/element-anatomy/inline-action.spec.md`「Dismiss canonical — X close only」+ `patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」。
+
+### Header actions slot(2026-07-08)
+
+Header 級操作(記錄 prev / next 導覽、header 級溢出選單 ⋮ 等「作用於整個 dialog 內容」的操作)走 `<DialogHeader actions={…}>` slot,**不**塞 children 自刻右側 cluster。
+
+- **何時用**:操作對象是 dialog 承載的記錄本身(切換上下筆、複製連結、更多選單)。欄位級操作仍歸 body;confirm / cancel 歸 footer。
+- **分隔線由 DS 自動放**:actions 與內建 Close X 之間 DS 渲 `<ButtonDivider>` — `action-bar.spec.md:281`「最右側為關閉 / 解除按鈕 → 分隔線必須(誤觸保護)」;幾何 = ButtonDivider `mx-1` 於 `gap-2` cluster → 兩側 12px 對稱(同 spec「分隔線幾何」段)。
+- **按鈕形態**:`<Button variant="text" iconOnly …>`(text variant 自動 `data-unbounded`,不撐高 chrome header;對齊 action-bar「溢出按鈕一律最低視覺重量」)。
+- ❌ **禁**:consumer 在 children 內自刻 cluster + divider(分隔線落點歸 DS,自刻 = 漏分隔線 / 幾何 drift 根因 — 2026-07-08 WM 詳情 header 錨例)。
 
 ## Title
 
-`text-body-lg font-medium truncate`——單行截斷，不換行。
+`text-body-lg font-medium truncate`——單行截斷，不換行；截斷時 hover 顯 tooltip 補完整標題（僅實際截斷才顯——rule owner `components/Tooltip/tooltip.spec.md`「截斷文字 → tooltip」；實作消費 `patterns/element-anatomy/truncated-text.spec.md` `<TruncatedText>`）。
 
-**Header 可成長**:Dialog 提供 `<DialogDescription>` primitive 作副標/補充說明(`mt-[var(--item-gap-label-desc-reading-lg)] text-body text-fg-secondary` — title body-lg 16 + desc body 14 → reading-lg token)。Consumer 傳 title + description 時 header 自然長高(這也是為何 Dialog / Sheet / Popover 的 SurfaceHeader 刻意 **padding-based 而非 fixed-h** — 宣告 chrome 可成長)。詳見 `patterns/overlay-surface/overlay-surface.spec.md`「為什麼 SurfaceHeader 是 padding-based」+ `tokens/uiSize/uiSize.spec.md`「消費 --chrome-header-height 的 2 種實作 pattern」。
+**Header 可成長**:Dialog 提供 `<DialogDescription>` primitive 作副標/補充說明(`mt-[var(--item-gap-label-desc-reading-lg)] text-body text-fg-secondary` — title body-lg 16 + desc body 14 → reading-lg token)。Consumer 傳 title + description 時 header 自然長高(這也是為何 Dialog / Sheet / Popover 的 SurfaceHeader 刻意 **padding-based 而非 fixed-h** — 宣告 chrome 可成長)。詳見 `patterns/overlay-surface/overlay-surface.spec.md`「為什麼 SurfaceHeader 是 padding-based」+ `tokens/uiSize/uiSize.spec.md`「Chrome header 選型 canonical」節(含「2 種 pattern 對照」)。
 
 ## Footer 按鈕
 
@@ -140,13 +150,28 @@ Dialog 是容器，無整體 disabled / loading / empty 狀態——這些屬於
 
 **Dark mode**：由 semantic token（`bg-surface-raised` / `border-border`）自動切換，無自訂 palette。
 
-**Density**:Dialog **繼承 page density**(v5 校準,跟 Sheet 對齊),見上「Density」段。
+**Density**:Dialog **全繼承 page**(layout-space + ui-size 皆不自鎖),見上「Density」段。
+
+---
+
+## 常見誤解
+
+| 誤解 | 正解 |
+|------|------|
+| 「側邊 / 長停留面板也用 Dialog」 | 視覺重量不同——Dialog 是中央阻斷 modal,Sheet 側滑較輕(見「何時不用」+ 禁止事項「長 form wizard」條) |
+| 「autoHeight 是預設」 | 預設採 viewport-bounded 固定高度以維持穩定外框；autoHeight 只給內容量已知且穩定的短 dialog(見「高度行為」) |
+| 「maxWidth 想設多寬都行」 | 受 viewport inset 公式截斷(見「maxWidth」邊界) |
+| 「視覺不顯示標題就可拿掉 DialogTitle」 | 必須保留,用 VisuallyHidden 包裹給 screen reader(見「A11y 預設」) |
 
 ---
 
 ## 禁止事項
 
-- ❌ **不在 Dialog 內 nested Dialog**：modal 疊 modal 會形成焦點陷阱地獄（使用者無法預測 Esc 關哪一層），複雜多步驟流程改用單一 Dialog + 內部步驟切換
+- ❌ **不用 nested Dialog 承載多步驟流程**：一層一步的精靈式堆疊會讓使用者失去所在位置感，複雜多步驟流程改用單一 Dialog + 內部步驟切換。
+  **⚠️ 本條 2026-08-09 收窄**（原文是「不在 Dialog 內 nested Dialog」，理由寫「使用者無法預測 Esc 關哪一層」）。兩個問題：
+  （a）**該理由在本專案的技術棧不成立**——`@radix-ui/react-focus-scope` 的 `createFocusScopesStack()` 在新 scope 進入時 `pause()` 前一層、移除時 `resume()`；`@radix-ui/react-dismissable-layer` 以 layers 陣列索引判定，Esc 與 outside-click 只作用於最上層。堆疊順序是確定的，不是不可預測。
+  （b）**原文與本檔「何時用」段自相矛盾**——`:29` 明列「破壞性動作確認：刪除、**離開不儲存**」是 Dialog 用途，而「離開不儲存」的確認必然出現在正在編輯的 Dialog 之上。原文的全稱禁令讓這個既有用途無法表達。
+  **收窄後允許**：確認 / 警告 / 破壞性動作二次確認可疊在既有 Dialog 之上（Esc 只關最上層）。**仍禁止**：把流程步驟拆成一層層 Dialog。
 - ❌ **不用 Dialog 顯示非阻斷訊息**：成功 / 失敗的短暫回饋用 Toast；持續性系統狀態用 Alert。Dialog 的阻斷成本過高
 - ❌ **不把長 form wizard 塞 Dialog**：超過 3 步驟或表單高度接近全螢幕的流程改用獨立頁面或 Sheet，Dialog 不適合長時間停留
 - ❌ **不在 Dialog footer 把 primary action 放左側**：CTA 靠右（`justify-end`）是跨平台使用者期待（macOS / Windows / Web 主流皆如此），反向放置會降低可用性
@@ -157,7 +182,7 @@ Dialog 是容器，無整體 disabled / loading / empty 狀態——這些屬於
 
 Radix Dialog 自動處理：
 
-- **Modal 語意**：`role="dialog"` + `aria-modal="true"`
+- **Modal 語意**：`role="dialog"`(Radix 刻意**不**設 `aria-modal="true"`,改用 aria-hidden 的 `hideOthers()` 把背景兄弟節點設 `aria-hidden` + FocusScope trap 達成隔離,避免 `aria-modal` 在部分 screen reader 隱藏整頁的已知 bug）
 - **標題綁定**：`<DialogTitle>` 自動成為 `aria-labelledby` 指向對象，screen reader 開啟時讀出標題
 - **Focus trap**：焦點鎖在 Dialog 內，Tab 循環不逃出
 - **Esc 關閉**：按 Esc 自動關閉
@@ -168,11 +193,11 @@ Consumer 必須保留 `<DialogTitle>`——即使視覺不顯示，也要用 `Vi
 
 ---
 
-## 為何無 Inspector
+## anatomy story 結構
 
-Dialog 是 modal 浮層元件,關鍵決策維度是 `maxWidth`(400/480/560/720)× `autoHeight` × `destructive` × open/close 行為——已由 `SizeMatrix`(maxWidth 4 檔) / `HeightBehavior`(viewport-fill vs autoHeight) / `DestructiveMatrix` / `StateBehavior`(open / close / ESC / overlay click) 四張矩陣 + `ColorMatrix`(layout + 視覺 token)完整覆蓋。互動 Inspector 切單一 open/close 不如結構性矩陣對照——Dialog 的正確用法是「照情境選 size / 選 autoHeight」,需要 side-by-side 比對決策。
+Dialog 是 modal 浮層元件,關鍵決策維度是 `maxWidth`(400/480/512/560/720)× `autoHeight` × `destructive` × open/close 行為。互動 `Inspector`(右側 Controls 即時切 `maxWidth` / `autoHeight` 看寬度 tier 與高度模式差異)搭配結構性矩陣 side-by-side 比對,完整呈現「照情境選 size / 選 autoHeight」的決策。
 
-對應 anatomy story:保留 `Overview` + 元件特有 `HeightBehavior` / `DestructiveMatrix` + `SizeMatrix` + `StateBehavior` + `ColorMatrix`。
+對應 anatomy story:`Overview` + `Inspector` + 元件特有 `HeightBehavior` / `DestructiveMatrix` + `SizeMatrix` + `StateBehavior` + `ColorMatrix` + `Accessibility`。
 
 ---
 
@@ -191,12 +216,13 @@ Dialog 是 modal 浮層元件,關鍵決策維度是 `maxWidth`(400/480/560/720)
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `accordion.spec.md`
+- `alert.spec.md`
 - `coachmark.spec.md`
+- `command.spec.md`
+- `dropdown-menu.spec.md`
 - `file-viewer.spec.md`
-- `layoutSpace.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
-- `density.spec.md`
+- `overlay-surface.spec.md`
+- `popover.spec.md`
+- `scroll-area.spec.md`
+- `sheet.spec.md`
+- `toast.spec.md`