四個決策維度

Keyboard type：顯示哪種鍵盤

Keyboard type 決定使用者按下輸入框時出現什麼鍵盤。數字鍵盤、email 鍵盤、URL 鍵盤、一般文字鍵盤 — 每種鍵盤的按鍵配置和自動行為不同。

選擇判斷依據是「使用者要輸入什麼內容」。email 地址用 email 鍵盤（有 @ 鍵），電話號碼用數字鍵盤，密碼或 CLI 指令用 visiblePassword 型別（避免自動校正和建議）。

app_tunnel 的 terminal 輸入框用 TextInputType.visiblePassword — 因為 CLI 指令包含路徑分隔符、flag 縮寫等非自然語言內容，一般文字鍵盤會嘗試自動校正 ls -la 或 /usr/bin/ 成其他東西（U.C3）。

Submit model：怎麼送出輸入

Submit model 決定使用者輸入的內容何時傳送給系統。兩個基本選項：整行送出（使用者按 Enter/Send 後一次傳送整行）和逐字元送出（每個按鍵即時傳送）。

這個決策直接影響通訊協議設計（本章合成，UF-8 Derive）。整行送出代表每次傳送一個完整指令字串（ls -la\n），server 端按行處理。逐字元送出代表每個按鍵產生一個 WebSocket frame（l、s、 、-、l、a），server 端需要處理單字元輸入，包括 Tab 補全和 Ctrl+C 這類立即回應的操作。

app_tunnel 選擇整行送出（onSubmitted），代表 Tab 補全在 client 端無法觸發（因為 Tab 不會單獨送出），但實作成本較低且協議設計較簡單。逐字元送出支援 Tab 補全和命令編輯，但 protocol 複雜度顯著提高。

IME policy：輸入法的行為控制

IME（Input Method Editor）policy 控制手機輸入法的自動行為：自動校正、建議列、個人化學習。每個行為在某些輸入場景是幫助，在另一些場景是干擾或安全風險。

三個控制項各自有獨立的影響：

• autocorrect：自動校正把輸入替換成字典中的詞。CLI 指令和路徑不是自然語言，自動校正會破壞輸入內容。
• enableSuggestions：建議列在鍵盤上方顯示候選詞。在 terminal 場景中建議列遮擋畫面底部的終端機輸出。
• enableIMEPersonalizedLearning：IME 從使用者輸入中學習新詞，跨 app 適用。CLI 輸入可能包含密碼和路徑 — 這是安全問題，見 安全敏感輸入框的 IME 控制 checklist。

Special keys：特殊按鍵的處理

手機鍵盤沒有桌面鍵盤的 Esc、Tab、Ctrl、方向鍵。如果應用需要這些按鍵，必須自建 UI 元件提供。

app_tunnel 用底部工具列提供 Esc/Tab/Ctrl/方向鍵。這個工具列的設計（按鈕大小、排列、長按行為）是 UX 決策，不是實作細節。

決策表作為設計產物

四個維度的決策應該在功能規格中以表格形式記錄，讓 code review 時可以逐項對照實作是否符合規格。

app_tunnel 的六個 TextField 參數全是 W2 hotfix 事後補上的，沒有一個是事前規劃。每個參數都有 gotcha — 漏掉 enableIMEPersonalizedLearning: false 就是安全漏洞，漏掉 autocorrect: false 就是 UX 問題。事先決策並記錄在規格中，code review 時逐項勾選，比事後逐一發現問題的成本低。

四個維度在不同場景下的具體決策各有不同。CLI 場景的特殊需求見 Terminal app 輸入設計，安全敏感欄位的 IME 控制逐項列在 IME 安全 checklist。Submit model 的選擇（整行 vs 逐字元）直接影響通訊協議的設計 — 這個交叉影響在 testing 模組三 協議整合測試中從 test 的角度分析。

觀察

app_tunnel 的 Terminal 畫面在 W2 修復前沒有任何文字輸入元件。使用者只能透過底部工具列的特殊鍵（Esc/Tab/Ctrl/方向鍵）操作終端機，無法打字。

W2-001 修復時加入的 TextField 及其參數：

1TextField(
2  keyboardType: TextInputType.visiblePassword,   // 避免自動校正
3  enableSuggestions: false,                       // 關閉建議列
4  autocorrect: false,                             // 關閉自動校正
5  enableIMEPersonalizedLearning: false,           // 關閉 IME 個人化學習
6  onSubmitted: _submitInput,                      // Enter 送出整行
7  textInputAction: TextInputAction.send,          // 鍵盤顯示「傳送」
8)

每個參數都是一個設計決策，但沒有一個是事前規劃的 — 全部是寫 code 時臨時判斷。

判讀

1. 輸入設計影響 UI layout 和 protocol。onSubmitted（整行送出）vs 逐字元即時送出不只是 UI 問題 — 整行送出代表 protocol 層送的是 command\n，逐字元送出代表每個按鍵都是一個 WS frame。這個決策應該在 protocol spec 階段就做，因為它影響 server 端的行為預期。

