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

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

@@ -0,0 +1,356 @@
+// @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-h3 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 幫你摘要、翻譯或改寫內容。"
+            isLastStep
+            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
+          // 2026-07-14 Dim 55:--color-cyan-6 不存在(12 hue 無 cyan)→ 改既有 turquoise
+          image={<MediaGradient from="var(--color-blue-6)" to="var(--color-turquoise-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

@@ -10,7 +10,6 @@ benchmark:
   - 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 設計原則
 
@@ -22,7 +21,7 @@ Coachmark 是**主動推送的功能介紹浮層**——anchor 到特定 UI 元
 
 **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 -->
+`Coachmark` 在本 DS 專指錨定目標、用於解說功能或分步導覽的暫時性浮層；命名不延伸到一般 Tooltip、Popover 或 Dialog。
 
 ---
 
@@ -30,9 +29,9 @@ Coachmark 是**主動推送的功能介紹浮層**——anchor 到特定 UI 元
 
 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 -->
+- **預設比 Popover 寬一階**:容納 media + 多行 description(主動推送內容量 > 篩選面板);固定單一寬度、無 size variant,具體寬度值見 `coachmark.tsx`
+- **外殼移除預設 padding 並裁切圓角**:讓 Media 邊緣貼齊外殼圓角;Body / Footer 各自消費 overlay-surface padding token(實作見 `coachmark.tsx`)
+- **Footer `justify-between`**:step 計數(左)+ actions(右)，把目前位置與可執行導覽分成兩個穩定區域
 
 SSOT 規則:**Coachmark 不重寫 Popover 的任何視覺 token**,只加自己結構層的差異。
 
@@ -49,6 +48,8 @@ SSOT 規則:**Coachmark 不重寫 Popover 的任何視覺 token**,只加自己
 
 **為什麼 onboarding 絕不用 Dialog**:強制彈窗打斷使用者自主探索的動線,心理上造成「又是 tutorial?跳過」的本能反彈。Coachmark 的 non-modal 特性讓使用者保持主控權,tour 反而更容易被完整看完。
 
+**常見誤解**:「必須完成才能繼續用產品」的強制流程 ≠ Coachmark scope — 強制完成 = 阻斷 = Dialog(Coachmark 永遠可退出,見禁止事項「不強迫完成 tour」);hover 查詢式說明也 ≠ Coachmark — 那是 Tooltip 的被動模型(見「何時不用」)。
+
 ---
 
 ## 何時用
@@ -77,19 +78,19 @@ SSOT 規則:**Coachmark 不重寫 Popover 的任何視覺 token**,只加自己
 
 ```
 ┌────────────────────────────────┐
-│ Header(可選)                  │  ← SurfaceHeader padding;kind="tips"/"new-features"
-│   使用技巧 / 新功能介紹        │     text-caption uppercase text-fg-secondary
+│ Header(可選)                  │  ← kind="tips"/"new-features";tour-level title
+│   使用技巧 / 新功能介紹        │
 ├────────────────────────────────┤
-│ Media                          │  ← 可選,頂部 full-width,AspectRatio {16/9} default
-│ (image / illustration / video) │     邊緣對齊(overflow-hidden)
+│ Media                          │  ← 可選,頂部 full-width,AspectRatio 鎖比例(預設 16:9)
+│ (image / illustration / video) │     邊緣貼齊外殼圓角
 ├────────────────────────────────┤
-│ Body                           │  ← SurfaceBody padding(px-loose py-tight)
-│   Title                        │     text-body-lg font-medium
-│   Description                  │     text-body text-fg-secondary
+│ Body                           │  ← Title + Description(token 見「視覺 Token」表)
+│   Title                        │
+│   Description                  │
 ├────────────────────────────────┤
-│ Footer(justify-between)        │  ← SurfaceFooter padding(px-loose py-tight)
-│   2 of 3       [Skip] [Next]   │     左 step / 右 actions
-│   1 of 3  [Prev] [Next]        │     多步驟中段:無 Skip,加 Prev
+│ Footer(justify-between)        │  ← 左 step 計數 / 右 actions
+│   1 of 3       [Skip] [Next]   │     多步驟第一步:有 Skip,無 Prev
+│   2 of 3  [Prev] [Next]        │     多步驟中段:有 Prev,Skip 自動隱藏
 │                  [知道了]      │     單步驟:無 step / Prev / Skip,只 CTA
 └────────────────────────────────┘
 ```
@@ -98,9 +99,10 @@ SSOT 規則:**Coachmark 不重寫 Popover 的任何視覺 token**,只加自己
 
 ## Props 結構
 
-- `children` — trigger anchor(用 Popover asChild 定位)
+- `children` — trigger anchor(用 Popover asChild 定位)。**必為單一 anchor element**(型別 `ReactElement`;asChild Slot 契約,對齊 Popover / Tooltip / HoverCard——多元素 / fragment / string 會 `React.Children.only` runtime 炸,型別收緊讓錯誤提前到 compile 期)
 - `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 不渲染該按鈕
@@ -126,9 +128,9 @@ SSOT 規則:**Coachmark 不重寫 Popover 的任何視覺 token**,只加自己
 
 ## Media 區規則
 
-- **尺寸**:固定 `aspect-video`(16:9),確保不同 tour 步驟視覺一致,consumer 不需自己算高度
+- **比例**:預設 16:9(`mediaRatio` prop 預設 `16/9`),由 `AspectRatio` 鎖長寬比 — 同一段 tour 各步驟維持一致比例,consumer 不需自己算高度。需要時 consumer 可傳 `mediaRatio`(如 `4/3` 產品截圖 / `1/1` 方圖 / `3/4` 直式)覆寫
 - **背景**:預設 `bg-muted`(當內容是 illustration 或透明 PNG 時有底色)
-- **邊緣**:`overflow-hidden` + `rounded-t-lg` 讓媒體切齊浮層圓角
+- **邊緣**:圓角切齊靠外殼裁切(見「與 Popover 的關係」)——media 不自帶圓角
 - **支援內容**:image / video / SVG illustration / animated GIF / Lottie
 - **禁止**:不放互動元件(按鈕 / 輸入框)——media 純視覺說明,互動一律走 footer
 
@@ -150,7 +152,7 @@ const steps = [
 
 **設計建議**:
 - **≤ 5 步**——超過使用者疲勞,改用靜態 onboarding 頁面
-- **Skip 只在第一步提供**——進到 step 2+ 後 Skip 自動隱藏(canonical,見上方「CTA 語義表」);想退出走 Esc / header Close 按鈕
+- **Skip 在傳 `onPrev` 時隱藏**——由 `onPrev` 是否存在決定(非讀 `step.current`):有 `onPrev`(通常為第 2+ 步)即自動隱藏 Skip;單步驟也不顯示(canonical,見上方「CTA 語義表」)。想退出走 Esc / header Close 按鈕
 - **最後一步 `isLastStep`**——Next → Done 語意切換,讓使用者知道「這是最後一步」
 - **每步 anchor 到對應 feature**——不 anchor 或 anchor 到無關元素 = 失去「教 X 怎麼用」的精準性
 - **Multi-step 建議傳 `kind="tips"` 或 `"new-features"`**——header 讓使用者一眼看出 tour 性質 / 何時結束的預期
@@ -159,11 +161,11 @@ const steps = [
 
 ## Footer 按鈕順序
 
-Previous(可選)→ Skip(可選)→ Next / Done。對齊 Ant Tour / Intercom convention: <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+Previous(可選)→ Skip(可選)→ Next / Done。動作順序由可逆導覽、退出流程、提交當前步驟三種語意排列:
 
 - **Previous 最左**——回到上一步(負方向,視覺權重低)
-- **Skip 中間**——exit escape hatch,tertiary 不搶焦點;**僅第一步顯示**(見 CTA 語義表)
-- **Next / Done 最右**——推進主動線(正方向,primary 視覺權重高);**不強制 autoFocus** — 讓 Radix 預設行為接管(通常 focus 第一個 focusable),避免使用者還在讀 body 時按 Enter 誤推進
+- **Skip 中間**——exit escape hatch,tertiary 不搶焦點;**未傳 `onPrev` 時顯示**(有 `onPrev` 或單步則隱藏,見 CTA 語義表)
+- **Next / Done 最右**——推進主動線(正方向,primary 視覺權重高);**Coachmark 抑制 CTA 自動 focus**(`onOpenAutoFocus` preventDefault 後 focus content 容器本身,非第一個 CTA),避免使用者還在讀 body 時按 Enter 誤推進;想推進者按 Tab 即達 CTA 再 Enter(單步無 header 一下即達;有 header 或多步時 Close X / Previous / Skip 在推進 CTA 前,需多按幾下;焦點已在 content 內,不觸發 non-modal focus-outside dismiss;2026-07-05 D4 修)
 
 第 1 步通常無 Previous;最後步 Next 改 Done(由 `isLastStep` 控制)。單步驟 CTA 改 `'知道了'`。
 
@@ -175,9 +177,9 @@ Previous(可選)→ Skip(可選)→ Next / Done。對齊 Ant Tour / Intercom con
 |----|-------|------|
 | 浮層外殼 | 繼承 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 分隔線) |
+| Title | `text-body-lg font-medium text-foreground` | body 主 title(16px),比 kind header 的 `PopoverTitle` 小標籤(`text-body` 14px)重一階——主教學訊息是視覺主角 |
 | Description | `text-body text-fg-secondary` | 主說明文字 |
-| Step 計數 | `text-caption text-fg-secondary tabular-nums` | 數字等寬,切換步驟不跳動 |
+| Step 計數 | `text-body text-fg-secondary tabular-nums` | 跟 body 內文同字體；固定數字 advance width，切換步驟時維持量測穩定 |
 | 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 覆寫 |
@@ -190,7 +192,7 @@ Previous(可選)→ Skip(可選)→ Next / Done。對齊 Ant Tour / Intercom con
 - ❌ **不用 Coachmark 做確認框**——確認破壞性動作必須阻斷流程,改用 `Dialog`
 - ❌ **Media 區不放互動元件**——按鈕 / 輸入 / checkbox 一律走 footer。Media 是視覺說明不是互動區
 - ❌ **Description 不寫超過 3 行**——Coachmark 是快速說明,超過 3 行改用 Dialog + 完整 body 或連結到說明文件
-- ❌ **不強迫完成 tour**——永遠提供退出機制(Esc / header Close / 第一步 Skip)。沒有退出的 onboarding 讓使用者感到被綁架,反而降低完成率
+- ❌ **不強迫完成 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
@@ -200,8 +202,8 @@ Previous(可選)→ Skip(可選)→ Next / Done。對齊 Ant Tour / Intercom con
 
 ## A11y 預設
 
-- **焦點管理**:由 Popover(Radix)處理——開啟移焦點進 content,關閉 return to trigger
-- **Esc 關閉**:預設啟用(= Skip 行為)——user 按 Esc 等同 skip,尊重退出意願
+- **焦點管理**:Coachmark **刻意抑制 CTA 自動 focus**(`onOpenAutoFocus` preventDefault 後 focus content 容器本身,對齊 `dialog.tsx` 的 `?? content` fallback canonical)——避免使用者還在讀 body 時 CTA 被 auto-focus 偷觸發(焦點在容器上按 Enter 無動作);按 Tab 移到 content 內第一個 tabbable(單步無 header 即推進 CTA;有 header 會先到 PopoverHeader 右上 Close X,多步則先經 Previous / Skip)。焦點**不**停在 trigger:non-modal Popover 焦點在 content 樹外時按 Tab 會觸發 focus-outside dismiss 誤關閉浮層,CTA 鍵盤永遠到不了(2026-07-05 D4 修;dismiss 機制詳 `popover.spec.md` A11y 段)。關閉時焦點 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」語意清楚
 
@@ -209,7 +211,11 @@ Previous(可選)→ Skip(可選)→ Next / Done。對齊 Ant Tour / Intercom con
 
 ## 邊界狀態
 
-disabled / density 繼承 Popover(density 鎖 md,見 `../Popover/popover.spec.md`);empty(title + description 都不傳)則 Body 不渲染(已於「Props 結構」規定);loading 由 consumer 決定。
+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 預設」)
 
 ---
 
@@ -221,10 +227,11 @@ disabled / density 繼承 Popover(density 鎖 md,見 `../Popover/popover.spec.md
 - `../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 -->
+- 本 spec 的 Anatomy / 導覽狀態表與 `coachmark.tsx` — canonical authority
 
 ## 被引用(auto-maintained,Dim 3 reciprocal audit)
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `aspect-ratio.spec.md`
+- `popover.spec.md`