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

package/src/components/CircularProgress/circular-progress.spec.md

@@ -0,0 +1,268 @@
+---
+component: CircularProgress
+family: self-contained
+variants: {}
+sizes: {}
+traits:
+  - isMatrixHeavy
+benchmark:
+  - MUI CircularProgress: github.com/mui/material-ui/tree/master/packages/mui-material/src/CircularProgress
+  - Ant Design Progress: github.com/ant-design/ant-design/tree/master/components/progress
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# CircularProgress 設計原則
+
+**圓形進度指示(determinate + indeterminate 雙模式)**——整個設計系統 circular 形式進度的 SSOT。
+
+**Layout Family**:非 family — self-contained primitive(獨立視覺,無 slot 結構)。
+
+**實作基礎**:自繪 SVG(雙 circle:track + arc)+ Tailwind `animate-spin`(indeterminate 模式)。無 external primitive base。
+
+> 最薄的 circular progress primitive。`value` 有無切換兩態:無 value = indeterminate 旋轉 / 有 value = determinate arc + track。
+
+---
+
+## 定位 + 姊妹元件分界(SSOT)
+
+| 元件 | 型態 | 可量化? | 典型使用 |
+|------|------|---------|----------|
+| **`ProgressBar`** | linear **determinate** | ✅ 0–100 | 頁面級 / 表單步驟 / 上傳 bar / card 內大區塊進度 |
+| **`CircularProgress`**(本元件) | circular **兩態** | ✅ 有 value / ❌ 無 value | inline 小空間 / Button loading / Field loading / 單一 icon 位置 / cell 內進度 |
+
+**判斷法**:
+- 水平大區塊 / 頁面級 → **ProgressBar**
+- 小空間 / inline icon 位置 → **CircularProgress**(有 value 用 determinate / 無則 indeterminate)
+
+### 世界級流派選擇(為何 circular 兩態合一)
+
+查 6 家世界級 circular progress 命名策略:
+- **合一派**(一元件 determinate + indeterminate):Material `CircularProgress` / Chakra `CircularProgress`
+- **分離派**(2 元件):Ant(`Spin` + `Progress type=circle`) / Mantine(`Loader` + `RingProgress`)
+- **只有 indeterminate**:Polaris / Atlassian / Carbon
+- **混合**:Apple HIG(ActivityIndicator indeterminate / ProgressView determinate circular+linear 合)
+
+**本 DS 採合一派**(Material / Chakra),理由:
+1. **語義一致**:「CircularProgress」天然涵蓋兩態,不像「Spinner with value」語義拉扯
+2. **元件數少**:不拆 Spinner + CircularProgress 兩元件,consumer 只要記一個
+3. **視覺結構共用**:同一 SVG skeleton(`size` + strokeWidth + 雙 circle),`value` 有無只切換 dashoffset 計算 + animate-spin class,無 code 重複
+
+(2026-04-20 從「Spinner + CircularProgress 分離」改為本架構;`Spinner` 元件已廢除並遷至本元件。consumer 改 import `CircularProgress`。)
+
+---
+
+## 何時用
+
+- **Button / Inline Action 的 loading 狀態**:Button `loading` prop 內部渲染(無 value = indeterminate)
+- **Field loading 狀態**(Input / NumberInput / Combobox / Select):consumer 傳 `loading={true}` → 元件內部 readonly + endAction slot 自動塞 `<CircularProgress>`(見 `field-controls.spec.md`「Loading state」)
+- **Cell / row 局部進度**(cell 上傳中、cell async fetch 中):size 16-20 inline
+- **inline 可量化小進度**(如 file uploader list row 的上傳 % / 倒數計時):有 value
+- **全頁 / empty surface 載入**:`<Empty icon={<CircularProgress size={48}/>}/>` compose(Empty canonical 垂直堆疊,無需另造)
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 頁面級 / 表單級大區塊進度 | `ProgressBar`(linear) | CircularProgress 在大尺寸視覺比例不如 linear bar |
+| 骨架載入(list / card 初次 render) | `Skeleton` | Skeleton 保留內容形狀 |
+| 全頁 loading 版面 | `<Empty icon={<CircularProgress/>}/>` | 版面繼承 Empty 垂直堆疊 canonical |
+| 通知計數 / 狀態紅點 | `Badge`(dot 模式) | 語義完全不同 |
+
+---
+
+## API
+
+```tsx
+export interface CircularProgressProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /** 0-100;undefined → indeterminate(旋轉 partial arc) */
+  value?: number
+  /** 直徑 px,預設 24,≤ 64 建議 */
+  size?: number
+  /** 狀態色(與 ProgressBar 一致) */
+  status?: 'inProgress' | 'success' | 'error'
+  /** 視覺 label(inline,font-size inherit,color text-fg-muted) */
+  label?: string
+  /** Determinate 模式的 affix(indeterminate 忽略) */
+  affix?: 'value' | 'status-icon' | React.ReactNode
+  /** A11y label(指定後 shouldAnnounce=true) */
+  'aria-label'?: string
+}
+```
+
+### 尺寸策略:自由 `number`,跟 Avatar 同一套
+
+不用 `sm | md | lg` enum(跨度 16 → 64 太大)。
+
+#### Size inheritance table(consumer 傳入的 canonical 值)
+
+| Context | 建議 `size` | 來源 |
+|---------|-------------|------|
+| 獨立使用 | **24**(預設) | 不傳 |
+| Button startIcon loading | `iconSize`(16 / 20) | Button 內部程式化 `<CircularProgress size={iconSize}/>` |
+| Field endAction loading | `ICON_SIZE[size]`(16 / 16 / 20) | Input / Field 內部程式化(`loading` prop) |
+| 取代 Avatar | 與 Avatar size 相同 | Consumer 傳 |
+| Empty overlay 全頁 loading | **48** | Empty 範例與 story convention |
+| 大型 card 中央 | 32–48 | Consumer 判 |
+
+**程式化原則**:consumer wrapper(Button / Input `loading`)內部決定 size,consumer 不再傳;獨立場景(Empty / 自組 card)consumer 傳。
+
+### 最大尺寸建議(不設硬上限)
+
+不設 prop 上限(跟 Avatar 策略一致)。視覺建議 ≤ 64px。超過通常代表場景該改用 Empty 組合或動畫插圖。
+
+### Determinate 達 100% 的 canonical:**swap 為完成 state,不留 value=100**
+
+達 100% 時 consumer **必須 swap** 為完成狀態呈現,不保留 `<CircularProgress value={100}/>`:
+
+| 完成後呈現 | 場景 |
+|-----------|------|
+| ✓ 打勾 icon(`<CircleCheck/>` / `<Check/>`) | cell inline / 上傳列表 row |
+| 直接呈現該呈現的內容 | 資料載入完成 → 渲染實際 list / table / card |
+| 切到 `<Empty>` 或其他 state component | 全頁 overlay → 內容出現;或 empty state |
+| CircularProgress 直接消失 | 非同步操作完成,UI 回到預設態 |
+
+**世界級慣例**:Gmail / Dropbox / Google Drive 上傳完成即消失;iOS Activity Indicator 完成隱藏;Figma / Notion async fetch 完成切到實際內容。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+**為什麼不留 100%**:`CircularProgress` 語義是「進行中」,停在 100% 跟「完成」的語義衝突,使用者看到「滿的 circle」會困惑「還在跑嗎?」。
+
+### 不設 `status` prop — 完成 / 失敗由 consumer 端 swap
+
+世界級 DS(Material / Chakra / Ant / Polaris)**沒有**「success / error CircularProgress」variant——完成與失敗的語義應由 consumer 在業務邏輯上**替換 CircularProgress 為實際內容**(Check icon + label / 結果 / 錯誤訊息等),不讓 progress 指示器本身做狀態 morph(綠底空心 circle + check icon 並排是 anti-pattern)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+```tsx
+// ✅ canonical — consumer 端 swap
+{uploading
+  ? <CircularProgress />
+  : done
+  ? <><Check /> 已完成</>
+  : error
+  ? <><AlertCircle /> 失敗,重試</>
+  : null}
+
+// ❌ anti-pattern — 不存在的 API
+<CircularProgress status="success" />      // 本 DS 無此 prop
+<CircularProgress affix="status-icon" />   // 本 DS 無此選項
+```
+
+### Size canonical(一條規則)
+
+**若 CircularProgress 放在 field-height 相關容器內,`size` 對齊該容器的 icon 尺寸;否則預設 `24`。**
+
+| 情境 | 建議 size | 為什麼 |
+|------|----------|--------|
+| field-height 相關容器(Button loading / Input loading / DataTable cell / Field control loading 等) | 對齊容器的 iconSize(本 DS 全部是 `sm/md = 16 / lg = 20`) | 與容器內其他 icon 視覺同刻度,避免 row 內 icon 跳高低 |
+| 獨立使用 / 全頁 / Empty overlay / Coachmark media 等無 field-height 約束 | 預設 24(傳統 Material 標準)— 需要更大(例如 Empty 大圖)可 32 / 48 | 無參考尺寸時走 DS 預設,不憑感覺挑 | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+**實作保證**:
+- Button / Input / Field 等 **元件內部自動傳對的 size**(consumer 不用傳)— 來源:這些元件本來就知道自己的 `iconSize`(`field-controls.spec.md` 中 `sm/md=16, lg=20`)
+- DataTable cell 由 consumer 手寫 render,**consumer 傳 `16`(sm/md table) / `20`(lg table)** — 規則在 `data-table.spec.md` 十一之一
+- 獨立使用 CircularProgress 的元件 **預設走 24** — 已是 `<CircularProgress />` default
+
+世界級對照:Material / Ant / Carbon 的 inline loading 全部 16dp;Material 獨立使用標準 = 40dp(desktop)/ 24dp(compact)。本 DS 收斂成「inline 跟 context 走 16 或 20,獨立走 24」兩檔,不暴露更多 size 階。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+### 顏色策略:固定 `text-primary` + consumer 覆寫
+
+固定 `text-primary`(品牌語義色「正在處理」)。不隨狀態變色。
+
+| Consumer | className | 實際色彩 |
+|----------|-----------|---------|
+| 獨立 / 全頁 / Empty overlay / Input loading | 無(走預設) | `text-primary` |
+| Button `loading` 各 variant | `className="text-current"` | 繼承 button `text-on-emphasis` / `text-foreground` |
+
+Track 色鎖 `var(--secondary)`(= neutral-3,與 ProgressBar track 一致)。
+
+### Label 策略:font-size 繼承 + 色鎖 neutral-7
+
+- `label` 有值 → render `<span className="text-fg-muted">`,font-size **繼承 parent**(不設 text-size class,CSS inherit 天然處理)
+- 塞在元件內(Button / Field)時不用 label(元件本身已有文字);全頁 / Empty overlay 場景可開
+
+### A11y 策略
+
+| 模式 | role | aria 屬性 |
+|------|------|----------|
+| Determinate(`value` 有值) | `progressbar` | `aria-valuenow / aria-valuemin=0 / aria-valuemax=100` + optional `aria-label` |
+| Indeterminate + 有 aria-label / label | `status` | `aria-label={label ?? aria-label}` |
+| Indeterminate + 無 label | `aria-hidden=true` | 由父層 `aria-busy` 管理(Button 模式) |
+
+---
+
+## 視覺與幾何鐵律
+
+- **正方形不可妥協**:`style={{ width: size, height: size }}` 強制。本體絕不加 margin / padding
+- **SVG 雙 circle**:track(`var(--secondary)`) + arc(`currentColor`),stroke-linecap round,rotate -90deg 從 12 點起始
+- **strokeWidth 動態 scale**:`Math.max(2, Math.round(size / 10))` 維持跨尺寸視覺比例
+  - size 24 → stroke 2
+  - size 32 → stroke 3
+  - size 48 → stroke 5
+  - size 64 → stroke 6
+- **Indeterminate arc**:固定 25%(`INDETERMINATE_ARC_RATIO=0.25`),外層 `animate-spin` 旋轉整個 span(Material 流派)
+- **旋轉規則單純**:indeterminate → 轉;determinate → 不轉;沒有 status 條件分支,因為沒有 status。完成時 consumer 把整個 CircularProgress swap 成其他內容(Check icon / 結果 / Empty),不靠元件本身做 spin-stop 動畫
+- **`align-middle` 鎖死**(SVG 對齊 adjacent text x-height 中線):外層 span 本體帶 `align-middle`,避免在 inline-flex 容器內出現基線錯位。consumer 若在文字旁放 CircularProgress,**不需**自己加 `align-middle` 或 `leading-none`
+- **Determinate transition**:`transition-[stroke-dashoffset] duration-300`(value 變化時 smooth animation)
+
+---
+
+## Do / Don't
+
+✅ **Do**
+- 無進度資訊 → 不傳 value(indeterminate,替代舊 Spinner 用法)
+- 有進度資訊 → 傳 `value={N}`(determinate + track)
+- 跟 Button / Field loading 配合 → 走 `loading` prop,不自己 import
+- 全頁 loading → `<Empty icon={<CircularProgress size={48}/>}/>`,不手刻 overlay
+
+❌ **Don't**
+- 不要 inline `<Loader2 className="animate-spin" />` — 用 CircularProgress
+- 不要加 `color` / `variant` / `speed` / `thickness` prop — 單一職責
+- 不要在本元件外包 `absolute inset-0 flex items-center justify-center` — 用 Empty compose
+- 不要用 CircularProgress 表達裝飾效果 — 語意鎖「進度」,不轉其他
+
+---
+
+## 為何僅保留 Overview + 兩 consumer context stories
+
+CircularProgress 是**最薄的 circular progress primitive**,刻意避免多維度變體:
+
+- **無 Inspector**:variant 只有 value 有無 + status 三狀態(lifecycle),互動切換式 Inspector 可展的決策點少。`UsageInButton` / `UsageInline` 已覆蓋真實 consumer context
+- **ColorMatrix N/A(只繼承 Progress color token)**:本元件 color 完全來自 `text-current`(繼承 host)+ Progress token(track / fill),無 own variant × state 色彩組合可 matrix 對照。status(running/success/error)已在 `UsageInButton` / `UsageInline` 真實 context 演示,獨立 ColorMatrix story 會是冗餘
+- **SizeMatrix 透過 Inspector 即可展示 — 無 separate SizeMatrix story**:size 是自由 number(非 sm/md/lg tier),Inspector 的 size slider 即可展示 16 / 24 / 32 / 48 等常用值的行為差異,比靜態 matrix 更貼近消費情境
+- **無 StateBehavior**:無 hover / focus / active,唯一「狀態」是 value 變化(已在 Determinate story 動態演示)
+
+對應 anatomy story:`Overview` + `UsageInButton` + `UsageInline`。缺 canonical 5 多數項的 rationale 即本段。
+
+---
+
+## 邊界案例
+
+- **Disabled(consumer host)**:CircularProgress 本身**不擁有 disabled state**(色彩繼承 host 的 `text-current`)。當消費 host 為 Button loading + disabled 組合時,spinner 顏色自動跟 Button text color 弱化為 `text-fg-disabled`;不需 CircularProgress 端 prop。
+- **Loading(本即元件本質)**:本元件本質是 loading indicator;無需另外的 loading prop。indeterminate(無 `value`)= 旋轉動畫,determinate(有 `value`)= 弧長對應 0–100%。
+- **Empty / 0 progress**:`value=0` 在 determinate mode 渲空 track,符合「尚未開始」語意;若 0 + lifecycle status `success`,自動切 success token(`UsageInline` story 演示)。
+- **Dark mode**:走 Progress token + `text-current` 繼承,自動 adapt。
+- **Size 極端值**:size 為自由 number(非 sm/md/lg tier);size < 12 不建議(stroke width / icon overlap 失調),size > 96 建議改 ProgressBar(linear 在大尺寸更易讀)。
+
+---
+
+## 相關
+
+- **ProgressBar** — `components/ProgressBar/progress-bar.spec.md`(linear determinate 姊妹元件)
+- **Avatar 自由 size 策略** — `components/Avatar/avatar.tsx`(同 pattern 先例)
+- **Empty compose 全頁 loading** — `components/Empty/empty.spec.md`(icon slot 接 ReactElement)
+- **Field loading state** — `components/Field/field-controls.spec.md`「Loading state」
+- **Button loading prop** — `components/Button/button.tsx`(消費,使用 `text-current` 繼承)
+
+## 遷移記錄(2026-04-20)
+
+`Spinner` 元件已廢除並遷至本元件。Breaking change:
+- `import { Spinner } from '.../Spinner/spinner'` → `import { CircularProgress } from '.../CircularProgress/circular-progress'`
+- `<Spinner size={N}/>` → `<CircularProgress size={N}/>`(indeterminate 行為相同)
+- `<Spinner size={N} aria-label="..."/>` → `<CircularProgress size={N} aria-label="..."/>`
+- 新增能力:`<CircularProgress value={N}/>` 支援 determinate
+
+遷移理由:世界級命名對齊 Material / Chakra,支援 determinate 需求(user 2026-04-20 提出),元件數減少(廢除重複的 Spinner 名稱)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `badge.spec.md`
+- `skeleton.spec.md`

