Who is an accessibility file for?

GitHub added a tab this month, and I have 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 next to the README, the license and the security policy. That's the whole feature. Nobody at GitHub reads the file or grades it.

I added one to the repository behind this site a week later. 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 reader is someone who just hit a barrier

This was the first thing I got stuck on. 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 go looking for a statement before anything else. 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 would like to find out 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, which is the coding agent. It can't ask what we meant, but it can read a page of rules.

I'll be honest that no agent opens this file by itself yet. Mine does because I told it to.

What I didn't have on the list was 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 honest part was hard

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 they're optional. Eric Bailey (opens in a new tab), who worked on this feature at GitHub, says plainly that some organizations are afraid a written list of problems will be used against them.

I looked for evidence either way and didn't find anything I'd trust, so ask a lawyer and not me.

But "we are committed to accessibility" 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 was everything the build already checks, eight things, any of which can stop a release. That half was easy and, if I'm honest, a little smug.

The second half fixed that. 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

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.

1. 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 shouldn't need to be.
2. 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.
3. Your target. Name the standard and the level, and say that a target isn't a claim that you meet it.
4. What's actually enforced. Only checks that can fail a change. A rule nothing enforces goes in number 2.
5. Rules for contributors. Keep it short, then point your agent's instructions at the same file.
6. 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.

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. I'd like them to find out we already knew, and how to tell us the rest.