GitHub’s ACCESSIBILITY.md Gives Projects a Place to Explain the Gaps

A person who hits an inaccessible command-line table, unlabeled control or unusable design handoff should not have to guess whether the project knows about the problem—or where to report it. GitHub’s new ACCESSIBILITY.md support gives maintainers a predictable place to answer those questions, but the file only helps if it is specific and kept current.

The repository gets a visible place for accessibility work

GitHub announced the change on November 5. It recognizes ACCESSIBILITY.md in the repository root, .github/ or docs/ and can inherit an organization-wide statement from its .github repository. Public repositories can add or propose a statement through Insights > Community Standards. New repositories also receive an accessibility issue label by default. ^[1]

That makes the information easier to discover beside familiar project guidance such as contribution instructions, codes of conduct and security policies. The statement is documentation, not an audit badge. GitHub’s own examples include specific limitations: GitHub CLI explains a screen-reader difficulty with table output and offers a one-item-per-line command; the Annotation Toolkit explains how to supplement visual Figma annotations with a structured text description and says keyboard-only and screen-reader testing has not been done. ^[1]

Those examples work because they tell a reader what happens in practice. “We care about accessibility” is not an answer to whether a task works with a keyboard or how a user can report a barrier.

A statement is not a conformance claim

The W3C Web Accessibility Initiative recommends that an accessibility statement explain an organization’s commitment, standards or guidelines considered, accessibility measures, known barriers, feedback contact and complaint procedure. The appropriate scope differs between a small library, a command-line tool, a design system and a large web application. ^[2]

A team may name WCAG as a target. That sentence does not establish that a product conforms. GitHub’s announcement makes the same distinction: any conformance claim should identify what was evaluated, when, by what method and by whom. ^[1]

This distinction protects users and maintainers. A truthful statement can say “keyboard navigation was checked in the settings flow in Chrome and Safari; the data table has a known screen-reader limitation” without implying every page and browser passed a full audit. If a team has not tested with a particular assistive technology, it should say that plainly rather than borrowing a standards label as shorthand for evidence.

Write for the person reporting the barrier

A first version can be short. It should answer five practical questions:

1. Which tasks, interfaces or environments has the project considered?
2. What barriers are known, and what workaround exists today?
3. Where can someone report a barrier without having to prove a disability?
4. Who will acknowledge, triage and update the report?
5. What checks should contributors run when they change the affected interface?

The reporting route should accept a plain description. Screenshots, recordings and disability disclosure can be optional context, not prerequisites. GitHub’s guidance encourages maintainers to make the response process realistic: promise the acknowledgement and updates the team can actually deliver, not an ideal service level no volunteer can sustain. ^[1]

For a command-line project, a useful entry might say which screen readers and terminals were tested, identify a table-output issue, provide a plain-text alternative, and link to the issue tracker. For a web library, it might state keyboard behavior, supported browser combinations, and a tracked issue for a known focus problem. These examples are recommendations, not descriptions of any specific repository.

Treat the file as a maintained interface

Place the file where GitHub can recognize it, then link it from the project’s other contribution and support pages. Add an owner to the normal maintenance routine: review the statement when supported platforms change, when a known barrier is fixed, and when a user report exposes an inaccurate claim.

A lightweight review can ask contributors to include accessibility evidence for changed flows. That may mean keyboard navigation, visible focus, zoom or text scaling, and a screen-reader check when the change affects labels or reading order. The required checks depend on the interface; a statement should not claim that every change receives every test unless that is true.

When a barrier is reported, track the issue in the project’s ordinary system and update the statement when the status changes. Close the loop with the reporter. The point is to make the project’s current limits legible, not to turn one Markdown file into a substitute for accessible design.

For related maintainer practices, see our coverage of GitHub’s bulk branch-rule migration and security boundaries for trusted developer tools.