coastdigitalgroup/coastai-skills

Toast 與 Snackbar 系統

目的

Toast 與 Snackbar 系統提供了一套設計暫態、非干擾性通知層的方法論。這些是短暫出現、可自動關閉或由使用者手動關閉的 UI 元件，位於主要介面上的專屬螢幕圖層。與強制回應覆蓋層不同，它們不會搶佔焦點或中斷使用者流程；而是作為被動、高可見度的「確認迴路」，用於確認背景或即時任務已成功、失敗或需要輕微關注。此系統確保 Toast 在外觀上視覺統一，位置安排能避免阻擋重要控制項，並完全支援滑鼠、觸控及輔助技術使用者。

使用案例

• 非同步操作： 確認檔案已上傳、草稿已儲存，或記錄已在背景中刪除。
• 微型操作確認： 確認將商品加入購物車、複製連結至剪貼簿，或切換本地化系統偏好設定等操作。
• 可逆破壞性操作： 通知使用者某項目已被封存或刪除，並在 snackbar 內提供立即的「復原」動作。
• 瞬態狀態更新： 顯示簡短的自動化系統提示，例如切換至「離線」或「線上」狀態。

何時不應使用

• 高嚴重性系統阻斷： 若重大錯誤需要立即干預或阻止使用者繼續操作（例如：會話過期、付款失敗），請使用 overlay-and-dialog-system (Modal)。
• 持續性區塊警告： 若警告或錯誤與整個區塊、頁面或表單上下文相關且需保持可見直到問題解決，請使用 banner-and-alert-system (Inline Alert)。
• 表單驗證訊息： 若使用者在特定輸入欄位中發生錯誤，請使用 form-design-system (欄位層級驗證)。
• 主要內容發現： 絕對不要使用 toast 來呈現主要內容、行銷公告或導航選項。

輸入

1. 訊息嚴重性 / 類型： 成功（確認）、資訊（中性更新）、警告（非阻斷性問題）或錯誤（操作失敗）。
2. 動作需求： 回饋是被動的（唯讀），還是包含單一微型動作（例如：「復原」、「檢視」、「重試」）？
3. 螢幕空間與裝置類別： 目標視埠（桌上型電腦、平板、手機）以及主要的輸入方式（滑鼠懸停 vs. 拇指觸及範圍）。
4. Z-Index 與圖層策略： 堆疊上下文規則，以防止與頂部導航、浮動頁尾或活動中的覆蓋層重疊。

輸出

1. 元件結構規格： 基於格線的容器、圖示槽、訊息字串、動作 CTA 及手動關閉按鈕的藍圖。
2. 空間對齊與放置規則： 針對桌上型電腦（例如右上角或右下角堆疊）和手機（例如底部全寬滑入）的自適應座標。
3. 佇列與堆疊邏輯： 處理同時發生的提示、最大可見數量限制及過期順序的系統規則。
4. 互動時間軸與過期規格： 管理自動關閉超時、懸停暫停行為及滑動手勢的規則。
5. 無障礙 / ARIA 藍圖： 即時區域的語意映射、互動式 Toast 的焦點處理，以及螢幕閱讀器宣告。

工作流程

1. 建構元件結構

使用標準的間距代幣定義 Toast 容器的精確間距與佈局網格：

• 圖示槽： 固定寬度（例如 20px 或 24px），位於最左側。使用語意明確、高對比度的狀態圖示（成功使用勾號，警告/錯誤使用驚嘆號三角形，資訊使用資訊圓圈）。
• 文字區域： 左對齊、可換行的排版，包含簡短標題（粗體，可選）和描述。絕對不要使用省略號截斷文字；在最多 3 行內換行顯示。
• 動作槽（可選）： 一個單一的、高度可見的文字按鈕（例如「復原」），放在訊息的右側。在手機上若文字較長，則將動作換行至新行並靠右對齊。
• 關閉觸發： 一個清晰的 'X' 關閉按鈕，放在最右側。必須有至少 24x24px 的點擊區域（觸控目標建議為 44x44px）。

2. 根據視埠決定空間放置

• 桌上型電腦放置： 將 Toast 容器堆疊放在螢幕的右上角或右下角。與視埠邊緣保持 24px 的固定偏移量。
  • 右上角堆疊： 主要操作流程發生在頁面下半部分時最佳。
  • 右下角堆疊： 頂部導航或工具列佔據上方邊距，需要避免重疊時最佳。
• 手機放置： 將桌上型堆疊轉換為底部固定、全寬的 Snackbar（距左、右、底部邊緣 12px 至 16px 邊距）。這可將互動保持在最佳的「拇指觸及區」內。
• Z-Index 規則： 始終分配一個專用的 z-index 代幣（例如 z-index: 5000 或更高），使其位於標準固定標題 (z-index: 1000) 之上，但低於活動中的全螢幕覆蓋層 (z-index: 10000)。

3. 建立堆疊與佇列邏輯

管理高觸發頻率的環境，避免佈局抖動或認知負擔：

• 最大可見限制： 將活動佇列限制在垂直堆疊的 3 個可見 Toast。
• 堆疊方向：
  • 若放置在螢幕頂部，新的 Toast 從頂部滑入，將舊的 Toast 往下推。
  • 若放置在螢幕底部，新的 Toast 從底部滑入，將舊的 Toast 往上推。
• 佇列緩衝： 若在 3 個 Toast 活動時觸發第 4 個，將新 Toast 緩存在記憶體中。等到最舊的可見 Toast 自然過期並淡出後，立即渲染它。

4. 編寫過期與懸停暫停時間軸邏輯

Toast 必須存在足夠長的時間以便閱讀，但也要迅速消失以清空螢幕：

