Communitygithub.com

gsap-motion

Arquitectura de animación GSAP 3 para sitios web premium: registro de plugins (ScrollTrigger, SplitText, Flip, Observer, Draggable, Inertia, CustomEase, MorphSVG, DrawSVG — todos gratuitos en el paquete público de gsap), integración con React mediante useGSAP con ámbito y limpieza, gsap.matchMedia para ramas responsivas y de movimiento reducido, líneas de tiempo, secuencias con pin y scroll sincronizado, revelaciones de texto, transiciones de clip-path/máscara, morphs de diseño con Flip, scroll horizontal, parallax, efectos magnéticos/de cursor y transiciones de página. Úsalo para cualquier trabajo con GSAP o ScrollTrigger, cualquier animación impulsada por scroll o cinematográfica, y cuando las animaciones tengan fugas, se dupliquen, entrecorten o se rompan tras cambios de ruta o de tamaño de ventana.

¿Qué es gsap-motion?

Este skill proporciona una arquitectura completa y probada para trabajar con GSAP 3 en proyectos React. Su objetivo principal es eliminar los bugs más comunes de GSAP en React (fugas de memoria, animaciones duplicadas, problemas con ScrollTrigger tras cambios de ruta o de tamaño) mediante un conjunto de reglas estrictas y patrones reutilizables. La arquitectura incluye un registro centralizado de plugins, tokens de animación que respetan `prefers-reduced-motion`, hooks para detección en vivo de movimiento reducido y ejemplos prácticos de componentes (secuencias con pin, morphs con Flip, interactividad con `quickTo`, revelaciones al hacer scroll, transiciones de ruta). El skill estandariza el uso de `useGSAP` con ámbito de ref para garantizar la limpieza automática de todas las animaciones al desmontar el componente, prohíbe la creación de ScrollTriggers en ámbito de módulo y promueve el uso de `gsap.matchMedia()` para manejar condiciones responsivas y de accesibilidad. Está diseñado para plataformas como Claude Code, Cursor y Codex, y su documentación incluye recetas para una amplia variedad de efectos (héroe cinematográfico, parallax, galerías con Draggable, botones magnéticos, transiciones SVG) y una lista de verificación para asegurar que cada animación tenga un propósito comunicativo claro.

Compatible con~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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Arquitectura de animación GSAP

