JS 移動或隱藏 DOM 元素時、鍵盤 focus 的命運要主動處理 — 不處理會跑掉或停在不可見元素上、鍵盤使用者瞬間迷失方向。 多數動態 UI 的 focus 問題不是「某個元素該 focusable」、是「某個變動沒考慮 focus 該去哪」。

為什麼 focus 管理需要主動處理

商業邏輯

鍵盤使用者依 focus 知道「現在在哪」。focus 變動有三種來源：

第二、三類是 JS 變動 DOM 引起的副作用、開發者要主動處理。

三類 DOM 變動對 focus 的影響

每類有對應的處理 — 主要是「事前 save、事後 restore」。

搜尋頁的具體風險點

風險 1：Filter slot 跨 viewport 切換

位置：matchMedia callback 的 place() 函式。

1function place() {
2  if (mql.matches) slot.appendChild(filter);
3  else drawer.insertBefore(filter, drawer.firstChild);
4}

判讀：使用者鍵盤 focus 在 filter 內某個 checkbox、視窗 resize 跨過 1400px、appendChild 把 filter 整個搬到別處。理論上 focus 跟著節點走、實際視瀏覽器。

症狀：使用者按 tab 進到 filter checkbox、調視窗寬度跨 breakpoint、focus 突然在 body 或其他位置。

第一個該查的：

1function place() {
2  var activeBefore = document.activeElement;
3  if (mql.matches) slot.appendChild(filter);
4  else drawer.insertBefore(filter, drawer.firstChild);
5  // 嘗試還原 focus
6  if (activeBefore && filter.contains(activeBefore)) {
7    activeBefore.focus();
8  }
9}

activeElement 在 reparent 前後仍指向同一個 DOM 節點（如果 focus 在 filter 內）。明確 .focus() 確保視覺一致。

風險 2：Scope filter 隱藏當前 focus 元素

位置：scope filter 的 apply()。

1items.forEach(function (el) {
2  el.classList.toggle('is-scope-filtered', !show);
3});

判讀：若使用者 focus 在某個 result（例如標題連結）、切換 scope 後該 result 被隱藏（display: none）— focus 跳到 body。

症狀：使用者 tab 到 result、切 scope、focus 不見了。

第一個該查的：

 1function apply() {
 2  var activeBefore = document.activeElement;
 3  // ... 套用 scope filter
 4  if (activeBefore && getComputedStyle(activeBefore).display === 'none') {
 5    // 該元素被隱藏、focus 移到下一個可見的同類元素
 6    var nextResult = findNextVisibleResult(activeBefore);
 7    if (nextResult) nextResult.focus();
 8    else input.focus();   // 沒有下一個就回到 search input
 9  }
10}

明確處理「focus 元素被隱藏時去哪」、不留給瀏覽器預設行為。

風險 3：Pagefind 重繪結果時 focus 流失

位置：使用者改 query 時、pagefind 重新渲染結果列表。

判讀：若使用者 tab 到第 1 個結果、修改 query、pagefind 替換整個結果列表 — 第 1 個結果被 remove、focus 跳到 body。

症狀：使用者打字過程中、tab 順序時不時被打回起點。

第一個該查的：這個情境較難解 — 框架管的 DOM 我們不能干預。可行的做法：

• 使用者打字時通常在 input 上、focus 不在結果列表 — 影響面小
• 若真有需要、用 tabindex / aria-activedescendant 模擬 focus 但不實際 focus DOM

風險 4：載入 pagefind UI 時 focus 行為

位置：頁面載入後 PagefindUI mount 約 200-500ms。

判讀：使用者開啟搜尋頁、瀏覽器把 focus 放 body、使用者按 tab — 應該到搜尋輸入框。

症狀：使用者開頁面立刻按 tab、focus 跳到網站其他部分（nav、其他 link）、不是搜尋框。

第一個該查的：考慮頁面載入後自動 focus 搜尋輸入框（auto-focus）— 對搜尋頁是合理 UX、不是干擾。

1waitForElement(searchRoot, '.pagefind-ui__search-input', function (input) {
2  input.focus();
3});

內在屬性比較：四種 focus 處理策略

選擇順序：簡單變動用 save / restore；framework 管的 DOM 用模擬 focus；關鍵元素用 auto-focus。

盤點 focus 影響的具體步驟

對每個 JS 變動 DOM 的位置、列三個問題：

1. 這個變動會 reparent / remove / hide 哪些元素？
2. 這些元素有可能是當前 focus 嗎？ （form input、checkbox、link 都是常見 focusable）
3. 若是、focus 該去哪？ （restore / next sibling / 預設位置）

回答完三題、變動前後加 save / restore 邏輯。

設計取捨：DOM 變動時的 focus 處理策略

四種做法、各自機會成本不同。這個專案選 A（save / restore activeElement）當預設、其他做法在特定情境合理。

A：Save / restore activeElement（這個專案的預設）

• 機制：JS 變動 DOM 前 var activeBefore = document.activeElement、變動後 activeBefore.focus()
• 選 A 的理由：跨瀏覽器一致、簡單元件移動 / 顯隱都涵蓋
• 適合：自家管的 DOM 變動（reparent、display: none、remove）
• 代價：每個變動位置要顯式加 save / restore 邏輯（用 helper 包裝可一行）

B：不處理（依瀏覽器預設）

• 機制：JS 變動 DOM、不主動處理 focus
• 跟 A 的取捨：B 簡單、A 有額外邏輯；但 B 結果不一致（Chrome / Safari 不同）、多數預設是「focus 跳 body」、使用者迷失
• B 才合理的情境：純展示元素變動（沒有 focusable 子元素）— 不會發生 focus 掉失

C：用 tabindex / aria-activedescendant 模擬 focus

• 機制：focus 物理上不動、用 attribute 標記「邏輯 focus」
• 跟 A 的取捨：C 比 A 複雜、但能處理 framework 管的 DOM（無法 save / restore）
• C 比 A 好的情境：framework 持續重繪元素 identity、save / restore 失敗 — 用 attribute 表達 focus

D：Auto-focus 關鍵元素

• 機制：頁面載入後 / modal 開啟後自動 focus 預期的第一個元素
• 跟 A 的取捨：D 不依變動觸發、A 對應變動處理；D 適合「使用者預期」的初始 focus
• D 比 A 好的情境：搜尋頁載入 → focus search input、modal 開啟 → focus 第一個 input — 使用者預期的場景才用

