a11y-audit

Accessibility Audit

WCAG 2.2 无障碍审计与修复技能

Description

The a11y-audit 技能为现代 Web 应用提供完整的无障碍审计流程。它实现了三阶段工作流——扫描、修复、验证——用于识别 WCAG 2.2 Level A 和 AA 违规项，按框架生成精确的修复代码，并生成可供利益相关方查阅的合规报告。

对于发现的每一处违规，它都会针对你的框架（React、Next.js、Vue、Angular、Svelte 或纯 HTML）提供精确的修改前/修改后代码修复。

本技能的功能：

1. 扫描代码库中所有 WCAG 2.2 Level A 和 AA 违规项，并按严重程度（Critical、Major、Minor）分类
2. 修复每个违规项，提供与框架相关的修改前/修改后代码模式
3. 验证修复是否解决了原有违规，且未引入回归问题
4. 报告审计结果，格式适用于开发者、产品经理和合规利益相关方
5. 集成到 CI/CD 流水线中，防止无障碍性回归

Features

Feature	Description
Full WCAG 2.2 Scan	检查代码库中所有 Level A 和 AA 成功标准
Framework Detection	自动检测 React、Next.js、Vue、Angular、Svelte 或纯 HTML
Severity Classification	将每个违规项分类为 Critical、Major 或 Minor
Fix Code Generation	为每个问题生成修改前/修改后的代码差异
Color Contrast Checker	根据 AA 和 AAA 对比度标准验证前景色/背景色组合
Compliance Reporting	生成包含通过/未通过摘要的利益相关方报告
CI/CD Integration	支持 GitHub Actions、GitLab CI、Azure DevOps 流水线配置
Keyboard Navigation Audit	检测缺失的焦点管理和 Tab 顺序问题
ARIA Validation	检查不正确、冗余或缺失的 ARIA 属性

Severity Definitions

Severity	Definition	Example	SLA
Critical	阻碍整个用户群体的访问	缺失 alt 文本，导航无法通过键盘访问	发布前修复
Major	严重阻碍，显著降低体验	颜色对比度不足，表单缺少标签	在当前迭代内修复
Minor	造成使用不便的可用性问题	冗余的 ARIA 角色，标题层级不够理想	在接下来 2 个迭代内修复

Usage

Quick Start

# Scan entire project
python scripts/a11y_scanner.py /path/to/project

# Scan with JSON output for tooling
python scripts/a11y_scanner.py /path/to/project --json

# Check color contrast for specific values
python scripts/contrast_checker.py --fg "#777777" --bg "#ffffff"

# Check contrast across a CSS/Tailwind file
python scripts/contrast_checker.py --file /path/to/styles.css

Slash Command

/a11y-audit                    # Audit current project
/a11y-audit --scope src/       # Audit specific directory
/a11y-audit --fix              # Audit and auto-apply fixes
/a11y-audit --report           # Generate stakeholder report
/a11y-audit --ci               # Output CI-compatible results

Three-Phase Workflow

Phase 1: Scan -- 遍历源代码树，检测框架，应用规则集。

python scripts/a11y_scanner.py /path/to/project --format table

Phase 2: Fix -- 针对每个违规项应用与框架相关的修复。

完整的修复模式目录请参见 references/framework-a11y-patterns.md。

Phase 3: Verify -- 重新运行扫描器，确认修复效果并检查是否存在回归。

python scripts/a11y_scanner.py /path/to/project --baseline audit-baseline.json

Example: React Component Audit

// BEFORE: src/components/ProductCard.tsx
function ProductCard({ product }) {
  return (
    <div onClick={() => navigate(`/product/${product.id}`)}>
      <img src={product.image} />
      <div style={{ color: '#aaa', fontSize: '12px' }}>{product.name}</div>
      <span style={{ color: '#999' }}>${product.price}</span>
    </div>
  );
}

#	WCAG	Severity	Issue
1	1.1.1	Critical	<img> 缺少 alt 属性
2	2.1.1	Critical	<div onClick> 无法通过键盘访问
3	1.4.3	Major	白底上的颜色 #aaa 对比度不达标（2.32:1，需要 4.5:1）
4	1.4.3	Major	白底上的颜色 #999 对比度不达标（2.85:1，需要 4.5:1）
5	4.1.2	Major	交互元素缺少角色和可访问名称

// AFTER: src/components/ProductCard.tsx
function ProductCard({ product }) {
  return (
    <a href={`/product/${product.id}`} className="product-card"
       aria-label={`View ${product.name} - $${product.price}`}>
      <img src={product.image} alt={product.imageAlt || product.name} />
      <div style={{ color: '#595959', fontSize: '12px' }}>{product.name}</div>
      <span style={{ color: '#767676' }}>${product.price}</span>
    </a>
  );
}

Vue、Angular、Next.js 和 Svelte 的示例请参见 references/examples-by-framework.md。

Tools Reference

a11y_scanner.py

Usage: python scripts/a11y_scanner.py <path> [options]

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

Usage: python scripts/contrast_checker.py [options]

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: none	始终通过 focus-visible 提供可见的焦点指示器
信息性图片使用空的 alt=""	信息性图片需要有描述性的 alt 文本
跳过标题级别（h1 -> h3）	标题级别必须依次递进
只有 onClick 而没有 onKeyDown	添加键盘支持，或优先使用原生元素
忽略 prefers-reduced-motion	将动画包裹在 @media (prefers-reduced-motion: no-preference) 中

相关 Skills

Skill	关系
senior-frontend	无障碍修复中使用的前端模式
code-reviewer	将无障碍检查纳入代码审查工作流
senior-qa	将无障碍测试集成到 QA 流程中
playwright-pro	带有无障碍断言的自动化浏览器测试
epic-design	符合 WCAG 2.1 AA 标准的动画与滚动叙事
tdd-guide	用于无障碍测试用例的测试驱动开发模式

参考文档

参考	描述
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	特定框架的修复模式（React、Vue、Angular、Svelte、HTML）
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 创作实践 1.2
• Deque axe-core 规则
• eslint-plugin-jsx-a11y