2. IME 控制有安全意涵。enableIMEPersonalizedLearning: false 不只是 UX 偏好 — CLI 輸入可能包含資料庫密碼、API key、伺服器路徑。IME 學習這些內容等於把 secret 存到了 IME 的詞庫裡，跨 app 可用。這是安全問題，不是 UX 問題。

3. 事後 hotfix 的六個參數每個都有 gotcha。如果這些決策在企劃階段做，可以寫成決策表並在 code review 時對照。事後 hotfix 時開發者可能漏掉其中一兩個（例如只加 autocorrect: false 但忘了 enableIMEPersonalizedLearning: false），漏掉的那個就成為安全漏洞。

策略

1. 功能規格新增「輸入機制決策表」：keyboard type / submit model / IME policy / special keys 四個維度，每個列出選項和取捨理由。
2. 輸入機制跟 protocol 一起設計：「整行送出」還是「逐字元」決定了 WS 訊框的設計，必須在 protocol spec 階段決定。
3. 安全敏感參數強制列入 review checklist：enableIMEPersonalizedLearning、autocorrect 在處理 secret 的輸入框中是安全要求，不是可選項。

下一步路由

• 想設計 mobile 輸入機制 → 輸入機制決策表
• 想看 protocol 跟輸入的關聯 → T.C1 WS frame type（sendData 的型別決策）
• 想做安全審查 → 待補：CLI 輸入安全 checklist

對應 findings

待寫章節

• 輸入機制四維度決策表（keyboard type / submit model / IME policy / special keys）
• Terminal app 輸入設計（CLI 特殊需求）
• 表單 UX 模式（validate / auto-fill / error feedback）
• 搜尋 UX 模式（debounce / instant / suggestion）
• 安全敏感輸入框的 IME 控制 checklist

跨分類引用

• → testing 模組三 協議整合測試：整行 vs 逐字元影響 protocol test 斷言
• → monitoring 模組七 資安：IME 個人化學習 = secret 洩漏風險

鍵盤使用者導航三要素：focus 可見、tab 順序合理、有 escape 路徑。 三者任一缺失、鍵盤使用者就卡住。視覺使用者看不到 focus 也能用滑鼠繼續、鍵盤使用者沒有 fallback。

本篇焦點：鍵盤可達性。

• 視覺呈現面的 a11y（對比 / 放大）由 #40 視覺輔助 處理
• 行動 / motor 使用者的 a11y（hit target）由 #53 Motor 可達性 處理
• DOM 移動時的 focus 處理由 #37 focus management on DOM move 處理（本篇處理「靜態 focus 設計」、#37 處理「動態 focus 移動」）

為什麼鍵盤可達性需要獨立盤點

使用者類型

最後一類占人口比例不小 — 鍵盤可達性對全體使用者都有價值、不只 a11y 使用者。

三要素的失敗模式

三者都是「視覺使用者通常不會碰到、鍵盤使用者必碰」— 開發者用滑鼠測 100% OK、鍵盤使用者一進去就壞。

風險點 1：Focus indicator 的可見度

位置：tab focus 到 search input、scope radio、filter checkbox 等元素。

判讀：

• 瀏覽器預設 focus outline（藍色 2px）
• 某些 theme 用 outline: 0 移除 — 鍵盤使用者迷失
• 自訂 outline 要對比足夠（WCAG 2.4.7、AA 3:1 對比 + 至少 2px 寬）

症狀：鍵盤使用者 tab 過去看不到 focus 在哪、不知道下一個 enter 會激活誰。

第一個該查的：用 keyboard tab 過所有互動元素、確認每個都有可見 focus。

修正方向：

 1/* 預設 — 信任瀏覽器 outline */
 2/* 不寫 outline: 0 */
 3
 4/* 客製 — 用 :focus-visible（只在鍵盤觸發時顯示、滑鼠點擊不顯示） */
 5:focus-visible {
 6  outline: 2px solid currentColor;
 7  outline-offset: 2px;
 8}
 9
10/* 移除 outline 必須補 box-shadow / border 等替代 */
11button:focus { outline: 0; box-shadow: 0 0 0 3px var(--focus-color); }

:focus-visible 是現代做法 — 滑鼠使用者不看到 outline（不會覺得「煩」）、鍵盤使用者看到 outline（必要的回饋）。

Focus indicator 的對比度

WCAG 2.4.11 要求 focus indicator 跟相鄰背景對比 ≥ 3:1：

