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

package/src/components/Notice/notice.principles.stories.tsx

@@ -0,0 +1,102 @@
+// @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.
+// v3 canonical(2026-05-01):≥ 2 stories(UsageGuidance + CompositionRules)對齊
+// Polaris/Material/Ant 共識,取代原 escape rationale。
+import type { Meta, StoryObj } from '@storybook/react'
+import LinkTo from '@storybook/addon-links/react'
+
+const meta: Meta = {
+  title: 'Design System/Internal/Notice/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <section className="mb-10">
+    <h3 className="text-body-lg font-medium text-foreground mb-2">{title}</h3>
+    <div className="prose prose-sm max-w-prose">{children}</div>
+  </section>
+)
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div>
+      <Section title="何時用">
+        <p>適合 Notice 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+        <ul className="space-y-1">
+          <li>
+            <LinkTo kind="Design System/Internal/Notice/展示" name="部署成功 橫幅"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">CI/CD 部署成功橫幅 — 附「查看部署紀錄」動作</span></LinkTo>
+          </li>
+          <li>
+            <LinkTo kind="Design System/Internal/Notice/展示" name="工作區付款失敗"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">工作區付款失敗 — 附「更新付款方式」補救動作</span></LinkTo>
+          </li>
+          <li>
+            <LinkTo kind="Design System/Internal/Notice/展示" name="行內通知變體對照"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">方案限制 / 空間不足 / 連線失敗等行內提示(五種語意變體)</span></LinkTo>
+          </li>
+          <li>
+            <LinkTo kind="Design System/Internal/Notice/展示" name="Toast 樣式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">「變更已儲存」「已複製連結」Toast 短暫提示</span></LinkTo>
+          </li>
+          <li>
+            <LinkTo kind="Design System/Internal/Notice/展示" 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>
+      </Section>
+
+      <Section title="何時不用 + 替代">
+        <p>Notice 是 internal primitive,自身有 dismiss 按鈕 + <code>onDismiss</code> callback,但不管 dismiss 後的 mount / unmount 生命週期,也無 auto-dismiss 計時——需要這些行為改用以下 consumer:</p>
+        <ul>
+          <li><strong>需要 dismiss 後移除(永久 inline)</strong> → 用 <code>Alert</code>(內部消費 Notice + live region:error/warning role="alert"、其餘 role="status")。Alert 是 controlled-only:提供 <code>onDismiss</code> callback,consumer 在 callback 中更新狀態並自行 unmount,Alert 不會自行移除</li>
+          <li><strong>需要 auto-dismiss(短暫 toast)</strong> → 用 <code>Toast</code></li>
+          <li><strong>表單欄位錯誤訊息</strong> → 用 <code>Field</code> 內建 errorText,不用 Notice</li>
+        </ul>
+      </Section>
+
+      <Section title="vs 近親 — Notice / Alert / Toast">
+        <p>三者關係:Notice 是 primitive,Alert / Toast 是 consumer:</p>
+        <ul>
+          <li><strong>Notice(本元件)</strong> — internal primitive,提供 announcement row 結構 + variant token</li>
+          <li><strong>Alert</strong> — 永久 inline announcement(stays until dismissed)</li>
+          <li><strong>Toast</strong> — 短暫 announcement(auto-dismiss)</li>
+        </ul>
+        <p className="text-fg-muted">建新 announcement 類元件 → 消費 Notice 不要 hand-craft row(對齊 主檔消費準則)。</p>
+      </Section>
+    </div>
+  ),
+}
+
+// ── CompositionRules — Notice 兩個 consumer pattern(對齊 Material Banner/Snackbar / Polaris Banner)──────
+
+export const CompositionRules: Story = {
+  name: '組合規則',
+  render: () => (
+    <div>
+      <Section title="Pattern 1 — Alert(persistent inline announcement)">
+        <div className="prose prose-sm max-w-prose">
+          <p>需要「持續顯示直到 user 主動 dismiss」→ <LinkTo kind="Design System/Components/Alert/展示" name="單行（低調 vs 實心對照）"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Alert 低調單行</span></LinkTo>。Alert 內部消費 Notice + 加上 dismiss button + live region ARIA(error/warning → role="alert" assertive;info/success/neutral → role="status" polite)。</p>
+          <ul>
+            <li>典型場景:付款失敗 banner / workspace 警告 / 重要通知 user 必看</li>
+            <li>對齊世界級:Polaris <code>Banner</code> / Material <code>Banner</code> / Atlassian <code>InlineMessage</code> — 共識用「persistent + dismissible」</li>
+          </ul>
+        </div>
+      </Section>
+
+      <Section title="Pattern 2 — Toast(auto-dismiss floating announcement)">
+        <div className="prose prose-sm max-w-prose">
+          <p>需要「短暫提示,使用者不需 acknowledge」→ <LinkTo kind="Design System/Components/Toast/展示" name="有標題與描述"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">有 Title + Description</span></LinkTo>。Toast 基於 Sonner + 消費 Notice layout,自動 4 秒消失(可調)。</p>
+          <ul>
+            <li>典型場景:儲存成功 / 複製到剪貼簿 / 非關鍵操作回饋</li>
+            <li>對齊世界級:Material <code>Snackbar</code> / Polaris <code>Toast</code> / Sonner — 共識用「auto-dismiss + 浮動 + 不阻塞 task」</li>
+          </ul>
+        </div>
+      </Section>
+
+      <Section title="禁止 — 自刻 announcement row">
+        <div className="prose prose-sm max-w-prose">
+          <p>建新 announcement 類元件(例如 InAppNotification banner)→ 必消費 Notice primitive,不可自刻 <code>&lt;div className="flex p-3 bg-..."&gt;</code>(對齊 M1 主檔消費準則 / 確保 icon 選擇 + variant token 一致)。</p>
+        </div>
+      </Section>
+    </div>
+  ),
+}