判讀徵兆

核心原則：JS 變動 DOM = focus 副作用。每個變動位置都該回答「focus 該去哪」、不留給瀏覽器預設。

跟 #57 Loading / Empty / End 三狀態 共骨：兩者都是「狀態變動需要回答對應的 UX 問題」 — #57 講「使用者看到的訊號」、本卡講「鍵盤使用者的 focus 位置」。動態 UI 設計 = 狀態變動 + 狀態變動的 UX + 狀態變動的 a11y 三個維度同時設計。

動態內容變動對螢幕報讀軟體使用者預設不可見 — 要主動透過 aria-live region 把變動「廣播」給輔助技術。 沒 live region 的 UI 在視覺使用者眼裡很流暢、在 screen reader 使用者眼裡是「靜悄悄變了什麼但我不知道」。

為什麼動態內容需要主動廣播

商業邏輯

Screen reader 的工作模式：

第四種是動態 UI 的常見情境 — 使用者在 search input 上、結果列表變動 — screen reader 預設不知道。

aria-live 屬性告訴 screen reader「這個區域內容變動時、主動朗讀變動」。沒 aria-live、變動就沉默。

三類動態變動

polite 等使用者當前朗讀完才宣告、assertive 立刻打斷 — 多數場景用 polite。

搜尋頁的具體風險點

風險 1：Scope filter 切換後沒提示

位置：scope filter 的 apply() — 改變 result 顯示後沒有 aria 提示。

判讀：使用者切換 scope（標題 / 內文 / 全部）、UI 上結果數量變了 — screen reader 完全不知道。使用者可能繼續以為「189 筆結果」、實際只剩 4 筆。

症狀：screen reader 使用者切 scope 後、tab 到結果區、發現跟剛才不同、困惑。

第一個該查的：加 aria-live region 在 scope UI 旁邊、apply 後寫入訊息。

1<div class="search-scope" role="radiogroup" aria-label="搜尋範圍">
2  <!-- radios... -->
3</div>
4<div class="search-scope-status" aria-live="polite" aria-atomic="true"></div>

1function apply() {
2  // ... filter 邏輯
3  var visible = items.filter(el => !el.classList.contains('is-scope-filtered')).length;
4  document.querySelector('.search-scope-status').textContent = '篩選後 ' + visible + ' 筆結果';
5}

aria-atomic="true" 確保整個訊息每次都完整朗讀（而非只朗讀差異）。

風險 2：搜尋結果載入完成沒提示

位置：使用者打字、pagefind 載入結果 — UI 上 result 出現、但 screen reader 不知道載入完成。

判讀：使用者打字結束、預期「結果出來了」— 但需要主動 tab 過去確認、不像視覺使用者一眼看到。

症狀：使用者打字後不知道結果是否準備好、不知道是否該 tab 過去。

第一個該查的：pagefind 自身可能已實作 aria-live；若未、加一個 region 在結果區上方。

1<div class="search-results-status" aria-live="polite"></div>

1new MutationObserver(function () {
2  var count = items.length;
3  status.textContent = count + ' 筆結果符合搜尋';
4}).observe(resultsRoot, { childList: true });

風險 3：Filter 變動後沒提示

位置：使用者勾選 / 取消 filter checkbox、pagefind 自動更新結果。

判讀：勾選某個 tag、結果列表變動 — screen reader 看不到變動、若 focus 還在 checkbox 也沒朗讀。

症狀：螢幕報讀軟體使用者勾 filter、不知道有沒有效果。

第一個該查的：同上、aria-live region 反映「N 筆結果符合篩選」。

風險 4：「無結果」訊息

位置：搜尋字找不到任何結果。

判讀：頁面顯示「找不到 X 相關內容」、screen reader 若 focus 還在 input 不會朗讀。

症狀：screen reader 使用者打字後沒任何回應、不知道是「無結果」還是「還在搜尋」。

第一個該查的：把「無結果」訊息放 aria-live region 內、變動時自動朗讀。

Live region 的設計選擇

polite vs assertive

優先 polite — assertive 容易打斷使用者、感覺很突兀。

aria-atomic

對「N 筆結果」這類固定格式訊息、用 aria-atomic="true" 確保使用者聽到完整脈絡（不只朗讀數字變動）。

aria-relevant

預設只朗讀「新增 / 文字變動」、不朗讀「移除」。多數情境用預設即可。

內在屬性比較：四種動態內容廣播策略

優先選 aria-live="polite" + aria-atomic="true"、廣覆蓋且不打擾。

Live region 的常見錯誤

1. 動態建立 region

1var status = document.createElement('div');
2status.setAttribute('aria-live', 'polite');
3status.textContent = '...';
4document.body.appendChild(status);

不會生效 — screen reader 在 region 出現「之後」變動才朗讀、region 從無到有的瞬間不算。

正確：region 在 HTML 預先存在、JS 只更新內容。

2. 全頁加一個共用 region

可能導致訊息混淆 — 不同 source 的訊息共用同一個 region、難以追蹤。每個語意區域有自己的 region 較清楚。

3. 太頻繁的訊息

每次變動都廣播 — 使用者被 spam。Debounce + 重複內容跳過。

設計取捨：動態內容廣播策略

四種做法、各自機會成本不同。這個專案選 A（aria-live polite + aria-atomic）當預設、其他做法在特定情境合理。

A：aria-live="polite" + aria-atomic="true"（這個專案的預設）

• 機制：region 預先在 HTML、JS 寫入 textContent 觸發 polite 朗讀（等使用者當前朗讀完）
• 選 A 的理由：覆蓋多數動態變動、不打擾使用者當前操作
• 適合：搜尋結果數量變動、filter 切換、scope 改變等大多數 UI 變動
• 代價：訊息要等使用者當前朗讀完才聽到（最多幾秒延遲）

B：aria-live="assertive"

• 機制：立刻打斷使用者當前朗讀、強制聽新訊息
• 跟 A 的取捨：B 即時、A 禮貌；但 B 打斷感強、頻繁使用會讓使用者疲勞
• B 比 A 好的情境：真正緊急的訊息（錯誤 / 警告 / 安全提示）— 必須立刻知道

C：role="status" / role="alert"

