指令面板系統

指令面板系統 是做什麼的？

目的

指令面板系統提供一個全域性、鍵盤觸發的覆蓋式選單（通常以 Cmd+K 或 Ctrl+K 喚醒）的設計與空間框架。在現代、高密度的網頁應用程式、開發者平台與內容豐富的文件入口網站中，標準的導航列往往不堪負荷。指令面板扮演「指令中心」的角色，為熟練使用者提供直接、無摩擦的鍵盤路徑來進行搜尋、導航與執行操作，同時也作為一個互動式的鍵盤快捷鍵字典。

此技能確保指令面板在空間上符合人體工學、在視覺上結構完整以避免認知疲勞，並且完全符合進階無障礙規範（WCAG 2.2 AA）。

使用案例

• 為 SaaS 儀表板設計全域快捷工作空間控制器。
• 建構開發者導向的入口網站與文件搜尋入口（例如 API 參考文件）。
• 為企業 CRM 或 CMS 平台實作快速行動管理面板。
• 在複雜的多層級網頁產品中建立統一的命令列介面（CLI）。

何時不應使用

• 靜態行銷登陸頁面： 使用者意圖純屬探索與轉換；全域導航列與清晰的 Call-to-Action（CTA）更為有效。
• 淺層資訊網站（<15 頁）： 實作與教導指令面板的額外成本超過了任何路徑尋找的好處。
• 簡單的行動裝置消費型網站： 螢幕空間有限，且使用者完全依賴觸控互動，沒有外接實體鍵盤。

輸入

1. 指令與動作清單： 一個包含所有可搜尋動作、頁面、設定與文件的完整分類。
2. 上下文對應規則： 定義哪些指令為全域性、哪些為上下文專屬的規則（例如「刪除專案」僅在檢視專案時出現）。
3. 鍵盤快捷鍵系統： 將動作對應至實體鍵盤快捷鍵的對照表（例如 G 接著 D 代表「前往儀表板」）。
4. 品牌設計 Token： 字型比例、顏色、間距比例與陰影 token（來自 fluid-spacing-system 與 fluid-typography-system）。

輸出

1. 觸發器視覺規格： 持久性進入點與鍵盤快捷鍵徽章的視覺設計。
2. 面板佈局架構： 覆蓋模態視窗、結果分組、分類導航與輔助頁尾的網格結構。
3. 指令行視覺規格： 圖示、指令標題、分類徽章與快捷鍵註解的層級規範。
4. 鍵盤與無障礙規格： 符合 ARIA APG Combobox 模式的確切鍵盤事件對應與 ARIA 狀態規範。

---

工作流程

1. 建立面板觸發器與進入點

由於指令面板預設為隱藏，你必須設計可被發現的進入點：

• 持久性標頭觸發器： 在全域標頭中模擬搜尋列的按鈕，包含放大鏡圖示、文字標籤（例如「搜尋或執行指令...」）以及靠右對齊的實體鍵盤快捷鍵徽章（例如 ⌘K 或 Ctrl+K）。
• 浮動指令按鈕： 對於儀表板密集型或全螢幕的視口，在視口右下角放置一個低調的觸發按鈕。
• 隱形全域監聽器： 確保在任何地方按下 Cmd+K（macOS）或 Ctrl+K（Windows/Linux）都會立即開啟面板（除非焦點在文字輸入框中）。

2. 設計模態覆蓋層與背景遮罩

• 背景遮罩： 使用高對比度、半透明的背景遮罩（例如 rgba(15, 23, 42, 0.4)）來調暗背景頁面，將注意力完全集中於當前任務。
• 垂直位置： 將模態視窗水平置中，但垂直錨定於視口的 頂部 10%–15% 處，而非絕對垂直置中。這符合自然視線水平，並為觸控螢幕上的虛擬鍵盤預留空間。
• 尺寸邊界： 將寬度限制在舒適的掃描範圍內——理想值介於 600px 至 680px 之間。高度應為動態，最大上限為 450px 至 550px，以確保不會超出小型筆電螢幕。

3. 結構化內部佈局網格

將指令面板劃分為四個不同的水平區域：

