use_figma — Habilidade de API do Plugin Figma para Movimento
Contexto de movimento para a ferramenta MCP use_figma. figma-use cobre as regras fundamentais da API do Plugin — carregue ambos juntos.
Sempre passe skillNames: "figma-use-motion" (separado por vírgula junto com figma-use) ao chamar use_figma para trabalho de movimento. Apenas para registro.
Bloqueio de Execução
As APIs de Movimento são protegidas pela flag de funcionalidade de usuário metronome. Quando o usuário chamador não a possui, cada propriedade de movimento e auxiliar referenciada nesta habilidade lança "<nome>" não é uma API suportada.
Saia rapidamente desse erro. Não tente novamente; informe ao usuário que o movimento não está habilitado para ele e pare. Caso contrário, você queimará chamadas e confundirá o usuário com falhas idênticas repetidas.
Quando usar esta habilidade
Carregue esta habilidade 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 timeline 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 por figma-use — esta habilidade é apenas para a dimensão temporal.
Superfície da API de Movimento Exposta
node.manualKeyframeTracks— leitura/escrita de keyframes manuais (incluindo trilhas de preenchimento, traço e efeito).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.node.timelines— lista somente leitura de timelines para o frame de nível superior que contém o nó, com durações em segundos.node.setTimelineDuration(id, durationSeconds)— escrever a duração da timeline do frame de nível superior que contém o nó.node.animations— dados de keyframe resolvidos somente leitura (atualmente apenas trilhas manuais — veja motion-patterns.md).figma.motion.figmaAnimationStyles()— lista somente leitura dos estilos de animação primários do Figma.
Criar código-fonte de módulo de preset personalizado "figma:motion" está fora do escopo. Se o usuário quiser um estilo de animação totalmente novo, diga isso e pare; não invente um.
Documentos de Referência
Carregue estes conforme necessário, com base no que a tarefa envolve:
| Documento | Quando carregar | O que cobre |
|---|---|---|
| motion-patterns.md | Ao adicionar/editar animação de movimento | Keyframes manuais, preenchimentos/traços animados, aplicação de estilos de animação, duração da timeline |
| motion-easing.md | Ao definir easing de animação | Objetos de easing de keyframe, cubic/spring personalizado, HOLD, aplicando easing dentro de um estilo de animação |
Verificando a Animação
get_screenshot mostra apenas o estado de repouso da timeline, nunca o movimento. Para verificar o movimento, use export_video e amostre frames — mas ele renderiza no 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 × frames, então mantenha ambos não maiores do que os frames precisam:
- Escolha os momentos primeiro. Você precisa de um frame por fase (por exemplo, por passo de escalonamento, ou início / meio / estabilização), não reprodução suave — geralmente 4–6. Essa contagem define seu fps.
- Tamanho para o que você precisa ler. Comece pequeno —
constraint: { type: 'WIDTH', value: 320 },quality: "low"— mas texto e elementos pequenos ficam borrados ali, então aumenteWIDTH(768+) quando precisar avaliar detalhes finos. Omitirconstraint= tamanho completo (1x; o servidor limita a 10x / 4096px). - Defina fps apenas o suficiente para capturar esses frames:
fps: 5cobre alguns; 10 é um limite superior. Mais alto apenas incha a renderização.
Mecânica: export_video funciona apenas em um frame de nível superior cujos filhos carregam a animação (passe esse frame, não o descendente que você keyframed). Ele retorna um jobId com status: "processing" — reinvoke com { fileKey, jobId } para consultar. Em seguida, extraia frames localmente com ffmpeg -ss <t> -i anim.mp4 -frames:v 1 frame_<t>.png — a extração é gratuita, então, uma vez que você pagou pela renderização, explore-a para cada frame que lhe diga algo em vez de reexportar. Sem um extrator de frames 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: se os frames estiverem errados (ordem errada, tempo errado, um elemento faltando, uma máscara ocultando a composição), corrija os keyframes/estilos e reexporte. Leia todos os frames e agrupe cada correção em uma passagem antes de re-renderizar — 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 de 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 frame de nível superior (filho direto de uma página). Anime descendentes.
- Os valores de timeline são segundos na API pública do Plugin. Estenda via
setTimelineDuration; nunca encurte a menos que o usuário tenha solicitado. - 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 de scenegraphMOTION_*. - Campos de keyframe manual vêm da lista de permissões pública em motion-patterns.md; campos de scenegraph gerados/internos intencionalmente lançam erro.
- IDs de nós mutados são retornados (conforme Regra 15 do
figma-use). - Quando a correção do movimento não é auto-evidente e um extrator de frames (
ffmpeg) estiver disponível, verifique viaexport_video+ amostragem de frames — renderize pequeno, fps baixo, itere até acertar (veja a seção Verificando a Animação acima).get_screenshotmostra apenas o estado de repouso.