I once had what seemed like a straightforward task: clicking a button in a list item should pop up a form asking for additional info, with submit and cancel actions. We decided to think about good UX from the start, and that's when the questions began.
The design called for the form to appear right where the user clicked. Is that a popup? Or a dialog? Do we need a backdrop? Should it close on Esc? What about the Android back button — should it dismiss just the overlay or navigate away from the page entirely? And next sprint we had socket-based notifications coming, which raised a whole new set of questions about transient UI.
This was one of those rare cases where we decided to skip off-the-shelf component libraries and build everything ourselves. The questions kept piling up, so I went straight to the WAI-ARIA spec.
The discovery: accessibility is architecture
As I dug into accessibility, I found something I didn't expect — a rigorously defined system for describing interfaces in terms of their behavior, not their visual appearance.
ARIA APG isn't just a set of guidelines for making interfaces usable by people with disabilities. It's a coherent architectural system that helps you structure components and their interactions correctly. It covers nearly every edge case that, if left unhandled, would leave users in a frustrating situation. And that turns out to be incredibly useful for day-to-day development.
I'd recommend every UI developer read the ARIA Authoring Practices Guide. It's a surprisingly friendly document, and it will change how you think about components.
Accessibility helps everyone
Before diving into the details, it's worth reframing what "accessibility" actually means. It benefits a much wider audience than you might think. Plenty of people experience temporarily limited abilities every day:
- One hand is holding a grocery bag, a child, or is in a cast
- The screen is washed out by sunlight or set to low brightness
- The mouse is broken, the trackpad is awkward
- Eyes are strained after a long workday, or you're just not feeling well
Accessibility isn't about serving a special-needs minority. It's about solid application architecture that makes the interface work well for everyone — including the user who's walking down the street in bright sunlight trying to dismiss a confirmation dialog with one thumb.
The right vocabulary
Here's a problem most frontend teams have: the words we use are wrong. "Modal," "toast," "snackbar," "drawer" — these are informal names that different people interpret differently. The WAI-ARIA spec gives us precise terms that map to behavior, not looks (see Live Region Roles and Window Roles):
dialog — content that doesn't require user action. A product detail card, a photo viewer with comments. Requirements: backdrop, autofocus and focus lock,
aria-describedbyoraria-labelledby,aria-modal.alert — important information that demands the user's attention but doesn't require a response. It disappears on its own. A timer going off, an error notification.
alertdialog — information that requires a user response. Same requirements as dialog. Confirming a file deletion, an error with recovery options.
status / log / marquee — similar to alert but don't demand immediate attention. A new message in a chat, an order processing status update.
Notice the pattern: these roles define what the component does, not what it looks like. A "toast" could be an alert, a status, or even an alertdialog depending on whether it needs user action. When you start design and development from these behavioral roles, composing the final visual components becomes obvious. You stop arguing about naming and start reasoning about function.
From spec to code: headless UI
This is where the architectural insight becomes practical. Studying accessibility helped me understand why libraries like Ariakit and React Spectrum separate state from presentation. When you decouple a component's logic and behavior from its visual rendering, grounding it in WAI-ARIA semantics, you get:
- A clear layering — the spec defines behavior, a headless layer implements that behavior (focus management, keyboard navigation, ARIA attributes), and your visual components just consume it. Each layer has a single responsibility.
- Composition over configuration — you don't have to figure out how to bolt a new feature onto an existing component. Need a dialog that also has a form? Compose the dialog behavior with the form behavior. The visual layer stays thin and flexible.
- Easier conversations with designers — when you share the same vocabulary of roles and behaviors, design reviews become about intent ("is this an alert or an alertdialog?") rather than implementation ("should the toast have an X button?").
When you organize code around accessibility patterns, the architecture almost writes itself. WAI-ARIA gives you a ready-made component taxonomy — all you have to do is follow it.
It's a living standard (and that's okay)
WAI-ARIA doesn't have all the answers. How should a modal react to the browser's back button? Should the Android system back button close an open modal or navigate away from the page? The APG guides don't give a direct answer, and the debate is still ongoing. There are even open questions about Menu and Menubar navigation.
That's fine. A living standard with gaps is still better than no standard at all. It gives you a foundation to build on and a community to reference when you hit an edge case.
Takeaways
Using WAI-ARIA as the foundation for UI component architecture gives you unexpected advantages:
- Faster development — proven patterns for most scenarios, out of the box
- Easier refactoring — clear behavioral layers make changes straightforward
- Better communication — shared terminology between engineers and designers
- Higher quality — you won't forget critical details like focus management or keyboard navigation
- Regulatory readiness — your product won't run into compliance issues down the road
Accessibility isn't an extra feature you can defer to "someday." It's the foundation of good architecture that helps you build quality interfaces faster and more efficiently. WAI-ARIA isn't dogma, but it's the baseline every web developer needs.
Practical resources
- Component patterns with clear explanations — share these with your designers
- Example index with reference implementations
- Practices guide with detailed behavior descriptions
- WAI-ARIA specification for a deep dive
- Open issues to see what's still being figured out
Top comments (0)