Communitygithub.com

gsap-motion

Architecture d'animation GSAP 3 pour sites premium — registre de plugins (ScrollTrigger, SplitText, Flip, Observer, Draggable, Inertia, CustomEase, MorphSVG, DrawSVG — tous gratuits dans le package public gsap), intégration React avec useGSAP pour le scoping et le nettoyage, gsap.matchMedia pour les branches réactives et préférant les mouvements réduits, timelines, séquences épinglées avec défilement synchronisé, révélations de texte, transitions clip-path/masque, morphing de mise en page Flip, défilement horizontal, parallaxe, effets magnétiques/curseur et transitions de page. À utiliser pour tout travail GSAP ou ScrollTrigger, toute animation pilotée par le défilement ou cinématique, et chaque fois que des animations fuient, se dupliquent, saccadent ou se brisent après des changements de route ou de redimensionnement.

Qu'est-ce que gsap-motion ?

Cette compétence fournit une architecture d'animation GSAP 3 robuste et testée pour les applications React, conçue pour éviter les bugs courants de GSAP dans React (fuites, duplication, saccades après changement de route ou redimensionnement). Elle inclut un registre de plugins centralisé (tous les plugins GSAP sont gratuits, y compris ScrollTrigger, SplitText, Flip, etc.), des tokens de mouvement, un hook React pour les préférences de mouvement réduit, et des composants d'exemple prêts à l'emploi. Les règles fondamentales (8 règles) préviennent 90% des bugs : utiliser `useGSAP` avec un scope ref, ne jamais créer de ScrollTrigger en dehors de ce contexte, utiliser `gsap.matchMedia` pour les branches réduites/responsives, et respecter les bonnes pratiques de performance (animer des propriétés légères, ne pas utiliser `will-change` en permanence). La compétence supporte les plateformes React (avec `@gsap/react`) et standardise sur Lenis pour le défilement fluide (à utiliser avec `lenis-scroll`). Elle inclut des recettes pour les séquences héroïques cinématiques, les révélations de texte, le défilement horizontal, les transitions de page et bien d'autres motifs d'animation.

Compatible avec~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/jakyherr05-hash/Claude-code-skill/tree/HEAD/plugins/premium-web-studio/skills/gsap-motion

Demander à votre IA préférée

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

Documentation

Architecture d'animation GSAP

