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]proporcionauseGSAP.- Vuelve a comprobar antes de un nuevo proyecto:
npm view gsap version licenseyls node_modules/gsap/*.js. - Usa ScrollSmoother o Lenis, nunca ambos. Este estudio estandariza en Lenis (skill
lenis-scroll).
Arquitectura (copia assets/ en src/motion/)
| Archivo | Rol |
|---|---|
assets/registry.ts | Registra los plugins una vez, crea los CustomEases del proyecto, establece valores predeterminados, ScrollTrigger.config({ ignoreMobileResize: true }). Todo importa gsap desde aquí. |
assets/tokens.ts | Tokens de animación (duraciones, easing, staggers) reflejados desde ANIMATION_SPECIFICATION.md + prefersReducedMotion() |
assets/lit.ts | Ejemplo 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.ts | Hook 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/*.tsx | Patrones 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
- 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 usancontextSafe. - Nunca crees ScrollTriggers en el ámbito del módulo ni en
useEffectsimple sin revertirlos. Nunca llames aScrollTrigger.killAll()como estrategia de limpieza. - Un
gsap.matchMedia()por sección con condicionesmotion/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. - Seguro con Strict Mode:
useGSAPmaneja la doble invocación de React 18/19. Verifica con una comprobación de fugas:ScrollTrigger.getAll().lengthvuelve al valor base después de navegar a otra ruta y regresar. - 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: trueen cualquier trigger cuyos valores se calculen a partir del diseño. - Fijar correctamente: fija un envoltorio interno, mantén
pinSpacing, asígnale unmin-height: 100svhque no dependa de webfonts y usaanticipatePin: 1con Lenis. Usa un pin por experiencia; los pines apilados confunden a los usuarios. - 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).
will-changesolo 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.