a11y-audit
作者 alirezarezvania11y-audit 是一個用於前端程式碼庫的 accessibility audit 技能，可掃描、修正並驗證 WCAG 2.2 Level A 與 AA 問題。它支援 React、Next.js、Vue、Angular、Svelte 與 HTML，提供依嚴重度分類的 findings、對比檢查、報告範本，以及 CI/CD 指引。
此技能評分為 78/100，代表它很適合推薦給想要 agent 輔助 accessibility audit 工作流程的目錄使用者。它提供足夠具體的流程內容、scripts、範例與參考資料，足以支持安裝；但使用者仍應審慎看待其廣泛的 WCAG 涵蓋主張，並預期需要自行做一些設定驗證。
- 觸發條件清楚：frontmatter 明確指出可用於 accessibility audits、a11y violation fixes、color contrast checks、compliance reports，以及 CI/CD accessibility checks。
- 實作支援完整：此技能包含內容充實的 SKILL.md，加上 scanner 與 contrast-checker scripts、範例輸入、預期的 JSON/report 輸出，以及 WCAG、ARIA、框架模式、測試與 CI/CD 相關參考。
- 能有效放大 agent 能力：Scan/Fix/Verify 流程與各框架的修復參考，有助於 agent 產出比一般 accessibility prompt 更有結構的稽核與修正。
- 技能路徑中沒有安裝指令或 README，因此使用者可能需要自行判斷如何在自己的 agent 環境中安裝或呼叫它。
- repo 證據中有些主張偏廣，例如可掃描「every WCAG 2.2 Level A and AA violation」；此外，CI 範例似乎預期使用 `violations` JSON key，但範例輸出使用的是 `findings`。
a11y-audit skill 概覽
a11y-audit 的用途
a11y-audit 是一項無障礙稽核 skill，協助你在網頁程式碼庫中找出、修正並驗證 WCAG 2.2 Level A 與 AA 問題。當你希望 AI agent 不只提供籠統的無障礙建議，而是產出有結構的發現事項，包含嚴重程度、WCAG 對應條文、符合框架脈絡的修正方式，以及開發者或法遵利害關係人可實際採取行動的報告時，a11y-audit 會特別有用。
最適合的使用者與專案
a11y-audit skill 適合使用 React、Next.js、Vue、Angular、Svelte 或純 HTML 的前端團隊。它尤其適用於準備發版、清理既有無障礙技術債、審查 pull request，或把無障礙檢查加入 CI/CD 的團隊。如果你只需要高層次的 UX 評論、法律認證，或是不搭配程式碼層級修正的人工螢幕閱讀器測試，它的幫助就比較有限。
這項 skill 的不同之處
這項 skill 不是一次性的提示詞，而是圍繞 Scan、Fix、Verify 工作流程設計。它的支援檔案包含用於掃描與對比檢查的 Python scripts、範例輸出、報告範本、CI/CD 指引、WCAG 2.2 參考資料、ARIA patterns、測試檢查清單，以及各框架專用範例。這讓 agent 更容易產出可重複使用的稽核結果，而不是只給出模糊的「改善無障礙」建議。
採用前的重要考量
a11y-audit 可以協助找出常見的程式碼層級違規，例如缺少 alt text、滑鼠點擊處理器無法用鍵盤操作、缺少 label、正值 tabIndex、表格標題問題、ARIA 誤用，以及對比不足。不過，它仍應搭配人工審查、瀏覽器測試、鍵盤測試，以及輔助科技檢查。自動化與 AI 輔助稽核無法完整驗證使用者意圖、內容語意、焦點體驗，或真實螢幕閱讀器行為。
如何使用 a11y-audit skill
a11y-audit 安裝方式與 repository path
使用以下指令從 GitHub repository 安裝這項 skill：
npx skills add alirezarezvani/claude-skills --skill a11y-audit
skill 位於：
engineering-team/a11y-audit/skills/a11y-audit
安裝後，先閱讀 SKILL.md，再查看 references/wcag-quick-ref.md、references/testing-checklist.md、references/framework-a11y-patterns.md、references/aria-patterns.md 和 references/ci-cd-integration.md。接著預覽 expected_outputs/sample-scan-report.md 與 expected_outputs/sample-scan-output.json，在要求 agent 稽核你自己的程式碼前，先了解理想輸出應該長什麼樣子。
讓稽核結果更好的輸入內容
若要有效使用 a11y-audit，請提供 agent 實際的 component files、使用的 framework、routing context、design-system 限制，以及目標標準。較弱的提示是：
“Check this page for accessibility.”
較好的提示是：
“Use the a11y-audit skill to review these React components for WCAG 2.2 Level AA. Focus on keyboard access, form labels, image alternatives, table semantics, ARIA use, and color contrast. Return findings grouped by severity with file/line references, WCAG criteria, before/after code, and verification steps. Do not change our design-system Button API.”
這會讓 skill 擁有足夠脈絡來優先處理真正需要修正的問題，並避免產出泛用式改寫。
建議的 Scan、Fix、Verify 工作流程
先從範圍明確的小區塊開始掃描：一個頁面、一個 component folder，或一個 pull request。如果你需要機器可讀的輸出，可以要求 JSON-style findings；如果是給人審閱，則可要求 markdown report。接著請 agent 先修正 critical 和 serious issues，同時保留既有行為與框架慣例。
實務上可採用以下流程：
- 對明確路徑執行或要求掃描，例如
src/components/UserCard.tsx。 - 依嚴重程度與 WCAG criterion 檢視發現事項。
- 分小批套用修正：keyboard support、labels、semantics、contrast、ARIA。
- 要求 skill 驗證每個原始問題是否已解決。
- 使用
references/audit-report-template.md中的結構產出最終報告。
使用內建 scripts 與參考資料
repository 包含 scripts/a11y_scanner.py 與 scripts/contrast_checker.py。當你想在聊天工作階段之外進行可重現檢查時，可以把它們當作實用輔助工具或範例。contrast sample 會顯示一般文字、大型文字與 UI components 的精確比例，以及 pass/fail thresholds。CI/CD 參考資料則包含 GitHub Actions pattern，可在 pull requests 出現 critical accessibility violations 時讓檢查失敗；如果你想把 a11y-audit 用於 Frontend Development 工作流程，防止回歸問題，而不是只產出一次性報告，這會很有幫助。
a11y-audit skill 常見問題
a11y-audit 適合初學者嗎？
適合，只要你具備基本前端知識。這項 skill 會用 WCAG references 與具體修正方式說明違規問題，因此能一邊稽核一邊教學。初學者應先從一個 component 開始，並在對整個 codebase 大量套用變更前，要求解釋每個問題。
它比一般無障礙提示詞好在哪裡？
一般提示詞可能只會產出檢查清單或泛用建議。a11y-audit skill 提供更受限且可操作的工作流程、嚴重程度模型、範例輸出、報告格式、framework examples、ARIA 指引、contrast guidance，以及 CI/CD integration notes。這樣的結構能幫助 agent 產出更容易審閱、實作與驗證的結果。
它可以認證 WCAG compliance 嗎？
不行。a11y-audit 可以支援 WCAG 2.2 Level A 與 AA 的修正工作，但不能取代正式無障礙稽核、使用者測試、法律審查或輔助科技驗證。請把它視為面向開發者的稽核與修正加速器，而不是認證機構。
什麼情況不應該使用 a11y-audit？
不要單靠它處理 native mobile apps、PDF accessibility、video captioning workflows、legal conformance statements，或需要人工測試的複雜輔助科技行為。它最擅長處理 web UI source code，尤其是 HTML 與現代前端框架 components。
如何改進 a11y-audit skill 的使用效果
讓 a11y-audit 提示更具體
最常見的失敗模式，是在缺乏足夠 source context 的情況下要求稽核。請包含 framework、file paths、component purpose、相關 CSS 或 design tokens，以及變更是否必須保留 public APIs。如果涉及色彩，請提供 foreground 與 background values，而不只是 class names。如果涉及表單，請包含 validation behavior 與 visible label requirements。
要求符合你程式碼庫風格的修正
告訴 skill 你偏好的 patterns。例如：“Use our existing <Button> and <TextField> components,” “avoid adding ARIA when semantic HTML is available,” 或 “keep route behavior unchanged.” 這能減少過度修正，例如不必要地替換 components，或對語意元素加入多餘的 roles。
不要只停在第一次回答
收到第一份報告後，請要求 a11y-audit 依原始 WCAG criterion 驗證每個修正，並找出可能的回歸問題。好的追問包括：“Check keyboard order after these changes,” “Confirm the accessible names for all icon buttons,” 以及 “Review whether these ARIA attributes are necessary or harmful.” 這會把 skill 從單純掃描器變成修正循環的一部分。
加入專案專屬 guardrails
若會重複使用，建議維護一份簡短的內部無障礙簡報，列出你們支援的 frameworks、design-system components、severity policy、browser support 與 CI threshold。再搭配 repository 參考資料，例如 testing-checklist.md、wcag-22-new-criteria.md 和 ci-cd-integration.md。越一致地定義 acceptance criteria，a11y-audit 對 pull requests、release checks 與長期前端品質就越有價值。