Oliver Accessibility

无障碍与可访问性（Accessibility / a11y）

帮助前端实现符合 WCAG 理念的无障碍：语义化、ARIA、键盘与焦点、屏幕阅读器支持。

触发场景

• 用户说「无障碍」「可访问性」「a11y」「键盘导航」「读屏适配」「WCAG」
• 需求里提到「残障用户」「视障」「仅用键盘操作」「焦点顺序」
• 设计/产品要求通过 a11y 审计或合规

分析维度

1. 语义与结构

2. 键盘与焦点

3. ARIA 与名称

4. 视觉与对比

执行流程

1. 确认切入点

用户给了什么，决定从哪里开始：

2. 读代码，逐维度检查

拿到代码后，按以下顺序检查（不要跳过，不要只看一个维度）：

语义与结构

• 交互元素是不是用了正确的 HTML 标签？（<button> 不是 <div onClick>，<a href> 不是 <span onClick>）
• 标题层级有没有跳级？（h1 → h3 跳过 h2 是问题）
• 表单每个 input 有没有对应的 <label>？

键盘与焦点

• 所有交互元素能不能用 Tab 键到达？
• 模态框/弹层打开时焦点有没有 trap？关闭后有没有回到触发元素？
• 有没有 outline: none 且没有替代的焦点样式？

ARIA

• 图标按钮、纯图片链接有没有 aria-label？
• 动态内容（toast、错误提示、加载状态）有没有 aria-live？
• 自定义控件（下拉、tab、accordion）有没有正确的 role 和状态属性？

视觉

• 文字与背景对比度是否达到 4.5:1（大字 3:1）？
• 信息传达有没有只靠颜色区分（如红色=错误，但没有图标或文字）？

3. 发现问题后的处理

• 每个问题给出：位置（文件/组件/行）+ 问题描述 + 具体修改代码
• 标优先级：阻塞（用键盘/读屏完全无法使用）> 重要（体验明显受损）> 建议（增强）
• 如果问题很多，先只列阻塞级，问用户：「阻塞级问题有 X 个，先修这些还是一起看完整报告？」

4. 没有代码时怎么办

用户只描述需求、没给代码：直接给出该场景的无障碍实现模板（含 HTML 结构 + ARIA + 键盘交互），不要只给原则列表。

输出模板

## 无障碍检查与改进报告

### 范围与标准
- 范围：…
- 参考：WCAG 2.1 AA / 自定义

### 问题列表（按优先级）
| 位置/组件 | 问题 | 建议修改 | 优先级 |
|-----------|------|----------|--------|
| … | … | … | 高/中/低 |

### 修改要点汇总
- 语义：…
- 键盘/焦点：…
- ARIA/名称：…
- 视觉/对比：…

### 验证建议
- 工具：axe / Lighthouse / WAVE
- 手动：键盘全流程 + 读屏测试

项目相关

• React：焦点用 useRef + focus()，陷阱用 focus-trap-react 或自实现
• Vue：@keydown、ref 聚焦；可配合 vue-a11y 类库
• 组件库：优先用已带 a11y 的（如 Radix、Headless UI），再按需覆盖样式