w3c/aria-practices: WAI-ARIA patterns and examples

What w3c/aria-practices solves

w3c/aria-practices maintains the WAI-ARIA Authoring Practices Guide, abbreviated APG. The guide addresses a recurring gap in interface development: ARIA attributes describe roles and states, but they do not by themselves prescribe the keyboard commands, focus transitions, or state changes expected from every interactive component. APG connects those ARIA concepts to documented patterns and corresponding HTML, CSS, and JavaScript examples.

The intended users include interface authors, accessibility specialists, component designers, and developers implementing widgets such as dialogs, menus, sliders, or tabs. It is also the working repository for the Authoring Practices Task Force of the ARIA Working Group. The README names Daniel Montalvo as the staff contact and asks that commit access not be provided without coordination.

This is a guidance and examples repository, not a conventional application or distributable component library. package.json marks the package as private, and the repository layout emphasizes content templates, common resources, build scripts, and tests. A team can use APG to inform a component, but it still needs to confirm that the pattern's semantics and behavior fit the product's DOM structure, styling, and application state.

How APG patterns are organized and checked

The repository separates authored guidance from supporting infrastructure. Directories such as `content/`, `content-templates/`, `common/`, `scripts/`, and `test/` indicate a documentation project with reusable page resources and validation machinery. The README's linting example refers to `examples/slider/js/text-slider.js`, showing that pattern behavior is implemented in concrete source files rather than confined to prose.

Validation covers all three principal web languages. HTML is processed through HTMLHint and the NU HTML Validator. CSS is checked with stylelint under `stylelint-config-standard`, followed by a Prettier formatting check. JavaScript is processed by ESLint under the repository configuration and checked by Prettier. Spelling and link integrity also have dedicated commands.

The `test` script combines linting with an AVA regression suite. That makes examples part of the repository's test boundary, but passing automation is not the same as a complete accessibility assessment. ARIA requirements can still depend on correct role assignment, accessible names, state changes, focus movement, and the way a host application integrates a pattern.

One explicit exception appears in `.vnurc`. The README says it allows errors or warnings to pass when they concern a future ARIA feature that the validator has not implemented. That is a practical accommodation for standards work. It does not turn the validator exception into proof that the affected markup is correct; the repository simply permits the message during that development condition.

Installing w3c/aria-practices and running its checks

The README directs contributors to install Node.js, which includes npm, and to install the repository dependencies from the directory containing `aria-practices`. The HTML validator has an additional Java runtime requirement, so a JDK must also be installed.

This command installs the JavaScript dependencies declared by the repository. Run it from the repository root.

npm install

The repository defines `npm run fix` to apply automatic corrections through ESLint, stylelint, and Prettier. It is useful after an editable validation failure, but the README also instructs contributors to test again and fix remaining problems manually.

npm run fix

The CSS validation command runs stylelint and then checks CSS formatting with Prettier. A successful run should finish without reporting either a lint violation or a formatting difference.

npm run lint:css

The documented JavaScript command is `lint:js`, which delegates to the same validation path represented internally by `lint:es`. The repository's combined lint command also checks HTML and spelling, so it is the broader pre-submission option.

npm test

The README warns that `npm test` can take several minutes and open several browser windows that gain focus. The full command includes linting and regression tests. Contributors running it on a shared workstation should account for that window-switching behavior, especially in an automated environment without a graphical session.

Contribution workflow and documentation maintenance

The contribution process begins with coordination rather than an unsolicited code patch. The README instructs contributors to comment on an existing issue or raise a new one, summarize the proposed resolution, and wait for an editor to confirm that no conflicting plan exists. Contributors are then directed to the wiki page about submitting pull requests.

Planning is connected to publication. Each GitHub milestone corresponds to a working draft or release published on w3.org, while GitHub projects group work by design-pattern type or guidance area. The scope and roadmap are kept in the project wiki. A proposed example change may therefore affect editorial wording, standards guidance, validation, and publication sequencing rather than fixing only a local component defect.

