Implementar Movimento
Visão Geral
Esta skill guia a tradução de animações e transições do Figma em código executável (motion.dev, keyframes CSS ou bibliotecas específicas de framework).
O Figma expõe movimento através de duas ferramentas:
get_motion_context— ferramenta de movimento autoritativa. Retorna o inventário completo de nós animados, snippets de código pré-computados (CSS@keyframes+ motion.dev), bindings de keyframes de fallback quando snippets não estão disponíveis e dicas de coordenação de timeline recursiva (timelineCohorts). Fonte da verdade para dados de animação e quais IDs de nós animam.get_design_context— a estrutura do design: layout, dimensionamento, ativos, estilos, dicas de Code Connect, contexto de captura de tela e, às vezes, marcadores de posicionamento de movimento em elementos animados (data-node-id, e em nós divididosdata-motion-keys/data-motion-wrapper-for/data-motion-transform-template). Pode renderizar um nó animado como um elemento simples (div,p,span, etc.) ou um elemento de movimento (motion.div); não incorpora os valores de animação.
Os dois são vinculados pelo ID do nó, e esse é todo o fluxo de trabalho. get_motion_context informa quais nós animam e fornece os valores de keyframe, easing, timing e snippets. get_design_context informa a aparência desses nós e onde eles estão. Para cada nó em get_motion_context.nodes, encontre o data-node-id correspondente no contexto de design e mescle o movimento nessa estrutura — adicionando ou envolvendo um motion.{tag} quando o elemento estrutural for simples. Quando o contexto de design reutilizou um componente do Figma, o nó de movimento também pode incluir fallbackNodeId; use-o apenas como fallback após tentar o nodeId exato.
Limites da Skill
- Use esta skill quando a entrega for código de movimento no repositório do usuário.
- Se o usuário pedir para criar/editar animações dentro do próprio Figma, mude para figma-use e siga essa skill.
- Esta skill atualmente cobre animações conforme emitidas por
get_motion_context(snippets mais trilhas de keyframes de fallback, incluindo movimento criado por preset resolvido nessas formas). Fluxos de variantes interativos mais amplos ainda podem precisar de tratamento de estado específico do produto no código.
Pré-requisitos
- Servidor MCP do Figma conectado e acessível.
- ID do nó analisado da URL do Figma fornecida pelo usuário. Formato da URL:
https://figma.com/design/:fileKey/:fileName?node-id=1-2— extraiafileKey(o segmento após/design/) enodeId(o valor do parâmetro de consultanode-id, ex.:42-15). - Base de código alvo. O formato de saída do movimento se adapta ao stack (veja Recomendações de Framework).
Escolha de Ferramenta
Para implementação de movimento, use ambas as ferramentas com funções distintas:
| Situação | Ferramenta | Por que |
|---|---|---|
| Entender estrutura estática, ativos, estilos, Code Connect ou layout visual | get_design_context | Fornece a referência de código do componente/página e URLs de ativos necessários para posicionar nós animados corretamente. |
| Buscar dados de animação para qualquer nó | get_motion_context | Projetado especificamente para movimento e é a fonte da verdade para timing, easing, snippets e keyframes. |
Um nó tem marcadores de movimento (data-motion-keys, data-motion-wrapper-for) | Marcadores para posicionamento dividido, get_motion_context para valores | Marcadores de divisão informam quais trilhas vão em qual elemento; os keyframes/easing/timing e o inventário de nós animados vêm de get_motion_context. |
get_motion_context aceita recursive: true (limitado a 500 nós) quando você precisa do movimento dos descendentes em uma única chamada.
Fluxo de Trabalho Obrigatório
Etapa 1: Confirmar que o contexto de design está disponível
get_design_context(fileKey=":fileKey", nodeId="<node-id>")
Se get_design_context já foi chamado para este nó, reutilize essa saída. Caso contrário, chame-o agora normalmente.
Use-o como a estrutura de registro — hierarquia, dimensionamento, estilos, ativos, dicas de Code Connect, contexto de captura de tela e quaisquer marcadores de posicionamento de movimento que ele incluir (Etapa 3). O inventário de nós animados e os valores de animação vêm de get_motion_context (Etapa 2).
Etapa 2: Buscar dados de movimento autoritativos
get_motion_context(fileKey=":fileKey", nodeId="<node-id>", recursive=true)
Forma da resposta (uma entrada por nó animado):
codeSnippets— strings CSS@keyframese motion.dev pré-geradas. Use-as diretamente. Não as regenere a partir de dados de trilhas de fallback.keyframeBindings— trilhas de keyframes vinculadas, incluindo movimento derivado de preset resolvido em dados de trilha, incluídas apenas como dados de fallback quando ambos os formatos de snippet estão ausentes.motionSummary— descrição em linguagem natural de uma linha por campo da animação. Presente apenas quando não há snippet (a geração de código de movimento apenas com bindings de keyframes não pôde expressar como CSS/motion.dev). Construa a partir dele quando presente; ignore-o sempre que um snippet existir.fallbackNodeId— ID de fallback opcional para correspondência de contexto de design componentizado. SenodeIdfor um ID qualificado por instância comoI4005:6111;30:8005, o D2R pode renderizar o corpo do componente reutilizável com o ID do componente subjacente, como4002:3957. Nesse caso,fallbackNodeIdé odata-node-ida ser procurado se a busca exata pornodeIdfalhar.
Respostas recursivas também incluem timelineCohorts — um array de nível superior (não por nó) de nós compartilhando uma timeline: { rootNodeId, durationMs, loopMode: 'once' | 'loop' | 'boomerang', memberNodeIds[] }. Para movimento coordenado de vários nós, conduza todos os memberNodeIds de um ciclo de vida compartilhado usando durationMs (÷1000 para segundos) e loopMode — não infira timing a partir da ordem dos irmãos.
Detalhes de implementação importantes para LLMs:
- Quando um snippet existe,
motionSummary,timelineDurationMsetransformOriginpodem ser omitidos para reduzir o payload — o snippet já carrega duração + transform-origin (motion.devduration/style={{ transformOrigin }}, ou CSSanimation/transform-origin) e o cohort carregadurationMs. Um campo ausente nunca significa "sem animação." - Respostas recursivas deduplicam snippets exatamente duplicados. Um snippet pode ser substituído por um comentário apontando para o primeiro nó com movimento idêntico; reutilize o mesmo componente, variante, classe ou constantes em vez de escrever uma segunda animação.
- O servidor MCP infere snippets CSS vs motion.dev a partir de
clientFrameworks; se a resposta contiver apenas um formato de snippet, adapte esse formato ao stack do usuário em vez de assumir que o outro formato falhou.
Etapa 3: Mesclar contexto estático e de movimento
- Comece de
get_motion_context.nodes, não de tagsmotion.*visíveis no JSX estático. Cada nó retornado está animado. Corresponda cada nó de movimento de volta aoget_design_contextpelonodeId/data-node-idexato primeiro. Se e somente se não houver correspondência exata, tentefallbackNodeId/data-node-id. Recorra ao nome/tipo do nó e à posição da captura de tela somente depois que ambos os IDs falharem. - Correspondência de ID exata vence sobre
fallbackNodeId.fallbackNodeIdaponta para o ID do componente subjacente que o D2R pode emitir dentro de um componente reutilizável. É compartilhado por cada instância desse componente. Se onodeIdexato existir no contexto de design, aplique o movimento lá e ignore o fallback. Isso é crítico para animação de instância raiz: uma instância pode girar ou mover-se de forma diferente de outra instância do mesmo componente, e aplicar esse movimento ao corpo do componente compartilhado animaria todas as instâncias incorretamente. - Aplique cada nó de movimento à estrutura de contexto de design correspondente, indexada por
data-node-id. Odata-node-idcorrespondente é a âncora estrutural, nem sempre o elemento DOM final que recebe o movimento. Use a forma do snippet e os marcadores de posicionamento para decidir se o movimento vai nesse elemento exato, em um wrapper, em um elemento interno ou em um caminho SVG inline.get_design_contextjá pode emitirmotion.{tag}com valores removidos, ou pode emitir um elemento estrutural simples (div,p,span, raiz de componente, etc.). Se for simples e o snippet alvejar o próprio elemento, converta-o para omotion.{tag}apropriado ou adicione um wrapper de movimento preservando o texto, filhos, classes/estilos, atributos edata-node-iddo nó. Carregue referências/exemplos-e-antiexemplos.md para ver exemplos desta etapa de mesclagem. - Movimento de filho componentizado geralmente corresponde por fallback. Quando o contexto de design extrai uma instância do Figma em um componente React reutilizável, os filhos dentro do corpo desse componente geralmente têm IDs de componente subjacentes (
4002:3957) enquanto o contexto de movimento relata IDs de instância ativa (I4005:6111;30:8005). Neste caso, usefallbackNodeIdpara encontrar odata-node-iddo corpo do componente, mas mantenha o movimento escopo da instância renderizada que você está implementando. Se houver várias instâncias e apenas uma tiver movimento raiz diferente, a correspondência de ID exata mantém esse movimento por instância separado. - Nós divididos carregam um marcador
data-motion-keys/data-motion-wrapper-for— veja Lidando com transformações intercaladas abaixo. - Preserve wrappers
display: contents— a menos que o próprio grupo anime. Wrappers de grupo transparentes de layout vêm comocontents(Tailwindcontents), geralmente junto com umabsolute/inset-[…]morto (que não faz nada em uma caixacontents). Para um grupo estático, mantenhadisplay: contentse deixe os filhos se posicionarem contra o ancestral real mais próximo — converter oinsetdo wrapper em uma caixa posicionada reposiciona os filhos para uma caixa menor, fazendo com que eles renderizem muito pequenos / deslocados para dentro. Para um grupo animado (o próprio nó do grupo tem movimento),display: contentsnão pode carregar uma transformação — substitua-o por um wrapper posicionado real e aplique o movimento do grupo lá. Carregue referências/pegadinhas.md antes de implementar este caso. get_motion_contexté o inventário completo de nós animados. Alguns nós animados renderizam como elementos simples (nãomotion) — raízes de instância de componente (<div>de posicionamento simples ), texto (<p>), máscaras — que ainda carregam umdata-node-id. Percorra cada nó na resposta de movimento e aplique seu movimento ao elemento com odata-node-idcorrespondente, envolvendo ou convertendo conforme necessário. Se um nó animado não tiver nenhum elemento na saída (por exemplo, uma máscara animada achatada em umamask-imageestática), não o descarte silenciosamente — deixe um comentário// TODO: movimento <nodeId> não suportadoe destaque-o em seu resumo.- Se um nó aparecer no contexto de movimento, mas não no JSX estático, adicione o elemento necessário para representá-lo — o código do contexto de design é uma referência, não um inventário de animação completo.
- Em caso de conflito entre contexto de design e movimento (timing/easing/valores animados), prefira
get_motion_context. - Movimento SVG em nível de caminho: incorpore o SVG e anime o
<path>real. Quandoget_motion_contextalveja o caminho de um vetor (PATH_TRIM,motion.path,stroke-dasharray) mas o contexto de design o renderiza como um<img>, incorpore o SVG e aplique o snippet ao<path>, mantendo o wrapper de layout. Carregue referências/movimento-svg-e-caminho.md para o guia completo para este caso (motion.path,pathLength="1", camadas wrapper+caminho, corte de caminho CSS).
Lidando com transformações intercaladas
Um nó com ambas uma transformação base estática e transformações animadas é dividido entre elementos aninhados para que as duas componham corretamente em vez de lutar: um motion.div sem ID carregando data-motion-wrapper-for="<nodeId>" (o wrapper EXTERNO) envolve um div de transformação estática (ex.: rotate-45 + dimensionamento hypot() — ou o próprio wrapper carrega data-motion-transform-template="<css>") que envolve o nó INTERNO (data-node-id). Mantenha o aninhamento wrapper > div de transformação estática > interno — colapsá-lo quebra o dimensionamento e a transformação base.
- Coloque trilhas por
data-motion-keys. Asdata-motion-keysdo wrapper (trilhas de transformação —x/y/rotate/scaleX/scaleY/skewX) vão no wrapper EXTERNO; asdata-motion-keysdo elemento interno vão no elemento INTERNO. - Reaplique um
data-motion-transform-template. Se o wrapper carregar um, definatransformTemplate={(_, generated) => "<css> " + generated}para que a transformação animada componha sobre essa transformação de layout estático. - Desloque a transformação animada pela base estática (evite rotação dupla).
get_motion_contextfornece a transformação absoluta do nó, que já inclui qualquer base estática que esses divs aplicam. Um snippetrotatede[45, 125, 125]sobre uma baserotate-45significa que o wrapper anima o deslocamento[0, 80, 80](= absoluto − 45), não o absoluto — senão os 45° são aplicados duas vezes e o elemento fica em 90° em repouso. Trilhas sem base estática (ex.:x/ycomeçando em 0) passam inalteradas. Veja o exemplo de transformação intercalada. - Mantenha transformações de layout separadas das transformações do Motion. Para cada elemento
motion.*que animarotate,scaleouskew, verifique se ele também não depende de transformações de layout do Tailwind como-translate-x-1/2ou-translate-y-1/2para centralização/posicionamento. Esses utilitários compartilham a propriedade CSStransformque o Motion.dev escreve inline, então a transformação do Motion pode apagar a tradução de layout. Se ambos forem necessários, divida o elemento em um wrapper de layout estático carregando a transformação de centralização/posicionamento e um elementomotion.*interno carregando rotate/scale/opacity animados, ou codifique o deslocamento de layout no próprio Motion (x: "-50%") e mantenha-o presente para cada keyframe.
Etapa 4: Aplicar o movimento no código
- motion.dev presente nos snippets? Use o código motion.dev textualmente para alvos React. Importe de
motion/react— a menos que a base de código já use outra biblioteca de movimento (Framer Motion, React Spring, GSAP), nesse caso adapte o snippet a ela. Carregue referências/recomendações-de-framework.md ao adaptar para outro stack ou escolher uma biblioteca. - Keyframes CSS presentes? Use para alvos vanilla/não React, ou quando a base de código não tiver biblioteca de movimento React.
- Nenhum snippet (apenas bindings de keyframes)? Construa motion.dev/CSS equivalente a partir de
keyframeBindings. Cada binding temduration,easinge arraykeyframes. Construa string CSS@keyframesou opção motion.devtransitiona partir deles. - Adaptação de framework e camada de componente. Para alvos React, coloque o movimento no elemento renderizado correto — converta
divparamotion.div, ou adicione um wrappermotion.divse o elemento precisar permanecer estático. Useinitial,animate,transitionpara motion.dev; para CSS, apliqueanimationcom o nome@keyframesgerado. Verifique se os estilos iniciais da animação correspondem ao estado estático para evitar "pulo" no carregamento. - Movimento coordenado (cohorts de timeline). Quando o movimento de vários nós compartilha uma timeline:
- Calcule duração:
durationMs / 1000para segundos. - Defina
loopModeconforme apropriado (once= sem loop,loop= repetir,boomerang= ida e volta). - Use os mesmos valores
initialeanimatepara todos os membros (a menos que o snippet especifique o contrário), mas defina atrasos de início diferentes se o cohort especificaroffsetpor nó. Se não houver deslocamentos, inicie todos juntos.
- Calcule duração:
- Imports e dependências. motion.dev:
import { motion } from "motion/react". Framer Motion:import { motion } from "framer-motion". GSAP: usegsap.to(...). React Spring: useuseSpring. CSS: adicione a tag<style>ou importe o arquivo CSS. - Teste e itere. Após aplicar o movimento, verifique se a animação corresponde ao design do Figma. Se não, ajuste valores, easing ou timing. Use o console do navegador ou extensões React DevTools para depurar.
Referências
- referências/exemplos-e-antiexemplos.md — exemplos de etapas de mesclagem.
- referências/pegadinhas.md — problemas comuns (wrappers display: contents, conflitos de transformação, etc.).
- referências/movimento-svg-e-caminho.md — guia para movimento SVG em nível de caminho.
- referências/recomendações-de-framework.md — adaptação a diferentes stacks (React, Vue, Angular, vanilla).