Communitygithub.com

erlinerd/erlin-skills

Introduce la biblioteca de animaciones motion a sitios Next.js/React, migra desde framer-motion e implementa animaciones de revelación al hacer scroll, cuadrículas escalonadas, transiciones de página y efectos de navegación. No se encarga de animaciones SwiftUI, solo CSS ni videos Remotion.

¿Qué es erlin-skills?

Esta skill está diseñada para desarrolladores que trabajan con sitios Next.js/React y desean agregar o migrar animaciones de manera controlada y accesible. Proporciona una metodología completa para introducir la biblioteca 'motion' (sucesora de framer-motion), migrar imports de framer-motion a motion/react, e implementar efectos visuales comunes como revelaciones al hacer scroll, cuadrículas con efecto escalonado (stagger), transiciones entre páginas y animaciones en la navegación. Lo que distingue a esta skill es su fuerte enfoque en la accesibilidad y la prevención de errores: incluye un mecanismo de 'salvaguardia de visibilidad' (por ejemplo, IntersectionObserver con un timeout de 2.5s) para garantizar que el contenido nunca quede oculto debido a animaciones fallidas, hydrated incorrecta o JavaScript bloqueado. Además, respeta estrictamente la preferencia de movimiento reducido del usuario, excluye animaciones de entrada en elementos LCP (como H1 o hero), y utiliza transiciones CSS ligeras para efectos hover en lugar de depender de la librería de animación. La skill guía al usuario paso a paso: primero verifica el entorno (gestor de paquetes, versión de Next/React, enrutador y si los componentes son servidores), luego reutiliza dependencias existentes o migra solo si es necesario, aplica el componente de revelación (Reveal) con configuraciones de retardo específicas según la ubicación (cuadrículas, listas, tarjetas, navegación, transiciones de ruta), y finalmente verifica con lint y build. También incluye reglas claras sobre cuándo usarla (solo Next.js/React con motion/framer-motion) y cuándo no (SwiftUI, CSS-only, Remotion).

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/erlinerd/erlin-skills/tree/HEAD/skills/web/erlin-web-motion

Preguntar en tu IA favorita

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

Documentación

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

  1. 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.lock o bun.lockb → bun. Si hay múltiples lockfiles, detente y pregunta al usuario; si no hay lockfile, lee package.json y verifica packageManager. 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 existe pages/ → Pages Router, no hay mecanismo de template.tsx, modifica en pages/_app.tsx o 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 (directorio app/[locale]/), coloca la plantilla en app/[locale]/template.tsx; si no hay rutas con locale (por ejemplo, cambio de idioma en el cliente), colócala en app/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.
  2. Reutilizar dependencias existentes: Si ya existe framer-motion y 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 instala motion con el gestor de paquetes del proyecto, verifica cada lugar los imports de motion/react y la API; después de confirmar que no quedan dependencias residuales, elimina el paquete antiguo. No modifiques comentarios o documentación no relacionados.

  3. Implementar animaciones: usar Reveal como referencia: La plantilla está en assets/reveal.tsx, cópiala a components/motion/reveal.tsx y 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 whileInView ya verificado u otros mecanismos, asegurando que el contenido sea accesible incluso si el observer, JS o la hidratación fallan.
    • Maneja prefers-reduced-motion y 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 uses motion.div, cero sobrecarga del runtime de animación.
    • Reveal tiene su propio prop className: las tarjetas que son div (como las tarjetas glass) pasan directamente la clase a Reveal, evitando una capa de anidamiento; elementos semánticos como article/section se envuelven con Reveal, manteniendo la semántica.
  4. Ubicaciones de aplicación y fórmula de stagger:

    UbicaciónMétododelay
    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 largas
    Lista de artículos (writing, latest-writing)Cada fila envuelta en Reveali * 0.05~0.07, con tope Math.min(i*0.05, 0.3) para evitar retraso en listas largas
    Columna de texto en fila de imagen grande de proyectoRevealfijo 0.15, escalonado con la imagen
    Tarjetas de contenido/contacto (about)Reveal grandesegundo bloque 0.1
    Barra de navegaciónmotion.header con entrada inicial y:"-100%", ocultar al hacer scroll reutilizando la misma transformación—
    Menú móvilAnimatePresence + transición de opacity/y, reemplazando el cambio block/hidden—
    Cambio de rutaCrear app/template.tsx (sin ruta con locale) o app/[locale]/template.tsx (con prefijo de locale; Next remonta template en cada navegación) con entrada opacity+y, 0.35s—
  5. 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 npm
    

    Solo 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-motion a motion (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: SkewReveal tiene el prop instant, o el estado inicial debe ser directamente el estado final, de lo contrario el texto SSR parpadeará.
    • Todas las animaciones respetan prefers-reduced-motion: Usa useReducedMotion(), 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.
  • 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 (como components/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 de assets/reveal.tsx a components/motion/reveal.tsx y adaptar los alias de ruta.
  • Transición de ruta: app/template.tsx (sin ruta con locale) o app/[locale]/template.tsx (con prefijo de locale), entrada con opacity+y 0.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 && build con el gestor de paquetes confirmado, build debe 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.

Skills relacionados