use_figma — Skill de la API de Plugin de Figma para Animación
Contexto de animación para la herramienta MCP use_figma. figma-use cubre las reglas fundamentales de la API de Plugin; cargue ambas juntas.
Siempre pase skillNames: "figma-use-motion" (separado por comas junto con figma-use) al llamar a use_figma para trabajo de animación. Solo para registro.
Control de tiempo de ejecución
Las APIs de animación están controladas por el flag de funcionalidad de usuario metronome. Cuando el usuario que llama no lo tiene, cada propiedad y helper de animación referenciado en esta skill lanza "<name>" no es una API soportada.
Salga rápidamente ante ese error. No vuelva a intentar; diga al usuario 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 skill
Cargue esta skill siempre que una tarea de use_figma involucre:
- Agregar, 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 anteriores.
El trabajo de diseño estático (crear formas, componentes, variables, diseño) se realiza solo a través de figma-use — esta skill es solo para la dimensión temporal.
Superficie de API de animación expuesta
node.manualKeyframeTracks— lectura/escritura de fotogramas clave manuales (incluyendo pistas de relleno, trazo y efecto).node.applyManualKeyframeTrack(field, track)/node.removeManualKeyframeTrack(field)— agregar, reemplazar o eliminar una pista de fotogramas clave manual sin reescribir todo el objeto.node.animationStyles— lectura/escritura de 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 aplicado mediante suiddevuelto/leído.node.timelines— lista de solo lectura de líneas de tiempo para el fotograma principal contenedor, con duraciones en segundos.node.setTimelineDuration(id, durationSeconds)— escribir la duración de la línea de tiempo del fotograma principal contenedor.node.animations— datos resueltos de fotogramas clave de solo lectura (actualmente solo pistas manuales — ver motion-patterns.md).figma.motion.figmaAnimationStyles()— lista de solo lectura de los estilos de animación propios de Figma.
La creación de código fuente de módulo preestablecido "figma:motion" personalizado está fuera del alcance. Si el usuario quiere un estilo de animación completamente nuevo, dígalo y deténgase; no invente uno.
Documentos de referencia
Cárguelos según sea necesario según lo que implique la tarea:
| Documento | Cuándo cargar | Qué cubre |
|---|---|---|
| motion-patterns.md | Agregar/editar animación de movimiento | Fotogramas clave manuales, rellenos/trazos animados, aplicar estilos de animación, duración de línea de tiempo |
| motion-easing.md | Configurar easing de animación | Objetos de easing de fotogramas clave, cúbico/resorte personalizado, HOLD, aplicar 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 verificar el movimiento, use export_video y muestree fotogramas, pero se renderiza del lado del servidor y es lento y costoso (~10 segundos a minutos), así que haga que cada renderizado cuente.
Planifique antes de renderizar: el costo escala con píxeles × fotogramas, así que mantenga ambos al mínimo necesario:
- Elija los momentos primero. Necesita un fotograma por fase (por ejemplo, por paso de escalonamiento, o inicio / medio / asentamiento), no reproducción suave — normalmente 4–6. Este número establece sus fps.
- Ajuste el tamaño 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 lo suficientemente altos para capturar esos fotogramas:
fps: 5cubre unos pocos; 10 es un límite superior. Más solo aumenta el tamaño del renderizado.
Mecánica: export_video funciona solo en un fotograma principal cuyos hijos llevan la animación (pase ese fotograma, no el descendiente al que aplicó fotogramas clave). Devuelve un jobId con status: "processing" — vuelva a invocarlo con { fileKey, jobId } para sondear. 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 renderizado, explótelo para cada fotograma que le brinde información 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, sincronización incorrecta, un elemento faltante, una máscara que oculta la composición), corrija los fotogramas clave/estilos y reexporte. Lea todos los fotogramas y agrupe todas las correcciones en una sola pasada antes de volver a renderizar — cada renderizado tiene un costo real, así que haga que cada uno cuente en lugar de reexportar después de cada pequeño cambio.
Omita la exportación por completo para cambios triviales o evidentes.
Lista de verificación previa
Además de la lista de verificación previa de figma-use, verifique:
- El easing usa la forma pública
{ type: 'EASE_OUT', easingFunctionCubicBezier?: …, easingFunctionSpring?: … }— no nombres internos de escenario comoOUT_CUBIC. - La entrada-salida suave 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 fotograma principal (hijo directo de una página). Anime a los descendientes en su lugar.
- Los valores de la línea de tiempo están en segundos en la API pública del Plugin. Extienda mediante
setTimelineDuration; nunca reduzca 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 internos de escenarioMOTION_*. - Los campos de fotogramas clave manuales provienen de la lista blanca pública en motion-patterns.md; los campos de escenario generados/internos lanzan intencionalmente un error.
- Los IDs de nodos mutados se devuelven (según la Regla 15 de
figma-use). - Cuando la corrección de la animación no sea evidente y haya un extractor de fotogramas (
ffmpeg) disponible, verifique medianteexport_video+ muestreo de fotogramas — renderice pequeño, con fps bajos, itere hasta que esté correcto (consulte la sección Verificar la animación arriba).get_screenshotmuestra solo el estado de reposo.