fixing-accessibility

fixing-accessibility

修復無障礙問題。

使用方式

• /fixing-accessibility
  將這些限制套用至本次對話中的所有 UI 工作。

• /fixing-accessibility <file>
  根據以下所有規則審查該檔案，並回報：

  • 違規項目（引用確切行數或片段）
  • 為何重要（一句簡短說明）
  • 具體修復方式（程式碼層級建議）

請勿大規模重寫 UI。偏好最小且針對性的修復。

何時套用

在以下情況參考這些準則：

• 新增或修改按鈕、連結、輸入框、選單、對話框、分頁、下拉選單
• 建構表單、驗證、錯誤狀態、輔助文字
• 實作鍵盤快捷鍵或自訂互動
• 處理焦點狀態、焦點鎖定或模態行為
• 渲染僅圖示的控制項
• 新增僅懸停互動或隱藏內容

依優先順序的規則分類

優先級	分類	影響
1	可存取名稱	嚴重
2	鍵盤存取	嚴重
3	焦點與對話框	嚴重
4	語意	高
5	表單與錯誤	高
6	宣告	中高
7	對比與狀態	中
8	媒體與動畫	低中
9	工具邊界	嚴重

快速參考

1. 可存取名稱（嚴重）

• 每個互動控制項都必須有可存取名稱
• 僅圖示按鈕必須有 aria-label 或 aria-labelledby
• 每個 input、select 和 textarea 都必須有標籤
• 連結必須有有意義的文字（不要用「點這裡」）
• 裝飾性圖示必須設為 aria-hidden

2. 鍵盤存取（嚴重）

• 不要將 div 或 span 當作按鈕使用，除非有完整的鍵盤支援
• 所有互動元素必須可透過 Tab 鍵到達
• 鍵盤使用者必須能看到焦點
• 不要使用大於 0 的 tabindex
• Escape 鍵必須關閉對話框或覆蓋層（若適用）

3. 焦點與對話框（嚴重）

• 模態框開啟時必須鎖定焦點
• 關閉時將焦點歸還給觸發元素
• 在對話框內設定初始焦點
• 開啟對話框不應意外捲動頁面

4. 語意（高）

• 優先使用原生元素（button、a、input）而非基於角色的 hack
• 若使用角色，必須有必要的 aria 屬性
• 列表必須使用 ul 或 ol 搭配 li
• 不要跳過標題層級
• 表格在適用時必須使用 th 作為標題

5. 表單與錯誤（高）

• 錯誤必須使用 aria-describedby 連結到欄位
• 必填欄位必須被宣告
• 無效欄位必須設定 aria-invalid
• 輔助文字必須與輸入框關聯
• 停用的提交動作必須說明原因

6. 宣告（中高）

• 重大表單錯誤應使用 aria-live
• 載入狀態應使用 aria-busy 或狀態文字
• 提示訊息不應是傳達重要資訊的唯一方式
• 可展開的控制項必須使用 aria-expanded 和 aria-controls

7. 對比與狀態（中）

• 確保文字和圖示有足夠的對比
• 僅懸停的互動必須有鍵盤對應
• 停用狀態不能僅依賴顏色
• 不要移除焦點外框，除非有可見的替代方案

8. 媒體與動畫（低中）

• 圖片必須有正確的替代文字（有意義或空白）
• 含有語音的影片應在相關時提供字幕
• 對於非必要的動畫，尊重 prefers-reduced-motion
• 避免自動播放有聲音的媒體

9. 工具邊界（嚴重）

• 偏好最小變更，不要重構不相關的程式碼
• 若原生語意已解決問題，不要添加 aria
• 除非要求，否則不要遷移 UI 函式庫

常見修復

<!-- 僅圖示按鈕：添加 aria-label -->
<!-- 修改前 --> <button><svg>...</svg></button>
<!-- 修改後 -->  <button aria-label="關閉"><svg aria-hidden="true">...</svg></button>

<!-- div 當作按鈕：使用原生元素 -->
<!-- 修改前 --> <div onclick="save()">儲存</div>
<!-- 修改後 -->  <button onclick="save()">儲存</button>

<!-- 表單錯誤：使用 aria-describedby 連結 -->
<!-- 修改前 --> <input id="email" /> <span>無效的電子郵件</span>
<!-- 修改後 -->  <input id="email" aria-describedby="email-err" aria-invalid="true" /> <span id="email-err">無效的電子郵件</span>

審查指引

• 先修復嚴重問題（名稱、鍵盤、焦點、工具邊界）
• 在添加 aria 之前，優先使用原生 HTML
• 引用確切片段，說明失敗原因，提出小修復
• 對於複雜元件（選單、對話框、組合框），偏好使用已建立的可存取基本元件而非自訂行為