• 機制：用 semantic role 取代 aria-live、語意更明確
• 跟 A 的取捨：C 跟 A 行為類似（status = polite、alert = assertive）、但 role 表達意圖更清楚
• C 比 A 好的情境：region 本身就是 status 或 alert 元素（語意對齊）

D：不處理（沉默）

• 機制：DOM 變動不通知 screen reader
• 成本特別高的原因：screen reader 使用者完全不知道有變動、UI 變得不可用
• D 才合理的情境：純視覺裝飾變動（背景動畫 / decorative）— 對 screen reader 使用者無意義

判讀徵兆

核心原則：UI 上「使用者沒主動觸發但有變動」的位置、screen reader 預設沉默 — 用 aria-live region 把沉默變成可聽見。

跟 #57 Loading / Empty / End 三狀態的區分 同源：兩者都是「狀態變動需要告知使用者」、aria-live 告訴的是 screen reader、#57 講的是視覺區分。完整的狀態變動 UX = 視覺區分 + aria-live 廣播。

有 native HTML element 提供的語意與行為時、永遠優先用 native — ARIA role 是「沒有 native 對應時的 fallback」、不是設計起點。 Native element 自帶 keyboard、focus、screen reader 行為；ARIA 是給作者宣告 semantic 的工具、需要作者自己補完所有行為。

為什麼 native 永遠優先

商業邏輯

ARIA 規範自己有一條 first rule：

First Rule of ARIA: If you can use a native HTML element with the semantics and behavior you require already built in, instead of re-purposing an element and adding an ARIA role, do so.

理由是 native element 提供「semantic + behavior」雙包裝：

ARIA role 只貼 semantic 標籤、不送行為 — 用 ARIA 等於承擔「補完所有行為」的責任。

何時 ARIA 是必要

ARIA 的設計用途是「補強 native」、不是「取代 native」。

搜尋頁的具體風險點

風險 1：Scope UI 用 div role="radiogroup" 而非 fieldset

位置：

1<div class="search-scope" role="radiogroup" aria-label="搜尋範圍">
2  <label><input type="radio" name="search-scope" value="all" checked><span>全部</span></label>
3  <!-- ... -->
4</div>

判讀：<div role="radiogroup"> 給 screen reader 看到「這是 radio group」、但作者要自己保證：

• 鍵盤方向鍵在選項間切換
• Tab 行為符合 radiogroup 慣例（tab 進到 group、方向鍵在內切換、tab 出 group）
• aria-required / aria-invalid 等狀態同步

<fieldset><legend> 是 native element：

• 自帶 group semantic
• legend 自動關聯為 group label
• 內部 <input type="radio" name="X"> 已是完整 radiogroup（HTML 內建）

症狀：screen reader 可能不認得自訂 radiogroup、無法用方向鍵切換。

第一個該查的：用 NVDA / VoiceOver 進入 radiogroup、按方向鍵看是否能切換。失敗則改用 fieldset。

1<fieldset class="search-scope">
2  <legend>搜尋範圍</legend>
3  <label><input type="radio" name="search-scope" value="all" checked> 全部</label>
4  <label><input type="radio" name="search-scope" value="title"> 標題</label>
5  <label><input type="radio" name="search-scope" value="content"> 內文</label>
6</fieldset>

name="search-scope" 同名讓三個 radio 自動成為 group、HTML 自帶方向鍵切換。

風險 2：用 <div onclick> 取代 <button>

位置：自訂按鈕 UI（搜尋頁未必有、但常見 anti-pattern）。

判讀：

• <button> 自帶 enter / space 觸發、tab focus、disabled 狀態
• <div onclick> 只有 click 事件、鍵盤無法觸發、tab 不會 focus

症狀：鍵盤使用者無法操作該 UI。

第一個該查的：找 <div onclick> / <span onclick> 的 pattern、改為 <button>。

風險 3：Pagefind 自身的 ARIA 實作

位置：Pagefind 的 <details><summary> filter blocks。

判讀：

• <details> / <summary> 是 native element、自帶 expand / collapse、enter 切換
• Pagefind 包了 .pagefind-ui__filter-name class 但底層仍是 native — 行為跟著
• 這是好的設計、不需要動

症狀：rare、native element 多半 OK。

第一個該查的：確認 Pagefind 沒用 div+role 重新實作這些 — 從 source 看大致符合 native first principle。

風險 4：Search input 用 <input type="search"> 還是 <input type="text">

位置：Pagefind 自身的 input。

判讀：

• <input type="search"> 在 mobile 顯示「搜尋」鍵盤、自帶清除按鈕
• <input type="text"> 純文字輸入

症狀：mobile 鍵盤不適配搜尋場景、額外清除 UI 自己做。

第一個該查的：確認 Pagefind 用 type="search"。從 pagefind-ui 渲染結果可看到 type="text"、有自訂的清除按鈕 — 可考慮是否值得改。

內在屬性比較：四種實作 radio group 的方式

優先順序：fieldset > div role + native input > div role + div role。

ARIA 使用的判斷流程

每個 UI 元素開始實作前、走這個流程：

 11. 有沒有 native element 對應？
 2   是 → 用 native（fieldset、button、input、details / summary）
 3   否 → 進 2
 4
 52. 有沒有 ARIA pattern 對應？
 6   是 → 用 div + role + 完整 ARIA 屬性 + 自己寫鍵盤行為
 7   否 → 進 3
 8
 93. 用 div + 自己想 semantic
10   注意：可能 screen reader 不認得、需要充分測試

多數情境停在 1 — native HTML 涵蓋常見 UI 模式。需要走到 2、3 的場景比想像中少。

設計取捨：實作 UI 元素的策略

四種做法、各自機會成本不同。這個專案永遠優先選 A（native HTML element）— 不夠用才退到 B / C / D。

A：純 native HTML element（永遠的首選）

• 機制：用 <button>、<fieldset><legend>、<details><summary>、<input type="search"> 等 native 元素
• 選 A 的理由：semantic + 鍵盤 + focus + form 整合「四件套」自帶、跨瀏覽器一致、跨 screen reader 一致
• 適合：所有 native 涵蓋的 UI 模式（按鈕、表單、disclosure、radio group）
• 代價：受 native 視覺預設限制、客製樣式可能要對抗 UA 預設

B：Native + ARIA 補強（aria-label / aria-describedby / aria-expanded）

