Implementar Movimiento
Resumen
Esta habilidad guía la traducción de animaciones y transiciones de Figma a código ejecutable (motion.dev, keyframes de CSS o bibliotecas específicas del framework).
Figma expone el movimiento a través de dos herramientas:
get_motion_context: herramienta de movimiento autorizada. Devuelve el inventario completo de nodos animados, fragmentos de código precomputados (CSS@keyframes+ motion.dev), enlaces de keyframes de respaldo cuando los fragmentos no están disponibles, y pistas de coordinación de línea de tiempo recursiva (timelineCohorts). Fuente de verdad para datos de animación y qué IDs de nodo se animan.get_design_context: la estructura del diseño: diseño, tamaño, activos, estilos, pistas de Code Connect, contexto de captura de pantalla y, a veces, marcadores de colocación de movimiento en elementos animados (data-node-id, y en nodos divididosdata-motion-keys/data-motion-wrapper-for/data-motion-transform-template). Puede representar un nodo animado como un elemento simple (div,p,span, etc.) o un elemento de movimiento (motion.div); no incluye los valores de animación.
Ambos están vinculados por el ID del nodo, y ese es todo el flujo de trabajo. get_motion_context te dice qué nodos se animan y proporciona los valores de keyframes, easing, temporización y fragmentos. get_design_context te dice cómo se ven esos nodos y dónde están ubicados. Para cada nodo en get_motion_context.nodes, encuentra la data-node-id coincidente en el contexto de diseño y fusiona el movimiento en esa estructura — agregando o envolviendo un motion.{etiqueta} cuando el elemento estructural es simple. Cuando el contexto de diseño ha reutilizado un componente de Figma, el nodo de movimiento también puede incluir fallbackNodeId; úsalo solo como respaldo después de intentar con el nodeId exacto.
Límites de la Habilidad
- Usa esta habilidad cuando el entregable sea código de movimiento en el repositorio del usuario.
- Si el usuario solicita crear/editar animaciones dentro de Figma, cambia a figma-use y sigue esa habilidad.
- Esta habilidad actualmente cubre animaciones tal como las emite
get_motion_context(fragmentos más pistas de keyframes de respaldo, incluido movimiento creado por preset resuelto en esas formas). Los flujos de variantes interactivas más amplias pueden necesitar manejo de estado específico del producto en el código.
Prerrequisitos
- Servidor MCP de Figma conectado y accesible.
- ID de nodo extraído de la URL de Figma que proporciona el usuario. Formato de URL:
https://figma.com/design/:fileKey/:fileName?node-id=1-2— extraefileKey(el segmento después de/design/) ynodeId(el valor del parámetro de consultanode-id, ej.42-15). - Código base objetivo. El formato de salida del movimiento se adapta a la pila tecnológica (ver Recomendaciones de Framework).
Elección de Herramienta
Para la implementación del movimiento, usa ambas herramientas con roles distintos:
| Situación | Herramienta | Por qué |
|---|---|---|
| Entender la estructura estática, activos, estilos, Code Connect o diseño visual | get_design_context | Proporciona la referencia de código del componente/página y las URLs de activos necesarias para colocar los nodos animados correctamente. |
| Obtener datos de animación para cualquier nodo | get_motion_context | Diseñado específicamente para movimiento y es la fuente de verdad para temporización, easing, fragmentos y keyframes. |
Un nodo tiene marcadores de movimiento (data-motion-keys, data-motion-wrapper-for) | Marcadores para colocación dividida, get_motion_context para valores | Los marcadores divididos indican qué pistas van en qué elemento; los keyframes/easing/temporización y el inventario de nodos animados provienen de get_motion_context. |
get_motion_context acepta recursive: true (limitado a 500 nodos) cuando necesitas el movimiento de los descendientes en una sola llamada.
Flujo de Trabajo Requerido
Paso 1: Confirmar que el contexto de diseño estático está disponible
get_design_context(fileKey=":fileKey", nodeId="<node-id>")
Si get_design_context ya se ha llamado para este nodo, reutiliza esa salida. Si no, llámalo normalmente ahora.
Úsalo como la estructura de referencia — jerarquía, tamaño, estilo, activos, pistas de Code Connect, contexto de captura de pantalla y cualquier marcador de colocación de movimiento que incluya (Paso 3). El inventario de nodos animados y los valores de animación provienen de get_motion_context (Paso 2).
Paso 2: Obtener datos de movimiento autorizados
get_motion_context(fileKey=":fileKey", nodeId="<node-id>", recursive=true)
Forma de la respuesta (una entrada por nodo animado):
codeSnippets: cadenas de CSS@keyframesy motion.dev pregeneradas. Úsalas directamente. No las regeneres a partir de datos de pistas de respaldo.keyframeBindings: pistas de keyframes enlazadas, incluido movimiento derivado de preset resuelto en datos de pista, incluidas solo como datos de respaldo cuando ambos formatos de fragmento faltan.motionSummary: descripción en lenguaje natural, una línea por campo, de la animación. Presente solo cuando no hay fragmento (la generación de código solo con keyframes no pudo expresarse como CSS/motion.dev). Construye a partir de él cuando esté presente; ignóralo siempre que exista un fragmento.fallbackNodeId: ID de respaldo opcional para coincidir con el contexto de diseño componentizado. SinodeIdes un ID calificado por instancia comoI4005:6111;30:8005, D2R puede representar el cuerpo del componente reutilizable con el ID del componente subyacente, como4002:3957. En ese caso,fallbackNodeIdes eldata-node-ida buscar si la búsqueda exacta denodeIdfalla.
Las respuestas recursivas también incluyen timelineCohorts: un array de nivel superior (no por nodo) de nodos que comparten una línea de tiempo: { rootNodeId, durationMs, loopMode: 'once' | 'loop' | 'boomerang', memberNodeIds[] }. Para movimiento coordinado de múltiples nodos, impulsa todos los memberNodeIds desde un ciclo de vida compartido usando durationMs (÷1000 para segundos) y loopMode — no infieras la temporización del orden de los hermanos.
Detalles de implementación importantes para LLMs:
- Cuando existe un fragmento,
motionSummary,timelineDurationMsytransformOriginpueden omitirse para reducir el payload — el fragmento ya lleva la duración + transform-origin (motion.devduration/style={{ transformOrigin }}, o CSSanimation/transform-origin) y la cohorte llevadurationMs. Un campo faltante nunca significa "sin animación". - Las respuestas recursivas deduplican fragmentos exactamente duplicados. Un fragmento puede ser reemplazado con un comentario que apunte al primer nodo con movimiento idéntico; reutiliza el mismo componente, variante, clase o constantes en lugar de escribir una segunda animación.
- El servidor MCP infiere fragmentos CSS vs motion.dev a partir de
clientFrameworks; si la respuesta solo contiene un formato de fragmento, adapta ese formato a la pila del usuario en lugar de asumir que el otro formato falló.
Paso 3: Fusionar contexto estático y de movimiento
- Empieza desde
get_motion_context.nodes, no desde etiquetasmotion.*visibles en el JSX estático. Cada nodo devuelto está animado. Empareja cada nodo de movimiento de vuelta aget_design_contextpornodeId/data-node-idexacto primero. Si y solo si no hay una coincidencia exacta, prueba confallbackNodeId/data-node-id. Recurre al nombre/tipo de nodo y posición de captura de pantalla solo después de que ambos IDs fallen. - La coincidencia de ID exacto prevalece sobre
fallbackNodeId.fallbackNodeIdapunta al ID del componente subyacente que D2R puede emitir dentro de un componente reutilizable. Es compartido por cada instancia de ese componente. Si elnodeIdexacto existe en el contexto de diseño, aplica el movimiento allí e ignora el respaldo. Esto es crítico para la animación de instancia raíz: una instancia puede rotar o moverse de manera diferente a otra instancia del mismo componente, y aplicar ese movimiento al cuerpo del componente compartido animaría todas las instancias incorrectamente. - Aplica cada nodo de movimiento a la estructura de contexto de diseño coincidente, claveada por
data-node-id. Ladata-node-idcoincidente es el ancla estructural, no siempre el elemento DOM final que recibe movimiento. Usa la forma del fragmento y los marcadores de colocación para decidir si el movimiento va en ese elemento exacto, en un envoltorio, en un elemento interno o en una ruta SVG en línea.get_design_contextya puede emitirmotion.{etiqueta}con valores eliminados, o puede emitir un elemento estructural simple (div,p,span, raíz del componente, etc.). Si es simple y el fragmento apunta al elemento mismo, conviértelo almotion.{etiqueta}apropiado o agrega un envoltorio de movimiento preservando el texto, hijos, clases/estilos, atributos ydata-node-iddel nodo. Carga references/examples-and-anti-examples.md para ver ejemplos de este paso de fusión. - El movimiento de hijo componentizado generalmente coincide mediante respaldo. Cuando el contexto de diseño extrae una instancia de Figma en un componente React reutilizable, los hijos dentro del cuerpo de ese componente a menudo tienen IDs de componente subyacente (
4002:3957) mientras que el contexto de movimiento informa IDs de instancia vivos (I4005:6111;30:8005). En este caso, usafallbackNodeIdpara encontrar eldata-node-iddel cuerpo del componente, pero mantén el movimiento limitado a la instancia renderizada que estás implementando. Si hay múltiples instancias y solo una tiene un movimiento raíz diferente, la coincidencia de ID exacto mantiene ese movimiento por instancia separado. - Los nodos divididos llevan un marcador
data-motion-keys/data-motion-wrapper-for— ver Manejo de transformaciones entrelazadas más abajo. - Preserva los envoltorios con
display: contents— a menos que el grupo mismo se anime. Los envoltorios de grupo transparentes en diseño vienen comocontents(Tailwindcontents), generalmente junto con unabsolute/inset-[…]muerto (que no hace nada en una cajacontents). Para un grupo estático, manténdisplay: contentsy deja que los hijos se posicionen contra el ancestro real más cercano — convertir elinsetdel envoltorio en una caja posicionada reparenta a los hijos a una caja más pequeña, por lo que se renderizan demasiado pequeños/desplazados hacia adentro. Para un grupo animado (el nodo del grupo mismo tiene movimiento),display: contentsno puede llevar una transformación — reemplázalo con un envoltorio posicionado real y aplica el movimiento del grupo allí. Carga references/gotchas.md antes de implementar este caso. get_motion_contextes el inventario completo de nodos animados. Algunos nodos animados se renderizan como elementos simples (nomotion) — raíces de instancias de componente (<div>de posición simple), texto (<p>), máscaras — que todavía llevan undata-node-id. Recorre cada nodo en la respuesta de movimiento y aplica su movimiento al elemento con eldata-node-idcoincidente, envolviendo o convirtiendo según sea necesario. Si un nodo animado no tiene ningún elemento en la salida (ej. una máscara animada aplanada en unmask-imageestático), no lo elimines en silencio — deja un comentario// TODO: <nodeId> motion unsupportedy menciónalo en tu resumen.- Si un nodo aparece en el contexto de movimiento pero no en el JSX estático, agrega el elemento necesario para representarlo — el código del contexto de diseño es una referencia, no un inventario de animación completo.
- En caso de conflicto entre el contexto de diseño y el de movimiento (temporización/easing/valores animados), prefiere
get_motion_context. - Movimiento SVG a nivel de ruta: pon el SVG en línea y anima el
<path>real. Cuandoget_motion_contextapunta a la ruta de un vector (PATH_TRIM,motion.path,stroke-dasharray) pero el contexto de diseño lo renderiza como un<img>, pon el SVG en línea y aplica el fragmento al<path>, manteniendo el envoltorio de diseño. Carga references/svg-and-path-motion.md para el tutorial completo de este caso (motion.path,pathLength="1", capas de envoltorio+ruta, recorte de ruta CSS).
Manejo de transformaciones entrelazadas
Un nodo con tanto una transformación base estática como transformaciones animadas se divide entre elementos anidados para que las dos se compongan correctamente en lugar de luchar: un motion.div sin ID que lleva data-motion-wrapper-for="<nodeId>" (el envoltorio EXTERNO) envuelve un div de transformación estática (ej. rotate-45 + tamaño hypot() — o el envoltorio mismo lleva data-motion-transform-template="<css>") que envuelve el nodo INTERNO (data-node-id). Mantén el anidamiento envoltorio > div de transformación estática > interno — colapsarlo rompe el tamaño y la transformación base.
- Coloca las pistas por
data-motion-keys. Lasdata-motion-keysdel envoltorio (pistas de transformación —x/y/rotate/scaleX/scaleY/skewX) van en el envoltorio EXTERNO; lasdata-motion-keysdel elemento interno van en el elemento INTERNO. - Re-aplica un
data-motion-transform-template. Si el envoltorio lleva uno, establecetransformTemplate={(_, generated) => "<css> " + generated}para que la transformación animada se componga sobre esa transformación de diseño estático. - Desplaza la transformación animada por la base estática (evita la doble rotación).
get_motion_contextda la transformación absoluta del nodo, que ya incluye cualquier base estática que aplican esos divs. Un fragmentorotatede[45, 125, 125]sobre una baserotate-45significa que el envoltorio anima el desplazamiento[0, 80, 80](= absoluto − 45), no el absoluto — de lo contrario, los 45° se aplican dos veces y el elemento se sitúa en 90° en reposo. Las pistas sin base estática (ej.x/yempezando en 0) pasan sin cambios. Ver el ejemplo de transformación entrelazada. - Mantén las transformaciones de diseño separadas de las transformaciones de Motion. Para cada elemento
motion.*que animerotate,scaleoskew, verifica que no dependa también de transformaciones de diseño de Tailwind como-translate-x-1/2o-translate-y-1/2para centrado/posicionamiento. Esas utilidades comparten la propiedad CSStransformque Motion.dev escribe en línea, por lo que la transformación de Motion puede borrar la traducción de diseño. Si se necesitan ambas, divide el elemento en un envoltorio de diseño estático que lleve la transformación de centrado/posicionamiento y un elemento internomotion.*que lleve rotate/scale/opacity animados, o codifica el desplazamiento de diseño en Motion mismo (x: "-50%") y manténlo presente para cada keyframe.
Paso 4: Aplicar el movimiento en el código
- ¿motion.dev presente en los fragmentos? Usa el código de motion.dev textualmente para objetivos React. Importa desde
motion/react— a menos que el código base ya use otra biblioteca de movimiento (Framer Motion, React Spring, GSAP), en cuyo caso adapta el fragmento a ella. Carga references/framework-recommendations.md al adaptar a otra pila o elegir una biblioteca. - ¿Keyframes de CSS presentes? Úsalos para objetivos vanilla/no React, o cuando el código base no tenga una biblioteca de movimiento React.
- ¿Sin fragmentos (solo keyframes enlazados)? Construye motion.dev/CSS equivalente a partir de
keyframeBindings: para cada pista, genera el bloque de keyframes o las opciones de animación (easing, duración, delay, modo de bucle). Carga references/keyframe-bindings-guide.md para plantillas de código específicas de biblioteca. - ¿motionSummary presente (sin fragmentos)? Lee la descripción en lenguaje natural y tradúcela al código de animación apropiado para la pila del usuario.
timelineCohortspresente? Para cada cohorte, agrupa losmemberNodeIdsen un solo controlador de línea de tiempo con la duración y el modo de bucle compartidos. Prepara configuraciones de animación idénticas para todos los hermanos. No asumas orden entre hermanos ni agregues delays secuenciales a menos que los keyframes individuales los lleven.- Preserva los atributos
data-node-iden los elementos renderizados finales.
Recomendaciones de Framework {#framework-recommendations}
Ver references/framework-recommendations.md.