AbhiDas-lab/Website-Builder-Skill

Auditer et construire des sites web qui restent corrects

Un site ne reste pas correct parce que quelqu'un l'a vérifié une fois. Il reste correct quand chaque règle est une vérification, chaque vérification s'exécute là où elle peut bloquer un mauvais déploiement, et chaque vérification a déjà été vue échouer. Tout ce qui suit sert cet objectif.

C'est une méthode, pas un guide de marque. Les règles propres à un site (sa langue, sa ponctuation, comment il écrit son nom, les marques de ses partenaires, ce qui est confidentiel, comment les coordonnées sont affichées) appartiennent à un profil interne pour ce projet, généralement son fichier CLAUDE.md. Lisez le profil interne du projet avant de vérifier le contenu. S'il n'y en a pas, proposez d'en créer un (modèle dans references/templates.md).

Un profil interne appartient à un seul site. N'importez pas les règles, la juridiction, le fuseau horaire ou la marque d'un autre projet dans celui-ci simplement parce qu'ils se trouvent dans votre contexte. Demandez la langue, la juridiction légale (quelle loi sur la confidentialité s'applique), le fuseau horaire dans lequel les plannings s'exécutent et l'audience, ou indiquez ce que vous supposez.

Deux modes partagent une même boucle :

• Audit : vérifier un site en ligne, une branche, une page ou un rapport d'audit externe que quelqu'un a envoyé.
• Construction : démarrer un nouveau site, ou ajouter une page, une fonctionnalité, une collection CMS ou un type de contenu récurrent à un site existant.

La boucle, pour chaque changement

1. Mesurer d'abord, sur le résultat construit, partout. Construisez le site et lisez dist/ (ou le site en ligne), chaque page, à plusieurs largeurs. Un rapport qui a vérifié une seule URL manque la page où se trouve le vrai problème. Traitez tout audit externe comme un ensemble d'hypothèses : dans le projet d'où vient cette méthode, trois des quatre éléments « obligatoires » d'un rapport ont échoué à la mesure (il comptait alt="" comme manquant, blâmait le balisage de carte pour des ancres provenant de deux navigations, et déclarait des données structurées présentes comme absentes).