• 機制：native element 加 ARIA 屬性補強 semantic 或表達動態狀態
• 跟 A 的取捨：B 在 A 的基礎上加細節、不取代
• B 比 A 好的情境：native 已涵蓋主要功能、需要補額外資訊（label、描述）或動態狀態（expanded / pressed / checked）

C：<div role="X"> + 完整 ARIA pattern + 自寫鍵盤行為

• 機制：用 div 包成 semantic 元素、加 role + 完整 ARIA + JS 補鍵盤
• 跟 A 的取捨：C 給更高客製彈性、A 拿成熟方案；C 維護成本高（要自己保證所有行為）
• C 比 A 好的情境：native 沒對應的 UI 模式（complex tree view、custom slider）— 必須自己定義 semantic

D：純 div + 自訂 semantic（無 ARIA）

• 機制：用 div 自己想 semantic、不加 role
• 成本特別高的原因：screen reader 不認得、鍵盤無法操作、違反 a11y 標準
• D 是反模式：違反 a11y 標準（屬合規 / 法規層）— 純視覺裝飾元素（無互動）才能例外

判讀徵兆

核心原則：ARIA 的 first rule 是「能用 native 就不用 ARIA」。Native element 是 50 年累積的瀏覽器 + 輔助技術知識結晶、不要繞道。

視覺輔助使用者跟一般使用者「看到的不是同一個 UI」 — 對比度、放大倍率、字型尺寸調整都會把版面變形。 設計時先盤點「在這些變形下、UI 還能用嗎」、不需要等到使用者反映。WCAG 提供量化標準、可以在開發階段驗證。

本篇焦點：視覺呈現面的 a11y（對比 / 放大 / 字型 zoom）。

• 鍵盤使用者的 a11y（focus indicator / tab 順序）由 #52 鍵盤可達性 處理
• 行動 / motor 使用者的 a11y（hit target / 點擊精準度）由 #53 Motor 可達性 處理

為什麼視覺輔助需要獨立盤點

商業邏輯

視覺輔助使用者的需求多元：

每類觸發不同的 CSS 行為。一個 UI 在標準視窗看起來 OK、放大 200% 後可能：

• 字超出容器
• Absolute 定位元件跑到視窗外
• 對比度被覆蓋（dark mode / 高對比模式）

WCAG（Web Content Accessibility Guidelines）提供量化標準（對比度 AA ≥ 4.5:1、放大 200% 不橫向 scroll）— 可在開發階段測量。

視覺呈現的三維度

三維度獨立、要分開檢查 — 一維度過 ≠ 全部過。

風險點 1：搜尋結果 highlight 對比度

位置：Pagefind 高亮命中關鍵字（黃底）。

判讀：

• 預設 --pagefind-ui-tag = #eeeeee（淺灰）— 文字 #393939（深灰）、對比 ~9:1、合格
• 但搜尋頁 dark mode 下、theme 可能讓文字變淺色 — 對淺底要驗證
• 色弱使用者看不出哪個字是 highlight（若僅靠顏色區分）

WCAG 標準：

第一個該查的：用 Chrome DevTools 的 Contrast Ratio 工具量 highlight 區域的「背景 vs 文字」對比。不足則覆寫 --pagefind-ui-tag 變數。

雙重保險：除了顏色、加 underline 或 bold 區分 highlight — 色弱使用者不靠顏色也能辨識。

風險點 2：Absolute 定位元件在放大模式下跑到視窗外

位置：.search-filter-slot { position: absolute; right: calc(100% + 2rem); }。

判讀：

• Absolute 定位相對 main 計算
• 使用者用 OS 螢幕放大鏡（macOS Zoom）放大 4x 看 main 中央
• main 仍在視窗範圍、但 absolute filter 在 main 左外側 — 放大 4x 後可能完全跑到視窗左邊看不見

症狀：低視力使用者用放大鏡時、不知道 filter 存在、無法操作。

第一個該查的：用 macOS 的 Zoom 功能（System Settings > Accessibility > Zoom）放大 4x、看 filter 是否仍在可達範圍。

修正方向：

詳細展開由 #43 最小必要範圍 + #27 runtime 量測模式統一 補充。

風險點 3：字型放大 200% 後 layout 破壞

位置：所有寫死 px 高度的元素（H1、search input、filter slot padding）。

判讀：

• 使用者用瀏覽器 zoom（Cmd +）通常等比放大 — 字 + box 一起放大、layout 不破
• 但 OS Display Scale（macOS Display > Larger Text）只放大字型不放大 box — 字撐爆寫死的 64px 高度

當 H1 字撐到 80px、寫死 height: 64px 的 box — 字被裁切。

症狀：低視力使用者開啟「文字放大」設定、UI 字被裁。

第一個該查的：開瀏覽器 zoom 200%、看 layout 是否變橫向 scroll（破壞）或仍 reflow（OK）。

WCAG 標準：1.4.4 Resize text — zoom 至 200% 時不需要橫向 scroll。

修正方向：

預設用 min-height + 相對單位、特殊精準對齊才用 ResizeObserver。

設計取捨：layout 適應字型放大

當「對齊精度」與「字型放大相容性」衝突、四種做法：

A：用 min-height + 相對單位（這個專案的預設）

• 機制：min-height: 4rem、box 隨字撐高、用 em / rem 跟著 scale
• 選 A 的理由：字型放大時 layout 自然 reflow、不裁切
• 適合：絕大多數 UI 元素、不需要極精準對齊
• 代價：對齊精度受字型 metrics 影響、難以做 pixel-perfect 對齊

B：寫死 height + ResizeObserver 量測補償

• 機制：height: 64px、用 ResizeObserver 量實際渲染高度寫回 CSS 變數、其他依賴此值的元素跟著調
• 跟 A 的取捨：B 達到 pixel-perfect 對齊、A 信任 reflow；B 多一層 JS 量測、A 純 CSS
• B 比 A 好的情境：對齊精度是 UX 核心（搜尋頁的視覺對齊）、字型可預期

C：寫死 height + 不處理字型放大

• 機制：height: 64px、不管字型放大
• 成本特別高的原因：字型放大時 UI 被裁切、低視力使用者無法用
• C 才合理的情境：UI 不會被字型放大影響（純圖示、無文字）

D：用 clamp(min, ideal, max) 限制字型大小

• 機制：字型 font-size: clamp(0.875rem, 1rem, 1.125rem)、限制使用者放大範圍
• 跟 A/B/C 的取捨：D 主動限制字型放大範圍、違反 WCAG 1.4.4
• D 是反模式：違反 WCAG 1.4.4 — 強制限制字型放大是反 a11y、低視力使用者完全無法調整

