AOM wants JavaScript to be able to edit the accessibility tree

What the effort actually proposes

The Accessibility Object Model, AOM, is an effort to create a JavaScript API that allows developers to modify, and eventually explore, the accessibility tree for an HTML page.

That sentence is the whole proposal, and it is worth unpacking the two halves, because the second one is aspirational. Modification comes first: a way for script to change what the accessibility tree contains, which is a different capability from the one developers have today. The exploration part, the idea of letting a script read the tree as well as write to it, is described as eventual.

The editors list gives a sense of who is pushing it. Alice Boxhall and Dominic Mazzoni from Google, James Craig from Apple, and Alexander Surkov from Mozilla. Three engine vendors with a shared interest, which is the usual shape of a web platform proposal that hopes to become a standard rather than a library.

The project lives in a Web Incubator Community Group, the WICG, which is the place where proposals incubate before they go anywhere else. The homepage is wicg.github.io/aom, and the default branch of the repository is gh-pages, which is a detail that tells you the repository is the published site as much as it is a source of documents.

For an engineer, the audience question has two answers. If you build browser features or accessibility tooling, this is a specification to implement against. If you build web applications and want to know whether you can adjust what a screen reader announces, this is where the answer is being worked out.

A repository of documents, not code

The top level listing of the repository shows what kind of project this is. There is a LICENSE.md and a README.md, and then the contents are documents: explainer.md, the notification API document, accessibility-tree.md, aria-reflection-explainer.md, element_reference_properties.md, exportid-explainer.md and reference-target-explainer.md. There are directories for the demos, for images, for meeting notes, for a csun_paper directory and for the spec itself, and a w3c.json file at the root.

There is no src directory, no build system for a library, no package manifest, and no test suite. That is not a criticism, it is the nature of a standards effort. The artefacts are proposals, and their quality is judged by how clearly they argue a case rather than by whether they compile.

The w3c.json file is worth a mention because it is the machine readable part. A repository that carries a configuration file describing itself to the standards tooling is a repository whose contents are meant to be fed into a process rather than only read.

The specification directory is the other structural signal. A proposal that has its own spec directory has moved past the explainer stage, which is where most ideas die.

For a reader, the practical consequence is that there is nothing to install and nothing to run except the demos. Evaluating AOM means reading documents, not trying a library.

How to read the effort, in the order the README gives

The README is short and it is effectively a reading guide, which is the most useful thing it does for someone arriving cold.

Under Details for the Accessibility Object Model, it says to read the explainer, then the spec, with a note attached to the spec link that it is not up to date. Then it points at caniuse.md for the question of whether AOM is in Chrome, Safari or Firefox today, and finally at the demos, an interactive slide deck and a tic-tac-toe demo, both marked as for Chrome.

So the intended order is: explainer for the argument, spec for the shape of the API, caniuse for the current status, and the demos for the feel of it. The note about the spec being out of date is placed right at the point of reading rather than buried, which is a courtesy that saves an hour of confusion.

The demos are the part that requires the browser you probably have. The slide deck is interactive and the tic-tac-toe demo is a small application, and both are marked as for Chrome, which tells you that they exercise an implementation that exists in one engine at the time of writing.

For a first pass, the explainer and the demos are the two that pay off. The spec is where you go when you need the precise shape of an interface, and the README tells you it may not be the latest version of it.

The notification initiative, and a README that redirects

The second half of the README covers the Accessibility, or ARIA, Notification API, and it opens with a warning. The note says notification-api.md is outdated and points to the up-to-date explainer of the initiative, hosted in the MSEdgeExplainers repository under Accessibility/AriaNotify.

That is a small but instructive detail. A proposal that has moved its canonical document out of the repository it was incubated in, while the repository keeps the old copy, is a proposal that found traction. The editors listed for it are all from Microsoft: Sara Tang, Doug Geoffray, Alison Maher, Travis Leithead and Daniel Libby.

The aim is narrow. The effort aims to create a JavaScript API to allow developers to initiate notifications that confirm user actions, not necessarily tied to direct UI changes.

The distinction in that last clause is the interesting part, and it is a design question rather than an implementation detail. The notification is a confirmation that something happened, and it is explicitly not required to correspond to a change the user can see. A background job that finishes, a save that resolves, a queued action that is now cancelled: none of those are visible UI changes, and each of them is exactly the kind of event a screen reader user would otherwise have no way of knowing about.

The two initiatives in this repository, the accessibility tree and the notification channel, are related in that both are about closing the gap between what an application knows and what assistive technology can convey. But they are separate proposals, with separate editors and separate documents, and the README treats them as two sections rather than one.

The neighbouring explainers and the difference in approach

Several of the other files in the repository are separate proposals that sit next to AOM rather than inside it, and the difference in approach between them is the interesting part of the layout.

aria-reflection-explainer.md is the one to compare with AOM. AOM, as the README states it, allows developers to modify, and eventually explore, the accessibility tree. ARIA reflection is a separate explainer about reading the ARIA state of elements. The distinction is a direction of travel: one proposal is about a script changing what the platform exposes, the other about a script inspecting what is already exposed. AOM is the more invasive of the two, and the fact that both live in the same repository suggests the community is working on them together.

The other explainers are more specific. exportid-explainer.md, reference-target-explainer.md and element_reference_properties.md, along with accessibility-tree.md, sit in the same directory as the main explainer, which suggests related proposals in the accessibility scripting space.

Because the README does not describe the contents of these documents, the honest position is that their scope has to be read from the documents themselves. What the repository layout does show is the shape of the work: one headline proposal about writing to the tree, one about reading from it, and a set of narrower proposals about specific attributes.

That shape is itself informative. AOM is the ambitious one, and the existence of the narrower proposals suggests the community expects the smaller pieces to be shippable on their own.

Maintenance, licence and who the repository is for

The repository is not archived, and the last push was on 2026-08-19. There are no GitHub releases, which is expected for a document set, and the licence is recorded as a custom one that GitHub cannot classify, with a LICENSE.md file in the repository as the authoritative text. Because this is a repository of specification text rather than source code, that file is the document to read before you quote or reuse anything from it.

The activity signal is a meeting-notes.md file and the presence of a csun_paper directory, which together suggest the work is being carried forward in the WICG's own process and in the academic venue as well as in the browser implementations. The caniuse.md file is maintained in the same repository, which is unusual and useful, because it means the status of each piece is maintained by the people proposing it.

The audience is narrow and the document is honest about it. Browser engineers implementing the API need the spec. Accessibility tool authors need the exploration half, which is the eventual one. Web developers who want to change what a screen reader says about their page are the ones who will care most about the notification API, and they will find that the proposal is the deliverable, not a library.

If you are in that last group, the practical value of this repository today is that it tells you which direction the platform is heading, and gives you the vocabulary to ask for the thing you need by the time it ships.

Editorial conclusion

AOM suits browser engineers, accessibility tool authors and web developers who need to change what assistive technology sees about a page, and it is the right document set to read if you are implementing a side of that API. It is the wrong thing to build against today, because the README itself flags the spec as not up to date and moves one of its two initiatives to another repository. Verify first which browser supports which part by reading caniuse.md, since the demos in the repository are marked as for Chrome, and treat the explainers rather than the spec as the current source, because that is the distinction the README draws for you.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. WICG/aom on GitHub