habilidad-animacion-empro-labs

Habilidad de Animación de Empro Labs

Habilidad de diseño de movimiento web. Dos pasos: escribe primero la especificación de movimiento (ANIMATION.md) y luego escribe el código.

ANIMATION.md es un archivo guardado en el proyecto. Puede editarse manualmente, reutilizarse en otros proyectos y ser leído por otras herramientas.

Las rutas en este archivo son relativas a la carpeta de la habilidad (~/.claude/skills/empro-labs-animation-skill/). Usa rutas absolutas cuando ejecutes los scripts.

Solicitud

La solicitud del usuario desde el comando slash:

$ARGUMENTS

Si la solicitud anterior está vacía, haz una pregunta: ¿qué debería moverse y hacia dónde? Luego comienza la Fase A.

Flujo principal

Fase A  Entender la entrada  ──→  Fase B  Escribir ANIMATION.md (el usuario aprueba)  ──→  Fase C  Implementar  ──→  Fase D  Auditar

Verificaciones iniciales (en este orden)

1. ¿El proyecto tiene ANIMATION.md? → Reutilízalo, edítalo o renuévalo, según lo que pida el usuario.
2. ¿Tiene DESIGN.md (de la habilidad de diseño web)? → Hereda sus colores, fuentes y dirección de estilo. Mantén el movimiento coherente con él.
3. ¿Tiene tokens de movimiento (variables --motion-* o un archivo de movimiento)? → Reutilízalos. No inventes nuevos valores.
4. ¿Ya tiene código de animación? → Ejecuta primero python scripts/analyze_motion.py <project> --inventory, para que sepas lo que existe antes de proponer cambios.
5. Ninguno de los anteriores → Fase A.

Fase A: Entender

Las entradas pueden combinarse:

Entrada	Qué hacer
URL de referencia	Ejecuta python scripts/capture_motion.py --url [URL] --output ./motion-capture. Lee capture.json para obtener duraciones reales, easings, propiedades animadas y efectos vinculados al scroll. Usa top.png para el ambiente.
Video o captura de pantalla del movimiento	Describe el disparador, la duración aproximada y la sensación del easing. Confirma los números con el usuario.
Palabras clave ("rápido", "cinematográfico")	Asócialas a una personalidad en references/motion-personalities.md.
Nombre de marca ("como Linear")	Captura el sitio en vivo si es accesible. Si no, pide una URL de referencia. No adivines el movimiento basándote en la memoria de una marca.
Código existente	Ejecuta el script de inventario y conserva lo que funciona.

A1. Personalidad (haz como máximo dos preguntas)

• Sensación: ¿tranquila, rápida, divertida o cinematográfica?
• Tipo de página: ¿con mucho contenido (el movimiento pasa desapercibido) o de exhibición (el movimiento puede liderar)?

Muestra uno o dos candidatos de references/motion-personalities.md, cada uno con una razón de una línea. El usuario confirma.

A2. Nivel de interacción (obligatorio, no lo omitas)

Consulta references/interaction-tiers.md.

Nivel	Experiencia	Herramientas
L1 Micro	Hover, focus, press, interruptores, cambios de estado pequeños	Solo transiciones CSS
L2 Coreografiado	Entrada y salida, listas escalonadas, modales, cajones, cambios de ruta, loaders	Keyframes CSS, API de Animaciones Web o una línea de tiempo de GSAP
L3 Historia de scroll	Revelaciones vinculadas al scroll, fijación, parallax, secciones impulsadas por una línea de tiempo	GSAP + ScrollTrigger, o animaciones CSS controladas por scroll con un fallback

L3 está limitado a dos secciones fijadas por página. Cada sección de la página indica su nivel en la especificación.

A3. Stack

Verifica package.json y el framework (HTML plano, React, Vue, Svelte, Next.js). Elige las herramientas con references/tooling.md. Por defecto: CSS y la API de Animaciones Web. Añade GSAP solo para L3 o líneas de tiempo complejas.

Fase B: Escribir ANIMATION.md

Sigue references/animation-md-template.md. Diez secciones:

1. Personalidad y Principios del Movimiento
2. Tokens de Movimiento (duraciones, easings, distancias)
3. Inventario de Coreografías (tabla: elemento, disparador, propiedad, duración, easing, retardo, fallback de movimiento reducido)
4. Movimiento de Componentes (por defecto, hover, focus-visible, active, disabled, entrada, salida)
5. Comportamiento de Scroll
6. Transiciones de Página y Ruta
7. Presupuesto de Rendimiento
8. Accesibilidad
9. Qué Hacer y Qué No Hacer (al menos 8 elementos, al menos 5 de ellos son "Qué No Hacer")
10. Dependencias

Muestra un resumen al usuario y espera la aprobación. Luego guarda ANIMATION.md en la raíz del proyecto.

Fase C: Implementar

