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:
| Field | Content |
|---|---|
node | the element’s id, as a number |
role | see below |
name | the accessible name; empty for none |
value | for a slider, spinbutton, textbox or combobox, its value when not empty; a slider or spinbutton without one uses aria-valuenow |
description | the accessible description, when not empty |
states | focused, disabled, checked, expanded, selected, pressed |
bounds | the border box in CSS pixels, as the last update placed it |
children | the 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:
buttonforbutton;linkfor anawith anhref;textboxfor a textinput,checkboxfortype="checkbox",sliderfortype="range"andspinbuttonfortype="number";regionfor asectionthat 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:
aria-label, trimmed;- the text content of the elements
aria-labelledbypoints at, joined by spaces; - for
button,checkboxandoptiononly, the text the element renders; 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::drivein 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.