@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

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 + 處理 unmount + live region:error/warning role="alert"、其餘 role="status")</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="低調單行"><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

@@ -0,0 +1,158 @@
+---
+component: Notice
+family: 2
+variants: {}
+sizes: {}
+traits:
+  - isInternal
+benchmark:
+  - Ant Design Alert: github.com/ant-design/ant-design/tree/master/components/alert
+  - Polaris Banner: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Banner
+  - 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` 控制。
+
+## 定位
+
+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 確保跨元件視覺一致。
+
+**尺寸偏離（documented exception）**：Notice / Alert / Toast **單一固定 size**——不實作 Family 2 baseline 的 sm/md/lg，padding 也不隨 density 變（`px-4 py-3` 固定）。通知用單一 prominent size 強化「搶注意」的目的性，對齊世界級共識（Material Banner/Snackbar、Polaris Banner、Atlassian InlineMessage、GitHub Flash）。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+## Typography
+
+**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 行高）。
+
+> **為何 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 -->
+| py | `py-3`（12px） | 介於 row（7px）和 section（16px）之間，通知的 sweet spot |
+| gap | `gap-2`（8px） | 跟 item-layout icon-text gap 一致 |
+
+不隨 density 變——Toast/Alert 是通知，不是工作區域元件。
+
+## Layout
+
+item-layout 4-slot：
+```
+[status icon?]  [title + description?]  [endContent?]  [dismiss X?]
+```
+
+- 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」(overlay header 走 sm native + 負 margin trick;只有 notification banner family 用 xs)+ `patterns/element-anatomy/item-anatomy.spec.md`「Dismiss canonical — X close only」
+- endContent: 通常放 `<Button variant="tertiary" size="xs">`
+
+## Variant
+
+| Variant | Icon | 語意 |
+|---|---|---|
+| neutral | 無 | 一般訊息 |
+| info | Info（ℹ） | 資訊提示 |
+| success | CircleCheck（✓） | 操作成功 |
+| warning | TriangleAlert（⚠） | 警告 |
+| error | XCircle（✕） | 錯誤 |
+
+## Theme 策略
+
+Notice **不設** bg 和 text color。消費者在 container 設 `data-theme` + `text-foreground`，Notice 內所有 token 自然適配。
+
+消費者的 data-theme 策略：
+
+| 場景 | data-theme | text 結果 |
+|---|---|---|
+| 有色相 solid（info/success/error） | `"dark"` | neutral-9 = 白 |
+| warning solid | `"light"`（永遠） | neutral-9 = 黑 |
+| neutral solid | `{inverse}`（跟頁反） | 跟隨翻轉 |
+| subtle | 不設（跟隨頁面） | 跟隨頁面 |
+
+### 為什麼 data-theme 要搭配 text-foreground
+
+CSS `color` 從 body 繼承的是**已解析的計算值**，不是 `var(--foreground)` 表達式。`data-theme` 改變 `--foreground` 的值，但不改 `color` 屬性。在 theme boundary 設 `text-foreground` class 強制 `color: var(--foreground)` 在正確 context 重新解析。
+
+## 何時用 / 何時不用
+
+**Notice 是 internal primitive**——不直接使用，透過 `Alert` / `Toast` 等外層通知元件消費。
+
+| 場景 | 正確做法 |
+|------|---------|
+| Inline / fixed 持久通知 | 用 `Alert`（內部消費 Notice）|
+| 浮動自動消失的短暫通知 | 用 `Toast`（內部消費 Notice + sonner）|
+| 直接在 JSX 中用 `<Notice>` | ❌ **禁止**——失去 Alert / Toast 外層的生命週期與定位管理 |
+
+### 消費者
+
+- `../Alert/alert.spec.md` — inline / fixed 持久通知
+- `../Toast/toast.spec.md` — 浮動非阻斷短暫通知
+
+---
+
+## 為何無 SizeMatrix / ColorMatrix
+
+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` / `Accessibility`,額外追加元件特有的 `VariantIconMap`(展示 5 種 variant 對應的 status icon + 語意)。
+
+---
+
+## 邊界案例
+
+- **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` 為必填(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。
+
+---
+
+## 相關
+
+- `../Alert/alert.spec.md` — 主要消費者（持久通知）
+- `../Toast/toast.spec.md` — 主要消費者（短暫通知）
+- `../../patterns/element-anatomy/item-anatomy.spec.md` — Notice 的 layout 共用規則
+- `../../tokens/color/color.spec.md` — color tokens 和 variant × theme 策略
+- `../../tokens/color/primitives.css` — primitives nested theme（`:root, [data-theme]` pattern）
+
+## A11y 預設
+
+**ARIA / Pattern**:對齊 [W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/) 對應 pattern。
+
+**Keyboard 行為**:
+
+- Tab — focus dismiss button(若 dismissible)
+- 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**:唯一 focusable 元素是 dismiss `<Button>`,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)。
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `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>
+  ),
+}

package/src/components/Notice/notice.tsx