• 動態存活時間 (TTL)： 根據內容長度計算過期時間：
  • 短被動 Toast（少於 40 個字元）： 在 5 秒 後關閉。
  • 較長或包含動作的 Toast： 在 7 到 10 秒 後關閉，以確保螢幕閱讀器能完整宣告，且使用者有時間閱讀和採取行動。
  • 錯誤/失敗 Toast： 不自動關閉。保持可見，直到使用者手動點擊 'X' 按鈕，確保關鍵回饋不會遺失。
• 「懸停暫停」互動：
  • 若滑鼠使用者將游標懸停在 Toast 佇列的任何部分，凍結所有活動 TTL 計時。僅在滑鼠離開 Toast 邊界後才重置並恢復計時器。
  • 若鍵盤使用者將焦點置於 Toast 內部的任何元素，則無限期凍結計時器。僅在焦點移回主文件時才恢復倒數計時。

5. 定義關閉與手勢行為

• 觸控滑動： 在行動裝置上，允許使用者透過水平滑動（向左或向右）立即將個別 Snackbar 從螢幕上劃掉。拖曳閾值保持在視埠寬度的 30%。
• 動畫： 使用流暢、硬體加速的轉場（例如 transform 和 opacity），持續時間為 200ms 到 300ms，使用 cubic-bezier(0.16, 1, 0.3, 1) (ease-out-expo) 作為進入動畫，並使用簡單的 opacity 淡出作為退出動畫。

---

決策規則

堆疊對齊矩陣

視埠	主要導航佈局	建議的 Toast 放置位置	動畫方向
桌上型電腦	左側邊欄 / 儀表板	右下角（保持主要工作區域清晰）	從螢幕外向左滑入
桌上型電腦	固定頂部標題	右下角（防止遮擋導航）	向左或向上滑入
桌上型電腦	極簡風格 / 頁尾較重	右上角	向左或向下滑入
手機	任意	底部居中 / 全寬	從底部邊緣向上滑入

過期邏輯矩陣

Toast 嚴重性 / 類型	包含動作按鈕？	建議過期時間	關閉類型
成功 / 資訊	否	5 秒（固定）	自動關閉 + 手動關閉
成功 / 資訊	是（「復原」/「檢視」）	8 - 10 秒	自動關閉 + 手動關閉
警告	否	7 秒	自動關閉 + 手動關閉
錯誤 / 失敗	是或否	無限（保持持久）	僅 手動關閉

---

限制條件

• 無障礙 (WCAG 2.2 合規)：
  • ARIA 即時區域： 將被動 Toast 映射到 role="status"（預設為 aria-live="polite" 和 aria-atomic="true"）。避免使用 role="alert"（強制性），除非是在傳達系統故障（例如「網路連線中斷」），因為強制性提示會立即打斷螢幕閱讀器的朗讀。
  • 鍵盤尋路 (WCAG 2.2 SC 2.1.1)： 當 Toast 包含互動式動作（例如「復原」或「檢視」）時，它必須可以透過鍵盤操作。由於鍵盤 Tab 循環可能較慢，請提供全域快捷鍵（例如 Escape 關閉活動中的 Toast，或 F6 將焦點直接移至 Toast 佇列容器），或將 Toast 容器緊接在觸發它的元素之後放置於 DOM 的 Tab 順序中。
  • 無焦點陷阱： 切勿將鍵盤焦點困在 Toast 佇列內。使用者必須能夠自由地按 Tab 鍵跳出 Toast 回到頁面內容。
• 對比度 (WCAG 2.2 SC 1.4.3)：
  • 所有文字、狀態圖示和按鈕相對於 Toast 背景必須滿足最低對比度：
    • 一般文字：4.5:1 最小對比度。
    • 圖示和活動控制項邊框：3:1 最小對比度。
• 響應式設計：
  • 在視埠寬度 < 600px 時，Toast 容器必須跨越全寬（width: calc(100% - 32px)），並置中水平對齊，以避免產生奇怪的邊距欄位。

---

常見失敗模式

• 「遮擋行動」陷阱： 將桌上型 Toast 佇列直接放在高頻互動元素（例如購物車標題按鈕或表格篩選下拉選單）的上方，導致使用者誤點。
• 「曇花一現」閃現： 在 2-3 秒內自動關閉複雜、多字的錯誤或警告。這違反了基本的無障礙閱讀時間閾值，並讓錯過上下文的用戶感到困惑。
• 螢幕閱讀器靜默： 在沒有 ARIA 即時區域包裝器的情況下動態將 Toast 加入 DOM，導致它們對視障用戶完全不可見。
• 佈局抖動： Toast 佇列在進入時高度突然變化，導致主要頁面內容上下跳動。
• 忽略懸停/焦點過期： 當使用者正在懸停閱讀密集的文字訊息或將游標懸停在「復原」CTA 上時，Toast 自行關閉，導致使用者點擊「空氣」並觸發非預期操作。

---

驗證標準

• Toast 使用獨特、高對比度的語意指示器（顏色 + 獨特圖示）進行樣式化。
• 在桌上型電腦上，Toast 不與主要導航元素或全域操作區域重疊。
• 在手機上，Toast 轉換為底部固定、全寬的元件，便於拇指觸及。
• 活動中的計時器在滑鼠懸停或鍵盤聚焦時立即暫停。
• 包含動作的 Toast 保持可見至少 8-10 秒；錯誤 Toast 永不自動關閉。
• 正確指定語意的螢幕閱讀器標記（role="status" 或 role="alert"）。
• 鍵盤使用者可以導航到並觸發 Toast 動作按鈕，且無焦點陷阱障礙。
• 所有互動元素（關閉按鈕、CTA）滿足 WCAG 2.2 的 24x24px 最小觸控目標（建議為 44x44px）。