What this covers

The element tree keeps an accessibility tree and has a vocabulary of commands that act on it by role and name. This page describes both at the framework revision named at the foot of the page, from the code in crates/elements/src/a11y_*.rs. The commands are used by the framework’s tests and its comparison with Chromium.

Screen readers

In the browser build, the demos copy the accessibility tree into hidden DOM elements beside the canvas, one element per node, with its role, name, value, description, states and position. The browser exposes those elements to screen readers and to automation tools. The copy changes only the nodes that changed since the previous frame.

What is not built yet:

  • Activating, focusing or changing a control from a screen reader does not reach the app. Focus set by the app does not move the browser’s focus.
  • Text that is not a control (headings, paragraphs) is not in the tree, so a reader meets controls only.
  • No screen reader has been tested against the hidden elements, and they are not yet compared with the tree Chromium builds for the same page.
  • Native desktop builds give the tree to no operating-system accessibility service.

A node whose role needs a state the tree does not hold, such as a heading without a level, is refused and the frame stops, naming the role, the name and what is missing.

The tree

Document::ax_tree returns the top nodes of the tree, each with its children. It reads the last update, and a document changed since then is refused with not_updated; update the document first.

Each node has:

FieldContent
nodethe element’s id, as a number
rolesee below
namethe accessible name; empty for none
valuefor a slider, spinbutton, textbox or combobox, its value when not empty; a slider or spinbutton without one uses aria-valuenow
descriptionthe accessible description, when not empty
statesfocused, disabled, checked, expanded, selected, pressed
boundsthe border box in CSS pixels, as the last update placed it
childrenthe nodes nearest under it, in document order

An element is a node when it has a role and was drawn. An element with no role is not a node, and its children attach to its nearest ancestor that is one. A node is left out when it has no box (display: none on it or an ancestor) or is visibility: hidden; aria-hidden="true" leaves out the element and everything under it. Text is not a node of its own.

Roles

The role is the first token of the role attribute that is a WAI-ARIA 1.2 role (abstract roles are not in the list). none, presentation and generic give no role. Without a role, the implicit roles are:

  • button for button;
  • link for an a with an href;
  • textbox for a text input, checkbox for type="checkbox", slider for type="range" and spinbutton for type="number";
  • region for a section that has a name.

No other element has an implicit role: a heading needs role="heading".

Names and descriptions

The name is the first of these that is not empty:

  1. aria-label, trimmed;
  2. the text content of the elements aria-labelledby points at, joined by spaces;
  3. for button, checkbox and option only, the text the element renders;
  4. title, with runs of whitespace collapsed to one space.

Rendered text leaves out display: none and aria-hidden elements and text under visibility: hidden; an svg with role="img" contributes its aria-label. There is no label element yet: it is one of the tags the element tree refuses at this revision.

The description is the content of the elements aria-describedby points at; without that, it is the title, when something other than the title already names the node.

The framework compares the roles, names, values, descriptions and states of its fixture pages with the tree Chromium 155 builds for the same HTML (the elements-corpus crate). That comparison covers those fixtures, not every page.

Driving a document from Rust

Document::drive finds elements by role and accessible name, then sends actions through the same input path as a person. It can press, focus, type, send keys and set supported control values. Missing, ambiguous, hidden, disabled or covered targets are refused with a diagnostic.

The API is used by framework tests at this revision. It has no browser, socket or command-line transport built into the app. The framework source contains the command and reply types in its a11y_* modules.

What is not here

  • No operating-system accessibility adapter for native builds; in the browser, the hidden elements described under Screen readers.
  • No transport for commands: a program that wants to drive a document calls Document::drive in Rust.
  • label, textarea, select, HTML list elements and tables are refused by the element tree at this revision, so they have no roles to find.