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

package/src/components/Toast/toast.spec.md

@@ -36,7 +36,7 @@ Toast 是**短暫的浮動通知，自動消失**。用於操作結果回饋（
 
 **實作基礎**：基於 sonner（浮動管理）+ 消費 Notice primitive（layout + icon + theme 策略，與 Alert 共用）。
 
-**Layout Family**：CLAUDE.md 4-Family Model **Family 2（List item layout）** 消費者。結構繼承 `patterns/element-anatomy/item-anatomy.spec.md`「List item layout」章節的 reading-mode 規格。Toast 透過 Notice 繼承 Family 2 結構。
+**Layout Family**：本元件是 `patterns/element-anatomy/item-anatomy.spec.md` 所擁有的 **Family 2（List item layout）** 消費者。結構繼承其「List item layout」章節的 reading-mode 規格；Toast 透過 Notice 繼承 Family 2 結構。
 
 ---
 
@@ -44,7 +44,7 @@ Toast 是**短暫的浮動通知，自動消失**。用於操作結果回饋（
 
 - **操作結果短暫回饋**：儲存成功、訊息已送出、已複製到剪貼簿、刪除失敗
 - **背景非同步動作完成**：檔案上傳完成、資料同步完成、通知已寄出
-- **需要「復原」按鈕的操作**：刪除後 4 秒內可 Undo（sonner action 模式）
+- **需要「復原」按鈕的操作**：刪除後 10 秒內可 Undo（sonner action 模式；含 `action` 的 toast 預設 `duration` = 10000ms，見「API」段）
 - **非關鍵資訊**：訊息即使使用者沒看到也不影響流程
 
 ## 何時不用
@@ -70,17 +70,23 @@ Toast 是**短暫的浮動通知，自動消失**。用於操作結果回饋（
 
 - ❌ **不用 Toast 做 critical confirmation**：Toast 會自動消失，使用者可能沒看到就消失——關鍵訊息改用 Alert 或 Dialog
 - ❌ **不用 Toast 取代 error validation**：欄位錯誤訊息要貼近發生位置（FieldError），Toast 定位遠離錯誤欄位,使用者難對應到錯誤來源
-- ❌ **不同時彈 > 3 個 Toast**：同時多則 Toast 視覺雜訊重且無法閱讀，sonner 會自動 queue；應用層若批量觸發 toast,整理成單一 Toast with list 或改用 Alert
+- ❌ **不同時彈 > 3 個 Toast**：同時多則 Toast 視覺雜訊重且無法閱讀，sonner 預設只顯示最近 3 則（`visibleToasts=3`），超出的仍在 DOM 內但以 `data-visible=false` 隱藏堆疊（非 queue 到 DOM 外或延後建立）；應用層若批量觸發 toast,整理成單一 Toast with list 或改用 Alert
 - ❌ **不把需要 user action 的內容放 Toast**：action 按鈕僅限「復原 / Undo」這類非必要後手——強制 CTA（付款、確認刪除）用 Dialog
 
 ---
 
 ## A11y 預設
 