1. 搜尋與篩選區： 一個無邊框、全寬的輸入欄位，附有醒目的搜尋圖示（最小 20px）。使用引導使用者的佔位文字（例如「輸入指令或搜尋...」）。
2. 分類篩選列（可選）： 一列緊湊的標籤或分段控制項（例如「全部」、「動作」、「頁面」、「使用者」），讓使用者在搜尋前先篩選結果。
3. 結果列表（可捲動容器）： 一個包含分組標題（例如「最近使用」、「導航」、「系統設定」）的可捲動 listbox。
4. 輔助頁尾： 一個低對比度的狀態列，顯示鍵盤指南（例如 ↑↓ 瀏覽、↵ 選擇、esc 關閉）。

+-----------------------------------------------------------+
|  [搜尋圖示]  搜尋或輸入指令...                      [ESC] |
+-----------------------------------------------------------+
|  ( 全部 )  ( 動作 )  ( 頁面 )  ( 成員 )  ( 說明 )        |
+-----------------------------------------------------------+
|  最近搜尋                                                 |
|  [圖示] 前往帳單設定                           [ ⌘ G ] [ B ]|
|  [圖示] 建立新發票                            [ ⌘ N ]     |
|                                                           |
|  導航                                                     |
|  [圖示] 儀表板                                            |
|  [圖示] 團隊設定                              [ ⌘ , ]     |
+-----------------------------------------------------------+
|  ↑↓ 瀏覽  |  ↵ 選擇  |  esc 關閉  |  ? 說明文件          |
+-----------------------------------------------------------+

4. 建立指令行視覺層級

結果列表中的每個項目必須在數毫秒內可被掃描：

• 左對齊圖示： 一個明確、高對比度的圖示，表示項目的類型（例如文件用檔案圖示、設定用齒輪圖示、人員用使用者頭像）。
• 主要標籤： 指令本身的半粗體、主要顏色文字（例如「邀請團隊成員」）。
• 次要子標籤（可選）： 位於主要標籤下方或旁邊的淡化、較小描述，以提供上下文（例如「設定 > 組織」）。
• 右對齊快捷鍵徽章： 使用小型、高對比度的按鍵徽章（例如 ⌥I）顯示與該指令關聯的實體鍵盤快捷鍵。

5. 定義互動狀態與鍵盤選取

指令面板主要由鍵盤驅動；因此，鍵盤選取狀態優先於滑鼠懸停：

• 啟用中/焦點項目狀態： 當使用方向鍵瀏覽項目時，套用顯著的背景填色變化（使用主要色調的淺色 token，例如 var(--color-primary-light)）以及左邊框指示器。主要文字應切換為品牌色。
• 懸停狀態（滑鼠）： 鏡像鍵盤啟用狀態。滑鼠移到項目上時應更新鍵盤選取，以防止雙重焦點狀態。
• 空狀態： 當搜尋無結果時，顯示一個乾淨、具說明性的空狀態，建議替代動作（例如「找不到指令。請嘗試搜尋我們的說明中心」並附上搜尋連結）。
• 載入狀態： 如果搜尋查詢結果是異步取得的，在搜尋輸入框底部顯示一個微妙的線性載入指示器，避免使用會導致版面位移的骨架卡片。

---

決策規則

• 「Cmd+K vs 持久性搜尋」規則： 如果網站的主要價值在於消費結構化內容（例如電子商務目錄），請使用持久性搜尋列。如果價值在於管理工作流程、指令執行或密集導航，則使用 Cmd+K 指令面板。
• 分組限制規則： 絕不同時顯示超過 3–4 個指令分類。將每個分類中可見項目的最大值保持在 5 個，並提供「顯示更多...」選項（如果存在更多項目）。
• 「按鍵數量」規則： 顯示在指令旁邊的實體鍵盤快捷鍵絕不能超過 3 個按鍵（例如 Ctrl+Shift+P 可以接受；Ctrl+Alt+Shift+Z 則過於複雜）。
• 動態上下文規則： 根據活躍路由動態過濾指令。如果使用者位於帳單頁面，則在預設（未輸入）結果列表的頂部優先顯示「更新信用卡」或「下載發票 PDF」。

---

限制條件

1. 無障礙（WCAG 2.2 AA 最低要求）

