How to Stop Guessing When Building Accessible Interfaces

Have you ever wondered why an ordinary button on the web sometimes behaves strangely when you try to click it with a keyboard? Or why a screen reader suddenly starts babbling nonsense when you open a modal? Usually the problem is with ARIA attributes. We're used to adding them "by eye," hoping that aria-label or role="button" will magically fix bad semantics. But accessibility isn't magic — it's strict interaction patterns.

In the w3c/aria-practices repository lies what I call the "frontend developer's bible." It's not just a boring specification, but a living Authoring Practices Guide (APG) that explains exactly how dropdowns, tabs, sliders, and accordions should work so that absolutely anyone can use them.

What This Project Is About

The project is run by a W3C working group. Essentially, these are the people who invent web standards. In the repository, they collect reference examples of interface pattern implementations. If you don't know whether focus should return to the button after closing a modal, or which arrow keys should switch tabs — this is where you look.

Many developers still consider accessibility (a11y) something optional. But when a project grows, the lack of proper keyboard navigation becomes technical debt. This repository helps eliminate that debt at the component design stage.

What This Repository Offers

Inside, you'll find not just dry rules, but working code examples. Here are a few things I constantly refer to in this project.

Ready-Made Design Patterns

For each complex element (for example, Combobox or Tree View), there's a separate section. It describes expected keyboard behavior and required roles. This eliminates the need to reinvent the wheel. You just take the list of requirements and check your component against them.

Reference Code Examples

In the examples folder, there are implementations in pure HTML, CSS, and JavaScript. There are no unnecessary abstractions, React, or Vue — just raw accessibility logic. This is handy when you need to understand how to link id elements via aria-controls or aria-labelledby so the screen reader correctly announces the context.

Testing and Linting

Interestingly, the authors use strict linting. They validate HTML through NU HTML Validator, and JS and CSS through standard ESLint and Stylelint. If you decide to contribute to the project, you'll need to install the JDK for the HTML validator. This shows the level of seriousness: even in code examples, not a single validation error is allowed.

How to Use This in Your Work

I often use this repository as a checklist. For example, I'm writing a custom select. Instead of googling "how to make an accessible select," I go to APG and look at the Select-Only Combobox section.

There I find:

1. Which attributes the parent element needs.
2. How to manage the aria-expanded state.
3. What should happen when pressing Home, End, or PageUp keys.

By the way, the repository has scripts for automated testing of examples. The npm test command runs tests that check element behavior in the browser. This is a great example of how you can automate accessibility testing in your own projects.

The Technical Side

The project runs on Node.js. To work with it locally, you'll need:

• Node.js and npm to run linters and tests.
• JDK (Java Development Kit) for HTML validation.

Interesting point: the project has automatic error fixing configured on commit. If you messed up spaces in CSS or forgot camelCase in JavaScript, the linter will try to fix it itself before letting the code into the repository.

Who Should Check Out aria-practices

First and foremost — component library developers. If you're writing your own design system, ignoring these practices simply isn't an option. The project is also useful for QA engineers: you can find here exactly how an interface should behave when testing accessibility.

I won't say that reading this repository is light evening entertainment. The texts are dry, and there are many requirements. But it's the only way to build interfaces that truly work for everyone, not just for those who use a mouse.

If you're tired of your modals "flying" to the end of the page when closed, or want to finally understand what aria-live is for, just clone this repository and see how the pros from W3C do it. Link to the project: w3c/aria-practices.