use_figma. Skill da API de Plugin do Figma
Use a ferramenta use_figma para executar JavaScript em arquivos Figma através da API de Plugin. Todos os documentos de referência detalhados estão em references/.
Sempre passe skillNames: "figma-use" ao chamar use_figma. Este é um parâmetro de registro usado para rastrear o uso do skill. Não afeta a execução.
Se as ferramentas MCP do Figma aparecerem como ferramentas adiadas, carregue todos os seus esquemas em uma única chamada ToolSearch usando a sintaxe select:, por exemplo, ToolSearch query="select:use_figma,get_screenshot,get_metadata,create_new_file". Uma viagem de ida e volta é melhor que seis.
Se a tarefa envolver construir ou atualizar uma página completa, tela ou layout de várias seções no Figma a partir do código, carregue também figma-generate-design. Ele fornece o fluxo de trabalho para descobrir componentes do sistema de design via search_design_system, importá-los e montar telas incrementalmente. Ambos os skills trabalham juntos: este para as regras da API, aquele para o fluxo de trabalho de construção de telas.
Se a tarefa envolver criar ou construir um componente no Figma (mesmo um único componente), carregue também figma-generate-library. Ele fornece o fluxo de trabalho de criação de componentes, fundamentos de variáveis, conjuntos de variantes e vinculações de tokens de design. Somente o figma-use não cobre isso.
Antes de tudo, carregue plugin-api-standalone.index.md para entender o que é possível. Quando for solicitado a escrever código da API de plugin, use este contexto para pesquisar (grep) em plugin-api-standalone.d.ts por tipos, métodos e propriedades relevantes. Esta é a fonte definitiva da verdade para a superfície da API. É um arquivo de tipos grande, então não o carregue de uma vez; pesquise seções relevantes conforme necessário.
IMPORTANTE: Sempre que você trabalhar com sistemas de design, comece com working-with-design-systems/wwds.md para entender os conceitos-chave, processos e diretrizes para trabalhar com sistemas de design no Figma. Em seguida, carregue as referências mais específicas para componentes, variáveis, estilos de texto e estilos de efeito conforme necessário.
1. Regras Críticas
- Use
returnpara enviar dados de volta. O valor de retorno é serializado automaticamente em JSON (objetos, arrays, strings, números). NÃO chamefigma.closePlugin()nem envolva o código em uma IIFE assíncrona. Isso é tratado para você. - Escreva JavaScript puro com
awaitereturnde nível superior. O código é automaticamente envolvido em um contexto assíncrono. NÃO envolva em(async () => { ... })(). figma.notify()lança "não implementado": nunca use 3a.getPluginData()/setPluginData()não são suportados emuse_figma: não os use. UsegetSharedPluginData()/setSharedPluginData()(estes SÃO suportados), ou rastreie IDs de nós retornando-os e passando-os para chamadas subsequentes.console.log()NÃO é retornado. Usereturnpara saída- Trabalhe incrementalmente em pequenos passos. Divida grandes operações em várias chamadas
use_figma. Valide após cada etapa. Esta é a prática mais importante para evitar bugs. - As cores estão no intervalo 0-1 (não 0-255):
{r: 1, g: 0, b: 0}= vermelho - Preenchimentos/contornos são arrays somente leitura: clone, modifique, reatribua
- Toda edição de texto segue a receita canônica: carregar fonte →
await→ mutar → retornar IDs de nós afetados. Pular o carregamento lançaCannot write to node with unloaded font "<family> <style>". A regra cobre mais do quecharacters: aplica-se a qualquer operação em nós com fontes não carregadas (appendChild,insertChild,setBoundVariable,setExplicitVariableModeForCollection,setValueForMode, callbacksfindAlltocando texto). Ao mutar texto existente, carregue as fontes atuais do nó viagetStyledTextSegments(['fontName']), não um padrão codificado. Inter é pré-carregado na maioria dos ambientes, então outras famílias revelam esse bug com mais frequência. A receita é a mesma para cada fonte. Useawait figma.listAvailableFontsAsync()primeiro se a string de estilo não for verificada. Veja Receita canônica de edição de texto. - As páginas carregam incrementalmente: use
await figma.setCurrentPageAsync(page)para alternar páginas e carregar seu conteúdo. O setter síncronofigma.currentPage = pageNÃO funciona e lançará um erro (veja Regras de Página abaixo) setBoundVariableForPaintretorna uma NOVA pintura, é necessário capturar e reatribuircreateVariableaceita coleção como objeto ou string de ID (objeto preferido)layoutSizingHorizontal/Verticalé restrito a valores dependendo do contexto estrutural;FIXEDsempre funciona,HUGeFILLnão.'HUG'é válido apenas em um frame de auto-layout em si OU em um filho TEXT de um.'FILL'é válido apenas em um filho de um frame de auto-layout que também não está em posição absoluta, não está dentro de um frame imutável e não é filho de uma grade de tela. Consequência prática: anexe a um pai de auto-layout PRIMEIRO, depois definaHUG/FILL: um nó recém-criado ou não parente ainda não pode satisfazer a regra. A propriedade em si existe em todoSceneNode; o erro é de rejeição de valor, não "propriedade inexistente". Veja Armadilhas. 12a. Use auto-layout para contêineres que contêm filhos relacionados. Quando os filhos têm uma relação estrutural, empilhados, lado a lado, alinhados, com espaçamento, apertados, envolva-os emfigma.createAutoLayout(), não emfigma.createFrame()comx/yabsolutos. Coordenadas absolutas governam onde um contêiner fica na tela; auto-layout governa como seus filhos se relacionam dentro dele. Pular o contêiner não deixa proteção contra refluxo de texto, alterações de conteúdo ou sobreposição.- Posicione novos nós de nível superior longe de (0,0). Nós anexados diretamente à página padrão ficam em (0,0). Escaneie
figma.currentPage.childrenpara encontrar uma posição livre (ex.: à direita do nó mais à direita). Isso só se aplica a nós no nível da página; nós aninhados dentro de outros frames ou contêineres de auto-layout são posicionados pelo pai. Veja Armadilhas. - Em erro do
use_figma, PARE. NÃO tente novamente imediatamente. Scripts com falha são atômicos: se um script erra, ele não é executado e nenhuma alteração é feita no arquivo. Leia a mensagem de erro com cuidado, corrija o script e tente novamente. Veja Recuperação de Erros. - DEVE
returnTODOS os IDs de nós criados/mutados. Sempre que um script cria novos nós ou muta nós existentes na tela, colete cada ID de nó afetado e retorne-os em um objeto estruturado (ex.:return { createdNodeIds: [...], mutatedNodeIds: [...] }). Isso é essencial para que chamadas subsequentes possam referenciar, validar ou limpar esses nós. - Sempre defina
variable.scopesexplicitamente ao criar variáveis. O padrãoALL_SCOPESpolui todos os seletores de propriedade, quase nunca é o que você deseja. Use escopos específicos como["FRAME_FILL", "SHAPE_FILL"]para fundos,["TEXT_FILL"]para cores de texto,["GAP"]para espaçamento, etc. Veja variable-patterns.md para a lista completa. - Use
awaitem toda Promise. Nunca deixe uma Promise semawait; chamadas assíncronas semawait(ex.:figma.loadFontAsync(...)semawait, oufigma.setCurrentPageAsync(page)semawait) serão disparadas e esquecidas, causando falhas silenciosas ou condições de corrida. O script pode retornar antes da operação assíncrona ser concluída, levando a dados ausentes ou alterações aplicadas pela metade.
Para exemplos detalhados ERRADOS/CORRETOS de cada regra, veja Armadilhas e Erros Comuns.
2. Regras de Página (Críticas)
O contexto da página é redefinido entre chamadas use_figma: figma.currentPage começa na primeira página a cada vez.
Alternando páginas
Use await figma.setCurrentPageAsync(page) para alternar páginas e carregar seu conteúdo. O setter síncrono figma.currentPage = page NÃO funciona: lança "Setting figma.currentPage is not supported" em use_figma. Sempre use o método assíncrono.
// Alterna para uma página específica (carrega seu conteúdo)
const targetPage = figma.root.children.find((p) => p.name === "My Page");
await figma.setCurrentPageAsync(targetPage);
// targetPage.children agora está populado
Chame setCurrentPageAsync no máximo uma vez por invocação de use_figma, distribua trabalhos de várias páginas em paralelo
Um script deve alternar páginas no máximo uma vez. Nunca loops sobre figma.root.children e alterne páginas dentro do loop.
Se o trabalho abranger várias páginas, divida-o em N chamadas use_figma (uma por página alvo) e emita-as em paralelo: uma única mensagem do assistente contendo N blocos de uso da ferramenta use_figma. O harness os executa simultaneamente; cada script define currentPage exatamente uma vez.
Instrução explícita: ao distribuir, você DEVE emitir as N chamadas de ferramenta em uma mensagem. Não as envie em várias rodadas. Não aguarde uma antes de emitir a próxima. Chamadas sequenciais por página são mais lentas que o padrão de loop que esta regra substitui e desperdiçam todo o benefício da divisão.
// EVITE, alterna páginas N vezes em um script, recarrega o arquivo a cada vez
for (const page of figma.root.children) {
await figma.setCurrentPageAsync(page);
// ... toque nesta página ...
}
// PREFIRA, chamada de descoberta somente leitura para obter IDs de página,
// depois, na PRÓXIMA mensagem, emita N chamadas de ferramenta use_figma em paralelo
// (uma por página), cada uma definindo currentPage uma vez.
Padrão para distribuição paralela para qualquer trabalho de várias páginas, leituras e escritas igualmente. Veja gotchas.md → Defina a página atual uma vez por chamada use_figma para a justificativa completa.
Entre execuções de script
figma.currentPage é redefinido para a primeira página no início de cada chamada use_figma. Se seu fluxo de trabalho abranger várias chamadas e tiver como alvo uma página não padrão, chame await figma.setCurrentPageAsync(page) no início de cada invocação.
Você pode chamar use_figma várias vezes para construir incrementalmente sobre o estado do arquivo, ou para recuperar informações antes de escrever outro script. Por exemplo, escreva um script para obter metadados sobre nós existentes, return esses dados, depois use-os em um script subsequente para modificar esses nós.
3. return É Seu Canal de Saída
O agente vê APENAS o valor que você retorna. Todo o resto é invisível.
- Retornar IDs (CRÍTICO): Todo script que cria ou muta nós na tela DEVE retornar todos os IDs de nós afetados, ex.:
return { createdNodeIds: [...], mutatedNodeIds: [...] }. Este é um requisito rigoroso, não opcional. - Relatório de progresso:
return { createdNodeIds: [...], count: 5, errors: [] } - Informações de erro: Erros lançados são capturados e retornados automaticamente; apenas deixe-os propagar ou
throwexplicitamente. - A saída de
console.log()nunca é retornada ao agente - Sempre retorne dados acionáveis (IDs, contagens, status) para que chamadas subsequentes possam referenciar objetos criados
4. Modo Editor
use_figma funciona no modo design (editorType "figma", o padrão). FigJam ("figjam") e Slides ("slides") têm conjuntos diferentes de tipos de nó disponíveis. A maioria dos nós de design é bloqueada no FigJam, e nós exclusivos do FigJam são bloqueados no Slides.
Identifique o editor pela URL: Design = figma.com/design/..., FigJam = figma.com/board/..., Slides = figma.com/slides/.... Confirme antes de assumir que uma API está disponível.
Disponível no modo design: Rectangle, Frame, Component, Text, Ellipse, Star, Line, Vector, Polygon, BooleanOperation, Slice, Page, Section, TextPath.
Bloqueados no modo design: Sticky, Connector, ShapeWithText, CodeBlock, Slide, SlideRow, SlideGrid, InteractiveSlideElement, Webpage.
Disponíveis no modo Slides: Rectangle, Frame, Component, Text, Ellipse, Star, Line, Vector, Polygon, BooleanOperation, Slice, Section, TextPath, Slide, SlideRow, SlideGrid, InteractiveSlideElement.
Bloqueados no modo Slides: Sticky, Connector, ShapeWithText, CodeBlock, Webpage, Page.
APIs exclusivas do design (não apenas tipos de nó): figma.createPage() está disponível apenas em arquivos Design (figma.com/design/...). Tanto no FigJam (figma.com/board/...) quanto no Slides (figma.com/slides/...) ele lança TypeError: figma.createPage no such property 'createPage' on the figma global object. Não emita figma.createPage() em fluxos de trabalho do FigJam ou Slides.
Nota sobre Slides: Ainda não existe uma ferramenta de leitura dedicada para arquivos Slides. Use
use_figmacom scripts somente leitura para inspeção (veja a Seção 6 "Inspecionar primeiro"), eget_screenshot/await node.screenshot()para contexto visual. Para orientação específica da API do Slides, carregue o skill figma-use-slides.
5. APIs Eficientes. Prefira Estas em Vez de Alternativas Verbosas
Essas APIs reduzem o boilerplate, eliminam erros de ordenação e comprimem a saída de tokens. Sempre prefira-as em vez das alternativas verbosas.
node.query(selector): Pesquisa de nós estilo CSS
Encontre nós dentro de uma subárvore usando seletores estilo CSS. Substitui loops verbosos de findAll + filtro.
// ANTES, travessia verbosa
const texts = frame.findAll(n => n.type === 'TEXT' && n.name === 'Title')
// DEPOIS, one-liner com query
const texts = frame.query('TEXT[name=Title]')
Sintaxe do seletor:
- Tipo:
FRAME,TEXT,RECTANGLE,ELLIPSE,COMPONENT,INSTANCE,SECTION(insensível a maiúsculas/minúsculas) - Atributo exato:
[name=Card],[visible=true],[opacity=0.5] - Substring de atributo:
[name*=art](contém),[name^=Header](começa com),[name$=Nav](termina com) - Travessia por caminho de ponto:
[fills.0.type=SOLID],[fills.*.type=SOLID](índice curinga) - Correspondência de instância:
[mainComponent=nodeId],[mainComponent.name=Button] - Combinadores:
FRAME > TEXT(filho direto),FRAME TEXT(qualquer descendente),A + B(irmão adjacente),A ~ B(irmão geral) - Pseudo-classes:
:first-child,:last-child,:nth-child(2),:not(TYPE),:is(FRAME, RECTANGLE),:where(TEXT, ELLIPSE) - ID do nó:
#nodeIdou GUID simples - Vírgula:
TEXT, RECTANGLE(união)
Sempre que possível, prefira node.query() em vez de findAll() + lógica de filtro personalizada. Use findAll apenas quando a lógica de filtro for complexa demais para um único seletor (ex.: múltiplas condições OR em propriedades diferentes, geração dinâmica de condições).
figma.group(groupedNodes, parent, index): Agrupamento eficiente
Agrupa nós em um único frame GROUP. Muito mais curto que criar um frame, definir preenchimento e contorno, e reposicionar.
// Agrupa rect e text dentro de frame
const group = figma.group([rect, text], frame, 0)
// Afunila filho único (se group tiver apenas um filho, aplana o grupo)
figma.ungroup(group)
figma.combineAsVariants(nodes, parent, index): Criação de conjuntos de variantes
Combina componentes em um conjunto de variantes. Muito mais curto que criar manualmente um ComponentSet.
const variantSet = figma.combineAsVariants([primary, secondary, tertiary], frame, 0)
figma.createTable(options): Criação rápida de tabelas
Cria uma tabela completamente estilizada a partir de dados. A opção withHeaders torna a primeira linha cabeçalho.
const table = figma.createTable({
rows: 3,
columns: 4,
cellWidth: 100,
cellHeight: 40,
withHeaders: true,
parent: page
})
figma.createGrid(): Layout de grade de componentes
Cria uma grade de componentes a partir de uma matriz de arrays. Cada subarray é uma linha.
const grid = figma.createGrid([
[componentA, componentB, componentC],
[componentD, componentE, componentF]
], {
parent: page,
itemSpacing: 10
})
figma.color.rgb(colorName): Cores nomeadas
Retorna um objeto {r, g, b} de uma paleta limitada de nomes de cores do Figma (red, green, blue, white, black, yellow, cyan, magenta, orange, purple, grey/gray, transparent, none). As strings de cores hex/rgb/hsl NÃO são convertidas. Prefira figma.util.decimalToHex(color) para conversão decimal → hex.
const red = figma.color.rgb('red') // {r: 1, g: 0, b: 0}
const white = figma.color.rgb('white') // {r: 1, g: 1, b: 1}
const transparent = figma.color.rgb('transparent') // {r: 0, g: 0, b: 0, a: 0}
figma.object: Atalho para identidade de tipos
Usado em arrays de documentos e findAll callbacks para verificar o tipo do nó. Mais curto que escrever figma[type].
const frames = page.findAll(node => node.type === figma.object.FRAME)
Acessível como figma.object ou importação nomeada. Tipos disponíveis: FRAME, GROUP, BOOLEAN_OPERATION, COMPONENT, INSTANCE, COMPONENT_SET, ELLIPSE, POLYGON, RECTANGLE, STAR, LINE, VECTOR, TEXT, SLICE, SECTION, PAGE, STICKY, CONNECTOR, SHAPE_WITH_TEXT, CODE_BLOCK, STAMP, WIDGET, EMBED, LINK_UNFURL, MEDIA, TABLE.
figma.mixed: Identificador para valores mistos
if (node.opacity === figma.mixed) {
// Trata valores mistos
}
figma.util: Funções utilitárias
figma.util.decimalToHex(decimal): decimal → string hex (#RRGGBB)figma.util.hexToDecimal(hex): string hex (#RGB, #RRGGBB, ou #RGBA) → decimalfigma.util.roundNumber(value): arredonda para 2 casas decimais
figma.createComponent() com createInstance(): Reutilização de componentes
Ao criar múltiplos nós semelhantes, defina um componente base e crie instâncias.
const baseButton = figma.createComponent()
baseButton.name = 'Button'
const instance1 = baseButton.createInstance()
const instance2 = baseButton.createInstance()
6. Estratégia de Recuperação de Erros e Autocorreção
Quando um script use_figma falha, o harness retorna uma mensagem de erro que inclui a mensagem de erro exata do mecanismo de script. Sempre leia-a completamente antes de tentar novamente. Não é necessário adivinhar; o erro é fornecido.
Causas comuns e como corrigi-las
| Erro | Causa Provável | Correção |
|---|---|---|
Cannot write to node with unloaded font | Fonte não carregada antes de editar texto | Siga a receita canônica de edição de texto (Regra 8) |
Cannot read properties of undefined (reading '...') | ID de nó não válido ou não existe | Verifique se o ID foi retornado corretamente da chamada anterior |
figma.createPage no such property 'createPage' | Modo de editor incorreto (FigJam/Slides) | Mude para um arquivo Design |
Setting figma.currentPage is not supported | currentPage usado como setter síncrono | Use await figma.setCurrentPageAsync() |
Expected 0-1 range | Valor de cor não normalizado | Converta valores 0-255 para 0-1 |
| Valor de layoutSizingVertical/Horizontal rejeitado | Contexto estrutural não suporta o valor | Anexe ao pai auto-layout primeiro, depois defina |
| Erro de tempo limite (timeout) | Script muito grande ou complexo | Divida em chamadas menores e mais focadas |
Tente novamente com alterações mínimas
Após um erro, não reescreva o script inteiro. Faça a correção mínima necessária e tente novamente. Tenha cuidado especial com:
- Nomes de propriedades – a API do Figma é sensível a maiúsculas/minúsculas.
- Async/await – esqueceu um
await? - IDs de nós – eles são consistentes entre chamadas? (Dica: sempre retorne IDs de nós recém-criados)
- Modo de editor – você está no modo Design, FigJam ou Slides?
Padrão "Inspecionar Primeiro" para scripts complexos
Para operações complexas (especialmente ao modificar estruturas existentes), use primeiro um script de descoberta para coletar informações, depois escreva o script de modificação com base no que aprendeu:
// Passo 1: Descobrir
const page = figma.root.children.find(p => p.name === "My Page");
await figma.setCurrentPageAsync(page);
const target = page.findOne(n => n.name === "Target");
return {
id: target.id,
type: target.type,
childrenCount: target.children.length,
fills: target.fills,
strokes: target.strokes
}
// Passo 2: Modificar (usa dados do Passo 1)
const page = figma.root.children.find(p => p.name === "My Page");
await figma.setCurrentPageAsync(page);
const target = page.findOne(n => n.id === "<id from step 1>");
// ... modifica com conhecimento total do estado
return { mutatedNodeIds: [target.id] }
7. Abordagens para Grandes Scripts
Divisão Funcional (Recomendado)
Divida um script em múltiplas chamadas use_figma, cada uma fazendo uma operação bem definida:
- Chamada 1: Crie estrutura de páginas e contêineres
- Chamada 2: Popule com conteúdo
- Chamada 3: Aplique estilos e variáveis
- Chamada 4: Valide e retorne resultados
Quando usar um script maior (Menos Recomendado)
- Quando a operação é atômica (tudo ou nada)
- Quando você precisa ler o estado em uma chamada e depois modificá-lo, e dividir adicionaria complexidade devido à passagem de estado entre chamadas
- Ao criar uma única tela com muitas partes que compartilham contexto
Divisão Inteligente: A Abordagem Equilibrada
Para construções de tela típicas, divida em:
- Script de definição: crie nós, defina relações pai-filho, retorne IDs
- Script de estilo: aplique preenchimentos, contornos, cores, efeitos
- Script de conteúdo: popule texto, imagens
- Script de variáveis: vincule variáveis a propriedades
Cada script retorna seus IDs de nós criados/mutados para o próximo script consumir.
8. Trabalhando com Sistemas de Design
Quando solicitado a trabalhar com um sistema de design Figma:
- Comece com working-with-design-systems/wwds.md
- Carregue
node.query()para encontrar componentes rapidamente - Use
search_design_system(via MCP ou manualmente) para descobrir componentes disponíveis - Crie instâncias de componentes do sistema de design e personalize-as através de propriedades de componentes
- Vincule variáveis de design token a propriedades via
setBoundVariablee APIs relacionadas
API de vinculação de variáveis
// Vincula uma variável a uma propriedade de preenchimento
const boundPaint = figma.mix.setBoundVariableForPaint(target.fills[0], variable)
target.fills = [boundPaint]
// Vincula uma variável a uma propriedade de texto
await target.setBoundVariable('fontSize', variable)
// Define o modo de coleção para um nó
target.setExplicitVariableModeForCollection(collection, modeId)
Veja variable-patterns.md para mais padrões.
9. Otimizações e Padrões
Processamento em lote
Em vez de fazer chamadas individuais para cada nó, processe em lote dentro de um único script:
const page = figma.root.children.find(p => p.name === "My Page");
await figma.setCurrentPageAsync(page);
const allTexts = page.findAll(n => n.type === "TEXT" && n.characters.includes("old"));
const updatedIds = [];
for (const text of allTexts) {
const fonts = text.getStyledTextSegments(['fontName']);
for (const segment of fonts) {
await figma.loadFontAsync(segment.fontName);
}
text.characters = text.characters.replace(/old/g, "new");
updatedIds.push(text.id);
}
return { mutatedNodeIds: updatedIds, count: updatedIds.length }
Reutilização de resultados de descoberta
Use uma chamada de descoberta para coletar informações, depois várias chamadas paralelas para modificar:
// Descoberta
const page = figma.root.children.find(p => p.name === "My Page");
await figma.setCurrentPageAsync(page);
const targets = page.query("COMPONENT, INSTANCE");
return targetIds: targets.map(n => ({ id: n.id, type: n.type, name: n.name }))
// Em seguida, emita N chamadas paralelas, cada uma segmento de targetIds
Padrão de componente de design preferido: Pesquisar → Importar → Construir
- Pesquisar: Use
search_design_systempara encontrar componentes - Importar: Use
get_component(se disponível) ou crie instâncias manualmente - Construir: Componha com auto-layout, vinculação de variáveis e variações
Isso se alinha com os fluxos de trabalho em figma-generate-design e figma-generate-library.
Referências
- plugin-api-standalone.index.md — Índice da documentação da API
- plugin-api-standalone.d.ts — Arquivo de declaração de tipos completo (pesquise seções relevantes)
- gotchas.md — Armadilhas e exemplos corrigidos para cada regra
- variable-patterns.md — Padrões para criar e vincular variáveis
- working-with-design-systems/wwds.md — Guia de sistemas de design
- figma-generate-design — Fluxo de trabalho de construção de telas
- figma-generate-library — Fluxo de trabalho de criação de componentes