coastdigitalgroup/coastai-skills

入門導覽系統 (Onboarding Tour System)

目的

「入門導覽系統」技能提供一套全面的設計方法論，用於結構化、風格化並協調多步驟引導式產品流程說明。其設計目的是在初次入門或重大功能發布時，透過視覺上隔離關鍵介面元素、提供依序且高度相關的上下文，引導用戶進入活躍且成功的狀態，從而減輕用戶的認知負荷。此系統能建立可預測、易於使用且由用戶控制節奏的導覽，避免產生混亂、擾人或過於侵入式的體驗。

使用案例

• 初次用戶入門： 引導新註冊的用戶完成複雜 SaaS 應用的核心工作流程，以驅動啟用。
• 新功能推廣： 向既有用戶突顯並說明新發布的高價值工具或介面元素。
• UI 重新設計熟悉化： 在重大介面重新設計或重組後，協助回訪用戶找到熟悉的工具。
• 複雜步驟式資料輸入導覽： 在初始設定（例如設定第一條自動化規則）過程中，引導用戶操作多面向的面板。

何時不應該使用

• 自解釋性介面： 如果任務可以透過更清晰的版面配置、更好的標籤或直觀的圖示來簡化，請先改善核心 UI，不要用導覽來掩蓋不佳的 UX。
• 高度重複的微任務： 避免用彈出視窗打斷頻繁的工作流程。如需常規協助，請使用 tooltip-and-hint-system 或行內輔助文字。
• 純行動裝置或低解析度介面： 多步驟錨定彈出式導覽會消耗大量螢幕空間，且在行動裝置上極易發生裁切或重疊。請改用全螢幕卡片或可關閉的行內步驟。
• 關鍵錯誤或交易性回饋： 對於即時系統回饋或錯誤，請使用 banner-and-alert-system 或 toast-and-snackbar-system。

輸入

1. 資訊架構與上下文： 導覽將執行的特定頁面版面、儀表板區塊或 UI 座標。
2. 錨點元素清單： 每個步驟中需要被突顯的特定目標按鈕、輸入框、表格或導覽連結。
3. 入門里程碑（「為什麼」）： 完成入門並確保啟用所需的最小關鍵動作。
4. 裝置斷點： 導覽必須渲染的響應式目標視埠，使用 responsive-grid-system 的指南。

輸出

1. 背景遮罩與隔離規格： 在視覺上隔離目標元素，同時調暗其餘介面以集中用戶注意力。
2. 彈出式卡片解剖規格： 導覽氣泡的詳細結構藍圖（箭頭、主體文字、步驟指示器、略過/下一步/返回按鈕、關閉控制項）。
3. 序列與流程邏輯： 逐步路線對應、進展模型（嚴格線性 vs. 使用者驅動）以及會話持續性。
4. 響應式策略與行動裝置備援方案： 針對浮動錨定彈出視窗無法安全放置的小螢幕的適配規則。
5. 無障礙地標與互動規格： 完整的 ARIA 規範、鍵盤導覽地圖以及焦點鎖定行為。

工作流程

1. 定義步驟序列（快樂路徑）

• 將導覽序列限制在 3 到 5 個步驟（米勒定律）。更長的序列會導致高放棄率。
• 每個步驟專注於一個主動帶來的好處，而不只是一個標籤（例如，不要寫「這是設定選單」，而應寫「在此自訂您的工作區以符合團隊的工作流程」）。
• 確保最後一個步驟具有清晰、可操作的行動呼籲 (CTA)，讓用戶處於活躍且具有生產力的狀態。

2. 設計背景遮罩與隔離（聚焦）

• 使用深色半透明背景覆蓋層（通常為 #000000 帶 50-70% 不透明度）來抑制背景雜訊並聚焦視線。
• 在活動錨點元素周圍建立一個「隔離遮罩」（使用 SVG 路徑裁切或 CSS clip-path / 盒陰影）。
• 在突顯的錨點周圍保留 4px 到 8px 的內邊距緩衝，以防止遮罩過於貼近元素邊框。

3. 建立彈出式卡片層級

• 錨點對齊： 將彈出式卡片動態放置在突顯元素旁邊。使用一個小的方向箭頭/指針，在視覺上將卡片連結到錨點。
• 元件解剖結構：
  • 頁首： 包含標準的關閉按鈕 (『X』) 和進度指示器（例如「步驟 2 / 4」）。
  • 主體： 使用粗體、簡潔的標題和最多 2 句描述性文字。
  • 動作列： 將「略過」連結靠左對齊，導覽按鈕靠右對齊。確保「下一步」（或「知道了」）使用主要 CTA 樣式，而「返回」使用低對比度的三級樣式。

4. 為無障礙功能編寫程式碼（鍵盤與螢幕閱讀器對等性）

