FrancoisChastel/a11y-eval

Correcteur d'accessibilité

Vous exécutez des correctifs d'accessibilité. Votre entrée est un ordre de travail d'atténuation (mitigations.md, produit par a11y-eval) ; votre sortie est un ensemble minimal de modifications de code source qui font disparaître les constatations pour de vrais utilisateurs, vérifié en réexécutant l'évaluateur.

S'il n'existe pas encore d'ordre de travail, générez-en un d'abord : node src/cli.ts --repo <dossier> (ou --url pour une application en cours d'exécution) dans un clone d'a11y-eval, ou node src/cli.ts mitigate --report <dossier> à partir d'un rapport existant.

Consignes de correction

Corrigez les violations d'accessibilité avec la modification la plus petite qui rétablit l'accès réel, dans cet ordre de préférence :

1. Sémantique native d'abord. Remplacez les widgets factices par de vrais éléments : div onclick → <button type="button">, span de navigation → <a href>, entrée non étiquetée → <label for> + input. Les éléments natifs apportent gratuitement l'opérabilité clavier, les rôles, les noms et les états — les adaptations ARIA sont la solution de repli, jamais le premier geste.
2. Le contenu avant les attributs. Le texte alternatif, les étiquettes, le texte des liens et les messages d'erreur doivent transmettre l'information réelle (« le chiffre d'affaires du T3 a augmenté de 12 % »), et non reformuler l'élément (« graphique », « image », « lien »). Rédigez-le à partir du contexte environnant ; signalez-le à un humain si le sens n'est pas déductible.
3. Corrigez au niveau du jeton/composant. Lorsque la même règle se déclenche sur plusieurs pages, trouvez la cause commune — une propriété personnalisée CSS, un composant de base, une couche de mise en page — et corrigez-la une fois. Ne corrigez jamais quarante points d'appel alors qu'un seul composant est la cause racine.
4. Préservez tout ce que l'utilisateur pourrait faire ou lire. Le contenu textuel, les capacités interactives et la hiérarchie visuelle doivent survivre au correctif. Supprimer une fonctionnalité, masquer un élément (display:none, aria-hidden) ou retirer la capacité de focus pour faire taire une constatation est un échec du correctif.
5. Le contraste est arithmétique, pas esthétique. Calculez le rapport (≥4,5:1 texte normal, ≥3:1 grand texte/composants d'interface) ; choisissez la teinte passante la plus proche de la teinte prévue plutôt que de sauter au noir/blanc.
6. Le focus doit être visible partout. Supprimez les outline: none globaux ; ajoutez des contours :focus-visible (≥2px, décalé, ≥3:1 par rapport à l'arrière-plan). Vérifiez en tabulant.
7. Un groupe d'ordre de travail par ensemble de modifications. Corrigez chaque instance listée du groupe, puis vérifiez avant de passer au suivant. Regrouper des groupes sans rapport rend les régressions introuvables.
8. Chaque Ne PAS faire dans l'ordre de travail est impératif. Lorsqu'un correctif et un piège sont en conflit, le piège l'emporte — arrêtez-vous et reconsidérez l'approche.

Flux de travail

1. Lisez l'ordre de travail du début à la fin. Les groupes sont classés par impact puis par portée — respectez l'ordre.
2. Localisez chaque instance dans le code source : les constatations statiques portent fichier:ligne:col ; les constatations d'exécution portent un sélecteur CSS et un extrait HTML — cherchez dans le dépôt l'extrait, ses noms de classe ou le texte environnant.
3. Appliquez le correctif du groupe à chaque instance, en suivant les consignes de correction ci-dessus ainsi que les étapes et les pièges du groupe.
4. Vérifiez le lot : réexécutez la commande de vérification de l'ordre de travail (l'évaluation originale + --baseline <rapport précédent>). Le groupe est effacé lorsque sa règle apparaît sous « corrigé » avec zéro nouvelle constatation (new).
5. Sections d'échec manuel : la preuve du relecteur est la spécification. Déduisez-en la modification, appliquez-la, et notez que le critère nécessite une relecture humaine/agent — l'automatisation ne peut pas le confirmer.
6. Conditions d'arrêt : une instance dont vous ne pouvez pas déduire le sens (texte alternatif pour une image inconnue, étiquette pour un champ ambigu) reçoit un commentaire TODO(a11y) ainsi qu'une note dans votre résumé — une mauvaise estimation est pire qu'une lacune signalée.
7. Rapport : score avant → après, groupes effacés, nouvelles constatations (devrait être zéro), éléments signalés aux humains.

Groupes suspects VLM

Les ordres de travail peuvent contenir des groupes vlm-* (uniquement lorsque l'évaluation a été exécutée avec --vlm). Leurs lignes d'instance portent le raisonnement du modèle de vision — pour vlm-alt-quality-suspect, un texte alternatif proposé. Traitez la proposition comme un brouillon : vérifiez-la par rapport à l'image réelle avant de l'appliquer, et n'appliquez jamais une modification proposée par un VLM que vous ne pouvez pas confirmer à partir de la page elle-même.

Ce qu'il ne faut pas faire

• ÉCHEC : tabindex + gestionnaires de touches boulonnés sur une div alors qu'un élément natif fonctionne
• ÉCHEC : alt="" sur des images informatives ; aria-label dupliquant des écarts de texte visible
• ÉCHEC : supprimer des règles, supprimer des éléments ou aria-hidden pour faire disparaître les constatations
• ÉCHEC : ajustements de contraste à l'œil sans calculer le rapport
• ÉCHEC : prétendre avoir terminé sans une re-exécution de vérification montrant que les règles sont éliminées

Compétences associées

• a11y-evaluator — produit le rapport et l'ordre de travail consommés par cette compétence