Écrire des règles de vérification d'accessibilité qui renvoient réussite, échec ou incomplet

## Traitez lint et tests comme une partie du changement, pas comme du nettoyage Considérez le formatage, le linting, les tests, la documentation et les conventions de commit comme faisant partie du changement, et non comme un nettoyage à effectuer après l’implémentation. ### Vérifications obligatoires - Exécutez l’outil de formatage et le linter du dépôt avant le commit. - Exécutez l’ensemble complet des tests avant de terminer, avec une couverture unitaire et d’intégration pour les changements de comportement. - Ne suivez les exceptions documentées que pour les changements qui ne peuvent pas affecter le comportement à l’exécution. - Conservez les travaux non résolus dans le système de suivi des issues du projet au lieu de les dissimuler dans des changements sans rapport. - Ne commitez ni journalisation temporaire ni paramètres locaux de débogage. ### Conventions de code - Traitez les erreurs et les cas limites tôt afin que le chemin de réussite reste facile à suivre. - Respectez l’emplacement établi des exports, les règles de nommage et le style des imports. - Nommez les fichiers et les identifiants de règles de façon cohérente ; distinguez les fonctions, les booléens et les constantes selon les conventions du projet. - Déclarez les variables près de leur première utilisation. - Documentez les API exportées, les paramètres, les valeurs de retour et la logique complexe. - Séparez le refactoring d’une fonctionnalité ou d’un correctif ciblé. ## Choisissez entre nœuds virtuels et DOM réel, et gardez des dépendances à sens unique Choisissez délibérément entre une abstraction d’arbre virtuel et de véritables nœuds DOM. L’abstraction est efficace pour les attributs et propriétés mis en cache, tandis que le DOM réel est nécessaire pour les API du navigateur et le comportement de mise en page. ### Sélection des nœuds - Préférez les nœuds virtuels pour accéder aux attributs, aux propriétés mises en cache, au parcours de l’arbre et aux opérations sur les sélecteurs. - Utilisez de véritables nœuds DOM pour la mise en page, la géométrie, la recherche de la racine, le comportement calculé par le navigateur et les autres API natives. - Résolvez les entrées ambiguës au moyen d’une seule limite de conversion documentée. - Gardez les utilitaires généraux fondés sur des entrées et sorties en DOM réel, sauf si une dépendance aux nœuds virtuels apporte un avantage clair en matière d’API ou de performances. - Ne dispersez pas la logique de conversion entre les différentes règles. ### Direction des dépendances - Conservez les définitions de normes sous forme de données pures, sans imports d’exécution. - Autorisez les utilitaires de bas niveau à dépendre uniquement du code de base de niveau inférieur et des données de normes, au moyen de chemins explicites. - Centralisez les imports de modules tiers dans une couche d’adaptation désignée. - Permettez aux helpers de domaine partagés d’utiliser les utilitaires de bas niveau, mais jamais l’inverse. - Autorisez les vérifications et règles de haut niveau à composer les couches inférieures sans créer de cycles. - Faites respecter mécaniquement ces limites au moyen de règles de linting ou de build. ## Renvoyez réussite, échec ou incomplet et placez les messages dans les métadonnées Rendez le contrat de résultat explicite afin que les consommateurs puissent distinguer la conformité, l’échec et l’insuffisance des preuves. ### Résultats des vérifications - Renvoyez `pass` lorsque la condition testée est satisfaite. - Renvoyez `fail` lorsque la condition testée est enfreinte. - Renvoyez `incomplete` lorsque le moteur ne peut pas déterminer le résultat de manière fiable. - Joignez des données structurées destinées aux modèles de messages et à l’explication des résultats `incomplete`. - Ne transformez pas de force une incertitude en `pass` ou en `fail` dans le seul but de produire une réponse binaire. ### Définitions des règles - Composez les vérifications avec des groupes explicites `all`, `any` et `none`. - Délimitez les éléments candidats avec un sélecteur et, facultativement, un matcher supplémentaire. - Limitez l’impact aux valeurs de gravité déclarées par le projet. - Lisez les définitions HTML et ARIA depuis les données de normes centralisées au lieu de coder des listes en dur dans les vérifications. ### Messages destinés aux utilisateurs - Conservez les messages dans les métadonnées des règles ou des vérifications plutôt que dans le code d’implémentation. - Utilisez des espaces réservés nommés dont les valeurs sont fournies par le résultat de la vérification. - Fournissez des variantes au singulier et au pluriel lorsque la grammaire l’exige. - Mettez à jour le modèle de localisation chaque fois qu’un message source change. ## Examinez avec un soin particulier le contraste des couleurs et la validation des rôles Certains résultats d’accessibilité dépendent d’informations incomplètes du navigateur ou de normes qui évoluent rapidement. Ces domaines exigent des conclusions prudentes et un examen ciblé. ### Couleur et visibilité - Tenez compte des formats de couleur pris en charge, de l’opacité, du mélange, des contextes d’empilement et des effets de texte. - Renvoyez `incomplete` lorsque l’arrière-plan effectif ou le contraste ne peut pas être déterminé. - Évaluez sémantiquement la visibilité pour les lecteurs d’écran au lieu de vous appuyer uniquement sur la visibilité CSS. - Prenez en compte les attributs d’état masqué, les arbres composés et les limites du Shadow DOM. ### Normes sémantiques - Maintenez la validation des rôles et des attributs synchronisée avec la spécification d’accessibilité en vigueur. - Résolvez séparément les rôles implicites et explicites. - Interrogez les définitions centralisées des rôles et des attributs afin que chaque règle utilise la même source de vérité. - Ajoutez des cas de régression pour les mises à jour de la spécification et le balisage précédemment mal classé. - Exigez un examen ciblé lorsqu’un changement peut modifier les résultats de nombreuses règles. ## Testez chaque règle sur des pages réalistes, y compris avec Shadow DOM Reproduisez la structure du code source dans l’arborescence des tests unitaires afin que la responsabilité de l’implémentation et des tests reste évidente. ### Tests unitaires et tests des vérifications - Utilisez le contexte ou le harness de vérification standard fourni par le projet. - Réinitialisez uniquement l’état appartenant au test lorsque les fixtures partagées et les arbres virtuels sont déjà effacés par le harness. - Testez les résultats `pass`, `fail` et `incomplete`, y compris les données de message qui leur sont jointes. - Ajoutez des cas ciblés pour les conditions limites avant d’élargir la couverture d’intégration. ### Tests d’intégration - Associez chaque fixture de règle à des résultats attendus structurés. - Utilisez la représentation canonique des sélecteurs du moteur, y compris les sélecteurs imbriqués pour les frames. - Utilisez une page HTML complète lorsque le comportement au niveau du document ne peut pas être représenté par un fragment. - Ajoutez un cas de Shadow DOM ouvert pour chaque règle ou vérification concernée. - Mettez à jour la couverture des règles virtuelles lorsqu’un changement affecte l’évaluation de l’arbre virtuel. - Exécutez des tests ciblés pendant les itérations et la suite complète faisant autorité avant le transfert. ## Régénérez les modèles de traduction dans le même commit que les messages Distinguez les bundles de publication générés des artefacts sources générés que le dépôt suit intentionnellement. ### Politique relative aux artefacts - Ne modifiez pas directement les sorties de publication regroupées ou minifiées. - Régénérez les modèles ou artefacts sources suivis au moyen du build approuvé. - Commitez un modèle de localisation généré dans le même changement que le message source qui l’a produit. - Ne répartissez pas les mises à jour synchronisées des sources et des fichiers générés entre des commits distincts. - Excluez les bundles de publication ignorés des commits ordinaires de fonctionnalités. ### Vérification - Inspectez le diff généré pour repérer les changements inattendus de messages, de locales ou de règles. - Confirmez que chaque nouvel espace réservé existe dans les données de la vérification qui le produit. - Exécutez la validation de la localisation et du build après toute modification de message. - Documentez quels artefacts sont générés, lesquels sont suivis et lesquels sont réservés aux publications. ## Mettez à jour le changelog et la doc d'API, et évitez les changements incompatibles Gardez chaque changement ciblé et rendez ses conséquences publiques visibles pour les réviseurs et les consommateurs. ### Documentation des changements - Mettez à jour le changelog lors de l’ajout ou de la modification substantielle d’une règle. - Mettez à jour conjointement la documentation de l’API et les définitions de types lorsqu’une interface publique change. - Utilisez le format de commit conventionnel requis par le dépôt, avec un objet concis et la motivation dans le corps. - Liez l’issue résolue au moyen du footer pris en charge ou des métadonnées de la pull request. - Remplissez la checklist de revue du projet avant le transfert. ### Compatibilité - Évitez les changements incompatibles lorsque les anciens et nouveaux formats peuvent être pris en charge simultanément. - Marquez clairement les API obsolètes et fournissez un chemin de migration. - Lorsqu’une rupture est inévitable, identifiez-la explicitement dans les métadonnées de publication et le changelog. - Incluez des instructions de migration, des tests mis à jour, des fichiers générés synchronisés et des preuves visibles par les réviseurs. - Ne déclarez pas que le changement est prêt tant que le formatage, le linting, les tests ciblés, les tests d’intégration, la suite complète et les vérifications de documentation n’ont pas produit de résultats effectifs.