@@ -1,16 +1,23 @@
+/**
+ * @internal — DS-internal 單元(per `.claude/rules/ui-development.md` Public vs Internal canonical;spec frontmatter `isInternal`)。
+ * 不進 root barrel front-door;由 Alert / Toast wrap 消費,end-user app 請用 wrapper 元件。
+ */
 import * as React from 'react'
 import { X as XIcon, Info, CircleCheck, TriangleAlert, XCircle, type LucideIcon } from 'lucide-react'
 import { cn } from '@/lib/utils'
 import { Button } from '@/design-system/components/Button/button'
-import { ItemContent, ItemPrefix } from '@/design-system/patterns/element-anatomy/item-anatomy'
+import { ItemContent, ItemPrefix, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
 
 /**
  * Notice — Toast / Alert 共用的視覺佈局層
  *
- * ── Typography: md tier ──
- * title: text-body (14px) leading-compact — 有 description 時加 font-medium
- * description: text-body (14px) leading-compact + text-fg-secondary (neutral-8)
+ * ── Typography: Family 2 reading-md(2026-06-15 user 拍板,off-grid 偏移收斂)──
+ * title: text-body (14px) default leading 1.5 — 有 description 時加 font-medium
+ * description: text-body (14px) default leading 1.5 + text-fg-secondary (neutral-8)
  * 14px 配 14px — 視覺層級靠 font-weight + color 區分,不靠 font-size。
+ * **行高 = reading 預設 1.5**(非 compact):Notice 是 Family 2 reading consumer,
+ * ItemContent 預設 mode='reading' + gap token `--item-gap-label-desc-reading` 名實相符。
+ * 原 `leading-compact`(1.3)= reading-gap + scanning-行高 混搭的 off-grid 偏移,已移除。
  *
  * ── Padding（固定,不隨 density 變） ──
  * px = px-4（16px）
@@ -27,7 +34,7 @@ import { ItemContent, ItemPrefix } from '@/design-system/patterns/element-anatom
  * Rationale(Notification banner family canonical):
  * - Notice / Alert / Toast 屬 **notification banner family**(ephemeral、px-4 py-3 固定不隨 density),
  *   dismiss 是邊角小 affordance,xs 視覺不搶眼不跟 content 競爭。見 `overlay-surface.spec.md`
- *   「Chrome dismiss size canonical」三家族分類(Modal sm / Non-modal xs / Notification xs)
+ *   「Chrome dismiss size canonical」(overlay header 走 sm native + 負 margin trick;xs 只用於 notification banner family)
  * - Close 左側可加 refresh / share(action group region),皆統一 xs
  * - `dismiss` prop 自動套 variant="text" + fg-muted override
  * SSOT:patterns/element-anatomy/inline-action.spec.md「Dismiss canonical — X close only」
@@ -54,7 +61,11 @@ export const SUBTLE_ICON_COLOR: Record<NoticeVariant, string> = {
 
 const NOTICE_LAYOUT = [
   'flex items-start gap-2 w-full',
-  'text-body leading-compact',
+  // 2026-06-15 user 拍板:Notice = 乾淨 Family 2 reading-md consumer。
+  // 原 `leading-compact`(1.3)是 off-grid 偏移(reading gap token + scanning 行高混搭、未文件化),
+  // 已移除 → label/desc 走 text-body reading 預設 1.5,與 ItemContent 預設 mode='reading' + gap
+  // token `--item-gap-label-desc-reading` 名實相符。詳 notice.spec.md「Typography」段。
+  'text-body',
   'px-4 py-3',
 ].join(' ')
 
@@ -120,7 +131,12 @@ const Notice = React.forwardRef<HTMLDivElement, NoticeProps>(
         />
 
         {(endContent || dismissible) && (
-          <div className="flex items-center gap-2 shrink-0 h-[1lh]">
+          // 2026-06-15 user 拍板:消費 ItemSuffix primitive(原手刻 div + @row-slot-handcraft-allow
+          // 已移除)。item-anatomy.spec.md 把 Notice 的 action/dismiss 對應到 suffix slot;ItemSuffix
+          // base geometry(h-[1lh] shrink-0 ml-auto flex items-center gap-2)正是此處所需,hoverReveal
+          // 預設 false 故無 row inline-action 機制干擾。內裝 dismiss = Button iconOnly dismiss xs(banner
+          // family canonical,overlay-surface.spec.md「Chrome dismiss size canonical」)。
+          <ItemSuffix>
             {endContent}
             {dismissible && (
               <Button
@@ -133,7 +149,7 @@ const Notice = React.forwardRef<HTMLDivElement, NoticeProps>(
                 onClick={onDismiss}
               />
             )}
-          </div>
+          </ItemSuffix>
         )}
       </div>
     )
@@ -178,14 +194,14 @@ export function useInverseTheme(): 'dark' | 'light' {
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const noticeMeta = {
   component: 'Notice',
-  family: null, // non-family composite / overlay / layout
+  family: 2, // Family 2（List item layout）消費者 — 對齊 notice.spec.md frontmatter family: 2 + body「Layout Family」段
   variants: {
 
   },
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  states: ['default'], // 無互動 layout primitive(spec「邊界案例」:不擁有 disabled;hover / focus 屬內嵌 dismiss Button)
   tokens: {
     bg: [],
     fg: ['text-error-text', 'text-fg-muted', 'text-fg-secondary', 'text-info-text', 'text-success-text', 'text-warning-text'],

package/src/components/NumberInput/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 './number-input'