site-upgrade

Site upgrade

Une méthode pour transformer un site qui semble assemblé en un site dont son propriétaire est fier de faire la démonstration. Elle a été distillée à partir de refontes réelles qui ont été livrées et que les propriétaires et leurs équipes ont très bien notées : le site marketing d'une application mobile, le site d'une entreprise cloud B2B repris dans deux directions complètes, et un centre d'aide construit de toutes pièces. Réutilisez la méthode, les recettes et les pièges. Ne réutilisez jamais un look : chaque site tire sa direction de sa propre marque, de son produit et de son public.

Ce que signifie « terminé »

La mise à niveau est terminée lorsque tous ces points sont vérifiés, et pas avant :

• Chaque affirmation sur le site remonte à une source que vous pouvez nommer : code du produit, texte juridique, système de facturation, ou réponse écrite du propriétaire.
• Le design provient du matériel propre de la marque, et son idée échoue au test du concurrent (direction.md).
• Un ou deux moments signature que le visateur fait ou regarde ; tout le reste est discipliné.
• Rien n'a besoin d'animation pour être vu. En mouvement réduit, les états finaux s'affichent.
• Il a été vérifié dans un vrai navigateur à 1440, 1920×710, 390 et 320 px, dans chaque thème, avec mouvement réduit, sur une version de production.
• Votre critique écrite lui attribue une note de 9/10 ou plus, ou votre rapport indique clairement où il pèche (critique.md).
• Il est livré sous forme de PRs que l'équipe peut réviser, avec un court résumé à coller.

Règles de base

1. La vérité avant le design. Chaque fonctionnalité, nombre, prix, date de disponibilité et preuve sociale remonte à une source. Le texte de l'intégration et du paywall du produit promet souvent trop : vérifiez-le dans le code. « Inconnu » est une réponse valable : rendez l'emplacement facultatif et demandez, ne le comblez jamais avec un nombre plausible. Supprimez les preuves fabriquées.
2. La marque décide de l'apparence. Dérivez la palette, la typographie et le dispositif signature du matériel propre de la marque : logo, nom, UI du produit, vidéos, lieu. Un dispositif qui semble généré (tells.md) n'est autorisé que si le matériel de la marque ou le propriétaire l'y place, et que le contrat de direction le nomme.
3. Le produit est le héros. L'UI réelle et les artefacts réels surpassent les icônes, la 3D de stock et les abstractions. Une démo ressemble à la réalité : une vraie facture A4, un vrai modèle rendu, le vrai catalogue.
4. Un site web, pas un diaporama. Évitez les empilements de blocs centrés titre-plus-image qui s'estompent chacun. Utilisez la composition, les histoires à défilement épinglé, la profondeur en couches, les démos interactives et l'animation pilotée par l'état.
5. Ne cachez jamais le contenu derrière une animation. Une révélation qui ne se déclenche jamais laisse une page blanche. Respectez prefers-reduced-motion en affichant les états finaux.
6. Propriétaire dans la boucle, pas dans le chemin. Montrez la direction avant la construction complète. Faites la page d'accueil en premier et élargissez aux autres pages une fois qu'elle est approuvée. Posez chaque question ouverte une fois, avec des options, et continuez à construire autour.
7. La configuration contient les valeurs. Les variables d'environnement portent une URL, un ID ou un jeton, jamais d'interrupteurs marche/arrêt ou de constantes en dur. Dérivez les valeurs dépendantes à partir de celles-ci. Ne commitez que .env.example.
8. Suivez le dépôt cible. Lisez son README, CONTRIBUTING, AGENTS.md et la configuration commitlint. Utilisez son gestionnaire de paquets. Faites correspondre ses versions de framework (Next 14 vs 16, Tailwind 3 vs 4, React 18 vs 19).
9. Les secrets et les internes restent en dehors. N'imprimez, ne commitez et n'écho jamais un jeton que le propriétaire colle. Les commits et PRs publics ne portent pas de noms de clients, de prix privés ou de failles de sécurité non corrigées.
10. Ne déclarez jamais terminé en dessous de 9/10. Notez le travail à partir de captures d'écran avant de le rapporter. Une auto-évaluation de 6 ou 7 proposée après « terminé » est le signe d'un travail bâclé.

