Écrire des règles dans un dépôt de règles frontend et les vérifier avant publication

## Avant de modifier une règle, distinguer les fichiers sources modifiables des fichiers générés Considérez un dépôt de règles frontend comme un produit composé de contenu source, de schémas, d’API, d’outils de révision, de pages rendues et d’index générés. Avant de le modifier, déterminez quelle couche est responsable du comportement, puis examinez cette couche et ses consommateurs directs. - Cartographiez le paquet de contenu, les types et schémas partagés, les surfaces applicatives, le serveur d’outils et les sorties générées. - Lorsqu’ils sont disponibles, utilisez les outils de révision et de recherche de règles du dépôt au lieu d’inventer des consignes de mémoire. - Examinez le code inspecté avant de recommander des corrections et recherchez dans le corpus de règles avant d’avancer des affirmations sur l’accessibilité, les performances, le SEO, la sécurité, la confidentialité, l’internationalisation ou les tests. - Ne réalisez des audits étendus que lorsque la tâche exige un audit étendu. - Distinguez les sources modifiables des artefacts générés et des projections rendues. Déduisez les consignes de compatibilité de la politique de navigateurs déclarée et des données fournies par les paquets. Ne vous fiez pas à des tableaux de compatibilité mémorisés et ne traitez pas implicitement une vue générée comme la source de vérité. ## Définir les métadonnées que chaque règle doit avoir Chaque règle nécessite un contrat de métadonnées stable qui prend en charge l’analyse, la recherche, la notation, la révision et le rendu. Gardez l’ensemble obligatoire suffisamment restreint pour pouvoir l’appliquer systématiquement. Les métadonnées obligatoires doivent comprendre : - un titre lisible par une personne, entre guillemets, et une description d’une phrase ; - une catégorie, une priorité et une difficulté autorisées ; - une estimation entière de l’effort avec une unité déclarée ; - des instructions exploitables pour vérifier, corriger et expliquer la règle. Les métadonnées facultatives utiles comprennent une sous-catégorie, des conclusions concises, l’impact pour l’utilisateur ou l’entreprise, les sources de preuves, les ressources complémentaires, les règles associées, les outils, les étiquettes, une instruction de révision du code et le contexte d’une révision automatisée. Validez les catégories et les énumérations par rapport aux listes canoniques autorisées. Placez entre guillemets les valeurs qui contiennent une ponctuation significative pour la syntaxe. N’ajoutez pas de champs simplement parce qu’ils semblent utiles ; ajoutez-les uniquement lorsque l’analyseur, l’interface, la couche de recherche ou le générateur les utilise. Les instructions doivent nommer l’objet à examiner et la correction attendue. Rejetez les textes de substitution tels que « vérifier cette règle », qui ne fournissent aucune stratégie de révision exécutable. ## Séparer les preuves, les lectures complémentaires et les liens vers les règles liées Conservez les preuves faisant autorité dans les métadonnées structurées de la source. Conservez les lectures et outils facultatifs dans les métadonnées des ressources, et la navigation entre règles dans les métadonnées des règles associées. Ne substituez pas un rôle à un autre. - Attribuez à chaque règle au moins 2 sources pertinentes, avec 2 rôles de source distincts et au moins 1 autorité primaire. - Utilisez des identifiants stables pour les preuves lorsque le pipeline les prend en charge. - Écartez du corps les lignes génériques comme « Voir aussi » et « Référence ». - Créez un lien vers un outil nommé lors de sa première mention significative lorsqu’il apporte une aide concrète et figure déjà dans les métadonnées de ressources ou d’outils. Les liens intégrés doivent étayer une affirmation précise ou un choix d’implémentation. Une valeur par défaut utile est de 2 à 5 liens par règle, avec 0 à 1 dans l’introduction et 1 à 3 dans les consignes principales. Dans la plupart des cas, limitez les liens internes vers des règles à 0 ou 1 et n’en utilisez 2 que pour les sujets exceptionnellement interconnectés. Préférez un texte d’ancrage descriptif aux libellés comme « en savoir plus ». Laissez les outils de compilation déduire les champs qu’ils peuvent dériver de façon sûre, mais n’utilisez jamais l’inférence pour excuser des preuves faibles ou non pertinentes. ## Dans chaque règle, placer les exemples de code avant les raisons et la vérification à la fin Rédigez chaque règle dans un ordre stable afin que les personnes, les agents et les validateurs trouvent les mêmes informations : 1. une brève introduction en langage simple ; 2. un exemple de code réaliste ou un ensemble d’exemples ; 3. une explication de l’importance de la règle ; 4. toutes les consignes d’implémentation nécessaires ; 5. une dernière section de vérification. Placez les exemples avant la justification et conservez la vérification comme dernière section de premier niveau. Intercalez les sections facultatives, comme les bonnes pratiques, les erreurs courantes, les exemples de frameworks, les outils, les seuils, les exceptions, la compatibilité des navigateurs, les normes et les notes d’implémentation. N’ajoutez des exceptions que lorsqu’il existe des réserves valides ou des faux positifs. Ne divisez la vérification en contrôles automatisés et manuels que lorsque les deux sont pertinents. Ajoutez une note visible sur les normes ou la prise en charge lorsque la compatibilité ou la conformité modifie la décision d’implémentation. Préférez des instructions de réussite ou d’échec à des conseils génériques. Indiquez comment un ingénieur peut vérifier la règle, quelles preuves sont recevables et quelle condition fait échouer le contrôle. ## Donner aux règles frontend des seuils mesurables de réussite ou d’échec Utilisez des seuils mesurables chaque fois qu’une règle peut être testée : - des budgets de performance tels que `LCP <= 2.5s`, `CLS <= 0.1` ou des limites de taille d’actifs ; - des critères d’accessibilité tels que les rapports de contraste, la taille des cibles, le comportement du clavier, le zoom et la redistribution ; - des états SEO tels que l’indexabilité, les codes d’état et le comportement de l’URL canonique ; - des exigences de sécurité telles que les conditions de transport et d’en-têtes de réponse. Attribuez la priorité en fonction des conséquences : réservez le niveau le plus élevé aux défaillances qui rendent le site inutilisable ou enfreignent la sécurité ou la loi ; utilisez les niveaux inférieurs pour une expérience dégradée, les bonnes pratiques et les améliorations facultatives. Les exemples doivent être suffisamment réalistes pour révéler le mode de défaillance. Incluez les exceptions importantes et les contraintes de prise en charge, mais n’ajoutez pas toutes les sections facultatives à chaque règle. Traitez la vérification comme une partie de la règle, et non comme une tâche éditoriale ultérieure. Une recommandation sans contrôle reproductible est incomplète. ## Garder les composants d’interface partagés dans le design system, pas dans chaque page Placez la typographie, les icônes, les couleurs sémantiques, les composants réutilisables et les autres préoccupations communes à plusieurs applications dans un système de conception partagé. Les applications doivent configurer l’intégration propre au framework tout en consommant le contrat partagé. - Réutilisez les composants existants avant de créer des variantes propres à une page. - Appliquez une fonctionnalité partagée à chaque surface concernée, et pas seulement à la première page qui l’a demandée. - Maintenez les contrôles secondaires utilisables lorsque vous employez des modèles de cartes à lien étendu. - Centralisez les icônes de marque et les exports d’icônes du framework ; les consommateurs ne doivent pas contourner la frontière du système de conception. - Préférez des jetons de thème sémantiques avec tout le contraste prévu à des modificateurs d’opacité arbitraires. - Restaurez explicitement les marqueurs de liste lorsqu’une réinitialisation CSS les supprime du texte enrichi. Ne masquez pas un écart en supprimant les avertissements d’hydratation serveur-client. Corrigez la frontière d’état, par exemple en différant l’état propre au client jusqu’après le montage. Conservez la protection issue du navigateur sur les mutations et formulaires du navigateur. N’appliquez pas de contrôles antibot côté client aux points de terminaison d’API programmatiques qui ne peuvent pas effectuer un défi de navigateur. ## Connecter un nouvel outil de bout en bout, de la définition aux tests Un nouvel outil ou une nouvelle fonctionnalité inter-paquets n’est complet que lorsque sa définition, son exportation, son enregistrement, son routage, son implémentation, ses tests et sa documentation concordent. Pour un outil appelable : 1. définissez un nom précis, une description et un schéma d’entrée ; 2. exportez-le à la frontière du paquet ; 3. enregistrez-le dans le catalogue d’outils du serveur ; 4. connectez-le au chemin de routage ; 5. testez la découverte, la validation, le routage et le comportement. N’utilisez les fichiers d’exportation agrégés qu’aux frontières des paquets ; les fichiers internes de ce type ajoutent des étapes de navigation et masquent les responsabilités. Centralisez les versions des dépendances partagées lorsque plusieurs paquets les utilisent, et organisez les scripts par fonction avec un index maintenu. Respectez les contrats propres à la version de chaque bibliothèque. Par exemple, utilisez la forme actuelle des erreurs du validateur installé, créez les clients de requête avec état au moyen de la fabrique approuvée du dépôt et conservez les enveloppes de configuration asynchrone dans un ordre qui préserve toutes les propriétés renvoyées. Redémarrez les services après toute modification d’une configuration chargée au démarrage. Une modification réussie ne constitue pas une preuve tant que le processus en cours ne l’a pas chargée. ## Lancer toutes les vérifications avant publication, sans en sauter aucune Exécutez la chaîne de qualité canonique du dépôt après avoir modifié une règle ou son infrastructure : - validez les métadonnées obligatoires, les valeurs de catégorie, la qualité des sources et la structure de la règle ; - notez les instructions exploitables, les preuves, les exemples, la profondeur du corps, la vérification, les seuils et les sections conditionnelles applicables ; - exécutez le formatage, l’analyse statique, les contrôles de types, les contrôles de paquets, les tests ciblés et la compilation complète requise par la surface modifiée ; - régénérez les index ou les compétences et confirmez que la sortie générée est synchronisée. Ne contournez pas les contrôles de pré-commit. Corrigez les erreurs de documentation, les conversions de type dangereuses, la complexité, les frontières d’importation, le code inutilisé et la couverture au lieu d’emprunter un chemin sans vérification. Traitez la notation automatisée comme un contrôle qualité, pas comme une preuve d’exactitude sémantique. Examinez le résultat rendu et le résultat destiné aux outils, ainsi que le fichier source. Avant la publication, confirmez que les instructions obligatoires sont exploitables, que les preuves font autorité, que les exemples correspondent à la recommandation, que la vérification arrive en dernier et qu’il ne reste aucune différence générée. Ne publiez qu’après la réussite de toute la chaîne.