A button, aria-expanded, and hidden: the smallest component that gets it right. Accessibility bugs are easy to miss because they do not show up in screenshots. The only reliable way to find them is to use the interface the way assistive technology users do.
What users actually experience
Most of the problems we found came from custom controls that looked like buttons but were built from generic elements. Switching to native elements fixed focus, keyboard support, and announcements in one step.
<button type="button" aria-expanded="false" aria-controls="shipping-details">
Shipping details
</button>
<div id="shipping-details" hidden>
<p>Orders ship within two working days.</p>
</div>
<script>
const button = document.querySelector('[aria-controls="shipping-details"]');
const panel = document.getElementById('shipping-details');
button.addEventListener('click', () => {
const open = button.getAttribute('aria-expanded') === 'true';
button.setAttribute('aria-expanded', String(!open));
panel.hidden = open;
});
</script>
Fixing the markup
Automated checkers catch roughly a third of the issues. The rest need a keyboard, a screen reader, and a few minutes of patience. We now budget that time into every feature estimate.
- Use native elements before ARIA.
- Every interactive element needs a visible focus style.
- Test with a keyboard before every release.
- Keep text contrast at 4.5:1 or higher.
Testing with real tools
Colour contrast is the one area where tooling is excellent. Every text and background pair in the design system has a measured ratio, and the build fails if a new token pair drops below the WCAG AA threshold.
As always, the examples are simplified to fit on a page. The production version has more error handling and logging, but the shape of the code is the same.
Before you ship this
Do not add role=”button” to a div and call it done. You still need tabindex, Enter and Space handling, and a focus style. A real button gives you all three for free.
Adding manpower to a late software project makes it later.
Fred Brooks, The Mythical Man-Month, 1975
Wrapping up
If you try this on your own project, start with one page or one service rather than the whole codebase. A small experiment gives you real numbers to argue with, and it is easy to roll back if the idea does not fit.
Shared this with my team. The list near the end is going straight into our pull request template.
I would push back a little on the second section. In our monorepo the trade-off went the other way.
A repo is on the way. I will link it in the post once it is cleaned up.
Shared this with my team. The list near the end is going straight into our pull request template.
Clear, practical, no fluff. More of this, please.
A repo is on the way. I will link it in the post once it is cleaned up.
Our accessibility audit flagged exactly this last month. I wish I had read this first.
Clear, practical, no fluff. More of this, please.
Came for the snippet, stayed for the explanation.