WCAG 稽核
您正在稽核使用者介面的無障礙障礙並修復它們。身心障礙使用者無法像視力正常的滑鼠使用者那樣繞過遺失的標籤:請將每個已確認的發現視為一個真實的錯誤,它阻礙了真實的人。
目標: 一份 經過驗證 的發現清單,每個發現都對應到一個 WCAG 2.2 成功準則,並附有精確的位置、證據和最小的修復——然後應用這些修復,並重新驗證。
原則
- 經過驗證,否則不出貨。 每一項發現都必須通過階段三。一份簡短的真正問題清單勝過一份冗長且使用者學會忽略的清單。
- 原生 HTML 優先。 最好的 ARIA 就是沒有 ARIA。將
<div onClick>修復為<button>,而不是加上role、tabindex和按鍵處理器。 - 最小化、保留行為的修復。 修改失敗的標記;不要重新設計樣式、重構或重新格式化周圍的程式碼。除非發現 本身是 視覺相關(對比度、焦點環、目標大小),否則保持視覺設計不變。
- 絕不發明內容。 Alt 文字、標籤和連結文字必須反映 UI 實際的意義。如果您無法判斷圖像傳達的內容,請將發現標記為
needs_validation並詢問;不要撰寫alt="image"。 - 自動化是基礎,不是天花板。 工具只能捕捉約三分之一到一半的 WCAG 失敗情況。報告 未測試 的項目(請參閱手動檢查清單)。
設定
根據使用者的請求決定範圍:整個儲存庫、一個目錄、特定元件或一個 URL。然後檢查工具:
npx --yes @mintwork/wcag-audit-skill --version # CLI 可用?
如果 CLI 不可用(離線、沒有 Node),請繼續使用手動模式:自行閱讀references/RULES.md 中的規則清單來檢查原始碼,並跳過階段二,除非使用者的環境提供了其他瀏覽器工具。
將所有產出寫入儲存庫根目錄的 .wcag-audit/ 目錄(建立它;建議將其加入 .gitignore,如果專案提交了 CI 基準線,則保留 .wcag-audit/baseline.json)。除非使用者要求,否則絕不寫入其他位置。
工作流程
依序執行各階段。告訴使用者您目前在哪個階段。對於小範圍(一個元件),階段可以簡短,但不要跳過階段三。
階段一 — 靜態掃描(原始碼)
npx @mintwork/wcag-audit-skill scan <path> --json -o .wcag-audit/static.json --fail-on none
即使專案提交了基準線(.wcag-audit/baseline.json),也要在不使用 --baseline 的情況下進行稽核:基準線只會讓 CI 忽略已知的發現,而這些發現仍然需要審查。
然後閱讀 references/STATIC-SCAN.md 並執行工具無法完成的審查:包裝原生元件的自訂元件、條件渲染、設計系統 props(<Icon label=…>)、在 CSS-in-JS 中被移除或在其他樣式表中被取代的焦點樣式(CLI 會逐一檢查 .css / .scss / .less 和 Tailwind 類別)、僅以顏色區分的狀態,以及任何因展開 props 或動態值而被掃描器跳過的項目。將這些項目作為候選發現加入,並設定 "source": "static" 和 "confidence": "medium"。
階段二 — 執行階段掃描(真實瀏覽器)
僅當有可用的 URL 或應用程式可以啟動時才執行。找到開發指令(package.json 中的 scripts、README),在背景啟動它,等待它回應,然後執行:
npx @mintwork/wcag-audit-skill scan http://localhost:3000 --source src --json -o .wcag-audit/runtime.json --fail-on none
# 更多頁面 / 狀態:
npx @mintwork/wcag-audit-skill scan http://localhost:3000/login http://localhost:3000/cart --json -o .wcag-audit/runtime-2.json --fail-on none
掃描重要的頁面(首頁、主要流程、表單、開啟的模態框)——請參閱 references/RUNTIME-SCAN.md 了解應涵蓋的狀態、SPA 等待和驗證。將狀態(開啟模態框、提交空表單、深色模式、320px)放入配置中並執行 scan --config .wcag-audit/config.json;對於需要登入的頁面,使用使用者的 --storage-state <file>,絕對不要使用憑證。如果專案有 Storybook,也執行 scan --storybook storybook-static(或執行中的 Storybook URL)以涵蓋每個元件狀態。每個執行階段發現的 sourceHint 都是一個搜尋結果:在修復前先在那裡確認。執行階段掃描能捕捉靜態分析無法發現的問題:計算出的對比度、真實的 accessible name、焦點順序、鍵盤陷阱、隱形焦點。
階段三 — 驗證(消除誤報)
對於每一項候選發現,遵循 references/VERIFICATION.md 的步驟。嘗試反駁它:在報告的行號處開啟原始碼,追蹤 props/slots/spreads 到其值設定的位置,檢查父元件是否提供了標籤,對於執行階段的發現則檢查渲染的 DOM。指定一個 verdict:
confirmed— 您追溯了它,並且它確實違反了準則。記錄您如何知道。needs_validation— 看似合理但您無法確認(例如 alt 文字品質、您看不到的內容、您無法到達的頁面)。不套用修復。rejected— 已反駁。記錄原因(這教導使用者應調整哪些規則)。
合併重複項:由靜態和執行階段掃描報告的相同根本原因,應視為一個發現,並包含兩個位置。
階段四 — 修復
修復 confirmed 的發現,從嚴重性最高的開始,使用 references/FIX-PATTERNS.md 的指引。對於每個修復:
- 進行能滿足準則的最小變更,並使用該框架的慣用語法(React 中的
htmlFor、Vue 中的:aria-label等)。 - 用一兩句話解釋:哪裡錯了、影響了誰、改變了什麼。
- 在變更可見 UI 或文案(對比色、新的可見標籤、連結文字)之前先詢問,除非使用者已事先同意。
機械性的發現(html-lang 修復、meta-viewport-zoom、aria-attr-valid 拼寫錯誤)可以由 CLI 修復:執行 scan <path> --dry-run,向使用者顯示 diff,然後執行 scan <path> --fix。只有在您知道頁面語言時,才能使用 --lang <code> 加上遺失的 lang。
然後以機械方式重新驗證:
npx @mintwork/wcag-audit-skill verify .wcag-audit/static.json
npx @mintwork/wcag-audit-skill verify .wcag-audit/runtime.json # 開發伺服器仍在執行
如果仍有問題,或修復引入了新的發現,verify 會以非零狀態碼退出。請疊代直到已確認的發現被解決,或者您已解釋為何無法在程式碼中修復(例如需要使用者提供字幕內容)。執行專案自己的測試/lint。
階段五 — 報告
撰寫符合 assets/report-schema.json 規範的 .wcag-audit/findings.json,並驗證它:
node <skill-dir>/scripts/validate-findings.mjs .wcag-audit/findings.json
然後撰寫 .wcag-audit/REPORT.md,並給使用者一份簡短的摘要,遵循 references/REPORTING.md 的格式:按嚴重性和 verdict 分類的計數、已修復的項目、需要使用者輸入的項目、未測試的項目。
嚴重性
| 嚴重性 | 意義 | 範例 |
|---|---|---|
| critical | 對某些使用者而言完全阻礙任務 | 未標籤的表單欄位、作為唯一提交方式的 <div onClick>、鍵盤陷阱、停用縮放 |
| serious | 重大困難或資訊遺失 | 低對比度主體文字、遺失頁面語言、無名稱的連結 |
| moderate | 摩擦、令人困惑的結構 | 跳過標題層級、在上下文中冗長或含糊的連結文字 |
| minor | 潤飾、最佳實踐 | 含糊的 alt 文字、自動對焦 |
嚴重性反映的是這個 UI 中對使用者的影響,而不是規則的預設值:頁尾中未標籤的搜尋框,其嚴重性低於登入頁面上未標籤的密碼欄位。
反模式(禁止)
- 不要加入與可見文字重複或矛盾的
aria-label(違反 WCAG 2.5.3)。 - 當
<button>可行時,不要使用role="button"+tabindex="0"。 - 不要透過改變視覺大小來「修復」標題順序的發現;請改變層級並保留 CSS。
- 不要在資訊性圖像上設定
alt=""來讓掃描器閉嘴。 - 未在註解旁附上書面理由,就不要隱藏發現(
wcag-audit-ignore)。 - 不要聲稱符合 WCAG「標準」——自動化加上代理程式的審查只能顯示失敗,無法證明符合性。
- 不要修改產生的、供應商的或
node_modules的程式碼;請修復來源元件。
檔案
- references/RULES.md — 每條靜態和執行階段規則,對應到 WCAG
- references/STATIC-SCAN.md — 階段一依框架進行的手動審查
- references/RUNTIME-SCAN.md — 階段二頁面、狀態、SPA、驗證
- references/VERIFICATION.md — 階段三每條規則的反駁程序
- references/FIX-PATTERNS.md — 階段四修復前後對比
- references/REPORTING.md — 階段五報告格式
- references/MANUAL-CHECKLIST.md — 自動化無法檢查的項目
- assets/report-schema.json — findings.json 的 schema
scripts/validate-findings.mjs— 用於 findings.json 的零依賴驗證器