開發階段檢查清單

每個視覺輔助項目對應一個檢查動作：

每個 ~30 秒、開發完成前跑一輪、抓常見問題。

設計取捨：色彩區分策略

當資訊需要區分（hit / miss、selected / unselected）、四種做法：

A：顏色 + 形狀 / 位置雙重區分（這個專案的預設）

• 機制：highlight 用黃底 + bold；selected radio 用色彩 + ✓ 圖示
• 選 A 的理由：色弱使用者不靠顏色仍能辨識
• 適合：絕大多數需要區分資訊的場景
• 代價：UI 多一層視覺裝飾

B：純顏色區分

• 機制：紅色 = 錯、綠色 = 對
• 跟 A 的取捨：B 視覺乾淨、A 對色弱友善；B 違反 WCAG 1.4.1 Use of Color
• B 是反模式：違反 WCAG 1.4.1 Use of Color（合規層） — 色弱使用者完全無法區分對 / 錯

C：純形狀 / 位置區分（無顏色）

• 機制：用 ✓ / ✗ / 位置區分、不靠顏色
• 跟 A 的取捨：C 對色彩無關、A 對視力正常使用者更直覺
• C 比 A 好的情境：列印 / 黑白渲染環境

D：使用者可自訂顏色

• 機制：透過 CSS variable 讓使用者覆寫色彩
• 跟 A 的取捨：D 提供無限彈性、實作成本高
• D 才合理的情境：core a11y 工具（如 reading mode）

跟其他原則的關係

判讀徵兆

核心原則：視覺輔助使用者用的是「同一份程式、不同的 viewport / colour / scale」。WCAG 提供量化標準、開發階段可測 — 等使用者反映晚了。

鍵盤使用者導航三要素：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 秒、開發完成前跑一輪。

判讀徵兆

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

Hit target ≥ 44×44px、相鄰互動元素之間有間距、避免「精準瞄準」需求。 Motor accessibility 處理的不是視覺、是「手能否準確點擊」 — 行動裝置使用者、年長使用者、motor 障礙使用者都受益。設計時優先擴大 padding、不是縮小視覺。

本篇焦點：motor 可達性。

• 視覺呈現面的 a11y由 #40 視覺輔助 處理
• 鍵盤使用者的 a11y由 #52 鍵盤可達性 處理

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

使用者類型

最後一類包含「正常使用者在某些情境」 — motor a11y 的設計對全體使用者都有價值。

失敗模式

WCAG 標準

WCAG 2.2 把 motor a11y 從 AAA 拉到部分 AA — 顯示這類問題的重要性提升。

風險點 1：Hit target 太小

位置：scope UI 的 radio buttons、filter checkbox。

判讀：

• WCAG 2.5.5（AAA）建議互動元素 hit target ≥ 44×44px
• Native <input type="radio"> 在桌面 ~13×13px、行動裝置 24×24px
• label 包住 input + 文字、整個 label 可點 — 提升 hit target

症狀：行動裝置使用者點擊精準度不足、誤點旁邊選項。

第一個該查的：量 label 整體（含 padding）的高度與寬度。

修正方向：

 1/* 較差 — input 視覺很小、label 文字緊鄰 */
 2label { display: inline-block; }
 3input[type="radio"] { width: 13px; height: 13px; }
 4
 5/* 好 — label 整個區域可點、padding 撐到 44px */
 6label {
 7  display: inline-flex;
 8  align-items: center;
 9  padding: 0.625rem 1rem;  /* 約 44px 高 */
10  cursor: pointer;
11}
12input[type="radio"] { margin-right: 0.5rem; }

關鍵不是把 input 視覺變大、是把可點區域擴大（padding）— 視覺保持精緻、可點區域達標。

風險點 2：相鄰互動元素間距不足

位置：filter checkbox 列、scope radio 列。

判讀：

兩個 hit target 緊鄰、即使各自達 44px、相鄰時仍可能誤觸 — WCAG 2.5.8 要求「目標之間有足夠間距」。

症狀：使用者想點 A 但點到旁邊的 B。

修正方向：

 1/* 加 gap 確保相鄰元素間距 */
 2.filter-list {
 3  display: flex;
 4  flex-direction: column;
 5  gap: 8px;  /* 至少 8px 間距 */
 6}
 7
 8/* 或用 padding 撐開 */
 9.filter-list label {
10  padding: 0.625rem 1rem;
11  margin-bottom: 4px;  /* 加總間距達 8px+ */
12}

預設 8px 間距 — 比視覺需求多一點、避免誤觸。

風險點 3：需要精準 drag / pinch 的操作

位置：搜尋頁未實作 drag 互動、但若未來加（例如拖拽結果排序、pinch 縮放圖片）。

判讀：

WCAG 2.5.7（AA）要求 drag 動作有單擊替代 — 例如「拖拽排序」要有「上移 / 下移」按鈕作為替代。

症狀：motor 障礙使用者無法完成 drag 操作。

修正方向：

1<!-- 主互動：drag -->
2<li draggable="true">項目 A</li>
3
4<!-- 必須提供：button 替代 -->
5<li>
6  項目 A
7  <button aria-label="上移">↑</button>
8  <button aria-label="下移">↓</button>
9</li>

對搜尋頁當前實作不適用、但未來加互動時的預警。

設計取捨：擴大 hit target 的策略

當「視覺精緻度」與「hit target 大小」衝突、四種做法：

A：視覺保持小、padding 擴大可點區（這個專案的預設）

• 機制：input 視覺 13px、label padding 撐到 44px
• 選 A 的理由：視覺精緻 + a11y 達標、兩全
• 適合：絕大多數互動元素
• 代價：UI 整體高度增加（每行 44px+）

B：視覺直接放大到 44px

• 機制：input width: 44px; height: 44px;
• 跟 A 的取捨：B 視覺粗、A 視覺精緻；B 在「需要清楚看到」的情境（年長使用者）有價值
• B 比 A 好的情境：使用者主要是年長者、視覺辨識比精緻重要

C：視覺小、不擴 padding（不滿足 a11y）

• 機制：input 13px、label 緊鄰文字、無 padding
• 成本特別高的原因：行動使用者誤點、motor 障礙者無法用、違反 WCAG 2.5.8
• C 才合理的情境：純 desktop 應用 + 確認使用者群不含行動 / motor — 通常不該假設

