Accessibility Audit（a11y-audit）是一个 WCAG 2.2 无障碍审计与修复技能，为现代 Web 应用提供完整的无障碍审计流水线。它实现“扫描—修复—验证”三阶段工作流，用于识别 WCAG 2.2 A 级与 AA 级违规，按框架生成精确修复代码，并产出适合相关方查看的合规报告。
用途与主要能力 该技能会扫描代码库，找出所有 WCAG 2.2 A 级与 AA 级违规，并按严重程度（Critical、Major、Minor）分类；针对每个违规项，提供按框架定制的精确前后对比代码修复，覆盖 React、Next.js、Vue、Angular、Svelte 或纯 HTML；随后验证修复是否解决原始违规且未引入回归；还能以结构化格式输出结果，供开发者、PM 与合规相关方使用，并可集成到 CI/CD 流水线中防止无障碍回归。
主要功能包括：完整的 WCAG 2.2 扫描（检查代码库中全部 A 级与 AA 级成功标准）；框架自动检测；严重程度分类；修复代码生成（为每个问题产出前后对比代码差异）；颜色对比度检查（按 AA 与 AAA 比率验证前景/背景组合）；合规报告（含通过/失败摘要的相关方报告）；CI/CD 集成（GitHub Actions、GitLab CI、Azure DevOps 流水线配置）；键盘导航审计（检测缺失的焦点管理与 Tab 顺序问题）；ARIA 校验（检查错误、冗余或缺失的 ARIA 属性）。
严重程度定义
- Critical（严重）：阻断整个用户群体的访问，例如缺少 alt 文本、导航无法通过键盘访问。SLA 为发布前修复。
- Major（主要）：显著障碍，降低体验，例如颜色对比度不足、缺少表单标签。SLA 为当前迭代内修复。
- Minor（次要）：造成摩擦的可用性问题，例如冗余 ARIA 角色、标题层级欠佳。SLA 为接下来两个迭代内修复。
使用方式 快速开始：
扫描整个项目
python scripts/a11y_scanner.py /path/to/project
以 JSON 输出供工具使用
python scripts/a11y_scanner.py /path/to/project --json
检查特定颜色值的对比度
python scripts/contrast_checker.py --fg "#777777" --bg "#ffffff"
检查 CSS/Tailwind 文件中的对比度
python scripts/contrast_checker.py --file /path/to/styles.css
斜杠命令： /a11y-audit # 审计当前项目 /a11y-audit --scope src/ # 审计特定目录 /a11y-audit --fix # 审计并自动应用修复 /a11y-audit --report # 生成相关方报告 /a11y-audit --ci # 输出 CI 兼容结果
三阶段工作流 阶段 1：扫描——遍历源码树，检测框架，应用规则集。 python scripts/a11y_scanner.py /path/to/project --format table
阶段 2：修复——针对每个违规项应用框架特定的修复。完整修复模式目录见 references/framework-a11y-patterns.md。
阶段 3：验证——重新运行扫描器，确认修复并检查回归。 python scripts/a11y_scanner.py /path/to/project --baseline audit-baseline.json
示例：React 组件审计（详见原文示例，包含 ProductCard 组件修复前后的代码对比，涉及 1.1.1、2.1.1、1.4.3、4.1.2 等 WCAG 条款）。Vue、Angular、Next.js 与 Svelte 的示例见 references/examples-by-framework.md。
工具参考 a11y_scanner.py 用法：python scripts/a11y_scanner.py <path> [options] 选项： --json Output results as JSON --format {table,csv} Output format (default: table) --severity {critical,major,minor} Filter by minimum severity --framework {react,vue,angular,svelte,html,auto} Force framework (default: auto) --baseline FILE Compare against previous scan results --report Generate stakeholder report --output FILE Write results to file --quiet Suppress output, exit code only --ci CI mode: non-zero exit on critical issues
contrast_checker.py 用法：python scripts/contrast_checker.py [options] 选项： --fg COLOR Foreground color (hex) --bg COLOR Background color (hex) --file FILE Scan CSS file for color pairs --tailwind DIR Scan directory for Tailwind color classes --json Output results as JSON --suggest Suggest accessible alternatives for failures --level {aa,aaa} Target conformance level (default: aa)
常见陷阱与正确做法
- 在 <div> 上使用 role="button"：应使用原生 <button>，自带键盘处理。
- 对所有元素使用 tabindex="0"：只有交互元素需要焦点，应使用原生元素。
- 在非交互元素上使用 aria-label：应使用 aria-labelledby 指向可见文本。
- 用 display: none 隐藏屏幕阅读器内容：应改用 .sr-only 类。
- 仅用颜色传达含义：应配合图标、文本标签或图案。
- 仅用占位符作为标签：应始终提供可见的 <label>。
- 去掉 outline 且无替代：应通过 focus-visible 提供可见焦点指示。
- 信息性图片使用空 alt=""：信息性图片需要描述性 alt 文本。
- 跳过标题层级（h1 -> h3）：标题层级必须连续。
- 只有 onClick 而无 onKeyDown：应添加键盘支持或优先使用原生元素。
- 忽略 prefers-reduced-motion：应将动画包裹在 @media (prefers-reduced-motion: no-preference) 中。
相关技能 senior-frontend（a11y 修复中使用的前端模式）、code-reviewer（将 a11y 检查纳入代码审查流程）、senior-qa（将 a11y 测试集成到 QA 流程）、playwright-pro（带无障碍断言的自动化浏览器测试）、epic-design（符合 WCAG 2.1 AA 的动画与滚动叙事）、tdd-guide（a11y 测试用例的测试驱动开发模式）。
参考文档 wcag-quick-ref.md（WCAG 2.2 A 级与 AA 级标准快速参考）、wcag-22-new-criteria.md（WCAG 2.2 新成功标准，如焦点外观、目标尺寸等）、aria-patterns.md（ARIA 模式、键盘交互与实时区域）、framework-a11y-patterns.md（各框架修复模式）、color-contrast-guide.md（颜色对比度检查器细节、Tailwind 调色板映射、sr-only 类）、ci-cd-integration.md（GitHub Actions、GitLab CI、Azure DevOps、pre-commit 钩子配置）、audit-report-template.md（相关方审计报告模板）、testing-checklist.md（手动测试清单：键盘、屏幕阅读器、视觉、表单）、examples-by-framework.md（Vue、Angular、Next.js 与 Svelte 的完整审计示例）。
资源 WCAG 2.2 规范、WAI-ARIA Authoring Practices 1.2、Deque axe-core Rules、eslint-plugin-jsx-a11y。
限制 资料未提供许可证、定价、安装方式、运行环境依赖与适用范围等细节，暂未提供。