Migrer un site WordPress vers un stack headless peut être libérateur : performances, flexibilité front, architecture moderne. Mais j'ai souvent vu une conséquence trop peu anticipée — une régression de l'accessibilité. Lors d'une migration, on change la façon dont le HTML est généré, comment le DOM est hydraté, comment les interactions sont gérées — et chaque étape peut introduire des erreurs pour les utilisateurs de lecteurs d'écran, de navigateurs clavier-only ou d'autres technologies d'assistance.

Dans cet article, je partage mon approche pratique pour réduire les erreurs d'accessibilité pendant et après la migration WordPress → headless. Ce sont des conseils que j'applique quand je travaille avec Next.js, Gatsby, Nuxt ou tout autre framework front (et en back avec WPGraphQL, REST, Strapi ou Contentful) pour conserver — voire améliorer — l'expérience accessible.

Anticiper l'accessibilité dès la planification

Avant de toucher une ligne de code, je fais en sorte que l'accessibilité fasse partie du cahier des charges. Des décisions d'architecture ont un impact : SSR vs SSG vs CSR, stratégie d'images, gestion des dialogues/modals, routes dynamiques, prévisualisation CMS, etc. Voici ce que j'illustre systématiquement :

  • Choisir SSR/SSG pour les pages critiques. Les contenus rendus côté serveur offrent un HTML complet, utile aux technologies d'assistance avant la phase d'hydratation.
  • Prévoir des stratégies de fallback pour JS désactivé ou erreurs de chargement (progressive enhancement).
  • Inclure les exigences ARIA, titres de pages et structures sémantiques dans la définition des composants et des champs CMS.

    • Conserver et enrichir le HTML sémantique

    WordPress génère souvent un HTML relativement sémantique lorsqu'on utilise des thèmes et des templates bien conçus. En headless, on reprend la responsabilité complète du rendu — il faut donc ne pas la lâcher.

  • Prioriser les balises sémantiques : <header>, <main>, <nav>, <article>, <aside>, <footer>. Le rôle des landmarks est crucial pour le repérage des utilisateurs de lecteurs d'écran.
  • Veiller à l'ordre DOM logique : l'ordre visuel et l'ordre DOM doivent rester cohérents pour éviter des surprises au clavier ou au lecteur d'écran.
  • Garder les titres hiérarchiques (h1 → h2 → h3). Si le CMS autorise des titres libres, imposer des bonnes pratiques via le schéma de contenu.

    • Gérer correctement le routing et les changements de contexte

    Les frameworks SPA modifient l'URL sans recharger la page — les lecteurs d'écran doivent être informés. Lors d'une migration, j'ajoute systématiquement des mécanismes pour annoncer les changements importants :

  • Mettre à jour le focus principal après navigation : placer le focus sur <main> ou sur un titre de page.
  • Modifier le titre document.title à chaque route et s'assurer que les descriptions meta importantes sont présentes pour la navigation vocale.
  • Utiliser des live regions (aria-live) pour annoncer le chargement de contenu asynchrone non navigable par URL.

    • Hydratation, rendu côté client et problèmes courants

    L'hydratation peut créer un "flash" ou un contenu inattendu. J'observe souvent :

  • Labels manquants après hydratation (ex. controlled components qui perdent l'attribut id/for).
  • Composants accessibles côté serveur mais rendus différemment côté client, cassant l'ordre DOM.

    • Pour limiter les risques :

  • Conserver la parité SSR/CSR : ce qui est rendu côté serveur doit correspondre au rendu côté client.
  • Éviter la logique conditionnelle basée uniquement sur window/document pour des éléments critiques d'accessibilité.

    • Formulaires, validations et erreurs

    Les formulaires sont un autre point d'échec fréquent. En headless, la validation côté client et la présentation des erreurs doivent être accessibles :

  • Associer les messages d'erreur aux champs via aria-describedby.
  • Utiliser des role="alert" ou aria-live="assertive" pour les messages importants.
  • Ne pas se reposer uniquement sur les couleurs pour indiquer une erreur : ajouter des icônes, un texte descriptif et des attributs ARIA adéquats.

    • Images, médias et contenu riche

    La migration entraîne souvent une refonte du pipeline d'images (optimisation, lazy-loading). Pour rester accessible :

  • Fournir systématiquement des attributs alt utiles. Dans un CMS headless, rendre le champ "alt" obligatoire ou proposer un fallback automatisé (mais pas idéal).
  • Pour les images décoratives, utiliser alt="" et role="presentation" si nécessaire.
  • Pour les vidéos, fournir des sous-titres, des transcriptions et des contrôles clavier-friendly.

    • Composants interactifs et gestion du focus

    Les composants custom (menus, dropdowns, modals, tooltip) demandent une attention particulière :

  • Gérer le focus trap dans les modals et le retour du focus après fermeture.
  • Fournir des labels accessibles et des rôles ARIA corrects (role="dialog", aria-modal="true", aria-expanded, aria-controls...).
  • S'assurer que les éléments interactifs sont focusables (tabindex) et ont des états visuels et textuels clairs.

    • Outils de test automatisés et intégration continue

    L'automatisation est votre alliée pour attraper les régressions. J'intègre régulièrement ces outils :

  • axe-core / axe-core-ci pour intégrer des scans d'accessibilité dans le pipeline CI.
  • Lighthouse pour des audits rapides (mais pas suffisant seul).
  • Pa11y pour des tests en ligne de commande.
  • Storybook avec addon-a11y pour vérifier les composants isolément.

    • Configurer le CI pour échouer la build sur régressions critiques permet d'éviter d'envoyer en production des erreurs facilement détectables.

    Tests manuels et utilisateurs réels

    Aucun outil automatique ne remplace le test humain. J'organise toujours :

  • Parcours clavier complet (navigation, formulaires, dialogues).
  • Tests avec lecteurs d'écran populaires : NVDA (Windows), VoiceOver (macOS/iOS), TalkBack (Android).
  • Sessions utilisateur avec personnes utilisant des aides techniques — elles mettent souvent en lumière des problèmes inattendus.

    • Maintenir la qualité côté CMS (WordPress) lorsque headless

    Le CMS reste la source de vérité. Pour éviter que des contenus non accessibles ne remontent :

  • Configurer des champs obligatoires (ex. alt, description) dans l'éditeur Gutenberg ou via des plugins.
  • Former les rédacteurs : bonnes pratiques pour titres, listes, tableaux, liens explicites.
  • Mettre en place des validations côté serveur pour les champs critiques.

    • Exemples concrets de pièges rencontrés (et solutions)

    ProblèmeCauseSolution
    Skip link invisibleCSS modifié durant la migrationRestaurer visibilité au focus et tester au clavier
    Dialog non annoncéAbsence de role/aria-modalAjouter role="dialog" aria-modal="true" + focus trap
    Titre de page non mis à jourSPA navigation sans mise à jour document.titleMettre à jour title et déplacer le focus sur <main>

    En résumé, aborder l'accessibilité comme une responsabilité transversale — architecture, composant, contenu, CI et tests utilisateurs — est le moyen le plus fiable de minimiser les régressions lors d'une migration vers un stack headless. Dans mes projets, adopter cette démarche permet non seulement de respecter les obligations légales et éthiques, mais aussi d'améliorer l'expérience pour tous.