ElvinEga/skills

Animación por Scroll

Un enrutador hacia diez patrones de animación por scroll. Todos los patrones, excepto JOS, están construidos sobre los mismos primitivos de React + Framer Motion — useScroll + useTransform (+ useSpring para suavizado) — así que lee este archivo primero para obtener el modelo mental compartido, luego carga solo el/los archivo(s) de referencia que coincidan con lo que el usuario quiere.

Modelo Mental Compartido (Patrones de Framer Motion)

Casi todos los efectos en este skill siguen el mismo esqueleto:

import { motion, useScroll, useSpring, useTransform } from "framer-motion";
import { useRef } from "react";

const containerRef = useRef<HTMLDivElement>(null);

const { scrollYProgress } = useScroll({
  target: containerRef,
  offset: ["start start", "end end"],
});

const smoothProgress = useSpring(scrollYProgress, {
  damping: 25,     // 20–30: más alto = menos rebote
  stiffness: 200,  // 150–300: más alto = más rápido
  mass: 0.5,       // 0.5–0.8: más bajo = más ligero/rápido
});

const someValue = useTransform(smoothProgress, [0, 1], [valorInicio, valorFin]);

• La altura del contenedor controla velocidad/dramatismo. Más vh = más lento, más cinematográfico. Rango típico: 150vh (rápido) a 400vh (meditativo).
• position: sticky; top: 0 fija el contenido al viewport mientras el contenedor alto proporciona espacio de scroll para animar.
• Siempre envuelve el scrollYProgress crudo en useSpring — sin él, el movimiento se siente robótico/lineal en lugar de físico.
• Efectos con múltiples elementos (pilas, cuadrículas, orbitadores) le dan a cada elemento una ventana: start = índice / total, end = start + 1 / total, luego mapea [start, end] (o una curva de campana de 5 puntos para efectos con punto máximo en el medio) a las transformaciones de ese elemento.
• Respeta prefers-reduced-motion: recurre a un diseño estático o un fade simple para los usuarios que lo soliciten.

Elegir un Patrón — Guía de Selección

Lee el archivo de referencia correspondiente en references/ para el código completo del componente, variantes, reglas críticas y tabla de resolución de problemas. No adivines los valores de transformación de memoria — los archivos de referencia tienen números ajustados y funcionales.

El usuario pide...	Lee esta referencia
Tarjetas apilándose / pegándose al hacer scroll, genérico "tarjetas apiladas", pila con inclinación 3D, pila multicapa, pila de tarjetas horizontal	references/scroll-stack.md
Específicamente estilo "Chronos" de apilamiento, recesión cinematográfica agresiva con crecimiento de sombra/radio	references/chronos-scroll-stack.md
Capas de profundidad a múltiples velocidades, fondo/primer plano moviéndose a diferentes velocidades, paralaje "alucinante"/dramático, formas decorativas flotantes	references/insane-parallax.md
Zoom hero tipo Apple sobre una imagen, desenfoque de cambio de enfoque, revelaciones de texto en capas sobre una imagen que se acerca, zoom de lanzamiento de producto cinematográfico	references/immersive-scroll-zoom.md
Imágenes de galería que se acercan al entrar en vista, zoom de punto focal de producto, cuadrícula de imágenes con escala controlada por scroll	references/image-zoom-scrolling.md
División de imagen en mitades/cuadrantes y separación, fragmentación diagonal, revelación estilo portafolio de agencia con inclinación 3D	references/image-split-3d.md
Elementos en órbita, anillos de progreso circulares, galerías radiales/espirales, texto siguiendo una trayectoria circular	references/circular-scroll.md
Tarjetas/azulejos que crecen/escalan al activarse, expansión de cuadrícula en curva de campana, mampostería con clic para expandir	references/expanding-cards-scroll.md
Reproducción cuadro por cuadro, "flipbook" de scroll, secuencias de imágenes en canvas, video de presentación de producto vinculado a la posición del scroll	references/scroll-image-sequences.md
Revelaciones simples de fade/slide/zoom-in, revelaciones escalonadas, SIN usar React/Framer Motion, o explícitamente "JOS"	references/jos-animation.md

Si la solicitud es ambigua o podría encajar en varios patrones (ej. "hacer el héroe más dinámico al hacer scroll"), prefiere insane-parallax.md o immersive-scroll-zoom.md para secciones de héroe, y pregunta solo si realmente no está claro — de lo contrario, elige la coincidencia más cercana y anota la suposición.

Reglas Transversales (aplican independientemente del patrón)

• Solo Framer Motion para cada patrón excepto JOS — nada de GSAP, nada de código vanilla de escucha de scroll, a menos que el usuario solicite explícitamente una implementación sin Framer Motion.
• Valores por defecto de Spring que funcionan bien en casi todas partes: damping: 20–30, stiffness: 150–300, mass: 0.5–0.8. Cada archivo de referencia proporciona los valores ajustados exactos para ese patrón — usa esos por encima de estos valores generales cuando difieran.
• willChange: "transform, opacity" en elementos animados para mantener las cosas en el hilo del compositor.
• Matemáticas de z-index para cualquier cosa apilada: normalmente total - index para que los elementos anteriores estén encima mientras retroceden.
• No sobre-animes. 3–8 tarjetas/cuadros/capas suele ser el punto óptimo; más se vuelve agotador o daña el rendimiento en móvil.
• Móvil: suaviza los rangos de escala, reduce el número de capas/cuadros, y prefiere whileInView sobre secuencias largas guiadas por scroll donde el dramatismo no sea esencial.

Combinar Patrones

Estos patrones se componen. Una página de aterrizaje podría usar insane-parallax para el héroe, scroll-stack para una sección de características, y jos-animation para simples revelaciones escalonadas con fade-in en otra parte de la misma página. Lee cada archivo de referencia relevante de forma independiente — no dependen unos de otros excepto donde se indique (ej. scroll-stack.md apunta a chronos-scroll-stack.md para la variante cinematográfica completa).