無障礙審計員
審計網頁應用程式的無障礙合規性(WCAG 2.1 Level AA)並提供改善建議。
使用時機
- 建構或審查 UI 元件時
- 用戶要求無障礙性改善
- 準備進行無障礙審計
- 用戶提到「accessibility」、「a11y」、「WCAG」、「screen reader」或「keyboard navigation」
操作說明
1. 語義 HTML 檢查
使用正確的 HTML 元素:
<!-- 錯誤 -->
<div onclick="submit()">Submit</div>
<!-- 正確 -->
<button onclick="submit()">Submit</button>
語義結構:
<header>、<nav>、<main>、<footer><article>、<section>、<aside><h1>至<h6>保持正確層級<button>用於動作,<a>用於導航
2. ARIA 屬性
何時使用 ARIA:
- 自訂 Widget(標籤頁、折疊面板、對話框)
- 動態內容更新
- 複雜互動
- 語義 HTML 不足時
常見 ARIA 屬性:
<!-- 地標角色 -->
<nav role="navigation" aria-label="主導航">
<!-- Widget 角色 -->
<div role="button" tabindex="0" aria-pressed="false">
<!-- 即時區域 -->
<div role="alert" aria-live="assertive">發生錯誤</div>
<!-- 標籤與說明 -->
<button aria-label="關閉對話框">×</button>
<input aria-describedby="password-help" />
ARIA 第一條規則: 如果語義 HTML 可用,就不要使用 ARIA
3. 鍵盤導航
所有互動元素必須可透過鍵盤操作:
// 為自訂元素加入鍵盤支援
<div
role="button"
tabindex="0"
onClick={handleClick}
onKeyDown={(e) => {
if (e.key === 'Enter' || e.key === ' ') {
handleClick();
}
}}
>
點擊我
</div>
Tab 順序:
- 自訂互動元素使用
tabindex="0" - 避免使用
tabindex > 0(會造成混亂的 Tab 順序) - 僅在需要程式焦點時使用
tabindex="-1"
焦點管理:
- 可見的焦點指示器
- 在對話框中鎖定焦點
- 關閉對話框時返回焦點
- 為主要內容提供跳過連結
4. 替代文字與圖片
資訊型圖片:
<img src="chart.png" alt="第三季銷售額成長 25%" />
裝飾型圖片:
<img src="decoration.png" alt="" />
<!-- 或 -->
<img src="decoration.png" role="presentation" />
複雜圖片:
<figure>
<img src="complex-chart.png" alt="每季銷售圖表" />
<figcaption>
圖表資料的詳細說明……
</figcaption>
</figure>
5. 色彩與對比度
對比度(WCAG AA):
- 一般文字:至少 4.5:1
- 大字體(18pt 以上):至少 3:1
- UI 元件:至少 3:1
不要僅依賴顏色:
<!-- 錯誤:僅用顏色 -->
<span style="color: red;">錯誤</span>
<!-- 正確:圖示 + 顏色 -->
<span style="color: red;">
<svg aria-hidden="true"><!-- 錯誤圖示 --></svg>
<span class="sr-only">錯誤:</span>
輸入無效
</span>
6. 表單與標籤
每個輸入欄位都需要標籤:
<!-- 明確標籤 -->
<label for="email">電子郵件</label>
<input id="email" type="email" />
<!-- 隱含標籤 -->
<label>
電子郵件
<input type="email" />
</label>
<!-- 圖示按鈕使用 aria-label -->
<button aria-label="搜尋">
<svg><!-- 搜尋圖示 --></svg>
</button>
錯誤訊息:
<input
id="password"
aria-invalid="true"
aria-describedby="password-error"
/>
<div id="password-error" role="alert">
密碼長度必須至少 8 個字元
</div>
7. 標題與文件結構
正確的標題層級:
<h1>頁面標題</h1>
<h2>第一節</h2>
<h3>子節 1.1</h3>
<h3>子節 1.2</h3>
<h2>第二節</h2>
不要跳過層級: h1 → h2 → h3(不要 h1 → h3)
8. 動態內容
向螢幕閱讀器宣告更新:
<!-- 有禮:等待用戶暫停 -->
<div role="status" aria-live="polite">
5 封新訊息
</div>
<!-- 果斷:立即中斷 -->
<div role="alert" aria-live="assertive">
您的連線將在 1 分鐘後過期
</div>
載入狀態:
<button aria-busy="true" aria-label="載入中……">
<span aria-hidden="true">載入</span>
</button>
9. 螢幕閱讀器測試
僅對螢幕閱讀器顯示的文字:
.sr-only {
position: absolute;
width: 1px;
height: 1px;
padding: 0;
margin: -1px;
overflow: hidden;
clip: rect(0, 0, 0, 0);
white-space: nowrap;
border-width: 0;
}
隱藏裝飾性元素:
<svg aria-hidden="true"><!-- 圖示 --></svg>
10. 常見檢查問題
遺漏:
- 圖片的替代文字
- 表單輸入欄位的標籤
- 正確的標題層級
- 鍵盤焦點指示器
- 圖示按鈕的 ARIA 標籤
不當:
- 低對比度文字
- 非語義標記(如用 div 當按鈕)
- 對話框中缺少焦點管理
- 鍵盤陷阱
- 自動播放媒體
測試:
- 僅使用鍵盤導航
- 螢幕閱讀器(NVDA、JAWS、VoiceOver)
- 色盲模擬
- 縮放至 200%
- 自動化工具(axe、Lighthouse)
11. 自動化測試
工具:
# Lighthouse
npx lighthouse https://example.com --only-categories=accessibility
# axe-core
npm install --save-dev @axe-core/cli
npx axe https://example.com
# pa11y
npm install --save-dev pa11y
npx pa11y https://example.com
在測試中使用:
import { axe } from 'jest-axe';
test('不應有無障礙違規', async () => {
const { container } = render(<MyComponent />);
const results = await axe(container);
expect(results).toHaveNoViolations();
});
12. WCAG 2.1 Level AA 檢查清單
可感知:
- 非文字內容的文字替代
- 音訊/影片的字幕
- 內容可適配(語義標記)
- 足夠的色彩對比
可操作:
- 可透過鍵盤操作
- 無鍵盤陷阱
- 適當的時間限制(可調整)
- 無誘發癲癇的閃爍
- 跳過導覽連結
- 描述性的頁面標題
- 焦點順序合理
- 連結目的從上下文清楚可知
可理解:
- 指定頁面語言(
<html lang="en">) - 可預測的導航
- 輸入輔助(標籤、指示、錯誤訊息)
穩健:
- 有效的 HTML
- 自訂 Widget 的名稱、角色、值
- 與輔助技術相容
最佳實踐
- 從一開始就建構無障礙性
- 使用真實的輔助技術進行測試
- 優先使用語義 HTML,其次才是 ARIA
- 保持邏輯的文件結構
- 提供多種存取內容的方式
- 徹底測試鍵盤導航
- 不要停用縮放
- 使用地標與標題
支援檔案
reference/wcag-checklist.md:完整 WCAG 2.1 AA 檢查清單reference/aria-patterns.md:常見 ARIA Widget 模式


