无障碍测试超能力
依据 WCAG 标准审计网页组件,结合自动化扫描、键盘与屏幕阅读器测试定位违规,按严重性给出 ARIA、表单标签、对比度与焦点修复代码,并用验证清单确认达标。
完整提示词
---
name: accessibility-testing-superpower
description: |
执行 Web 应用程序的 WCAG 合规性审计和无障碍修复。
使用场景:1) 对 UI 进行 WCAG 2.1/2.2 合规性审计 2) 修复屏幕阅读器或键盘导航问题 3) 正确实现 ARIA 模式 4) 审查颜色对比度和视觉无障碍性 5) 创建无障碍表单或交互式组件
---
# 无障碍测试工作流
## 配置
- **WCAG 级别**: ${wcag_level:AA}
- **被测组件**: ${component_name:Page}
- **合规标准**: ${compliance_standard:WCAG 2.1}
- **最低 Lighthouse 分数**: ${lighthouse_score:90}
- **主要屏幕阅读器**: ${screen_reader:NVDA}
- **测试框架**: ${test_framework:jest-axe}
## 审计决策树
```
收到无障碍请求
|
+-- 新组件/页面?
| +-- 首先运行自动化扫描(axe-core, Lighthouse)
| +-- 键盘导航测试
| +-- 屏幕阅读器播报检查
| +-- 颜色对比度验证
|
+-- 存在需修复的现有违规?
| +-- 确定对应的 WCAG 成功准则
| +-- 检查语义化 HTML 是否可解决
| +-- 仅在 HTML 不足时应用 ARIA
| +-- 使用辅助技术验证修复效果
|
+-- 合规性审计?
+-- 自动化扫描(可捕获约 30% 的问题)
+-- 手动测试清单
+-- 按严重性记录违规项
+-- 创建修复路线图
```
## WCAG 快速参考
### 严重性分类
| 严重性 | 影响 | 示例 | 修复时间线 |
|----------|--------|----------|--------------|
| 致命 | 完全阻碍访问 | 无键盘焦点、空按钮、功能性图像缺少 alt | 立即 |
| 严重 | 重大障碍 | 对比度差、缺少表单标签、无跳过链接 | 本迭代内 |
| 中等 | 使用困难但仍可用 | 导航不一致、错误信息不明确 | 下一版本 |
| 轻微 | 使用不便 | 冗余的 alt 文本、轻微的标题层级问题 | 待办事项 |
### 常见违规及修复方法
**缺少可访问名称**
```html
<!-- 违规 -->
<button><svg>...</svg></button>
<!-- 修复:aria-label -->
<button aria-label="关闭对话框"><svg>...</svg></button>
<!-- 修复:视觉隐藏文本 -->
<button><span class="sr-only">关闭对话框</span><svg>...</svg></button>
```
**表单标签关联**
```html
<!-- 违规 -->
<label>邮箱</label>
<input type="email">
<!-- 修复:显式关联 -->
<label for="email">邮箱</label>
<input type="email" id="email">
<!-- 修复:隐式关联 -->
<label>邮箱 <input type="email"></label>
```
**颜色对比度不达标**
```
最低对比度比例(WCAG ${wcag_level:AA}):
- 普通文本(<${large_text_size:18}px 或 <${bold_text_size:14}px 加粗):${contrast_ratio_normal:4.5}:1
- 大号文本(>=${large_text_size:18}px 或 >=${bold_text_size:14}px 加粗):${contrast_ratio_large:3}:1
- UI 组件和图形:3:1
工具:WebAIM Contrast Checker、浏览器 DevTools
```
**焦点可见性**
```css
/* 不提供替代方案时切勿这样做 */
:focus { outline: none; }
/* 正确的自定义焦点样式 */
:focus-visible {
outline: ${focus_outline_width:2}px solid ${focus_outline_color:#005fcc};
outline-offset: ${focus_outline_offset:2}px;
}
```
### 焦点管理模式
**模态框焦点陷阱**
```javascript
// 模态框打开时:
// 1. 保存之前获得焦点的元素
// 2. 将焦点移动到模态框内第一个可聚焦元素
// 3. 将 Tab 键限制在模态框边界内
// 模态框关闭时:
// 1. 将焦点返回至已保存的元素
```
**动态内容**
```javascript
// 添加内容后:
// - 通过 aria-live 区域宣布,或
// - 将焦点移至新内容的标题
// 删除内容后:
// - 将焦点移至逻辑上的下一个元素
// - 绝不能让焦点停留在已被删除的元素上
```
## 屏幕阅读器测试
### 宣告内容验证
| 元素 | 应当宣告的内容 |
|---------|-----------------|
| 按钮 | 角色 + 名称 + 状态(例如“提交按钮”) |
| 链接 | 名称 + “link”(例如“首页链接”) |
| 图像 | 替代文本 或 “decorative”(跳过) |
| 标题 | 级别 + 文本(例如“二级标题,关于我们”) |
| 表单字段 | 标签 + 类型 + 状态 + 说明 |
| 错误 | 错误信息 + 关联字段 |
### 测试命令(快速参考)
**VoiceOver (macOS)**
- VO = Ctrl + Option
- VO + A:朗读全部
- VO + Right/Left:在元素间导航
- VO + Cmd + H:下一个标题
- VO + Cmd + J:下一个表单控件
**${screen_reader:NVDA} (Windows)**
- NVDA + Down:朗读全部
- Tab:下一个可聚焦元素
- H:下一个标题
- F:下一个表单字段
- B:下一个按钮
## 自动化测试集成
### 在测试中使用 axe-core
```javascript
// ${test_framework:jest-axe}
import { axe, toHaveNoViolations } from 'jest-axe';
expect.extend(toHaveNoViolations);
test('${component_name:component} 是无障碍的', async () => {
const { container } = render(<${component_name:MyComponent} />);
const results = await axe(container);
expect(results).toHaveNoViolations();
});
```
### Lighthouse CI 门槛设置
```javascript
// lighthouserc.js
module.exports = {
assertions: {
'categories:accessibility': ['error', { minScore: ${lighthouse_score:90} / 100 }],
},
};
```
## 修复优先级矩阵
```
影响 vs 努力:
低努力 高努力
高影响 | 优先处理 | 计划后续 |
| 替代文本 | 重新设计 |
| 标签 | 导航重构 |
-----------------|---------------|-------------|
低影响 | 快速胜利 | 待办清单 |
| 对比度调整 | 可选优化 |
| | 增强功能 |
```
## 验证清单
在标记无障碍工作完成前:
```
自动化测试:
[ ] axe-core 报告零违规
[ ] Lighthouse 无障碍分数 >= ${lighthouse_score:90}
[ ] HTML 验证通过(影响辅助技术解析)
键盘测试:
[ ] 不使用鼠标即可完成全部任务
[ ] 始终可见焦点
[ ] Tab 键顺序符合逻辑
[ ] 无焦点陷阱
屏幕阅读器测试:
[ ] 至少使用一种屏幕阅读器进行测试 (${screen_reader:NVDA})
[ ] 所有内容均被正确宣告
[ ] 交互元素具有正确的角色/状态
[ ] 动态更新被正确宣告
视觉测试:
[ ] 已验证对比度比率 (${contrast_ratio_normal:4.5}:1 最低要求)
[ ] 在 ${zoom_level:200}% 缩放下正常工作
[ ] 无仅通过颜色传达的信息
[ ] 尊重 prefers-reduced-motion 设置
```可替换内容
- [ ]
分类与标签
编程开发、编程开发、代码