# Fixing Accessibility

> 审计并修复 HTML 可访问性问题，包括 ARIA 标签、键盘导航、焦点管理、颜色对比度和表单错误。当添加交互控件、表单、对话框，或审查 WCAG 合规性时使用。触发词：可访问性、a11y、ARIA、WCAG、键盘导航、屏幕阅读器、对比度。

- Skill: `kscz0000/fixing-accessibility` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kscz0000/fixing-accessibility`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/fixing-accessibility/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: kscz0000 (https://skillmd.com/u/kscz0000)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/kscz0000/fixing-accessibility

---


# fixing-accessibility

修复可访问性问题。

## 使用方法

- `/fixing-accessibility`
  将这些约束应用于本对话中的所有 UI 工作。

- `/fixing-accessibility <file>`
  按下方所有规则审查该文件并报告：
  - 违规点（引用准确的行或片段）
  - 为什么重要（一句话）
  - 具体修复建议（代码级）

不要重写 UI 的大块内容。优先做最小、有针对性的修复。

## 何时使用

在以下情况参考这些指南：
- 添加或修改按钮、链接、输入框、菜单、对话框、标签页、下拉框
- 构建表单、校验、错误状态、辅助文本
- 实现键盘快捷键或自定义交互
- 处理焦点状态、焦点陷阱或模态行为
- 渲染仅图标的控件
- 添加仅悬停的交互或隐藏内容

## 规则类别（按优先级）

| 优先级 | 类别 | 影响 |
|:------:|------|:----:|
| 1 | 可访问名称 | 严重 |
| 2 | 键盘访问 | 严重 |
| 3 | 焦点与对话框 | 严重 |
| 4 | 语义 | 高 |
| 5 | 表单与错误 | 高 |
| 6 | 公告 | 中-高 |
| 7 | 对比度与状态 | 中 |
| 8 | 媒体与动效 | 低-中 |
| 9 | 工具边界 | 严重 |

## 速查

### 1. 可访问名称（严重）

- 每个交互控件必须具有可访问名称
- 仅图标的按钮必须有 `aria-label` 或 `aria-labelledby`
- 每个 `input` / `select` / `textarea` 必须有 label
- 链接必须有有意义的文本（不要"点击这里"）
- 装饰性图标必须使用 `aria-hidden`

### 2. 键盘访问（严重）

- 不要在不具备完整键盘支持的情况下用 `div` 或 `span` 作为按钮
- 所有交互元素必须可通过 Tab 访问
- 键盘用户的焦点必须可见
- 不要使用大于 0 的 `tabindex`
- Escape 必须在适当时关闭对话框或浮层

### 3. 焦点与对话框（严重）

- 模态打开时必须陷阱焦点
- 关闭时将焦点恢复到触发元素
- 在对话框内设置初始焦点
- 打开对话框不应意外滚动页面

### 4. 语义（高）

- 优先使用原生元素（`button`、`a`、`input`）而非 role 模拟
- 如果使用 role，所需的 aria 属性必须存在
- 列表必须使用 `ul` 或 `ol` 加 `li`
- 不要跳过标题层级
- 表格的表头必须使用 `th`（如适用）

### 5. 表单与错误（高）

- 错误必须使用 `aria-describedby` 关联到字段
- 必填字段必须被播报
- 无效字段必须设置 `aria-invalid`
- 辅助文本必须与输入关联
- 禁用的提交动作必须说明原因

### 6. 公告（中-高）

- 关键表单错误应使用 `aria-live`
- 加载状态应使用 `aria-busy` 或状态文本
- 提示框不能是传递关键信息的唯一方式
- 可展开控件必须使用 `aria-expanded` 和 `aria-controls`

### 7. 对比度与状态（中）

- 确保文本和图标有足够对比度
- 仅悬停的交互必须有键盘等价物
- 禁用状态不能仅依赖颜色
- 不要移除焦点轮廓而无可视替代

### 8. 媒体与动效（低-中）

- 图片必须有正确的 `alt` 文本（有意义的或空的）
- 含语音的视频在适当时应提供字幕
- 尊重 `prefers-reduced-motion` 处理非必要动效
- 避免自动播放含声音的媒体

### 9. 工具边界（严重）

- 优先做最小改动，不要重构无关代码
- 当原生语义已解决问题时不要添加 aria
- 除非被请求，否则不要迁移 UI 库

## 常见修复

```html
<!-- 仅图标按钮：添加 aria-label -->
<!-- before --> <button><svg>...</svg></button>
<!-- after -->  <button aria-label="关闭"><svg aria-hidden="true">...</svg></button>

<!-- div 当按钮用：使用原生元素 -->
<!-- before --> <div onclick="save()">保存</div>
<!-- after -->  <button onclick="save()">保存</button>

<!-- 表单错误：用 aria-describedby 关联 -->
<!-- before --> <input id="email" /> <span>邮箱无效</span>
<!-- after -->  <input id="email" aria-describedby="email-err" aria-invalid="true" /> <span id="email-err">邮箱无效</span>
```

## 审查指导

- 优先修复严重问题（名称、键盘、焦点、工具边界）
- 优先使用原生 HTML，再考虑添加 aria
- 引用准确片段，说明问题，提出小修复
- 对于复杂组件（菜单、对话框、组合框），优先使用成熟的辅助功能原语，而非自定义行为

## 限制

- 仅当任务明确匹配上述范围时使用本技能。
- 不要将输出视为环境特定验证、测试或专家审查的替代品。
- 如果缺少必需的输入、权限、安全边界或成功标准，请停止并要求澄清。