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

package/src/components/Coachmark/coachmark.principles.stories.tsx

@@ -0,0 +1,355 @@
+// @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.
+// @principles-rationale: UsageGuidance merges WhenToUse + WhenNotToUse + Vs*Rule into single 使用指引 story per refactor task (2026-04-26)
+// @anatomy-exempt: Dialog footer Cancel/Delete buttons are action cancel (not overlay dismiss); preserved verbatim from pre-refactor structure
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Bot, Sparkles, Users, FolderPlus, Filter, Trash2, AlertCircle } from 'lucide-react'
+import { Coachmark } from './coachmark'
+import { MediaGradient } from './coachmark-story-helpers'
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverBody,
+  PopoverHeader,
+  PopoverTitle,
+} from '@/design-system/components/Popover/popover'
+import {
+  Dialog,
+  DialogTrigger,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogBody,
+  DialogFooter,
+} from '@/design-system/components/Dialog/dialog'
+import { Button } from '@/design-system/components/Button/button'
+import { Checkbox } from '@/design-system/components/Checkbox/checkbox'
+import { CheckboxGroup } from '@/design-system/components/Checkbox/checkbox-group'
+
+const meta: Meta = {
+  title: 'Design System/Components/Coachmark/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const Rule = ({
+  title, note, children,
+}: {
+  title: string; note?: string; children: React.ReactNode
+}) => (
+  <div className="mb-14">
+    <h3 className="text-body font-bold text-foreground mb-1">{title}</h3>
+    {note && <p className="text-caption text-fg-muted mb-5 max-w-[720px] leading-relaxed">{note}</p>}
+    <div className="flex flex-wrap gap-3 items-start">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p className={`text-footnote leading-normal ${warn ? 'text-error font-medium' : 'text-fg-muted'}`}>{children}</p>
+)
+
+const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <section className="mb-12">
+    <h2 className="text-heading-3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
+    {children}
+  </section>
+)
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div>
+      <Section title="何時用">
+        <div className="prose prose-sm max-w-prose mb-8">
+          <p>適合 Coachmark 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+          <ul className="space-y-1">
+            <li><LinkTo kind="Design System/Components/Coachmark/展示" name="單步驟新功能介紹"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">首次推出 AI 助理時 anchor 到入口按鈕介紹(單步驟)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/Coachmark/展示" name="多步 新手導覽"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">新用戶首登的三步功能導覽(多步 Onboarding)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/Coachmark/展示" name="多步提示"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">進階快捷鍵的漸進式提示(多步 Tips)</span></LinkTo></li>
+          </ul>
+          <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方 vs 近親 段)。</p>
+        </div>
+      </Section>
+
+      <Section title="何時不用 + 替代方案">
+        <Rule
+          title="❌ 不用 Coachmark 做錯誤提示"
+          note="錯誤訊息是使用者動作的回饋(表單驗證失敗、API 錯誤、權限不足)— 應該用 Notice / Alert / Toast 呈現事件。Coachmark 是主動推送教學,語意完全相反"
+        >
+          <div className="flex items-center gap-2 p-3 border border-error/30 bg-error/5 rounded-md text-caption">
+            <AlertCircle className="w-4 h-4 text-error" />
+            <span className="text-foreground">這是錯誤訊息的樣子 — 應該用 Notice / Alert / Toast,不是 Coachmark</span>
+          </div>
+          <Label warn>錯誤 → Notice / Alert / Toast;Coachmark 只用於主動推送教學</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不用 Coachmark 做確認框"
+          note="確認破壞性動作必須阻斷流程(Dialog)。Coachmark 是 non-modal,使用者可忽略 — 讓破壞性動作變成「可忽略」等於沒確認"
+        >
+          <Label warn>刪除 / 取消訂閱 / 重置資料 → Dialog(必須阻斷),不用 Coachmark</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不強迫完成 tour(拿掉退出機制)"
+          note="使用者的本能是「我想自己試試」。沒退出 = 綁架,使用者找關閉方式或直接關閉整個頁面。永遠提供退出機制(第一步 Skip;step 2+ 走 Esc / header Close,有 Prev 時 Skip 自動隱藏,見 CTA 語義表)反而提升完成率 — 信任使用者會選擇"
+        >
+          <Label warn>❌ 拿掉所有退出路徑(無 Skip / Esc / header Close)— 使用者 frustration 增加,產品印象變差</Label>
+        </Rule>
+
+        <Rule
+          title="❌ Description 塞超過 3 行"
+          note="Coachmark 是快速提示不是完整教學。長文案使用者不讀,反而浪費了「主動彈出」的機會。長內容:拆多步 / 改 Dialog / 連結到文件"
+        >
+          <Label warn>❌ 5+ 行 description — 使用者掃一眼就點 Skip</Label>
+          <Label>✅ 2-3 行精準說明,需要深入 → 「了解更多」連結到 help doc</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 在 Coachmark 內放 nested Popover / Dialog"
+          note="浮層嵌套浮層 = 層級混亂 + 焦點管理崩壞 + Esc 不知道關哪個。複雜互動結束 tour 後再開啟;tour 的角色是「指向功能」不是「讓使用者在 tour 內完成任務」"
+        >
+          <Label warn>❌ Coachmark 內放 Popover / Dialog — 焦點管理崩壞</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 自包視覺 token(bg / shadow / radius)"
+          note="Coachmark 是 Popover 的 composition — 浮層視覺完全繼承 Popover。自己寫 bg-* / shadow-* 會讓 Coachmark 和其他浮層漂移,改 Popover 視覺時 Coachmark 不跟進"
+        >
+          <Label warn>❌ 在 Coachmark 外殼加 className=&quot;bg-*&quot; / shadow-*;視覺改動一律改 Popover</Label>
+        </Rule>
+      </Section>
+
+      <Section title="vs 近親元件">
+        <Rule
+          title="Popover — 使用者主動點擊才出現的互動面板"
+          note="filter、設定、快速切換等補充 UI。使用者知道自己要什麼、主動點擊 trigger。典型案例:Jira filter、Linear view settings、Notion 頁面設定"
+        >
+          <Popover>
+            <PopoverTrigger asChild>
+              <Button variant="tertiary" startIcon={Filter}>依狀態篩選</Button>
+            </PopoverTrigger>
+            <PopoverContent align="start">
+              <PopoverHeader><PopoverTitle>依狀態篩選</PopoverTitle></PopoverHeader>
+              <PopoverBody>
+                <CheckboxGroup>
+                  <Checkbox defaultChecked label="進行中" />
+                  <Checkbox label="已完成" />
+                </CheckboxGroup>
+              </PopoverBody>
+            </PopoverContent>
+          </Popover>
+          <Label>↑ 使用者主動點擊 trigger,面板才出現——這是 Popover 的觸發模型</Label>
+        </Rule>
+
+        <Rule
+          title="Coachmark — 系統主動推送的功能介紹,anchor 到某個 UI 元素"
+          note="使用者不知道新功能存在、不會主動點擊。系統判斷時機(首次進入 / 新版上線)主動出現 Coachmark,anchor 到要介紹的 feature 上。典型案例:Intercom feature discovery、Linear onboarding tour、Slack 新功能提示"
+        >
+          <Coachmark
+            open
+            image={<MediaGradient from="var(--color-indigo-6)" to="var(--color-purple-6)" icon={Bot} label="AI 助理" />}
+            title="試試新的 AI 助理"
+            description="在任何文件中按下 AI 按鈕,讓 Claude 幫你摘要、翻譯或改寫內容。"
+            onSkip={() => {}}
+            onNext={() => {}}
+            side="bottom"
+            align="start"
+          >
+            <Button variant="primary" startIcon={Bot}>AI 助理</Button>
+          </Coachmark>
+          <Label>↑ 系統主動出現,使用者不需事先知道有這個功能</Label>
+        </Rule>
+
+        <Rule
+          title="Dialog — modal 阻斷,使用者必須處理才能繼續"
+          note="破壞性動作(刪除)、必填表單、重要決策用 Dialog。Overlay 強制聚焦,使用者不能忽略,必須完成或取消。Coachmark 是 non-modal 輔助,使用者可忽略繼續主流程"
+        >
+          <Dialog>
+            <DialogTrigger asChild>
+              <Button variant="primary" danger startIcon={Trash2}>永久刪除專案</Button>
+            </DialogTrigger>
+            <DialogContent autoHeight maxWidth="440px">
+              <DialogHeader><DialogTitle>確定要永久刪除此專案?</DialogTitle></DialogHeader>
+              <DialogBody><p className="text-body">此動作無法復原,所有相關任務、評論、附件都會一併刪除。</p></DialogBody>
+              <DialogFooter>
+                <Button variant="tertiary">取消</Button>
+                <Button variant="primary" danger>永久刪除</Button>
+              </DialogFooter>
+            </DialogContent>
+          </Dialog>
+          <Label>↑ 破壞性決策必須完整處理,不能讓使用者點旁邊跳過</Label>
+        </Rule>
+
+        <Rule
+          title="判準 — 問「不看這個資訊會怎樣?」"
+          note="不看也能用 → Coachmark(介紹 / 提示 / onboarding)。不看就做不下去(破壞性動作、必要資訊輸入、多步表單)→ Dialog。視覺上 Coachmark 共用 overlay-surface(bg / border / shadow / radius 完全繼承 Popover),差別僅:觸發模型(主動 vs 被動)+ 結構(Coachmark Header 可選 kind / 有 Media / Footer 是 justify-between)"
+        >
+          <Label>Coachmark:新功能介紹、onboarding tour、版本更新提示</Label>
+          <Label>Dialog:刪除確認、建立 project 表單、付款資訊輸入、多步 wizard</Label>
+        </Rule>
+      </Section>
+    </div>
+  ),
+}
+
+export const MultiStepBestPracticesRule: Story = {
+  name: '多步導覽最佳實踐',
+  render: () => (
+    <div>
+      <Rule
+        title="每步 anchor 到對應 feature"
+        note="Coachmark 的核心價值是「在 UI 元素旁邊介紹它」。anchor 到無關位置 = 失去精準性,變成一般 onboarding modal。使用者看完要能「記得這個功能在畫面的哪裡」"
+      >
+        <Coachmark
+          open
+          image={<MediaGradient from="var(--color-yellow-6)" to="var(--color-deep-orange-6)" icon={Users} label="團隊" />}
+          title="邀請成員"
+          description="輸入 email 寄送邀請,新成員自動加入這個 Workspace。"
+          step={{ current: 2, total: 3 }}
+          onPrev={() => {}}
+          onSkip={() => {}}
+          onNext={() => {}}
+          side="bottom"
+          align="start"
+        >
+          <Button variant="tertiary" size="sm" startIcon={Users}>邀請成員</Button>
+        </Coachmark>
+        <Label>↑ Coachmark anchor 到「邀請成員」按鈕,使用者看完就知道去哪找</Label>
+      </Rule>
+
+      <Rule
+        title="≤ 5 步 — 超過使用者疲勞"
+        note="onboarding 的黃金比例是 3 步(Linear / Notion / Figma 都是 3 步)。超過 5 步使用者流失率大幅上升。內容多就拆多次 tour(首次 / 進階 / 專家)而非一次塞完"
+      >
+        <Label>✅ 3 步:建立 workspace → 邀請成員 → 建立專案(Notion)</Label>
+        <Label>✅ 4 步:選模板 → 命名 → 邀協作 → 開始編輯(Figma)</Label>
+        <Label warn>❌ 8+ 步 — 使用者 Skip 率 &gt; 60%</Label>
+      </Rule>
+
+      <Rule
+        title="永遠提供退出機制 — 尊重退出意願"
+        note="沒退出機制的 onboarding = 綁架使用者。使用者的本能是「我想自己試試」,強迫看完反而留下負面印象。退出機制是對自主權的尊重,真正有用的 tour 使用者會主動看完"
+      >
+        <Label warn>❌ 完全拿掉退出路徑(連 Esc / header Close 都禁用)— user 會直接離開產品</Label>
+        <Label>✅ 第一步提供 Skip(tertiary 不搶焦點);step 2+ 退出走 Esc / header Close(有 onPrev 時 Skip 自動隱藏,見 CTA 語義表)</Label>
+      </Rule>
+
+      <Rule
+        title="最後一步 isLastStep = Next 變 Done"
+        note="語意切換告訴使用者「這是最後一步」。如果最後步仍寫 Next,使用者不知道 tour 是否結束,體驗斷裂。Done 的語意收斂明確,讓使用者知道「我完成了」"
+      >
+        <div className="flex gap-6">
+          <Coachmark
+            open
+            image={<MediaGradient from="var(--color-green-6)" to="var(--color-green-7)" icon={Sparkles} label="完成" />}
+            title="建立你的第一個專案"
+            description="專案用來組織相關的任務、文件和討論。"
+            step={{ current: 3, total: 3 }}
+            isLastStep
+            onPrev={() => {}}
+            onSkip={() => {}}
+            onNext={() => {}}
+            side="bottom"
+            align="start"
+          >
+            <Button variant="primary" size="sm" startIcon={Sparkles}>建立專案</Button>
+          </Coachmark>
+        </div>
+        <Label>↑ 最後步 Next 文字 → Done,使用者知道「完成了」</Label>
+      </Rule>
+
+      <Rule
+        title="Footer 順序 — Previous / Skip / Next"
+        note="對齊 Ant Tour / Intercom convention 的左→右位置順序:Previous 最左(回退,視覺權重低)、Skip 中間(退出,tertiary)、Next 最右(推進,primary)。此為各按鈕『出現時』的排列位置,非三鍵同時 render — Skip 僅第一步顯示、Previous 第 2+ 步顯示,兩者永不共存(見 CTA 語義表)"
+      >
+        <Label>Previous 第 2+ 步才出現;第 1 步只有 Skip / Next</Label>
+      </Rule>
+
+      <Rule
+        title="non-modal 設計尊重使用者自主探索"
+        note="onboarding 的精神是「幫忙介紹但不強迫」。使用者點 Skip / 按 Esc / 點擊別處都能關閉,不影響主流程。把 onboarding 包在 Dialog 裡 — 使用者第一反應是找 X 關掉,根本沒讀內容"
+      >
+        <Coachmark
+          open
+          image={<MediaGradient from="var(--color-blue-6)" to="var(--color-cyan-6)" icon={FolderPlus} label="Workspace" />}
+          title="建立你的第一個 Workspace"
+          description="Workspace 是團隊協作的主要空間,所有專案、文件、成員都在這裡集中管理。"
+          step={{ current: 1, total: 3 }}
+          onSkip={() => {}}
+          onNext={() => {}}
+          side="bottom"
+          align="start"
+        >
+          <Button variant="primary" startIcon={FolderPlus}>建立 Workspace</Button>
+        </Coachmark>
+        <Label>↑ 使用者可按 Skip 退出 tour,繼續自己探索 — 不強迫完成</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const MediaContentRule: Story = {
+  name: 'Media 內容原則',
+  render: () => (
+    <div>
+      <Rule
+        title="Media = 純視覺說明,幫助理解功能價值"
+        note="最佳內容:(1) Illustration / 概念圖(抽象功能最適合)、(2) Screenshot 功能畫面、(3) Animated GIF / Lottie 示範操作。目的是讓使用者「一眼看懂這個功能在做什麼」"
+      >
+        <Coachmark
+          open
+          image={<MediaGradient from="var(--color-indigo-6)" to="var(--color-purple-6)" icon={Bot} label="AI Illustration" />}
+          title="AI 助理"
+          description="illustration 傳達概念,比純文字更快被理解"
+          onNext={() => {}}
+          side="bottom"
+          align="start"
+        >
+          <Button variant="primary" size="sm">Anchor</Button>
+        </Coachmark>
+        <Label>↑ Illustration 適合抽象功能(AI / 協作 / 自動化)</Label>
+      </Rule>
+
+      <Rule
+        title="❌ Media 區不放互動元件"
+        note="按鈕 / 輸入 / checkbox 一律走 footer。Media 是「看」的區塊不是「做」的區塊。放互動元素會讓使用者搞不清楚「這個按鈕是示範還是真的能點」,破壞 Coachmark 的教學角色"
+      >
+        <Label warn>❌ Media 區放 &lt;Button onClick=...&gt; — 使用者分不清示範 vs 實際操作</Label>
+        <Label>✅ Media 顯示 static screenshot / illustration,互動一律透過 footer 的 Next 推進</Label>
+      </Rule>
+
+      <Rule
+        title="Description 不超過 3 行"
+        note="Coachmark 是快速說明不是完整教學。超過 3 行使用者沒耐心讀,體驗反而變差。需要詳細說明:(a) 連結到 help doc,(b) 改用 Dialog + scrollable body,(c) 拆成多步 tour"
+      >
+        <Coachmark
+          open
+          image={<MediaGradient from="var(--color-indigo-6)" to="var(--color-purple-6)" icon={Sparkles} label="簡潔" />}
+          title="簡潔的 description"
+          description="兩行說明足以傳達核心價值 — 使用者能快速掃完並理解功能用途。"
+          onNext={() => {}}
+          side="bottom"
+          align="start"
+        >
+          <Button variant="tertiary" size="sm">Anchor</Button>
+        </Coachmark>
+        <Label>↑ 2 行精準說明,不超過 3 行</Label>
+      </Rule>
+
+      <Rule
+        title="同一段 tour 維持一致比例 — 視覺節奏穩定"
+        note="media 比例由 mediaRatio 控制(預設 16:9)。同一段 tour 各步驟用同一個比例,確保視覺節奏一致 — 使用者看第二步不會因為 media 變高/變矮而分心。需要時 consumer 可傳 mediaRatio(4/3 / 1/1 / 3/4)覆寫"
+      >
+        <Label>預設 16:9;一段 tour 內各步驟沿用同一比例,consumer 準備素材時遵守該比例</Label>
+      </Rule>
+    </div>
+  ),
+}

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

@@ -0,0 +1,238 @@
+---
+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(主動推送內容量 > 篩選面板);固定單一寬度、無 size variant,具體寬度值見 `coachmark.tsx`
+- **外殼移除預設 padding 並裁切圓角**:讓 Media 邊緣貼齊外殼圓角;Body / Footer 各自消費 overlay-surface padding token(實作見 `coachmark.tsx`)
+- **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 反而更容易被完整看完。
+
+**常見誤解**:「必須完成才能繼續用產品」的強制流程 ≠ Coachmark scope — 強制完成 = 阻斷 = Dialog(Coachmark 永遠可退出,見禁止事項「不強迫完成 tour」);hover 查詢式說明也 ≠ Coachmark — 那是 Tooltip 的被動模型(見「何時不用」)。
+
+---
+
+## 何時用
+
+| 場景 | 範例 |
+|------|------|
+| 首次功能介紹 | 第一次使用 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(可選)                  │  ← kind="tips"/"new-features";tour-level title
+│   使用技巧 / 新功能介紹        │
+├────────────────────────────────┤
+│ Media                          │  ← 可選,頂部 full-width,AspectRatio 鎖比例(預設 16:9)
+│ (image / illustration / video) │     邊緣貼齊外殼圓角
+├────────────────────────────────┤
+│ Body                           │  ← Title + Description(token 見「視覺 Token」表)
+│   Title                        │
+│   Description                  │
+├────────────────────────────────┤
+│ Footer(justify-between)        │  ← 左 step 計數 / 右 actions
+│   1 of 3       [Skip] [Next]   │     多步驟第一步:有 Skip,無 Prev
+│   2 of 3  [Prev] [Next]        │     多步驟中段:有 Prev,Skip 自動隱藏
+│                  [知道了]      │     單步驟:無 step / Prev / Skip,只 CTA
+└────────────────────────────────┘
+```
+
+---
+
+## Props 結構
+
+- `children` — trigger anchor(用 Popover asChild 定位)
+- `kind` — `'tips' | 'new-features' | ReactNode`;有值則渲染 Header(tour-level title)
+- `image` — ReactNode 媒體區;不傳則不渲染
+- `mediaRatio` — Media 長寬比(預設 `16/9`,見「Media 區規則」)
+- `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 區規則
+
+- **比例**:預設 16:9(`mediaRatio` prop 預設 `16/9`),由 `AspectRatio` 鎖長寬比 — 同一段 tour 各步驟維持一致比例,consumer 不需自己算高度。需要時 consumer 可傳 `mediaRatio`(如 `4/3` 產品截圖 / `1/1` 方圖 / `3/4` 直式)覆寫
+- **背景**:預設 `bg-muted`(當內容是 illustration 或透明 PNG 時有底色)
+- **邊緣**:圓角切齊靠外殼裁切(見「與 Popover 的關係」)——media 不自帶圓角
+- **支援內容**: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 視覺權重高);**Coachmark 抑制開啟時的自動 focus**(`onOpenAutoFocus` preventDefault,連 Radix 預設會 focus 的第一個 focusable 也一併抑制),避免使用者還在讀 body 時按 Enter 誤推進;想推進者自行 tab 到 CTA 再 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-body text-fg-secondary tabular-nums` | 跟 body 內文同字體;數字等寬,切換步驟不跳動 |
+| 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 讓使用者感到被綁架,反而降低完成率。註:header Close 僅在傳 `kind`(有 header)時才 render;無 `kind` 的 multi-step tour 第 2+ 步退出靠 Esc(永遠可用),multi-step 務必傳 `kind` 以提供 header Close 退出入口
+- ❌ **單步驟 CTA 不叫 "Next"**——沒有下一步就不用 Next 字眼,用 `'知道了' / 'Got it' / 'Start'`
+- ❌ **有 Prev 時不同時顯示 Skip**——使用者投入進度後兩個退出路徑衝突(見 CTA 語義表)
+- ❌ **不自包視覺 token**——bg / shadow / radius / padding 一律繼承 Popover,改視覺就改 Popover
+- ❌ **不在 Coachmark 內放 nested Popover / Dialog**——層級混亂焦點崩壞,複雜互動結束 tour 後再開
+
+---
+
+## A11y 預設
+
+- **焦點管理**:Coachmark **刻意抑制開啟時的自動 focus**(`onOpenAutoFocus` preventDefault),焦點停在 trigger——避免使用者還在讀 body 時 CTA 被 auto-focus 偷觸發(按 Enter 誤推進);想推進者自行 tab 到 CTA。關閉時焦點 return to trigger(Radix 預設 `onCloseAutoFocus`,未 override)
+- **Esc 關閉**:預設啟用——user 按 Esc 透過 Radix `onOpenChange` 關閉浮層(效果等同退出),**不觸發 `onSkip` callback**(Esc 是「關閉浮層」非「明確 skip」;若需區分 Esc-退出 vs Skip-按鈕 的追蹤事件,consumer 在 Skip 按鈕的 `onSkip` 處理)
+- **ARIA**:trigger 自動 `aria-expanded` / `aria-controls`,content `role="dialog"`(Radix 預設)
+- **Step 計數 tabular-nums**:螢幕閱讀器讀「2 of 3」語意清楚
+
+---
+
+## 邊界狀態
+
+disabled / layout-space 繼承 Popover(鎖 `data-layout-space="md"` 保持 header py-tight 精簡;ui-size / 控件大小繼承 page density),SSOT 見 `tokens/density/density.spec.md` L47;empty(title + description 都不傳)則 Body 不渲染(已於「Props 結構」規定);loading 由 consumer 決定。
+
+- **步數 > 5**:元件不機械限制 — `step.total` 照實顯示(如「6 of 8」);≤ 5 是設計建議(見 Multi-step Tour),超過應改靜態 onboarding 頁
+- **無 `image`**:整個 Media 區不渲染(非 skeleton 佔位,見「Props 結構」)
+- **Multi-step 中途 Esc**:浮層關閉(`onOpenChange(false)`),step state 由 consumer 持有不受影響 — 再開啟從原 step 續;不觸發 `onSkip`(見「A11y 預設」)
+
+---
+
+## 相關
+
+- `../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`
+- `popover.spec.md`