Toolkit · Pour les développeurs

Accessibilité web pour les développeurs — conçu pour les ingénieurs qui préfèrent corriger la cause racine plutôt que d'ajouter un overlay

La section du site orientée ingénierie. Modèles HTML sémantique, rôles ARIA qui fonctionnent réellement en production, harnais de tests adaptés aux lecteurs d'écran, recettes d'intégration CI, et l'état de l'art par framework pour la gestion du clavier.

Conçu comme point d'entrée : les modèles, les outils, les harnais de test et les guides spécifiques aux frameworks dont les ingénieurs ont réellement besoin pour livrer des fonctionnalités accessibles sans théâtre d'overlay. Lié au scanner WCAG 2.2 gratuit pour un triage ponctuel et au guide d'achat des outils de surveillance pour une couverture continue.

Les quatre pratiques d'ingénierie qui font vraiment la différence

Opinionated. Pas exhaustif. Les modèles qui, lorsqu'ils sont appliqués, éliminent la plupart des régressions d'accessibilité avant la revue de code.

HTML sémantique d'abord, ARIA ensuite

Lorsque l'HTML natif peut faire le travail, utilisez-le. <button> dispose nativement de la gestion clavier, du focus, du rôle et de l'activation par Entrée/Espace ; <label> associe un contrôle à sa description ; <dialog> embarque le piège de focus et le comportement d'inertie du reste de la page que vous devriez sinon coder manuellement ; <details> est un widget de divulgation sans JavaScript. ARIA est la trappe de secours — utile lorsqu'il n'existe pas d'élément natif adapté, nocif lorsqu'on le saupoudre sur un élément qui fonctionne déjà. Référence : les critères de succès WCAG 2.2 et le guide des pratiques d'authoring ARIA du W3C.

La navigation au clavier n'est pas une case à cocher

Chaque élément interactif doit fonctionner au clavier seul. Tab et Shift+Tab pour se déplacer ; Entrée ou Espace pour activer ; Échap pour fermer une surface transitoire (modale, popover, menu). Le focus doit être visible — jamais outline: none; sans remplacement. Le focus doit se déplacer logiquement — lorsqu'une modale s'ouvre, le focus y entre ; lorsque la modale se ferme, le focus revient à l'élément qui l'a ouverte. Testez au clavier avant de tester à la souris ; la souris masque des bugs que le clavier révèle immédiatement.

Noms et descriptions accessibles

Pas de saupoudrage d'aria-label. Le nom accessible provient par défaut du contenu textuel de l'élément ; aria-labelledby référence le texte d'un autre nœud ; aria-label écrase tout avec une chaîne codée en dur (et doit être votre dernier recours car il contourne la traduction et tend à diverger de l'étiquette visible). La description accessible est distincte — aria-describedby référence le nœud d'aide ou de message d'erreur. Vérifiez dans l'arbre d'accessibilité des outils de développement ce que le lecteur d'écran reçoit réellement — les hypothèses et la réalité divergent souvent.

Testez dans votre vraie CI, pas seulement en local

Une vérification axe locale est un test de bon sens. Une CI verte est une porte contre les régressions. Connectez eslint-plugin-jsx-a11y à chaque PR ; ajoutez des assertions axe-core aux tests unitaires et e2e ; exécutez des flux AT-driver sur des pages représentatives afin qu'un vrai lecteur d'écran pèse dans la balance. L'étude sur les outils de test avec lecteur d'écran couvre ce qui vaut la peine d'être automatisé et ce qui nécessite encore un balayage manuel.

La chaîne d'outils — 13 outils et bibliothèques sélectionnés

Chaque entrée correspond à une étape du cycle de vie — lint, test unitaire, e2e, runtime, surveillance ou revue manuelle — afin de connecter le bon outil à la bonne porte.

Guides spécifiques aux frameworks

Les écueils d'accessibilité qui changent de forme selon les écosystèmes — et une couverture approfondie pour chacun d'eux.

React

Clés dans les listes (des listes mal clées perturbent les lecteurs d'écran lors du réordonnancement des éléments). Gestion du focus lors du changement de route (sans cela, le focus reste sur le lien qui a déclenché la navigation et la nouvelle page est invisible pour les utilisateurs de technologies d'assistance). Portails et pièges de focus — une modale rendue dans document.body doit quand même maintenir le focus en son sein. Les incohérences d'hydratation qui modifient la structure du DOM entre le SSR et le client peuvent silencieusement briser les relations ARIA. Notre analyse approfondie sur les régions aria-live dans les frameworks modernes couvre le modèle d'annonce des régions live que la réconciliation React tend à briser.

Vue / Svelte / Solid

