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

package/src/components/AgentPanel/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 './agent-panel'

package/src/components/Alert/alert.anatomy.stories.tsx

@@ -0,0 +1,241 @@
+// @anatomy-exempt: anatomy specs / token 對照表格用 raw <table>,非業務資料表。業務資料表才用 <DataTable>。
+// @anatomy-rationale:
+//   SizeMatrix N/A — Alert 固定 md tier(由消費的 Notice primitive 決定),
+//     不隨 density 縮放(僅 placement="fixed" 的水平 px 走 --layout-space-loose,density-aware)。Placement(inline / fixed)取代 size 作為佈局決策,
+//     已由 PlacementMatrix 涵蓋。
+import type { Meta, StoryObj } from '@storybook/react'
+import { Alert, type AlertProps } from './alert'
+import { H3, Desc, Td, Th } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
+
+const meta: Meta = {
+  title: 'Design System/Components/Alert/設計規格',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+type InspectorStory = StoryObj<AlertProps>
+
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>Anatomy</H3>
+        <Desc>Alert 跟 Toast 共用同一套排版、圖示與主題策略。結構:圖示 + 標題 + 說明文字 + 右側操作區(endContent)+ 右上角關閉鈕(需傳 onDismiss 才渲染)。</Desc>
+        <Alert
+          variant="warning"
+          title="方案即將到期"
+          description="您的 Pro 方案將在 3 天後到期,請及時續訂以維持服務"
+          onDismiss={() => {}} // anatomy 展示含 dismiss X slot(2026-07-05 D4:X 僅在傳 onDismiss 時渲染)
+        />
+      </div>
+
+      <div>
+        <H3>Props 速查</H3>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Prop</Th><Th>Type</Th><Th>Default</Th><Th>說明</Th></tr></thead>
+            <tbody>
+              {[
+                ['variant', "'neutral' | 'info' | 'success' | 'warning' | 'error'", "'neutral'", '語意類型(決定 icon + 色彩)'],
+                ['appearance', "'subtle' | 'solid'", "'subtle'", '視覺重量(淺底邊框 vs 飽和底色)'],
+                ['placement', "'inline' | 'fixed'", "'inline'", 'inline 嵌內容 vs fixed 頂部全域警告'],
+                ['title', 'ReactNode', '必填', '主要訊息'],
+                ['description', 'ReactNode', '—', '補充說明'],
+                ['endContent', 'ReactNode', '—', '右側操作區（CTA 按鈕等）'],
+                ['dismissible', 'boolean', 'true', '搭配 onDismiss 顯示右上角關閉按鈕(兩者同時成立才渲染 X)'],
+                ['onDismiss', '() => void', '—', '按下關閉按鈕時觸發;未傳則不渲染 X(2026-07-05 D4)'],
+              ].map(([p, t, d, desc]) => (
+                <tr key={p}><Td mono>{p}</Td><Td mono>{t}</Td><Td mono>{d}</Td><Td>{desc}</Td></tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const Inspector: InspectorStory = {
+  name: '元件檢閱器',
+  parameters: {
+    docs: {
+      description: {
+        story: '在右側 Controls 面板切換 variant / appearance / placement / dismissible,即時查看 render 結果。世界級 DS 的 Inspector = Figma inspect 替代,讓 designer 直接在 Storybook 試出各種組合。',
+      },
+    },
+  },
+  args: {
+    variant: 'warning',
+    appearance: 'subtle',
+    placement: 'inline',
+    title: '方案即將到期',
+    description: '您的 Pro 方案將在 3 天後到期,請及時續訂以維持服務',
+    dismissible: true,
+    onDismiss: () => {}, // 2026-07-05 D4:X 僅在傳 onDismiss 時渲染,Inspector 切 dismissible 才看得到 X
+  },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['neutral', 'info', 'success', 'warning', 'error'],
+      description: '語意類型(決定 icon + 色彩)',
+    },
+    appearance: {
+      control: 'radio',
+      options: ['subtle', 'solid'],
+      description: '視覺重量:subtle(淺底邊框,預設)/ solid(飽和底色,全站警告)',
+    },
+    placement: {
+      control: 'radio',
+      options: ['inline', 'fixed'],
+      description: 'inline(預設,圓角嵌入)/ fixed(頂部全域,無圓角無邊框)',
+    },
+    title: { control: 'text', description: '主要訊息' },
+    description: { control: 'text', description: '補充說明' },
+    dismissible: { control: 'boolean', description: '是否顯示關閉按鈕(需同時傳 onDismiss 才渲染 X)' },
+  },
+  render: (args) => <Alert {...args} />,
+}
+
+export const ColorMatrix: Story = {
+  name: '色彩對照表',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>Subtle(淺底 + 邊框,預設)</H3>
+        <Desc>視覺重量適中,99% 的 Alert 用 subtle。不搶頁面焦點,使用者注意但可繼續主要任務。</Desc>
+        <div className="flex flex-col gap-3 max-w-xl">
+          <Alert variant="neutral" title="新功能上線" description="我們推出了 Dark Mode,請前往設定啟用" />
+          <Alert variant="info" title="系統維護中" description="部分功能暫停服務,預計 30 分鐘內恢復" />
+          <Alert variant="success" title="驗證通過" description="您的電子郵件已成功驗證" />
+          <Alert variant="warning" title="額度即將用完" description="您本月 API 額度已使用 90%" />
+          <Alert variant="error" title="付款失敗" description="您上次的訂閱付款失敗,請更新付款方式" />
+        </div>
+      </div>
+
+      <div>
+        <H3>Solid(飽和底色)</H3>
+        <Desc>視覺重量高,用於真的很重要的全站警告。一個頁面最多一個 solid Alert。</Desc>
+        <div className="flex flex-col gap-3 max-w-xl">
+          <Alert variant="info" appearance="solid" title="系統升級" description="本站將於 02:00 進行升級" />
+          <Alert variant="warning" appearance="solid" title="配額用盡" description="請立即升級方案以繼續使用" />
+          <Alert variant="error" appearance="solid" title="服務中斷" description="API 服務暫時不可用,工程團隊正在修復" />
+        </div>
+      </div>
+
+      <div>
+        <H3>Variant × Theme 策略</H3>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Variant</Th><Th>Subtle</Th><Th>Solid</Th></tr></thead>
+            <tbody>
+              <tr><Td mono>neutral</Td><Td mono>bg-muted + border-border;無 status icon(VARIANT_ICON.neutral = null)</Td><Td>bg-surface-raised + data-theme inverse(跟頁面反)</Td></tr>
+              <tr><Td mono>info</Td><Td mono>bg-info-subtle + border-[var(--info-text)] + text-info-text</Td><Td mono>bg-info + data-theme="dark"(藍底白字)</Td></tr>
+              <tr><Td mono>success</Td><Td mono>bg-success-subtle + border-[var(--success-text)] + text-success-text</Td><Td mono>bg-success + data-theme="dark"(綠底白字)</Td></tr>
+              <tr><Td mono>warning</Td><Td mono>bg-warning-subtle + border-[var(--warning-text)] + text-warning-text</Td><Td mono>bg-warning + data-theme="light"(黃底深字)</Td></tr>
+              <tr><Td mono>error</Td><Td mono>bg-error-subtle + border-[var(--error-text)] + text-error-text</Td><Td mono>bg-error + data-theme="dark"(橘底白字)</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const PlacementMatrix: Story = {
+  name: '出現位置（內嵌 vs 固定）',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>Inline(預設) — 嵌入頁面內容</H3>
+        <Desc>`rounded-md`(4px)圓角 + 邊框,像一張 card 嵌在內容區塊裡。Settings 頁的方案提示、表單內的注意事項。</Desc>
+        <Alert
+          variant="warning"
+          title="即將到期"
+          description="您的方案將在 3 天後到期"
+        />
+      </div>
+
+      <div>
+        <H3>Fixed — 頂部全域警告</H3>
+        <Desc>無圓角無邊框,頁面寬度橫條。系統維護、服務降級、全站重要公告。</Desc>
+        <Alert
+          variant="info"
+          placement="fixed"
+          title="系統維護中"
+          description="2026-04-20 02:00-04:00 進行系統升級,部分功能暫停"
+        />
+      </div>
+
+      <div>
+        <H3>Placement 對照</H3>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Placement</Th><Th>圓角</Th><Th>Border</Th><Th>用途</Th></tr></thead>
+            <tbody>
+              <tr><Td mono>inline ★default</Td><Td mono>rounded-md(4px)</Td><Td>有</Td><Td>頁面內嵌</Td></tr>
+              <tr><Td mono>fixed</Td><Td>無(rounded-none)</Td><Td>無</Td><Td>header 底下全域警告</Td></tr>
+            </tbody>
+          </table>
+        </div>
+        <p className="text-footnote text-fg-muted mt-3">Alert 是 inline 容器(不是浮層),用 `rounded-md`(4px)。Toast 是浮層用 `rounded-lg`(8px)。</p>
+      </div>
+    </div>
+  ),
+}
+
+export const StateBehavior: Story = {
+  name: '狀態行為',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>Dismissible(右側 close icon)</H3>
+        <Desc>
+          Alert 預設 `dismissible=true`,傳入 `onDismiss` 時右上角顯示 close button(未傳 handler 不渲染 X——controlled-only,無 handler 的 X 是死按鈕;2026-07-05 D4)。按 close 觸發 `onDismiss` 由 consumer 控制移除(Alert 本身不 own unmount 狀態——inline 通知通常需要 consumer 記住「使用者已關閉」狀態)。
+        </Desc>
+        <div className="flex flex-col gap-3 max-w-xl">
+          <Alert variant="info" title="可關閉" description="右上角有 close icon,按下觸發 onDismiss" onDismiss={() => {}} />
+          <Alert variant="warning" title="不可關閉" description="永久性警告,設 dismissible={false} 隱藏 close icon" dismissible={false} />
+          <Alert variant="neutral" title="靜態通知" description="沒傳 onDismiss 時同樣不渲染 close icon(避免按了沒反應的假 affordance)" />
+        </div>
+      </div>
+
+      <div>
+        <H3>Close button 互動狀態</H3>
+        <Desc>
+          Chrome corner close 用 Button iconOnly `dismiss` size="xs"(notification banner family 設計準則,見 `overlay-surface.spec.md`「Chrome dismiss size canonical」)。現行 canonical 為兩分:notification banner family(Notice / Alert / Toast,px-4 py-3 固定)dismiss 用 `xs`;overlay surface(Dialog / Sheet / Popover)另走 `sm` + unbounded 負 margin trick。corner 屬 action group region,實務上可與 refresh / share 等 Button 並排(用 ButtonDivider 分群),必須統一 Button primitive + 同 family 全 xs。`dismiss` prop 自動套 `variant="text"` + icon `fg-muted` 弱化,hover 時恢復 foreground。
+        </Desc>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>State</Th><Th>視覺</Th><Th>Token</Th></tr></thead>
+            <tbody>
+              <tr><Td>default</Td><Td>Button xs iconOnly(24×24),X icon 16,fg-muted</Td><Td mono>text-fg-muted(`dismiss` override)</Td></tr>
+              <tr><Td>hover</Td><Td>Button bg 套 neutral-hover,icon 升 foreground</Td><Td mono>bg-neutral-hover / text-foreground</Td></tr>
+              <tr><Td>focus</Td><Td>2px ring(鍵盤導航)</Td><Td mono>ring-ring ring-offset-1</Td></tr>
+              <tr><Td>solid appearance</Td><Td>icon 隨 variant 的 data-theme:info / success / error(dark theme)白字,warning(light theme)深字</Td><Td mono>text-fg-muted → hover text-foreground(隨 data-theme 翻轉)</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <div>
+        <H3>非互動 Alert(無內建 open/close state)</H3>
+        <Desc>
+          Alert 本身無 open/closed state——它是 inline 容器,「顯示」= consumer 把 Alert render 進 tree,「關閉」= consumer 從 tree 移除。與 Toast(有 open 動畫 + auto-dismiss timer)語意不同。
+        </Desc>
+      </div>
+    </div>
+  ),
+}
+
+// ── Accessibility ─────────────────────────────────────────────────────────
+// 2026-05-17 ship per audit Dim 13(story-rules.md 6-canonical 含 Accessibility)
+export const Accessibility = {
+  name: '無障礙與鍵盤',
+  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">{"無障礙朗讀行為依 variant 自動切換：\n\n-   一般提示（neutral / info / success）  ： role=\"status\"  +  aria-live=\"polite\" ——螢幕報讀器在使用者空閒時才讀出內容，不打斷目前動作\n-   緊急提示（warning / error）  ： role=\"alert\"  +  aria-live=\"assertive\" ——立即中斷目前朗讀讀出內容，因為使用者必須馬上知道\n-   關閉按鈕  ：必須有  aria-label （如「關閉通知」）\n-   行動按鈕  ：放在 Alert 內的操作按鈕用最小尺寸、低調樣式，文字直接描述動作（「前往設定」「立即更新」）"}</p>
+    </div>
+  ),
+}

