Qu'est-ce que l'arbre d'accessibilité ?
Comprenez comment les navigateurs créent l’arbre d’accessibilité, calculent les rôles et noms, l’inspectent dans DevTools et testent les contrôles avec Playwright.
L’arbre d’accessibilité est une seconde représentation d’une page web que le navigateur construit à partir du DOM à destination des technologies d’assistance. Il conserve le rôle, le nom accessible, les états et la valeur de chaque élément porteur de sens, tout en écartant la plupart des conteneurs purement destinés à la mise en page.
Vous y êtes confronté lorsqu’un audit signale « button has no accessible name », lorsqu’un linter se plaint d’un div cliquable, ou lorsque le getByRole de Playwright ne trouve pas un élément pourtant visible à l’écran. Ces trois outils rendent compte de la même structure. Cet article explique comment le navigateur construit cet arbre, ce que contient chaque nœud, comment l’inspecter et comment écrire des tests qui s’appuient sur lui.
Points clés
- Les navigateurs construisent l’arbre d’accessibilité à partir du DOM, de la sémantique native du HTML et des attributs ARIA. Les éléments
divetspanqui ne servent qu’à la mise en forme n’obtiennent généralement pas de nœud propre. - Le contenu masqué avec
display: none,visibility: hidden, l’attributhiddenouaria-hidden="true"est exclu de l’arbre d’accessibilité, même s’il reste présent dans le DOM. - De manière simplifiée, le nom accessible d’un élément provient d’abord de
aria-labelledby, puis dearia-label, puis de l’étiquetage natif (<label>,alt), puis du contenu textuel, et enfin detitle. - Un
<div>doté d’un gestionnaire de clic n’a pas de rôle button dans l’arbre : les lecteurs d’écran ne l’annoncent donc pas comme un contrôle et les utilisateurs du clavier ne peuvent pas l’atteindre. - Le localisateur
getByRoleet les ARIA snapshots de Playwright s’appuient sur les rôles et les noms accessibles : les tests qui les utilisent échouent donc sur les mêmes bugs que ceux qui bloquent les utilisateurs de technologies d’assistance.
Comment le navigateur construit l’arbre d’accessibilité
Les navigateurs construisent l’arbre d’accessibilité à partir de trois sources : le DOM, la sémantique intégrée des éléments HTML et les éventuels attributs ARIA. HTML-AAM définit la correspondance entre chaque élément HTML et un rôle accessible, tandis que Core-AAM 1.2 définit la correspondance entre les rôles, états et propriétés ARIA et les API d’accessibilité des plateformes.
La correspondance entre le DOM et l’arbre d’accessibilité n’est pas bijective. Un <div> ou un <span> qui n’existe que pour le flexbox ou la mise en forme est généralement aplati, c’est-à-dire supprimé de l’arbre. À l’inverse, HTML-AAM précise qu’un <video> doté de l’attribut controls expose ses contrôles intégrés, comme la lecture et le volume, sous forme de nœuds enfants associés à des rôles tels que button et slider. Aucun de ces contrôles n’apparaît dans le DOM de la page.
Le contenu masqué est lui aussi supprimé. WAI-ARIA 1.2 exclut de l’arbre les éléments qui ne sont pas affichés (display: none, visibility: hidden, attribut HTML hidden) ou qui portent aria-hidden="true". Une classe CSS de type « visually hidden » ou sr-only relève d’un cas différent : elle déplace le contenu hors de l’écran, si bien que ce contenu reste dans l’arbre.
Que contient un nœud accessible ?
Chaque nœud de l’arbre d’accessibilité expose jusqu’à quatre informations : un rôle (ce qu’il est), un nom (comment il s’appelle), des états (sa condition actuelle) et, pour certains contrôles, une valeur. Voici une case à cocher étiquetée :
<label><input type="checkbox" checked> Email me product updates</label>
Au format ARIA snapshot de Playwright, le nœud obtenu se présente ainsi (à titre d’illustration) :
- checkbox "Email me product updates" [checked]
Le rôle est checkbox, le <label> fournit le nom et [checked] correspond à l’état. Une case à cocher transmet son information par son état coché. La valeur concerne des contrôles comme les champs de texte et les curseurs, et le format de snapshot la place après un deux-points :
- textbox "Email": ada@example.com
Pour savoir comment les rôles sont attribués et quand ajouter vous-même des rôles ARIA, consultez Understanding Accessibility Roles in HTML.
Comment le nom accessible est-il calculé ?
De manière simplifiée, le navigateur tire le nom accessible d’un élément de la première source qui en fournit un :
aria-labelledby, qui pointe vers le texte d’autres élémentsaria-label- L’étiquetage natif : un élément
<label>ou le textealtd’une image - Le contenu textuel de l’élément lui-même, pour les rôles qui autorisent un nom issu du contenu (boutons, liens)
- L’attribut
title, en dernier recours
ARIA l’emporte sur l’étiquetage natif. Si un bouton affiche le texte visible « Send » et porte aria-label="Submit form", un lecteur d’écran annonce « Submit form », et un utilisateur de commande vocale qui dit « click Send » risque de n’obtenir aucune correspondance. L’algorithme complet, y compris la gestion des contrôles imbriqués et de la récursivité, est décrit dans Accessible Name and Description Computation 1.2.
Comment les lecteurs d’écran utilisent-ils l’arbre d’accessibilité ?
Les lecteurs d’écran ne lisent pas le DOM. Ils lisent l’arbre d’accessibilité par l’intermédiaire de l’API d’accessibilité du système d’exploitation, que le navigateur implémente. Les tables de correspondance de Core-AAM couvrent MSAA avec IAccessible2 et UI Automation sous Windows, l’API AX (NSAccessibility) sous macOS, et ATK/AT-SPI sous Linux. Le lecteur d’écran interroge ces objets pour obtenir le rôle, le nom et l’état, et écoute des événements tels que les changements de focus. Si une propriété n’atteint jamais l’arbre, l’utilisateur ne l’entend jamais.
Comment inspecter l’arbre d’accessibilité
Les DevTools de Chrome comme ceux de Firefox affichent directement l’arbre d’accessibilité : Chrome via l’onglet Accessibility du panneau Elements, Firefox via son Accessibility Inspector.
Chrome : ouvrez le panneau Elements, sélectionnez un nœud et ouvrez l’onglet Accessibility (il peut se trouver derrière le bouton More Tabs »). Il affiche le rôle, le nom et les propriétés calculés, ainsi que l’origine du nom. Activez Show accessibility tree pour remplacer l’arbre DOM du panneau Elements par l’arbre d’accessibilité de la page entière. La référence d’accessibilité des Chrome DevTools documente ces deux fonctionnalités. Chrome propose également une page interne chrome://accessibility pour le débogage au niveau du navigateur.
Firefox : l’Accessibility Inspector s’ouvre depuis le menu contextuel de la page (Inspect Accessibility Properties) ou en effectuant un clic droit sur un nœud dans le volet HTML de l’Inspector, puis en choisissant Show Accessibility Properties. L’inspecteur expose l’arbre d’accessibilité propre à Gecko plutôt que des informations issues de la couche d’accessibilité de la plateforme : il affiche donc le même résultat sur tous les systèmes d’exploitation.
Deux bugs que révèle l’arbre d’accessibilité
L’arbre d’accessibilité met en évidence deux bugs de composants courants : un div cliquable sans rôle button, et un bouton-icône sans nom accessible. Chacun se manifeste par un rôle manquant ou un nom manquant. Les templates Vue et Angular produisent le même résultat, car l’arbre ne voit que le DOM rendu.
Un div cliquable sans rôle button
// Before
<div className="btn" onClick={save}>Save</div>
// After
<button type="button" onClick={save}>Save</button>
# Before (illustrative)
- text: Save
# After
- button "Save"
Un <div> doté d’un gestionnaire de clic n’a pas de rôle button dans l’arbre d’accessibilité. Un lecteur d’écran ne l’annonce pas comme un contrôle, et un utilisateur du clavier ne peut ni l’atteindre avec la touche Tab ni l’activer avec Entrée ou Espace. Les session replays de ce bug montrent clairement le problème : les utilisateurs de la souris cliquent sur le contrôle sans difficulté, tandis que les utilisateurs du clavier passent directement par-dessus, avec Tab, un élément qui ressemble à un bouton mais qui n’existe pas en tant que tel dans l’arbre.
Un bouton-icône sans nom
// Before
<button onClick={close}><svg aria-hidden="true">{/* icon */}</svg></button>
// After
<button aria-label="Close dialog" onClick={close}>
<svg aria-hidden="true">{/* icon */}</svg>
</button>
# Before (illustrative)
- button
# After
- button "Close dialog"
Un bouton composé uniquement d’une icône, sans texte ni aria-label, apparaît comme un bouton au nom vide : un lecteur d’écran n’a alors rien d’autre à annoncer que « bouton ».
Tester l’arbre d’accessibilité avec Playwright
Le localisateur getByRole de Playwright trouve les éléments par rôle ARIA, attributs ARIA et nom accessible, conformément aux spécifications du W3C, et ne retient par défaut que les éléments non masqués. Un test qui trouve un contrôle par son rôle et son nom vérifie donc aussi que ce contrôle expose bien ce rôle et ce nom. Les ARIA snapshots vont plus loin : locator.ariaSnapshot() et page.ariaSnapshot() renvoient une représentation YAML de l’arbre d’accessibilité, et expect(locator).toMatchAriaSnapshot() permet d’écrire des assertions sur celle-ci.
import { test, expect } from '@playwright/test';
test('save control is a real button', async ({ page }) => {
await page.goto('/settings');
await page.getByRole('button', { name: 'Save' }).click();
await expect(page.locator('body')).toMatchAriaSnapshot(`- button "Save"`);
await expect(page.locator('body')).toMatchAriaSnapshot(`- button "Close dialog"`);
});
Exécutez ce test sur le balisage « avant » et l’appel à getByRole échoue, pour la même raison qu’un utilisateur de lecteur d’écran se retrouve bloqué. Un template n’a besoin de correspondre qu’à une partie de l’arbre, et un template à nœud unique comme ceux-ci correspond à n’importe quelle profondeur. Si un template liste plusieurs nœuds au niveau supérieur, ceux-ci doivent partager le même parent et apparaître dans le même ordre que dans l’arbre. Lorsqu’un localisateur échoue, journalisez await page.ariaSnapshot() pour voir ce que l’arbre contient réellement. Ces noms sont ceux de l’API JavaScript ; les autres bindings disposent d’équivalents. La documentation de Playwright précise par ailleurs que les localisateurs basés sur les rôles ne remplacent ni les audits d’accessibilité ni les tests de conformité : considérez-les comme un retour précoce.
Les données de rôle et de nom comptent aussi au-delà des exécuteurs de tests. Certains outils d’automatisation pilotés par l’IA lisent la structure sémantique d’une page, ce qui explique en partie pourquoi les navigateurs agentiques fonctionnent mieux sur un balisage sémantique.
Conclusion
L’arbre d’accessibilité est la version de votre interface que reçoivent réellement les technologies d’assistance : un rôle manquant ou un nom vide dans cet arbre signifie que le contrôle est inutilisable pour ces utilisateurs. Ouvrez l’onglet Accessibility sur votre composant personnalisé le plus utilisé, vérifiez son rôle et son nom, puis transformez cette vérification en assertion getByRole pour que la correction reste acquise.
FAQ
Ajouter role='button' à un div suffit-il à le corriger dans l'arbre d'accessibilité ?
En partie seulement. Ajouter role='button' donne au div un nœud de type bouton dans l'arbre d'accessibilité, si bien que les lecteurs d'écran l'annoncent comme un bouton, mais cela n'ajoute aucun comportement de bouton. Le div a encore besoin de tabindex='0' pour rejoindre l'ordre de tabulation et d'un gestionnaire keydown qui déclenche l'action sur Entrée et Espace. Un élément button natif fournit le focus et l'activation au clavier par défaut.
aria-hidden='true' empêche-t-il les utilisateurs du clavier de donner le focus à un élément ?
Non. aria-hidden='true' retire un élément et ses descendants de l'arbre d'accessibilité, mais n'a aucun effet sur le focus clavier. Un lien, un bouton ou un champ situé dans un conteneur aria-hidden peut toujours recevoir le focus via Tab : les utilisateurs du clavier atterrissent alors sur un contrôle que les technologies d'assistance ne peuvent pas nommer. Définir aria-hidden='false' sur un enfant ne le réexpose pas. Pour masquer un contenu interactif à tous les utilisateurs, utilisez display: none ou l'attribut hidden.
Comment lire le rôle calculé et le nom accessible d'un élément dans des tests automatisés ?
Utilisez des commandes d'automatisation plutôt que des scripts exécutés dans la page. La spécification WebDriver du W3C définit les commandes Get Computed Role et Get Computed Label, que ChromeDriver implémente et que WebdriverIO expose sous la forme de getComputedRole() et getComputedLabel(). Playwright propose les assertions toHaveRole() et toHaveAccessibleName() pour un élément unique, ainsi que ariaSnapshot() pour obtenir une représentation YAML d'un sous-arbre entier. Tous ces outils renvoient le rôle et le nom que reçoivent les technologies d'assistance.
Pourquoi les correspondances de nom de getByRole ont-elles changé après la mise à jour vers Playwright 1.65 ?
Playwright 1.65 ne prend plus en compte le texte que le navigateur n'affiche pas dans les noms accessibles et les ARIA snapshots. Le texte qui n'est attribué à aucun slot, ou qui se trouve directement dans un élément details fermé, n'est plus comptabilisé. Cela peut modifier les résultats de getByRole() utilisé avec l'option name, la sortie de ariaSnapshot() et les assertions toMatchAriaSnapshot() : les noms attendus doivent donc correspondre uniquement au texte que le navigateur affiche réellement.
Gain control over your UX
See how users are using your site as if you were sitting next to them, learn and iterate faster with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.
Star on GitHub12k