Modèles similaires ; les changements d'état réactif ne déclenchent pas les mises à jour des régions live par défaut. Le modèle de réactivité de chaque framework a une définition différente de « le DOM a changé », et les lecteurs d'écran voient — ou ne voient pas — la mise à jour du nœud résultante de façon subtilement différente. Le v-if contre v-show de Vue, les déclarations réactives de Svelte et la réactivité fine de Solid produisent tous des mises à jour différentes de l'arbre d'accessibilité pour ce qui ressemble au même code.

Mobile natif (iOS + Android)

Une surface d'API entièrement différente. iOS expose UIAccessibility (et .accessibilityLabel() / .accessibilityHint() de SwiftUI) à VoiceOver ; Android expose AccessibilityNodeInfo à TalkBack. L'ARIA de style web ne se transpose pas. L'article sur les API d'accessibilité mobiles natives met en correspondance les concepts web avec leurs équivalents natifs afin que les ingénieurs formés au web cessent de deviner.

Bibliothèques de composants

Les bibliothèques headless (Radix UI, Headless UI, React Aria) gèrent les parties difficiles — gestion du focus, navigation au clavier, câblage ARIA — et laissent le design visuel entièrement à votre charge. Les bibliothèques complètes (Material UI, Chakra, Ant) livrent des visuels opinionés mais varient largement en qualité d'accessibilité, et « accessible par défaut » signifie rarement « audité contre de vrais lecteurs d'écran ». Notre étude sur les bibliothèques de composants accessibles évalue les principales options face à de vrais tests avec technologies d'assistance.

Liste de contrôle de revue de PR pour l'accessibilité

À imprimer, à coller dans votre modèle de PR ou à automatiser dans un bot. Le minimum que chaque relecteur doit vérifier.

  • Les éléments interactifs fonctionnent au clavier seul (Tab + Entrée + Espace + Échap).
  • L'indicateur de focus est visible sur chaque élément interactif.
  • Les champs de formulaire ont un <label> associé.
  • Les messages d'erreur sont associés à leurs champs (aria-describedby ou texte adjacent).
  • Les changements de contenu dynamique sont annoncés via aria-live le cas échéant.
  • Les boîtes de dialogue modales piègent le focus et le restituent à l'élément déclencheur à la fermeture.
  • Les images ont un texte alternatif pertinent ; les images décoratives portent alt="".
  • Les listes utilisent <ul> / <ol> / <dl> — pas de soupe de <div>.
  • La hiérarchie des titres est cohérente (pas de niveaux sautés).
  • Les tests Lint + axe passent en CI avant la fusion.

Antipatterns d'ingénierie courants

Les modèles qui passent la revue de code puis cassent en production. Détectez-les plus tôt.

  • Le « widget overlay » — du JavaScript tiers qui prétend ajouter de l'accessibilité à un site existant. Ce n'est pas le cas, il perturbe fréquemment la couche de technologies d'assistance, et il a généré sa propre vague d'actions en justice. Contexte : les fournisseurs d'overlay.
  • role="button" sur un <div> — ajoute l'annonce du rôle sans le comportement clavier (Entrée, Espace) ni la participation à l'ordre de tabulation. Utilisez <button>.
  • aria-hidden="true" sur des éléments focusables — crée un piège de focus où les utilisateurs clavier peuvent atteindre par Tab un élément que le lecteur d'écran est invité à ignorer. Retirez l'élément de l'ordre de tabulation avec tabindex="-1" ou supprimez l'aria-hidden.
  • Menu déroulant personnalisé sans gestion clavier — un combobox à base de <div> qui s'ouvre au clic mais ignore les touches fléchées, Début/Fin, la saisie prédictive et Échap. L' étude sur les bibliothèques de composants accessibles couvre les bibliothèques qui gèrent cela correctement nativement.
  • Notifications toast qui n'annoncent pas — une surface transitoire rendue sans role="status" (polite) ou role="alert" (assertive). Les utilisateurs voyants la voient ; les utilisateurs de lecteurs d'écran ne la voient pas.
  • DOM généré qui brise l'arbre d'accessibilité — de lourdes enveloppes autour d'un input (un select personnalisé construit à partir de douze <div> imbriqués) cachent souvent le contrôle réel aux technologies d'assistance. Testez ce que la technologie d'assistance voit, pas seulement ce que l'utilisateur voit.

Le Toolkit + pipeline de surveillance

