← 文章 / 开源项目
GitHub Blog 7天前 · 2026-11-15 11:12:58 · 19 阅读

无障碍声明文件 ACCESSIBILITY.md 现已在 GitHub 上有专属位置

无障碍工作往往分散在 issue 跟踪器、贡献指南、审计报告、团队经验和与用户的沟通之中。这些信息没有固定的存放位置,遇到障碍的人只能四处搜索,而随着贡献者和项目负责人的更替,维护者也会丢失相关背景。 ACCESSIBILITY.md 文件如今会显示在仓库概览页面上,为项目提供一个长期稳定的场所,用来阐明无障碍目标、对贡献者的期望、支持的环境、已知的限制,以及报告障碍的流程。

GitHub 让无障碍声明更容易被找到

GitHub 在 Insights 下的 Community Standards 页面,“Additional community file” 区域显示 Accessibility 卡片,附带用于创建声明的 Add 按钮。

GitHub 现在能够识别位于仓库根目录、.github/ 目录或 docs/ 目录中的 ACCESSIBILITY.md 文件。仓库也可以从所属组织的 .github/ 仓库继承无障碍声明。对于公开仓库,维护者可以在 Insights > Community Standards 中通过一份简洁的模板文档添加或提议声明。

GitHub 的社区健康文件帮助人们了解一个项目是如何运作的:

  • 贡献指南说明如何提议改动
  • 行为准则确立参与项目的期望
  • 安全策略说明如何报告漏洞

识别 ACCESSIBILITY.md 后,无障碍信息就有了与这些指南并列的专属位置。

新建仓库默认还会包含一个 accessibility issue 标签。声明文档解释如何报告障碍以及后续的处理流程,而这个标签则帮助维护者整理和跟进相关工作。

无障碍声明让项目实践更加透明

比如 GitHub CLI 的无障碍声明,就记录了相关设置、已知的障碍和解决方案。它解释了为什么表格输出在屏幕阅读器下难以理解,并提供了一条命令,可以逐行打印 pull request 的编号和标题。它还要求贡献者在修改提示或输出时,展示开启相关无障碍设置后的效果。使用 CLI 的开发者得到了具体的解决方案,参与贡献的开发者也明确了改动需要达到的标准。

GitHub Annotation Toolkit 的无障碍声明记录了其 Figma 库的一个局限:标注是通过画布位置、连接线和对应编号来视觉化表达元素之间的关系的。而单独访问某个画布对象,并不一定能传达出这些关系。

该声明为协作者提供了一个具体的替代方案:提供结构化的文字描述,说明每个被标注的元素、其预期的语义和行为,以及相关的顺序。对于准备或接收设计交接的开发者来说,这说明了视觉标注需要附带哪些信息。

该文件还说明了如何上报无障碍障碍,并明确指出这个库尚未进行纯键盘操作或屏幕阅读器测试。读者既能得到实用指引,也能清楚了解项目实际验证过哪些内容、没验证过哪些内容。在仓库概览中展示这些信息,也让它更容易和项目的其他文档一起被找到。

GitHub 的文件编辑器展示 ACCESSIBILITY.md 起始模板,包含记录无障碍优先级、贡献者期望以及如何上报障碍的说明。

记录项目能够维护的内容

ACCESSIBILITY.md 文件没有固定格式。小型库、命令行工具、文档网站和大型 Web 应用的用户、风险和维护能力各不相同。先从项目能够持续保持准确的信息写起。

  • 优先级与目标:说明无障碍性对项目为何重要,以及哪些用户体验会受到关注。
  • 对贡献者的期望:描述对变更所要求的无障碍检查、证据或评审流程,包括面向人类贡献者和 coding agent 的操作说明。
  • 报告无障碍障碍:提供直接、无障碍的报告渠道。不要求用户披露残障情况,也不强制提供截图或录屏。
  • 响应流程:说明维护者如何确认、分诊、跟踪和沟通无障碍问题。如果项目使用严重级别,应在分诊时由维护者分配或确认。
  • 支持的环境:列出项目支持或已测试的平台、浏览器、输入方式和辅助技术。
  • 已知限制:从受影响的体验角度描述障碍,附上可用的变通方案,并链接到相关的修复跟踪事项。
  • 责任归属与维护:指明负责保持声明及相关实践最新状态的团队、角色或维护者。
  • 反馈与改进:说明用户和贡献者如何针对声明或项目的无障碍实践提出修改建议。

需要注意的是,项目可以将某个 Web Content Accessibility Guidelines 版本和级别作为目标。但设定目标并不等于已验证的合规,合规声明需要经过评估,并应注明评估范围、日期、方法和评估者。

最有用的 ACCESSIBILITY.md 都包含哪些内容

最有用的无障碍声明,服务的是那些在问题已经发生后才找上门的用户。相比堆砌法律条文和标准术语,通俗易懂的语言、描述清晰的链接和明确的报告渠道更为重要。

有效的报告指引会引导用户提供相关背景,例如受影响的任务、页面、观察到的行为、浏览器、操作系统和辅助技术,同时将截图和录屏设为可选项,避免要求用户证明自己的残障情况。

声明还应该设定维护者能够稳定兑现的预期,包括问题确认、状态更新、可用的变通方案、预计时间线,以及让报告者验证修复效果的机会。

从示例开始,再做调整

Open Source Accessibility Toolkit 提供了一个详细的公开示例。

GitHub 的 Community Standards 工作流则提供了一个更简短的起始模板,其中带有提示文字,项目方可以直接替换成自己的信息。发布这份文件之前,并不需要先制定一份完美的政策。先把准确的信息写上,明确标注尚存的不足,然后随着项目无障碍实践的成熟不断更新这份声明。

添加无障碍声明,能让用户、贡献者和维护者更容易发现项目的无障碍工作。在开源项目中推广这一做法,有助于让无障碍成为社区规划、构建、反馈和改进工作的一部分。

原始来源: GitHub Blog

评论 (0)