D'abord, choisissez le mode

Ce que le visiteur est venu faire décide jusqu'où le design peut aller. Un projet peut contenir plusieurs surfaces dans différents modes ; donnez à chacune le sien.

Mode	Surfaces	Le visiteur	Ce qui mène	Lire
Persuader	produit, marketing, entreprise, campagne, tarification	décide et agit	le produit qui fait ses preuves ; une action réelle sur le premier écran	building-blocks.md
Lire	centre d'aide, docs, changelog, blog	comprend quelque chose	la question du lecteur ; la marque possède le cadre, jamais la colonne de lecture	read-mode.md
Expérimenter	portfolio, showroom, galerie	explore le travail	le travail lui-même, dès le premier viewport	building-blocks.md § Expérience

Le site marketing d'un produit est en mode Persuader même s'il montre l'application. Son centre d'aide est en mode Lire même s'il est beau.

Flux de travail

Travaillez à travers les phases dans l'ordre. Lisez chaque référence lorsque vous atteignez sa phase, pas avant.

Phase	Faire	Lire
0. Lancement	Créer une branche à partir de la branche par défaut, démarrer le serveur de dev (noter le port réel), capturer l'ensemble « avant » pour le rapport	verification.md § 1
1. Découverte	Auditer le site, trouver les sources de vérité, écrire le registre des affirmations et l'inventaire des sujets, collecter le matériel de marque, rapporter les résultats	discovery.md
2. Direction	Trouver l'idée et passer le test du concurrent, définir la palette et la typographie, choisir les moments signature, rédiger le contrat de direction, le montrer	direction.md, tells.md
3. Construire en statique	Jetons, le héros, chaque acte avec du contenu réel, les pages intérieures. Désactivez l'animation mentalement	building-blocks.md, media.md, read-mode.md
4. Animation et signature	Une introduction chorégraphiée, des moments pilotés par l'état, la signature. 3D uniquement si elle mérite sa place	motion.md, three-d.md
5. Contact et conversion	Validation partagée, le formulaire, une route externe, un email de notification conçu, réservation ou pré-remplissage de lead	contact-email.md
6. SEO et standards	Rendu serveur, métadonnées, cartes sociales, données structurées, fichiers d'exploration, en-têtes. Sa propre PR en pile	seo-standards.md
7. Vérifier et critiquer	Boucles de navigation à chaque largeur et thème, les vérifications scriptées, une version de production, puis la critique notée, jusqu'à trois tours	verification.md, critique.md
8. Livrer	Commits, PRs, la mise à jour de l'équipe, le rapport avant/après, DESIGN.md, notes mémoires	delivery.md

Consultez gotchas.md à chaque fois que quelque chose se comporte bizarrement. Lisez feedback.md à chaque fois que le propriétaire réagit : il transforme ce que les propriétaires disent (« pas assez de piquant », « couleurs déséquilibrées », « copie bon marché ») en ce qu'il faut changer.

Si un skill de direction design est installé (frontend-design, impeccable, taste-skill), chargez-le en phase 2 pour plus d'étendue. Ce skill fonctionne de manière autonome sans lui.

Stack. Les recettes sont livrées sur Next.js, React, Tailwind et GSAP, hébergées sur Cloudflare Pages, et les extraits montrent cette stack. La méthode, les vérifications et la plupart des scripts n'en dépendent pas : sur Astro, SvelteKit, Nuxt ou du HTML simple, conservez la règle et traduisez la recette vers le framework et les versions cibles.

Scripts

Exécutez à partir de la racine du dépôt cible. <skill> est le dossier de ce skill.

