ACCESSIBILITY.md 进仓库首页：无障碍声明该写哪些可核对内容

如果你维护一个开源仓库，并想让无障碍问题有一个固定入口，ACCESSIBILITY.md 就是放在仓库里的那份声明文件。按 GitHub 博客的说法，这类文件会被突出展示，用来记录无障碍目标、已知障碍、支持环境、贡献者期望和报告流程（来源：GitHub Blog，2026-11-05）。关键不在于写得多长，而在于每一条都能被外部读者按步骤核对。本文讨论“该写哪些可核对的内容”，不涉及具体界面呈现。

先明确材料的边界#

可确认的事实只有摘要层面：GitHub 会 highlight ACCESSIBILITY.md 文件，并把它作为记录上述五类信息的载体。材料没有说明文件必须放在哪个路径、在页面哪个位置展示、是否影响仓库搜索结果或徽章。这些属于待核实，不应在文章或声明里当成已知行为来写。本文提供的写法与示例属于建议，示例中的域名、邮箱、版本号均为占位或演示，未在真实仓库运行。

五类信息，分别怎么写成可核对项#

目标要带标准和版本

WCAG 指 Web Content Accessibility Guidelines（Web 内容无障碍指南）。写“以 WCAG 2.2 AA 为目标”比写“尽量无障碍”可核对，因为读者知道按哪套成功准则检查。同时要写范围：只覆盖 Web 前端，还是也包括文档站、CLI、移动端。未覆盖的部分明确列出，比含糊带过更诚实。

障碍要能定位到界面

一条可用的障碍记录至少包含：位置、表现、对谁造成影响、跟踪链接、有没有临时绕行方式。这样贡献者能复现，也能判断问题是否已被记录。没有 issue 编号的条目，至少给一个日期，说明这是某次核对的结果。

环境要区分“核对过”和“没核对”

无障碍结论高度依赖环境组合。写清“Firefox 128 + NVDA 2024.4（Windows 11）已核对”和“Safari + VoiceOver 未核对”，读者就知道结论的适用范围。只写“支持主流环境”无法核对，也无法证伪。

贡献者期望要能在评审时判定

把要求写成 review 时能回答“是/否”的条目：交互元素可键盘操作且有可见焦点；图片提供有意义的替代文本，装饰图用空 alt；提交 PR 时说明是否影响无障碍以及如何手动验证。这比引用一份外部规范更容易执行。

报告流程要给最小信息集

写清渠道（issue 模板或邮箱占位）、需要哪些信息（页面地址、浏览器与辅助技术版本、复现步骤）、多久确认收到。响应时间写成“目标：5 个工作日内确认”，并注明不是保证，避免把流程写成服务承诺。

一个最小示例#

下面是演示用片段，未在真实仓库执行；域名、邮箱、版本号均为占位，请替换为你的实际信息。

# Accessibility

## 目标与范围
- 目标：WCAG 2.2 AA
- 覆盖：Web 前端与文档站
- 未覆盖：CLI、移动端（截至 2026-11 未做系统性评估）

## 已知障碍
| 位置 | 表现 | 影响 | 跟踪 |
| --- | --- | --- | --- |
| 设置页下拉框 | 键盘无法展开 | 无法用键盘完成配置 | #123 |

## 支持环境
- 已核对：Firefox 128 + NVDA 2024.4（Windows 11）
- 未核对：Safari + VoiceOver、移动端

## 贡献者期望
- 交互元素可键盘操作，且有可见焦点
- 图片提供有意义的 alt，装饰图用 alt=""
- PR 描述中说明是否影响无障碍，以及如何手动验证

## 报告问题
- 渠道：issue 模板 Accessibility，或 accessibility@example.com（占位）
- 请提供：页面 URL、浏览器与辅助技术版本、复现步骤
- 响应目标：5 个工作日内确认收到（目标，非保证）

维护与边界#

• 声明要带日期和版本，并在环境或障碍变化时更新；一次写完就不再改的文件很快会失真。
• 不要把 ACCESSIBILITY.md 当作合规认证。符合某项标准通常需要按既定方法评估并保留记录，声明只描述现状与流程。
• 小项目可以先写三节：范围、已知障碍、报告渠道，再逐步补充。字段齐全但内容空洞，不如少写几条可核对的。
• 与 SECURITY.md、CONTRIBUTING.md 的分工要写清：无障碍问题走哪个入口，避免报告者不知道往哪提交。
• GitHub 具体如何识别与展示该文件，请以官方文档或实际仓库表现为准；本文材料未覆盖这部分。