Marcelo Paiva

A man in a wheelchair at the base of a railed ramp leading to an open door.Meant to show: A wheelchair user arriving at a door somebody thought to mark and to ramp. The file is the sign beside it: where to go, said before he had to ask.

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

5 min listen · 4 min read · Read by a synthetic voice (af_heart, made with Kokoro), from the essay’s own words.

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.

  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 they 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. 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.

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#6ab2d4

How this drawing was made

The 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.

An essay

This is an article in a magazine: a drawing at the top, then the essay, read straight down in one column.

From top to bottom

  1. At the top, the site header: my name, which goes home, then links to Writing, Work, Signal, Tools and Resume, then Settings, where you choose the drawings, light or dark, and movement.
  2. The essay’s drawing, with a line under it on what it was meant to show.
  3. The date, the title, and a one-paragraph summary.
  4. A Listen control: play the essay read aloud by a synthetic voice, with buttons to go back or forward 15 seconds, a position slider and a speed choice. It shows how long it takes to listen and to read.
  5. The essay, in sections with their own headings. Some have pictures, videos, lists or diagrams along the way.
  6. About the drawing: how the drawing was made, and a link to more on that.
  7. Links to the newer and older essay. The left and right arrow keys go there too.
  8. At the bottom, the footer: a note on how this site is built, links to Illustrations, Pens, Concepts and Accessibility, this Describe this page button, then GitHub, LinkedIn and email.

What you can do here

Read the essay.