The w3c/aria repository is where WAI-ARIA and its mapping suites are written

One repository, twelve specifications, twelve issue trackers

This repository maintains specifications and related publications for the Accessible Rich Internet Applications suite of technologies. It is developed by the ARIA Working Group, and the README names the W3C staff contact, Daniel Montalvo, along with a request not to provide commit access to the repository without coordination.

The size of the suite is the first thing to register. Alongside the main ARIA deliverable there are eleven more: Accessible Name and Description Computation, Core Accessibility API Mappings, CSS Accessibility API Mappings, HTML Accessibility API Mappings, Digital Publishing WAI-ARIA Module, Digital Publishing Accessibility API Mappings, Graphics WAI-ARIA Module, Graphics Accessibility API Mappings, SVG Accessibility API Mappings, MathML Accessibility API Mappings, and Portable Document Format Accessibility API Mappings.

The directory listing matches that list one for one, with a folder per specification: accname, core-aam, css-aam, html-aam, dpub-aria, dpub-aam, graphics-aam, graphics-aria, svg-aam, mathml-aam and pdf-aam, alongside common and admin directories and a documentation folder.

The issue tracking arrangement is unusual and worth understanding before you open anything. The README says this repository should be used for issues related to the ARIA spec as well as issues that involve both the ARIA spec in conjunction with other specifications maintained by the working group, and that there are separate issue tracking repos for the separate specifications. Each entry in the list gives a Spec link, an Editor's Draft link and an Issue Repository link.

So filing in the wrong repository is a real and easy mistake. The guidance is to file issues in the repository specific to the specification or deliverable to which the issue applies, and there are more deliverables than this repository holds, as specified in the ARIA Charter.

The repository is not archived, the default branch is main, and the last push was on 2026-10-19. There are no GitHub releases, which is right for a repository whose output is a set of web publications rather than a versioned artifact.

Why there is a separate mapping specification for every technology

The split between ARIA and the AAMs is the architectural idea in this repository, and it explains the shape of the folder list better than any other explanation.

ARIA defines the abstract layer: roles, states, properties, and the rules for how they apply to markup. The Accessibility API Mappings specifications define how those abstract roles and states map onto the actual platform accessibility APIs that assistive technology consumes, per technology. Core AAM covers the core mappings, HTML AAM covers HTML elements, CSS AAM covers CSS, SVG AAM covers SVG, MathML AAM covers MathML, PDF AAM covers PDF, Graphics AAM covers graphics content, and the Digital Publishing pair covers the Digital Publishing WAI-ARIA Module and its own mappings.

This division exists because the mapping is where implementations diverge. A role can be perfectly specified in ARIA and still be exposed differently by different browsers, because each browser maps it into its own platform tree. If you are debugging why a screen reader announces something unexpected, the AAM for that technology is where the answer lives, not the ARIA spec.

It also means the specifications have different maturity and different audiences. The AAMs are for browser implementers and assistive technology vendors, and they are largely reference material. ARIA itself is read by anyone writing markup.

One thing the repository does not pretend to cover is the gap between specification and behaviour. Alongside the specifications there is an ancillary document, a running list of browser accessibility heuristics that are not specified or are partially specified. That list exists precisely because the AAMs do not cover everything browsers actually do, and it is the honest place to look when the specification and the behaviour disagree.

How the documents are built: Respec and typed cross references

Documents in this repository use the Respec preprocessor, and the README explains the custom elements the working group adds on top of it.

The ARIA spec allows easy generation of links to roles, states and properties, with the right link and styling, by enclosing the name in one of three elements:

<rref>
<sref>
<pref>

There is a constraint that catches contributors out: the README notes that this only works in the ARIA spec, and other specs must use cross references as defined below.

The other mechanism is for reaching into a different specification in the suite. Links with special class attributes allow cross references into other specs in the suite, which are transformed by the script to be the appropriate target for the given publication, so editors' drafts point to other editors' drafts, and TR publications point to other TR publications.

That transformation is the reason the spec sources can be published twice without editing. The same source files produce the Editor's Draft served from GitHub Pages, with a w3c.github.io URL for each deliverable, and the formal W3C publication, and the cross references follow the right target in each case. It also means that a broken reference usually appears as a link pointing at a draft rather than at the published document, which is a failure mode you learn to recognise quickly if you work on the sources.

The configuration for this lives in the respecConfig, and the editor drafts are the fastest way to see the current state of the text without building anything.

Who can commit, and how a change gets in

The governance rules are stated plainly, and they matter if you are planning to send a pull request.