Línea base verificada (2026-11-15)

  • [email protected] es la versión más reciente en npm. Su campo de licencia es "Licencia estándar 'sin cargo'" (gsap.com/standard-license): gratuita para sitios comerciales, incluido el trabajo para clientes. El único uso prohibido es la creación de herramientas visuales de construcción de animaciones sin código que compitan con Webflow. Todos los plugins se incluyen en el paquete público: ScrollTrigger, ScrollSmoother, SplitText, Flip, Observer, Draggable, InertiaPlugin, CustomEase, CustomBounce, CustomWiggle, MorphSVGPlugin, DrawSVGPlugin, MotionPathPlugin, ScrambleTextPlugin, ScrollToPlugin, Physics2D, PhysicsProps, GSDevTools y muchos más.
  • @gsap/[email protected] proporciona useGSAP.
  • Vuelve a comprobar antes de un nuevo proyecto: npm view gsap version license y ls node_modules/gsap/*.js.
  • Usa ScrollSmoother o Lenis, nunca ambos. Este estudio estandariza en Lenis (skill lenis-scroll).

Arquitectura (copia assets/ en src/motion/)

ArchivoRol
assets/registry.tsRegistra los plugins una vez, crea los CustomEases del proyecto, establece valores predeterminados, ScrollTrigger.config({ ignoreMobileResize: true }). Todo importa gsap desde aquí.
assets/tokens.tsTokens de animación (duraciones, easing, staggers) reflejados desde ANIMATION_SPECIFICATION.md + prefersReducedMotion()
assets/lit.tsEjemplo de primitiva de texto reutilizable: SplitText con aria:'auto', autoSplit y onSplit que devuelve el tween. Adapta la revelación a la marca (lit, enmascarado, deslizado…).
assets/useReducedMotion.tsHook en vivo de prefers-reduced-motion para cambios a nivel de DOM (por ejemplo, renderizar pasos estáticos en lugar de un pin)
assets/examples/*.tsxPatrones probados de la demo de referencia: secuencia con pin y scroll (Method), filtro con Flip (ScheduleIndex), interactividad con quickTo (TheHour), revelaciones al hacer scroll (Rooms), cortina de transición de ruta (Router)

Estos archivos son la implementación verificada de demo/ en este repositorio, ejercitada por su suite de Playwright (limpieza entre rutas, movimiento reducido, sincronización de scroll).

Reglas que previenen el 90% de los bugs de GSAP en React

  1. Cada animación vive dentro de useGSAP(() => {...}, { scope: ref }). El contexto revierte todos los tweens, ScrollTriggers, SplitTexts y ramas de matchMedia al desmontar. Las animaciones en manejadores de eventos usan contextSafe.
  2. Nunca crees ScrollTriggers en el ámbito del módulo ni en useEffect simple sin revertirlos. Nunca llames a ScrollTrigger.killAll() como estrategia de limpieza.
  3. Un gsap.matchMedia() por sección con condiciones motion/reduce (y desktop/mobile). Los estados ocultos iniciales se establecen dentro de la rama de movimiento, para que los usuarios sin JavaScript y con movimiento reducido vean el contenido final.
  4. Seguro con Strict Mode: useGSAP maneja la doble invocación de React 18/19. Verifica con una comprobación de fugas: ScrollTrigger.getAll().length vuelve al valor base después de navegar a otra ruta y regresar.
  5. Refrescar tras cambios de diseño: después de que las fuentes carguen (document.fonts.ready.then(() => ScrollTrigger.refresh())), después de filtrar listas y después de que el contenido de la ruta se monte. invalidateOnRefresh: true en cualquier trigger cuyos valores se calculen a partir del diseño.
  6. Fijar correctamente: fija un envoltorio interno, mantén pinSpacing, asígnale un min-height: 100svh que no dependa de webfonts y usa anticipatePin: 1 con Lenis. Usa un pin por experiencia; los pines apilados confunden a los usuarios.
  7. Anima propiedades económicas: transform, opacity, clip-path; variables CSS solo en subárboles pequeños. Evita width/height/top/left en líneas de tiempo con scroll, y lee el diseño antes de escribir (GSAP agrupa sus propias escrituras).
  8. will-change solo mientras se anima, y solo en unas pocas capas.

Recetas

references/recipes.md contiene patrones probados o documentados para: secuencia heroica cinematográfica, revelaciones con SplitText (caracteres/palabras/líneas, enmascaradas), transiciones de clip-path y máscara, narrativa con pin y scroll, sección de scroll horizontal (containerAnimation), capas de parallax, morphs de estado con Flip, secciones gestuales con Observer, carruseles con Draggable + Inertia, botones magnéticos, seguidores de cursor, morph/dibujo SVG, distorsión de imagen transferida a WebGL, transiciones de página y scroll 3D con cámara WebGL.

references/react-lifecycle.md cubre cambios de ruta, cambio de tamaño de ventana, cambios de contenido y depuración de fugas.

Lista de verificación de movimiento con propósito (antes de animar)

  • ¿Qué comunica esta animación (jerarquía, causalidad, estado, material de marca)? Si no comunica nada, elimínala.
  • ¿Es el momento emblemático o debería permanecer discreta?
  • ¿Qué muestra la versión de movimiento reducido? (Debe seguir siendo completamente comprensible).
  • ¿Cuál es la expresión móvil? (Los efectos hover necesitan una alternativa táctil; los pines se acortan).
  • ¿Cuántos ScrollTriggers crea la página? Escribe el inventario en la especificación para que QA pueda verificarlo.

Skills relacionados