1/* 較差 — 灰底 + 灰 outline、對比不足 */
2.button { background: #f0f0f0; }
3.button:focus-visible { outline: 2px solid #cccccc; }
4
5/* 好 — 跟背景對比足夠 */
6.button:focus-visible { outline: 2px solid #0066cc; }

風險點 2：Tab 順序與視覺布局的對齊

位置：搜尋頁元素：H1 → search input → scope radio → results → filter sidebar。

判讀：

預設 tab 順序 = DOM 順序。如果視覺布局跟 DOM 順序不一致（例如 sidebar 在右、但 DOM 在前）、鍵盤使用者體驗：

• Tab 1：H1（OK）
• Tab 2：跑到 sidebar（視覺在右下、鍵盤跳過去）
• Tab 3：search input（視覺在左上、鍵盤跳回來）

症狀：鍵盤使用者 tab 順序看似隨機、失去空間感。

第一個該查的：用 keyboard tab 過所有互動元素、看 focus 移動順序是否符合視覺閱讀順序（左到右、上到下）。

修正方向：

預設選「DOM 順序對齊視覺順序」 — 不需要 tabindex、對所有 a11y 工具都正確。

Skip link 設計

1<body>
2  <a href="#main" class="skip-link">跳到主內容</a>
3  <nav>...</nav>
4  <main id="main">...</main>
5</body>

 1.skip-link {
 2  position: absolute;
 3  top: -40px;       /* 預設藏起來 */
 4  left: 0;
 5  background: var(--bg);
 6  padding: 8px;
 7}
 8.skip-link:focus {
 9  top: 0;            /* tab 到時顯示 */
10}

第一個 tab 焦點 = skip link、鍵盤使用者可以選擇跳過 nav 直達主內容。

風險點 3：Modal / overlay 的 escape 路徑

位置：Pagefind drawer 在 mobile 模式展開、filter sidebar 在某些 layout 是 modal-like。

判讀：

鍵盤使用者進入 modal 後需要：

1. 按 ESC 可以關閉
2. Tab 順序限制在 modal 內（focus trap、不會 tab 到背景元素）
3. 關閉 modal 後 focus 回到觸發元素

任一缺失 = 卡住。

症狀：鍵盤使用者打開 filter drawer 後 tab 跑到背景元素、不知道怎麼關 drawer。

第一個該查的：開啟 modal / drawer / overlay、按 ESC 看會不會關、tab 看會不會跑到背景。

修正方向：

 1function openModal(modal, trigger) {
 2  modal.showModal?.() || (modal.style.display = 'block');
 3
 4  // ESC 關閉
 5  modal.addEventListener('keydown', function (e) {
 6    if (e.key === 'Escape') closeModal(modal, trigger);
 7  });
 8
 9  // Focus trap（簡化版）
10  var focusables = modal.querySelectorAll('button, input, select, [tabindex]');
11  focusables[0]?.focus();
12
13  modal.addEventListener('keydown', function (e) {
14    if (e.key !== 'Tab') return;
15    var first = focusables[0];
16    var last = focusables[focusables.length - 1];
17    if (e.shiftKey && document.activeElement === first) {
18      e.preventDefault(); last.focus();
19    } else if (!e.shiftKey && document.activeElement === last) {
20      e.preventDefault(); first.focus();
21    }
22  });
23}
24
25function closeModal(modal, trigger) {
26  modal.close?.() || (modal.style.display = 'none');
27  trigger?.focus();  // 焦點回觸發元素
28}

用 <dialog> 元素自動 trap：

1<dialog id="filter-modal">...</dialog>

1modal.showModal();  // 自動 focus trap + ESC 處理

<dialog> 是現代做法 — 鍵盤行為由瀏覽器處理、不需要手寫 trap 邏輯。

設計取捨：focus 處理策略

當需要客製 focus 視覺時、四種做法：

A：信任瀏覽器預設 outline（這個專案的預設）

• 機制：完全不寫 outline 規則、瀏覽器藍色 outline 自動套用
• 選 A 的理由：成本最低、跨瀏覽器一致、不會意外破壞
• 適合：對 focus 視覺沒有強烈品牌需求
• 代價：focus 看起來「不夠精緻」（瀏覽器預設不一定符合品牌風格）

B：用 :focus-visible 客製 outline

• 機制：:focus-visible { outline: 2px solid var(--brand); }、滑鼠點擊不顯示
• 跟 A 的取捨：B 達到品牌一致性、滑鼠使用者不被「煩」；A 簡單但視覺一般
• B 比 A 好的情境：品牌設計嚴格要求 focus 視覺

C：用 box-shadow 取代 outline

• 機制：:focus-visible { box-shadow: 0 0 0 3px var(--focus); outline: 0; }
• 跟 B 的取捨：C 跟 outline 視覺差異是「跟著元素圓角」、適合圓角 UI；outline 永遠是矩形
• C 比 B 好的情境：圓角元素需要 focus 跟隨圓角

D：完全移除 focus indicator

• 機制：*:focus { outline: 0; }、不補替代
• 成本特別高的原因：違反 WCAG 2.4.7、鍵盤使用者完全無法導航
• D 是反模式：違反 WCAG 2.4.7（合規層） — 即使品牌追求極簡、也該保留 focus indicator

「邏輯 tab 順序」要素的詳細展開（DOM vs tabindex 的取捨、跟 mental model 對齊）見 #71 Tab Order = DOM Order = Mental Model 三者對齊。

跟其他原則的關係

開發階段檢查清單

每個 ~30 秒、開發完成前跑一輪。

判讀徵兆

核心原則：鍵盤可達性的三要素都是「視覺使用者通常不會碰、鍵盤使用者必碰」 — 開發階段必須拔滑鼠測一輪、不能依賴使用者通報。