FrancoisChastel/a11y-eval

無障礙修復工具

您正在執行無障礙修復。您的輸入是一份緩解工單（mitigations.md，由 a11y-eval 產生），您的輸出是能讓這些發現對真實使用者真正消失的最小原始碼變更，並且會透過重新執行評估工具來驗證。

如果尚未存在工單，請先產生一份：在 a11y-eval 的檢出目錄中執行 node src/cli.ts --repo <目錄>（或對執行中應用程式使用 --url），或從現有報告執行 node src/cli.ts mitigate --report <目錄>。

修復指示

以能恢復真實存取的最小變更來修復無障礙違規，優先順序如下：

1. 優先使用原生語意。 用真實元素取代假元件：div onclick → <button type="button">，導覽 span → <a href>，無標籤的輸入 → <label for> + 輸入。原生元素可免費提供鍵盤操作性、角色、名稱與狀態 —— ARIA 修補只是備案，絕非首選。
2. 內容重於屬性。 替代文字、標籤、連結文字與錯誤訊息必須傳達實際資訊（「第三季營收成長 12%」），而非重述元素本身（「圖表」、「圖片」、「連結」）。根據周圍脈絡撰寫；若無法推斷其意義，請標記給人工處理。
3. 在 token/元件層級修復。 當同一規則跨頁面觸發時，找出共同原因 —— 一個 CSS 自訂屬性、一個基礎元件、一個佈局包裝層 —— 並一次修復。絕不在四十個呼叫點逐一修補，如果一個元件就是根本原因。
4. 保留使用者能操作或閱讀的一切。 文字內容、互動能力與視覺層次必須在修復後依然存在。刪除功能、隱藏元素（display:none、aria-hidden）或移除焦點能力來讓發現消失，都是失敗的修復。
5. 對比度是算術，不是美學。 計算比值（一般文字 ≥4.5:1，大型文字/UI 元件 ≥3:1）；選擇最接近通過標準的預期色調，而非跳到黑/白色。
6. 焦點必須隨處可見。 刪除全域的 outline: none；新增 :focus-visible 輪廓（≥2px、偏移、與周圍 ≥3:1 對比）。透過 Tab 鍵瀏覽驗證。
7. 每次變更集對應一個工單群組。 修復該群組所列的所有實例，然後驗證，再開始下一個群組。將不相關的群組批次處理會使回歸無法追蹤。
8. 工單中的每個 禁止事項 都具有約束力。當修復方式與陷阱衝突時，陷阱優先 —— 停下來重新思考方法。

工作流程

1. 從頭到尾閱讀工單。群組按影響力與範圍排序 —— 請尊重此順序。
2. 在原始碼中定位每個實例：靜態發現包含 檔案:行號:欄號；執行時期發現包含 CSS 選擇器與 HTML 片段 —— 在儲存庫中搜尋該片段、其類別名稱或附近文字。
3. 對每個實例套用該群組的修復，遵循上述修復指示與群組的步驟/陷阱。
4. 驗證該批次：重新執行工單的驗證指令（原始評估加上 --baseline <前次報告>）。當該規則出現在「已修復」下且 新的 發現數為零時，該群組即清除。
5. 人工失敗區段：審查者的證據是規格書。從中推導變更、套用，並註明該標準需要人類/代理重新審查 —— 自動化無法確認它。
6. 停止條件：當您無法推斷某個實例的意義時（例如未知圖片的替代文字、模糊欄位的標籤），請新增 TODO(a11y) 註解並在摘要中註記 —— 錯誤的猜測比標記的缺口更糟。
7. 報告：修復前後分數、已清除的群組、新的發現（應為零）、標記給人工處理的項目。

VLM 可疑群組

工單可能包含 vlm-* 群組（僅在評估使用 --vlm 執行時出現）。其實例行包含視覺語言模型的推理 —— 對於 vlm-alt-quality-suspect，有一個提議的替代文字。將該提案視為草稿：在套用前根據實際圖片驗證它，並且絕不套用您無法從頁面本身確認的 VLM 提議變更。

禁止事項

• 失敗：當原生元素可行時，在 div 上硬塞 tabindex + 鍵盤處理器
• 失敗：對資訊性圖片使用 alt=""；aria-label 重複可見文字但內容不符
• 失敗：壓制規則、刪除元素或使用 aria-hidden 來讓發現消失
• 失敗：未計算比值就憑目測調整對比度
• 失敗：未重新執行驗證並顯示規則已消失就宣稱完成

相關技能

• a11y-evaluator — 產生本技能所使用的報告與工單