Editorial quality is checked as part of maintenance. The repository links to the APG Editorial Style Guidelines for its prose and to the ARIA specification README for additional guidance. package.json also provides spelling, link-checking, coverage-report, reference-table, and regression-report scripts. Their command names are documented, but the README does not describe the output format or operational behavior of every reporting script.

Several repository policies affect maintainers rather than readers. Pull requests with linting errors are not merged until those errors are resolved. On commit, the configured tools inspect staged files and may automatically fix certain CSS or JavaScript issues before committing them. Contributors using an editor with EditorConfig integration can receive the same formatting expectations directly in their working environment.

APG limitations and unsuitable component-library use

APG does not turn ARIA markup into an accessible component by itself. The README provides guidance, examples, linters, and regression tests, but it does not document a framework-specific integration API, a public import path for each widget, or a complete browser support matrix. A production team must still map the documented pattern onto its own components and verify the resulting user experience.

The repository is also not an application dependency in the usual npm sense. The package is private and has version `0.0.0`, while the documented releases are APG drafts and note releases. Product teams that expect semver guarantees, framework wrappers, changelogs for installed components, or automated migration paths should not assume those facilities exist.

The static checks have defined boundaries. The HTML command validates files under `content/`, and `.vnurc` can permit messages related to unimplemented future ARIA features. The JavaScript checks apply repository-wide file matching rather than proving that every pattern has been exercised through assistive technology. The regression command is useful for repository maintenance, but the README does not claim that it replaces manual keyboard testing or user evaluation.

A second limitation is coordination overhead. New contributions require issue discussion and editor confirmation, and commit access requires coordination. That process fits a W3C-authored guide, but it is a poor match for a product team seeking immediate, independent component releases.

APG guidance versus an internal component library

The clearest alternative is an internal component library or application design system that owns its rendered widgets, keyboard controller, focus policy, package API, and integration tests. This approach can expose framework bindings and versioned releases while keeping behavior close to the product. The team must then define and maintain the interaction contract itself, including accessible names, roles, states, and focus behavior.

APG follows a different approach. It documents expected behavior as WAI-ARIA authoring patterns and maintains examples beside the guide. Milestones connect repository work to W3C drafts and releases, while topics group related pattern work. It is therefore the stronger reference when the decision concerns ARIA semantics, documented interaction behavior, or alignment with W3C practices. An internal library is the stronger choice when the immediate requirement is deployable UI code with a supported package lifecycle.

Both approaches can be used together. A team can consult the relevant APG pattern during design review, implement it inside its own design system, and add regression tests around the actual component API. That arrangement preserves the guidance without pretending that the APG repository supplies a production widget package.

License, release history, and upgrade checks

The repository metadata needs careful review. The repository classification describes its license as Other and points to `LICENSE.md`, while package.json declares `MIT`. Anyone copying examples, prose, or other files should inspect `LICENSE.md` and confirm the stated terms for the intended use. This article does not interpret the license or provide legal advice.

The repository is not archived, and its last push was on 2026-10-14. The listed release history includes APG 1.2 Working Draft #3 from 2020-10-25, APG 1.1 Note Release 4 from 2019-11-10, and APG 1.2 Note Release 1 from 2021-11-16. The chronology does not provide a current package-version cadence for teams copying its examples.

Upgrades therefore require review. package-lock.json can track JavaScript tooling changes, but lockfile updates do not by themselves update the W3C guidance a product has copied into application code. The first adoption check should be `LICENSE.md`, followed by a comparison of the referenced pattern, its keyboard contract, and the product's current behavior.

Editorial conclusion

Adopt w3c/aria-practices as an implementation and review reference when work must follow W3C ARIA authoring guidance. Do not treat it as a drop-in component package or as proof that an implementation is accessible. Before reuse, inspect LICENSE.md, check the relevant pattern's keyboard and focus requirements, then run the documented lint and regression commands in the product's supported environment.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. w3c/aria-practices on GitHub