2. Classez ce que vous avez trouvé. Un défaut est corrigé. Une décision éditoriale (texte, compromis de mise en page, une carte isolée dans la dernière rangée d'une grille, quel choix de titre utiliser) est transmise au propriétaire avec des options mesurées, pas votre préférence. Un non-changement délibéré est consigné avec sa raison pour que le prochain auditeur ne le rouvre pas. Lisez le commentaire de code près de tout ce qui semble anormal avant de le modifier ; la raison s'y trouve souvent.

3. Corrigez à la source de vérité. Ne modifiez jamais manuellement les fichiers générés. Les corrections qui doivent survivre à une régénération vont dans une couche de règles que le générateur applique, et cette couche doit générer une erreur si le texte auquel elle se rattache disparaît.

4. Ajoutez une vérification qui l'aurait détecté, dans la bonne porte (section suivante), en lisant le résultat construit plutôt qu'un fixture. Ajoutez ensuite un contrôle : un cas voisin qui ne doit pas déclencher la vérification.

5. Testez la vérification en la cassant. Cassez le vrai élément (dans la source, ou en mutant dist/), exécutez la vérification, constatez qu'elle échoue avec un message utile, restaurez, constatez qu'elle réussit. Une vérification qui ne peut pas échouer ressemble exactement à une qui réussit. Si la mutation ne la déclenche pas, confirmez d'abord que la mutation a bien touché ce que la vérification lit, puis corrigez la vérification. scripts/break-test.mjs effectue le cycle de mutation, exécution et restauration en toute sécurité.

6. Régénérez les données dérivées et lisez le diff. Les tables de dimensions d'images, les dates de sitemap, les index de recherche et les fichiers de type deviennent silencieusement obsolètes. Une dérive que vous n'avez pas causée est une vraie dérive, pas un bruit.

7. Livrez, et surveillez l'arrivée. Avant de vous fier à un push, sachez ce qu'il déploie (sur de nombreux hébergeurs, un push sur n'importe quelle branche est la production). Créez une branche, fusionnez, poussez, puis regardez CI jusqu'à la fin et confirmez que le site en ligne sert le changement. Ne rapportez pas un succès depuis une construction locale.

8. Enregistrez-le. Une ligne numérotée dans un registre : ce qui a changé, pourquoi, quels fichiers, quelle vérification le garantit. Enregistrez aussi les constatations retirées et vos propres erreurs. Format dans references/templates.md.

Portes : où vit chaque vérification

La plupart des équipes supposent que CI bloque un mauvais déploiement. Souvent ce n'est pas le cas : l'hébergeur construit et déploie sur push pendant que CI s'exécute en parallèle, et une sauvegarde CMS déclenche un déploiement sans CI du tout. Décidez pour chaque règle de la porte dont elle a besoin, et notez-la à côté de la vérification.

Porte	Bloque le déploiement ?	Mettre ici
Build / postbuild (s'exécute dans le build de l'hébergeur)	Oui	Tout ce qui ne doit jamais atteindre les visiteurs : secrets divulgués ou données personnelles, ponctuation ou orthographe interdite, forme des marques, adresses email complètes, contenu trop long pour un emplacement fixe. Doit être rapide et sans navigateur.
Vérification statique de dist/ (CI)	Non	Liens, titres, meta, données structurées, sitemap, redirections, fichiers d'en-têtes, hygiène du balisage, comptages, accessibilité lisible depuis le HTML.
Balayage par navigateur headless (CI)	Non	Mise en page et débordement à plusieurs largeurs, troncature, tailles de cible, styles calculés, comportement (carrousels, disclosures, embeds).
Vérification en ligne (à la main, après les modifications du tableau de bord)	Non	Ce que la réponse déployée contient réellement, dans les deux sens : déclaré mais non servi, servi mais non déclaré. Les règles du tableau de bord peuvent réécrire des en-têtes que le dépôt ne voit jamais.
Humain sur un vrai appareil	Non	Sensation tactile, hover persistant, :active sur iOS, zones de sécurité, comportement de défilement et d'intersection.

Deux raffinements :

• Signalez, pas d'échec, là où l'échec pénaliserait un éditeur. Si une sauvegarde CMS produit quelque chose par construction (un cinquième article dans une rangée de quatre cartes, un téléchargement au mauvais chemin), signalez-le ; un build rouge pour une question de classement apprend aux gens à ignorer les builds rouges. La langue, les fuites et les octets échouent toujours.
• Ce que CI détecte et qui ne doit jamais être livré a besoin d'une garde au moment du build aussi. Si le balayage par navigateur trouve qu'un contenu trop long casse une mise en page, ajoutez une limite bon marché au moment du build (caractères, comptages) pour que la mauvaise version ne puisse pas être déployée pendant que CI est encore en cours.

Comment écrire des vérifications qui tiennent

• Lisez le résultat construit, pas les fixtures. Les vérifications qui itèrent sur une liste tenue à jour ignorent silencieusement tout ce qui est ajouté plus tard ; dans le projet source, chaque article de blog créé via CMS n'était pas vérifié de cette façon. Pilotez les vérifications structurelles à partir de dist/**/index.html.
• Lisez chaque champ destiné au lecteur : texte du corps, <title>, contenu de meta, alt, aria-label, title, placeholder. La dérive vit dans les attributs que personne ne lit.
• Calculez, ne faites pas de correspondance de chaîne. Mesurez la largeur du titre en pixels (scripts/title-width.mjs), calculez le contraste à partir de l'alpha réel du dégradé au bord supérieur du texte, comparez la géométrie affichée. Une correspondance de chaîne laisse passer une valeur différente avec le même défaut.
• Vérifiez dans les deux sens. Le fichier existe et la page le déclare ; les champs de configuration CMS et le schéma de contenu ; les en-têtes déclarés et les en-têtes servis ; chaque chemin source dans un mapping est effectivement suivi.
• Correspondance de motifs, ne collez jamais le secret. Une liste de blocage de termes confidentiels qui contient les termes est elle-même la fuite. Les motifs de prix ont besoin d'un chiffre à côté du mot pour que le vocabulaire ordinaire passe.
• Supprimez <script> et <style> avant les règles de prose, sinon les @type de JSON-LD et les color de CSS feront échouer les vérifications d'orthographe. Vérifiez le balisage brut pour la ponctuation, car les normalisateurs de texte partagés réécrivent souvent les tirets et les espaces.
• Mesurez la couverture. Instrumentez l'assistant d'assertion pour enregistrer quelles assertions ont été exécutées. Une assertion qui ne s'exécute jamais ne peut jamais échouer.
• Laissez du mou. Le CI Linux affiche le texte 2 à 3 % plus large que Windows ou macOS ; une mise en page qui tient à 1 px en local échoue en CI, et Android rend comme CI. Laissez 20 px ou plus, et testez les largeurs de part et d'autre de chaque point de rupture, pas seulement 375/768/1280.

Pire cas de contenu

Le contenu de démonstration est choisi, sans que personne le remarque, pour être beau. Avant de faire confiance à un composant qui affiche du contenu éditable ou futur (diapositives d'événements, cartes, fil d'Ariane, titres, champs CMS), alimentez-le avec des pires cas plausibles via le même fichier de données que le contenu réel : le nom réaliste le plus long, un sous-titre sur deux lignes, un compte de 1, 3 ou 5 dans une grille de 2 ou 4, un champ optionnel manquant, un titre dépassant la longueur de séparation du fil d'Ariane. Ne validez pas le fixture. Ensuite :

• ce qui casse visiblement, corrigez-le dans le composant (laissez une ligne optionnelle céder, enroulez plutôt que tronquez) ;
• ce qui ne peut pas céder, maintenez-le avec une limite au moment du build et un message d'erreur clair ;
• ce qui est un choix de design (cartes orphelines, image manquante), demandez au propriétaire.

Dans le projet source, cela a révélé du texte courant 150 px dans une légende à toutes les largeurs et un fil d'Ariane perdant son espace, ni l'un ni l'autre visibles avec le vrai contenu du jour.

Ce que vous ne pouvez pas vérifier depuis une session d'agent

Les agents et les navigateurs headless affichent avec visibilityState caché : IntersectionObserver ne se déclenche jamais, les images paresseuses ne se chargent jamais, les timelines d'animation restent à zéro. Ils ne défileront pas à partir d'un toucher synthétique, et focus() dans un document non focalisé ne déclenche aucun événement de focus. Donc : ne concluez jamais sur un comportement déclenché par le défilement, le chargement paresseux ou la sensation tactile à partir d'une session. Staginguez le changement, dites clairement qu'il n'est pas confirmé, et donnez à la personne une vérification spécifique à faire (pour le chargement paresseux, une fenêtre de navigation privée, parce qu'un rechargement normal peint depuis le cache). Plus dans references/tooling-gotchas.md.

Mode audit : que livrer

Commencez par le verdict. Ensuite les constatations, les plus graves en premier, chacune avec la mesure qui la sous-tend. Gardez les affirmations que vous n'avez pas pu reproduire hors des constatations et dans leur propre liste courte, avec ce que vous avez mesuré à la place. Utilisez le format de rapport dans references/templates.md. Pour chaque constatation, dites dans quelle porte sa vérification devrait vivre. Si l'utilisateur n'a demandé qu'un verdict, donnez-le en quelques lignes et proposez le rapport complet.

Lorsqu'on vous demande d'agir sur un audit tiers, mesurez chaque affirmation avant de corriger quoi que ce soit, et rapportez quelles affirmations tenaient, lesquelles non, et ce que l'audit a manqué.

Mode construction : quoi mettre en place

Pour un nouveau site, mettez en place l'infrastructure de vérification avant la première page, car l'adapter après-coup signifie auditer tout deux fois. references/build-baseline.md liste la base de démarrage : décisions d'hébergeur et d'URL (forme canonique, origines en double désactivées, page 404 servie, actifs immuables), les quatre portes de vérification, les en-têtes de sécurité et CSP sans 'unsafe-inline', la parité de schéma CMS, la base mobile et animations, et le profil interne.

Pour une nouvelle page ou fonctionnalité sur un site existant, exécutez la boucle ci-dessus, étendez les vérifications existantes plutôt que d'en écrire de parallèles, et effectuez le passage de pire cas sur tout ce qui affiche du contenu éditable.

Animations et toucher, brièvement

Par défaut, moins d'animations. Animez uniquement là où cela donne un retour, maintient une continuité spatiale, montre un changement d'état ou cache un changement gênant, et gardez les animations d'interface sous 300 ms. Rejetez les fondus au défilement, les compteurs de nombres, les marquees et les animations d'entrée sur chaque vue de page. Filtrez les effets de hover derrière (hover: hover) and (pointer: fine) ; donnez au toucher un état de pression :active ; chaque animation a besoin d'un chemin réduit et d'un fallback qui montre le contenu immédiatement. Avant de proposer une transition entre deux choses, confirmez que les deux choses existent sur les deux pages. Détails dans references/audit-checklist.md (Mobile, toucher et animations).

Fichiers de référence

Lisez celui dont vous avez besoin, quand vous en avez besoin :

• references/audit-checklist.md : le catalogue complet des vérifications par domaine (SEO, accessibilité, performances, sécurité et confidentialité, style de contenu, mise en page, CMS, mobile et animations), chacune avec ce qu'elle détecte, quelle porte, et l'écueil qui l'a rendue nécessaire. À lire avant tout audit, et lors de l'ajout de vérifications.
• references/build-baseline.md : configuration de démarrage pour un nouveau site. À lire lors du démarrage ou de la replateforme d'un site.
• references/tooling-gotchas.md : pièges d'outils et d'environnement qui coûtent des heures. À lire avant de faire confiance à une mesure de navigateur, un outil d'image, ou un script avec des échappements d'expression régulière.
• references/judgement-calls.md : décisions qui semblent fausses et sont correctes, et comment distinguer les défauts des choix éditoriaux. À lire avant de « corriger » quelque chose qui semble étrange.
• references/templates.md : modèles de ligne de registre, rapport d'audit, décision du propriétaire et profil interne.

Les scripts vivent dans le dossier scripts/ de ce skill, pas dans le projet. Exécutez-les depuis là, ou copiez-les dans le projet lorsque vous mettez en place ses vérifications ; ne les décrivez pas comme si un dépôt les avait déjà. Lorsque vous citez une mesure dans un rapport, dites comment vous l'avez obtenue. Node 18+, sans dépendances :

• scripts/title-width.mjs : largeur en pixels d'un titre dans un résultat de bureau Google, avec un auto-test contre des mesures Chrome. node title-width.mjs "Étiquette de page · Marque" [--suffix " · Marque"].
• scripts/break-test.mjs : muter un fichier, exécuter une commande de vérification, confirmer qu'elle échoue avec un message attendu, restaurer le fichier quoi qu'il arrive. Exécutez avec --help.