Only formally designated editors have commit access to this repository. Editors are designated by the Working Group Chair, and they make a set of commitments that are worth reading as a description of how the group actually operates: execute the consensus of the Working Group regardless of personal opinion, seek Working Group review of substantive technical issues, in good faith separate editorial issues, which may be addressed without explicit review requests, from substantive issues which require review, and follow the W3C Manual of Style and the Chicago Manual of Style, along with the W3C Editors guidelines.

Everyone else contributes through issues and pull requests. Issues can be assigned to people who are members of the ARIA Contributors team, and if you are an ARIA Working Group participant and need access, the README directs you to Daniel Montalvo.

When a pull request is accepted by the Working Group, an editor will integrate the changes, and the commenter receives a notification that the pull request was accepted. So the merge itself is an editor action, and your contribution is judged against the group consensus rather than merged on approval of a reviewer with merge rights.

For the pull request itself the README asks for a complete summary and description, because the Working Group needs to understand the rationale for proposed changes, and it says that description may need to be very detailed in some cases, or quite brief, for example if providing a change to address a spelling issue. That is a useful signal about the mix of work that arrives: substantive specification changes and typo fixes travel through the same queue, and the group distinguishes them.

The ARIA Process Document in documentation/process.md is where the group documents how it tracks issues and pull requests, and that is the document to read before you plan a contribution.

Formatting rules that will fail your first pull request

Two mechanical requirements are stated, and both are the kind of thing that turns a good contribution into a rejected one.

The first is the base branch. Keep it up-to-date with the base branch, for example by selecting rebase under the Update branch options menu on the GitHub web interface. The group would rather integrate a small number of commits than merge a long-running branch.

The second is formatting. Run prettier to preserve spec formatting, and for consistency use the print width setting below:

prettier --print-width 200

The repository carries a .prettierrc at the top level, alongside a .gitattributes file and a .gitignore, so the formatting configuration is committed and shared. This is a specification source repository where the markup is the deliverable, which is why formatting is enforced rather than suggested.

The repository also has a validator-tests directory and an img directory, and a w3c.json file at the root, which is the group configuration that the Respec tooling reads.

Other governance files are present as well: CODE_OF_CONDUCT.md, CONTRIBUTING.md and a LICENSE.md. The licence is recorded in the repository metadata as Other, a custom licence GitHub cannot classify, so LICENSE.md at the root is the text that governs, and it is the file to read if you intend to reuse specification text in your own documentation.

Where the repository is the wrong tool

The limits are obvious once you understand what this repository produces, and they are the kind that make a difference to an engineer's schedule.

It produces specifications, not code. There is no library to install and no runtime component to depend on. If your problem is that a component library is missing an aria attribute, this repository will not give you a patch; it gives you the normative text and a way to file an issue about the spec if the text is wrong.

It is also not a browser bug tracker. A mismatch between the ARIA spec and what a browser does is filed in this repository only if the specification itself is at fault. When the browser is at fault, the issue belongs to the browser project, and the browser accessibility heuristics list exists because that space is not covered by any specification.

The timescales are a second limitation. A substantive change needs Working Group review and an editor to integrate it, and the separation of editorial from substantive issues is deliberate, which means a real spec change is not something you can land in a sprint. If your deadline is next week, this repository is not on the critical path.

There is also no released artifact to pin. The repository has no GitHub releases, and the output is a set of continuously updated web publications: an Editor's Draft per deliverable at a w3c.github.io URL, and formal W3C publications elsewhere. If you need a stable version of the text to write a conformance test against, you have to take a snapshot of the published specification yourself.

One last thing worth saying plainly. The eleven deliverables are not equally complete. PDF AAM is listed in the README with an Editor's Draft and an Issue Repository but no Spec link, which tells you that deliverable is at a different stage from the others, and the heuristics list is the standing reminder that the boundary between specified and unspecified behaviour is wider than the folder names suggest.

Editorial conclusion

Frontend engineers and accessibility specialists should follow the w3c/aria repository rather than copying role names from a blog post, because it is where the ARIA specification and the accessibility API mappings that decide what browsers expose to assistive technology are actually written, and where the browser heuristics list records the behaviour that is still unspecified. It is the wrong tool for shipping a fix today, since the repository produces specifications rather than code, and it is the wrong place to file a defect against a particular browser. Before contributing, read documentation/process.md for how the working group tracks issues, rebase on the base branch, run prettier with the --print-width 200 setting the README asks for, and remember that only formally designated editors have commit access.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. w3c/aria on GitHub