package/src/components/Coachmark/coachmark.spec.md

@@ -0,0 +1,230 @@
+---
+component: Coachmark
+family: composite
+traits:
+  - isOverlay
+variants: {}
+sizes: {}
+benchmark:
+  - Radix Popover primitive: github.com/radix-ui/primitives/tree/main/packages/react/popover
+  - Shepherd onboarding: github.com/shipshapecode/shepherd
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Coachmark 設計原則
+
+## 定位
+
+Coachmark 是**主動推送的功能介紹浮層**——anchor 到特定 UI 元素,帶 media + title + description + footer 按鈕列,用於首次功能介紹 / onboarding 多步導覽 / 新功能提示。
+
+**實作基礎**:Popover 的 composition pattern——完全消費 Popover 的定位、動畫、焦點管理、overlay-surface padding 系統,不自寫浮層邏輯。差別:(1) **Header 可選**(`kind="tips" | "new-features" | ReactNode`;single-step 常無 header、multi-step tour 建議帶 header 提示整體脈絡),(2) 有 **Media 區**(可選,頂部 full-width 圖 / 截圖 / illustration),(3) Footer 是 `justify-between`(左 step 計數 / 右 actions)而非 `justify-end`。
+
+**Layout Family**:非上述 family — composite / multi-section(Media / Body / Footer 多區塊組合)。
+
+**世界級對照**:Apple HIG「Coachmark」(Apple 命名原處)/ Material「Feature Discovery」/ Ant Design `<Tour>` / Shepherd.js / react-joyride / Intercom Product Tours。命名採 Apple HIG 詞彙(最早且最廣泛被理解的術語)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+---
+
+## 與 Popover 的關係
+
+Coachmark **就是** Popover 的 composition —— 不是競品。改 Popover 視覺(bg / border / shadow / radius / padding)Coachmark 自動跟進,不需雙邊同步。唯一 Coachmark 自己擁有的視覺決策:
+
+- **預設比 Popover 寬一階**:容納 media + 多行 description(主動推送內容量 > 篩選面板);具體寬度 class 見 `coachmark.tsx` cva
+- **`p-0 overflow-hidden`**:移除 PopoverContent 預設 padding,讓 Media 邊緣對齊圓角;Body / Footer 自己消費 overlay-surface padding token
+- **Footer `justify-between`**:step 計數(左)+ actions(右),對齊 Ant Tour / Intercom convention <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+SSOT 規則:**Coachmark 不重寫 Popover 的任何視覺 token**,只加自己結構層的差異。
+
+---
+
+## 與 Dialog 的分界
+
+**核心差別:是否阻斷使用者流程**。
+
+- **Coachmark**(non-modal 輔助):使用者可忽略、可 skip、可繼續原本的操作。onboarding 的精神是「幫忙介紹但不強迫」
+- **Dialog**(modal 阻斷):使用者必須處理(確認 / 取消 / 完成表單)才能繼續
+
+**判斷法**:「這個資訊不看會怎樣?」不看也能用 → Coachmark;不看就做不下去(破壞性動作、必要資訊輸入、多步表單)→ Dialog。
+
+**為什麼 onboarding 絕不用 Dialog**:強制彈窗打斷使用者自主探索的動線,心理上造成「又是 tutorial?跳過」的本能反彈。Coachmark 的 non-modal 特性讓使用者保持主控權,tour 反而更容易被完整看完。
+
+---
+
+## 何時用
+
+| 場景 | 範例 |
+|------|------|
+| 首次功能介紹 | 第一次使用 AI 助理功能時,anchor 到 AI 按鈕介紹「點這裡開始對話」 |
+| Onboarding 多步導覽 | Notion-style 3-step tour:建立 workspace → 邀請成員 → 建立第一個頁面 |
+| 版本更新 / What's new | 新 dashboard view 上線時提示「試試新的圖表模式」 |
+| 新功能發現 | Intercom-style feature discovery,anchor 到功能 icon 並說明價值 |
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 錯誤訊息 / 系統通知 | `Notice` / `Alert` / `Toast` | Coachmark 是主動推送「要不要試試」,不是事件回饋 |
+| 靜態 help text(hover 說明) | `Tooltip` | Tooltip 是被動查詢,Coachmark 是主動推送 |
+| 確認破壞性動作 | `Dialog` | Coachmark 可忽略,破壞性動作必須阻斷 |
+| 必要資訊輸入(表單 wizard) | `Dialog` + `Tabs` | 必填欄位不能讓使用者 skip |
+| 一般點擊觸發的浮層面板 | `Popover` | Coachmark 是「系統主動出現」,Popover 是使用者點擊才出現 |
+| Hover 觸發可互動浮層 | `HoverCard` | 觸發模型不同(Coachmark 由外部狀態控制) |
+
+---
+
+## Anatomy
+
+```
+┌────────────────────────────────┐
+│ Header(可選)                  │  ← SurfaceHeader padding;kind="tips"/"new-features"
+│   使用技巧 / 新功能介紹        │     text-caption uppercase text-fg-secondary
+├────────────────────────────────┤
+│ Media                          │  ← 可選,頂部 full-width,AspectRatio {16/9} default
+│ (image / illustration / video) │     邊緣對齊(overflow-hidden)
+├────────────────────────────────┤
+│ Body                           │  ← SurfaceBody padding(px-loose py-tight)
+│   Title                        │     text-body-lg font-medium
+│   Description                  │     text-body text-fg-secondary
+├────────────────────────────────┤
+│ Footer(justify-between)        │  ← SurfaceFooter padding(px-loose py-tight)
+│   2 of 3       [Skip] [Next]   │     左 step / 右 actions
+│   1 of 3  [Prev] [Next]        │     多步驟中段:無 Skip,加 Prev
+│                  [知道了]      │     單步驟:無 step / Prev / Skip,只 CTA
+└────────────────────────────────┘
+```
+
+---
+
+## Props 結構
+
+- `children` — trigger anchor(用 Popover asChild 定位)
+- `kind` — `'tips' | 'new-features' | ReactNode`;有值則渲染 Header(tour-level title)
+- `image` — ReactNode 媒體區;不傳則不渲染
+- `title` / `description` — 文字內容;兩個都不傳則整個 Body 不渲染
+- `step` — `{ current, total }`;有值則 footer 左側顯示 `2 of 3`
+- `onSkip` / `onNext` / `onPrev` — footer 按鈕 callback;無 callback 不渲染該按鈕
+- `isLastStep` — `true` 影響 CTA 文字(見下方「CTA 語義表」)
+- `doneLabel` — 單步驟 CTA 自訂文字(預設 `'知道了'`)
+- `open` / `onOpenChange` — controlled 控制(多步 tour 由 consumer 管理)
+- `side` / `align` / `sideOffset` — 定位,對齊 Popover props(**`align` 跟隨 trigger 位置:左 → start / 中 → center / 右 → end**,見 `popover.spec.md`「Align 對齊 canonical」SSOT)
+
+### CTA 語義表(世界級 canonical)
+
+| 情境 | `onPrev` | `isLastStep` | CTA 文字 | Skip 顯示? |
+|------|----------|--------------|----------|-----------|
+| **單步驟**(只 1 步) | — | `true` | `doneLabel ?? '知道了'` | 否(單步驟無 skip 意義) |
+| Multi 第一步 | — | `false` | `Next` | **是**(尚未投入進度) |
+| Multi 中間步 | ✓ | `false` | `Next` | 否(有 Prev 時不再 Skip) |
+| Multi 最後步 | ✓ | `true` | `Done` | 否 |
+
+**為什麼單步驟 CTA 不叫 "Next"**:Next 語義隱含「還有下一步」,single step 用 Next 使用者會困惑「後面還有嗎?」。Apple HIG / Intercom / Pendo 同樣慣例:single-step tip / onboarding toast 一律用「知道了 / Got it / Start」類完成詞。
+
+**為什麼有 Prev 時不顯示 Skip**:使用者按 Next 進到 step 2+ 代表已投入進度,此時同時出現「Prev(回上一步)」和「Skip(放棄全部)」語義衝突。Linear / Shepherd.js / Pendo tour 都在第 2 步後隱藏 Skip;想退出的使用者按 Esc / 關閉圖示即可(Radix 預設 Esc = dismiss)。
+
+---
+
+## Media 區規則
+
+- **尺寸**:固定 `aspect-video`(16:9),確保不同 tour 步驟視覺一致,consumer 不需自己算高度
+- **背景**:預設 `bg-muted`(當內容是 illustration 或透明 PNG 時有底色)
+- **邊緣**:`overflow-hidden` + `rounded-t-lg` 讓媒體切齊浮層圓角
+- **支援內容**:image / video / SVG illustration / animated GIF / Lottie
+- **禁止**:不放互動元件(按鈕 / 輸入框)——media 純視覺說明,互動一律走 footer
+
+---
+
+## Multi-step Tour 模式
+
+**Coachmark 本身不管理 step state**——consumer 自己管理 `currentStep` + 每步 anchor element:
+
+```tsx
+const [step, setStep] = useState(0)
+const steps = [
+  { anchorRef: workspaceBtnRef, title: '建立 workspace', ... },
+  { anchorRef: inviteBtnRef, title: '邀請成員', ... },
+  { anchorRef: projectBtnRef, title: '建立第一個專案', ... },
+]
+// 每步渲染一個 Coachmark,anchor 到對應元素
+```
+
+**設計建議**:
+- **≤ 5 步**——超過使用者疲勞,改用靜態 onboarding 頁面
+- **Skip 只在第一步提供**——進到 step 2+ 後 Skip 自動隱藏(canonical,見上方「CTA 語義表」);想退出走 Esc / header Close 按鈕
+- **最後一步 `isLastStep`**——Next → Done 語意切換,讓使用者知道「這是最後一步」
+- **每步 anchor 到對應 feature**——不 anchor 或 anchor 到無關元素 = 失去「教 X 怎麼用」的精準性
+- **Multi-step 建議傳 `kind="tips"` 或 `"new-features"`**——header 讓使用者一眼看出 tour 性質 / 何時結束的預期
+
+---
+
+## Footer 按鈕順序
+
+Previous(可選)→ Skip(可選)→ Next / Done。對齊 Ant Tour / Intercom convention: <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+- **Previous 最左**——回到上一步(負方向,視覺權重低)
+- **Skip 中間**——exit escape hatch,tertiary 不搶焦點;**僅第一步顯示**(見 CTA 語義表)
+- **Next / Done 最右**——推進主動線(正方向,primary 視覺權重高);**不強制 autoFocus** — 讓 Radix 預設行為接管(通常 focus 第一個 focusable),避免使用者還在讀 body 時按 Enter 誤推進
+
+第 1 步通常無 Previous;最後步 Next 改 Done(由 `isLastStep` 控制)。單步驟 CTA 改 `'知道了'`。
+
+---
+
+## 視覺 Token
+
+| 層 | Token | 說明 |
+|----|-------|------|
+| 浮層外殼 | 繼承 Popover(`bg-surface-raised` / `border-border` / `rounded-lg` / `--elevation-200`) | 改 Popover 自動跟進 |
+| Media 背景 | `bg-muted` | illustration / 透明 PNG 底色 |
+| Title | `text-body-lg font-medium text-foreground` | 比 Popover header 輕(Coachmark 無 header 分隔線) |
+| Description | `text-body text-fg-secondary` | 主說明文字 |
+| Step 計數 | `text-caption text-fg-secondary tabular-nums` | 數字等寬,切換步驟不跳動 |
+| Body padding | `px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]` | overlay-surface SSOT(PopoverBody) |
+| Footer padding | 同上 | overlay-surface SSOT(PopoverFooter) |
+| Width | 比 Popover 預設寬一階(固定,具體 class 見 `coachmark.tsx`) | 固定;consumer 可 className 覆寫 |
+
+---
+
+## 禁止事項
+
+- ❌ **不用 Coachmark 做錯誤提示**——錯誤是系統回饋使用者動作的結果,用 `Notice` / `Alert` / `Toast`。Coachmark 是主動推送教學,語意相反
+- ❌ **不用 Coachmark 做確認框**——確認破壞性動作必須阻斷流程,改用 `Dialog`
+- ❌ **Media 區不放互動元件**——按鈕 / 輸入 / checkbox 一律走 footer。Media 是視覺說明不是互動區
+- ❌ **Description 不寫超過 3 行**——Coachmark 是快速說明,超過 3 行改用 Dialog + 完整 body 或連結到說明文件
+- ❌ **不強迫完成 tour**——永遠提供退出機制(Esc / header Close / 第一步 Skip)。沒有退出的 onboarding 讓使用者感到被綁架,反而降低完成率
+- ❌ **單步驟 CTA 不叫 "Next"**——沒有下一步就不用 Next 字眼,用 `'知道了' / 'Got it' / 'Start'`
+- ❌ **有 Prev 時不同時顯示 Skip**——使用者投入進度後兩個退出路徑衝突(見 CTA 語義表)
+- ❌ **不自包視覺 token**——bg / shadow / radius / padding 一律繼承 Popover,改視覺就改 Popover
+- ❌ **不在 Coachmark 內放 nested Popover / Dialog**——層級混亂焦點崩壞,複雜互動結束 tour 後再開
+
+---
+
+## A11y 預設
+
+- **焦點管理**:由 Popover(Radix)處理——開啟移焦點進 content,關閉 return to trigger
+- **Esc 關閉**:預設啟用(= Skip 行為)——user 按 Esc 等同 skip,尊重退出意願
+- **ARIA**:trigger 自動 `aria-expanded` / `aria-controls`,content `role="dialog"`(Radix 預設)
+- **Step 計數 tabular-nums**:螢幕閱讀器讀「2 of 3」語意清楚
+
+---
+
+## 邊界狀態
+
+disabled / density 繼承 Popover(density 鎖 md,見 `../Popover/popover.spec.md`);empty(title + description 都不傳)則 Body 不渲染(已於「Props 結構」規定);loading 由 consumer 決定。
+
+---
+
+## 相關
+
+- `../Popover/popover.spec.md` — Coachmark 的實作基礎,所有浮層視覺 SSOT
+- `../Dialog/dialog.spec.md` — modal 阻斷浮層,與 Coachmark non-modal 對立
+- `../../patterns/overlay-surface/overlay-surface.spec.md` — Body / Footer padding SSOT(經 Popover 消費)
+- `../Tooltip/tooltip.spec.md` — hover 觸發純文字提示
+- `../HoverCard/hover-card.spec.md` — hover 觸發互動浮層
+- `../Notice/notice.spec.md` — 系統通知 / 錯誤訊息
+- Apple HIG Coachmarks / Ant Design `<Tour>` / Shepherd.js — 世界級對照 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `aspect-ratio.spec.md`