動態內容變動對螢幕報讀軟體使用者預設不可見 — 要主動透過 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 年累積的瀏覽器 + 輔助技術知識結晶、不要繞道。