Figma Plugins — Automatizando Fluxos de Design com JavaScript

Figma se tornou a ferramenta central do fluxo de design de produto, mas tarefas repetitivas ainda consomem tempo significativo de designers: renomear camadas em lote, preencher componentes com dados reais, manter tokens sincronizados, exportar assets em formatos específicos. A Figma Plugin API permite automatizar exatamente essas tarefas com JavaScript — e o espaço entre o que a ferramenta oferece nativamente e o que um plugin customizado pode fazer é enorme. Este artigo examina a arquitetura da Plugin API, os padrões de desenvolvimento mais úteis e casos de uso que justificam o investimento.

Arquitetura de um plugin Figma

Um plugin Figma tem dois ambientes de execução separados com funções distintas:

Plugin sandbox (main.ts): Executa no contexto do Figma, com acesso à `figma` API global para manipular o documento — ler e modificar nós, propriedades de componentes, variáveis, estilos. Não tem acesso ao DOM do browser nem pode fazer requisições HTTP diretamente (por razões de segurança).

UI (ui.html): Um iframe que executa no browser, com acesso ao DOM, às APIs web e à capacidade de fazer fetch para APIs externas. A UI não tem acesso direto à `figma` API.

A comunicação entre os dois ambientes é feita via mensagens:

```typescript // main.ts → ui.html figma.ui.postMessage({ type: 'nodes-selected', data: selectedNodes });

// ui.html → main.ts parent.postMessage({ pluginMessage: { type: 'apply-styles', payload: stylesData } }, '*');

// Recebendo em main.ts figma.ui.onmessage = (msg) => { if (msg.type === 'apply-styles') { applyStylesToSelection(msg.payload); } }; ```

Esse modelo de mensagens é a base de todo desenvolvimento de plugin. A UI busca dados externos e passa para o main; o main manipula o documento e notifica a UI do resultado.

Manipulação de nós: fundamentos da Figma API

A Figma API representa o documento como uma árvore de nós com tipos específicos: `DocumentNode`, `PageNode`, `FrameNode`, `ComponentNode`, `InstanceNode`, `TextNode`, `RectangleNode`, entre outros. Cada tipo tem propriedades específicas que podem ser lidas e modificadas.

```typescript // Iterar sobre a seleção atual figma.currentPage.selection.forEach(node => { if (node.type === 'TEXT') { node.characters = node.characters.toUpperCase(); node.setRangeFontStyle(0, node.characters.length, 'Bold'); } });

// Criar um novo retângulo const rect = figma.createRectangle(); rect.x = 100; rect.y = 100; rect.resize(200, 100); rect.fills = [{ type: 'SOLID', color: { r: 0.2, g: 0.4, b: 1 } }]; figma.currentPage.appendChild(rect); ```

Trabalhando com componentes e instâncias

Um dos casos de uso mais valiosos em plugins é manipular instâncias de componentes em lote — trocar o valor de uma propriedade em centenas de instâncias de uma só vez, por exemplo.

```typescript // Encontrar todas as instâncias de um componente específico const instances = figma.currentPage.findAllWithCriteria({ types: ['INSTANCE'] }).filter(node => node.mainComponent?.name === 'Card/Product');

// Atualizar uma propriedade de componente em todas as instâncias instances.forEach(instance => { instance.setProperties({ 'Variant': 'Compact' }); }); ```

Integrando dados externos

Um dos usos mais impactantes de plugins é preencher designs com dados reais em vez de lorem ipsum. Conectar o Figma a uma API de produtos, uma planilha, um CMS ou um banco de dados interno transforma mockups estáticos em representações muito mais próximas do produto real.

```typescript // ui.html: busca dados e envia para o plugin async function fetchAndPopulate() { const response = await fetch('https://api.seu-produto.com/products?limit=10'); const products = await response.json(); parent.postMessage({ pluginMessage: { type: 'populate-cards', data: products } }, '*'); }

// main.ts: recebe os dados e popula os nós figma.ui.onmessage = async (msg) => { if (msg.type === 'populate-cards') { const frames = figma.currentPage.selection; msg.data.forEach((product, i) => { if (frames[i]?.type === 'FRAME') { const titleNode = frames[i].findOne(n => n.name === 'title' && n.type === 'TEXT') as TextNode; if (titleNode) titleNode.characters = product.name; } }); figma.notify('Cards populados com dados reais!'); } }; ```

Casos de uso que justificam um plugin customizado

Com base nos plugins que desenvolvemos internamente e para clientes, os casos de maior retorno são:

Sincronização de tokens com o repositório: Um plugin que lê os tokens do design system diretamente do repositório Git (via GitHub API) e atualiza as variáveis do Figma automaticamente elimina a necessidade de atualização manual quando há mudanças nos tokens.

Auditoria de inconsistências: Plugins que percorrem o documento identificando componentes que não usam estilos do design system, textos com propriedades hardcoded em vez de variáveis, ou instâncias desconectadas do componente master são ferramentas poderosas para manter a qualidade do arquivo ao longo do tempo.

Geração de specs de handoff: Exportar automaticamente as especificações de um componente (propriedades, variantes, tokens utilizados) para um formato consumível por desenvolvedores reduz o trabalho manual de documentação.

Preenchimento com conteúdo real: Para e-commerces, plugins que conectam ao catálogo de produtos e preenchem automaticamente imagens, títulos e preços em templates de página economizam horas em apresentações para clientes.

Publicação e distribuição interna

Plugins podem ser publicados na Figma Community (público) ou distribuídos privativamente para uma organização via Figma Organization (apenas membros da org têm acesso). Para design systems internos com dados sensíveis ou integrações proprietárias, a distribuição privada é o caminho correto.

O investimento em um plugin customizado geralmente se paga rapidamente: se um designer gasta 30 minutos por semana em uma tarefa repetitiva e um plugin reduz isso para 2 minutos, o retorno é evidente. Multiplique por um time de 10 designers e o impacto acumulado ao longo de um ano é substancial.