如何创建无障碍文档
遵循 WCAG 指南创建无障碍文档，包括语义化 HTML、键盘导航、替代文本和包容性内容实践。
当你编写无障碍文档时，你会优先考虑内容设计，使尽可能多的用户都能使用你的文档，而不受其访问和交互方式的限制。
无障碍文档能改善所有人的使用体验。无论用户是通过屏幕阅读器、键盘导航、移动设备，还是慢速网络访问，你的内容都将更清晰、结构更合理、导航更便捷。
本指南介绍创建无障碍文档的最佳实践。无障碍是一项持续的工作。技术和标准会不断演进，始终存在改进的机会。请从影响最大的改动入手，并将无障碍融入你的工作流程。
无障碍（有时缩写为 a11y，意指”accessibility”首尾字母之间的 11 个字母）是指有意识地设计和构建尽可能多的人都能使用的网站和工具。无论是临时还是永久性的残障人士，都应当享有与他人同等水平的数字技术可达性。而为无障碍而设计也能惠及所有人，包括那些通过移动设备或在慢速网络上访问你网站的用户。
无障碍的文档应遵循网页无障碍标准，主要是 网页内容无障碍指南（WCAG）。这些指南有助于确保你的内容具有可感知、可操作、可理解和健壮性等特征。
让你的文档具备可访问性是一个过程。你不必一次性修复所有问题，也不能一次完成就了事。
如果你刚开始为文档落实无障碍实践，可以考虑采取分阶段的方法：先从影响最大的改动入手，再循序推进。
以下是你现在就可以采取的三项措施，来提升文档的可访问性：
- 运行
mint a11y，识别 content 中的可访问性问题。 - 为所有图片添加替代文本（alt text）。
- 检查标题层级，确保每页只有一个 H1，且各级标题按顺序递进。
最好的工作流程是最适合你团队的那个。下面是开展无障碍工作的一个可行方法：
阶段 1：图像与结构
- 检查所有图像是否包含具有描述性的 alt 文本。
- 审核链接文本，替换”点击这里”等泛泛表述。
- 修复整份文档中的标题层级问题。
阶段 2：导航与媒体
- 在文档中测试键盘导航。
- 测试屏幕阅读器兼容性。
- 为嵌入视频添加字幕和文字稿。
- 检查颜色对比度。
阶段 3：融入你的工作流程
- 在发布新内容前运行
mint a11y。 - 将无障碍检查纳入内容评审流程。
- 添加交互功能时测试键盘导航。
- 确认新的外部链接和嵌入包含合适的标题和说明。
从小处着手，并将无障碍纳入日常工作流程，才能长期坚持。每一次改进都能帮助更多用户顺利使用你的文档。
结构清晰的内容更便于浏览和理解，尤其有助于依靠标题在页面间移动的屏幕阅读器用户，以及使用键盘进行导航的用户。
每个页面应只有一个 H1 标题，该标题来自页面 frontmatter 中的 title: 属性。按顺序使用后续标题，避免跳级。例如，不要从 H2 直接跳到 H4。
<!-- 正确 -->
# 页面标题 (H1)
## 主要章节 (H2)
### 子章节 (H3)
### 另一个子章节 (H3)
## 另一个主要章节 (H2)
<!-- 错误 -->
# 页面标题 (H1)
## 主要章节 (H2)
#### 子章节 (H4)
### 另一个子章节 (H3)同一层级的标题应具有唯一名称。
<!-- 好的示例 -->
## 无障碍功能提示 (H2)
### 编写有效的替代文本 (H3)
### 使用适当的颜色对比度 (H3)
<!-- 不好的示例 -->
## 无障碍功能提示 (H2)
### 提示 (H3)
### 提示 (H3)链接文本应当有意义，并清楚表明其指向的内容。避免使用诸如”点击这里”或”了解更多”这类含糊的表述。
<!-- 好的示例 -->
了解如何 [配置导航](/organize/navigation)。
<!-- 链接文本与目标之间的关系不明确 -->
[了解更多](/organize/navigation)。- 拆分长段落。
- 使用列表呈现步骤和选项。
- 通过提示框突出关键信息。
尽量少用表格，仅在需要呈现由行列标题传达含义的表格数据时使用。
使用表格时，请包含表头，以便屏幕阅读器能将数据与正确的列关联：
| 功能 | 状态 | 最近更新 |
| ------- | ------ | ------------ |
| 搜索 | 启用 | 2024-03-15 |
| Analytics | 启用 | 2024-03-10 |
| 导出 | Beta | 2024-03-20 |较差的示例缺少表头，屏幕阅读器无法说明每一列代表的含义。
替代文字有助于屏幕阅读器用户理解图像，并会在图像加载失败时显示。文档中的图像应包含能够描述图像并清楚说明你为何包含该图像的替代文字。即使提供了替代文字，也不应仅依赖图像来传达信息。请确保你的内容能够表达图像所传达的要点。
进一步了解如何处理图像，请参阅 媒体指南。
- 具体明确：描述图像所展示的内容，而不是只说明这是一张图片。
- 简洁凝练：控制在一到两句话。
- 避免冗余：不要以”Image of”开头，因为屏幕阅读器已经知道替代文本属于图像。但如果这些信息对图像的 context 很重要，可以包含诸如”Screenshot of”或”Diagram of”之类的描述。
<!-- 好的示例 -->
<!-- 不够有用的示例 -->
对于 Markdown 图像，请在方括号中填写替代文本：
对于 HTML 图片，请使用 alt 属性：
<img
src="/images/screenshot.png"
alt="设置面板，已启用无障碍功能选项。选项以橙色矩形框突出显示。"
/>iframe 和视频嵌入需要提供描述性标题：
<iframe
src="https://www.youtube.com/embed/example"
title="教程：设置您的第一个文档站点"
></iframe>视觉设计的取舍会影响低视力、色盲或其他视觉障碍用户获取你文档信息的可访问性。
如果你自定义了主题颜色，请确认对比度符合 WCAG 要求：
- 正文：最低 4.5:1 对比度
- 大号文本：最低 3:1 对比度
- 交互元素：最低 3:1 对比度
请同时测试 light 与深色模式。mint a11y 命令会检查色彩对比度。
{
"colors": {
"primary": "#0066CC",
"background": {
"light": "#FFFFFF",
"dark": "#1A1A1A"
}
}
}在较差示例中，黄色 (#FFCC00) 与白色背景对比度不足。深色模式下的背景 (#333333) 偏亮，不利于最佳可读性。
如果你用颜色来传达信息，请同时加入文本标签或 icon。例如，不要仅用红色文字标记错误；请加入错误 icon 或”错误”一词。
- 使用通俗易懂的语言撰写内容。
- 在技术术语首次出现时给出定义。
- 避免冗长拖沓的长句。
- 使用主动语态。
更多写作最佳实践请参阅 风格与语调指南。
代码块是技术文档的重要组成部分，但为确保屏幕阅读器用户能理解，它们需要特定的无障碍设计考量。一般而言，请遵循以下指南：
- 将较长的代码示例拆分为更小且逻辑清晰的片段。
- 在代码中为复杂逻辑添加注释。
- 考虑为复杂算法提供文字说明。
- 展示文件结构时，使用带语言标签的实际代码块，而非 ASCII 艺术。
务必为语法高亮声明所用语言。这有助于屏幕阅读器向用户说明代码的 context：
```javascript
function getUserData(id) {
return fetch(`/api/users/${id}`);
}
```为代码块提供清晰的上下文：
以下函数从 API 获取用户数据：
```javascript
function getUserData(id) {
return fetch(`/api/users/${id}`);
}
```
这将返回一个解析为用户对象的 Promise。视频、动画及其他多媒体内容需要提供文本替代，确保所有用户都能获取其中的信息。
字幕可让聋人或听力障碍用户更便捷地获取视频内容，也能帮助处于对声音敏感环境的用户以及非母语使用者：
- 为视频中的所有口语内容提供字幕。
- 在字幕中包含相关的音效描述。
- 确保字幕与音频同步。
- 当多人发言时，使用正确的标点并标注说话者。
大多数视频托管平台都支持添加字幕。可上传字幕文件，或先使用自动生成的字幕作为基础，再进行准确性校对。
文字稿为获取视频内容提供了一种替代方式。它可被搜索、更便于引用，并且对屏幕阅读器更加友好：
<iframe
src="https://www.youtube.com/embed/example"
title="教程：设置认证"
></iframe>
<Accordion title="视频文稿">
在本教程中，我们将逐步介绍如何设置认证...
</Accordion>将文字稿放在视频附近，或提供明确的访问链接。
如果关键信息只出现在视频中：
- 提供等效的文本版本。
- 附上关键截图，并配有描述性替代文本（alt 文本）。
- 编写涵盖同样内容的图文教程。
这样可确保无法访问视频内容的用户仍然能够完成其任务。
定期测试可在用户遇到问题之前发现无障碍问题。
使用 mint a11y 命令行界面（CLI）命令自动扫描文档，检测常见的无障碍问题：
mint a11y该命令会检查：
- 图像和视频缺少替代文本（alt）。
- 颜色对比度不足。
扫描完成后，你会看到类似如下的报告：
Accessibility Issues Found:
❌ Missing alt text (3 issues)
- /guides/quickstart.mdx:45 - Image missing alt text
- /api-reference/users.mdx:12 - Image missing alt text
- /guides/setup.mdx:89 - Video missing title attribute
⚠️ Color contrast (2 issues)
- Primary color (#FFCC00) on light background fails WCAG AA (2.1:1)
- Link color (#FF6B6B) on dark background fails WCAG AA (3.2:1)
✅ 0 issues found in 15 other pages缺少替代文本：为图像或视频添加描述性替代文本：
<!-- 修改前 -->
<!-- 修改后 -->
颜色对比度不达标：在 docs.json 中更新主题颜色：
{
"colors": {
"primary": "#0066CC", // 由 #FFCC00 修改而来
"light": "#3399FF",
"dark": "#004C99"
}
}再次运行 mint a11y 以验证修复结果。
使用 flag 检查特定的无障碍问题：
# 仅检查缺少替代文本的问题
mint a11y --skip-contrast
# 仅检查颜色对比度问题
mint a11y --skip-alt-text
# 发现问题时使 CI/CD 流水线失败
mint a11y --fail-on-error仅使用键盘浏览文档：
- 按 Tab 在交互元素间向前移动。
- 按 Shift + Tab 向后移动。
- 按 Enter 激活链接和按钮。
- 确认所有交互元素均可到达，并具有可见的焦点指示。
如需进行更全面的测试：
- 屏幕阅读器：使用 NVDA（Windows） 或 VoiceOver（Mac） 进行测试。
- 浏览器扩展：安装 axe DevTools 或 WAVE，对页面进行问题扫描。
- WCAG 指南：查阅 Web Content Accessibility Guidelines，了解详细标准。
通过以下权威资源继续学习无障碍：
- WebAIM：关于网页无障碍的实用文章与教程
- The A11y Project：社区驱动的无障碍资源与检查清单
- W3C Web Accessibility Initiative (WAI)：官方无障碍标准与指南