Objectif
Méthodologie d'animations pour le site personnel d'Erlin : introduire la bibliothèque d'animations motion sur un site Next.js/React, migrer les imports depuis framer-motion, mettre en place les animations de défilement, les grilles stagger, les transitions de page et les animations de navigation, tout en ne faisant jamais disparaître le contenu à cause des animations. Leçon clé : whileInView a déjà laissé les cartes de projet de la page d'accueil bloquées à opacity:0 ("les cartes de projet ont disparu"). Un mécanisme de secours de visibilité est donc nécessaire ; les implémentations existantes fiables peuvent être conservées, Reveal est une référence optionnelle, et whileInView n'est pas totalement interdit.
Étapes d'exécution
-
Analyser d'abord l'environnement du projet (prendre 30 secondes avant d'agir pour éviter d'appliquer le mauvais modèle) :
- Gestionnaire de paquets : ne reconnaître qu'un seul lockfile :
pnpm-lock.yaml→ pnpm,package-lock.json→ npm,yarn.lock→ yarn,bun.lockoubun.lockb→ bun. En cas de multiples lockfiles, stopper et demander à l'utilisateur ; s'il n'y a pas de lockfile, lire le champpackageManagerdanspackage.json, si impossible à déterminer, stopper sans deviner. Les commandes d'installation, migration, lint, build suivront le gestionnaire identifié. - Version de Next/React : vérifier les versions réelles de Next/React et de la bibliothèque d'animations, leurs dépendances (peer dependencies) et les notes de compatibilité officielles ; ne pas coder en dur les versions ni affirmer une compatibilité totale entre versions.
- Structure de routage (avant de choisir un template, ne pas supposer App Router par défaut) : présence d'un dossier
app/→ App Router, suivre les règles ci-dessous pour le template ; seulementpages/→ Pages Router, pas de mécanismetemplate.tsx, modifier danspages/_app.tsxou le composant de page cible pour la transition, en expliquant la différence à l'utilisateur ; ni l'un ni l'autre → projet non Next, implémenter selon le point de montage du framework. App Router : si les routes sont préfixées par locale (dossierapp/[locale]/), placer le template dansapp/[locale]/template.tsx; pas de route locale (ex. changement de langue côté client) → placer dansapp/template.tsx, Next remonte également le template à chaque navigation, la fondu se produit normalement. - Le composant est-il actuellement un composant serveur ? : les éléments
motionnécessitant des interactions doivent être isolés dans le plus petit composant client ; ne pas transformer en client un composant entier contenant de la logique serveur.
- Gestionnaire de paquets : ne reconnaître qu'un seul lockfile :
-
Conserver les dépendances existantes : si
framer-motionest déjà présent et répond aux besoins, continuer à l'utiliser ; ne pas migrer par défaut pour ajouter des animations. Migrer seulement si l'utilisateur le demande ou si les capacités/compatibilité actuelles le justifient vraiment, après vérification des différences de version, installermotionavec le gestionnaire de paquets du projet, vérifier import par import les API demotion/react; retirer l'ancien paquet seulement après confirmation qu'il n'y a plus de dépendances résiduelles. Ne pas modifier des commentaires ou de la documentation non pertinents. -
Mettre en place les animations : se référer à Reveal si besoin : le modèle se trouve dans
assets/reveal.tsx, le copier danscomponents/motion/reveal.tsxet adapter les alias de chemin. Points de conception (à adapter selon le projet) :- Mécanisme de secours de visibilité : le modèle utilise IntersectionObserver + délai de 2,5 secondes ; 2,5 secondes est un paramètre de référence, à ajuster selon la page et le comportement de chargement. On peut utiliser
whileInViewdéjà validé ou d'autres mécanismes, pour garantir que le contenu reste accessible en cas d'échec de l'observer, du JS ou de l'hydration. - Gérer
prefers-reduced-motionet l'absence d'observer selon les règles SSR/hydration et de lint du projet ; éviter les incohérences d'hydration et les mises à jour synchrones inutiles viauseEffect; ne pas prendre une seule expérience de lint comme une interdiction générale de toutes les API. - En cas de
prefers-reduced-motion, rendre directement l'état final. - Utiliser une transition CSS pure (
cubic-bezier(0.22,1,0.36,1)), pas demotion.div, zéro surcoût d'exécution d'animations. Revealpossède une propclassName: les cartes qui sont desdiv(ex. cartesglass) passent directement leur classe àRevealpour éviter une imbrication supplémentaire ; les éléments sémantiques commearticle/sectionsont encapsulés parRevealpour préserver la sémantique.
- Mécanisme de secours de visibilité : le modèle utilise IntersectionObserver + délai de 2,5 secondes ; 2,5 secondes est un paramètre de référence, à ajuster selon la page et le comportement de chargement. On peut utiliser
-
Emplacements d'application et formule de stagger :
Emplacement Méthode delay Grille de cartes (plusieurs blocs sur la page d'accueil) Chaque élément encapsulé dans RevealMath.min(i * 0.08, 0.4), plafonné pour éviter la lenteur sur les longues grillesListe d'articles (writing, latest-writing) Chaque ligne encapsulée dans Reveali * 0.05~0.07, plafonné àMath.min(i*0.05, 0.3)pour éviter la lenteur sur les longues listesColonne de texte des lignes de grandes images de projet RevealFixe 0.15, pour décaler avec l'imageCarte de texte principal/contact (about) Grand bloc RevealSecond bloc 0.1Barre de navigation motion.headerinitialy:"-100%"glissement vers le bas, masquage au scroll en réutilisant la même transform— Menu mobile AnimatePresence+ transitionopacity/y, remplace le basculementblock/hidden— Changement de route Créer app/template.tsx(sans route locale) ouapp/[locale]/template.tsx(avec préfixe locale ; Next remonte le template à chaque navigation) pour un fonduopacity+y, 0,35 s— -
Validation et livraison : avec le gestionnaire de paquets confirmé à l'étape 1 :
pnpm lint && pnpm build # projet pnpm ; build doit réussir (projet SSG complet avec export SSG) npm run lint && npm run build # projet npmUniquement si l'utilisateur autorise le commit, suivre la convention de commit du projet, ex. :
feat(motion): migration vers motion et ajout d'animations globales. N'ajouter que les fichiers liés à cette tâche — si le dépôt contient des modifications non liées non commitées, ne pas les inclure dans ce commit.
Règles de décision
- Quand utiliser : ajouter des animations/effets à un site Next.js ; migrer de
framer-motionversmotion(vérifier les API de la version actuelle avant la migration) ; l'utilisateur demande "défilement", "stagger", "transition de page", "plus d'animations". - Ne pas couvrir : les animations SwiftUI, CSS-only ou Remotion (vidéo).
- Règles de conception d'animations (résumé des erreurs) :
- Ne pas animer les éléments LCP (H1, hero) :
SkewReveala une propinstant, ou l'état initial est directement l'état final, sinon le texte SSR scintillerait. - Toutes les animations respectent
prefers-reduced-motion: utiliseruseReducedMotion(), en mode réduit rendre l'état final / ne pas enregistrer d'écouteurs. - Easing uniforme
[0.22, 1, 0.36, 1](style easeOutQuint), durée 0,3–0,8 s, priorité à la retenue. - Les animations au survol utilisent une transition CSS (ex.
hover:-translate-y-1,group-hover:scale-105), pas besoin de motion. - Lors d'un filtrage côté client (ex. par tag), les éléments de liste dont la clé ne change pas ne rejouent pas l'animation — c'est un comportement attendu, les nouveaux éléments se déclenchent automatiquement.
- Ne pas animer les éléments LCP (H1, hero) :
- Appartenance des composants existants : conserver
SkewReveal(entrée),Parallax,Magnetic,MouseParallax; les nouvelles animations coexistent dans le même répertoire. Si le projet a déjà un dossier.zcode/.agentspour les composants d'animations (ex.components/motion/), placer les nouveaux composants dans ce dossier. - Frontière serveur/client : un composant serveur peut directement rendre
Reveal(c'est un composant client, utilisable comme enfant sans problème).
Avant de finaliser les animations, vérifier visuellement l'accessibilité et la visibilité du contenu ; ce skill gère l'implémentation technique de motion pour Next.js/React ; les animations pour RN/Expo ou d'autres stacks sont implémentées directement selon les mêmes principes, sans dépendre de ce skill.
Format de sortie
- Placement du composant
Reveal: copier depuisassets/reveal.tsxverscomponents/motion/reveal.tsxet adapter les alias de chemin. - Transition de route :
app/template.tsx(sans route locale) ouapp/[locale]/template.tsx(avec préfixe locale), fonduopacity+y0,35 s. - Message de commit : conventional commits + description en français, ex. :
feat(motion): migration vers motion et ajout d'animations globales.
Exemple
Question de l'utilisateur
"Ajouter le défilement au site et en profiter pour remplacer framer-motion par motion."
Réponse de l'outil
pnpm
pnpm add motion && pnpm remove framer-motion réussi, package.json affiche une version compatible de motion ; pnpm lint && pnpm build pour le SSG complet reste réussi.
sed
sed -i '' 's/from "framer-motion"/from "motion\/react"/g' <fichiers> exécuté, tous les imports pointent vers motion/react ; seuls les commentaires obsolètes liés à cette migration sont mis à jour.
Sortie finale
components/motion/reveal.tsx (IntersectionObserver manuel + fusible de 2,5 s) + stagger cartes/listes + app/template.tsx fondu de route ; lint et build passent ; rapport de vérification réelle ; ne commiter que les fichiers liés à cette tâche si autorisation de commit existante.
Garde-fous
- Ligne rouge sur le contenu : ne jamais faire disparaître le contenu à cause des animations — vérifier que le contenu est accessible en mode SSR, reduced-motion, et en cas d'échec de l'observer/script ;
Revealet le paramètre de délai sont une implémentation de référence, ne pas interdire mécaniquement les API. - Ligne rouge sur l'accessibilité : toutes les animations respectent
prefers-reduced-motion; les éléments LCP (H1, hero) ne sont pas animés à l'entrée. - Validation : exécuter
lint && buildavec le gestionnaire de paquets confirmé, lebuilddoit rester réussi (si le projet est un SSG complet, l'export SSG ne doit pas être cassé ; pour les projets SSR/ISR, seul le succès du build compte, ne pas inventer d'exigence SSG). - Discipline de commit : n'ajouter que les fichiers liés à cette tâche, ne pas inclure dans le commit des modifications non liées non commitées du dépôt.
- Amélioration progressive : ne pas modifier les composants d'animation qui fonctionnent déjà pour "uniformiser le style", décider en fonction des besoins et des preuves d'accessibilité.