Craft Frontend Motion

¿Qué hace Craft Frontend Motion?

Construye el movimiento como parte de la interacción del producto, no como decoración pegada a él. Rastrea el verdadero propietario del renderizado, selecciona la técnica más pequeña adecuada, preserva la semántica del estado y verifica el resultado en un navegador en vivo.

Flujo de trabajo

1. Inspecciona el objetivo antes de proponer una implementación.
   • Localiza la ruta real, el componente, los estilos, el propietario del estado, el propietario del evento y la pila de animación existente.
   • Lee las instrucciones del proyecto y preserva los cambios no relacionados.
   • Si el usuario pide discutir primero, detente en una especificación de movimiento concreta hasta que se apruebe.
2. Define el contrato de movimiento.
   • Indica el desencadenante, los estados inicial y final, la duración, la aceleración o resorte, el comportamiento de interrupción, el comportamiento de repetición, la superposición y el resultado con movimiento reducido.
   • Separa el estado del negocio de la retroalimentación visual. Una acción de eliminación, navegación o envío de formulario no debe depender de que una línea de tiempo ornamental se complete a menos que el producto lo requiera explícitamente.
3. Selecciona el material de origen.
   • Ejecuta python3 scripts/query_catalog.py --need "<descripción del efecto>" --top 4.
   • Lee references/motion-routing.md para la selección de técnicas.
   • Inspecciona el README oficial actual del repositorio seleccionado, el código fuente relevante, la versión de dependencia/API y la licencia antes de copiar código o agregar una dependencia. Trata los metadatos del catálogo como una instantánea de enrutamiento fechada, no como una verdad permanente.
4. Elige un modo de adopción.
   • Prefiere la pila de animación instalada del proyecto objetivo cuando pueda cumplir el contrato limpiamente.
   • Copia y adapta un componente pequeño solo cuando su código y licencia lo permitan; elimina suposiciones de demostración y dependencias no utilizadas.
   • Agrega una librería cuando su modelo de ejecución reduzca materialmente la complejidad o el riesgo.
   • Extrae la técnica en lugar del paquete cuando un repositorio es antiguo, no coincide con el framework o es demasiado pesado.
5. Implementa el sistema de movimiento coherente más pequeño.
   • Mantén los tiempos y las curvas de aceleración centralizados.
   • Limpia los bucles RAF, observadores, manejadores de eventos, canvases, líneas de tiempo, texturas y recursos GPU.
   • Maneja remontajes, entrada repetida rápida, interrupción, cambios de ruta, redimensionamiento, pestañas ocultas y React Strict Mode.
   • Asegura correctamente el código solo de navegador en aplicaciones SSR y carga perezosamente motores visuales pesados cuando sea práctico.
6. Verifica con references/quality-gates.md.
   • Ejecuta comprobaciones estáticas y pruebas enfocadas.
   • Prueba el runtime real en escritorio ancho, tamaño intermedio/tablet y móvil.
   • Verifica la continuidad de la transición, la geometría final, errores en consola, desbordamiento horizontal, comportamiento de entrada, movimiento reducido y rendimiento realista.
7. Reporta el resultado.
   • Comienza con lo que ahora funciona.
   • Nombra la técnica seleccionada o el repositorio de origen y por qué encajó.
   • Indica qué se verificó y cualquier limitación restante con honestidad.

Reglas de selección

• Usa transiciones/keyframes CSS para un pequeño número de propiedades compuestas y estados deterministas simples.
• Usa Motion para presencia en React, diseño compartido, gestos, valores y transiciones coordinadas de componentes.
• Usa React Spring para física interrumpible donde la continuidad de velocidad y la respuesta natural importan más que una línea de tiempo fija.
• Usa GSAP para líneas de tiempo explícitas de múltiples etapas, orquestación densa, trabajo con SVG/rutas, coreografía de desplazamiento o integración imperativa.
• Usa Anime.js para interpolación compacta de DOM/SVG/objeto/canvas y efectos generativos escalonados fuera de una abstracción específica de React.
• Usa Disintegrate solo como técnica/referencia para partición de instantáneas DOM; espera limitaciones de fidelidad de html2canvas y moderniza su ciclo de vida.
• Usa tsParticles para partículas ambientales configurables, confeti, fuegos artificiales y fondos; no lo etiquetes erróneamente como descomposición DOM precisa.
• Usa PixiJS para grandes recuentos de partículas 2D, filtros, campos de sprites, efectos 2D impulsados por shaders y control explícito de recursos GPU.
• Usa React Bits, Magic UI o Motion Primitives como colecciones de origen. Inspecciona el componente individual porque las dependencias, el costo de renderizado y la calidad varían.

Barreras de calidad del producto

• Preserva la causalidad espacial: el movimiento debe explicar de dónde vino un objeto, a dónde fue o qué cambió.
• Prefiere transform y opacity; anima propiedades de diseño solo con evidencia de que el costo es aceptable.
• Nunca ocultes un diseño roto detrás de una animación.
• Evita animaciones ambientales, de desplazamiento, hover y de entrada simultáneas compitiendo por la atención.
• Proporciona un comportamiento equivalente al teclado y preserva la semántica de enfoque.
• Respeta prefers-reduced-motion; reemplaza el movimiento con un cambio de estado inmediato o un fundido cruzado contenido.
• No afirmes suavidad solo con la inspección del código. Verifica en la ruta renderizada y reporta el alcance probado.
• No alteres reglas de proxy/enrutamiento ni configuración local no relacionada a menos que el usuario lo autorice explícitamente en el turno actual.

Recursos

• references/repositories.json: catálogo fechado de los diez repositorios fuente, licencias, fortalezas, riesgos y puntos de entrada de origen.
• references/motion-routing.md: guía de decisión y patrones de arquitectura listos para producción.
• references/quality-gates.md: lista de verificación de implementación y verificación visual en vivo.
• scripts/query_catalog.py: valida y busca en el catálogo de repositorios por necesidades en lenguaje natural o etiquetas.