• 焦點鎖定： 當導覽步驟處於活動狀態時，鍵盤焦點 (Tab 鍵) 必須被鎖定在導覽彈出式卡片內，以防止鍵盤用戶與背景元素互動。
• ARIA 關聯： 確保彈出式卡片容器使用 role="dialog" 或 role="alertdialog"，並帶有 aria-modal="false"（這樣輔助技術就知道背景元素仍然存在）。使用 aria-labelledby 將彈出式卡片標題與其關聯，並使用 aria-describedby 關聯描述。
• 鍵盤快捷鍵： 支援鍵盤導覽：Escape 關閉/略過導覽，ArrowRight 用於「下一步」，ArrowLeft 用於「返回」。

5. 規劃行動裝置適配策略

• 如果視埠小於 768px（平板/手機），則從浮動錨定彈出式視窗轉變為底部工作表抽屜或居中、非錨定的模態視窗。這可以防止卡片被推離螢幕或遮蓋關鍵元素。
• 確保在行動裝置上停用或簡化背景遮罩，以防止因行動裝置滾動而導致的裁切錯誤。

決策規則

• 線性導覽 vs. 使用者驅動任務清單：
  • 對於嚴格的初次設定序列（步驟 A 必須在步驟 B 之前），使用線性導覽。
  • 如果任務可以以任何順序完成，請使用互動式進度小工具（任務清單），允許使用者按自己的節奏選擇任務。
• 觸發條件：
  • 僅在首次執行或明確更新後自動觸發。
  • 對於標準訪問中的回訪用戶，切勿自動觸發導覽。
• 錨點位置覆寫：
  • 預設： 將彈出式卡片放置在錨點的「底部居中」或「右側居中」。
  • 碰撞規則： 如果錨點靠近螢幕邊緣，則翻轉彈出式卡片的位置以防止裁切（例如從「右側」翻轉到「左側」）。如果錨點被隱藏（在折疊面板內），請先以程式方式展開面板，然後再渲染彈出式卡片。
• 「略過」的提示：
  • 在每個步驟始終提供可見的「略過導覽」或「關閉」動作。強迫用戶完成導覽而無法逃脫會引起不滿。

約束條件

• 無障礙功能 (WCAG 2.2)：
  • 導覽卡片內部的文字對比度必須符合 WCAG AA（至少 4.5:1）。
  • 互動式按鈕上必須有高對比度的視覺焦點環 (outline)。
  • 上一步/下一步按鈕的觸控目標必須至少為 44x44px（建議）或滿足 24x24px 的最小值 (WCAG 2.2 SC 2.5.8)。
  • 背景裁切區域內的互動式錨點必須可以被聚焦。
• 版面位移管理：
  • 背景、裁切遮罩和彈出式卡片的出現不得移動現有版面元素。使用相對於文件視埠的 position: absolute 或 position: fixed。
• **Z-Index 對齊：
  • 背景與導覽卡片必須位於頂層公用程式提醒（如 Toasts）之下（例如背景 z-index 為 900，彈出式卡片 z-index 為 910），以確保高優先級的系統提醒仍能突破顯示。

常見失敗模式

• 「無窮導覽」陷阱： 步驟多於 5 個的導覽，導致用戶立即流失。
• 「雙重焦點」衝突： 在頁面上已有活動模態視窗時自動啟動導覽，造成重疊覆蓋層與輸入鎖定。
• 盲目錨點突顯： 突顯一個已滾動出螢幕或已折疊的元素，使箭頭指向空白區域。
• 無法觸及的背景動作： 要求用戶在被遮罩的元素中輸入內容以繼續，但用背景遮罩阻擋了他們的輸入或滑鼠點擊。
• 行動裝置氣泡擠壓： 讓錨定氣泡在行動裝置上縮小到無法閱讀的寬度，導致文字尷尬地斷行。

驗證標準

• 導覽嚴格限制在 3-5 個步驟內。
• 每個步驟都有清晰標示、可見的「略過」或關閉選項。
• 在活動步驟期間，鍵盤 Tab 焦點被鎖定在彈出式卡片內。
• 按下「下一步」時，焦點順暢地移動到下一個導覽卡片（或新增突顯的元素）。
• ARIA 屬性（role="dialog"、aria-modal、aria-describedby）正確配置。
• 定義了彈出式卡片碰撞處理（在靠近螢幕邊緣時自動翻轉位置）。
• 行動裝置視埠能優雅地從錨定彈出式視窗轉變為居中模態視窗或持續的底部工作表。
• 在隔離的錨點周圍保持 4-8px 的內邊距緩衝，以避免裁切邊框。
• 所有按鈕的活動與懸停狀態都符合 WCAG AA（4.5:1 對比度）。