Constructeur de sites web animés au scroll
Prenez un sujet et un thème de la part de l'utilisateur et livrez un site web complet, vérifié et animé au scroll — sans rendre la main en cours de route.
Avant de commencer : nouveau site ou rénovation ?
Ajouter du mouvement à une page qui se classe déjà est un travail différent avec des risques différents — le budget de scroll doit inclure la hauteur existante de la page, et un épingle est une distance de scroll morte sur une page que quelqu'un parcourt pour prendre une décision. Par défaut, construisez sur une URL de vitrine séparée et créez un lien vers celle-ci ; ne convertissez sur place que lorsque la page n'a pas de trafic à perdre et que son but est l'impression plutôt que la référence. Faites toujours une sauvegarde octet par octet en premier et donnez à l'utilisateur la commande de restauration. Lisez references/08-failure-modes.md §3 avant d'accepter une rénovation.
Le pipeline
Six phases. Exécutez-les dans l'ordre. Seule la Phase 1 dialogue avec l'utilisateur.
1 DÉCOUVERTE → assistant, 2–3 séries de questions [interactif]
2 SCORE → compile le plan scroll-score.json [autonome]
3 ASSETS → génère/rassemble images, trames, vidéo [autonome]
4 STRUCTURE → squelette du projet + moteur de mouvement [autonome]
5 CONSTRUCTION → implémente chaque battement du Score [autonome]
6 VÉRIFICATION → pilote un vrai navigateur, corrige, répète [autonome]
Une fois l'assistant fermé en Phase 1, arrêtez de poser des questions. Les phases 2 à 6 s'exécutent jusqu'à la fin selon votre propre jugement. Enregistrez les hypothèses dans DECISIONS.md et rapportez-les à la fin au lieu de bloquer dessus. L'utilisateur a demandé une construction de bout en bout ; une page à moitié construite plus une question est un échec.
Phase 1 — DÉCOUVERTE (l'assistant)
Interrogez avec l'outil AskUserQuestion, jamais en un mur de prose. Deux séries sont typiques, trois est le maximum. Banque de questions complète, branche par branche :
→ Lisez references/01-discovery-wizard.md
La première série est toujours les deux mêmes questions — le type de sujet et l'objectif principal :
| Sujet | Ce que le scroll fait vraiment |
|---|---|
| Personne (portfolio, CV, marque personnelle) | Gagner la confiance : travail → preuve → contact |
| Produit (physique ou numérique) | Révéler l'objet : héros → fonctionnalités → acheter |
| Entreprise (agence, startup, studio) | Établir l'ampleur : manifeste → travail → équipe |
| Événement / Lancement (conférence, sortie, publication) | Créer l'anticipation : date → programme → s'inscrire |
| Cause / Histoire (association, éditorial, reportage) | Porter un argument : accroche → preuves → agir |
La branche sur laquelle vous tombez sélectionne le squelette des sections et le modèle de mouvement dominant. La deuxième série pose des questions spécifiques à la branche (quel travail, quel produit, quelle preuve). La troisième série, seulement si encore ambiguë, décide de la direction esthétique, de l'intensité du mouvement et de la stratégie d'assets.
Arrêtez l'assistant dès que vous pouvez nommer : le sujet, l'objectif, 4 à 7 sections, une direction esthétique, et d'où viennent les assets. Déduisez le reste.
Phase 2 — SCORE (le plan)
Compilez tout dans scroll-score.json à la racine du projet. C'est le contrat que la construction et le vérificateur lisent tous les deux — écrivez-le avant d'écrire tout composant.
→ Lisez references/02-scroll-score.md pour le schéma complet.
Un Score est une liste de battements. Un battement = un moment animé par le scroll : ce qui est épinglé, ce qui se déroule, sur quelle distance, et ce qui bouge.
{
"meta": { "subject": "…", "type": "product", "goal": "…", "stack": "vite-vanilla" },
"theme": { "bg": "#0a0a0a", "fg": "#fafafa", "accent": "#ff4d17", "font": { … } },
"motion":{ "intensity": "cinematic", "smoothScroll": false, "reducedMotion": "degrade" },
"beats": [
{ "id": "hero", "pattern": "media-scrub-sequence", "pin": true,
"scrub": 1, "start": "top top", "end": "+=200%", "frames": 48, … },
{ "id": "features", "pattern": "sticky-stack", … }
]
}
Budgétez le scroll. La hauteur totale de la page devrait se situer autour de 100vh × (1 + Σ coût en scroll des battements). Un battement épinglé avec scrub coûte 1,5 à 2,5 hauteurs de viewport ; un battement de révélation coûte ~1. En dessous de 3, le site semble abrupt ; au-dessus de 12, il semble être une corvée. Visez 5 à 9.
Phase 3 — ASSETS
Ne livrez jamais des boîtes grises. Chaque battement nommé dans le Score a besoin de son asset réel avant la Phase 5 — une construction avec des placeholders doit toujours être refaite.
→ Lisez references/05-asset-pipeline.md pour le pipeline complet, y compris la chaîne rendu IA → vidéo interpolée → séquence de trames, toutes les invocations ffmpeg, et les budgets de poids.
Trois sources, par ordre de préférence :
- Fournis par l'utilisateur — gagnent toujours. Demandez-les dans l'assistant, jamais après.
- Générés —
mcp__image-gen-mcp__generate_image(gpt-image-2,background: "transparent"pour les produits, jusqu'à3840x2160), ouedit_imagepour transformer une vraie photo produit en rendu stylisé. - Placeholder — seulement pour un battement que l'utilisateur a explicitement reporté, et il doit s'agir d'une composition intentionnelle de dégradé/typographie, jamais d'une boîte grise.
Pour un héros en séquence d'images (le style Apple « le produit explose pendant le scroll »), la chaîne est : première trame + dernière trame → vidéo interpolée → trames extraites → séquence WebP → canvas scrub. Gardez la séquence en dessous de 4 Mo au total, 36 à 60 trames, 1600px de large. Ce budget est la raison pour laquelle l'effet reste utilisable ; le dépasser est l'échec le plus courant de ce modèle.
Phase 4 — STRUCTURE
Stack par défaut, sauf si l'utilisateur en a nommé une : Vite + vanilla TS + GSAP. Il n'y a pas de cycle de vie de framework à combattre, et les bugs ScrollTrigger dans React sont presque toujours des bugs de nettoyage. N'utilisez Next.js/React que lorsque l'utilisateur le demande ou que le projet nécessite du routage, et alors utilisez useGSAP() pour le nettoyage — jamais de useEffect nu.
Le scroll fluide (Lenis) est OPTIONNEL — il ne fait plus partie de la stack par défaut. Ajoutez-le seulement lorsque l'utilisateur demande explicitement un scroll fluide ou inertiel par son nom. Il remplace le scroll natif par sa propre position animée, et quand il semble même légèrement faux, toute la page est perçue comme cassée — c'est la raison la plus courante pour laquelle une construction techniquement correcte est rejetée. Le scrub de ScrollTrigger vous donne déjà la sensation adoucie et cinématique que les gens entendent généralement par « fluide ». Voir references/08-failure-modes.md §1.
→ Lisez references/07-stack-setup.md pour les structures et les commandes exactes.
GSAP est 100% gratuit depuis la v3.13 (acquisition de Webflow), y compris SplitText, ScrollSmoother et MorphSVG. npm install gsap obtient tout — pas de clé de licence, pas de gsap-trial, pas de contournements de plugins CDN. Ne dites pas à l'utilisateur qu'un plugin est payant.
Le contenu vit dans src/content.ts, jamais en ligne dans le balisage. L'utilisateur doit pouvoir changer le texte sans toucher au code de mouvement.
Phase 5 — CONSTRUCTION
Implémentez chaque battement du Score en utilisant les implémentations de modèles canoniques :
→ Lisez references/03-pattern-library.md — 12 modèles, prêts à copier.
| Modèle | Utilisez-le pour |
|---|---|
reveal-on-enter | Entrées de sections standard, grilles de cartes |
text-reveal | Titres, citations (SplitText, masqué) |
pin-scrub | Le moment « wow » central — scène épinglée, chronologie déroulée |
parallax-layers | Profondeur : arrière-plans, accessoires de premier plan |
media-scrub-sequence | Révélation de produit à la Apple (canvas + trames) |
media-scrub-video | Même effet à partir d'un fichier vidéo (currentTime) |
horizontal-scroll | Portfolios, galeries, chronologies |
mask-reveal | Une image qui s'ouvre pour engloutir le viewport |
sticky-stack | Listes de fonctionnalités, cartes qui s'empilent |
scroll-progress | Barres de progression, compteurs, indicateurs de section |
theme-morph | Changement de fond/couleur entre les sections |
snap-sections | Pages de type deck, une section par scroll |
Et les règles GSAP non négociables :
→ Lisez references/04-gsap-rules.md avant d'écrire du code ScrollTrigger.
Les cinq qui cassent les constructions le plus souvent :
- Un ScrollTrigger par chronologie, sur la chronologie — jamais sur une animation enfant, jamais imbriqué dans une chronologie parente.
- Si — et seulement si — vous avez ajouté Lenis, il partage la boucle de GSAP.
lenis.on('scroll', ScrollTrigger.update)+gsap.ticker.add(t => lenis.raf(t * 1000))+gsap.ticker.lagSmoothing(0). N'ajoutez jamais de bouclerequestAnimationFrameséparée pour Lenis. ease: "none"sur toute animation pilotantcontainerAnimationou un media scrub.scruboutoggleActions, jamais les deux sur le même déclencheur.ScrollTrigger.refresh()après le chargement des polices et des images — pas seulement lors du redimensionnement.- Avant tout épingle, parcourez les ancêtres pour
transform/filter/contain. N'importe lequel d'entre eux casse silencieusementposition: fixed, donc l'épingle est créée, signalepin: true, et ne fait rien. Supprimez la propriété ou définissezpinType: 'transform'. Voir08-failure-modes.md§2.
Animez uniquement transform et opacity. Tout ce qui touche top, left, width, height ou margin au scroll fera perdre des images.
Phase 6 — VÉRIFICATION
Cette phase n'est pas optionnelle, et c'est ce qui distingue ce skill de l'écriture manuelle de GSAP. Les animations au scroll ne peuvent pas être vérifiées en lisant du code — les épingles s'effondrent, les déclencheurs s'activent à la mauvaise profondeur, et les trames disparaissent seulement dans un vrai navigateur avec un vrai viewport.
→ Lisez references/06-verification.md pour la boucle complète et la liste de contrôle.
→ Lisez references/08-failure-modes.md — les échecs qui passent toutes les vérifications automatisées. Lisez-le avant la Phase 4, pas après que quelque chose a cassé.
Démarrez le serveur de développement, puis pilotez-le avec Playwright MCP :
mcp__playwright__browser_navigate → l'URL du serveur de développement
mcp__playwright__browser_resize → 1440×900, puis 390×844
mcp__playwright__browser_evaluate → faites défiler en profondeur, lisez l'état
mcp__playwright__browser_take_screenshot → à chaque profondeur
mcp__playwright__browser_console_messages → erreurs et avertissements GSAP
mcp__playwright__browser_network_requests → 404, poids des assets
Parcourez 0 %, 15 %, 30 %, 50 %, 70 %, 85 %, 100 % de la hauteur de la page sur desktop et mobile. À chaque arrêt, prenez une capture d'écran et regardez-la. Vous vérifiez que la page a l'air correcte, pas seulement qu'elle n'a pas généré d'erreurs.
Pilotez la page avec une VRAIE entrée — mouse.wheel() ou des pressions de touches, jamais window.scrollTo. Le défilement synthétique est avalé par les bibliothèques de détournement de scroll, ce qui est précisément l'échec que vous devez détecter. Si trois crans de molette ne bougent pas la page, elle est cassée quoi que disent les assertions.
Échouez l'exécution et corrigez si l'une de ces conditions est vraie :
- Une erreur console, ou un avertissement
ScrollTrigger - Toute 404, ou le poids total des assets dépasse le budget
- Une capture d'écran vide/sans style à n'importe quelle profondeur
- Une section épinglée qui chevauche la section suivante, ou qui effondre la mise en page
- Du contenu qui ne devient jamais visible (une révélation qui ne se déclenche jamais)
- Un débordement horizontal à 390px de large
markers: truequi survit n'importe où dans le code source- Aucun fallback
prefers-reduced-motion - Trois vrais crans de molette ne déplacent pas visiblement la page
- Un épingle dont la scène suit toujours le scroll (vérifiez
|rect.top| < 10dans la plage) - Un media déroulé qui atteint sa fin avant ~90% de son épingle
- Plus de ~40 crans de molette pour atteindre l'appel à l'action principal
Répétez correction → revérification jusqu'à propreté, jusqu'à 5 tours. Si quelque chose échoue encore après 5 tours, livrez le reste, désactivez ce battement derrière un indicateur, et dites-le clairement dans le rapport final. Ne signalez jamais un succès sur une page non vérifiée.
Définition de terminé
-
scroll-score.jsoncorrespond à ce qui a été réellement construit - Chaque battement vérifié sur desktop et mobile
- Zéro erreur console, zéro 404
-
prefers-reduced-motionse dégrade en états instantanés, aucun mouvement - Sanité de type Lighthouse : pas de changement de mise en page dû aux épingles, images dimensionnées
-
README.md— comment exécuter, où se trouve le contenu, comment échanger les assets -
DECISIONS.md— hypothèses faites après la fermeture de l'assistant - Message final : ce qui a été construit, ce qui a été supposé, quoi réviser
Ne faites pas
- ❌ Ne posez pas de questions après la fermeture de l'assistant — supposez, enregistrez et rapportez à la place
- ❌ Ne signalez pas terminé sans avoir exécuté la Phase 6 dans un vrai navigateur
- ❌ Ne livrez pas
markers: true,console.logou unTODOdans le code livré - ❌ N'utilisez pas
gsap-trialet ne prétendez pas que SplitText/ScrollSmoother nécessitent une licence Club - ❌ N'animez pas les propriétés de mise en page au scroll
- ❌ N'épinglez pas sur mobile sans le vérifier — préférez l'apparition progressive en dessous de 768px
- ❌ Ne dépassez pas le budget d'assets pour une séquence héros