La plupart des équipes veulent trois choses dans l'ordre : un scan de triage ponctuel lorsque quelque chose semble cassé, une référence d'ingénierie pour comprendre les modèles sous-jacents, et une couche de surveillance continue une fois que l'accessibilité est inscrite dans la feuille de route de production. Notre scanner WCAG 2.2 gratuit couvre le premier point — collez une URL publique, obtenez un rapport axe dans un nouvel onglet. La couverture d'ingénierie au bureau des articles couvre le second — notamment les analyses de la dette d'accessibilité en tant que dette technique et les post-mortems d'incidents d'accessibilité à la SRE pour les équipes gérant l'accessibilité à l'échelle.

Pour la couche continue, le guide d'achat des outils de surveillance est la pièce la plus opinionée du site. Il évalue axe Monitor, Siteimprove, Level Access et Qualibooth — ce dernier intégrant la surveillance à un transfert d'audit manuel, le maillon manquant dans la plupart des stacks automatisés — selon la largeur de couverture, les taux de faux positifs et la façon dont les données s'intègrent proprement dans les workflows d'ingénierie. L'objectif de la surveillance est de s'assurer que les corrections livrées aujourd'hui ne régressent pas au sprint suivant.

Questions d'ingénierie fréquemment posées

Les questions qui reviennent à chaque réunion de lancement sur l'accessibilité. Reflétées dans les données structurées FAQPage.

aria-label est-il préférable aux étiquettes textuelles visibles ?
Non. Le texte visible est presque toujours préférable — il bénéficie aux utilisateurs voyants, aux utilisateurs voyants ayant des handicaps cognitifs, aux utilisateurs de la commande vocale (qui disent ce qu'ils voient) et aux outils de traduction. Recourez à aria-label uniquement lorsqu'il n'y a pas de texte visible à associer (boutons avec icône seule) ou lorsque le texte visible n'est vraiment pas le nom accessible souhaité.
Faut-il utiliser des rôles ARIA pour tout ?
Non. La première règle d'ARIA est « ne pas utiliser ARIA ». Les éléments HTML natifs disposent déjà du bon rôle, du bon comportement au clavier et de la bonne sémantique dans l'arbre d'accessibilité. Utilisez ARIA uniquement lorsqu'il n'existe pas d'élément natif adapté — par exemple, une liste d'onglets, une arborescence ou un dialogue personnalisé où vous ne pouvez pas utiliser <dialog>.
Comment tester l'accessibilité en CI ?
Trois couches, classées par coût. (1) Lint : eslint-plugin-jsx-a11y sur chaque PR. (2) Tests unitaires : @testing-library/jest-dom plus jest-axe (ou @axe-core/react) sur chaque composant. (3) End-to-end : @axe-core/playwright sur des parcours utilisateurs représentatifs. Ajoutez une porte Pa11y ou Lighthouse CI en staging pour détecter la dérive que les couches inférieures manquent.
axe-core et Lighthouse sont-ils identiques ?
Lighthouse utilise axe-core sous le capot pour son audit d'accessibilité, mais il exécute un sous-ensemble sélectionné de règles et les présente dans un rapport plus large couvrant performance, SEO et bonnes pratiques. axe-core est le moteur lui-même — lorsque vous souhaitez l'ensemble complet des règles ou l'étendre, vous utilisez axe-core directement. Pour la plupart des équipes : utilisez Lighthouse pour le suivi des tendances, axe-core pour la porte réelle.
Quelle est la configuration minimale de test d'accessibilité pour un projet React ?
Ajoutez eslint-plugin-jsx-a11y à la configuration ESLint existante (fourni par défaut avec create-react-app et Next.js). Ajoutez @testing-library/jest-dom et jest-axe à votre configuration de tests unitaires, et appelez expect(await axe(container)).toHaveNoViolations() dans au moins un test par composant. C'est le minimum — cela détecte environ 40 % des problèmes WCAG réels pour quelques heures de configuration.
Faut-il tester avec de vrais lecteurs d'écran ?
Oui, pour toute fonctionnalité produit qu'un utilisateur de technologie d'assistance utilisera réellement. L'outillage automatisé détecte les défaillances structurelles (étiquettes manquantes, contraste, incohérences de rôles) mais pas les défaillances fonctionnelles (focus qui saute vers le pied de page, régions live qui n'annoncent pas, modale « accessible » qui piège le focus dans le mauvais sous-arbre). Prévoyez au moins un balayage manuel par version majeure avec NVDA sur Windows et VoiceOver sur macOS / iOS.

Prochaines étapes

Lancez une vérification rapide avec le scanner WCAG 2.2 gratuit si vous triagez une page spécifique. Lisez l'étude sur les outils de test avec lecteur d'écran avant de connecter AT-driver en CI. Et si l'accessibilité passe d'un « audit ponctuel » à une « préoccupation de production continue », le guide d'achat des outils de surveillance est la pièce la plus concrète du site pour choisir un fournisseur.