• ARIA Combobox 模式： 必須嚴格遵循 ARIA 創作實踐指南（APG）來建構標記：
  • 輸入容器必須具有 role="combobox"、aria-expanded="true"、aria-autocomplete="list" 以及 aria-controls="command-listbox-id"。
  • 結果列表必須具有 role="listbox"，且每個指令行必須具有 role="option"。
  • 當使用者按下方向鍵時，輸入框必須更新 aria-activedescendant 以指向活躍選項的 ID，且該選項必須具有 aria-selected="true"。
• 焦點管理： 開啟面板時必須將鍵盤焦點鎖定在覆蓋層內。按下 Tab 鍵應被攔截以在面板內循環，或完全停用（偏好使用方向鍵進行選項瀏覽）。關閉面板時必須將焦點返回到觸發該面板的確切元素。
• 螢幕閱讀器宣告： 在輸入框旁邊放置一個不可見的 div，具有 aria-live="polite" 和 aria-atomic="true"。在搜尋時，動態填入結果狀態（例如「找到 12 個結果，請使用上下方向鍵瀏覽」）。
• 對比度： 所有文字、快捷鍵徽章和焦點指示器必須符合 WCAG AA（一般文字最低 4.5:1，UI 邊框和選取指示器最低 3:1）。
• 背景鎖定： 當面板啟用時，應用程式的其餘部分必須設為 inert 並對螢幕閱讀器隱藏。使用 <dialog>.showModal() 來原生實現焦點鎖定、背景調暗以及透過 Escape 關閉。

2. 響應式設計與觸控適應

• 觸控視口調整： 在行動裝置螢幕上，指令面板必須切換為全螢幕覆蓋層或底部滑出抽屜。
• 虛擬鍵盤處理： 開啟時自動聚焦搜尋輸入框，並使用 inputmode="search" 以確保行動裝置在其虛擬鍵盤上顯示正確的「搜尋」動作按鈕。
• 隱藏實體按鍵提示： 在純觸控裝置上，隱藏實體鍵盤快捷鍵徽章（例如 ⌘K 或 ⌥I），因為它們不相關且會造成視覺雜亂。
• 觸控目標尺寸： 可移除標籤、分類標籤與列表行在觸控螢幕上的高度必須至少為 44px，以適應手指點按，並遵循 WCAG 2.2 SC 2.5.8。

---

常見失敗模式

• 「無限捲動」陷阱： 允許結果列表在沒有捲動容器的情況下渲染超過 100 筆相符項目，導致溢位螢幕，使頁尾指南無法存取。
• 缺乏背景捲動鎖定： 當使用者在指令面板內進行滾動瀏覽時，允許背景文件繼續滾動，導致版面迷失方向。
• 失去輸入焦點： 點擊分類標籤或結果選項時，文字輸入框失去鍵盤焦點，導致鍵盤使用者必須用 Tab 鍵返回。
• 難以理解的行動裝置顯示： 在 320px 的行動裝置螢幕上保留一個小型、桌面置中的模態視窗，導致主要標籤和快捷鍵徽章被截斷。
• 觸發器狀態鏡像缺失： 持久性標頭按鈕未顯示鍵盤快捷鍵，導致鍵盤使用者不知道存在指令面板。

---

驗證標準

• 標頭中存在一個持久性觸發按鈕，並附有清晰的 Cmd+K / Ctrl+K 視覺快捷鍵徽章。
• 在頁面任何位置按下 Cmd+K 或 Ctrl+K 會開啟模態視窗。
• 鍵盤焦點立即移至搜尋輸入框，且背景頁面滾動被鎖定。
• 選項瀏覽由向上和向下方向鍵驅動，並具有高度可見的聚焦啟用狀態。
• 選項行具有結構化層級：左側圖示、粗體動作標題、上下文路由層級以及右側快捷鍵徽章。
• ARIA APG Combobox 模式已完整指定，包括 role="combobox"、role="listbox"、role="option" 和 aria-activedescendant。
• 存在一個 aria-live="polite" 區域，用於向螢幕閱讀器宣告搜尋結果數量的變化。
• 在行動裝置視口上，面板會適應為全螢幕或底部抽屜，隱藏實體快捷鍵徽章，並將行高設為至少 44px。
• 按下 Escape 或點擊背景遮罩會關閉面板，並將焦點返回到觸發按鈕。