Objetivo
Metodología de animaciones para el sitio personal de Erlin: introducir la biblioteca de animaciones motion en sitios Next.js/React, migrar imports desde framer-motion, e implementar revelaciones al hacer scroll, cuadrículas escalonadas (stagger), transiciones de página y efectos de navegación, sin que nunca las animaciones oculten el contenido. Lección clave: whileInView dejó las tarjetas de proyectos en la página de inicio atascadas en opacity:0 ("las tarjetas de proyectos desaparecieron"). Por lo tanto, se requiere una salvaguardia de visibilidad; las implementaciones existentes y confiables pueden mantenerse, Reveal es una referencia opcional, no se prohíbe completamente whileInView.
Pasos de ejecución
-
Primero determinar el entorno del proyecto (tómate 30 segundos antes de actuar para evitar aplicar la plantilla incorrecta):
- Gestor de paquetes: Reconoce solo un lockfile:
pnpm-lock.yaml→ pnpm,package-lock.json→ npm,yarn.lock→ yarn,bun.lockobun.lockb→ bun. Si hay múltiples lockfiles, detente y pregunta al usuario; si no hay lockfile, leepackage.jsony verificapackageManager. Si aún no se puede determinar, detente y no adivines el gestor. Los comandos de instalación, migración, lint y build posteriores seguirán el gestor confirmado. - Versión de Next/React: Verifica la versión real de Next/React, la biblioteca de animaciones, sus dependencias entre pares (peer dependencies) y las notas oficiales de compatibilidad; no codifiques versiones ni afirmes compatibilidad total entre versiones de API.
- Estructura de rutas (antes de elegir la plantilla, detecta en lugar de asumir App Router): si existe el directorio
app/→ App Router, sigue las reglas a continuación para elegir la plantilla; si solo existepages/→ Pages Router, no hay mecanismo detemplate.tsx, modifica enpages/_app.tsxo en el componente de página objetivo para las transiciones e informa al usuario de la diferencia; si no existe ninguno → no es un proyecto Next, implementa de manera equivalente en el punto de montaje del framework. App Router: si hay rutas con prefijo de locale (directorioapp/[locale]/), coloca la plantilla enapp/[locale]/template.tsx; si no hay rutas con locale (por ejemplo, cambio de idioma en el cliente), colócala enapp/template.tsx. Next igualmente remonta el template en cada navegación, la entrada con opacidad funciona igual. - ¿El componente actual es un componente servidor?: Aísla los elementos de motion que requieren interacción en el componente cliente más pequeño; no conviertas todo el componente que contiene lógica de servidor a cliente.
- Gestor de paquetes: Reconoce solo un lockfile:
-
Reutilizar dependencias existentes: Si ya existe
framer-motiony cumple con los requisitos, continúa usándolo; no migres por defecto solo por agregar nuevas animaciones. Solo si el usuario solicita la migración o es estrictamente necesario por capacidades/compatibilidad, verifica las diferencias de versión, luego instalamotioncon el gestor de paquetes del proyecto, verifica cada lugar los imports demotion/reacty la API; después de confirmar que no quedan dependencias residuales, elimina el paquete antiguo. No modifiques comentarios o documentación no relacionados. -
Implementar animaciones: usar Reveal como referencia: La plantilla está en
assets/reveal.tsx, cópiala acomponents/motion/reveal.tsxy adapta los alias de ruta. Puntos de diseño (adaptar según el proyecto):- Salvaguardia de visibilidad: La plantilla usa IntersectionObserver con un timeout de 2.5s; 2.5s es solo un parámetro de referencia, ajusta según la página y el comportamiento de carga. Se puede usar
whileInViewya verificado u otros mecanismos, asegurando que el contenido sea accesible incluso si el observer, JS o la hidratación fallan. - Maneja
prefers-reduced-motiony la ausencia de observer según las reglas de SSR/hidratación y lint del proyecto; evita inconsistencias de hidratación y actualizaciones síncronas innecesarias de efectos, no tomes una experiencia de lint como una prohibición de toda la API. - Con movimiento reducido, renderiza directamente el estado final.
- Usa transiciones CSS puras (
cubic-bezier(0.22,1,0.36,1)), no usesmotion.div, cero sobrecarga del runtime de animación. Revealtiene su propio propclassName: las tarjetas que sondiv(como las tarjetasglass) pasan directamente la clase a Reveal, evitando una capa de anidamiento; elementos semánticos comoarticle/sectionse envuelven con Reveal, manteniendo la semántica.
- Salvaguardia de visibilidad: La plantilla usa IntersectionObserver con un timeout de 2.5s; 2.5s es solo un parámetro de referencia, ajusta según la página y el comportamiento de carga. Se puede usar
-
Ubicaciones de aplicación y fórmula de stagger:
Ubicación Método delay Cuadrícula de tarjetas (múltiples bloques en inicio) Cada elemento envuelto en RevealMath.min(i * 0.08, 0.4), con tope para evitar retraso en cuadrículas largasLista de artículos (writing, latest-writing) Cada fila envuelta en Reveali * 0.05~0.07, con topeMath.min(i*0.05, 0.3)para evitar retraso en listas largasColumna de texto en fila de imagen grande de proyecto Revealfijo 0.15, escalonado con la imagenTarjetas de contenido/contacto (about) Revealgrandesegundo bloque 0.1Barra de navegación motion.headercon entrada inicialy:"-100%", ocultar al hacer scroll reutilizando la misma transformación— Menú móvil AnimatePresence+ transición deopacity/y, reemplazando el cambioblock/hidden— Cambio de ruta Crear app/template.tsx(sin ruta con locale) oapp/[locale]/template.tsx(con prefijo de locale; Next remonta template en cada navegación) con entradaopacity+y, 0.35s— -
Verificación y entrega: Según el gestor de paquetes confirmado en el paso 1:
pnpm lint && pnpm build # proyecto pnpm; build debe tener éxito (proyecto SSG de todo el sitio incluye exportación SSG) npm run lint && npm run build # proyecto npmSolo si el usuario autoriza el commit, sigue las convenciones de commit del proyecto, por ejemplo:
feat(motion): migrar biblioteca motion y agregar animaciones en todo el sitio. Solo agrega los archivos relacionados con esta tarea — si el repositorio mezcla cambios no relacionados sin commit, no los incluyas en este commit.
Reglas de decisión
- Cuándo usar: Agregar animaciones/efectos a sitios Next.js; migrar de
framer-motionamotion(verificar la API de la versión actual antes de migrar); cuando el usuario solicite "revelación al hacer scroll", "stagger", "transición de página", "más animaciones". - No se encarga de: Animaciones SwiftUI, solo CSS o videos Remotion.
- Reglas de diseño de animaciones (resumen de errores):
- Los elementos LCP (H1, hero) no deben tener animaciones de entrada:
SkewRevealtiene el propinstant, o el estado inicial debe ser directamente el estado final, de lo contrario el texto SSR parpadeará. - Todas las animaciones respetan
prefers-reduced-motion: UsauseReducedMotion(), con movimiento reducido renderiza el estado final / no registra listeners. - Curva de aceleración unificada
[0.22, 1, 0.36, 1](estilo easeOutQuint), duración 0.3–0.8s, priorizando la moderación. - Las animaciones hover usan transiciones CSS (por ejemplo,
hover:-translate-y-1,group-hover:scale-105), no es necesario usar motion. - Al filtrar en el cliente (por ejemplo, filtro de tags), los elementos de lista con la misma clave no reproducen la animación nuevamente — este es el comportamiento esperado, los elementos nuevos se activan automáticamente.
- Los elementos LCP (H1, hero) no deben tener animaciones de entrada:
- Pertenencia de componentes existentes: SkewReveal de entrada, Parallax, Magnetic, MouseParallax pueden mantenerse; las nuevas animaciones coexisten en el mismo directorio; si el proyecto ya tiene un directorio de componentes de animación
.zcode/.agents(comocomponents/motion/), coloca los nuevos componentes allí. - Límite servidor/cliente: Los componentes servidor pueden renderizar directamente
Reveal(es un componente cliente, pero se puede usar como componente hijo sin problemas).
Antes de completar las animaciones, verifica visualmente la accesibilidad y visibilidad del contenido; esta skill se encarga de la implementación técnica de motion para Next.js/React; las animaciones en RN/Expo u otros stacks se implementan directamente bajo el mismo principio, sin depender de los scripts de esta skill.
Formato de salida
- Ubicación del componente
Reveal: copiar deassets/reveal.tsxacomponents/motion/reveal.tsxy adaptar los alias de ruta. - Transición de ruta:
app/template.tsx(sin ruta con locale) oapp/[locale]/template.tsx(con prefijo de locale), entrada conopacity+y0.35s. - Mensaje de commit: commits convencionales + descripción en español, por ejemplo:
feat(motion): migrar biblioteca motion y agregar animaciones en todo el sitio.
Ejemplo
Pregunta del usuario
"Agregar revelación al hacer scroll al sitio y de paso reemplazar framer-motion por motion."
Respuesta de la herramienta
pnpm
pnpm add motion && pnpm remove framer-motion exitoso, en package.json aparece la versión de motion compatible con el proyecto; pnpm lint && pnpm build el SSG de todo el sitio se mantiene exitoso.
sed
sed -i '' 's/from "framer-motion"/from "motion\/react"/g' <archivos> ejecutado, todos los imports apuntan a motion/react; solo se actualizan las referencias realmente obsoletas relacionadas con esta migración.
Salida final
components/motion/reveal.tsx (IntersectionObserver manual + timeout de 2.5s) + stagger de tarjetas/listas + app/template.tsx con entrada de ruta; lint y build pasan; se reporta la verificación real; solo se hace commit de los archivos relacionados si ya se tiene autorización.
Compuertas de seguridad
- Línea roja de contenido: Nunca permitir que las animaciones oculten el contenido — verificar que el contenido sea accesible en SSR, con movimiento reducido, y cuando el observer/script fallen; Reveal y los parámetros de timeout son implementaciones de referencia, no deshabilitar API mecánicamente.
- Línea roja de accesibilidad: Todas las animaciones respetan
prefers-reduced-motion; los elementos LCP (H1, hero) no tienen animaciones de entrada. - Verificación: Ejecutar
lint && buildcon el gestor de paquetes confirmado,builddebe mantenerse exitoso (cuando el proyecto es SSG de todo el sitio, la exportación SSG no debe romperse; para proyectos SSR/ISR, el éxito del build es el criterio, no inventar requisitos SSG). - Disciplina de commits: Solo agregar archivos relacionados con esta tarea, no incluir cambios no relacionados sin commit del repositorio.
- Mejora progresiva: No modificar componentes de animación que ya funcionan para "unificar estilos", decidir basándose en requisitos y evidencia de accesibilidad.