use_figma — Skill da API Plugin do Figma para Animação (Motion)
Contexto de animação para a ferramenta MCP use_figma. figma-use cobre as regras fundamentais da API Plugin — carregue ambos juntos.
Sempre passe skillNames: "figma-use-motion" (separado por vírgulas junto com figma-use) ao chamar use_figma para trabalhos de animação. Apenas para registro.
Bloqueio de Runtime
As APIs de animação são bloqueadas pelo recurso de usuário metronome_plugin_api. Quando o usuário chamador não o possui, toda propriedade e auxiliar de animação referenciado nesta skill lança "<nome>" não é uma API suportada.
Saia rapidamente desse erro. Não tente novamente; informe ao usuário que a animação não está habilitada para ele e pare. Caso contrário, você queimará chamadas e confundirá o usuário com repetidas falhas idênticas.
Quando usar esta skill
Carregue esta skill sempre que uma tarefa use_figma envolver:
- Adicionar, editar ou remover keyframes em um nó (
manualKeyframeTracks,applyManualKeyframeTrack,removeManualKeyframeTrack). - Animar cores de preenchimento ou traço ao longo do tempo.
- Aplicar, editar ou remover estilos de animação (
applyAnimationStyle,removeAnimationStyle,animationStyles). - Ler ou escrever a duração da linha do tempo via
node.timelines/node.setTimelineDuration(id, segundos). - Escolher easing para qualquer um dos itens acima.
Trabalho de design estático (criação de formas, componentes, variáveis, layout) passa apenas pelo figma-use — esta skill é exclusivamente para a dimensão temporal.
Superfície da API de animação exposta
node.manualKeyframeTracks— leitura/escrita de keyframes manuais (incluindo trilhas de preenchimento, traço e efeitos).node.applyManualKeyframeTrack(campo, trilha)/node.removeManualKeyframeTrack(campo)— adicionar, substituir ou remover uma trilha de keyframe manual sem reescrever o objeto inteiro.node.animationStyles— leitura/escrita de metadados de estilo de animação aplicados a um nó.node.applyAnimationStyle(styleId, presetData?)/node.removeAnimationStyle(id)— aplicar um estilo descoberto e remover uma instância de estilo aplicada pelo seuidretornado/lido de volta.node.timelines— lista de linhas do tempo somente leitura para o quadro de nível superior contentor, com durações em segundos.node.setTimelineDuration(id, duracaoSegundos)— escrever a duração da linha do tempo do quadro de nível superior contentor.node.animations— dados de keyframe resolvidos somente leitura (apenas trilhas manuais atualmente — veja motion-patterns.md).figma.motion.figmaAnimationStyles()— lista somente leitura dos estilos de animação primários do Figma.
A criação de código-fonte de módulo de preset "figma:motion" personalizado está fora do escopo. Se o usuário quiser um estilo de animação novo, diga isso e pare; não invente um.
Documentação de referência
Carregue conforme necessário com base no que a tarefa envolve:
| Documento | Quando carregar | O que cobre |
|---|---|---|
| motion-patterns.md | Adicionar/editar animação de movimento | Keyframes manuais, preenchimentos/traços animados, aplicação de estilos de animação, duração da linha do tempo |
| motion-easing.md | Configurar easing de animação | Objetos de easing de keyframe, cubic/spring personalizado, HOLD, aplicação de easing dentro de um estilo de animação |
Verificando a animação
get_screenshot mostra apenas o estado de repouso da linha do tempo, nunca o movimento. Para verificar movimento, use export_video e amostre quadros — mas ele renderiza no lado do servidor e é lento e caro (~10s a minutos), então faça cada renderização valer a pena.
Planeje antes de renderizar — o custo escala com pixels × quadros, então mantenha ambos não maiores do que os quadros precisam:
- Escolha os momentos primeiro. Você precisa de um quadro por fase (ex.: por passo de stagger, ou início / meio / estabilização), não reprodução suave — geralmente 4–6. Essa contagem define seu fps.
- Dimensione para o que você precisa ler. Comece pequeno —
constraint: { type: 'WIDTH', value: 320 },quality: "low"— mas texto e elementos pequenos ficam borrados aí, então aumenteWIDTH(768+) quando precisar julgar detalhes finos. Omitirconstraint= tamanho total (1x; o servidor limita a 10x / 4096px). - Defina fps apenas alto o suficiente para capturar esses quadros:
fps: 5cobre alguns; 10 é um limite superior. Mais alto apenas incha a renderização.
Mecânica: export_video funciona apenas em um quadro de nível superior cujos filhos carregam a animação (passe esse quadro, não o descendente que você keyframou). Ele retorna um jobId com status: "processing" — invoque novamente com { fileKey, jobId } para consultar. Em seguida, extraia quadros localmente com ffmpeg -ss <t> -i anim.mp4 -frames:v 1 frame_<t>.png — a extração é gratuita, então, depois de pagar pela renderização, explore-a para cada quadro que lhe diga algo, em vez de reexportar. Sem um extrator de quadros como ffmpeg, pule a exportação e raciocine sobre os keyframes.
Itere até acertar. A exportação é um diagnóstico, não uma aprovação final: se os quadros estiverem errados (ordem ruim, temporização incorreta, elemento faltando, máscara obscurecendo a composição), corrija os keyframes/estilos e reexporte. Leia todos os quadros e agrupe todas as correções em uma passagem antes de renderizar novamente — cada renderização tem uma sobrecarga real, então faça cada uma valer a pena em vez de reexportar após cada pequena alteração.
Pule a exportação completamente para alterações triviais ou auto-evidentes.
Lista de verificação pré-voo
Além da lista de verificação pré-voo do figma-use, verifique:
- Easing usa a forma pública
{ type: 'EASE_OUT', easingFunctionCubicBezier?: …, easingFunctionSpring?: … }— não nomes internos do scenegraph comoOUT_CUBIC. - Ease-in-out usa o enum público exato
EASE_IN_AND_OUT(ouEASE_IN_AND_OUT_BACK); nunca emita o alias inválidoEASE_IN_OUT. - O nó sendo animado não é um quadro de nível superior (filho direto de uma página). Anima descendentes.
- Os valores da linha do tempo estão em segundos na API Plugin pública. Estenda via
setTimelineDuration; nunca encurte a menos que o usuário tenha pedido. - Campos de keyframe de transformação usam nomes públicos (
TRANSLATION_X,TRANSLATION_Y,ROTATION,SCALE_X,SCALE_Y,SCALE_XY), não nomes internos do scenegraphMOTION_*. - Campos de keyframe manual vêm da lista de permissões pública em motion-patterns.md; campos internos gerados do scenegraph lançam erro intencionalmente.
- IDs de nós mutados são retornados (conforme Regra 15 do
figma-use). - Quando a correção da animação não é auto-evidente e um extrator de quadros (
ffmpeg) está disponível, verifique viaexport_video+ amostragem de quadros — renderize pequeno,fpsbaixo, itere até acertar (veja a seção Verificando a animação acima).get_screenshotmostra apenas o estado de repouso.