package/src/components/Notice/notice.spec.md

@@ -1,7 +1,18 @@
 ---
 component: Notice
 family: 2
-variants: {}
+# variant 語意 = status icon 選擇(見本文「Variant」表);world-class 對照見 frontmatter benchmark 清單
+variants:
+  neutral:
+    when: "一般訊息、系統公告;無情緒色、不掛 status icon"
+  info:
+    when: "資訊提示(版本更新、流程說明);Info icon"
+  success:
+    when: "操作成功確認;CircleCheck icon"
+  warning:
+    when: "可恢復警告(未儲存變更、連線不穩);TriangleAlert icon"
+  error:
+    when: "錯誤(操作失敗、權限不足);XCircle icon"
 sizes: {}
 traits:
   - isInternal
@@ -11,8 +22,6 @@ benchmark:
   - Carbon Notification: github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Notification
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
-
 # Notice 設計原則
 
 **Toast / Alert 共用的視覺佈局層**——跟 MenuItem 為 SelectMenu / DropdownMenu 共用是同一個架構概念。Notice 只負責 layout 和 icon 選擇，色彩由消費者透過 `data-theme` 控制。
@@ -23,28 +32,34 @@ Notice 是純視覺 primitive，不是獨立使用的元件。消費者：
 - **Toast**：浮動 + 自動消失（Sonner）
 - **Alert**：inline / fixed 持久通知
 
-**Layout Family**：CLAUDE.md 4-Family Model **Family 2（List item layout）** 消費者。結構繼承 `patterns/element-anatomy/item-anatomy.spec.md`「List item layout」章節的 reading-mode 規格。Notice 語意為 notification（非 row collection），但視覺排版遵循 Family 2 確保跨元件視覺一致。
+**Layout Family**：本元件是 `patterns/element-anatomy/item-anatomy.spec.md` 所擁有的 **Family 2（List item layout）** 消費者。結構繼承其「List item layout」章節的 reading-mode 規格。Notice 語意為 notification（非 row collection），但視覺排版遵循 Family 2 確保跨元件視覺一致。
 