-- **預設**（success / info / neutral）：`role="status"` + `aria-live="polite"`——screen reader 在空閒時讀出，不中斷使用者
-- **error / warning 升級**：`role="alert"` + `aria-live="assertive"`——立即中斷朗讀通知使用者
-- **由 sonner 自動管理**：本 DS 不覆寫 sonner 的 a11y 行為，consumer 無需額外處理
-- **關閉按鈕**：若 consumer 自訂 action,務必提供 `aria-label`（sonner 內建 dismiss 已處理）
+- **預設**（success / info / neutral）：`Toaster` 的 stable sibling `role="status"` + `aria-live="polite"` 在 screen reader 空閒時讀出，不中斷使用者。
+- **error / warning 升級**：另一個 stable sibling `role="alert"` + `aria-live="assertive"` 立即播報。severity 完全由 `variant` 路由，沒有 per-instance 降級開關。
+- **DS 自帶完整 announcer**：consumer 只需在 app root 掛一次 `<Toaster />`，不必、也不應另建 live region。`Toaster` 就地渲染三個 DOM siblings：Sonner 視覺 `<section aria-live="polite">`、DS polite region、DS assertive region；後兩者不在 Sonner section 內。
+- **視覺 Toast 不是 live region**：Sonner 2.0.7 在 `dist/index.mjs` 寫死 viewport `<section aria-live="polite" aria-relevant="additions text" aria-atomic="false">`，`Toaster` props 沒有對應 override；每則 visual toast 則是 `tabIndex=0` 的 `<li data-sonner-toast>`，custom JSX 放在其內。DS 因此把 custom visual root 設為 `role="group" aria-live="off"`，將其從 Sonner 父層 polite 變更播報中切出，避免重複播報或 warning / error 被父層降成 polite。`aria-live` 是 inherited ARIA state，明確 `off` 是對父層的局部 override，且不會從 accessibility tree 隱藏內容。
+- **不用 `aria-hidden` 隱藏視覺 Toast**：Sonner `<li>` 仍可由 ⌥T / Alt+T hotkey 聚焦，group 內的標題、描述、action 和 dismiss 仍可被閱讀與操作。含互動子元素的 toast 不可包在 `aria-hidden` 中。
+- **連續相同訊息仍會播報**：`toast()` 每次呼叫都產生單調遞增 sequence，announcer 會 replace live region 的 text node；即使文案完全相同也有可觀察的 child-list mutation，不會因 React 相同 string 而被略過。
+- **SSR-safe**：module scope 只保留 listener / sequence，render 期間不讀 `window` / `document`；DOM text-node 更新只在 client `useEffect` 訂閱後執行。`Toaster` 尚未 mount 前呼叫 `toast()` 不會製造 server-side DOM side effect，app-level 合約仍是先在 root 安裝單一 `Toaster`。
+- **action 與關閉鈕之間的分隔線**（2026-08-06 補；原本未定義）：由 Notice 基座自動放，與 Alert 完全一致——兩者共用同一個 suffix 容器與同一顆 X（`notice.tsx`）。語意 SSOT → `patterns/action-bar/action-bar.spec.md` 第五節理由 3（誤觸保護）：有 `action` 時加，只有 X 時不加。**不因 action 的 variant（tertiary 有框 / text 無框）而改變**——結構相同就該行為相同
+- **關閉按鈕**：畫面上可見的 X 關閉鈕由 Notice 渲染（`<Button dismiss aria-label="關閉通知">`，見 `../Notice/notice.tsx`），已自帶 `aria-label`，不是 sonner 內建 close 鈕（本 DS 用 `sonner.custom` + `unstyled`，未開 `closeButton`）。若 consumer 自訂 `action`，務必為自訂互動元素提供 `aria-label`。
+- **自動關閉計時器與鍵盤暫停路徑**（2026-07-05 D4）：sonner 計時器只在滑鼠 hover / pointer 按住 / 分頁切離時暫停——**Tab 鍵盤焦點進入 toast 不暫停倒數**（sonner 2.x 行為，`expanded / interacting` 只由 mouse / pointer 事件設定）。鍵盤替代路徑是 sonner 內建 hotkey **⌥T（Option+T / Alt+T）**：焦點跳入 toast 區域並展開 stack（`expanded=true`）→ 倒數暫停，焦點離開後恢復。為給鍵盤使用者足夠反應時間，含 `action` 的 toast 預設 `duration` 加長為 10000ms（見「API」段；WCAG 2.2.1 Timing Adjustable）。
 
 ---
 
@@ -94,7 +100,7 @@ Toast 是**短暫的浮動通知，自動消失**。用於操作結果回饋（
 
 ### 為什麼分三層
 
-陰影 token（`--elevation-200`）在 dark mode = 45% black，light mode = 4% black。如果陰影跟 `data-theme="dark"` 在同一層，light 頁面上的 dark toast 會有過重的 dark 陰影。分開讓陰影永遠用頁面 theme 的輕陰影。
+陰影 token（`--elevation-200`）在 dark mode = 25% black（`--black-a25`），light mode = 4% black（`--black-a04`）。如果陰影跟 `data-theme="dark"` 在同一層，light 頁面上的 dark toast 會有過重的 dark 陰影。分開讓陰影永遠用頁面 theme 的輕陰影。
 
 ## Variant × Theme 策略
 
