Accessibility Lab · LAB-08accessibility tree / role

The invisible DOM

There are two trees. You wrote one of them. Assistive technology reads the other.

Level: ENGINEER
Read time: 10 min
Experiment: Available
Type: INTERACTIVE

The question

A div with a click handler looks and behaves like a button on screen. What exactly is missing, and where does that difference live?

Hypothesis

The browser derives an accessibility tree from the DOM. Native elements contribute a role, a name, states and built-in keyboard behaviour; a styled div contributes a generic node with none of those.

Method

Laboratory available

The instrument for this investigation runs in the laboratory, where the controls, the live model and the observation log share one workstation.

Enter the laboratory

Edit the markup on the left. The accessibility tree on the right is recomputed with the role, accessible name and state that assistive technology would actually receive.

What we observed

Capability	<button>	<div onclick>
Role announced	button	generic
Reachable by Tab	yes	no (needs tabindex="0")
Enter and Space activate it	yes	no (needs a keydown handler)
Disabled state honoured	yes	no
Participates in a form	yes	no
Exposed to voice control by name	yes	only with an explicit name
Shows in the browser's find-and-click tooling	yes	unreliable

What a native control gives you for free

Why it happens

example.htmlhtml

1<!-- Correct: role, focus, keyboard, disabled all included -->2<button type="button" onclick="save()">Save</button>34<!-- Recoverable, but you now own the keyboard contract -->5<div role="button" tabindex="0"6 onclick="save()"7 onkeydown="if (event.key === 'Enter' || event.key === ' ') save()">Save</div>89<!-- Invisible to keyboard and assistive technology -->10<div class="btn" onclick="save()">Save</div>

The same control, three ways

Visual hiding has three distinct meanings and people routinely pick the wrong one. display: none and visibility: hidden remove the node from the accessibility tree. opacity: 0 and clip-path do not, the content stays announced and focusable, which is how invisible focus traps happen. A visually-hidden utility class is the correct tool for text intended only for screen readers.

example.csscss

1.visually-hidden {2 position: absolute;3 width: 1px; height: 1px;4 margin: -1px; padding: 0;5 overflow: hidden;6 clip-path: inset(50%);7 white-space: nowrap;8 border: 0;9}

The standard visually-hidden utility

Further research

The accessibility tree is not a copy of the DOM. Presentational nodes are pruned, anonymous boxes are ignored, and generated content may or may not appear. Browsers expose it through platform APIs. UIA on Windows, AX on macOS, AT-SPI on Linux, so two browsers can legitimately expose the same markup slightly differently. Chrome DevTools, Firefox's Accessibility panel and Safari's Audit tab all let you read the computed tree directly.

References

01W3C, accnameAccessible name and description computation
02W3CARIA Authoring Practices Guide
03MDNThe accessibility tree