Communitygithub.com

wcag-audit

Audite les interfaces utilisateur pour les défaillances d'accessibilité WCAG 2.2 et les corrige. Utilise une procédure par phases (analyse statique du code source, analyse runtime dans un navigateur réel avec axe-core et vérifications clavier, vérification contradictoire de chaque résultat, corrections minimales avec explications, et rapport lisible par machine).

Qu'est-ce que wcag-audit ?

Cette compétence d'agent IA réalise un audit complet d'accessibilité des interfaces utilisateur basé sur les critères WCAG 2.2. Elle suit un processus en cinq phases : analyse statique du code source (HTML, JSX, TSX, Vue, Svelte, Astro, MDX, Angular, CSS), analyse runtime dans un navigateur réel avec axe-core et tests clavier, vérification contradictoire pour éliminer les faux positifs, corrections minimales avec explications, et production d'un rapport lisible par machine. L'outil détecte les problèmes d'accessibilité tels que le manque de labels, les contrastes insuffisants, les problèmes de focus clavier, et propose des correctifs natifs HTML sans ajout excessif d'ARIA. Il est utile pour les développeurs et les équipes souhaitant vérifier la conformité WCAG 2.2, ADA, Section 508 ou EN 301 549 avant le déploiement d'interfaces générées par l'agent. Son approche centrée sur la vérification rigoureuse garantit que seuls les problèmes confirmés sont corrigés.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/mintwork/wcag-audit-skill/tree/HEAD/skills/wcag-audit

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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

  1. 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.
  2. HTML natif d'abord. Le meilleur ARIA est l'absence d'ARIA. Corrigez <div onClick> en le transformant en <button>, pas en ajoutant role, tabindex et des gestionnaires de touches.
  3. 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).
  4. 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_validation et demandez ; n'écrivez pas alt="image".
  5. 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 :

  1. Apportez la plus petite modification qui satisfait le critère, dans l'idiome du framework (htmlFor dans React, :aria-label dans Vue, etc.).
  2. Expliquez-la en une ou deux phrases : ce qui n'allait pas, qui cela affectait, ce qui a changé.
  3. 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éSignificationExemples
critiqueBloque complètement une tâche pour certains utilisateurschamp de formulaire non étiqueté, <div onClick> comme seul moyen de soumettre, piège clavier, zoom désactivé
sérieuxDifficulté majeure ou information manquantetexte à faible contraste, langue de page manquante, lien sans nom
modéréFrottement, structure déroutanteniveaux de titre sautés, texte de lien redondant ou vague dans son contexte
mineurPolissage, meilleure pratiquetexte 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-label qui 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

Skills associés