Accessibility documentation scattered across issue trackers, contribution guidelines, audit reports, and team conversations becomes difficult to locate and maintain as projects evolve. GitHub is addressing this by treating ACCESSIBILITY.md files as a standard community health document, similar to codes of conduct and security policies, making accessibility information visible on repository overview pages.
Making accessibility statements discoverable
GitHub recognizes ACCESSIBILITY.md files placed in a repository's root directory, .github/ directory, or docs/ directory. Organizations can also maintain a shared statement in their .github/ repository that child repositories inherit. For public repositories, maintainers can generate or propose a statement through Insights > Community Standards using a provided template.
This addition joins existing community health files that help projects communicate their practices. Contribution guidelines outline how to propose changes, codes of conduct set participation expectations, and security policies explain vulnerability reporting. An accessibility statement provides dedicated space for accessibility goals, contributor expectations, supported environments, known limitations, and barrier reporting processes.
New repositories now include an accessibility issue label by default. The statement guides users on reporting barriers and what to expect, while the label helps maintainers organize and track accessibility work.
Accessibility statements make project practices visible
GitHub CLI's accessibility statement demonstrates practical value by documenting settings, known barriers, and workarounds. It explains that table output can be difficult to follow with a screen reader and provides a command that prints pull request numbers and titles one per line instead. The statement also sets expectations for contributors changing prompts or output to demonstrate results with relevant accessibility settings enabled, giving both users a specific workaround and contributors clear guidance.
The GitHub Annotation Toolkit's accessibility statement identifies a limitation of its Figma library: annotations use canvas position, connecting lines, and matching numbers to convey relationships visually, but accessing individual canvas objects does not necessarily communicate what those relationships are. The statement provides a concrete alternative for collaborators: supply a structured text description identifying each annotated element, its intended semantics and behavior, and any relevant ordering. For developers preparing or receiving a design handoff, this clarifies what information must accompany the visual annotations.
The file also explains how to report accessibility barriers and explicitly states that the library has not undergone keyboard-only or screen-reader testing. Readers gain both practical guidance and clear understanding of what the project has verified. Displaying this information in the repository overview makes it easier to locate alongside other project documentation.
Document what the project can maintain
No single fixed format applies to all ACCESSIBILITY.md files. A small library, command-line tool, documentation site, and large web application each serve different users, face different risks, and have different maintenance capacity. Projects should begin with accurate information they can keep current.
- Priorities and goals: Explain why accessibility matters to the project and which user experiences receive attention.
- Contributor expectations: Describe the accessibility checks, evidence, or review practices expected for changes, including instructions for human contributors and coding agents.
- Reporting accessibility barriers: Provide a direct, accessible reporting path. Do not require disability disclosure, screenshots, or recordings.
- Response process: Explain how maintainers acknowledge, triage, track, and communicate about accessibility issues. If the project uses severity levels, let maintainers assign or confirm them during triage.
- Supported environments: List the platforms, browsers, input methods, and assistive technologies the project supports or has tested.
- Known limitations: Describe barriers in terms of the affected experience, include available workarounds, and link to tracked remediation work.
- Ownership and maintenance: Name the team, role, or maintainer responsible for keeping the statement and related practices current.
- Feedback and improvements: Explain how users and contributors can suggest changes to the statement or the project's accessibility practices.
Projects can identify a Web Content Accessibility Guidelines version and level as a target. A target does not establish verified conformance. A conformance claim requires an evaluation and should identify the evaluated scope, date, method, and evaluator.
What the most useful ACCESSIBILITY.md files contain
The most useful accessibility statements serve people who encounter problems. Plain language, descriptive links, and a clear reporting route matter more than legal or standards-heavy language.
Effective reporting guidance invites relevant context, such as the affected task, page, observed behavior, browser, operating system, and assistive technology. It makes screenshots and recordings optional and avoids asking someone to prove a disability.
The statement should also set expectations that maintainers can consistently meet. That can include acknowledgement, status updates, available workarounds, expected timelines, and an opportunity for the reporter to verify a fix.
Start with an example and adapt it
The Open Source Accessibility Toolkit provides a detailed public example. GitHub's Community Standards workflow provides a shorter starter with prompts that projects can replace with their own information. The goal is not to produce a perfect policy before publishing the file. Start with accurate information, name the gaps, and update the statement as the project's accessibility practices mature.
Adding an accessibility statement makes accessibility work more discoverable to users, contributors, and maintainers. Normalizing that practice across open source projects helps make accessibility part of how communities plan, build, report, and improve their work.