1. Tokens en todas partes. Cada duración y easing es una variable, como var(--motion-duration-base). Sin números mágicos dentro de los componentes.
2. Anima solo propiedades económicas. transform y opacity primero. clip-path y filter están permitidos en elementos pequeños. Nunca anime width, height, top, left, margin o padding a menos que ANIMATION.md registre una excepción con una razón.
3. El movimiento reducido es parte de la primera versión, no un parche posterior. El movimiento se elimina y los cambios de estado permanecen. Los tokens de distancia se reducen a cero con movimiento reducido, y el bloque prefers-reduced-motion en templates/motion-tokens.css muestra el patrón.
4. Usa los archivos de inicio cuando el proyecto aún no tenga una capa de movimiento: templates/motion-tokens.css y templates/reveal.js.
5. Los bucles necesitan una salida. Cualquier animación infinite se detiene o simplifica con movimiento reducido. Cualquier bucle que dure más de cinco segundos tiene un control de pausa.
6. Limpia el JavaScript. Elimina las líneas de tiempo de GSAP y los ScrollTriggers al desmontar (usa gsap.context() o useGSAP). Desconecta los observadores y elimina los listeners.
7. Mantén el movimiento en un solo lugar. Coloca los tokens en un archivo y las recetas en módulos pequeños. No disperses los valores de sincronización entre componentes.

Fase D: Auditar

1. Ejecuta la auditoría estática: python scripts/analyze_motion.py <project> --strict. Corrige todos los errores. Revisa todas las advertencias y, o bien corrígelas, o justifícalas en ANIMATION.md.
2. Ejecuta las comprobaciones del navegador:
   • Activa el movimiento reducido (DevTools → Rendering → prefers-reduced-motion: reduce). Confirma que no queda movimiento y que el contenido sigue siendo visible.
   • Limita la CPU (4×) y graba el panel de Rendimiento mientras se reproduce el movimiento. Busca frames largos.
   • Verifica un ancho de teléfono (390 px). Busca desbordamiento horizontal de elementos animados.
3. Revisa references/quality-checklist.md.
4. Informa qué pasó, qué falló y qué corregiste.

Líneas rojas (cada elemento debe cumplirse)

• Cada animación en ANIMATION.md tiene un fallback de movimiento reducido.
• Solo se animan transform, opacity y las excepciones registradas.
• Todas las duraciones y easings provienen de tokens.
• Cada bucle infinite respeta el movimiento reducido, y cualquier bucle de más de cinco segundos tiene un control de pausa.
• Nada parpadea más de tres veces por segundo.
• La retroalimentación interactiva aparece en menos de 100 ms. Las micro animaciones son de 250 ms o menos. Las transiciones de entrada y ruta son de 500 ms o menos.
• La retroalimentación solo por hover tiene un estado de focus de teclado y un equivalente táctil.
• En anchos de 600 px o menos, ningún elemento animado causa desplazamiento horizontal, y las secciones fijadas están desactivadas o simplificadas.
• Las animaciones de JavaScript se limpian al desmontar.

Índice de referencias

Lee solo los archivos que necesita la fase actual. No los cargues todos.

Archivo	Contenido	Leer cuando
references/animation-md-template.md	Plantilla de salida de ANIMATION.md (10 secciones)	Fase B
references/motion-principles.md	Por qué y cuándo animar, reglas de sincronización y easing	Fase A y B
references/interaction-tiers.md	Definiciones de niveles L1, L2 y L3 con patrones de código	Fase A2 y B
references/motion-personalities.md	Cuatro preajustes de personalidad con valores de tokens	Fase A1 y B
references/tooling.md	CSS vs WAAPI vs GSAP vs Motion vs View Transitions vs Lottie	Fase A3
references/component-recipes.md	Botón, tarjeta, acordeón, modal, cajón, toast, pestañas, loaders	Fase C
references/gsap-recipes.md	Líneas de tiempo de GSAP, ScrollTrigger, matchMedia, limpieza en React	Fase C (solo GSAP)
references/scroll-patterns.md	Revelación, barra de progreso, pila adhesiva, parallax, desplazamiento horizontal	Fase B (scroll) y C
references/performance.md	Presupuesto de frames, reglas amigables con el compositor, degradado móvil	Fase B y D
references/accessibility.md	Movimiento reducido, criterios de movimiento de WCAG, desencadenantes vestibulares	Fase B y D
references/quality-checklist.md	Lista de verificación de auditoría de 100 puntos	Fase D

Scripts

Script	Uso	Necesita
scripts/analyze_motion.py	Auditoría estática del CSS y JS de un proyecto. Encuentra animaciones de layout, transition: all, bucles infinitos, duraciones largas y falta de manejo de movimiento reducido. --inventory lista los valores de sincronización existentes.	Python 3 (solo biblioteca estándar)
scripts/capture_motion.py	Registra animaciones declaradas y en ejecución en una URL en vivo, desplaza la página y verifica qué sigue funcionando con movimiento reducido. Escribe capture.json y top.png.	Python 3, pip install playwright, python -m playwright install chromium

Ambos scripts aceptan --help.

Plantillas

Archivo	Uso
templates/motion-tokens.css	Variables de tokens, keyframes base, reglas de revelación y el bloque de movimiento reducido. Cópialo en el proyecto.
templates/reveal.js	Revelación de scroll sin dependencias con IntersectionObserver que respeta el movimiento reducido.

Idioma

Escribe ANIMATION.md y los resúmenes en el idioma del usuario. Mantén los nombres de CSS, JavaScript y tokens en inglés.

Cadena de respaldo

• El script de captura falla (no tiene Playwright, o el sitio bloquea el navegador) → pide una captura de pantalla o una grabación de pantalla corta y construye a partir de esa descripción.
• La referencia usa una biblioteca de animación que no puedes identificar → indícalo y pregunta si deseas igualar la sensación o el movimiento exacto.
• Ninguna entrada en absoluto → haz una pregunta sobre la sensación, luego usa la personalidad tranquila.