Audit WCAG
Vous auditez une interface utilisateur pour les barrières d'accessibilité et vous les corrigez. Les utilisateurs en situation de handicap ne peuvent pas contourner un label manquant comme le ferait un utilisateur souris voyant : traitez chaque résultat confirmé comme un véritable bogue qui bloque une personne réelle.
Objectif : une liste de résultats vérifiés, chacun lié à un critère de succès WCAG 2.2, avec un emplacement précis, une preuve et une correction minimale — puis les corrections, appliquées et revérifiées.
Principes
- Vérifié ou ne sort pas. Chaque résultat doit survivre à la Phase 3. Une courte liste de vrais problèmes vaut mieux qu'une longue liste que l'utilisateur apprend à ignorer.
- HTML natif d'abord. Le meilleur ARIA est l'absence d'ARIA. Corrigez
<div onClick>en le transformant en<button>, pas en ajoutantrole,tabindexet des gestionnaires de touches. - Corrections minimales et préservant le comportement. Modifiez le balisage qui échoue ; ne restylez pas, ne refactorisez pas et ne reformatez pas le code environnant. Conservez la conception visuelle inchangée, sauf si le résultat est visuel (contraste, anneau de focus, taille de cible).
- N'inventez jamais de contenu. Le texte alternatif, les labels et le texte des liens doivent refléter ce que l'UI signifie réellement. Si vous ne pouvez pas déterminer ce qu'une image transmet, marquez le résultat
needs_validationet demandez ; n'écrivez pasalt="image". - L'automatisation est un plancher, pas un plafond. Les outils détectent environ un tiers à la moitié des échecs WCAG. Signalez ce qui n'a pas été testé (voir la checklist manuelle).
Configuration
Déterminez le périmètre à partir de la demande de l'utilisateur : l'ensemble du dépôt, un répertoire, des composants spécifiques ou une URL. Vérifiez ensuite l'outillage :
npx --yes @mintwork/wcag-audit-skill --version # CLI disponible ?
Si la CLI n'est pas disponible (hors ligne, pas de Node), continuez en mode manuel : appliquez la liste de règles dans references/RULES.md en lisant vous-même le code source, et passez la Phase 2 à moins que l'environnement de l'utilisateur ne fournisse un autre outil de navigation.
Écrivez tous les artefacts dans .wcag-audit/ à la racine du dépôt (créez-le ; suggérez de l'ajouter à .gitignore, tout en conservant .wcag-audit/baseline.json si le projet commit une baseline CI). N'écrivez jamais ailleurs sauf si l'utilisateur le demande.
Flux de travail
Exécutez les phases dans l'ordre. Informez l'utilisateur de la phase en cours. Pour les petits périmètres (un seul composant), les phases peuvent être brèves, mais ne sautez pas la Phase 3.
Phase 1 — Analyse statique (source)
npx @mintwork/wcag-audit-skill scan <chemin> --json -o .wcag-audit/static.json --fail-on none
Auditez sans --baseline même si le projet en commit une (.wcag-audit/baseline.json) : la baseline permet seulement à l'IC d'ignorer les résultats connus, et ils nécessitent toujours une révision.
Ensuite, lisez references/STATIC-SCAN.md et effectuez la révision que l'outil ne peut pas faire : composants personnalisés qui encapsulent des éléments natifs, rendu conditionnel, props de design system (<Icon label=…>), styles de focus supprimés dans CSS-in-JS ou remplacés dans une autre feuille de style (la CLI vérifie .css / .scss / .less et les classes Tailwind un fichier à la fois), état color-only, et tout ce que le scanner a ignoré à cause de props spread ou de valeurs dynamiques. Ajoutez ces éléments comme résultats candidats avec "source": "static" et "confidence": "medium".
Phase 2 — Analyse runtime (navigateur réel)
Uniquement si une URL est disponible ou si l'application peut être démarrée. Trouvez la commande de développement (scripts package.json, README), démarrez-la en arrière-plan, attendez qu'elle réponde, puis :
npx @mintwork/wcag-audit-skill scan http://localhost:3000 --source src --json -o .wcag-audit/runtime.json --fail-on none
# Plus de pages / états :
npx @mintwork/wcag-audit-skill scan http://localhost:3000/login http://localhost:3000/cart --json -o .wcag-audit/runtime-2.json --fail-on none
Scannez les pages importantes (accueil, flux principaux, formulaires, modales ouvertes) — voir references/RUNTIME-SCAN.md pour les états à couvrir, les attentes SPA et l'authentification. Placez les états (ouvrir une modale, soumettre un formulaire vide, mode sombre, 320px) dans une configuration et exécutez scan --config .wcag-audit/config.json ; pour les pages connectées, utilisez --storage-state <fichier> de l'utilisateur, jamais d'identifiants. Si le projet a Storybook, exécutez également scan --storybook storybook-static (ou l'URL Storybook en cours) pour couvrir chaque état de composant. sourceHint de chaque résultat runtime est un résultat de recherche : confirmez-le avant de corriger à cet endroit. Les résultats runtime capturent ce que l'analyse statique ne peut pas : contraste calculé, noms accessibles réels, ordre de focus, pièges clavier, focus invisible.
Phase 3 — Vérification (élimination des faux positifs)
Pour chaque candidat, suivez references/VERIFICATION.md. Essayez de le réfuter : ouvrez la source à la ligne signalée, tracez les props/slots/spreads jusqu'à l'endroit où la valeur est définie, vérifiez si un parent fournit le label, vérifiez le DOM rendu pour les résultats runtime. Attribuez un verdict :
confirmed— vous l'avez tracé et il échoue au critère. Enregistrez comment vous le savez.needs_validation— plausible mais vous n'avez pas pu l'établir (par exemple, qualité du texte alternatif, contenu que vous ne pouvez pas voir, page inaccessible). Aucune correction n'est appliquée.rejected— réfuté. Enregistrez pourquoi (cela apprend à l'utilisateur quelles règles ajuster).
Fusionnez les doublons : la même cause racine signalée par l'analyse statique et runtime constitue un résultat avec les deux emplacements.
Phase 4 — Correction
Corrigez les résultats confirmed, en commençant par la sévérité la plus élevée, en utilisant references/FIX-PATTERNS.md. Pour chaque correction :
- Apportez la plus petite modification qui satisfait le critère, dans l'idiome du framework (
htmlFordans React,:aria-labeldans Vue, etc.). - Expliquez-la en une ou deux phrases : ce qui n'allait pas, qui cela affectait, ce qui a changé.
- Demandez avant les corrections qui modifient l'UI visible ou le texte (couleurs de contraste, nouveaux labels visibles, texte de lien), sauf si l'utilisateur a déjà donné son accord.
Les résultats mécaniques (réparations html-lang, meta-viewport-zoom, fautes de frappe aria-attr-valid) peuvent être corrigés par la CLI : exécutez scan <chemin> --dry-run, montrez le diff à l'utilisateur, puis scan <chemin> --fix. Un lang manquant n'est ajouté qu'avec --lang <code> une fois que vous connaissez la langue de la page.
Ensuite, revérifiez mécaniquement :
npx @mintwork/wcag-audit-skill verify .wcag-audit/static.json
npx @mintwork/wcag-audit-skill verify .wcag-audit/runtime.json # serveur de développement toujours en cours
verify se termine avec un code non nul si quoi que ce soit reste ou si une correction a introduit un nouveau résultat. Itérez jusqu'à ce que les résultats confirmés soient résolus ou que vous ayez expliqué pourquoi l'un d'eux ne peut pas être corrigé dans le code (par exemple, nécessite du contenu de sous-titres de l'utilisateur). Exécutez les propres tests/lint du projet.
Phase 5 — Rapport
Écrivez .wcag-audit/findings.json conforme au assets/report-schema.json et validez-le :
node <skill-dir>/scripts/validate-findings.mjs .wcag-audit/findings.json
Ensuite, écrivez .wcag-audit/REPORT.md et donnez à l'utilisateur un résumé court, en suivant references/REPORTING.md : comptes par sévérité et verdict, ce qui a été corrigé, ce qui nécessite leur intervention, ce qui n'a pas été testé.
Sévérité
| Sévérité | Signification | Exemples |
|---|---|---|
| critique | Bloque complètement une tâche pour certains utilisateurs | champ de formulaire non étiqueté, <div onClick> comme seul moyen de soumettre, piège clavier, zoom désactivé |
| sérieux | Difficulté majeure ou information manquante | texte à faible contraste, langue de page manquante, lien sans nom |
| modéré | Frottement, structure déroutante | niveaux de titre sautés, texte de lien redondant ou vague dans son contexte |
| mineur | Polissage, meilleure pratique | texte alternatif vague, autofocus |
La sévérité reflète l'impact utilisateur dans cette UI, pas la valeur par défaut de la règle : une boîte de recherche non étiquetée dans un pied de page est moins grave qu'un champ de mot de passe non étiqueté sur la page de connexion.
Anti-patrons (à ne pas faire)
- N'ajoutez pas
aria-labelqui duplique ou contredit le texte visible (casse WCAG 2.5.3). - N'ajoutez pas
role="button"+tabindex="0"quand<button>fonctionne. - Ne "corrigez" pas un résultat d'ordre de titre en modifiant la taille visuelle ; changez le niveau et conservez le CSS.
- Ne définissez pas
alt=""sur des images informatives pour faire taire le scanner. - Ne supprimez pas les résultats (
wcag-audit-ignore) sans une raison écrite à côté du commentaire. - Ne prétendez pas à la "conformité" WCAG — l'examen automatisé + agent peut montrer des échecs, pas la conformité.
- Ne modifiez pas le code généré, vendu ou
node_modules; corrigez le composant source.
Fichiers
- references/RULES.md — chaque règle statique et runtime, mappée à WCAG
- references/STATIC-SCAN.md — Phase 1 : révision manuelle par framework
- references/RUNTIME-SCAN.md — Phase 2 : pages, états, SPA, authentification
- references/VERIFICATION.md — Phase 3 : procédure de réfutation par règle
- references/FIX-PATTERNS.md — Phase 4 : corrections avant/après
- references/REPORTING.md — Phase 5 : format du rapport
- references/MANUAL-CHECKLIST.md — ce que l'automatisation ne peut pas vérifier
- assets/report-schema.json — schéma de findings.json
scripts/validate-findings.mjs— validateur sans dépendance pour findings.json