New series: what assistive tech really hears on your checkout page. Start with part one →
Shipwright
Home
Accessibility Sep 17, 2026 2 min read 1.5k views

Building an Accessible Disclosure Widget from Scratch

Mara Okafor

Mara Okafor

@maraokafor

Share
Cover illustration for the article Building an Accessible Disclosure Widget from Scratch

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.

disclosure.html
<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.

Mara Okafor

Mara Okafor

Author

Staff frontend engineer focused on CSS architecture and accessibility. Mara has audited more design systems than she can count and still gets excited about a good focus ring.

Related Posts

Comments 9

Alex Moreno

Shared this with my team. The list near the end is going straight into our pull request template.

Elias Lindqvist Member

I would push back a little on the second section. In our monorepo the trade-off went the other way.

Amara Nwosu

A repo is on the way. I will link it in the post once it is cleaned up.

Priya Raman Member

Shared this with my team. The list near the end is going straight into our pull request template.

Fatima Zahra

Clear, practical, no fluff. More of this, please.

Mara Okafor Author

A repo is on the way. I will link it in the post once it is cleaned up.

Amara Nwosu

Our accessibility audit flagged exactly this last month. I wish I had read this first.

Tomás Herrera Member

Clear, practical, no fluff. More of this, please.

Amara Nwosu

Came for the snippet, stayed for the explanation.

Leave a comment

Your email will not be published. Sign in for a faster experience.

Supports **bold**, *italic*, and `code`.