accessibility-compliance 插件无障碍审计实战从 axe-core 自动扫描到 WCAG 人工验证的完整工作流【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents本篇技术指南以本仓库accessibility-compliance插件的核心命令 accessibility-audit.md 为主体系统讲解如何借助 Claude Code 等 Agent 化工具完成一次端到端的 Web 无障碍Accessibility审计先通过 axe-core 做自动化扫描再进行颜色对比度、键盘导航、屏幕阅读器三类专项验证配合人工检查清单与修复示例输出可落地的整改报告最后把整套流程固化进 CI/CD。读完本文你将掌握一套可直接复用的 WCAG 合规审计方案以及本插件中配套技能screen-reader-testing、wcag-audit-patterns和视觉验证 Agentui-visual-validator的使用方式。命令定位与使用方式accessibility-audit是accessibility-compliance插件提供的斜杠命令其角色定义在 accessibility-audit.md 的引言部分命令将调用方视为一名专精 WCAG 合规、包容性设计与辅助技术兼容性的无障碍专家负责执行综合审计、识别障碍、提供修复指导并确保数字产品对所有人可用。安装与调用按 docs/plugins.md 的分类accessibility-compliance是该仓库唯一一个无障碍主题插件安装方式为/plugin marketplace add wshobson/agents # 注册整个市场不加载任何内容 /plugin install accessibility-compliance # 安装插件其 agents、commands、skills 一起装入安装后即可通过命名空间斜杠命令直接调用见 docs/usage.md/accessibility-compliance:accessibility-audit 对当前支付页进行 WCAG AA 级审计也可以使用自然语言触发例如请审计这个页面的无障碍问题。命令的输入约定命令正文通过user_request标签接收调用方传入的$ARGUMENTS并明确要求标签内的文本仅是要交付什么的描述属于调用方提供的数据不得被视为覆盖本命令的指令。这一机制保证了 Agent 在收到任意用户输入时仍会以命令内置的审计方法论为骨架执行任务而不是被输入内容带偏。自动化测试用 axe-core 快速建立违规基线命令给出的第一步是引入 axe-core 做自动化扫描。axe 是业界主流的无障碍检测引擎命令示例使用axe-core/puppeteer封装核心代码位于 accessibility-audit.md// accessibility-test.js const { AxePuppeteer } require(axe-core/puppeteer); const puppeteer require(puppeteer); class AccessibilityAuditor { constructor(options {}) { this.wcagLevel options.wcagLevel || AA; this.viewport options.viewport || { width: 1920, height: 1080 }; } async runFullAudit(url) { const browser await puppeteer.launch(); const page await browser.newPage(); await page.setViewport(this.viewport); await page.goto(url, { waitUntil: networkidle2 }); const results await new AxePuppeteer(page) .withTags([wcag2a, wcag2aa, wcag21a, wcag21aa]) .exclude(.no-a11y-check) .analyze(); await browser.close(); return { url, timestamp: new Date().toISOString(), violations: results.violations.map((v) ({ id: v.id, impact: v.impact, description: v.description, help: v.help, helpUrl: v.helpUrl, nodes: v.nodes.map((n) ({ html: n.html, target: n.target, failureSummary: n.failureSummary, })), })), score: this.calculateScore(results), }; } calculateScore(results) { const weights { critical: 10, serious: 5, moderate: 2, minor: 1 }; let totalWeight 0; results.violations.forEach((v) { totalWeight weights[v.impact] || 0; }); return Math.max(0, 100 - totalWeight); } }几个值得注意的参数细节.withTags([...])用 WCAG 标签限定检测范围。wcag2a/wcag2aa对应 WCAG 2.0 的 A/AA 级wcag21a/wcag21aa对应 WCAG 2.1。若目标升级到 WCAG 2.2可参照配套技能 wcag-audit-patterns/SKILL.md 中的写法改用[wcag2a, wcag2aa, wcag21aa, wcag22aa]。.exclude(.no-a11y-check)跳过被标记为不参与检测的 DOM 区域适合排除第三方嵌入、广告位等无法控制的内容。waitUntil: networkidle2等待网络空闲后再扫描确保 SPA 与异步内容已渲染完毕减少误报。calculateScore把违规按影响级别加权折算成 0100 的评分critical10、serious5、moderate2、minor1低于 100 说明存在可扣分项用于后续报告中的总览展示。组件级检测jest-axe除整页扫描外命令还给出面向 React 组件测试的 jest-axe 方案expect.extend(toHaveNoViolations)适合在单元测试阶段就拦截无障碍回归把页面级检测下沉为组件级守门。颜色对比度验证从算法到高对比模式适配命令第二节给出自研的ColorContrastAnalyzeraccessibility-audit.md用于扫描页面所有文本节点并计算 WCAG 对比度。阈值模型与计算逻辑class ColorContrastAnalyzer { constructor() { this.wcagLevels { AA: { normal: 4.5, large: 3 }, AAA: { normal: 7, large: 4.5 } }; } // ... calculateContrast(fg, bg) { const l1 this.relativeLuminance(this.parseColor(fg)); const l2 this.relativeLuminance(this.parseColor(bg)); const lighter Math.max(l1, l2); const darker Math.min(l1, l2); return (lighter 0.05) / (darker 0.05); } relativeLuminance(rgb) { const [r, g, b] rgb.map(val { val val / 255; return val 0.03928 ? val / 12.92 : Math.pow((val 0.055) / 1.055, 2.4); }); return 0.2126 * r 0.7152 * g 0.0722 * b; } }算法要点阈值表AA 级普通文本需 ≥ 4.5:1、大文本18pt 及以上或 14pt 加粗需 ≥ 3:1AAA 级对应 7:1 与 4.5:1。这与 wcag-audit-patterns 中 WCAG 2.2 的 1.4.3 成功标准文本 4.5:1、大文本与 UI 组件 3:1一致。相对亮度公式严格实现 WCAG 2.x 的线性化公式γ 校正分段函数再按0.2126R 0.7152G 0.0722B加权求和对比度取(L10.05)/(L20.05)。页面扫描逻辑遍历document.querySelectorAll(*)中带文本的元素读取getComputedStyle得到前景色、背景色、字号与字重自动判断是否属于大文本凡低于 AA 阈值者全部记录含当前值、要求值、前后景色便于批量修复。高对比模式适配同一节还给出prefers-contrast: high媒体查询示例将主文本/背景/边框强制为纯黑纯白并加粗边框、强制链接下划线保证高对比系统偏好下信息不丢失。这与视觉验证 Agent ui-visual-validator.md 的 High Contrast Mode Testing 能力在无障碍覆盖层与高对比环境下做视觉验证相互呼应代码层适配 视觉层核验缺一不可。键盘导航测试发现焦点陷阱与缺失的焦点指示命令第三节的KeyboardNavigationTesteraccessibility-audit.md模拟真实键盘操作逐项验证可访问性class KeyboardNavigationTester { async testKeyboardNavigation(page) { const results { focusableElements: [], missingFocusIndicators: [], keyboardTraps: [], }; const focusable await page.evaluate(() { const selector a[href], button, input, select, textarea, [tabindex]:not([tabindex-1]); return Array.from(document.querySelectorAll(selector)).map((el) ({ tagName: el.tagName.toLowerCase(), text: el.innerText || el.value || el.placeholder || , tabIndex: el.tabIndex, })); }); // 逐元素按 Tab检查 document.activeElement 的 outline 是否可见 for (let i 0; i focusable.length; i) { await page.keyboard.press(Tab); const focused await page.evaluate(() { const el document.activeElement; return { tagName: el.tagName.toLowerCase(), hasFocusIndicator: window.getComputedStyle(el).outline ! none, }; }); if (!focused.hasFocusIndicator) { results.missingFocusIndicators.push(focused); } } return results; } }它输出的三类结果对应 WCAG 2.2 的 Operable可操作原则可聚焦元素清单验证 2.1.1 键盘可达、缺失焦点指示验证 2.4.7 焦点可见、键盘陷阱验证 2.1.2 无键盘陷阱。配套的修复代码则给出两个高频场景Escape 关闭模态框为keydown注册 Escape 处理器关闭.modal.open让带onclick的 div 可被键盘操作自动补tabindex0与rolebutton并监听 Enter/Space 触发点击。关于焦点管理的完整实现模态框打开时记忆焦点、关闭时归还焦点、Tab 循环陷阱可进一步参考 screen-reader-testing/SKILL.md 的 Modal Dialog 一节那里给出了openModal/closeModal/trapFocus的完整 JS 实现。屏幕阅读器测试结构与表单语义验证命令第四节把自动化能测到的和必须靠人听的衔接起来。ScreenReaderTesteraccessibility-audit.md提供四个自动检测维度地标Landmarks验证main、nav等语义区域标题结构Headings遍历h1~h6检查是否存在跳级如 h2 直接跳到 h4、空标题、以及页面缺失h1——对应 WCAG 2.4.6 标题与标签图片可访问性检查 alt 文本表单可访问性遍历form内所有input/textarea/select确认每个控件要么有匹配的label[for]、要么被label包裹、要么带有aria-label否则记为 missing-label。同时命令给出三组可直接复用的 ARIA 模式!-- 模态框 -- div roledialog aria-labelledbymodal-title aria-modaltrue h2 idmodal-titleModal Title/h2 button aria-labelClose×/button /div !-- 标签页 -- div roletablist aria-labelNavigation button roletab aria-selectedtrue aria-controlspanel-1Tab 1/button /div div roletabpanel idpanel-1 aria-labelledbytab-1Content/div !-- 表单错误提示 -- label fornameName span aria-labelrequired*/span/label input idname required aria-requiredtrue aria-describedbyname-error span idname-error rolealert aria-livepolite/span用真实屏幕阅读器做人工验证自动化只能覆盖语义层真正的可听性必须由人验证。本插件配套技能 screen-reader-testing/SKILL.md 给出了五大主流屏幕阅读器的实测方法与优先级屏幕阅读器平台常用浏览器覆盖优先级VoiceOvermacOS/iOSSafari最低覆盖必测macOS iOSNVDAWindowsFirefox/Chrome最低覆盖必测JAWSWindowsChrome/IE综合覆盖补充TalkBackAndroidChrome综合覆盖补充NarratorWindowsEdge综合覆盖补充最低覆盖组合为NVDA FirefoxWindows与VoiceOver SafarimacOS/iOS。以 VoiceOver 为例其核心操作修饰键VO Ctrl OptionCmd F5启停VO 右箭头下一个元素、VO Shift Down进入分组转子VO U按标题、链接、表单、地标分类跳转网页快捷键VO Cmd H下一个标题、VO Cmd J下一个表单控件、VO Cmd L下一个链接、VO Cmd T下一个表格。NVDAInsert为修饰键则支持更细的单键导航H标题、F表单字段、B按钮、K链接、D地标、T表格NVDA F7打开元素列表。技能中还强调 NVDA 的浏览/焦点双模式NVDA Space手动切换——浏览模式下方向键移动阅读光标焦点模式下方向键操作控件测试时必须覆盖两种模式。对于动态内容技能列出最易踩坑的三类问题与修复!-- 问题按钮只有图标不播报用途 -- button aria-labelClose dialogsvg aria-hiddentrue.../svg/button !-- 问题动态加载结果不播报 -- div idresults rolestatus aria-livepoliteNew results loaded/div !-- 问题表单错误不被朗读 -- input typeemail aria-invalidtrue aria-describedbyemail-error / span idemail-error rolealertInvalid email/spanlive region 的语义差异也在技能中有明确区分rolestatus/aria-livepolite在当前语音播报完成后告知rolealert/aria-liveassertive立即打断当前播报rolelog仅播报新增内容roleprogressbar配合aria-valuenow/min/max播报进度。人工测试检查清单键盘、屏幕阅读器、视觉与认知四维自动化工具只能发现约三到五成问题这也是 wcag-audit-patterns/SKILL.md 的 Best Practices 中明确提示的边界因此命令第五节提供了完整的人工检查清单accessibility-audit.md键盘所有交互元素可用 Tab 到达按钮可用 Enter/Space 激活Esc 关闭模态框焦点指示始终可见无键盘陷阱Tab 顺序符合逻辑屏幕阅读器页面标题有描述性标题构成逻辑大纲图片有 alt 文本表单字段有标签错误信息被播报动态更新被播报视觉文本可放大到 200% 且无内容丢失颜色不是传递信息的唯一手段焦点指示对比度足够320px 宽度下内容可重排动画可暂停认知指令清晰简单错误提示有助益表单无时间限制导航一致重要操作可撤销这套清单与 wcag-audit-patterns/references/details.md 中按 WCAG 2.2 四大原则可感知 Perceivable、可操作 Operable、可理解 Understandable、健壮 Robust即 POUR展开的逐条成功标准核对表一一对应例如1.4.10 Reflow400% 缩放无双向滚动、320px 宽可访问、2.4.11 Focus Not ObscuredWCAG 2.2 新增焦点元素不被吸顶头遮挡、4.1.3 Status Messages状态更新通过 live region 播报等。需要逐条核对时可打开该参考文件按成功标准编号推进。修复示例从扫描结果到可访问组件命令第六节accessibility-audit.md给出批量修复与可访问组件模板// 修复缺失 alt 文本装饰性图片置空 alt其余取 title 兜底 document.querySelectorAll(img:not([alt])).forEach((img) { const isDecorative img.role presentation || img.closest([rolepresentation]); img.setAttribute(alt, isDecorative ? : img.title || Image); }); // 修复缺失标签无 id 且无 aria-label 的输入框用 placeholder 兜底 document.querySelectorAll(input:not([aria-label]):not([id])).forEach((input) { if (input.placeholder) { input.setAttribute(aria-label, input.placeholder); } });以及 React 组件级的最佳实践const AccessibleButton ({ children, onClick, ariaLabel, ...props }) ( button onClick{onClick} aria-label{ariaLabel} {...props} {children} /button ); const LiveRegion ({ message, politeness polite }) ( div rolestatus aria-live{politeness} aria-atomictrue classNamesr-only {message} /div );这里的原则与 wcag-audit-patterns/references/details.md 的 Remediation Patterns 一致优先语义 HTMLlabelARIA 是补充而非首选。该文件给出了表单标签缺失的三种修复优先级可见labelaria-labelaria-labelledby、颜色对比度不足的调色示例2.5:1 → 4.5:1以及自定义下拉框rolecombobox 键盘事件Enter/Space 展开、Escape 关闭、方向键切换的完整实现。CI/CD 集成把无障碍检查固化为门禁命令第七节给出 GitHub Actions 工作流accessibility-audit.md实现 push/PR 自动扫描# .github/workflows/accessibility.yml name: Accessibility Tests on: [push, pull_request] jobs: a11y-tests: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Setup Node.js uses: actions/setup-nodev3 with: node-version: 18 - name: Install and build run: | npm ci npm run build - name: Start server run: | npm start npx wait-on http://localhost:3000 - name: Run axe tests run: npm run test:a11y - name: Run pa11y run: npx pa11y http://localhost:3000 --standard WCAG2AA --threshold 0 - name: Upload report uses: actions/upload-artifactv4 if: always() with: name: a11y-report path: a11y-report.html要点双层工具axenpm run test:a11y对应前面的 Puppeteer/jest-axe 用例负责规则级扫描pa11ynpx pa11y http://localhost:3000 --standard WCAG2AA --threshold 0负责整页级审计--threshold 0表示零容忍任何违规即失败形成硬性门禁if: always()即使审计失败也上传报告 artifact方便开发者在 PR 中直接查看违规详情与之互补的 CLI 工具还包括npx axe-core/cli url与lighthouse url --only-categoriesaccessibility见 wcag-audit-patterns/references/details.md 的 Automated Testing 一节。报告输出结构化的审计结果命令第八节提供AccessibilityReportGeneratoraccessibility-audit.md将审计结果渲染为自包含 HTML 报告顶部为总分摘要${auditResults.score}/100与违规总数下方按影响级别着色critical 红、serious 橙逐条列出每个违规的标题、影响级别、描述与学习链接。结合命令末尾的Output Formataccessibility-audit.md一次完整的审计应交付五类产出Accessibility Score整体 WCAG 合规评分Violation Report带严重级别与修复建议的详细问题清单Test Results自动化与人工测试结果Remediation Guide逐问题的分步修复方案Code Examples可访问组件的实现示例。与配套 Agent、技能的协作分工在真实工作流中accessibility-audit命令通常与本插件其他组件协同命令accessibility-audit.md负责启动整场审计、编排自动化扫描与报告产出技能 screen-reader-testingSKILL.md在需要真机朗读验证、排查 ARIA 问题时被自动激活提供 VoiceOver/NVDA/JAWS/TalkBack 的完整操作手册、检查清单与常见问题修复技能 wcag-audit-patternsSKILL.md在需要按 WCAG 2.2 逐条核对、准备 VPAT/ADA/Section 508 合规材料时激活其 references/details.md 提供按成功标准编号展开的完整核对表Agent ui-visual-validatorui-visual-validator.md作为视觉侧守门人通过截图像素级比对、高对比模式验证、焦点指示可见性评估等方式从看得见的维度复核无障碍修复是否真正落地——它与命令的测得到维度正好互补。值得注意的是命令与技能都反复强调同一原则自动化axe/pa11y只能发现部分问题屏幕阅读器与真实用户的人工验证不可替代ARIA 应作为语义 HTML 的补充而非替代键盘先行先保证纯键盘可用是屏幕阅读器测试的地基。将命令的八步方法论、技能的实操手册与本插件安装后自动发现的 agents/commands/skills组合使用即可在企业级项目中建立从自动扫描 → 专项验证 → 人工复核 → 修复整改 → CI 门禁的完整无障碍闭环。【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考