The Accessibility Bugs Our Test Suite Never Caught

There is no shortage of articles about React. Most of them cover the happy path. This one is about what happened after the happy path ended.

When we finally measured, the numbers were worse than anyone guessed. Around 37% of the time spent on a typical change went into working around accessibility rather than building anything.

What was going wrong

We had good intentions. We even had a document describing how accessibility should work. The trouble was that the document and the code had quietly gone their separate ways.

The setup was ordinary: React at the edges, Vite doing most of the heavy lifting, and a handful of scripts nobody wanted to own. It worked well until usage roughly doubled over a single quarter.

The fix

The fix turned out to be smaller than expected. Instead of adding another layer, we removed one and leaned on what React already gives you out of the box.

The core of it looks like this:

.card-list {
  container-type: inline-size;
}

@container (min-width: 36rem) {
  .card {
    display: grid;
    grid-template-columns: 12rem 1fr;
    gap: 1.5rem;
  }
}

This alone let us delete a surprising amount of code elsewhere in the project.

A few things that helped along the way:

• Keep the old path around until the new one has survived a real incident.
• Agree on what "done" means before the first pull request.
• Measure before and after, even if it's just a rough number in a spreadsheet.

Caveats

The biggest cost was social, not technical. Changing how people think about accessibility takes much longer than changing the code.

We still haven't solved bundle size. That's a post for another day, and honestly, I'm not sure we'll get it right the first time either.

What's next

That's it for now. Next time I'll dig into server-side rendering, which turned out to be closely related.