Communitygithub.com

erlinerd/erlin-skills

Introduit la bibliothèque d'animations motion dans un site Next.js/React, migre depuis framer-motion, et met en place des animations de défilement, grilles stagger, transitions de page et animations de navigation.

Qu'est-ce que erlin-skills ?

Cette compétence est conçue pour les agents d'IA qui travaillent sur des projets Next.js/React, en leur fournissant une méthodologie éprouvée pour intégrer la bibliothèque d'animations `motion` (anciennement framer-motion). Elle gère la migration automatique des imports, l'installation des dépendances avec le bon gestionnaire de paquets, et le placement précis des animations (défilement, stagger, transitions de route, navigation). Un point clé est la robustesse : elle intègre un mécanisme de secours de visibilité (IntersectionObserver avec timeout) pour éviter que les animations ne masquent le contenu, comme dans le cas où `whileInView` peut laisser des cartes en `opacity:0`. La compétence analyse l'environnement (package manager, version de Next/React, structure de routage) avant toute modification, et respecte strictement les règles d'accessibilité (réduire les animations, ne pas animer les éléments LCP). Elle ne couvre pas les animations SwiftUI, CSS-only ou Remotion.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/erlinerd/erlin-skills/tree/HEAD/skills/web/erlin-web-motion

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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

  1. 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.lock ou bun.lockb → bun. En cas de multiples lockfiles, stopper et demander à l'utilisateur ; s'il n'y a pas de lockfile, lire le champ packageManager dans package.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 ; seulement pages/ → Pages Router, pas de mécanisme template.tsx, modifier dans pages/_app.tsx ou 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 (dossier app/[locale]/), placer le template dans app/[locale]/template.tsx ; pas de route locale (ex. changement de langue côté client) → placer dans app/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 motion né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.
  2. Conserver les dépendances existantes : si framer-motion est 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, installer motion avec le gestionnaire de paquets du projet, vérifier import par import les API de motion/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.

  3. Mettre en place les animations : se référer à Reveal si besoin : le modèle se trouve dans assets/reveal.tsx, le copier dans components/motion/reveal.tsx et 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 whileInView dé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-motion et 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 via useEffect ; 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 de motion.div, zéro surcoût d'exécution d'animations.
    • Reveal possède une prop className : les cartes qui sont des div (ex. cartes glass) passent directement leur classe à Reveal pour éviter une imbrication supplémentaire ; les éléments sémantiques comme article/section sont encapsulés par Reveal pour préserver la sémantique.
  4. Emplacements d'application et formule de stagger :

    EmplacementMéthodedelay
    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 grilles
    Liste 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 listes
    Colonne de texte des lignes de grandes images de projetRevealFixe 0.15, pour décaler avec l'image
    Carte de texte principal/contact (about)Grand bloc RevealSecond bloc 0.1
    Barre de navigationmotion.header initial y:"-100%" glissement vers le bas, masquage au scroll en réutilisant la même transform—
    Menu mobileAnimatePresence + transition opacity/y, remplace le basculement block/hidden—
    Changement de routeCréer app/template.tsx (sans route locale) ou app/[locale]/template.tsx (avec préfixe locale ; Next remonte le template à chaque navigation) pour un fondu opacity+y, 0,35 s—
  5. 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 npm
    

    Uniquement 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-motion vers motion (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) : SkewReveal a une prop instant, ou l'état initial est directement l'état final, sinon le texte SSR scintillerait.
    • Toutes les animations respectent prefers-reduced-motion : utiliser useReducedMotion(), 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.
  • 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/.agents pour 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 depuis assets/reveal.tsx vers components/motion/reveal.tsx et adapter les alias de chemin.
  • Transition de route : app/template.tsx (sans route locale) ou app/[locale]/template.tsx (avec préfixe locale), fondu opacity+y 0,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 ; Reveal et 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 && build avec le gestionnaire de paquets confirmé, le build doit 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é.

Skills associés