-**尺寸偏離（documented exception）**：Notice / Alert / Toast **單一固定 size**，**不**實作 Family 2 baseline 的 sm/md/lg。世界級共識（Material Banner/Snackbar、Polaris Banner、Atlassian InlineMessage、GitHub Flash）都是**單一 prominent size**——通知的使命是「搶注意」而非「在密度選擇裡協調」，提供 size 選項反而會讓 consumer 糾結（該用哪個 size？）而稀釋元件的目的性。同理 padding 也不隨 density 變（`px-4 py-3` 固定）——通知是跨 density 一致的訊息載體。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**尺寸偏離（documented exception）**：Notice / Alert / Toast **單一固定 size**——不實作 Family 2 baseline 的 sm/md/lg，padding 預設不隨 density 變（`px-4 py-3` 固定；唯一例外：Alert `placement="fixed"` 水平 px 改 density-aware，詳「Padding」段）。通知是跨頁面密度的高顯著性語意，固定尺寸才不會因宿主密度變成另一種優先序。
 
 ## Typography
 
-md tier，固定不隨 density 變：
-- title: `text-body`（14px）`leading-compact`（1.3）— 有 description 時加 `font-medium`
-- description: `text-body`（14px）`leading-compact` + `text-fg-secondary`（neutral-8）
+**Family 2 reading-md consumer（2026-06-15 user 拍板,off-grid 偏移收斂）**，md tier 固定不隨 density 變：
+- title: `text-body`（14px）**default leading 1.5** — 有 description 時加 `font-medium`
+- description: `text-body`（14px）**default leading 1.5** + `text-fg-secondary`（neutral-8）
+- label↔desc gap: `--item-gap-label-desc-reading`（ItemContent 預設 mode=`reading` size=`md` 自動選）
+- icon: 16px（`ICON_SIZE.md`，item-anatomy.tsx）
+
+相同 body 字級,層級靠 font-weight / color 區分（不靠 font-size,亦不靠 compact 行高）。
 
-相同 body 字級,層級靠 font-weight / color 區分。
+> **為何 reading-md 而非 compact（2026-06-15 codify，根治 off-grid 偏移）**：Notice 同時服務 title-only（多數）與 title+desc、Alert（banner）與 Toast（snackbar）。原本 root 套 `leading-compact`(1.3) 形成「reading gap token + scanning 行高」混搭,落在 ItemContent 4 個合法 mode（reading-md/reading-lg/scanning-md/scanning-lg）**之外**的第五種組合（label 14 + desc 14 + 行高 1.3）且未文件化 → 違反 `item-anatomy.spec.md`「偏離 canonical 必明文 rationale」。收斂為純 **reading-md**：title-only 14px 對齊 Ant/Material title-only norm（scanning-lg 的 16px 過大）；desc 維持 14px 可讀（scanning-md 的 12px caption 對通知訊息過小）；title↔desc 階層由 `font-medium` 承載已足夠。對照 FileItem（顯式 `mode="scanning"` + 文件化 = 正確消費範例,file-item.tsx:13/214）。
 
 ## Padding（固定）
 
 | 屬性 | 值 | 理由 |
 |---|---|---|
-| px | `px-4`（16px） | 世界級系統共識（Atlassian/GitHub/Material/Linear 都是 16px） | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+| px | `px-4`（16px） | 與 Alert / Toast 通知家族的內容邊距一致 |
 | py | `py-3`（12px） | 介於 row（7px）和 section（16px）之間，通知的 sweet spot |
 | gap | `gap-2`（8px） | 跟 item-layout icon-text gap 一致 |
 
 不隨 density 變——Toast/Alert 是通知，不是工作區域元件。
 
+**例外——Alert `placement="fixed"` 水平 px density-aware**:Alert 的 fixed placement 傳 `className='px-[var(--layout-space-loose)]'`(`alert.tsx` fixed 分支)覆寫 Notice 的 `px-4`，改用 density-aware 水平 padding（md=16 / lg=24px），讓 fixed alert 嵌在更大佈局時跟周圍 loose-padding 元素（Toolbar / BulkActionBar / DataTable）左右對齊。垂直 `py-3` 仍固定（notification banner family 垂直不隨 density）。故上方「px 固定」限 Notice 預設 / Toast / Alert inline placement；Alert fixed placement 是唯一 documented 例外。
+
 ## Layout
 
 item-layout 4-slot：
