
Who is an accessibility file for?
GitHub now gives accessibility its own tab on a project, next to the license. I added the file to this site, and the part I did not want to write turned out to be the useful one.
Listen to this essay
GitHub added a tab this month, and I've been thinking about it more than a tab probably deserves.
If your project has a file called ACCESSIBILITY.md, its front page now shows
an Accessibility tab, right next to the README, the license and the security
policy. That's the whole feature. Nobody at GitHub reads the file or grades it.
A week later I added one to the repository behind this site. I should say up front that the repository is private, so for now that tab has an audience of one, and it's me. I wrote it properly anyway, and I'm glad I did.
The first thing I got stuck on was simple: who actually clicks that tab?
The obvious answer is someone who just hit a barrier. GitHub's guide for maintainers (opens in a new tab) says they often look for a statement before anything else. And they aren't there for our values. They want to know if we know, and where to tell us.
Then there's the person about to contribute, who'd like to know what will get their change bounced before they open it. Fair enough.
And there's a reader I wouldn't have listed two years ago: the coding agent. It can't ask what we meant, but it can read a page of rules. To be honest, no agent opens this file by itself yet. Mine does because I told it to.
So who wasn't on my list? A legal team, or a procurement form. I think that's who most statements get written for, and it's why so many of them are one warm paragraph that nobody can do anything with.
The file can live in .github, at the top of the repository or in docs
(GitHub checks in that
order (opens in a new tab)).
What goes in it is up to us, and that's where it gets uncomfortable.
The W3C's guidance (opens in a new tab) says a statement needs a commitment, a standard and a way to reach us. Known problems are optional.
I understand why. Eric Bailey (opens in a new tab), who worked on this feature at GitHub, says it plainly: some organizations are afraid a written list of problems will be used against them. I looked for evidence either way and found nothing I'd trust, so ask a lawyer, not me.
But think about what you actually learn from "we are committed to accessibility". It has never told me anything about a product. The list of what doesn't work is the only part that proves somebody looked.
So I wrote mine in two halves. The first half was everything the build already checks: eight things, any of which can stop a release. That half was easy, and if I'm honest, it was also a little smug.
The second half fixed that. Here's some of what I had to write down:
- Nobody outside the project has ever audited this site.
- The drawings at the top of each post are generated, and they keep leaving out the one detail that says who the person is. I asked for a keyguard and got a plain keyboard. I asked for a white cane, twice, and got no cane.
- I hold my writing to reading-level rules that nothing checks except me, on a good day.
I knew all of that already. It just wasn't written anywhere a visitor could find it, and to a visitor, that's the same as hiding it.
How to report a barrier goes first
So if you're writing yours this week, here's the order I'd use. It's the order a person in trouble needs things in.
- How to report a barrier. A real address, and what happens after. Tell people they don't have to quote a guideline at you. Most of them aren't specialists, and they shouldn't need to be.
- What you already know is broken. If a list feels too exposed, link to your open issues. That's what Bailey does in his own project.
- Your target. Name the standard and the level. Say that a target isn't a claim that you meet it.
- What's actually enforced. Only checks that can fail a change. A rule nothing enforces goes in number 2.
- Rules for contributors. Keep it short. Then point your agent's instructions at the same file.
- A date, so people can tell when it was last true.
Will any of this change anything? I don't know. A file doesn't make a product accessible, and I can't show you that a tab changes what maintainers do.
But here's the small thing I am sure of. For years, "can I use this?" had nowhere to go. Now it has a spot on the front page, next to the license.
Someone is going to open that tab because something we built didn't work for them. When they do, I'd like them to find out we already knew, and how to tell us the rest.

About the drawing
The drawing for this piece was generated, not chosen. Hashing the piece’s name fixes one point on the color wheel; the other two follow from it. The same name always gives the same three colors.
#be6a9a#76d04d#6ab2d4The line under the drawing marked “Meant to show” is written by a person, not the model. A generated drawing keeps what is large and loses what is small, so the detail that decides who someone is can go missing, and a picture only reaches people who can see it. Where the drawing and that line disagree, the line is the intent.
Or press ←the left arrow and →the right arrow.