@@ -116,27 +122,26 @@ toast({
   title: '操作成功',
   description: '變更已儲存至伺服器',
   action: { label: '復原', onClick: handleUndo },
-  duration: 4000,
 })
 ```
 
 - `title`（必填）：主要訊息
 - `description`（選填）：補充說明，自然換行
 - `action`（選填）：tertiary xs 按鈕
-- `duration`（選填）：自動關閉時間，預設 4000ms
+- `duration`（選填）：自動關閉時間；預設依 `action` 而定——有 `action` → **10000ms**（鍵盤焦點不暫停 sonner 倒數，10 秒給鍵盤使用者足夠時間按到「復原 / 重試」，見「A11y 預設」段；2026-07-05 D4 user 拍板，對齊 Polaris toast with action ≥10s / Carbon actionable notification 預設 persistent），無 `action` → **4000ms**
 
 ## 寬度（元件級常數）
 
-Toast 固定 **360px 寬**（見 `.tsx` 的 `w-[360px]`）——跨通知視覺一致，避免長短不一造成視覺跳動；同時限制單一通知橫向占據空間，不遮蔽過多頁面內容。
+Toast 使用單一元件級寬度，以維持穩定的訊息行長與頁面遮蔽上限；canonical 數值與 utility 由 `toast.tsx` 擁有，調整時連同對應 story baseline 驗證。
 
 對照世界級：Material Snackbar 固定 344px、Sonner default toast 固定寬度——**單一元件的 canonical 寬度屬於該元件自己的 design spec，不抽為跨元件 token**。Token 系統只管共享值（如 `--field-height-*`、`--layout-space-*`）；單一元件獨有的結構常數留在 component code + 本 spec。
 
-## 為何無 Inspector / SizeMatrix
+## Inspector 形態特例 / 為何無 SizeMatrix
 
-- **無 Inspector**:Toast 透過 `toast()` **函式觸發**,不是 JSX 元件,沒有可 inspect 的 prop 面板——應有的互動玩法是「按鈕按下 → toast 浮現」,已由 `Overview` 中的 Action buttons 覆蓋。ToastOptions 的 schema 完整列於 `Overview` 表格。
+- **Inspector(函式觸發形態)**:Toast 透過 `toast()` **函式觸發**,不是 JSX 元件——anatomy `Inspector` story 以 Controls 編 ToastOptions + 觸發按鈕即時跳出對應通知,取代典型 JSX prop 面板;ToastOptions schema 另完整列於 `Overview` 表格。
 - **無 SizeMatrix**:Toast 固定寬度 **360px**(見本 spec「寬度(元件級常數)」段),單一 canonical width 跨 variant 不變——參考 Material Snackbar 344px / Sonner default。無 sm/md/lg size prop,也不隨 density 變(浮層是獨立視覺語境)。
 
-對應 anatomy story:保留 `Overview` + 元件特有 `ContainerArchitecture`(三層結構解 shadow 陰影 bug) + `ColorMatrix`(Variant × Theme 策略) + `StateBehavior`(dismiss / stacking / pause / swipe)。
+對應 anatomy story:`Overview` + `Inspector` + 元件特有 `ContainerArchitecture`(三層結構解 shadow 陰影 bug) + `ColorMatrix`(Variant × Theme 策略) + `StateBehavior`(dismiss / stacking / pause / swipe) + `Accessibility`。
 
 ---
 
@@ -145,9 +150,11 @@ Toast 固定 **360px 寬**（見 `.tsx` 的 `w-[360px]`）——跨通知視覺
 Toast 的 public API 是 `toast()` 函式(imperative 觸發)+ `<Toaster />` Provider(app-level,置於 main.tsx 一次)。**兩者皆非「forwardRef + ...props + asChild」canonical shadcn 元件 pattern**:
 
 - `toast(...)` 是 imperative API(sonner 負責 queue / stack / animation / auto-dismiss),consumer 不需持有 DOM ref
-- `<Toaster />` 是 Provider(sonner 內部管理 portal container),consumer 在 app root 放一次,無 consumer-facing DOM operation
+- `<Toaster />` 是 Provider(sonner 內部管理 viewport container),consumer 在 app root 放一次,無 consumer-facing DOM operation
 
-**sonner 已實作五件套內部**(Toaster Root 有 forwardRef / viewport DOM spread / 適當 a11y role=status/alert)。我們不再 wrap 一層,保持與 sonner 直接對應,避免 API 膨脹。
+**sonner 已實作 stack / viewport 內部**(Toaster 就地渲染外層 `<section aria-live="polite">` viewport region,以 CSS `position: fixed` 覆蓋 viewport——非 portal,sonner 不用 `createPortal`)。多則同時觸發時 sonner 不是 queue 到 DOM 外,而是全部渲染進 DOM、預設只顯示最近 3 則(`visibleToasts=3`)、超出項以 `data-visible=false` 隱藏堆疊。DS 另渲染的 polite / assertive announcer 是 Sonner section 的 siblings，不加視覺 wrapper、不影響 geometry。
+
+**app-level-one 是強制合約**：每個 application root 只能 mount 一個 `<Toaster />`。Sonner 使用 module-global toast store，DS announcer 也是 module-global event stream；同一 app 掛多個 Toaster 會讓每個 instance 都渲染同一批視覺 toast、也同時訂閱同一訊息，導致重複視覺與重複播報。DS 不假裝支援 multi-Toaster；各頁 / feature 不另掛，共用 app-shell 那一個。Storybook 每個獨立 story root 各掛一個不違反此合約。
 
 若 consumer 需要程式化控制(`toast.dismiss(id)` / `toast.promise(...)`),使用 sonner 原生 API,Toast 元件層不重新暴露。
 
@@ -174,4 +181,7 @@ Toast 的 public API 是 `toast()` 函式(imperative 觸發)+ `<Toaster />` Prov
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `alert.spec.md`
+- `dialog.spec.md`
+- `notice.spec.md`
 - `sheet.spec.md`

package/src/components/Toast/toast.stories.tsx

@@ -0,0 +1,241 @@
+import type { Meta } from '@storybook/react'
+import { Notice, type NoticeVariant } from '@/design-system/components/Notice/notice'
+import { Button } from '@/design-system/components/Button/button'
+import { Toaster, toast } from './toast'
+
+const meta: Meta = {
+  title: 'Design System/Components/Toast/展示',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { description: { component: '在操作完成後短暫顯示非阻斷回饋，由 Toaster 統一管理位置與佇列。適用儲存成功、背景工作完成等可自行消退的訊息；需持續閱讀或操作時用 Alert。' } },
+  },
+}
+export default meta
+
+// 2026-07-04 audit:補 'info'(NoticeVariant 5 值,原漏 → 靜態雙 theme 對照未涵蓋全 variant)
+// 2026-07-14 Dim 68 修:原 warning =「訂閱 7 天後停用 + 續訂 CTA」= 持久帳務狀態 + 強制 CTA,
+// 違反 toast.spec.md「持久性系統狀態(方案過期)→ Alert」+「❌ 不把需要 user action 的內容
+// 放 Toast(action 僅限復原類非必要後手)」。改為短暫操作回饋(匯入部分完成)+ 非必要「查看」後手。
+const VARIANTS: NoticeVariant[] = ['neutral', 'info', 'success', 'warning', 'error']
+const LABELS: Record<string, string> = {
+  neutral: '檔案已複製到剪貼簿',
+  info: '新版本 v2.4 可用',
+  success: '專案已儲存',
+  warning: '匯入部分完成',
+  error: '無法連線伺服器',
+}
+const ACTIONS: Record<string, string> = {
+  neutral: '復原',
+  info: '查看更新',
+  success: '查看',
+  warning: '查看',
+  error: '重試',
+}
+const DESCRIPTIONS: Record<string, string> = {
+  neutral: '「Q3 營收報表.xlsx」已加入剪貼簿',
+  info: '重新整理頁面即可套用新功能',
+  success: '變更已同步到所有成員',
+  warning: '120 筆已匯入,3 筆格式錯誤被略過',
+  error: '請檢查網路後再試一次',
+}
+
+/**
+ * 靜態 Toast 展示——完全複製 Toast.tsx 的三層結構:
+ * 1. Shadow wrapper: rounded-lg + elevation-200
+ * 2. Bg layer: bg-{color}
+ * 3. Theme layer: data-theme + text-foreground
+ *
+ * pageTheme 模擬頁面 theme,用來計算 inverse。
+ */
+function StaticToast({ variant, title, description, pageTheme }: {
+  variant: NoticeVariant; title: string; description?: string; pageTheme: 'light' | 'dark'
+}) {
+  const inverse = pageTheme === 'light' ? 'dark' : 'light'
+  const isInverse = variant === 'neutral' || variant === 'success'
+  const actionBtn = <Button variant="tertiary" size="xs">{ACTIONS[variant]}</Button>
+
+  // ── inverse: bg + theme 同層 ──
+  if (isInverse) {
+    return (
+      <div className="rounded-lg overflow-hidden w-[360px]" style={{ boxShadow: 'var(--elevation-200)' }}>
+        <div data-theme={inverse} className="bg-surface-raised text-foreground">
+          <Notice variant={variant} title={title} description={description}
+            iconClassName={variant === 'success' ? 'text-success' : undefined}
+            endContent={actionBtn} />
+        </div>
+      </div>
+    )
+  }
+
+  // ── 有色相: bg outer + theme inner ──
+  const bg = variant === 'warning' ? 'bg-warning' : variant === 'error' ? 'bg-error' : 'bg-info'
+  const theme = variant === 'warning' ? 'light' : 'dark'
+
+  return (
+    <div className="rounded-lg overflow-hidden w-[360px]" style={{ boxShadow: 'var(--elevation-200)' }}>
+      <div className={bg}>
+        <div data-theme={theme} className="text-foreground">
+          <Notice variant={variant} title={title} description={description} endContent={actionBtn} />
+        </div>
+      </div>
+    </div>
+  )
+}
+
+function modeLabel(variant: NoticeVariant, pageTheme: 'light' | 'dark') {
+  if (variant === 'warning') return 'light'
+  if (variant === 'neutral' || variant === 'success') return pageTheme === 'light' ? 'dark' : 'light'
+  return 'dark'
+}
+
+export const WithDescription = {
+  name: '有標題與描述',
+  render: () => (
+    <div className="flex gap-16">
+      <div className="flex flex-col gap-4">
+        <span className="text-caption text-fg-secondary font-medium">light mode</span>
+        <div className="flex flex-col gap-3 p-8 rounded-lg bg-canvas border border-divider">
+          {VARIANTS.map((v) => (
+            <div key={v} className="flex items-center gap-4">
+              <span className="text-caption text-fg-secondary w-24 shrink-0">套 {modeLabel(v, 'light')} theme</span>
+              <StaticToast variant={v} title={LABELS[v]} description={DESCRIPTIONS[v]} pageTheme="light" />
+            </div>
+          ))}
+        </div>
+      </div>
+      <div className="flex flex-col gap-4" data-theme="dark">
+        <span className="text-caption text-fg-secondary font-medium">dark mode</span>
+        <div className="flex flex-col gap-3 p-8 rounded-lg bg-canvas border border-divider">
+          {VARIANTS.map((v) => (
+            <div key={v} className="flex items-center gap-4">
+              <span className="text-caption text-fg-secondary w-24 shrink-0">套 {modeLabel(v, 'dark')} theme</span>
+              <StaticToast variant={v} title={LABELS[v]} description={DESCRIPTIONS[v]} pageTheme="dark" />
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const Interactive = {
+  name: '點擊觸發通知',
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <span className="text-caption text-fg-muted">點按鈕觸發 Toast</span>
+      <div className="flex flex-wrap gap-2">
+        <Button variant="secondary" onClick={() => toast({ title: '檔案已複製到剪貼簿', action: { label: '復原', onClick: () => {} } })}>複製檔案</Button>
+        <Button variant="secondary" onClick={() => toast({ variant: 'success', title: '專案已儲存', description: '變更已同步到所有成員', action: { label: '查看', onClick: () => {} } })}>儲存專案</Button>
+        <Button variant="secondary" onClick={() => toast({ variant: 'warning', title: '匯入部分完成', description: '120 筆已匯入,3 筆格式錯誤被略過', action: { label: '查看', onClick: () => {} } })}>匯入資料</Button>
+        <Button variant="secondary" onClick={() => toast({ variant: 'error', title: '無法連線伺服器', description: '請檢查網路後再試一次', action: { label: '重試', onClick: () => {} } })}>斷線示範</Button>
+      </div>
+      <Toaster />
+    </div>
+  ),
+}
+
+/**
+ * Deterministic regression contract for Sonner's fixed polite viewport and the DS-owned sibling
+ * announcers. Kept test-only because the reader-facing accessibility explanation lives in the
+ * anatomy story; this story mechanically proves the DOM and repeated-message behavior.
+ */
+export const LiveRegionContract = {
+  name: '朗讀區域互動',
+  tags: ['test-only'],
+  render: () => (
+    <div className="flex flex-wrap gap-2">
+      <Button
+        data-testid="toast-live-neutral"
+        onClick={() => toast({
+          variant: 'neutral',
+          title: '相同通知',
+          description: '連續觸發仍必須播報',
+          action: { label: '復原', onClick: () => {} },
+          duration: 60000,
+        })}
+      >
+        neutral
+      </Button>
+      <Button data-testid="toast-live-info" onClick={() => toast({ variant: 'info', title: '資訊通知', duration: 60000 })}>info</Button>
+      <Button data-testid="toast-live-success" onClick={() => toast({ variant: 'success', title: '成功通知', duration: 60000 })}>success</Button>
+      <Button data-testid="toast-live-warning" onClick={() => toast({ variant: 'warning', title: '警告通知', duration: 60000 })}>warning</Button>
+      <Button data-testid="toast-live-error" onClick={() => toast({ variant: 'error', title: '錯誤通知', duration: 60000 })}>error</Button>
+      <Toaster />
+    </div>
+  ),
+  play: async ({ canvasElement }: { canvasElement: HTMLElement }) => {
+    const { expect, userEvent, waitFor, within } = await import('@storybook/test')
+    const canvas = within(canvasElement)
+    const sonnerRegion = canvasElement.querySelector<HTMLElement>('section[aria-live="polite"]')
+    const politeRegion = canvasElement.querySelector<HTMLElement>('[data-toast-live-region="polite"]')
+    const assertiveRegion = canvasElement.querySelector<HTMLElement>('[data-toast-live-region="assertive"]')
+
+    await expect(sonnerRegion).not.toBeNull()
+    await expect(politeRegion).not.toBeNull()
+    await expect(assertiveRegion).not.toBeNull()
+    if (!sonnerRegion || !politeRegion || !assertiveRegion) return
+
+    // Sonner viewport and both DS announcers must be siblings; neither DS region may be nested in
+    // Sonner's hard-coded polite region.
+    await expect(politeRegion.parentElement).toBe(sonnerRegion.parentElement)
+    await expect(assertiveRegion.parentElement).toBe(sonnerRegion.parentElement)
+    await expect(sonnerRegion.contains(politeRegion)).toBe(false)
+    await expect(sonnerRegion.contains(assertiveRegion)).toBe(false)
+    await expect(politeRegion).toHaveAttribute('role', 'status')
+    await expect(politeRegion).toHaveAttribute('aria-live', 'polite')
+    await expect(assertiveRegion).toHaveAttribute('role', 'alert')
+    await expect(assertiveRegion).toHaveAttribute('aria-live', 'assertive')
+
+    const MutationObserverCtor = canvasElement.ownerDocument.defaultView?.MutationObserver
+    if (!MutationObserverCtor) throw new Error('MutationObserver is required for the Toast live-region contract')
+    let politeChildMutations = 0
+    const observer = new MutationObserverCtor((records) => {
+      politeChildMutations += records.filter((record) => record.type === 'childList').length
+    })
+    observer.observe(politeRegion, { childList: true })
+
+    await userEvent.click(canvas.getByTestId('toast-live-neutral'))
+    await waitFor(() => expect(politeRegion).toHaveTextContent('相同通知。連續觸發仍必須播報'))
+    const firstSequence = politeRegion.dataset.announcementSequence
+    const mutationsAfterFirstTrigger = politeChildMutations
+
+    const visualContent = await waitFor(() => {
+      const node = canvasElement.querySelector<HTMLElement>('[data-toast-visual-content]')
+      expect(node).not.toBeNull()
+      return node
+    })
+    await expect(visualContent).toHaveAttribute('role', 'group')
+    await expect(visualContent).toHaveAttribute('aria-live', 'off')
+    await expect(visualContent?.closest('[aria-hidden="true"]')).toBeNull()
+    const visualToast = visualContent?.closest<HTMLElement>('[data-sonner-toast]')
+    await expect(visualToast).toHaveAttribute('tabindex', '0')
+    await expect(visualContent?.querySelector('[aria-label="關閉通知"]')).not.toBeNull()
+    await expect(visualContent?.textContent).toContain('復原')
+    // There may be aria-live="off" visual groups, but no active nested live region.
+    await expect(sonnerRegion.querySelector('[aria-live="polite"], [aria-live="assertive"]')).toBeNull()
+
+    await userEvent.click(canvas.getByTestId('toast-live-neutral'))
+    await waitFor(() => expect(politeRegion.dataset.announcementSequence).not.toBe(firstSequence))
+    await waitFor(() => expect(politeChildMutations).toBeGreaterThan(mutationsAfterFirstTrigger))
+
+    for (const [testId, message] of [
+      ['toast-live-info', '資訊通知'],
+      ['toast-live-success', '成功通知'],
+    ] as const) {
+      await userEvent.click(canvas.getByTestId(testId))
+      await waitFor(() => expect(politeRegion).toHaveTextContent(message))
+    }
+    await expect(assertiveRegion).toBeEmptyDOMElement()
+
+    for (const [testId, message] of [
+      ['toast-live-warning', '警告通知'],
+      ['toast-live-error', '錯誤通知'],
+    ] as const) {
+      await userEvent.click(canvas.getByTestId(testId))
+      await waitFor(() => expect(assertiveRegion).toHaveTextContent(message))
+    }
+
+    observer.disconnect()
+  },
+}

package/src/components/Toast/toast.tsx

@@ -28,6 +28,71 @@ export interface ToastOptions {
   duration?: number
 }
 
+type ToastAnnouncement = {
+  level: 'polite' | 'assertive'
+  message: string
+  sequence: number
+}
+
+type ToastAnnouncementListener = (announcement: ToastAnnouncement) => void
+
+const toastAnnouncementListeners = new Set<ToastAnnouncementListener>()
+let toastAnnouncementSequence = 0
+
+function subscribeToToastAnnouncements(listener: ToastAnnouncementListener) {
+  toastAnnouncementListeners.add(listener)
+  return () => {
+    toastAnnouncementListeners.delete(listener)
+  }
+}
+
+function publishToastAnnouncement(options: ToastOptions) {
+  const isCritical = options.variant === 'error' || options.variant === 'warning'
+  const announcement: ToastAnnouncement = {
+    level: isCritical ? 'assertive' : 'polite',
+    message: [options.title, options.description].filter(Boolean).join('。'),
+    sequence: ++toastAnnouncementSequence,
+  }
+
+  toastAnnouncementListeners.forEach((listener) => listener(announcement))
+}
+
+function ToastLiveRegions() {
+  const politeRef = React.useRef<HTMLDivElement>(null)
+  const assertiveRef = React.useRef<HTMLDivElement>(null)
+
+  React.useEffect(() => subscribeToToastAnnouncements((announcement) => {
+    const region = announcement.level === 'assertive' ? assertiveRef.current : politeRef.current
+    if (!region) return
+
+    // Replace the text node instead of assigning the same React string again. That guarantees an
+    // observable child-list mutation even when two consecutive toasts have identical copy.
+    region.dataset.announcementSequence = String(announcement.sequence)
+    region.replaceChildren(region.ownerDocument.createTextNode(announcement.message))
+  }), [])
+
+  return (
+    <>
+      <div
+        ref={politeRef}
+        role="status"
+        aria-live="polite"
+        aria-atomic="true"
+        data-toast-live-region="polite"
+        className="sr-only"
+      />
+      <div
+        ref={assertiveRef}
+        role="alert"
+        aria-live="assertive"
+        aria-atomic="true"
+        data-toast-live-region="assertive"
+        className="sr-only"
+      />
+    </>
+  )
+}
+
 function ToastInner({
   id,
   variant = 'neutral',
@@ -38,17 +103,22 @@ function ToastInner({
   const isInverse = variant === 'neutral' || variant === 'success'
   const dismiss = () => sonnerToast.dismiss(id)
 
+  // action 執行後自動 dismiss:關閉「復原/重試」的重複觸發窗口(double-undo / double-retry),
+  // 對齊 Polaris Toast action / Material Snackbar action 按後即收慣例;
+  // toast.anatomy.stories.tsx「點 action button 執行 callback + 關閉 toast」宣稱自此為真。
   const actionButton = action ? (
-    <Button variant="tertiary" size="xs" onClick={action.onClick}>{action.label}</Button>
+    <Button variant="tertiary" size="xs" onClick={() => { action.onClick(); dismiss() }}>{action.label}</Button>
   ) : undefined
 
-  // ── Live region 由 outer Toast wrapper 擁有(WAI-ARIA + spec L59-60 canonical) ──
-  // Notice(inner layout)不再帶 role,避免 nested live region。
-  // - error / warning → role="alert" + aria-live="assertive"(中斷朗讀)
-  // - info / success / neutral → role="status" + aria-live="polite"(空閒朗讀)
-  const isCritical = variant === 'error' || variant === 'warning'
-  const liveRole = isCritical ? 'alert' : 'status'
-  const liveLevel = isCritical ? 'assertive' : 'polite'
+  // Sonner 2.0.7 owns a fixed aria-live="polite" section around every visual toast and does not
+  // expose an override. Mark our custom visual subtree as non-live so it remains readable/focusable
+  // through Sonner's tabIndex=0 toast + ⌥T hotkey without becoming a nested live region. The two
+  // stable sibling regions rendered by <Toaster> own announcements and severity routing.
+  const visualA11yProps = {
+    role: 'group',
+    'aria-live': 'off',
+    'data-toast-visual-content': '',
+  } as const
 
   // ── 1. Shadow wrapper（統一,永遠在頁面 theme） ──
   // ── 2+3. Bg + theme layer ──
@@ -56,7 +126,7 @@ function ToastInner({
   if (isInverse) {
     // bg-surface-raised 需要跟 data-theme 同層翻轉
     return (
-      <div role={liveRole} aria-live={liveLevel} className="rounded-lg overflow-hidden" style={{ boxShadow: 'var(--elevation-200)' }}>
+      <div {...visualA11yProps} className="rounded-lg overflow-hidden" style={{ boxShadow: 'var(--elevation-200)' }}>
         <div data-theme={inverseTheme} className="bg-surface-raised text-foreground">
           <Notice variant={variant} iconClassName={variant === 'success' ? 'text-success' : undefined}
             endContent={actionButton} onDismiss={dismiss} {...rest} />
@@ -69,7 +139,7 @@ function ToastInner({
   const theme = variant === 'warning' ? 'light' : 'dark'
 
   return (
-    <div role={liveRole} aria-live={liveLevel} className="rounded-lg overflow-hidden" style={{ boxShadow: 'var(--elevation-200)' }}>
+    <div {...visualA11yProps} className="rounded-lg overflow-hidden" style={{ boxShadow: 'var(--elevation-200)' }}>
       <div className={bg}>
         <div data-theme={theme} className="text-foreground">
           <Notice variant={variant} endContent={actionButton} onDismiss={dismiss} {...rest} />
@@ -80,26 +150,33 @@ function ToastInner({
 }
 
 export function toast(options: ToastOptions) {
-  const { duration = 4000, ...rest } = options
-  return sonnerToast.custom((id) => <ToastInner id={id} {...rest} />, { duration })
+  // 2026-07-05 D4:sonner 計時器不因鍵盤 Tab 焦點暫停(僅 hover / pointer 按住 / ⌥T hotkey)——
+  // 含 action(復原/重試)預設 10s,給鍵盤使用者足夠時間 Tab 到 action(user 拍板;對齊 Polaris toast with action ≥10s)
+  const { duration = options.action ? 10000 : 4000, ...rest } = options
+  const id = sonnerToast.custom((toastId) => <ToastInner id={toastId} {...rest} />, { duration })
+  publishToastAnnouncement(options)
+  return id
 }
 
 export interface ToasterProps {
   position?: 'top-left' | 'top-right' | 'top-center' | 'bottom-left' | 'bottom-right' | 'bottom-center'
 }
 
-// shadcn canonical:forwardRef + displayName 統一。Sonner Toaster portal-renders
-// 到 document body,ref 對 Toaster 本身無實際 DOM 節點可接(portal 逃逸),
-// 但保留 forwardRef 簽名以符合 DS 統一 API(consumer 可 typecheck 傳 ref,
-// 與其他 DS 元件一致)。
+// shadcn canonical:forwardRef + displayName 統一。SonnerToaster 不轉發 ref,
+// 故 ref 無實際 DOM 節點可接;viewport 為就地渲染的 <section>,以 CSS position:fixed
+// 覆蓋 viewport(非 portal — sonner 全庫 0 createPortal,2026-07-04 grep 驗證)。
+// 保留 forwardRef 簽名以符合 DS 統一 API(consumer 可 typecheck 傳 ref)。
 const Toaster = React.forwardRef<HTMLDivElement, ToasterProps>(
   ({ position = 'bottom-right', ...props }, _ref) => {
     return (
-      <SonnerToaster
-        position={position}
-        toastOptions={{ unstyled: true, className: 'w-[360px]' }}
-        {...props}
-      />
+      <>
+        <SonnerToaster
+          position={position}
+          toastOptions={{ unstyled: true, className: 'w-[360px]' }}
+          {...props}
+        />
+        <ToastLiveRegions />
+      </>
     )
   },
 )
@@ -109,7 +186,7 @@ Toaster.displayName = 'Toaster'
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const toastMeta = {
   component: 'Toast',
-  family: null, // non-family composite / overlay / layout
+  family: 2, // Family 2(List item layout)— 透過 Notice 繼承,對齊 toast.spec.md frontmatter L3 + L39
   variants: {
     neutral: { when: '非狀態通知;一般 announcement / tip' },
     info: { when: '資訊性提示(新版本 / 同步完成)' },
@@ -118,7 +195,8 @@ export const toastMeta = {
     error: { when: '錯誤(匯入失敗 / 權限不足);action prop 可加重試' },
   },
   sizes: {},
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 2026-07-04 audit 對齊:Toast 無 disabled state(spec 邊界案例明文;對齊 noticeMeta ['default'] 已修 pattern)
+  states: ['default'],
   tokens: {
     bg: ['bg-error', 'bg-info', 'bg-surface-raised', 'bg-warning'],
     fg: ['text-foreground'],

package/src/components/Tooltip/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 './tooltip'