package/src/components/Alert/alert.principles.stories.tsx

@@ -0,0 +1,214 @@
+// @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 { Alert } from './alert'
+
+const meta: Meta = {
+  title: 'Design System/Components/Alert/設計原則',
+  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-xl">{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 — 何時使用 Alert ──────────────────────
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / VsToastVsDialogRule(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>適合 Alert 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          <LinkTo kind="Design System/Components/Alert/展示" name="單行（低調 vs 實心對照）"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">單行(低調 vs 實心對照)</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Alert/展示" name="含說明文字（低調 vs 實心對照）"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">含說明文字(低調 vs 實心對照)</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Alert/展示" 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「何時用 / 何時不用」段;若仍不符,改用近親元件(見本頁下方「vs 近親」段)。</p>
+    </div>
+
+      {/* vs 近親 — VsToastVsDialogRule — 原 VsToastVsDialogRule */}
+      <div>
+      <Rule
+        title="Alert — 持久性通知、嵌入頁面、不阻斷"
+        note="使用者主動 dismiss 或處理才消失。適合:方案即將到期、帳號未驗證、系統維護、複雜動作的前置警告"
+      >
+        <Alert
+          variant="warning"
+          title="方案即將到期"
+          description="您的 Pro 方案將在 3 天後到期，請及時續訂以維持服務"
+        />
+        <Label>↑ 持久性:進頁面就看到,直到使用者處理(續訂 / dismiss)</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 操作結果短暫回饋：用 Toast"
+        note="「儲存成功」「已複製」這類一閃即可的訊息不該嵌入頁面 persistent 存在。Toast 自動消失,非阻斷"
+      >
+        <Alert
+          variant="success"
+          title="儲存成功"
+          description="您的變更已儲存"
+        />
+        <Label warn>↑ 儲存成功放 Alert → 頁面永遠留這條「儲存成功」,使用者看下一次儲存時還在,困惑。用 Toast 閃一下即可</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 需要阻斷確認的流程：用 Dialog"
+        note="「確定要刪除嗎」這類需要使用者明確確認才能繼續的動作必須 modal。Alert 非阻斷,使用者可以忽略繼續操作——危險"
+      >
+        <Alert
+          variant="error"
+          title="確定要刪除此專案？"
+          description="此動作無法復原"
+        />
+        <Label warn>↑ 刪除確認用 Alert → 使用者按了按鈕後彈 Alert,但仍能操作其他元素,錯亂。用 Dialog 強制聚焦</Label>
+      </Rule>
+
+      <Rule
+        title="判斷法：「訊息的生命週期」"
+        note="瞬時閃現 → Toast / 持續到處理 → Alert / 必須確認才能繼續 → Dialog"
+      >
+        <Label>三種訊號各司其職——別混用</Label>
+      </Rule>
+    </div>
+    </div>
+  ),
+}
+
+export const VariantRule: Story = {
+  name: '變體 選擇',
+  render: () => (
+    <div>
+      <Rule
+        title="info / success / warning / error — 語意與色彩對應"
+        note="跟 Toast 共用同一套 variant × theme 策略。語意由 variant 承載(不靠 consumer 用顏色暗示),icon 跟色彩自動配合"
+      >
+        <Alert variant="info" title="系統維護中" description="部分功能暫停服務,預計 30 分鐘內恢復" />
+        <Alert variant="success" title="驗證通過" description="您的電子郵件已成功驗證" />
+        <Alert variant="warning" title="額度即將用完" description="您本月 API 額度已使用 90%" />
+        <Alert variant="error" title="付款失敗" description="您上次的訂閱付款失敗,請更新付款方式" />
+      </Rule>
+
+      <Rule
+        title="neutral — 一般資訊（無特定語意）"
+        note="沒有明確 info / success / warning / error 定位時用 neutral。例:公告、提示、說明"
+      >
+        <Alert variant="neutral" title="新功能上線" description="我們推出了 Dark Mode,請前往設定啟用" />
+      </Rule>
+
+      <Rule
+        title="❌ 用 variant 傳達「強度」而非「語意」"
+        note="用 error 讓「重要公告」看起來更緊急 → 使用者以為真的出錯了。Variant 語意綁定具體事件類型,不是強度 knob"
+      >
+        <Alert variant="error" title="新功能上線" description="我們推出了 Dark Mode" />
+        <Label warn>↑ 「新功能」用 error 紅色 → 使用者以為是錯誤警告,誤導注意力</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const PlacementRule: Story = {
+  name: '行內 vs 固定放置',
+  render: () => (
+    <div>
+      <Rule
+        title="Inline（預設）— 嵌在 page 內容中"
+        note="有圓角 + 邊框,像一張 card 嵌在內容區塊裡。Settings 頁的方案提示、表單內的注意事項"
+      >
+        <Alert
+          variant="warning"
+          title="即將到期"
+          description="您的方案將在 3 天後到期"
+        />
+        <Label>↑ inline 模式 — 有圓角邊框,嵌入內容</Label>
+      </Rule>
+
+      <Rule
+        title="Fixed — 頂部全域警告（頁面寬度,無邊框圓角）"
+        note="系統維護、服務降級、全站重要公告。Fixed 讓使用者無論在哪頁都看到同一條訊息"
+      >
+        <Alert
+          variant="info"
+          placement="fixed"
+          title="系統維護中"
+          description="2026-04-20 02:00-04:00 進行系統升級,部分功能暫停"
+        />
+        <Label>↑ fixed 模式 — 無圓角邊框,頂部 full-width</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 混用：頁面中間放 fixed placement"
+        note="Fixed 是頂部全域警告的視覺語言。放在頁面中間會破壞「這是全域訊息」的預期"
+      >
+        <Label warn>Fixed 永遠在最頂部,不在內容區塊中間</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const AppearanceRule: Story = {
+  name: '低調 vs 實心 選擇',
+  render: () => (
+    <div>
+      <Rule
+        title="Subtle（預設）— 淺底 + 邊框，視覺重量適中"
+        note="99% 的 Alert 用 subtle。使用者注意到訊息但不被嚇到,可以繼續主要任務"
+      >
+        <Alert
+          variant="warning"
+          title="即將到期"
+          description="您的方案將在 3 天後到期"
+        />
+      </Rule>
+
+      <Rule
+        title="Solid — 飽和底色，視覺重量高"
+        note="用於真的很重要的全站警告(服務中斷、付款失敗必須立即處理)。一個頁面最多一個 solid Alert"
+      >
+        <Alert
+          variant="error"
+          appearance="solid"
+          title="付款失敗"
+          description="您上次的訂閱付款失敗,請立即更新付款方式以免服務中斷"
+        />
+      </Rule>
+
+      <Rule
+        title="❌ 所有 Alert 都用 solid"
+        note="視覺重量過高,使用者無法分辨哪個真重要。Solid 保留給最緊急的訊息"
+      >
+        <Alert variant="success" appearance="solid" title="已儲存" />
+        <Alert variant="info" appearance="solid" title="提示" />
+        <Alert variant="warning" appearance="solid" title="注意" />
+        <Label warn>↑ 全 solid → 訊號稀釋,使用者麻木</Label>
+      </Rule>
+    </div>
+  ),
+}

package/src/components/Alert/alert.spec.md

@@ -28,7 +28,6 @@ benchmark:
   - Polaris Banner: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Banner
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
 
 # Alert 設計原則
 
@@ -38,7 +37,7 @@ Alert 是**持久性通知**，嵌入在頁面中。用於系統狀態提示、
 
 **實作基礎**：消費 Notice primitive（共享 Toast 的 layout + icon + theme 策略）。
 
-**Layout Family**：CLAUDE.md 4-Family Model **Family 2（List item layout）** 消費者。結構繼承 `patterns/element-anatomy/item-anatomy.spec.md`「List item layout」章節的 reading-mode 規格。Alert 透過 Notice 繼承 Family 2 結構。
+**Layout Family**：本元件透過 Notice 間接繼承 `patterns/element-anatomy/item-anatomy.spec.md` 所擁有的 **Family 2（List item layout）** reading-mode 規格,不直接消費 item-anatomy。
 
 ---
 
@@ -73,6 +72,8 @@ Alert 是**持久性通知**，嵌入在頁面中。用於系統狀態提示、
 - 是（方案到期、帳戶未驗證、系統維護中、錯誤需要處理）→ **Alert**
 - 否（儲存成功、已複製、上傳完成）→ **Toast**
 
+頂部全域警告同理走 Alert（`placement="fixed"`）：fixed 是**頁面流內**的持久 bar（非 position fixed 浮層），與 Toast 浮層分屬不同層，不互相取代、不衝突。
+
 ---
 
 ## 禁止事項
@@ -81,26 +82,25 @@ Alert 是**持久性通知**，嵌入在頁面中。用於系統狀態提示、
 - ❌ **不把 error form validation 做成 Alert**：欄位級錯誤必須貼近發生位置（FieldError）,使用者才能快速定位；頁面級 Alert 只放非欄位的整體錯誤（如提交失敗、權限不足）
 - ❌ **Alert 不疊 Alert**：同區出現多個 Alert 視覺雜訊重,整理成一組 messages 或合併為單一 Alert with list
 - ❌ **destructive 操作確認不用 Alert**：刪除 / 離開等需要明確確認的動作用 Dialog,Alert 無法承載 confirm / cancel 雙按鈕的阻斷流程
-- ❌ **body action row 不得混入 close X**:close X 必在 chrome corner action group,不可跟 CTA 擺在同一 row(違反 same-row consistency — CTA 是 labeled Button sm tertiary,close X 是 Button iconOnly sm dismiss,box size 與視覺分量不同,同 row 會造成 gap / 對齊錯亂)。完整規則見 `patterns/element-anatomy/inline-action.spec.md`「Same-row consistency rule(防混用)」節
-- ❌ **close X 不用 Inline Action 或自刻 `<button><X /></button>`**:corner 屬 action group region,必用 `<Button iconOnly dismiss size="sm" />`(見上方 Chrome corner close X canonical)
+- ❌ **右側操作區(endContent + close X)內不混不同分量的 action**:endContent(CTA / refresh 等)與 close X 同渲染進單一右上 suffix(對齊第一行、靠右);close X 必用 `<Button iconOnly dismiss size="xs" />`(不是 Inline Action、不是自刻 `<button><X /></button>`,見下方 Chrome corner close X canonical);同一 suffix 內所有 action 必同分量(統一 Button iconOnly xs),不可混 Inline Action + Button iconOnly,否則違反 same-row consistency(box size 與視覺分量不同,造成 gap / 對齊錯亂),完整規則見 `patterns/element-anatomy/inline-action.spec.md`「Same-row consistency rule(防混用)」節
 
 ---
 
 ## A11y 預設
 
-- **預設**：`role="alert"` + `aria-live="polite"`——screen reader 在空閒時讀出 Alert 內容，不中斷使用者目前動作
-- **error variant 可升級**：`aria-live="assertive"` 中斷 screen reader 目前朗讀，立即讀出 Alert（僅用於真正 critical 的錯誤，避免濫用干擾）
+- **一般提示（neutral / info / success）**：`role="status"` + `aria-live="polite"`——screen reader 在空閒時讀出 Alert 內容，不中斷使用者目前動作
+- **緊急提示（warning / error）**：`role="alert"` + `aria-live="assertive"`——立即中斷 screen reader 目前朗讀讀出內容。「緊急與否」的界線即 variant 選擇本身：選 warning / error 即 assertive,依 variant 自動套用，無 per-instance 切換 API
 - **Close X 按鈕**：必須有 `aria-label`(如「關閉通知」),實作見下方「Chrome corner close X canonical」
-- **CTA 按鈕**：放在 Alert body action row 時 size 固定為 `xs` tertiary,文字描述動作(「前往設定」「立即更新」)
+- **CTA 按鈕**：透過 `endContent` 放進右側操作區(與 close X 同列,靠右上)size 固定為 `xs` tertiary,文字描述動作(「前往設定」「立即更新」)
 
 ---
 
 ## Chrome corner close X canonical
 
-Alert 右上角的 close X **必須用 `<Button iconOnly dismiss size="sm" />`**,不是 Inline Action、不是自刻 button。
+Alert 右上角的 close X **必須用 `<Button iconOnly dismiss size="xs" />`**,不是 Inline Action、不是自刻 button。
 
 **為什麼是 Button(Cat 3 Action group region)而非 Inline Action**:
-- Alert 的 chrome corner 屬 **action group region**(toolbar / chrome corner / standalone 類),實務上 close 左側可並排 refresh / share / minimize 等額外 action + `<Separator orientation="vertical" />`——一旦成為 action group,所有成員必同類(same-row consistency),統一 Button iconOnly
+- Alert 的 chrome corner 屬 **action group region**(toolbar / chrome corner / standalone 類),實務上 close 左側可並排 refresh / share / minimize 等額外 action + `<ButtonDivider />`——一旦成為 action group,所有成員必同類(same-row consistency),統一 Button iconOnly
 - Inline Action 是「embedded 在 host 內部的 tap target」(Cat 1,如 Input clear X / Tag dismiss X),不參與 action group 規則,兩者不可混用
 - `dismiss` prop 自動套 `variant="text"` + `fg-muted → hover foreground` 弱化,視覺輕量不壓過內容
 
@@ -110,30 +110,29 @@ SSOT 詳見 `patterns/element-anatomy/inline-action.spec.md`「Predicate:Inline
 
 ### Corner action group 佈局 canonical
 
-Alert chrome corner 可承載多個 action(close 左側並排):
+Alert 右側操作區(單一 suffix,對齊第一行靠右)可承載多個 action —— endContent 內容 + close X 並排:
 
 ```
-┌─ Alert ────────────────── [⟲] │ [X] ┐   ← chrome corner action group(Button sm)
-│ [icon] Title                         │     refresh / share / minimize 等 + Separator + close X
+┌─ Alert ────────────────── [⟲] │ [X] ┐   ← 右側操作區 action group(endContent + close X,Button xs)
+│ [icon] Title                         │     endContent(CTA / refresh / share 等)+ ButtonDivider + close X
 │ Description                          │
-│                      [CTA1] [CTA2]   │   ← body action row(Button sm tertiary)
 └──────────────────────────────────────┘
 ```
 
 **規則**:
-- 同一 action group 所有 Button 同 `size="sm"`(跟 close X 對齊)
-- 多 action 之間用 `<Separator orientation="vertical" />` 分群(`refresh / share` 一群,`close` 一群)
-- 若只有 close X 則不需要 Separator(單一 action 即 group)
+- 同一 action group 所有 Button 同 `size="xs"`(跟 close X 對齊)
+- **分隔線由 DS 自動放,consumer 零自刻**(2026-08-06):Notice 基座在 `endContent` 與 close X 之間自動渲染 `<ButtonDivider />`(`notice.tsx`),Alert 與 Toast 共用此基座因此行為一致。Consumer 只需傳 `endContent`
+- 加不加的**語意 SSOT 在 `patterns/action-bar/action-bar.spec.md` 第五節**(理由 3 誤觸保護):關閉鈕左邊緊鄰其他操作按鈕才加;只有 close X 時不加(沒有東西需要被隔開)。本檔不重複定義
 
 **世界級對照**:
 - **Material Banner**(`<Banner actions={[...]}/>` 右上 close + 可加 refresh)
 - **Polaris Banner**(`onDismiss` 走 IconButton,右上 action group)
 - **VS Code editor tab** window corner(close + pin + split,全部同 size IconButton)
-- **Figma panel corner**(close + collapse 同 group,Separator 分隔)
+- **Figma panel corner**(close + collapse 同 group,divider 分隔)
 
 ### Multi corner action 場景
 
-目前 Alert API 只透過 `dismissible` 渲染單一 close X。多 corner action 場景目前不支援;若未來 consumer 有需求,走 Checkpoint 3 決策(M8 benchmark + consumer survey),不預先投機擴 API。
+目前 Alert API 只透過 `dismissible` + `onDismiss` 渲染單一 close X(X 僅在傳 `onDismiss` 時渲染——controlled-only,無 handler 的 X 是死按鈕;對齊 Polaris Banner `onDismiss`-driven,2026-07-05 D4,詳 `../Notice/notice.spec.md`「邊界案例」)。多 corner action 場景目前不支援;若未來 consumer 有需求,走 Checkpoint 3 決策(M8 benchmark + consumer survey),不預先投機擴 API。
 
 ---
 
@@ -141,7 +140,7 @@ Alert chrome corner 可承載多個 action(close 左側並排):
 
 ### Subtle(預設)
 
-淺底色 + 四邊 1px border(邊框採語意色的 hover tint)。99% 場景用 subtle——視覺重量適中,使用者注意但可繼續主要任務。不設 `data-theme`,元素跟隨頁面 theme。
+淺底色 + 四邊 1px border(邊框採 `--{hue}-text` = icon 同色,2026-06-15 user 拍板;原借 `-hover` 狀態 token 是語意 smell 已改)。99% 場景用 subtle——視覺重量適中,使用者注意但可繼續主要任務。不設 `data-theme`,元素跟隨頁面 theme。
 
 ### Solid
 
@@ -154,16 +153,15 @@ Subtle vs Solid 的完整 variant × theme class 對照見 anatomy `ColorMatrix`
 - **`inline`(預設)**:頁面內嵌,圓角 + 邊框,像一張 card 嵌在內容區塊裡
 - **`fixed`**:頂部全域警告,無圓角無邊框,橫跨頁面寬度
 
-**為什麼兩種 placement 的圓角不同**:inline 是 content-level card(rounded-md = 4px,對齊 Alert 的 inline 容器身份,與 Dialog / Card 一致);fixed 是 page-level bar(無 radius,橫跨畫面形成整條)。Toast 是浮層用 `rounded-lg`(8px,浮層慣例),跟 Alert 區分。
+**為什麼兩種 placement 的圓角不同**:inline 是 content-level card(rounded-md = 4px,對齊 Alert 的 inline 容器身份,與 Card 同 tier — 見 `tokens/radius/radius.spec.md`「一般元件」;Dialog 屬浮層走 rounded-lg);fixed 是 page-level bar(無 radius,橫跨畫面形成整條)。Toast 是浮層用 `rounded-lg`(8px,浮層慣例),跟 Alert 區分。
 
 完整 placement 對照見 anatomy `PlacementMatrix` story。
 
-## 為何無 Inspector / SizeMatrix
+## 為何無 SizeMatrix
 
-- **無 Inspector**:Alert 的關鍵決策維度是 `variant`(5 色)× `appearance`(subtle / solid)× `placement`(inline / fixed),已在 `ColorMatrix` 完整呈現 variant × appearance 矩陣,再加 `PlacementMatrix` 呈現 placement——互動切換式 Inspector 不會比這兩張矩陣更能傳達 Alert 的設計規格。
-- **無 SizeMatrix**:Alert 無 `size` prop,其視覺尺寸繼承自 Notice primitive(14px body / 16px icon / fixed padding),不隨 density 變動。尺寸規格由 `Notice` spec own。改 Notice 時 Alert 自動跟進,不需要 Alert 有獨立 SizeMatrix。
+- **無 SizeMatrix**:Alert 無 `size` prop,其視覺尺寸繼承自 Notice primitive(14px body / 16px icon / 固定 py),字級與垂直 padding 不隨 density 變動;僅 `placement="fixed"` 的水平 px 走 `--layout-space-loose`(density-aware,跟周圍 loose-padding 佈局對齊,見 alert.tsx)。尺寸規格由 `Notice` spec own。改 Notice 時 Alert 自動跟進,不需要 Alert 有獨立 SizeMatrix。
 
-對應 anatomy story:保留 `Overview` + `ColorMatrix` + `StateBehavior` + 元件特有 `PlacementMatrix`。
+對應 anatomy story:`Overview` + `Inspector` + `ColorMatrix` + `PlacementMatrix` + `StateBehavior` + `Accessibility`(6-canonical;Alert 的 `Inspector` 互動切換 variant × appearance × placement × dismissible,SizeMatrix N/A 見上)。
 
 ---
 
@@ -179,9 +177,10 @@ Subtle vs Solid 的完整 variant × theme class 對照見 anatomy `ColorMatrix`
 
 ## 邊界案例
 
-- **Disabled(dismiss button)**:Alert 本身無 `disabled` prop(持久通知不該被禁用),但 dismiss close X 為 `<Button iconOnly dismiss size="sm" />`,自動繼承 Button disabled 視覺(`text-fg-disabled` + `cursor-not-allowed` + 無 hover bg);實務場景:後台正在執行 close action(API in-flight)時 consumer 可 disable button 防 double-click,fg token 走 Button SSOT 不在 Alert 加層。
-- **Loading**:Alert 本身不需 loading state(非 async surface);若 Alert body action row 內 CTA 在 async 動作中,該 Button 自己處理 `loading` prop。
+- **Disabled(dismiss button)**:Alert **不提供 dismiss 停用 API**——banner dismiss 恆可用(對齊 Polaris / Material Banner:通知關閉鈕應永遠可按)。「恆可用」指**已渲染的 X 永遠可按**;X 本身僅在傳 `onDismiss` 時渲染(否則是死按鈕假 affordance,2026-07-05 D4,見「Multi corner action 場景」段 + `../Notice/notice.spec.md`「邊界案例」)。Alert 本身亦無 `disabled` prop(持久通知不該被禁用)。若需防止 close action(API in-flight)被雙擊,consumer 在 `onDismiss` 內自行 debounce / 加上層鎖,不在 UI 層加 disable(Alert 不提供 dismiss 停用 API、也不把 disabled 轉傳給內部 dismiss Button;Button primitive 本身支援 disabled,但 Alert 刻意不開洞)。
+- **Loading**:Alert 本身不需 loading state(非 async surface);若 `endContent` 內的 CTA 在 async 動作中,該 Button 自己處理 `loading` prop。
 - **Empty / icon-only**:Alert 必有 `title`(API contract),無 empty 場景;若無 description 則僅顯示 title + icon,layout 自動收斂。
+- **極長字串**:title 單行 truncate、description 自由換行不截斷(皆繼承 ItemContent 預設);description 超過 2–3 行屬誤用,改 Dialog(見禁止事項)。
 
 ## 相關
 
@@ -193,5 +192,8 @@ Subtle vs Solid 的完整 variant × theme class 對照見 anatomy `ColorMatrix`
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `dialog.spec.md`
 - `empty.spec.md`
+- `notice.spec.md`
 - `skeleton.spec.md`
+- `toast.spec.md`