ACCESSIBILITY.md 怎么写：把无障碍目标与已知障碍写成可核查条目

ACCESSIBILITY.md 是放在代码仓库里的无障碍声明：把“我们重视无障碍”拆成可被别人核查的条目。据 GitHub 博客 2026 年 11 月 5 日的文章，GitHub 现在会突出显示该文件，并帮助维护者记录无障碍目标、已知障碍、支持环境、贡献者期望和报告流程（来源）。GitHub 具体如何识别文件名、在哪些界面展示，本次材料未提供，待核实；写作时应以官方文档和仓库实际表现为准。

先划清文件边界#

• 一个仓库一份，声明对象是本仓库当前版本，不替代公司级法律声明或合规认证。
• 只写能验证的内容：能复现的障碍、能列出的测试环境、能指到的 issue。
• 不做无限承诺：修复时间、覆盖全部辅助技术的保证，材料无法支撑时就写“计划中”或“待核实”。

五个区块各自回答一个问题#

已知障碍：一条一个编号#

“部分组件对读屏不友好”无法核查。改成带编号的表格，让报告者、评审者和后续 issue 都能引用同一条记录。下面的 Markdown 是演示示例，未执行，也不代表官方模板；浏览器与读屏版本按项目实际填写。

## 已知障碍

| ID | 影响 | 环境 | 复现步骤 | 状态 |
| --- | --- | --- | --- | --- |
| A11Y-001 | 键盘无法关闭对话框 | Chrome（版本待核实）+ NVDA（版本待核实） | 打开示例页 → Tab 到“关闭” → 按 Enter | 已确认，未修复 |
| A11Y-002 | 图表缺少文字替代 | 所有环境 | 用读屏浏览“统计”页 | 待核实 |

## 支持环境

- 已验证：占位组合，按测试记录填写
- 未测试：Safari + VoiceOver

## 报告流程

- 渠道：仓库 Issues，标题前缀 `[a11y]`
- 响应：收到后 5 个工作日内确认（示例口径，按项目实际调整）

状态建议只用少数可判定值：已确认、待核实、计划中、已修复。日期用 ISO 格式，便于排序和比对。

三条容易越界的写法#

• “本项目建设完全无障碍”：无法证伪，也不等于任何标准。删掉，改成具体目标与已知障碍清单。
• “符合 WCAG”：必须补上版本、级别、评估范围和评估方式；没有记录时写成目标或待核实。
• 把路线图写成承诺日期：写“计划中”并链接对应 issue，比写一个无法保证的日期更可核查。

维护：让条目跟得上代码#

• 发布前更新“已知障碍”的状态，关闭 issue 时同步修改文件。
• 把更新责任写进贡献指南或发布清单，避免声明长期停在旧版本。
• 用一条简单标准自检：第三方能否在十分钟内复现或证伪这条记录？不能就继续拆细。

ACCESSIBILITY.md 不需要写得长，但每条都要能被别人验证。先固定五个区块，再把已知障碍拆成带编号、环境、步骤和状态的条目，这份声明才真正可用。