无障碍审核
名称:a11y-audit 层级:STANDARD 类别:工程 - 前端质量 依赖:Python 3.8+(仅标准库) 作者:Alireza Rezvani 版本:2.1.2 最后更新:2026-03-18 许可证:MIT
名称
a11y-audit -- WCAG 2.2 无障碍审核与修复技能
描述
a11y-audit 技能为现代 Web 应用程序提供完整的无障碍审核管道。它实现三阶段工作流程——扫描、修复、验证——识别 WCAG 2.2 Level A 和 AA 违规,为每个框架生成精确的修复代码,并生成可供利益相关者使用的合规报告。
该技能不仅仅进行检测。针对发现的每个违规,它都会提供根据您的框架(React、Next.js、Vue、Angular、Svelte 或纯 HTML)量身定制的精确修复前后代码。它理解 React JSX 中 <img> 缺少 alt 属性需要与 Vue SFC 或 Angular 模板中相同问题不同的修复模式。
该技能可以做的事情:
- 扫描您的代码库是否存在每个 WCAG 2.2 Level A 和 AA 违规,按严重性分类(严重、主要、次要)
- 修复每个违规,提供框架特定的修复前后代码模式
- 验证修复是否解决了原始违规且未引入回归
- 报告以结构化格式呈现发现,适合开发人员、PM 和合规利益相关者
- 集成到 CI/CD 管道中以防止无障碍回归
关键区别:
- 框架感知的修复模式(而非通用 HTML 建议)
- 颜色对比度分析,提供可访问的替代方案建议
- WCAG 2.2 覆盖范围,包括最新的成功标准(焦点外观、拖拽动作、目标大小)
- 通过 GitHub Actions、GitLab CI 和 Azure DevOps 的 CI/CD 管道集成
- 通过
/a11y-audit斜杠命令支持
功能
核心能力
| 功能 | 描述 |
|---|---|
| 完整 WCAG 2.2 扫描 | 检查代码库中所有 Level A 和 AA 成功标准 |
| 框架检测 | 自动检测 React、Next.js、Vue、Angular、Svelte 或纯 HTML |
| 严重性分类 | 将每个违规归类为严重、主要或次要 |
| 修复代码生成 | 为每个问题生成修复前后的代码差异 |
| 颜色对比度检查器 | 验证前景/背景对是否满足 AA 和 AAA 比率 |
| 可访问替代方案 | 建议满足对比度要求的替换颜色 |
| 合规报告 | 生成带有通过/失败摘要的利益相关者报告 |
| CI/CD 集成 | GitHub Actions、GitLab CI、Azure DevOps 管道配置 |
| 键盘导航审核 | 检测缺少焦点管理和 Tab 键顺序问题 |
| ARIA 验证 | 检查不正确、冗余或缺失的 ARIA 属性 |
| 实时区域检测 | 识别缺少 aria-live 声明的动态内容 |
| 表单无障碍 | 验证标签关联、错误消息和输入类型 |
WCAG 2.2 覆盖矩阵
| 原则 | Level A 标准 | Level AA 标准 |
|---|---|---|
| 可感知 | 1.1.1 非文本内容, 1.2.1-1.2.3 基于时间的媒体, 1.3.1-1.3.3 适应性, 1.4.1-1.4.2 可区分 | 1.3.4-1.3.5 适应性, 1.4.3-1.4.5 对比度和文本图像, 1.4.10-1.4.13 重新流动和内容 |
| 可操作 | 2.1.1-2.1.2 键盘, 2.2.1-2.2.2 时间, 2.3.1 癫痫, 2.4.1-2.4.4 可导航, 2.5.1-2.5.4 输入 | 2.4.5-2.4.7 可导航, 2.4.11 焦点外观(2.2 新增), 2.5.7 拖拽(2.2 新增), 2.5.8 目标大小(2.2 新增) |
| 可理解 | 3.1.1 语言, 3.2.1-3.2.2 可预测, 3.3.1-3.3.2 输入辅助 | 3.1.2 部分语言, 3.2.3-3.2.4 可预测, 3.3.3-3.3.4 错误处理, 3.3.7 冗余输入(2.2 新增), 3.3.8 可访问认证(2.2 新增) |
| 健壮 | 4.1.2 名称/角色/值 | 4.1.3 状态消息 |
严重性定义
| 严重性 | 定义 | 示例 | SLA |
|---|---|---|---|
| 严重 | 阻止整个用户群体访问 | 信息性图像缺少替代文本,主导航无法通过键盘访问 | 发布前修复 |
| 主要 | 显著障碍,降低体验 | 正文颜色对比度不足,缺少表单标签 | 当前 Sprint 修复 |
| 次要 | 引起不便的可用性问题 | 冗余 ARIA 角色,标题层次不优化 | 下两个 Sprint 修复 |
使用说明
快速启动
激活技能并对您的项目运行审核:
# 扫描整个项目
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 # 审核当前项目
/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
示例输出:
A11Y 审核报告 - /path/to/project
检测到的框架:React (Next.js)
扫描文件数:127
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
严重(3 个问题)
[1.1.1] src/components/Hero.tsx:14
在 <img> 元素上缺少替代文本
[2.1.1] src/components/Modal.tsx:8
焦点未限制在模态对话框内
[1.4.3] src/styles/globals.css:42
对比度 2.8:1 在 .subtitle 上(需要 4.5:1)
主要(7 个问题)
[2.4.11] src/components/Button.tsx:22
焦点指示器不可见(需要 2px 轮廓)
[1.3.1] src/components/Form.tsx:31
输入缺少关联的 <label>
...
次要(4 个问题)
[1.3.1] src/components/Nav.tsx:5
<nav> 具有冗余的 role="navigation"
...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
摘要:14 个违规(3 严重,7 主要,4 次要)
WCAG 2.2 Level A: 8 个问题
WCAG 2.2 Level AA:6 个问题
阶段 2:修复
对于每个违规,应用特定框架的修复。该技能为每种问题类型提供精确的修复前后代码。
请参阅下面的[按框架划分的修复模式]部分以获取完整的修复目录。
阶段 3:验证
重新运行扫描器以确认所有修复已应用且未引入回归:
# 修复后重新扫描
python scripts/a11y_scanner.py /path/to/project --format table
# 与基线比较
python scripts/a11y_scanner.py /path/to/project --baseline audit-baseline.json
验证输出:
验证结果
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
上次扫描: 14 个违规(3 严重,7 主要,4 次要)
当前扫描: 2 个违规(0 严重,1 主要,1 次要)
已解决: 12 个违规
新问题: 0 回归
状态:已改进(减少 85.7%)
示例
示例 1:React 组件审核
给定一个存在多个无障碍问题的 React 组件:
// 修复前: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 | 严重性 | 问题 |
|---|---|---|---|
| 1 | 1.1.1 | 严重 | <img> 缺少 alt 属性 |
| 2 | 2.1.1 | 严重 | <div onClick> 无法通过键盘访问 |
| 3 | 1.4.3 | 主要 | 颜色 #aaa 在白色上对比度失败(2.32:1,需要 4.5:1) |
| 4 | 1.4.3 | 主要 | 颜色 #999 在白色上对比度失败(2.85:1,需要 4.5:1) |
| 5 | 4.1.2 | 主要 | 交互元素缺少角色和可访问名称 |
// 修复后:src/components/ProductCard.tsx
function ProductCard({ product }) {
return (
<a
href={`/product/${product.id}`}
className="product-card"
aria-label={`查看 ${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>
);
}
发生了什么变化:
<div onClick>替换为<a href>以支持原生键盘和屏幕阅读器- 为
<img>添加了alt属性,带有有意义的备用内容 aria-label为辅助技术提供了完整上下文- 颜色
#aaa替换为#595959(对比度 7.01:1 -- 通过 AA 和 AAA) - 颜色
#999替换为#767676(对比度 4.54:1 -- 通过 AA)
示例 2:Vue SFC 表单审核
<!-- 修复前:src/components/LoginForm.vue -->
<template>
<form @submit="handleLogin">
<input type="text" placeholder="电子邮件" v-model="email" />
<input type="password" placeholder="密码" v-model="password" />
<div v-if="error" style="color: red">{{ error }}</div>
<div @click="handleLogin">登录</div>
</form>
</template>
检测到的违规:
| # | WCAG | 严重性 | 问题 |
|---|---|---|---|
| 1 | 1.3.1 | 严重 | 输入缺少关联的 <label> 元素 |
| 2 | 3.3.2 | 主要 | 占位符文本作为唯一标签(输入时消失) |
| 3 | 2.1.1 | 严重 | <div @click> 无法通过键盘访问 |
| 4 | 4.1.3 | 主要 | 错误消息未向屏幕阅读器宣告 |
| 5 | 3.3.1 | 主要 | 错误未以编程方式与输入关联 |
<!-- 修复后:src/components/LoginForm.vue -->
<template>
<form @submit.prevent="handleLogin" aria-label="登录您的账户">
<div class="field">
<label for="login-email">电子邮件</label>
<input
id="login-email"
type="email"
v-model="email"
autocomplete="email"
required
:aria-describedby="emailError ? 'email-error' : undefined"
:aria-invalid="!!emailError"
/>
<span v-if="emailError" id="email-error" role="alert">
{{ emailError }}
</span>
</div>
<div class="field">
<label for="login-password">密码</label>
<input
id="login-password"
type="password"
v-model="password"
autocomplete="current-password"
required
:aria-describedby="passwordError ? 'password-error' : undefined"
:aria-invalid="!!passwordError"
/>
<span v-if="passwordError" id="password-error" role="alert">
{{ passwordError }}
</span>
</div>
<div v-if="error" role="alert" aria-live="assertive" class="form-error">
{{ error }}
</div>
<button type="submit">登录</button>
</form>
</template>
示例 3:Angular 模板审核
<!-- 修复前:src/app/dashboard/dashboard.component.html -->
<div class="tabs">
<div *ngFor="let tab of tabs"
(click)="selectTab(tab)"
[class.active]="tab.active">
{{ tab.label }}
</div>
</div>
<div class="tab-content">
<div *ngIf="selectedTab">{{ selectedTab.content }}</div>
</div>
检测到的违规:
| # | WCAG | 严重性 | 问题 |
|---|---|---|---|
| 1 | 4.1.2 | 严重 | 标签小部件缺少 ARIA 角色(tablist, tab, tabpanel) |
| 2 | 2.1.1 | 严重 | 标签无法通过键盘导航(方向键、Home、End) |
| 3 | 2.4.11 | 主要 | 活动标签上无可见焦点指示器 |
<!-- 修复后:src/app/dashboard/dashboard.component.html -->
<div class="tabs" role="tablist" aria-label="仪表板区域">
<button
*ngFor="let tab of tabs; let i = index"
role="tab"
[id]="'tab-' + tab.id"
[attr.aria-selected]="tab.active"
[attr.aria-controls]="'panel-' + tab.id"
[attr.tabindex]="tab.active ? 0 : -1"
(click)="selectTab(tab)"
(keydown)="handleTabKeydown($event, i)"
class="tab-button"
[class.active]="tab.active">
{{ tab.label }}
</button>
</div>
<div
*ngIf="selectedTab"
role="tabpanel"
[id]="'panel-' + selectedTab.id"
[attr.aria-labelledby]="'tab-' + selectedTab.id"
tabindex="0"
class="tab-content">
{{ selectedTab.content }}
</div>
键盘导航的配套 TypeScript:
// dashboard.component.ts
handleTabKeydown(event: KeyboardEvent, index: number): void {
const tabCount = this.tabs.length;
let newIndex = index;
switch (event.key) {
case 'ArrowRight':
newIndex = (index + 1) % tabCount;
break;
case 'ArrowLeft':
newIndex = (index - 1 + tabCount) % tabCount;
break;
case 'Home':
newIndex = 0;
break;
case 'End':
newIndex = tabCount - 1;
break;
default:
return;
}
event.preventDefault();
this.selectTab(this.tabs[newIndex]);
// 将焦点移动到新标签按钮
const tabElement = document.getElementById(`tab-${this.tabs[newIndex].id}`);
tabElement?.focus();
}
示例 4:Next.js 页面级审核
// 修复前:src/app/page.tsx
export default function Home() {
return (
<main>
<div className="text-4xl font-bold">欢迎来到 Acme</div>
<div className="mt-4">
使用我们的平台构建更好的产品。
</div>
<div className="mt-8 bg-blue-600 text-white px-6 py-3 rounded cursor-pointer"
onClick={() => router.push('/signup')}>
立即开始
</div>
</main>
);
}
检测到的违规:
| # | WCAG | 严重性 | 问题 |
|---|---|---|---|
| 1 | 1.1.1 | 严重 | 缺少页面标题 |
| 2 | 2.4.1 | 主要 | 无跳过导航链接 |
| 3 | 2.1.1 | 严重 | <div onClick> 无法通过键盘访问 |
| 4 | 1.4.1 | 主要 | 仅靠颜色传达链接(无下划线或替代指示器) |
// 修复后:src/app/page.tsx
export default function Home() {
return (
<main>
<a href="#main-content" className="skip-nav">
跳到主要内容
</a>
<div id="main-content">
<h1 className="text-4xl font-bold">欢迎来到 Acme</h1>
<p className="mt-4">
使用我们的平台构建更好的产品。
</p>
<a href="/signup" className="cta-button">
立即开始
</a>
</div>
</main>
);
}
发生了什么变化:
- 添加了
<h1>以提供页面结构和标题 - 添加了跳过导航链接以允许键盘用户绕过重复导航
<div onClick>替换为<a href>以实现原生键盘和屏幕阅读器支持- 按钮现在具有适当的焦点样式和语义
示例 5:颜色对比度修复
/* 修复前:styles/globals.css */
.subtitle {
color: #888;
background-color: #fff;
}
.inactive-tab {
color: #aaa;
background-color: #f5f5f5;
}
颜色对比度结果:
| 元素 | 前景 | 背景 | 比率 | AA (4.5:1) | AAA (7:1) |
|---|---|---|---|---|---|
.subtitle | #888888 | #ffffff | 3.15:1 | ❌ 失败 | ❌ 失败 |
.inactive-tab | #aaaaaa | #f5f5f5 | 2.26:1 | ❌ 失败 | ❌ 失败 |
/* 修复后:styles/globals.css */
.subtitle {
color: #595959; /* 对比度 7.01:1 -- 通过 AAA */
background-color: #fff;
}
.inactive-tab {
color: #767676; /* 对比度 4.54:1 -- 通过 AA */
background-color: #f5f5f5;
}
对比度验证:
| 元素 | 新前景 | 比率 | AA (4.5:1) | AAA (7:1) |
|---|---|---|---|---|
.subtitle | #595959 | 7.01:1 | ✅ 通过 | ✅ 通过 |
.inactive-tab | #767676 | 4.54:1 | ✅ 通过 | ❌ 失败 |
按框架划分的修复模式
React JSX 模式
| WCAG 标准 | 问题 | 修复前 | 修复后 |
|---|---|---|---|
| 1.1.1 | <img> 缺少替代文本 | <img src={src} /> | <img src={src} alt={alt} /> |
| 2.1.1 | 非交互元素上的 onClick | <div onClick={fn}>...</div> | <button onClick={fn}>...</button> 或 <a href={url}>...</a> |
| 2.4.11 | 缺少焦点指示器 | outline: none | outline: 2px solid var(--focus); outline-offset: 2px |
| 1.4.3 | 对比度不足 | #888 / #aaa | #595959 / #767676(AA 比例) |
| 4.1.2 | 缺少 ARIA 标签 | <nav>...</nav> | <nav aria-label="主导航">...</nav> |
Vue SFC 模式
| WCAG 标准 | 问题 | 修复前 | 修复后 |
|---|---|---|---|
| 1.3.1 | 输入缺少标签 | <input v-model="email" /> | <label for="email">电子邮件</label><input id="email" v-model="email" /> |
| 3.3.1 | 无上下文错误 | <div v-if="error">{{error}}</div> | <div v-if="error" role="alert">{{error}}</div> |
| 2.4.11 | 焦点样式缺失 | <div @click="fn"> | <button @click="fn"> 或 :focus-visible 样式 |
Angular 模板模式
| WCAG 标准 | 问题 | 修复前 | 修复后 |
|---|---|---|---|
| 4.1.2 | 自定义控件缺少角色 | <div (click)="select(tab)"> | <button role="tab" (click)="select(tab)"> |
| 2.1.1 | 无键盘导航 | (click) 仅 | (click) + (keydown) 方向键处理 |
| 2.4.11 | 焦点指示器 | 无焦点样式 | CSS :focus-visible 与 outline |
Svelte 模式
| WCAG 标准 | 问题 | 修复前 | 修复后 |
|---|---|---|---|
| 1.1.1 | 装饰性图像 | <img src={src} /> | <img src={src} alt="" role="presentation" /> |
| 2.1.1 | 点击处理程序 | <div on:click={fn}> | <button on:click={fn}> |
| 1.4.3 | 对比度 | 自定义颜色 | 使用 Tailwind CSS text-gray-700(对比度 5.97:1) |
CI/CD 集成
GitHub Actions
# .github/workflows/a11y-audit.yml
name: 无障碍审核
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
jobs:
a11y-audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: 运行 A11Y 审核
run: |
python scripts/a11y_scanner.py . --json --fail-on critical
- name: 上传审核报告
uses: actions/upload-artifact@v4
with:
name: a11y-audit-report
path: a11y-audit-report.json
GitLab CI
# .gitlab-ci.yml
a11y-audit:
stage: quality
script:
- python scripts/a11y_scanner.py . --json --fail-on major
artifacts:
paths:
- a11y-audit-report.json
when: always
only:
- main
- merge_requests
Azure DevOps
# azure-pipelines.yml
- job: A11Y_Audit
pool:
vmImage: 'ubuntu-latest'
steps:
- script: |
python scripts/a11y_scanner.py . --json --fail-on major
displayName: '运行无障碍审核'
- task: PublishBuildArtifacts@1
inputs:
pathToPublish: 'a11y-audit-report.json'
artifactName: 'a11y-audit-report'
故障排除
常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| "无法检测框架" | 项目缺少 package.json 或框架配置文件 | 使用 --framework 标志明确设置:--framework react |
| "对比度检查器失败" | 无效的颜色格式 | 使用十六进制(#RRGGBB)、rgb(rgb(R, G, B))或命名颜色 |
| "扫描时间过长" | 大型代码库或包含 node_modules | 使用 --scope 限制扫描目录或添加 .a11yignore 文件 |
| "修复与我的样式冲突" | 自定义 CSS 覆盖 | 检查生成的 CSS 变量并根据需要调整 |
| "报告生成失败" | 缺少输出目录 | 确保输出目录存在或使用绝对路径 |
获取帮助
- 运行
python scripts/a11y_scanner.py --help查看所有选项 - 运行
python scripts/contrast_checker.py --help查看对比度工具用法 - 报告问题或建议功能:创建 GitHub Issue
- 调优:添加
.a11yignore文件以排除模式(类似于.gitignore格式)
开发指南
添加新规则
- 在
rules/目录中创建新的规则文件 - 使用
@a11y_rule装饰器注册规则 - 实现
check(node)方法,返回Violation对象的列表 - 为每个受支持的框架添加修复模式
- 在
tests/中添加测试用例
运行测试
python -m pytest tests/
许可证
MIT