无障碍审计

a11y-audit
分类通用
作者Alireza Rezvani
许可MIT
评分4.80/5
使用12.6K

/a11y-audit

扫描前端项目中的 WCAG 2.2 无障碍问题，提供修复方案，并可选择性地检查颜色对比度。

用法

bash
/a11y-audit                     # 扫描当前项目
/a11y-audit ./src               # 扫描指定目录
/a11y-audit ./src --fix         # 扫描并自动修复可修复项

工作流程

第一步：扫描

在目标目录运行 a11y 扫描器：

bash
python3 {skill_path}/scripts/a11y_scanner.py {path} --json

解析 JSON 输出。按严重程度对发现的问题进行分组（critical → serious → moderate → minor）。

显示摘要：

code
A11y Audit: ./src
  Critical: 3 | Serious: 7 | Moderate: 12 | Minor: 5
  Files scanned: 42 | Files with issues: 15

第二步：修复

针对每个发现的问题（从 critical 开始）：

1. 读取受影响的文件
2. 展示违规内容及其上下文（修复前）
3. 应用来自 engineering-team/a11y-audit/skills/a11y-audit/references/framework-a11y-patterns.md 的修复方案
4. 展示结果（修复后）

可自动修复的问题（无需询问直接应用）：

  • 装饰性图片缺失 alt=""

  • <html> 标签缺失 lang 属性

  • tabindex 值 > 0 $\rightarrow$ 设置为 0

  • 非提交按钮缺失 type="button"

  • 移除了 outline 但未提供替代方案 $\rightarrow$ 添加 :focus-visible 样式

需要用户输入的问题（展示修复方案，询问是否应用）：

  • 缺失 alt 文本（需要用户提供描述）

  • 缺失表单标签（需要标签文本）

  • 标题结构重组（可能会影响布局）

  • ARIA 角色变更（可能会影响功能）

第三步：对比度检查

如果存在 CSS 文件，运行对比度检查器：

bash
python3 {skill_path}/scripts/contrast_checker.py --batch {path}

针对每组不合格的颜色组合，建议可访问的替代方案。

第四步：报告

在 a11y-report.md 生成 Markdown 报告：

  • 执行摘要（通过/失败，问题数量）

  • 每个文件的发现项及前后对比 (diff)

  • 剩余需要手动审核的项目

  • WCAG 标准覆盖情况

技能参考

  • engineering-team/a11y-audit/skills/a11y-audit/SKILL.md
  • engineering-team/a11y-audit/skills/a11y-audit/scripts/a11y_scanner.py
  • engineering-team/a11y-audit/skills/a11y-audit/scripts/contrast_checker.py
  • engineering-team/a11y-audit/skills/a11y-audit/references/wcag-quick-ref.md
  • engineering-team/a11y-audit/skills/a11y-audit/references/aria-patterns.md
  • engineering-team/a11y-audit/skills/a11y-audit/references/framework-a11y-patterns.md