¿Qué hace use_figma — Habilidad de Animación para el Plugin API de Figma?
Contexto de animación para la herramienta MCP use_figma. figma-use cubre las reglas fundamentales del Plugin API: cárguelos juntos.
Siempre pase skillNames: "figma-use-motion" (separado por comas junto con figma-use) al llamar a use_figma para trabajos de animación. Solo para registro.
Control de acceso en tiempo de ejecución
Las APIs de animación están protegidas por la feature flag de usuario metronome_plugin_api. Cuando el usuario que llama no la tiene, cada propiedad y helper de animación referido en esta habilidad lanza "<name>" is not a supported API.
Abandone rápidamente ante ese error. No reintente; informe al usuario de que la animación no está habilitada para él y deténgase. De lo contrario, quemará llamadas y confundirá al usuario con fallos idénticos repetidos.
Cuándo usar esta habilidad
Cargue esta habilidad siempre que una tarea de use_figma implique:
- Añadir, editar o eliminar fotogramas clave en un nodo (
manualKeyframeTracks,applyManualKeyframeTrack,removeManualKeyframeTrack). - Animar colores de relleno o trazo a lo largo del tiempo.
- Aplicar, editar o eliminar estilos de animación (
applyAnimationStyle,removeAnimationStyle,animationStyles). - Leer o escribir la duración de la línea de tiempo mediante
node.timelines/node.setTimelineDuration(id, seconds). - Elegir easing para cualquiera de los casos anteriores.
El trabajo de diseño estático (crear formas, componentes, variables, layout) se realiza solo a través de figma-use — esta habilidad es únicamente para la dimensión temporal.
Superficie de API de animación expuesta
node.manualKeyframeTracks— leer/escribir fotogramas clave manuales (incluyendo pistas de relleno, trazo y efectos).node.applyManualKeyframeTrack(field, track)/node.removeManualKeyframeTrack(field)— añadir, reemplazar o eliminar una pista de fotograma clave manual sin reescribir todo el objeto.node.animationStyles— leer/escribir metadatos de estilo de animación aplicados a un nodo.node.applyAnimationStyle(styleId, presetData?)/node.removeAnimationStyle(id)— aplicar un estilo descubierto y eliminar una instancia de estilo aplicada por suiddevuelto/leído.node.timelines— lista de solo lectura de líneas de tiempo para el marco de nivel superior contenedor, con duraciones en segundos.node.setTimelineDuration(id, durationSeconds)— escribir la duración de la línea de tiempo del marco de nivel superior contenedor.node.animations— datos de fotogramas clave resueltos de solo lectura (actualmente solo pistas manuales — consulte motion-patterns.md).figma.motion.figmaAnimationStyles()— lista de solo lectura de los estilos de animación de primera parte de Figma.
La creación de código fuente personalizado de módulo preset "figma:motion" está fuera del alcance. Si el usuario quiere un estilo de animación completamente nuevo, dígaselo y deténgase; no fabrique uno.
Documentos de referencia
Cárguelos según sea necesario según la tarea:
| Documento | Cuándo cargarlo | Qué cubre |
|---|---|---|
| motion-patterns.md | Añadir/editar animación de movimiento | Fotogramas clave manuales, rellenos/trazos animados, aplicación de estilos de animación, duración de línea de tiempo |
| motion-easing.md | Configurar easing de animación | Objetos de easing de fotograma clave, cúbico/resorte personalizado, HOLD, aplicación de easing dentro de un estilo de animación |
Verificar la animación
get_screenshot muestra solo el estado de reposo de la línea de tiempo, nunca el movimiento. Para comprobar el movimiento, use export_video y muestree fotogramas — pero se renderiza en el servidor y es lento y costoso (~10 segundos a minutos), así que haga que cada render cuente.
Planifique antes de renderizar — el costo escala con píxeles × fotogramas, así que mantenga ambos no más grandes de lo necesario:
- Elija los momentos primero. Necesita un fotograma por fase (p. ej., por paso escalonado, o inicio / medio / estabilización), no una reproducción suave — normalmente 4–6. Esta cantidad establece su fps.
- Tamaño acorde a lo que debe leer. Empiece pequeño —
constraint: { type: 'WIDTH', value: 320 },quality: "low"— pero el texto y los elementos pequeños se vuelven borrosos ahí, así que aumenteWIDTH(768+) cuando necesite juzgar detalles finos. Omitirconstraint= tamaño completo (1x; el servidor limita a 10x / 4096px). - Establezca fps justo lo suficientemente alto para capturar esos fotogramas:
fps: 5cubre unos pocos; 10 es un límite superior. Una frecuencia más alta solo hincha el render.
Mecánica: export_video funciona solo en un marco de nivel superior cuyos hijos llevan la animación (pase ese marco, no el descendiente al que aplicó fotogramas clave). Devuelve un jobId con status: "processing" — vuelva a invocar con { fileKey, jobId } para consultar el estado. Luego extraiga fotogramas localmente con ffmpeg -ss <t> -i anim.mp4 -frames:v 1 frame_<t>.png — la extracción es gratuita, así que una vez que haya pagado por el render, aprovéchelo para obtener cada fotograma que le diga algo en lugar de reexportar. Sin un extractor de fotogramas como ffmpeg, omita la exportación y razone sobre los fotogramas clave.
Itere hasta que esté correcto. La exportación es un diagnóstico, no una aprobación: si los fotogramas son incorrectos (mal orden, mal tiempo, un elemento faltante, una máscara que oculta el compuesto), corrija los fotogramas clave/estilos y reexporte. Lea todos los fotogramas y agrupe todas las correcciones en un solo pase antes de rerenderizar — cada render tiene un costo real, así que haga que cada uno cuente en lugar de reexportar tras cada cambio pequeño.
Omita la exportación por completo para cambios triviales o evidentes.
Lista de verificación previa al vuelo
Además de la lista de verificación previa al vuelo de figma-use, verifique:
- El easing usa la forma pública
{ type: 'EASE_OUT', easingFunctionCubicBezier?: …, easingFunctionSpring?: … }— no nombres internos de scenegraph comoOUT_CUBIC. - Ease-in-out usa el enum público exacto
EASE_IN_AND_OUT(oEASE_IN_AND_OUT_BACK); nunca emita el alias inválidoEASE_IN_OUT. - El nodo que se está animando no es un marco de nivel superior (hijo directo de una página). Anime descendientes en su lugar.
- Los valores de línea de tiempo están en segundos en el Plugin API público. Extienda mediante
setTimelineDuration; nunca acorte a menos que el usuario lo haya solicitado. - Los campos de fotogramas clave de transformación usan nombres públicos (
TRANSLATION_X,TRANSLATION_Y,ROTATION,SCALE_X,SCALE_Y,SCALE_XY), no nombres internosMOTION_*de scenegraph. - Los campos de fotogramas clave manuales provienen de la lista blanca pública en motion-patterns.md; los campos generados/internos de scenegraph lanzan intencionalmente un error.
- Los IDs de nodo mutados se devuelven (según la Regla 15 de
figma-use). - Cuando la corrección de la animación no es evidente y hay un extractor de fotogramas (
ffmpeg) disponible, verifique medianteexport_video+ muestreo de fotogramas — renderice pequeño, bajofps, itere hasta que esté correcto (consulte la sección Verificar la animación arriba).get_screenshotmuestra solo el estado de reposo.