D：用 hover area 擴大命中（hover 才放大）

• 機制：預設視覺小、hover 時擴大可點區
• 跟 A 的取捨：D 在 desktop 視覺精緻、hover 反饋也好；行動裝置沒有 hover、D 失敗
• D 比 A 好的情境：純 desktop 工具

設計取捨：誤點防護機制

對「誤點代價高」的操作（刪除 / 提交 / 付款）、四種做法：

A：直接觸發 + 後續 undo（這個專案的預設、若有此類操作）

• 機制：點擊立刻執行、提供 undo 機制（例如 toast「已刪除、5 秒內可復原」）
• 選 A 的理由：常見操作流暢、誤點有救
• 適合：可逆操作（刪除、移動、隱藏）
• 代價：實作 undo 機制需要儲狀態

B：點擊 → 確認對話框

• 機制：點擊出 confirm dialog「確定要 X 嗎？」
• 跟 A 的取捨：B 防誤點更強、A 流程更順；B 的成本是「正常使用者也要多一步」
• B 比 A 好的情境：不可逆操作（永久刪除、付款）

C：長按觸發

• 機制：需要長按 1 秒才觸發、誤點不會
• 跟 A/B 的取捨：C 對 motor 障礙不友善（需要持續按）、且不直觀
• C 是反模式：對 motor 障礙不友善（需要持續按 1 秒）— 不直觀、違反 a11y 預期互動

D：拖到「確認區」

• 機制：滑動到特定區域才觸發（iOS 拖刪除）
• 跟 A/B 的取捨：D 對非典型互動使用者不直觀、違反 WCAG 2.5.7（需 button 替代）
• D 才合理的情境：搭配 button 替代（drag + button 兩種途徑都行）

開發階段檢查清單

跟其他原則的關係

判讀徵兆

核心原則：Motor a11y 是「手能否準確點擊」 — 不只給 motor 障礙使用者、行動使用者 / 年長者 / 暫時受限使用者都受益。預設 padding 擴 44px、間距 8px、不可逆操作加 confirm — 這些是基礎、不是優化。

Tab 順序 = DOM 順序 = 使用者 mental model 的互動順序、三者該對齊。

三者偏差的後果：

• DOM ≠ mental model：視覺 / tab 順序跟使用者期望不一致、a11y 體驗差
• DOM ≠ tab order（用 tabindex > 0）：DOM 改變時 tab 順序維護成本爆炸（#52 反模式）
• 全對齊：DOM 簡單、tab 自然、a11y 預設正確

要解決不對齊、優先重排 DOM、不要用 tabindex 強制覆寫。

為什麼三者該對齊到 DOM 順序

Tab 順序跟 DOM 順序綁定是 spec 規定

HTML5 spec：tabbable elements 預設依 source order（DOM 順序）navigate。要改變只能用 tabindex 覆寫。

tabindex 三種值：

tabindex > 0 反模式（同 #52 鍵盤可達性）：

• 全頁面只要有任何元素用 tabindex > 0、整個 tab 順序變混亂（其他 0 / 不寫的元素都被推到後面）
• 維護成本：DOM 改了、所有 tabindex > 0 的數值都要重排
• A11y：screen reader 跟視覺使用者體驗到不同順序

唯一合法用法：要把元素「移出 tab cycle」用 tabindex="-1"（例如 modal 開啟時鎖住背景）。

Mental model 順序由 UI 設計決定

互動式 UI 隱含一個流程：使用者預期「先做 X 再做 Y」。例如：

設計者腦中有這個順序、寫 HTML 時要把它具體化成 DOM 順序。DOM 順序就是把 mental model 寫進 code 的方式。

多面向：常見不對齊 case

面向 1：Filter 在 search input 之前（這次任務的 case）

1<!-- DOM 順序：scope 先 → search input 後 -->
2<div class="search-scope">...</div>
3<div id="search"></div>  <!-- pagefind input 在裡面 -->

Tab 順序：scope radios → search input。但 mental model 是「先打字再篩選」、Tab 應該先到 input。

修法：DOM 重排、把 scope 移到 #search 之後。視覺位置由 CSS position: absolute 控制、不受 DOM 順序影響。

面向 2：Submit 按鈕在 form 中間

1<form>
2  <input name="email">
3  <button type="submit">送出</button>  <!-- 太早 -->
4  <textarea name="message"></textarea>
5</form>

Tab 順序：email → submit → textarea。使用者打完 email 按 Enter 就送出、textarea 還沒填。

修法：submit 移到所有 input 之後。

面向 3：Logo / nav 在主要 CTA 之前

1<header>
2  <a href="/">Logo</a>
3  <nav>... 5 個 links ...</nav>
4</header>
5<main>
6  <button>主要 CTA</button>  <!-- 使用者要按這個 -->
7</main>

Tab 順序：6 個 nav links → CTA。使用者要 tab 6 次才到 CTA。

修法：考慮加 「skip to main content」link（A11y 標準做法）— <a href="#main-content" class="skip-link">。第一個 tab 就跳過 nav 到 main。

面向 4：Modal 開啟時 background 仍 tabbable

1<div class="background-content">
2  <a href="...">某連結</a>  <!-- 仍可 tab 到 -->
3</div>
4<div role="dialog">
5  <input>
6  <button>確認</button>
7</div>

Tab 順序：背景連結 → modal input → confirm。使用者 tab 出 modal 跑回背景。

修法：modal 開啟時、用 inert attribute（modern）或所有背景元素設 tabindex="-1"（傳統）把它們踢出 cycle。<dialog> native 自動處理。

不對齊的修法：優先重排 DOM

第一順位：重排 DOM

把元素照 mental model 順序排在 HTML / template 裡。視覺位置如果跟 DOM 順序不同、用 CSS order（flex / grid）、position: absolute、grid-template-areas 控制。

1<!-- DOM 順序對齊 mental model：input → scope → drawer -->
2<div id="search"></div>
3<div class="search-scope">...</div>

1/* 視覺：scope 浮在 input 跟 drawer 之間（跟 DOM 順序無關） */
2.search-shell { position: relative; }
3.search-scope {
4  position: absolute;
5  top: calc(var(--input-h) + 8px);
6}