Référence vérifiée (2026-11-15)

  • [email protected] est la dernière version sur npm. Son champ licence est "Standard 'no charge' license" (gsap.com/standard-license) : gratuit pour les sites commerciaux, y compris le travail client. La seule utilisation interdite est la création d'outils visuels de construction d'animations sans code qui concurrencent Webflow. Tous les plugins sont livrés dans le package public : ScrollTrigger, ScrollSmoother, SplitText, Flip, Observer, Draggable, InertiaPlugin, CustomEase, CustomBounce, CustomWiggle, MorphSVGPlugin, DrawSVGPlugin, MotionPathPlugin, ScrambleTextPlugin, ScrollToPlugin, Physics2D, PhysicsProps, GSDevTools, et plus encore.
  • @gsap/[email protected] fournit useGSAP.
  • Re-vérifier avant un nouveau projet : npm view gsap version license et ls node_modules/gsap/*.js.
  • Utiliser ScrollSmoother ou Lenis, jamais les deux. Ce studio standardise sur Lenis (compétence lenis-scroll).

Architecture (copier assets/ dans src/motion/)

FichierRôle
assets/registry.tsEnregistre les plugins une fois, crée les CustomEases du projet, définit les valeurs par défaut, ScrollTrigger.config({ ignoreMobileResize: true }). Tout importe gsap depuis ici.
assets/tokens.tsJetons de mouvement (durées, eases, staggers) reflétés depuis ANIMATION_SPECIFICATION.md + prefersReducedMotion()
assets/lit.tsExemple de primitive de texte réutilisable : SplitText avec aria:'auto', autoSplit et onSplit retournant le tween. Adapter la révélation à la marque (lit, masqué, glissé…).
assets/useReducedMotion.tsHook en direct pour prefers-reduced-motion afin de basculer au niveau du DOM (ex : afficher des étapes statiques au lieu d'un épingle)
assets/examples/*.tsxMotifs testés de la démo de référence : séquence épinglée avec défilement synchronisé (Method), filtre Flip (ScheduleIndex), interaction pilotée par quickTo (TheHour), révélations à vue unique (Rooms), voile de transition de route (Router)

Ces fichiers sont l'implémentation vérifiée de demo/ dans ce dépôt, testée par sa suite Playwright (nettoyage entre les routes, mouvement réduit, synchronisation du défilement).

Règles qui préviennent 90% des bugs GSAP dans React

  1. Chaque animation vit à l'intérieur de useGSAP(() => {...}, { scope: ref }). Le contexte annule tous les tweens, ScrollTriggers, SplitTexts et branches matchMedia lors du démontage. Les animations de gestionnaires d'événements utilisent contextSafe.
  2. Ne jamais créer de ScrollTriggers à la portée du module ou dans un simple useEffect sans les annuler. Ne jamais appeler ScrollTrigger.killAll() comme stratégie de nettoyage.
  3. Un gsap.matchMedia() par section avec les conditions motion/reduce (et desktop/mobile). Les états cachés initiaux sont définis à l'intérieur de la branche motion, de sorte que les utilisateurs sans JS et avec mouvement réduit voient le contenu final.
  4. Sûr pour le mode strict : useGSAP gère la double invocation de React 18/19. Vérifier avec un test de fuite : ScrollTrigger.getAll().length revient à la valeur initiale après avoir navigué ailleurs et revenu.
  5. Rafraîchir après les changements de mise en page : après le chargement des polices (document.fonts.ready.then(() => ScrollTrigger.refresh())), après le filtrage des listes, et après le montage du contenu de la route. invalidateOnRefresh: true sur tout déclencheur dont les valeurs sont calculées à partir de la mise en page.
  6. Épingler correctement : épingler un wrapper intérieur, garder pinSpacing, lui donner un min-height: 100svh qui ne dépend pas des polices web, et utiliser anticipatePin: 1 avec Lenis. Utiliser un seul épingle par expérience ; les épingles empilées déroutent les utilisateurs.
  7. Animer des propriétés légères : transform, opacity, clip-path ; les variables CSS uniquement sur de petits sous-arbres. Éviter width/height/top/left dans les timelines synchronisées au défilement, et lire la mise en page avant d'écrire (GSAP regroupe ses propres écritures).
  8. will-change uniquement pendant l'animation, et seulement sur quelques couches.

Recettes

references/recipes.md contient des motifs testés ou documentés pour : séquence héroïque cinématique, révélations SplitText (caractères/mots/lignes, masqués), transitions clip-path et masque, narration épinglée avec défilement, section à défilement horizontal (containerAnimation), couches de parallaxe, morphismes d'état Flip, sections gestuelles pilotées par Observer, carrousels Draggable + Inertia, boutons magnétiques, suiveurs de curseur, morph/dessin SVG, distorsion d'image transmise à WebGL, transitions de page, et défilement 3D avec une caméra WebGL.

references/react-lifecycle.md couvre les changements de route, le redimensionnement, les changements de contenu et le débogage des fuites.

Liste de vérification pour un mouvement intentionnel (avant d'animer)

  • Que communique cette animation (hiérarchie, causalité, état, matériau de marque) ? Si rien, supprimez-la.
  • Est-ce le moment signature, ou doit-elle rester discrète ?
  • Que montre la version à mouvement réduit à la place ? (Elle doit rester parfaitement compréhensible.)
  • Quelle est l'expression mobile ? (Les effets de survol nécessitent une alternative tactile ; les épingles sont plus courtes.)
  • Combien de ScrollTriggers la page crée-t-elle ? Écrire l'inventaire dans le cahier des charges pour que le QA puisse l'asserter.

Skills associés