@@ -53,7 +68,7 @@ item-layout 4-slot：
 ```
 
 - Icon: 16px，`h-[1lh]` inline 對齊 first line
-- Dismiss X: `<Button iconOnly dismiss size="xs" />` — chrome corner action group region(Cat 3)。xs 是 **Notification banner family canonical**(Notice / Alert / Toast inherit):ephemeral banner `px-4 py-3` 固定不隨 density,dismiss 邊角小 affordance 輕量不搶眼。詳見 `patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical — 三家族分類」+ `patterns/element-anatomy/item-anatomy.spec.md`「Dismiss canonical — X close only」
+- Dismiss X: `<Button iconOnly dismiss size="xs" />` — chrome corner action group region(Cat 3)。xs 是 **Notification banner family canonical**(Notice / Alert / Toast inherit):ephemeral banner `px-4 py-3` 固定不隨 density,dismiss 邊角小 affordance 輕量不搶眼。詳見 `patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」(overlay header 走 sm native + 負 margin trick;只有 notification banner family 用 xs)+ `patterns/element-anatomy/inline-action.spec.md`「Dismiss canonical — X close only」
 - endContent: 通常放 `<Button variant="tertiary" size="xs">`
 
 ## Variant
@@ -85,7 +100,7 @@ CSS `color` 從 body 繼承的是**已解析的計算值**，不是 `var(--foreg
 
 ## 何時用 / 何時不用
 
-**Notice 是 internal primitive**——不直接使用，透過 `Alert` / `Toast` 等外層通知元件消費。
+**Notice 是 internal primitive**——不進 root barrel front-door、不裸用；透過 `Alert` / `Toast` 等外層通知元件消費；consumer 需要時可經 per-component subpath 包裝並自行確認後使用（`.claude/rules/ui-development.md`「Root barrel front-door 排除」SSOT，internal ≠ 禁用）。
 
 | 場景 | 正確做法 |
 |------|---------|
@@ -107,16 +122,17 @@ Notice 是 **Toast / Alert 共用的 layout primitive**,刻意不擁有尺寸與
 - **無 SizeMatrix**:Notice / Alert / Toast **單一固定 size**(見本 spec「尺寸偏離」段),不實作 Family 2 baseline 的 sm/md/lg——通知的使命是「搶注意」而非「在密度選擇裡協調」。padding 固定 `px-4 py-3`,typography 固定 md tier(14px),不隨 density 變。
 - **無 ColorMatrix**:Notice 本身**不設 bg / text color**(見本 spec「Theme 策略」段),色彩完全由 consumer(Alert / Toast)透過 `data-theme` + `text-foreground` 控制。Notice 層級的色彩矩陣沒有意義——視覺對照屬於 consumer 的職責,應查 `alert.anatomy.stories.tsx` 與 `toast.anatomy.stories.tsx` 的 ColorMatrix。
 
-對應 anatomy story:保留 `Overview` / `Inspector` / `StateBehavior`,額外追加元件特有的 `VariantIconMap`(展示 5 種 variant 對應的 status icon + 語意)。
+對應 anatomy story:保留 `Overview` / `Inspector` / `StateBehavior` / `Accessibility`,額外追加元件特有的 `VariantIconMap`(展示 5 種 variant 對應的 status icon + 語意)。
 
 ---
 
 ## 邊界案例
 
-- **Disabled(dismiss button)**:Notice 本身不擁有 disabled state(internal primitive,無互動);內嵌的 `<Button iconOnly dismiss size="xs" />` 自動繼承 Button disabled 視覺(`text-fg-disabled` + `cursor-not-allowed`)。Consumer(Alert / Toast)若需 disable dismiss,應透過 consumer-level prop pass-through。
+- **Disabled(dismiss button)**:Notice 本身不擁有 disabled state(internal primitive,無互動);內嵌的 `<Button iconOnly dismiss size="xs" />` 在 disabled context 內會自動繼承 Button disabled 視覺(`text-fg-disabled` + `cursor-not-allowed`)。Notice **不提供 disable dismiss 的 API**——`...props` 只 spread 到 root `<div>`,dismiss `<Button>` 不接收 / 不 forward 任何 consumer disabled prop,無 consumer-level prop pass-through 可停用 dismiss。對齊消費者 canonical(`../Alert/alert.spec.md`「Disabled(dismiss button)」:banner dismiss 恆可用,對齊 Polaris / Material Banner「通知關閉鈕應永遠可按」);若需防止 close action(API in-flight)被雙擊,consumer 在 `onDismiss` 內自行 debounce / 加上層鎖,不在 UI 層暴露 disabled 透傳。
 - **Loading**:Notice 非 async surface,無 loading state。Body 內若 consumer 注入 CTA Button,該 Button 自行處理 loading。
-- **Empty**:Notice 必有 title 或 description 其一(消費合約);無 title-only icon-less 形態,layout 至少 1 行內容。
+- **Empty**:Notice 的 `title` 為必填(TypeScript required prop,消費合約),`description` 選填;layout 至少 1 行 title 內容。誤傳空字串時照常 render(無 runtime warn / throw),空 title 的內容責任在 consumer(Alert / Toast)。`neutral` variant 不渲 status icon 時即為 title-only icon-less 形態(見 `NeutralTitleOnly` story),仍合法 render。
 - **Icon-only / variant=neutral**:`neutral` variant 不渲 status icon,layout 自動收斂為 `[title + description?]  [endContent?]  [dismiss X?]` 三 slot。
+- **`dismissible` 無 `onDismiss`**(2026-07-05 D4):X 渲染條件 = `dismissible`(預設 true)**且**有傳 `onDismiss`——Notice / Alert 為 controlled-only(不自我移除),無 handler 的 X 是可 focus、SR 播報「關閉通知」但按下零反應的死按鈕(假 affordance)。對齊 Polaris Banner(`onDismiss` 存在才顯示 X)/ Ant Alert(`closable` 預設 false)。顯式傳 `dismissible={true}` 卻缺 `onDismiss` 時 dev-only `console.warn` 提示(預設未傳不吵)。
 
 ---
 
@@ -134,10 +150,12 @@ Notice 是 **Toast / Alert 共用的 layout primitive**,刻意不擁有尺寸與
 
 **Keyboard 行為**:
 
-- Tab — focus dismiss button(若 dismissible)
-- Esc — dismiss(若 dismissible)
+- Tab — focus dismiss button(若 dismissible 且有傳 `onDismiss`——X 僅在兩者同時成立時渲染,見「邊界案例」,2026-07-05 D4;consumer 經 `endContent` 注入互動元素時,其 DOM 順序在 dismiss 之前,Tab 先落 endContent)
+- Enter / Space — 觸發 focus 中的 dismiss button(原生 button 行為,呼叫 `onDismiss`)
+
+Notice **不**自帶 Esc-to-dismiss 行為(`notice.tsx` 無 keydown handler);dismiss 純粹由 dismiss button 的 `onClick={onDismiss}` 觸發。若 consumer(Alert / Toast)需要 Esc 關閉,於 consumer 層自行掛 keydown。Dismiss 後的焦點處置 Notice 同樣不管理(無 focus restoration 邏輯)——節點移除後焦點落點由 consumer(Alert / Toast host)決定。
 
-**Focus**:focus-visible ring 對齊 DS canonical(`outline: 2px solid var(--ring)`);focus management 由元件 own。
+**Focus**:Notice 自身渲染的唯一 focusable 元素是 dismiss `<Button>`(consumer 經 `endContent` 注入的互動元素——如上方建議的 tertiary Button——由 consumer 自管 a11y),focus indicator 走 Button canonical(`focus-visible:ring-2 ring-ring`,box-shadow ring 非 CSS `outline`);Notice 本身無 focus management(dismiss 後焦點處置見上段,由 consumer 決定)。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
@@ -145,5 +163,8 @@ Notice 是 **Toast / Alert 共用的 layout primitive**,刻意不擁有尺寸與
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `alert.spec.md`
 - `bulk-action-bar.spec.md`
 - `coachmark.spec.md`
+- `item-anatomy.spec.md`
+- `toast.spec.md`

package/src/components/Notice/notice.stories.tsx

@@ -0,0 +1,257 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { Notice, useInverseTheme, SUBTLE_ICON_COLOR, type NoticeVariant } from './notice'
+import { Button } from '@/design-system/components/Button/button'
+
+const meta: Meta<typeof Notice> = {
+  title: 'Design System/Internal/Notice/展示',
+  component: Notice,
+  tags: ['!dev'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Notice 是 Toast / Alert 共用的視覺佈局 primitive——只負責 layout 與 icon 選擇,色彩由 consumer 透過 `data-theme` + `text-foreground` 控制。App 層級不直接使用 `<Notice>`,而是透過 `<Alert>` / `<Toast>`。以下情境展示 Notice 被 consumer 包成兩種視覺風格(subtle / solid)後的樣貌。',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof Notice>
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   共用:模擬 Alert 的 subtle / solid 外殼
+   ─ Notice 本身不含 bg / border——這裡補上 consumer 才會加的 surface
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+const SUBTLE_CONTAINER: Record<NoticeVariant, string> = {
+  neutral: 'bg-muted border border-border',
+  info: 'bg-info-subtle border border-[var(--info-text)]',
+  success: 'bg-success-subtle border border-[var(--success-text)]',
+  warning: 'bg-warning-subtle border border-[var(--warning-text)]',
+  error: 'bg-error-subtle border border-[var(--error-text)]',
+}
+
+const SOLID_BG: Record<Exclude<NoticeVariant, 'neutral'>, string> = {
+  info: 'bg-info',
+  success: 'bg-success',
+  warning: 'bg-warning',
+  error: 'bg-error',
+}
+
+const SOLID_THEME: Record<Exclude<NoticeVariant, 'neutral'>, 'dark' | 'light'> = {
+  info: 'dark',
+  success: 'dark',
+  warning: 'light',
+  error: 'dark',
+}
+
+function SubtleShell({
+  variant,
+  children,
+}: {
+  variant: NoticeVariant
+  children: React.ReactNode
+}) {
+  return (
+    <div className={`rounded-md overflow-hidden text-foreground ${SUBTLE_CONTAINER[variant]}`}>
+      {children}
+    </div>
+  )
+}
+
+function SolidShell({
+  variant,
+  children,
+}: {
+  variant: NoticeVariant
+  children: React.ReactNode
+}) {
+  const inverse = useInverseTheme()
+  if (variant === 'neutral') {
+    return (
+      <div
+        data-theme={inverse}
+        className="rounded-md overflow-hidden bg-surface-raised text-foreground"
+      >
+        {children}
+      </div>
+    )
+  }
+  const hue = variant as Exclude<NoticeVariant, 'neutral'>
+  return (
+    <div className={`rounded-md overflow-hidden ${SOLID_BG[hue]}`}>
+      <div data-theme={SOLID_THEME[hue]} className="text-foreground">
+        {children}
+      </div>
+    </div>
+  )
+}
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Story 1:部署成功通知(單行 subtle success)
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+export const DeploymentSuccess: Story = {
+  name: '部署成功 橫幅',
+  render: () => (
+    <div className="max-w-2xl">
+      <SubtleShell variant="success">
+        <Notice
+          variant="success"
+          iconClassName={SUBTLE_ICON_COLOR.success}
+          title="專案已成功部署到 production 環境"
+          endContent={
+            <Button variant="tertiary" size="xs">
+              查看部署紀錄
+            </Button>
+          }
+        />
+      </SubtleShell>
+    </div>
+  ),
+}
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Story 2:Workspace 付款失敗(solid error + 補救 action)
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+export const BillingFailed: Story = {
+  name: '工作區付款失敗',
+  render: () => (
+    <div className="max-w-2xl">
+      <SolidShell variant="error">
+        <Notice
+          variant="error"
+          title="本月訂閱付款失敗"
+          description="你的信用卡發卡行拒絕扣款。請在 7 天內更新付款方式,否則工作區將被暫停。"
+          endContent={
+            <Button variant="tertiary" size="xs">
+              更新付款方式
+            </Button>
+          }
+        />
+      </SolidShell>
+    </div>
+  ),
+}
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Story 3:功能限定於進階方案(subtle info + 多變體對照)
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+export const InlineVariants: Story = {
+  name: '行內通知變體對照',
+  render: () => {
+    const items: { variant: NoticeVariant; title: string; description?: string }[] = [
+      {
+        variant: 'info',
+        title: 'Audit log 僅限 Business 方案',
+        description: '升級後可回溯 90 天內所有成員的操作紀錄。',
+      },
+      {
+        variant: 'warning',
+        title: '此環境剩餘儲存空間不足 10%',
+        description: '建議清理舊版本或升級儲存方案,避免上傳中斷。',
+      },
+      {
+        variant: 'success',
+        title: '兩步驟驗證已啟用',
+      },
+      {
+        variant: 'error',
+        title: '無法連線到 GitHub integration',
+        description: '過去 24 小時有 3 次同步失敗,請重新授權 GitHub App。',
+      },
+      {
+        variant: 'neutral',
+        title: '維護視窗 4/25 02:00 – 04:00 (UTC+8)',
+        description: '期間 Dashboard 可能暫時無法存取,CI pipelines 不受影響。',
+      },
+    ]
+    return (
+      <div className="flex flex-col gap-3 max-w-2xl">
+        {items.map((item) => (
+          <SubtleShell key={item.variant} variant={item.variant}>
+            <Notice
+              variant={item.variant}
+              iconClassName={SUBTLE_ICON_COLOR[item.variant]}
+              title={item.title}
+              description={item.description}
+              endContent={
+                <Button variant="tertiary" size="xs">
+                  了解更多
+                </Button>
+              }
+            />
+          </SubtleShell>
+        ))}
+      </div>
+    )
+  },
+}
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Story 4:Toast 短暫通知(solid,不可 dismiss — sonner 自動關)
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+export const ToastLikeSolid: Story = {
+  name: 'Toast 樣式',
+  render: () => (
+    <div className="flex flex-col gap-3 max-w-md">
+      <p className="text-caption text-fg-muted">
+        浮動自動消失的 toast 通常不需要 dismiss 按鈕——關閉由計時器控制。
+      </p>
+      <SolidShell variant="success">
+        <Notice
+          variant="success"
+          title="變更已儲存"
+          dismissible={false}
+        />
+      </SolidShell>
+      <SolidShell variant="info">
+        <Notice
+          variant="info"
+          title="已複製連結到剪貼簿"
+          dismissible={false}
+        />
+      </SolidShell>
+      <SolidShell variant="error">
+        <Notice
+          variant="error"
+          title="上傳失敗"
+          description="檔案超過 25 MB 上限。"
+          dismissible={false}
+          endContent={
+            <Button variant="tertiary" size="xs">
+              重試
+            </Button>
+          }
+        />
+      </SolidShell>
+    </div>
+  ),
+}
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Story 5:只有 title(neutral 無 icon)
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+export const NeutralTitleOnly: Story = {
+  name: '中性 純文字',
+  render: () => (
+    <div className="max-w-2xl">
+      <SubtleShell variant="neutral">
+        <Notice
+          variant="neutral"
+          title="5 個成員已收到邀請 email,尚未加入工作區。"
+          endContent={
+            <Button variant="tertiary" size="xs">
+              重發邀請
+            </Button>
+          }
+        />
+      </SubtleShell>
+    </div>
+  ),
+}