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

package/src/components/TimePicker/time-picker.spec.md

@@ -0,0 +1,279 @@
+---
+component: TimePicker
+family: 4
+variants: {}
+sizes: {}
+traits:
+  - hasInteractiveStates
+  - isInputLike
+benchmark:
+  - Ant Design TimePicker: github.com/ant-design/ant-design/tree/master/components/time-picker
+  - MUI X Date Pickers (Time): github.com/mui/mui-x/tree/master/packages/x-date-pickers
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — all claims have inline URL or per-claim @benchmark-unverified retract. M22 inline cites added 2026-05-03 v11. -->
+
+# TimePicker 設計原則
+
+## 定位
+
+TimePicker 是**單一時間**(時/分/秒)輸入與顯示元件,對齊 Ant Design `<TimePicker>` API 風格(source: [github.com/react-component/picker/src/PickerInput/SinglePicker.tsx](https://github.com/react-component/picker/blob/master/src/PickerInput/SinglePicker.tsx)),但視覺與互動走本 DS 設計語言。
+
+**Layout Family**:**Family 4(Field control layout)**,視覺對齊 Family 1(Menu item)。見 `patterns/element-anatomy/element-anatomy.spec.md`「Field Composition(不在 family 但相關)」段。
+
+**實作基礎**:
+- **Trigger**:`<button>` + `fieldWrapperStyles`(視覺 = Input wrapper,但 role 是 button 開 popover)
+- **Popup**:`<Popover>`(消費 `patterns/overlay-surface/` 的 surface chrome)
+- **Panel 主體**:**自建** 2-3 欄 column picker(時 / 分 / 秒),**不引入第三方 time library**——自建讓 DS own 視覺與交互(對齊 Ant Design 的 Panel 結構 — [react-component/picker TimePanel](https://github.com/react-component/picker/tree/master/src/PickerPanel/TimePanel) + 本 DS token)
+- **世界級對照**:Ant Design TimePicker([source](https://github.com/react-component/picker/tree/master/src/PickerPanel/TimePanel))/ Material DateTimePicker([mui-x DigitalClock](https://github.com/mui/mui-x/blob/master/packages/x-date-pickers/src/DigitalClock/DigitalClock.tsx))/ iOS native time picker `@benchmark-unverified`(closed-source)——共同行為:column scroll selector、minuteStep 支援、Now / OK footer、clearable
+
+---
+
+## Controlled-only rationale(Dim 26)
+
+本元件刻意採 **controlled-only** 模式:`value` + `onChange` 必傳,不支援 `defaultValue` uncontrolled fallback。
+
+**為什麼**:
+- 內部狀態複雜(search filter / range / menu open state)跟 `value` 雙向 sync 會產生 race condition
+- Consumer 幾乎一定有外部 state(form library / app state),強制 controlled 消除 ambiguity
+- 世界級對照:Ant Design DatePicker([source](https://github.com/react-component/picker/blob/master/src/PickerInput/SinglePicker.tsx)) / Material MUI Select([source](https://github.com/mui/material-ui/blob/master/packages/mui-material/src/Select/Select.js))皆支援 dual-mode;我們選 controlled-only 對齊狀態一致性優先
+
+**若未來要改 dual-mode**:需引入 `useControllableState` helper + 測試 controlled↔uncontrolled switch 場景,屬 major API 擴充,非本 session scope。
+
+---
+
+## 何時用
+
+| 情境 | 範例 |
+|------|------|
+| 會議排程時間 | Calendar event 的 start / end time(常 minuteStep=15) |
+| 航班 / 公車時刻 | 起飛時間、發車時間(HH:mm) |
+| 營業時間 / 工作時間 | 店家開放時間、員工排班上下班 |
+| 提醒 / 鬧鐘時間 | Reminder time picker(秒無意義,showSeconds=false) |
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 同時需要日期 + 時間 | **DatePicker with time** 或 `<DatePicker> + <TimePicker>` 並列 | TimePicker 本身不帶日期;需配 DatePicker 組合 |
+| 時間範圍(from-to) | **兩個 `<TimePicker>`** 並列 + 之間 `<ArrowRight>` | TimePicker **MVP 不支援 range**,用組合達成(對齊 Ant `TimePicker.RangePicker` 的 composition 思路 — [source](https://github.com/react-component/picker/blob/master/src/PickerInput/RangePicker.tsx)) |
+| 純文字時間輸入(秒有意義的科學測量) | `<Input>` + mask / regex validation | TimePicker 的 column UX 不適合大量精確輸入 |
+| 倒數計時 / 相對時間 | 自行渲染 `MM:SS` 倒數 | TimePicker 是 wall-clock time,不是 duration |
+
+---
+
+## API
+
+```tsx
+<TimePicker
+  value={time}                   // ISO "HH:mm" or "HH:mm:ss" | null
+  onChange={setTime}
+  size="sm" | "md" | "lg"        // 對齊 field-height family,default md
+  mode="edit" | "readonly" | "disabled"
+  disabled={boolean}
+  error={boolean}
+  clearable={boolean}
+  placeholder="請選擇時間"
+  showSeconds={boolean}          // 預設 false(兩欄:時/分)
+  minuteStep={1 | 5 | 10 | 15 | 30}   // 會議常用 15
+  secondStep={1 | 5 | 10 | 15 | 30}   // showSeconds=true 時生效
+  disabledTime={(parts) => ({    // 動態禁用某些時/分/秒
+    disabledHours: [...],
+    disabledMinutes: [...],
+    disabledSeconds: [...],
+  })}
+  endIcon={Clock}                // 預設 Clock,傳 null 關閉(2026-05-05 v9:點擊觸發浮層 indicator 一律 suffix,對齊 DatePicker / Material endAdornment)
+  locale="en-US"
+  formatOptions={{ hour: '2-digit', minute: '2-digit', hour12: false }}
+/>
+```
+
+### Value 格式
+
+**Value 是 ISO time string**(`"HH:mm"` 或 `"HH:mm:ss"`),local-time 語義(不帶時區 / 不帶日期)—— 對齊 DatePicker 家族的「value = ISO string」策略,consumer 不需持有 Date object。
+
+### 顯示格式化
+
+**Display 走 `Intl.DateTimeFormat`**(跨 locale 統一、12h/24h 支援)。`formatOptions` 透傳進去。
+
+---
+
+## 尺寸
+
+| size | field-height(md density) | Icon | 字體 |
+|------|--------------------------|------|------|
+| sm | 28px(`h-field-sm`)| 16px | text-body |
+| md | 32px(`h-field-md`,**預設**)| 16px | text-body |
+| lg | 36px(`h-field-lg`)| 20px | text-body-lg |
+
+**field-height family 成員**,default = md(與 Button / Input / DatePicker 共享),完整 density-aware 值(lg density: sm=32 / md=36 / lg=40)見 `tokens/uiSize/uiSize.spec.md`。
+
+---
+
+## Panel 視覺規則
+
+Panel 展開後的 column picker 結構:
+
+```
+┌─────────────────────────────────┐
+│  時    分    [秒]                │  ← header(有 label 時顯示)
+├─────┬─────┬──────────────────┤
+│  09 │  00 │                   │
+│  10 │  15 │  每欄 scrollable   │  ← body
+│▓11▓│▓30▓│  選中項藍底白字     │
+│  12 │  45 │                   │
+│  13 │     │                   │
+├─────┴─────┴──────────────────┤
+│            [Now]    [OK]     │  ← footer(選填)
+└───────────────────────────────┘
+```
+
+### 欄內 item 狀態(對齊 SelectMenu canonical,**非 DatePicker**)
+
+| State | 視覺 | Token |
+|-------|------|-------|
+| 正常 | 置中文字 | `text-foreground` |
+| hover | 灰底 | `hover:bg-neutral-hover` |
+| **selected** | **灰底**(非藍底) | `bg-neutral-selected text-foreground rounded-md` |
+| disabled(`disabledTime`) | 灰字 | `text-fg-disabled cursor-not-allowed` |
+
+**為什麼 selected 走 neutral 非 primary**(2026-04-21 canonical):TimePicker panel 是「**列表選中**」語意 — user 在時 / 分 / 秒選項間切換,跟 `SelectMenu` / `MenuItem` 同流派(單選 list → `bg-neutral-selected`)。**DatePicker date cell selected 用 `bg-primary`** 是因為那是「**最終選定日期**」的強 affordance(確定性)。兩者不同語意,不互調。
+
+對齊 SelectMenu / MenuItem 的好處:consumer 看 TimePicker 面板知道這是「選一個項目」,跟 Select 下拉選單認知一致(Ant Design TimePicker panel 同樣採 neutral selected — [picker style source](https://github.com/ant-design/ant-design/blob/master/components/date-picker/style/panel.ts) `@benchmark-unverified` exact line)。
+
+### Spacing + 結構(2026-04-21 canonical,2026-04-21 window width 修正)
+
+- Panel 內 padding = `--layout-space-tight`(12px @ md density)
+- **三欄(時 / 分 / 秒)各欄 `w-12`(48px)固定,非 flex-1 均分**(對齊 Ant / Google 世界級慣例 `@benchmark-unverified` visual measurement)。**分隔「:」移除**(AR8 canonical — Ant TimePicker / Google Calendar 同樣不加 `:`,靠 column 間距自明 `@benchmark-unverified` visual)
+- Scrollable list 用 **`<ScrollArea>`**(對齊 DS 跨 OS 一致 overlay 捲軸 canonical);不 raw `overflow-y-auto`
+- **Scroll-into-view**:mount = `behavior:'auto'`(避閃爍),後續 `value` 變更 = `behavior:'smooth'`(對齊 iOS / Material / Ant timepicker idiom)。SSOT 在 `time-columns.tsx` `TimeColumn` useEffect
+- 每 item **`h-field-sm`(28px @ md / 32px @ lg)對齊 DatePicker date cell**(跨 picker 視覺一致)
+- List 高 `h-[216px]`(容納約 7 個 item 置中)
+
+### Panel 寬度 content-driven(AR42 修正,2026-04-21)
+
+**每欄 w-12(48px)固定,Panel 寬度隨 showSeconds 動態變化**:
+
+| 模式 | 欄數 | Panel 寬(含 padding + gap) |
+|------|------|---------------------------|
+| HH:mm(預設)| 2 欄 | `2 × 48 + gap-1 × 1 + px × 2` ≈ 48×2 + 4 + 24 = **124px** |
+| HH:mm:ss(showSeconds=true)| 3 欄 | `3 × 48 + gap-1 × 2 + px × 2` ≈ 48×3 + 8 + 24 = **176px** |
+
+**世界級對照**:
+- Ant Design TimePicker:每欄 ~56px,3 欄 ~170px(Panel 含 footer)`@benchmark-unverified` visual measurement(visual sampling,not source-citable as exact pixel)
+- Google Calendar Quick-Time:~150-170px
+- Material 3 TimePicker dial:~180px(含 AM/PM)`@benchmark-unverified` visual measurement
+- 本 DS:每欄 48px,2 欄 ~124px / 3 欄 ~176px,**符合世界級緊湊節奏**
+
+**為什麼每欄 48px 不 56 / 64**:
+- 48px = `h-field-sm × 1.7`,兩位數字 `tabular-nums`(約 16-18px 寬)+ 左右呼吸 ~15px。不貼邊也不浪費
+- 56-64px 寬度逼近 Select menu 語境;picker column 超過此寬度會模糊 picker vs menu 的視覺界線
+- Ant 56 / 本 DS 48 差異在:Ant 的 item 有圓角 button 佔寬,本 DS 走 `rounded-md` `text-center`,視覺 48px 不擠 `@benchmark-unverified` visual measurement
+
+**showSeconds 切換時 panel 寬度會跟著變**(刻意):
+- 對齊 Ant 慣例(content-driven)
+- showSeconds=false 的 panel 本就應該更窄,兩欄 + 大量留白會顯得 panel 空洞
+- Popover position 受 side / align / collisionPadding 控制,寬度變化只移動 panel 位置不影響 anchor 關係
+
+---
+
+## 鍵盤
+
+| 按鍵 | 行為 |
+|------|------|
+| 點 trigger | 開 Panel |
+| Esc | 關 Panel(不確認) |
+| Tab | 焦點在 column 間移動 |
+| ↑ / ↓ | 欄內上下選 |
+| Enter | 確認當前 highlight |
+| 直接鍵入數字(optional) | 跳到對應值 |
+
+---
+
+## 狀態行為
+
+### Mode / Error / Disabled / Readonly
+詳見 `../Field/field-controls.spec.md`(共用規則)。
+
+### Empty 值
+`value={null}` / `value=""` / `value=undefined` 都視為空,trigger 顯示 `placeholder`。Display 模式空值顯示 `—`(對齊 `EMPTY_DISPLAY`)。
+
+### 驗證時機
+- Panel 關閉(OK 或 outside click)時 commit value 給 `onChange`
+- `disabledTime` 在 Panel 開啟時套用(selected hour 改變會重算 disabledMinutes)
+- 若 consumer 需要 form-level 必填驗證 → 外層 `<Field>` + `<FieldError>` 承擔(不是 TimePicker 本體責任)
+
+### Loading
+N/A — TimePicker 是純同步輸入,無 async 狀態。
+
+---
+
+## A11y 預設
+
+- trigger 需 `aria-label`(若沒外部 `<label>`)
+- Panel 開啟時 trigger `aria-expanded="true"`
+- 每欄 `role="listbox"`,item `role="option" aria-selected`
+- Screen reader 讀出「時間選擇器,當前 9 時 30 分」
+
+---
+
+## Dismiss / Clear 規則(對齊 CLAUDE.md canonical)
+
+- **關閉 Panel** → `onOpenChange(false)`(Popover 內建)/ outside click / Esc —— 這是 **overlay close**,不是 `onClear`
+- **清空值** → `clearable={true}` 在 trigger 的 endAction slot 顯示 `X` 透過 `ItemInlineActionButton`(canonical),點擊 `onChange("")`
+- **禁止**:用帶文字 label 的 Button(「清除」)作 clear
+
+---
+
+## 為何無 Range(MVP)
+
+user 若需「from-to」時間範圍,用**兩個 `<TimePicker>` 並列 + 中間 `<ArrowRight>`**(對齊 Ant `TimePicker.RangePicker` 的 composition 思路)。內建 Range 暫不 MVP 實作,因為:
+
+1. 大部分「時間範圍」情境是**營業時間 / 會議時段**,consumer 端用兩個 TimePicker 組合語意更清晰
+2. 未來若出現大量 Range 需求(如 shift 排班表),再抽 `<TimePicker.Range>` sub-composition,對齊 DatePicker.Range 的 API pattern
+
+---
+
+## ColorMatrix 說明(兩層 SSOT 整合展示)
+
+TimePicker 視覺分兩層,各自繼承不同 SSOT:
+- **Trigger 層**:走 Field Controls family 色彩(由 `../Field/field-controls.spec.md` 擁有,共用 Input / Select)
+- **Panel column item 層**:走 SelectMenu / MenuItem canonical `bg-neutral-selected`(由 `patterns/element-anatomy/item-anatomy.spec.md` 擁有,非 `bg-primary`——見本 spec「欄內 item 狀態」表)
+
+`ColorMatrix` story 整合展示兩層 token 對照,但不重複定義(各 token 來源明示指向上游 SSOT)。
+
+## 為何無 StateBehavior
+
+trigger 的互動狀態(focus / invalid / disabled / readonly)完全繼承 `../Field/field-controls.spec.md` SSOT「Mode 狀態」;panel 內 column item 的 hover / selected / disabled 走 `patterns/element-anatomy/item-anatomy.spec.md`「選擇 / 狀態視覺規則」。TimePicker 層級無自有 state 行為,panel 開 / 關由 Popover primitive 處理。重寫 StateBehavior = 與兩個 SSOT 同時漂移。
+
+對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix`(兩層整合展示) + `SizeMatrix` + 元件特有 `ModeMatrix` / `PrecisionMatrix`。Field-level state 見 Input `StateBehavior` + field-controls.spec.md;panel item-level state 見 SelectMenu / MenuItem 的對應 story。
+
+---
+
+## 禁止事項
+
+- ❌ 不要在 TimePicker 內部直接顯示日期——那是 DatePicker 的語義
+- ❌ 不要把 value 改存 Date object——對齊家族 ISO string 策略
+- ❌ minuteStep 不要設 7 / 11 / 13 等非整除值——會出現 00 / 07 / 14 / 21 / 28 / 35... 不符時間習慣
+- ❌ 不要自刻 `<input type="time">`——瀏覽器原生 UI 跨 OS 不一致,違反 DS「跨 OS 視覺一致」原則
+- ❌ Clear button 用帶文字 label 的 Button(違反 dismiss canonical,見 `patterns/element-anatomy/item-anatomy.spec.md`「Dismiss 按鈕 canonical」)
+
+---
+
+## 邊界案例
+
+- **Disabled**:Field SSOT own;trigger 自動 disabled(`text-fg-disabled` + 不開 picker),Display mode + disabled 維持時間格式但 token 切 disabled。
+- **Loading**:TimePicker 為 sync UI(time math 在 client),無 loading state。極端 case(後端 disabled-times list)應由 consumer 先 disable trigger 直到 fetch 完成。
+- **Empty(no value)**:`value=null` 為合法 initial state,trigger 顯 placeholder(預設「選擇時間」);`null` + Display mode 顯 `—`(em dash + `text-fg-muted`)對齊 Input display empty 慣例。
+- **Empty(disabled all times)**:極端場景(`disabledHours` / `disabledMinutes` 覆蓋全範圍),panel column 全 disabled,鍵盤焦點停留無導覽目標。
+- **Dark mode / density**:走 Field + Popover SSOT 自動 adapt;panel column item 由 MenuItem SSOT 控 density。
+
+---
+
+## 相關
+
+- `../DatePicker/date-picker.spec.md` — 日期選擇,TimePicker 姊妹元件,API 風格對齊
+- `../Input/input.spec.md` — Field control 基礎
+- `../Field/field-controls.spec.md` — Mode / size / error 共用規則
+- `../Field/form-validation.spec.md` — 驗證時機
+- `../../patterns/element-anatomy/item-anatomy.spec.md`「Dismiss 按鈕 canonical」 — clear button 規則

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

@@ -0,0 +1,177 @@
+---
+component: Toast
+family: 2
+traits:
+  - hasVariants
+variants:
+  neutral:
+    when: "非狀態通知;一般 announcement / tip(『已複製到剪貼簿』『偏好已儲存』)"
+    world-class: ["Polaris Toast default", "Sonner default", "Linear toast neutral"]
+  info:
+    when: "資訊性提示(『新版本可用』『同步完成』);非錯誤、非成功"
+    world-class: ["Material Snackbar info", "Ant notification info"]
+  success:
+    when: "成功確認(『訂單已寄送』『付款完成』『5 筆資料已匯入』)"
+    world-class: ["Polaris Toast success", "Linear toast success", "Stripe payment success"]
+  warning:
+    when: "可恢復警告(『有未儲存變更』『連線不穩』『token 將過期』)"
+    world-class: ["Ant notification warning", "Carbon Notification warning"]
+  error:
+    when: "錯誤(『匯入失敗』『權限不足』『網路斷線』);action prop 可加重試"
+    world-class: ["Polaris Toast error", "Material Snackbar error", "Linear toast error"]
+sizes: {}
+benchmark:
+  - Radix Toast primitive: github.com/radix-ui/primitives/tree/main/packages/react/toast
+  - Polaris Toast: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Toast
+  - MUI Snackbar: github.com/mui/material-ui/tree/master/packages/mui-material/src/Snackbar
+  - Carbon Notification: github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Notification
+  - Ant Design notification: github.com/ant-design/ant-design/tree/master/components/notification
+---
+
+# Toast 設計原則
+
+## 定位
+
+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 結構。
+
+---
+
+## 何時用
+
+- **操作結果短暫回饋**：儲存成功、訊息已送出、已複製到剪貼簿、刪除失敗
+- **背景非同步動作完成**：檔案上傳完成、資料同步完成、通知已寄出
+- **需要「復原」按鈕的操作**：刪除後 4 秒內可 Undo（sonner action 模式）
+- **非關鍵資訊**：訊息即使使用者沒看到也不影響流程
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 關鍵錯誤或警告（使用者必須看到）| `Alert` + `Dialog` | Toast 會自動消失，關鍵訊息必須 persistent |
+| 欄位級驗證錯誤 | Field error message | Toast 是頁面級，欄位錯誤靠在欄位下方 |
+| 需要使用者確認的訊息（「是否繼續？」）| `Dialog` | Toast 非阻斷且自動消失，無法承載確認流程 |
+| 持久性系統狀態（方案過期、帳戶未驗證）| `Alert` | Toast 短暫，狀態需要 persistent |
+
+---
+
+## 與 Alert 的分界
+
+**Alert 是 canonical owner**——完整多維度比較詳見 `../Alert/alert.spec.md`「與 Toast / Notice 的分界」。
+
+簡述：**Toast** = 短暫浮動自動消失（操作回饋）；**Alert** = 持續顯示需 acknowledge（系統狀態）。判斷法「訊息重要到需要 acknowledge 嗎」在 Alert spec。
+
+---
+
+## 禁止事項
+
+- ❌ **不用 Toast 做 critical confirmation**：Toast 會自動消失，使用者可能沒看到就消失——關鍵訊息改用 Alert 或 Dialog
+- ❌ **不用 Toast 取代 error validation**：欄位錯誤訊息要貼近發生位置（FieldError），Toast 定位遠離錯誤欄位,使用者難對應到錯誤來源
+- ❌ **不同時彈 > 3 個 Toast**：同時多則 Toast 視覺雜訊重且無法閱讀，sonner 會自動 queue；應用層若批量觸發 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 已處理）
+
+---
+
+## Container 架構
+
+三層結構（所有 variant 統一）：
+
+1. **Shadow wrapper**：`rounded-lg`（8px）+ `elevation-200`（浮層陰影）。永遠在頁面 theme 解析。
+2. **Bg layer**：`bg-{color}`。有色相 variant 在頁面 theme 解析。
+3. **Theme layer**：`data-theme` + `text-foreground`。content token 在此 re-resolve。
+
+### 為什麼分三層
+
+陰影 token（`--elevation-200`）在 dark mode = 45% black，light mode = 4% black。如果陰影跟 `data-theme="dark"` 在同一層，light 頁面上的 dark toast 會有過重的 dark 陰影。分開讓陰影永遠用頁面 theme 的輕陰影。
+
+## Variant × Theme 策略
+
+| Variant | Bg | data-theme | 視覺 |
+|---|---|---|---|
+| neutral | `bg-surface-raised`（同層翻轉） | `{inverse}` | light 頁→暗底, dark 頁→亮底 |
+| success | `bg-surface-raised`（同層翻轉） | `{inverse}` | 同上 + 綠色 icon |
+| info | `bg-info`（outer） | `"dark"`（inner） | 藍底白字 |
+| warning | `bg-warning`（outer） | `"light"`（inner） | 黃底深字 |
+| error | `bg-error`（outer） | `"dark"`（inner） | 橘底白字 |
+
+neutral/success 的 bg + data-theme 在同一層，因為 `bg-surface-raised` 需要跟 data-theme 一起翻轉。
+
+## API
+
+```tsx
+toast({
+  variant: 'success',
+  title: '操作成功',
+  description: '變更已儲存至伺服器',
+  action: { label: '復原', onClick: handleUndo },
+  duration: 4000,
+})
+```
+
+- `title`（必填）：主要訊息
+- `description`（選填）：補充說明，自然換行
+- `action`（選填）：tertiary xs 按鈕
+- `duration`（選填）：自動關閉時間，預設 4000ms
+
+## 寬度（元件級常數）
+
+Toast 固定 **360px 寬**（見 `.tsx` 的 `w-[360px]`）——跨通知視覺一致，避免長短不一造成視覺跳動；同時限制單一通知橫向占據空間，不遮蔽過多頁面內容。
+
+對照世界級：Material Snackbar 固定 344px、Sonner default toast 固定寬度——**單一元件的 canonical 寬度屬於該元件自己的 design spec，不抽為跨元件 token**。Token 系統只管共享值（如 `--field-height-*`、`--layout-space-*`）；單一元件獨有的結構常數留在 component code + 本 spec。
+
+## 為何無 Inspector / SizeMatrix
+
+- **無 Inspector**:Toast 透過 `toast()` **函式觸發**,不是 JSX 元件,沒有可 inspect 的 prop 面板——應有的互動玩法是「按鈕按下 → toast 浮現」,已由 `Overview` 中的 Action buttons 覆蓋。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)。
+
+---
+
+## shadcn passthrough 例外說明
+
+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
+
+**sonner 已實作五件套內部**(Toaster Root 有 forwardRef / viewport DOM spread / 適當 a11y role=status/alert)。我們不再 wrap 一層,保持與 sonner 直接對應,避免 API 膨脹。
+
+若 consumer 需要程式化控制(`toast.dismiss(id)` / `toast.promise(...)`),使用 sonner 原生 API,Toast 元件層不重新暴露。
+
+---
+
+## 邊界案例
+
+- **Disabled(action button)**:Toast 本身為 ephemeral notification 無 disabled state(自動消失,不需禁用);若 `toast()` 傳入 `action` button(sonner ToastOptions),該 button 在 async 動作中 consumer 可 disable,視覺繼承 Button SSOT(`text-fg-disabled` + `cursor-not-allowed`)。
+- **Loading**:Sonner 提供 `toast.promise(promise, { loading, success, error })` API — loading 階段渲 spinner + `loadingText`,promise 成功 / 失敗自動切 success / error variant;本元件不需 wrap。
+- **Empty**:`toast()` 必傳 title(API contract);無 title-empty 場景。
+- **Icon-only**:`neutral` variant 不渲 status icon,layout 收斂為 `[title + description?]  [action?]  [dismiss X?]`。
+- **Dark mode / density**:走 Notice / Sonner 內部策略(見「Theme 策略」段),固定寬度 360px 跨 density 不變。
+
+---
+
+## 相關
+
+- `../Notice/notice.spec.md` — Toast 消費的 layout primitive（與 Alert 共用）
+- `../Alert/alert.spec.md` — 持久性通知（同一套視覺策略）
+- `../Dialog/dialog.spec.md` — 需要阻斷或確認的通知改用 Dialog
+- [sonner](https://sonner.emilkowal.ski/) — 浮動管理 library
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `sheet.spec.md`

package/src/components/Tooltip/tooltip.spec.md

@@ -0,0 +1,139 @@
+---
+component: Tooltip
+family: composite
+variants: {}
+sizes: {}
+traits:
+  - isOverlay
+benchmark:
+  - Radix Tooltip primitive: github.com/radix-ui/primitives/tree/main/packages/react/tooltip
+  - Ant Design Tooltip: github.com/ant-design/ant-design/tree/master/components/tooltip
+  - MUI Tooltip: github.com/mui/material-ui/tree/master/packages/mui-material/src/Tooltip
+  - Polaris Tooltip: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Tooltip
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Tooltip 設計原則
+
+## 定位
+
+Tooltip 是 hover 或 focus 時出現的短文字提示，用於補充畫面上未能清楚傳達的資訊。
+基於 Radix Tooltip（shadcn 包裝）+ 橋接 DS token。
+
+**Layout Family**：非上述 family — composite / multi-section（多區塊組合，自 own layout）。
+
+## 何時用
+
+Tooltip 的判斷標準是：**畫面上的資訊是否已經足夠讓使用者理解？**
+
+- **畫面不夠清楚 → 用 tooltip 補充。** 例如：icon-only 按鈕沒有文字 label，使用者需要 tooltip 才能確認這個 icon 代表什麼操作
+- **畫面已經清楚 → 不需要 tooltip。** 例如：按鈕已有完整的文字 label（「儲存」「刪除」），tooltip 重複同樣的文字沒有價值
+- **截斷文字 → 用 tooltip 顯示完整內容。** 但只有當文字實際被截斷時才顯示——tooltip 是補救機制，不是裝飾
+
+## 出現時機
+
+全產品統一一組時間參數，不因 tooltip 類型或位置而異——不一致的延遲會讓使用者無法建立穩定的操作預期。
+
+**Warm-up pattern（暖機模式）：**
+
+1. 使用者首次 hover 某個觸發器 → 等待初始延遲，確認是刻意停留而非滑鼠路過（NNGroup 研究：低於此閾值會導致隨意移動滑鼠時螢幕不停閃爍）
+2. Tooltip 出現後，使用者移到下一個觸發器 → 在掃描窗口期內，tooltip 即時切換，不再等待（toolbar 逐一掃描場景）
+3. 使用者離開所有觸發器超過掃描窗口期 → 系統冷卻，下次 hover 重新等待初始延遲
+
+這是一個行為的兩個階段，不是兩種不同的延遲。全域一個 `TooltipProvider` 統一控制，所有 tooltip（包括 Button icon-only 自動產生的）共享同一組參數。
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 內容需要互動（按鈕 / 連結 / 輸入框）| `HoverCard` | Tooltip 不可點擊，HoverCard 才支援互動元素 |
+| 需要長篇說明（多段文字 / 圖片）| `HoverCard` / 側邊 help panel | Tooltip 是一句話補充 |
+| 欄位驗證錯誤 | inline error message | Tooltip 需要 hover 才能看到，錯誤必須 persistent |
+| 必要資訊的唯一載體 | 直接顯示在畫面上 | Tooltip 觸控裝置無法觸發，關鍵資訊不能只靠 hover |
+| 按鈕已有完整文字 label | 不要加 tooltip | 重複同樣的文字沒有價值 |
+
+## 與 Button icon-only 的關係
+
+Button 的 `iconOnly` 模式已內建自動 tooltip（以 `aria-label` 驅動），開發者不需要額外包 `<Tooltip>`。只有在非 Button 元素需要 tooltip 時，才手動使用 Tooltip 元件。
+
+## 內容完整性
+
+Tooltip 是資訊的終點——tooltip 內不能再觸發 tooltip。內容必須完整呈現，不截斷、不省略。
+
+- Tag 在 tooltip 內不設 max-width，文字完整顯示
+- 多個 tag 自然換行（flex-wrap），tooltip 高度隨內容撐開
+- 不在 tooltip 內使用需要 hover 才能看到的元素
+
+## 子元素色彩
+
+Tooltip 底色是深色，子元素永遠套用 dark theme token（透過 `data-theme="dark"` wrapper）。元件放進 tooltip 自動適配深色背景，不需要特殊樣式。
+
+## Align 對齊
+
+**Tooltip 走「輕量浮層」例外**(見 `../Popover/popover.spec.md`「SSOT 適用範圍」)—— hover 觸發、純文字展示、寬度極窄(max 280px),Radix 預設 `center` 貼合指標即可。不強制對齊 structured overlay 的 trigger-position canonical。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+## Edge collision(避免貼 viewport 邊)
+
+**`collisionPadding` default = 8**(與 HoverCard 一致),Radix `avoidCollisions` 預設 true 會自動翻邊,但 padding 0 會讓 tooltip **貼齊 viewport 邊緣**(視覺上擠)。default 8 讓 tooltip 跟 viewport 邊保留最少 8px 呼吸距離。consumer 需自訂傳 prop 即可覆寫。
+
+世界級對照:Material Tooltip `margin: 14px` default / Polaris Tooltip 8-12px — 本 DS 選 8 對齊 HoverCard。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+## 最大寬度（元件級常數）
+
+Tooltip 最大寬度 **280px**（見 `.tsx` 的 `max-w-[280px]`）——超過換行。避免單條 tooltip 占據過大空間遮蔽內容，同時保證文字可完整呈現（見「內容完整性」節，tooltip 是資訊終點，不截斷）。
+
+對照世界級：Material tooltip 約 250–300px、Apple HIG tooltip 限制在可讀寬度——**單一元件的 canonical 寬度屬於該元件自己的 design spec，不抽為跨元件 token**。Token 系統只管共享值（如 `--field-height-*`、`--layout-space-*`）；單一元件獨有的結構常數留在 component code + 本 spec。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+## 禁止事項
+
+- ❌ 不要在已有完整 label 的按鈕上加 tooltip 重複同樣的文字
+- ❌ 不要在 tooltip 裡放互動元素——改用 HoverCard
+- ❌ 不要把 tooltip 當作必要資訊的唯一載體——tooltip 需要 hover 才能看到，觸控裝置無法觸發
+- ❌ 不要為個別 tooltip 設定不同的延遲時間——全產品統一一組參數
+- ❌ 不要在 tooltip 內截斷資訊——tooltip 是資訊終點，內容必須完整
+
+---
+
+## 為何無 ColorMatrix / SizeMatrix / StateBehavior
+
+Tooltip 是**單一職責 hover 提示 primitive**(一句話補充),刻意無變體:
+
+- **無 ColorMatrix**:Tooltip 固定一種視覺(dark surface + white text,跟頁面主題反轉),無 variant / severity / hue。若需要有色 hint,那是 Popover / HoverCard 的職責。Dark mode 自動由 inverse theme 處理。故無 color matrix。
+- **無 SizeMatrix**:Tooltip 無 size prop,尺寸由內容 + max-width 常數決定(本 spec「最大寬度」段)。不提供 sm/md/lg tier——短文字 hint 不需要尺寸變體。
+- **無 StateBehavior**:Tooltip 是 passive 出現 / 消失(hover / focus 觸發,見「出現時機」段),無 hover / selected / active / disabled 這類互動元件 state。開 / 關行為由 Radix primitive 處理,寫在 `Overview` 的 usage 說明已足夠。
+
+對應 anatomy story:保留 `Overview` + `Inspector`(delay / placement 互動試玩) + 元件特有 `PlacementReference`(12 種 side × align 對照)。
+
+---
+
+## 相關
+
+- `../HoverCard/hover-card.spec.md` — hover 觸發的可互動浮層（**Tooltip vs HoverCard 的分界 SSOT 在 HoverCard spec**「與 Tooltip 的分界」段落）
+- `../Button/button.spec.md` — `iconOnly` 模式自動產生 tooltip（由 aria-label 驅動）
+
+## A11y 預設
+
+**ARIA / Pattern**:繼承 Radix `tooltip` primitive a11y 預設(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/tooltip#accessibility)。
+
+**Keyboard 行為**:
+
+- Tab — focus trigger 時顯示
+- Esc — 關閉
+
+**Focus**:Radix primitive 自管 focus trap / restoration / visible ring(`outline: 2px solid var(--ring)` per design-system focus-visible canonical)。
+
+**驗證**: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。若要手動補充,寫在本節之前。
+
+- `coachmark.spec.md`
+- `name-card.spec.md`
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `motion.spec.md`