Tab 順序自然對齊 DOM、視覺位置由 CSS 獨立控制 — 兩個維度解耦、不互相影響。

第二順位：JS 動態移動 DOM

如果元素因為 framework 限制無法 hard-coded 在對的位置（例如某 vendor library 強制 mount 點）、用 JS 在 mount 後 reparent 元素到對的位置。

1// PagefindUI mount 後、把 scope 移到 input 跟 drawer 之間（如果 framework 允許）
2const scope = document.querySelector('.search-scope');
3const drawer = document.querySelector('.pagefind-ui__drawer');
4drawer.parentElement.insertBefore(scope, drawer);

風險：framework 重渲染可能 reparent 回去（#5 framework-managed DOM）。要驗證穩定性。

第三順位（不推薦）：tabindex 強制

1<input tabindex="1" name="search">  <!-- 反模式：tabindex > 0 -->
2<div tabindex="2" class="search-scope">...</div>

只在前兩種都做不到時用。維護成本高、a11y 跟設計工具支援差。

不該套用本原則的情境

「DOM = tab = mental model 三者對齊」原則在多數情境成立、但有合理例外：

四類共同特徵：沒有清楚的「使用者該先做 X 再做 Y」流程 — 本原則建立在「有 mental model 可對齊」上、沒有時自然不適用。

跟其他抽象層原則的關係

對應的實作篇

• 搜尋頁 scope filter 在 search input 之前的 tab 順序問題 — Checkpoint 1 retrospective 找到（#68 dogfooding）
• 任何「先選範圍再操作」vs「先操作再選範圍」的 UI 設計 — 都該檢視 tab order 是否對齊

判讀徵兆

核心原則：DOM 順序是寫進 code 的 mental model、tab 順序是使用者體驗的 mental model — 兩者該由「重排 DOM」對齊、不該由「tabindex」強制。視覺位置跟 DOM 順序解耦（用 CSS 控制）、讓兩者各自獨立優化。

適用：寫互動 UI、JS reparent / hide 元素、自製 component（modal / dropdown / tabs）、客製外部組件後檢查 a11y。 不適用：純後端 / 純資料流（沒有使用者直接互動）。

自包含聲明：閱讀本文件不需要先讀其他 reference。本文件涵蓋鍵盤可達性三要素、focus management 模板、aria-live 設計、native HTML 優先原則。

何時參閱本文件

為什麼 a11y 是預設不是補丁

A11y 不是「完整功能後再加上」、是設計時就決定的結構：

• 用 <button> vs <div onclick> → 鍵盤 / focus / a11y tree 自帶 vs 全部要自己補
• modal 用 <dialog> vs 自己組 → focus trap / escape / scrollable / inert 自帶 vs 全部要自己補
• 動態內容變動有 aria-live vs 沒 → screen reader 知道 vs 不知道

事後補 a11y 比事前設計貴 5-10 倍。寫之前先選對結構、後續成本低。

防線 1：靜態鍵盤可達性三要素

鍵盤使用者要能用、三個元素缺一不可：

要素 1：Visible focus indicator

1/* 反例：去掉預設 focus outline */
2button:focus { outline: none; }
3
4/* 對例：可見的 focus indicator */
5button:focus-visible {
6  outline: 2px solid var(--focus-color);
7  outline-offset: 2px;
8}

:focus-visible（鍵盤 focus）跟 :focus（含滑鼠 click 後）區分 — 滑鼠使用者不需要看到 outline、鍵盤使用者必須看到。

要素 2：邏輯 Tab 順序

Tab 順序預設由 DOM tree 決定。如果視覺順序跟 DOM 順序不同（例如用 CSS grid 重排），考慮：

• 重排 DOM 順序對齊視覺
• 用 tabindex="0" 讓元素可 focus（不要用 > 0）
• 不要用 tabindex="-1" 跳過該 focus 的元素

要素 3：Modal / drawer 有 escape 路徑

1dialog.addEventListener('keydown', (e) => {
2  if (e.key === 'Escape') dialog.close();
3});

或用 <dialog> native — Escape 自帶。

防線 2：動態 a11y

Focus management on DOM move

JS reparent / hide 元素時、focus 會跑掉（落到 body）。需要保存與還原：

 1function moveFilter(targetSlot) {
 2  const filter = document.querySelector('.filter');
 3  const focused = document.activeElement;
 4  const wasFilterFocused = filter.contains(focused);
 5
 6  targetSlot.appendChild(filter);  // reparent
 7
 8  if (wasFilterFocused) {
 9    focused.focus();  // 還原 focus
10  }
11}

aria-live 廣播動態變動

Screen reader 預設不會朗讀「DOM 變動」、要明確告訴它：

1<!-- polite：等使用者操作完才朗讀（搜尋結果數量、filter 切換） -->
2<div aria-live="polite" aria-atomic="true">
3  顯示 12 筆結果
4</div>
5
6<!-- assertive：立刻打斷朗讀（錯誤訊息、緊急狀態） -->
7<div aria-live="assertive" role="alert">
8  搜尋失敗、請重試
9</div>

aria-atomic="true" 整段重讀（不只朗讀變動的部分）。

範例：搜尋結果區

1<div class="results" aria-live="polite" aria-atomic="false">
2  <p class="status">顯示 <span id="count">12</span> 筆結果</p>
3  <ul>...</ul>
4</div>

JS 更新 #count 的 textContent 時、screen reader 朗讀「顯示 12 筆結果」。

防線 3：Native HTML > ARIA

為什麼優先 Native

何時用 ARIA

ARIA 是補強、不是替代：

• 用 native 但 a11y tree 還不夠（標 aria-label / aria-describedby 補語意）
• 真的沒有 native 元素（complex composite widget、tabs、tree）
• 動態變動需要廣播（aria-live）

範例：自製 toggle 還是 native checkbox

錯：

1<div class="toggle" role="switch" tabindex="0" aria-checked="false">
2  <span class="track"></span>
3</div>
4<script>
5  toggle.addEventListener('click', ...);
6  toggle.addEventListener('keydown', e => {
7    if (e.key === 'Enter' || e.key === ' ') ...;
8  });
9</script>

對：

1<label class="toggle">
2  <input type="checkbox">
3  <span class="track" aria-hidden="true"></span>
4  <span class="visually-hidden">啟用 dark mode</span>
5</label>

1.toggle input { position: absolute; opacity: 0; }
2.toggle input:checked + .track { background: var(--brand); }