• node <skill>/scripts/slop-scan.mjs [dir] [--json] [--strict] [--allow <rules>] [--list-rules] : analyse le code source à la recherche de marqueurs de site généré, de preuves inventées, de texte générique, de liens morts, de secrets et de pièges connus. Quitte avec le code 1 en cas d'erreurs (ou en cas d'avertissements avec --strict). Nommez une exception justifiée avec un commentaire site-upgrade-allow: <rule> <reason> (il couvre les lignes en dessous jusqu'à la prochaine ligne vide) ou un fichier .site-upgrade-allow à la racine du dépôt. Node 18+, aucune dépendance.
• <skill>/scripts/ssr-audit.sh <base-url> [path]... : par page (chaque page du sitemap quand aucun chemin n'est donné) : statut, nombre de <h1>, blocs JSON-LD, canonique, image sociale, échappatoires de rendu client et titre ; puis en-têtes de sécurité et fichiers d'exploration. Quitte avec le code 1 quand une page échoue. Exécutez-le contre un serveur de production.
• <skill>/scripts/video-prep.sh <source> <out-dir> [name] [poster-second] : imprime les coupes de scène comme candidats chapitres et écrit des encodages web silencieux avec des images clés à chaque coupe, une affiche et un clip de prévisualisation carré. Utilise le binaire imageio_ffmpeg en secours.
• <skill>/scripts/playwright/*.js : pour l'outil browser_run_code_unsafe du MCP Playwright. Le MCP ne lit que les fichiers dans l'espace de travail, alors copiez-les d'abord (mkdir -p .playwright-mcp && cp <skill>/scripts/playwright/*.js .playwright-mcp/)) et passez filename: ".playwright-mcp/<name>.js". Gardez .playwright-mcp/ hors de git.
  • reveal-scroll.js défile pour que chaque révélation se déclenche avant une capture d'écran et liste le texte encore caché après.
  • page-audit.js mesure le cadre : un <h1>, titres sur plus de deux lignes, petit texte, petites cibles tactiles, contrôles sans nom, images sans alt, sections sans titre et surfaces du navigateur non thématisées.
  • overflow.js trouve ce qui cause le défilement horizontal de 320 à 1440 px et nomme les coupables les plus extérieurs.
  • console-scan.js visite chaque URL du sitemap et rapporte les erreurs de console, les erreurs de page, les requêtes échouées, les 4xx/5xx et les violations CSP.

Actifs et modèles

Copiez dans le dépôt cible ou le bloc-notes et adaptez :

• assets/render-email.ts : rend les modèles React Email en HTML sans react-dom/server, pour les routes périphériques.
• assets/JsonLd.tsx : une balise script JSON-LD sécurisée à intégrer.
• assets/ScrollTriggerRefresh.tsx : remesure les déclencheurs de défilement GSAP chaque fois que la hauteur de la page change.
• assets/templates/claims-ledger.md : livré, non livré, inconnu et nombres, chacun avec une source (phase 1).
• assets/templates/direction-contract.md : la thèse, l'idée, le monde propre, le premier viewport, la signature et les exceptions de marque (phase 2).
• assets/templates/critique-round.md : la critique notée, un bloc par tour (phase 7).
• assets/templates/DESIGN.md : le système de design construit, écrit à la fin pour que les agents ultérieurs restent sur la marque (phase 8).
• assets/templates/team-update.md : la mise à jour à copier-coller pour le chat de l'équipe (phase 8).

Points de contrôle avec le propriétaire

Confirmez ces points avant de publier quoi que ce soit qui en dépend. Demandez une fois avec des options ; ne bloquez pas la construction :

• statut de lancement et disponibilité en magasin, à partir de la fiche du magasin en ligne plutôt que des indicateurs d'environnement
• prix et forfaits, et leur source
• chiffres que personne ne peut encore sourcer (disponibilité, centres de données, nombres de clients) : laissez-les de côté jusqu'à ce que quelqu'un les approuve
• la boîte de réception de contact, et une boîte de réception que le propriétaire peut lire pour les tests
• articles non encore publiés dans toute liste, catalogue ou carrousel
• identité légale, adresse et téléphone, identiques partout où ils apparaissent
• tout tiers qui recevrait des données de visiteurs (analytique, intégrations, polices, email), et les lignes de la politique de confidentialité dont il a besoin
• les fichiers sources pour toute mascotte, modèle 3D ou vidéo avant d'en reconstruire un
• chaque étape de production : domaines, DNS, paramètres de déploiement, migrations. Le propriétaire exécute ou approuve