Communitygithub.com

wcag-audit

審查網頁使用者介面是否符合 WCAG 2.2 無障礙規範(a11y),並修復問題。採用分階段程序進行:靜態原始碼掃描、真實瀏覽器執行階段掃描、對每項發現進行對抗驗證、最小修復並附上說明,最後產出機器可讀報告。

wcag-audit 是什麼?

這個技能(wcag-audit)是一個專為 AI 代理設計的無障礙稽核與修復工具,協助開發者系統性地發現並修正 WCAG 2.2 無障礙規範的違規問題。它支援多種框架的靜態原始碼掃描(包括 HTML、JSX、TSX、Vue、Svelte、Astro、MDX、Angular 和 CSS),並能透過 axe-core 和鍵盤操作檢查進行真實瀏覽器執行階段掃描。技能採用嚴謹的五階段工作流程:靜態掃描、執行階段掃描、驗證(嘗試反駁每項發現以消除誤報)、修復(最小化且保留行為的修復)與報告(產出結構化 JSON 和 Markdown 報告)。特別強調「經過驗證才出貨」的原則,同時提供詳細的參考文件處理開發者難以手動檢查的項目,如自訂元件、動態屬性與 CSS-in-JS 的焦點樣式。此技能也支援 Storybook 元件狀態覆蓋,並可處理登入驗證、SPA 切換等多種複雜情境。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/mintwork/wcag-audit-skill/tree/HEAD/skills/wcag-audit

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

WCAG 稽核

您正在稽核使用者介面的無障礙障礙並修復它們。身心障礙使用者無法像視力正常的滑鼠使用者那樣繞過遺失的標籤:請將每個已確認的發現視為一個真實的錯誤,它阻礙了真實的人。

目標: 一份 經過驗證 的發現清單,每個發現都對應到一個 WCAG 2.2 成功準則,並附有精確的位置、證據和最小的修復——然後應用這些修復,並重新驗證。

原則

  1. 經過驗證,否則不出貨。 每一項發現都必須通過階段三。一份簡短的真正問題清單勝過一份冗長且使用者學會忽略的清單。
  2. 原生 HTML 優先。 最好的 ARIA 就是沒有 ARIA。將 <div onClick> 修復為 <button>,而不是加上 role、tabindex 和按鍵處理器。
  3. 最小化、保留行為的修復。 修改失敗的標記;不要重新設計樣式、重構或重新格式化周圍的程式碼。除非發現 本身是 視覺相關(對比度、焦點環、目標大小),否則保持視覺設計不變。
  4. 絕不發明內容。 Alt 文字、標籤和連結文字必須反映 UI 實際的意義。如果您無法判斷圖像傳達的內容,請將發現標記為 needs_validation 並詢問;不要撰寫 alt="image"。
  5. 自動化是基礎,不是天花板。 工具只能捕捉約三分之一到一半的 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 的指引。對於每個修復:

  1. 進行能滿足準則的最小變更,並使用該框架的慣用語法(React 中的 htmlFor、Vue 中的 :aria-label 等)。
  2. 用一兩句話解釋:哪裡錯了、影響了誰、改變了什麼。
  3. 在變更可見 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 的程式碼;請修復來源元件。

檔案

相關技能