Native checkbox 自帶 keyboard / focus / state、CSS 把它隱藏、視覺用 .track 呈現。

視覺 / Motor a11y

視覺輔助

 1/* 對比度 */
 2:root { --text: #1a202c; --bg: #fff; }
 3/* WCAG AA: 普通文字 4.5:1、大文字 3:1 */
 4
 5/* 字型放大時不破版 */
 6.container { max-width: 60ch; }  /* ch 跟字型同步 */
 7.text { font-size: 1rem; line-height: 1.6; }  /* rem 跟使用者設定同步 */
 8
 9/* prefers-reduced-motion */
10@media (prefers-reduced-motion: reduce) {
11  * { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; }
12}

Motor / Hit target

1/* 觸控 hit target 最小 44×44 px (WCAG AAA) */
2button, a, [role="button"] {
3  min-height: 44px;
4  min-width: 44px;
5}
6
7/* 兩個 hit target 之間留 8px+ 間距、避免誤點 */
8.toolbar > * + * { margin-left: 8px; }

Wrong vs Right 對照

範例 1：自製 dropdown

錯：

1<div class="dropdown" tabindex="0">
2  <span>選單</span>
3  <div class="menu">
4    <div class="item">選項 1</div>
5    <div class="item">選項 2</div>
6  </div>
7</div>

問題：no native focus、no keyboard、no a11y role、screen reader 不知道是 menu。

對：

1<button aria-haspopup="menu" aria-expanded="false" aria-controls="menu1">
2  選單
3</button>
4<ul id="menu1" role="menu" hidden>
5  <li role="menuitem"><button>選項 1</button></li>
6  <li role="menuitem"><button>選項 2</button></li>
7</ul>

或如果是「選擇一個」 → <select> native。

範例 2：filter 切換沒 a11y broadcast

錯：

1button.addEventListener('click', () => {
2  document.querySelectorAll('.result').forEach(r => {
3    r.style.display = r.dataset.tag === currentFilter ? 'block' : 'none';
4  });
5});
6// screen reader 不知道結果變了

對：

1<div class="results" aria-live="polite">
2  <p class="status">顯示 <span id="count">12</span> 筆結果（filter: <span id="filter">全部</span>）</p>
3</div>

1button.addEventListener('click', () => {
2  // ... filter logic
3  document.getElementById('count').textContent = visibleCount;
4  document.getElementById('filter').textContent = currentFilter;
5  // aria-live 自動朗讀
6});

範例 3：JS 移動元素 focus 跑掉

錯：

1// resize 時把 filter 從 mobile drawer 移到 desktop sidebar
2mediaQuery.addEventListener('change', () => {
3  if (mediaQuery.matches) {
4    sidebar.appendChild(filter);
5  } else {
6    drawer.appendChild(filter);
7  }
8});
9// 如果 filter 內的某個 input 有 focus、reparent 後 focus 落到 body

對：

 1mediaQuery.addEventListener('change', () => {
 2  const focused = document.activeElement;
 3  const wasInFilter = filter.contains(focused);
 4
 5  if (mediaQuery.matches) {
 6    sidebar.appendChild(filter);
 7  } else {
 8    drawer.appendChild(filter);
 9  }
10
11  if (wasInFilter) focused.focus();  // 還原 focus
12});

自檢清單（dogfooding）

寫互動 UI 時：

• 用 <button> <dialog> <details> <fieldset> 取代自製 ARIA 結構？
• visible focus indicator 沒被 outline: none 拿掉？
• Tab 順序符合視覺順序（沒用 tabindex > 0）？
• Modal / drawer 有 Escape 關閉路徑？
• JS reparent / hide 時保存與還原 focus？
• 動態變動內容用 aria-live 廣播？
• 對比度 ≥ 4.5:1（普通文字）？
• Hit target ≥ 44×44 px？
• prefers-reduced-motion 時關掉動畫？

延伸閱讀

對應的事後檢討（在 content/report/）：

• focus-management-on-dom-move — 動態 DOM 移動時的 focus 管理
• aria-live-for-dynamic-content — Screen reader 與動態內容變動的 live region 設計
• native-html-over-aria-role — Native HTML element 優先於 ARIA role 的取捨
• keyboard-accessibility — 鍵盤可達性：focus indicator、tab 順序、escape 路徑
• motor-accessibility-hit-target — Motor 可達性：hit target、間距、誤點防護
• visual-aids-contrast-zoom-responsive — 視覺輔助：對比度、放大、字型 zoom 的 layout 適配

Last Updated: 2026-04-26 Version: 0.1.0

frontend-with-playwright 是一套前端開發協議 skill，原生位置在 .claude/skills/frontend-with-playwright/ 供 Claude runtime 呼叫；這份是同內容的文章版本，讓人類讀者也能直接在 blog 閱讀。

原則框架無關 — 適用 vanilla HTML/CSS/JS、Vue、React、jQuery — 因為核心是「DOM / CSS / JS 三者的本質行為」加上「Playwright 用 live DOM 量測驗證」、不依賴特定框架的渲染機制。源頭是 content/report/ 累積的 50+ 篇事後檢討、由本 skill 的六份 reference 萃取對應六個情境的協議步驟。

閱讀順序

場景 1：第一次接觸

場景 2：已熟悉協議、想直接解決當前任務

直接依觸發情境跳對應 reference：

每份 reference 自包含：讀任一份不需要回頭讀其他 reference。

跟 requirement-protocol 的關係

requirement-protocol 是上層的「對話協議」（澄清需求、失敗轉折、覆寫成本、工具切換時機）；本 skill 是下層的「前端執行協議」（DOM / CSS / JS / Playwright 的具體做法）。

兩個 skill 的 playwright 段落互補：requirement-protocol 講「何時切」、本 skill 講「切了之後具體寫什麼 query」。

與 blog 專案其他資料的關係

Last Updated

2026-04-26 — v0.2.0 接入 #55-#68 系列：新增第 7 份 reference data-flow-and-filter-composition（Filter × Source 層錯位 + 五策略 + 跨前端 / 後端 / 演算法 / DB 範例）；強調原則跨領域通用、不只前端。

歷史版本：

• 2026-04-26 — v0.1.0 初版：六份 references 對應「DOM topology / CSS-JS 邊界 / Playwright 三位置 / framework 共處 / Reactive 效能 / A11y」六個情境