Criar Especificação de Movimento
Gere uma especificação de movimento diretamente no Figma — barras de timeline e tabelas de detalhes documentando todas as propriedades animadas de uma composição do After Effects.
Fora do escopo do contrato de consumo do Markdown de Componente (
.md). As outras skillscreate-*exigem o.mddo componente (produzido por {{skill:create-component-md}}) e renderizam a partir de seurender-meta.create-motioné a exceção deliberada: sua entrada é uma exportação de timeline do After Effects ({{ref:motion/export-timeline.jsx}}), não uma inspeção de componente Figma — não há_base.json, nemextract-motion, nem seção de Movimento no.md. Esta skill NÃO requer um.mde NÃO participa da refatoração que exige.md/falha rápida/leituras na lista de permissões.
Contrato de execução (leia primeiro).
- Este arquivo são instruções para EXECUTAR, não um documento para editar. Invocar a skill = renderizar a especificação de movimento no Figma a partir do JSON da timeline do After Effects.
- Nunca edite este
SKILL.mdou qualquer outro arquivo de skill em resposta, mesmo que um esteja aberto ou focado no editor. Modifique uma skill apenas quando o usuário pedir explicitamente para alterar a própria skill. - O JSON da timeline de entrada é uma fonte da verdade SOMENTE LEITURA. Nunca o edite. O único artefato que esta skill produz é a anotação Figma; solicitações de renderização devem ser feitas no Figma, nunca como uma edição de arquivo.
- Nunca chame
AskQuestion, solicite confirmação ou pause para entrada (incluindo antes de escrever no Figma, a saída esperada). Em caso de ambiguidade, escolha a opção mais defensável e continue. - Apenas duas paradas legais: (a) JSON de timeline do AE ausente ou inválido (a porta de coleta + validação das Etapas 4/5); (b) aborto de uma linha se a conexão MCP do Figma estiver inativa.
Adaptador MCP
Leia uspecs.config.json → mcpProvider. Siga a coluna correspondente para cada chamada MCP nesta skill.
| Operação | figma-console | figma-mcp |
|---|---|---|
| Verificar conexão | figma_get_status | Pular — implícito. Se a primeira chamada use_figma falhar, oriente o usuário a verificar a configuração do MCP. |
| Navegar para arquivo | figma_navigate com URL | Extrair fileKey da URL (figma.com/design/:fileKey/...). Nenhuma navegação necessária. |
| Tirar screenshot | figma_take_screenshot | get_screenshot com fileKey + nodeId |
| Executar Plugin JS | figma_execute com code | use_figma com fileKey, code, description. O código JS é idêntico — sem alterações de wrapper. |
| Pesquisar componentes | figma_search_components | search_design_system com query + fileKey + includeComponents: true |
| Obter dados de arquivo/componente | figma_get_file_data / figma_get_component | get_metadata ou get_design_context com fileKey + nodeId |
| Obter variáveis (arquivo inteiro) | figma_get_variables | Script use_figma: return await figma.variables.getLocalVariableCollectionsAsync(); |
| Obter valores de token | figma_get_token_values | Script use_figma lendo valores de variáveis por modo/coleção |
| Obter estilos | figma_get_styles | search_design_system com includeStyles: true, ou use_figma: return figma.getLocalPaintStyles(); |
| Obter seleção | figma_get_selection | Script use_figma: return figma.currentPage.selection.map(n => ({id: n.id, name: n.name, type: n.type})); |
figma-mcp requer fileKey em cada chamada. Extraia-o uma vez da URL Figma do usuário no início do fluxo de trabalho. Para URLs de branch (figma.com/design/:fileKey/branch/:branchKey/:fileName), use :branchKey como o fileKey.
Contexto de página figma-mcp: use_figma redefine figma.currentPage para a primeira página em cada chamada. Quando um script acessa um nó de uma etapa anterior via getNodeByIdAsync(ID), o conteúdo da página pode não estar carregado — findAll, findOne e characters falharão com TypeError até que a página seja ativada. Insira este bloco de carregamento de página imediatamente após getNodeByIdAsync:
let _p = node; while (_p.parent && _p.parent.type !== 'DOCUMENT') _p = _p.parent;
if (_p.type === 'PAGE') await figma.setCurrentPageAsync(_p);
Isso sobe até o ancestral PAGE e carrega seu conteúdo. O MCP do Console não precisa disso — figma_execute herda o contexto da página do Desktop.
Entradas Esperadas
O usuário aciona esta skill com um destes padrões:
- {{skill:create-motion}} + JSON colado (da área de transferência, exportado via
{{ref:motion/export-timeline.jsx}}) - {{skill:create-motion}} + uma referência de arquivo (ex.:
@motion-ex.jsonou um caminho para um arquivo.json) - {{skill:create-motion}} + um link Figma (página/arquivo de destino onde a anotação deve ser colocada)
Obrigatório: Os dados JSON exportados — colados inline ou referenciados como um arquivo.
Opcional:
- Link Figma para a página de destino (se não fornecido, coloque na página atual no centro da viewport)
- Screenshot ou gravação da animação
- Descrição do propósito da animação
Fluxo de Trabalho
Copie esta lista de verificação e atualize conforme você progride:
Progresso da Tarefa:
- [ ] Etapa 1: Ler arquivo de instruções
- [ ] Etapa 2: Verificar conexão MCP
- [ ] Etapa 3: Ler chave do template de `uspecs.config.json`
- [ ] Etapa 4: Coletar contexto (JSON de colagem, referência de arquivo ou solicitar ao usuário)
- [ ] Etapa 5: Analisar e validar JSON (incluindo segments[] e hasAnimatedSegments)
- [ ] Etapa 6: Transformar dados (ler segmentos pré-calculados, calcular largura da trilha, posições da timeline)
- [ ] Etapa 7: Re-ler arquivo de instruções (Erros e Anti-Padrões, Lista de Verificação de Validação) e auditar
- [ ] Etapa 8: Importar e desanexar o template de Movimento
- [ ] Etapa 9: Preencher campos de cabeçalho
- [ ] Etapa 10: Gerar régua de tempo
- [ ] Etapa 11: Renderizar camadas de timeline (um `figma_execute` por camada)
- [ ] Etapa 12: Ocultar templates
- [ ] Etapa 13: Renderizar linhas da tabela
- [ ] Etapa 14: Validação visual
Etapa 1: Ler Instruções
Leia agent-motion-instruction.md
Etapa 2: Verificar Conexão MCP
Leia mcpProvider de uspecs.config.json para determinar qual Figma MCP usar.
Se figma-console:
figma_get_status— Confirme que o plugin Desktop Bridge está ativo- Se a conexão falhar: "Por favor, abra o Figma Desktop e execute o plugin Desktop Bridge. Depois tente novamente."
Se figma-mcp:
- A conexão é verificada implicitamente na primeira chamada
use_figma. Nenhuma verificação explícita é necessária. - Se a primeira chamada falhar: "Por favor, verifique se o FIGMA_API_KEY está configurado corretamente na sua configuração MCP."
Etapa 3: Ler Chave do Template
Leia o arquivo uspecs.config.json e extraia:
- O valor
motionSpecdo objetotemplateKeys→ salve comoMOTION_TEMPLATE_KEY
Se a chave do template estiver vazia, informe ao usuário:
A chave do template de especificação de movimento não está configurada. Execute {{skill:firstrun}} com o link da sua biblioteca de templates Figma primeiro.
Etapa 4: Coletar Contexto
Verifique o que o usuário forneceu:
- JSON já fornecido (colado inline ou como referência de arquivo como
@motion-ex.json) → leia-o e prossiga diretamente para a Etapa 5. Não pergunte novamente. - Apenas um link Figma (destino) mas nenhum JSON → solicite:
Por favor, cole o JSON exportado ou referencie o arquivo
.json(ex.:@motion-ex.json). - Nada fornecido → solicite:
Por favor, cole o JSON exportado de
export-timeline.jsx, ou referencie o arquivo.json.
Se um link de destino Figma foi fornecido, use figma_navigate para abri-lo antes de renderizar (Etapa 8).
Também aceite quaisquer screenshots, gravações ou descrições opcionais que o usuário fornecer para contexto adicional.
Etapa 5: Analisar e Validar JSON
Valide o JSON da área de transferência contra o esquema e as regras de validação no arquivo de instruções (seções Esquema JSON e Regras de Validação JSON). Se a validação falhar, informe ao usuário exatamente qual campo está ausente ou malformado e peça para reexportar.
Etapa 6: Transformar Dados
O script de exportação pré-calcula segmentos, formatação de valores, rótulos de barra, rótulos de easing e filtragem de não-mudança. O agente lê estes diretamente e calcula apenas valores dependentes de layout.
6a. Pular camadas não animadas — Verifique layer.hasAnimatedSegments. Se false, omita a camada da timeline e da tabela.
6b. Ler segmentos pré-calculados — Cada propriedade tem um array segments[] com startMs, endMs, durationMs, fromValue, toValue, barLabel, easing e easingType. Use esses valores diretamente — nenhum cálculo manual necessário.
6c. Calcular largura da trilha e pxPerMs — pxPerMs é uma taxa fixa; trackWidth é dinâmico com preenchimento à direita para rótulos de tick:
compDurationMs = composition.durationMs // lido diretamente do JSON
pxPerMs = 0.64 // taxa fixa — ~320px por tick de 500ms
trackWidth = max(compDurationMs * pxPerMs + 50, 1600) // área de dados + 50px de preenchimento do rótulo, mínimo 1600
Passe trackWidth e pxPerMs para o código de renderização do Figma. pxPerMs é uma taxa fixa (0,64), não derivada de trackWidth / compDurationMs. As posições das barras (barX, barWidth) são calculadas dentro do código Figma no momento da renderização — o agente não calcula posições por segmento.
No momento da renderização, redimensione tanto #track-area quanto #ruler-track para este trackWidth calculado. Os contêineres pai usam dimensionamento HUG e expandem automaticamente.
6d. Formatar meta da composição de acordo com as regras de Meta da Composição do arquivo de instruções. Salve como COMPOSITION_META.
Etapa 7: Auditar
Re-leia o arquivo de instruções, focando em:
- Seção Erros e Anti-Padrões
- Lista de Verificação de Validação Pré-Saída
Verifique seus dados transformados contra cada regra. Corrija quaisquer violações.
Etapa 8: Importar e Desanexar Template
Execute via figma_execute (substitua __MOTION_TEMPLATE_KEY__ e __COMPONENT_NAME__):
const TEMPLATE_KEY = '__MOTION_TEMPLATE_KEY__';
const templateComponent = await figma.importComponentByKeyAsync(TEMPLATE_KEY);
const instance = templateComponent.createInstance();
const { x, y } = figma.viewport.center;
instance.x = x - instance.width / 2;
instance.y = y - instance.height / 2;
const frame = instance.detachInstance();
frame.name = '__COMPONENT_NAME__ Motion';
figma.currentPage.selection = [frame];
figma.viewport.scrollAndZoomIntoView([frame]);
return { frameId: frame.id };
Salve o frameId retornado — você precisará dele para todas as etapas subsequentes.
Etapa 9: Preencher Campos de Cabeçalho
Execute via figma_execute (substitua __FRAME_ID__, __COMPONENT_NAME__, __COMPOSITION_META__):
const FRAME_ID = '__FRAME_ID__';
const frame = await figma.getNodeByIdAsync(FRAME_ID);
const textNodes = frame.findAll(n => n.type === 'TEXT');
const fontSet = new Set();
const fontsToLoad = [];
for (const tn of textNodes) {
try {
const fn = tn.fontName;
if (fn && fn !== figma.mixed && fn.family) {
const key = fn.family + '|' + fn.style;
if (!fontSet.has(key)) { fontSet.add(key); fontsToLoad.push(fn); }
}
} catch {}
}
await Promise.all(fontsToLoad.map(f => figma.loadFontAsync(f).catch(() => {})));
const compName = frame.findOne(n => n.name === '#component-name');
if (compName) {
const t = compName.type === 'TEXT' ? compName : compName.findOne(n => n.type === 'TEXT');
if (t) t.characters = '__COMPONENT_NAME__';
}
const compDesc = frame.findOne(n => n.name === '#component-description');
if (compDesc) {
const t = compDesc.type === 'TEXT' ? compDesc : compDesc.findOne(n => n.type === 'TEXT');
if (t) t.characters = 'Motion Specification';
}
const compMeta = frame.findOne(n => n.name === '#composition-meta');
if (compMeta) {
const t = compMeta.type === 'TEXT' ? compMeta : compMeta.findOne(n => n.type === 'TEXT');
if (t) t.characters = '__COMPOSITION_META__';
}
return { success: true };
Etapa 10: Gerar Régua de Tempo
Execute via figma_execute. Calcule a largura ideal da trilha, redimensione #ruler-track e todos os nós #track-area, depois clone #tick para cada intervalo.
Substitua __FRAME_ID__, __COMP_DURATION_MS__ (lido de composition.durationMs), __TRACK_WIDTH__ (calculado na Etapa 6c) e __PX_PER_MS__ (fixo em 0,64):
const FRAME_ID = '__FRAME_ID__';
const COMP_DURATION_MS = __COMP_DURATION_MS__;
const TRACK_WIDTH = __TRACK_WIDTH__;
const PX_PER_MS = __PX_PER_MS__;
const frame = await figma.getNodeByIdAsync(FRAME_ID);
const rulerTrack = frame.findOne(n => n.name === '#ruler-track');
if (!rulerTrack) return { error: '#ruler-track not found' };
// Redimensionar trilha da régua para a largura calculada
rulerTrack.resize(TRACK_WIDTH, rulerTrack.height);
// Redimensionar todos os nós #track-area (no template de camada e quaisquer camadas clonadas)
const trackAreas = frame.findAll(n => n.name === '#track-area');
for (const ta of trackAreas) {
ta.resize(TRACK_WIDTH, ta.height);
}
// Encontrar o template #tick dentro da trilha da régua
const tickTemplate = rulerTrack.findOne(n => n.name === '#tick');
if (!tickTemplate) return { error: '#tick template not found in #ruler-track' };
// Carregar fontes dos nós de texto do template tick
const tickTextNodes = tickTemplate.findAll(n => n.type === 'TEXT');
for (const tn of tickTextNodes) {
if (tn.characters.length > 0) {
try { await figma.loadFontAsync(tn.fontName); } catch {}
}
}
// Intervalo de tick: mire em 6–12 ticks
const tickInterval = COMP_DURATION_MS <= 300 ? 50
: COMP_DURATION_MS <= 600 ? 100
: COMP_DURATION_MS <= 1500 ? 250
: COMP_DURATION_MS <= 4000 ? 500
: COMP_DURATION_MS <= 10000 ? 1000
: 2000;
for (let ms = 0; ms <= COMP_DURATION_MS; ms += tickInterval) {
const xPos = ms * PX_PER_MS;
const tick = tickTemplate.clone();
rulerTrack.appendChild(tick);
tick.name = ms + 'ms';
tick.visible = true;
tick.x = xPos;
const label = tick.findOne(n => n.type === 'TEXT');
if (label) {
try { await figma.loadFontAsync(label.fontName); } catch {}
label.characters = ms + 'ms';
}
}
tickTemplate.visible = false;
return { success: true, trackWidth: TRACK_WIDTH, tickInterval: tickInterval };
Etapa 11: Renderizar Camadas de Timeline
Execute uma chamada figma_execute por camada para evitar timeouts. Para cada camada (onde hasAnimatedSegments é true), clone o #layer-template, defina o nome da camada, então para cada propriedade animada clone #property-template e posicione as barras.
Substitua todos os valores __PLACEHOLDER__.
… [truncado para tradução]