Coachmark 聚光導引
圈起畫面上的某個元素，旁邊說明它是什麼。
在 Storybook 開啟這是純呈現元件
目標矩形、內容、步進狀態與回呼全部由外部傳入。它不知道有幾支導覽、目前走到哪、 錨點怎麼找——那是宿主應用的事。
這條界線的價值：同一個元件可以被「新手導覽」「功能公告」「驗收清單」三種完全不同的流程共用。
三個關鍵決定
1. 聚光洞可以點穿
pointer-events: none，使用者仍能點到被圈起來的控制項。
導引是教人操作，不是代替他操作。
2. 可以縮小
需要實際操作（開對話框、切分頁）時，導引卡收成右下角小膠囊，整個畫面恢復可用。
這是最常被忽略、也最常被抱怨的一點：導引卡剛好擋住它正在叫你點的那顆按鈕。
導引卡一定要能縮小或移開，而且要讓使用者看得出來可以這樣做。
不要做成「只能下一步或關閉」。使用者一旦需要真的操作一下，就只剩關閉這條路， 然後他就再也不會打開導覽了。
3. 鍵盤可以走完
← → 換步、Esc 略過、Enter 前進。每一步自動把焦點移入卡片，
螢幕報讀器透過 aria-live 唸出新內容。
驗收模式
同一個元件換一種用途：加上 showVerdict，每一步多一組「✅ 通過／❌ 有問題＋備註」。
走完就是一份可交付的驗收報告。
這個用法是意外長出來的——原本只是新手導覽，後來發現「帶著人走一遍畫面並逐項標記」 正好就是驗收該做的事。
四種形態，不是四個 prop
除了「圈住某個元素」之外，這個元件還有四種形態。它們不是選配裝飾， 各自對應導覽裡一種一定會遇到的情況。
| 形態 | 什麼時候 |
|---|---|
無錨點置中卡（targetRect 傳 null） | 開場與收尾。此時沒有任何特定元素要圈 |
互動待點（actionHint） | 這一步必須使用者真的動手，導覽才能往下 |
狀態警示（warning） | 前置條件沒滿足，照著做會失敗 |
鏈結下一支（secondaryAction） | 走完一支，銜接下一支 |
開場與收尾不要硬找一個東西圈
導覽的第一步是「這段導覽要帶你做什麼」，最後一步是「你已經會了」。 這兩句話不屬於畫面上任何一個按鈕。
開場與收尾傳 targetRect = null，卡片置中，不畫聚光洞。
不要為了「每一步都要有聚光」而隨便圈一個標誌或標題。 使用者會盯著那個被圈起來的東西，想著「這個很重要嗎」——注意力用錯地方了。
需要動手的那一步，要說出來
有些步驟不能只用「下一步」帶過：開啟對話框、切換分頁、輸入一個值。 使用者若只是按「下一步」，導覽會繼續往前，但畫面沒有跟上——後面每一步都在講他看不到的東西。
用 actionHint 明說（「👆 點上方圈選處即可繼續」），
並讓實際操作也能推進到下一步。
不要只留「下一步」按鈕就期待使用者會自己去點圈起來的地方。 按鈕在那裡，人就會按按鈕——這不是使用者的錯。
搭配聚光洞可點穿：導覽是教人操作，不是代替他操作。
前置條件沒滿足要先講，不要讓他撞牆
導覽是預先寫好的，但畫面的狀態是活的。使用者可能正在一筆已鎖定的資料上跑這段導覽—— 照著做會被擋下來，而他不知道為什麼。
用 warning 在該步的卡片上講明白：
現在的狀態、為什麼不能做、去哪裡解除。
不要讓使用者照著導覽做，然後撞到一個「無法操作」的錯誤。 他會同時失去對導覽和對系統的信任——而且下次不會再開導覽了。
這一條讓導覽從「一段錄好的影片」變成狀態感知的東西， 也是它值得做成元件（而不是寫一份圖文教學）的主要理由。
最後一步接下一支
secondaryAction 在末步多一顆次要按鈕（「接著看：⟨下一段流程⟩ →」）。
每支導覽聚焦一件事（3–7 步），走完再鏈結到下一支。
不要為了「一次講完」把三個流程串成 15 步。 使用者會在第 9 步關掉，而且不會再打開。
主按鈕維持「完成」——離開的路要永遠比繼續的路好走。 一旦「接著看」變成主按鈕，導覽就從服務變成了糾纏。
何時不要用
第一次使用的關鍵路徑（3–7 步）、或新功能公告（1–2 步）。
不要用導覽來補救糟糕的介面。需要 12 步才講得完的畫面， 問題不在導覽——導覽只是把「看不懂」延後了三分鐘。
互動範例
聚光導引需要量測真實元素位置，在文件站的靜態頁面裡意義不大。 完整互動範例請看 Storybook 的「元件/引導/聚光導引」。
取用
npx shadcn@latest add https://kielchang.github.io/dooping-design-book/r/coachmark.json
延伸閱讀：模式 → 引導式導覽與驗收標記