Figma Code Connect na prática: ligando seu design system ao código para o handoff com IA

O problema não é novo: o dev abre o Dev Mode, copia o snippet autogerado do Figma↳Figma3 conteúdosFigma Dev Mode funciona mesmo? Testando na práticaDev (Back & Front) · mar 2025Claude Design: nova aposta da Anthropic contra Figma e MicrosoftProduto & UX · abr 2026A importância do HTML e CSS para quem trabalha com UI Design e Design SystemProduto & UX · dez 2024Ver tudo em Produto & UX → e recebe um genérico que não tem nada a ver com o do design system da empresa. Aí ele reescreve tudo na mão. Com IA↳Inteligência artificial440 conteúdosUX e IA: Transformando Experiências Digitais com Inteligência ArtificialProduto & UX · jan 2025MCP: O que é e por que você vai ouvir falar disso em breve?AI · jul 2025IA generativa e a urgência de reconstruir nossa relação com a verdadeAI · jun 2025Ver tudo em AI → no editor (Copilot, Cursor), o problema piora de um jeito silencioso: o agente gera código plausível, mas inventa nomes de componentes e props que não existem no seu repositório. O Code Connect ataca exatamente isso, servindo de ponte entre o componente no Figma e o componente real no seu código, e virando contexto para o MCP server guiar o agente com referências ao SEU código, não a um chute.

Vou mostrar o caminho que eu seguiria para conectar dois componentes reais, um Button e um Card, publicar, plugar no editor com IA e comparar a geração antes e depois. Uso a abordagem de template files, que é a recomendada na documentação por ser agnóstica de framework.

Pré-requisitos que ninguém te conta antes

Antes de instalar qualquer coisa, dois pontos de fricção reais para times brasileiros:

• Plano e seat. Segundo a doc, o Code Connect está disponível em um Dev ou Full seat nos planos Organization e Enterprise. Se o seu time está no plano Professional, isso já para a brincadeira. Vale confirmar antes de prometer a feature para a liderança.
• Node instalado para rodar a CLI, e acesso de escrita ao repositório do design system.

Instalação da CLI no projeto do design system:

npm install --save-dev @figma/code-connect

Você também vai precisar de um token de acesso pessoal do Figma com escopo de Code Connect, exportado como variável de ambiente (FIGMA_ACCESS_TOKEN). Guarde num .env fora do controle de versão.

Conectando o Button com um template file

A ideia do template file é você escrever, em TypeScript↳TypeScript23 conteúdosTypeScript: ReadonlyArrayDev (Back & Front) · jun 2019Onde usar ANY no TypeScriptDev (Back & Front) · out 2025Tudo sobre o Node rodar TypeScript nativamente!Dev (Back & Front) · jul 2025Ver tudo em Dev (Back & Front) →, exatamente como o snippet deve aparecer no Dev Mode. Nada de código autogerado: sai o que você escreveu. A doc traz este esqueleto para um botão, que é um bom ponto de partida:

// Button.figma.ts
// url=https://www.figma.com/file/your-file-id/Button?node-id=123
import figma from 'figma'

const instance = figma.selectedInstance

export default {
  example: figma.code`
    <Button
      size={${instance.getEnum('Size', { Large: 'large', Medium: 'medium', Small: 'small' })}}
      disabled={${instance.getBoolean('Disabled')}}
    >
      ${instance.getString('Text Content')}
    </Button>
  `,
  imports: ['import { Button } from "components/Button"'],
  id: 'button',
}

Repare no que está acontecendo aqui, porque é onde mora a maior parte dos tropeços:

• getEnum('Size', {...}) mapeia a property variante chamada Size no Figma para os valores que o seu componente React espera (large, medium, small).
• getBoolean('Disabled') lê uma property booleana.
• getString('Text Content') puxa o texto da instância.

O comentário // url= no topo é o que amarra este arquivo ao componente no Figma. Sem ele apontando para o node-id certo, a publicação não sabe onde encaixar.

O tropeço número um: nome de property não bate

O erro que mais aparece nessa hora é banal e travador: o nome passado para getEnum / getBoolean precisa ser idêntico ao nome da property no Figma, incluindo maiúsculas e espaços. Se no arquivo de design a variante se chama Tamanho (porque o time BR nomeou em português) e você escreveu Size, o mapeamento falha silenciosamente ou vem vazio.

O caminho que eu seguiria para não perder tempo: abrir o componente no Figma, olhar o painel de propriedades e copiar o nome exato, com acento e tudo. Se a variante for Tamanho com valores Grande / Médio / Pequeno, o mapa vira:

size={${instance.getEnum('Tamanho', { Grande: 'large', 'Médio': 'medium', Pequeno: 'small' })}}

A chave do objeto é o valor no Figma; o valor é o que vai para o código. Inverter isso é o segundo tropeço mais comum.

Conectando o Card e lidando com o slot de conteúdo

O Card costuma ser mais chato que o botão porque tem conteúdo composto: título, corpo, talvez uma imagem e um rodapé. Componentes com filhos não cabem num getString só. A estratégia que funciona é mapear as properties atômicas (variante de elevação, estado hasImage) e deixar o children explícito no template:

// Card.figma.ts
// url=https://www.figma.com/file/SEU-FILE-ID/DesignSystem?node-id=456
import figma from 'figma'

const instance = figma.selectedInstance

export default {
  example: figma.code`
    <Card
      elevation={${instance.getEnum('Elevation', { Flat: 'flat', Raised: 'raised' })}}
      hasImage={${instance.getBoolean('Show Image')}}
    >
      <Card.Title>${instance.getString('Title')}</Card.Title>
      <Card.Body>${instance.getString('Body')}</Card.Body>
    </Card>
  `,
  imports: ['import { Card } from "components/Card"'],
  id: 'card',
}

Aqui já dá para deixar o agente de IA com a estrutura de subcomponentes (Card.Title, Card.Body) que o seu design system realmente usa, em vez de uma div chapada.

Publicando

Com os dois arquivos prontos, a publicação torna os componentes visíveis no Dev Mode com os snippets true-to-production:

npx figma connect publish

Segundo a doc, uma vez publicados, os componentes passam a exibir no Dev Mode os snippets fiéis à produção do seu design system, no lugar dos exemplos autogerados. Vale um detalhe operacional: conexões criadas pela CLI aparecem também na Code Connect UI, mas só podem ser editadas pela CLI. Ou seja, o dono da verdade continua sendo o repositório, e isso é bom para governança.

Plugando o Dev Mode MCP Server no editor com IA

A parte que fecha o ciclo é o MCP server do Figma. É ele que carrega as conexões do Code Connect e as entrega como contexto para o agente. A doc é explícita: em ambos os casos (UI ou CLI) as conexões são usadas para fornecer mais contexto de código via MCP server.

No Cursor ou no VS Code com Copilot, você registra o servidor MCP do Figma na configuração de MCP do editor. Feito isso, com um frame selecionado no Dev Mode, o agente passa a ter acesso às referências reais dos seus componentes.

Antes e depois: o que muda na tela gerada

O teste honesto é pedir a mesma coisa ao agente nos dois cenários. Um prompt do tipo "gere a tela de checkout a partir deste frame":

Na prática (e isso é leitura minha, não medição), o ganho não é a tela sair "pronta", é o agente parar de alucinar a API dos seus componentes. Quando o import e o nome da prop vêm do seu próprio repositório, o dev revisa em vez de reescrever.

O que fica em aberto

Dois pontos merecem atenção antes de escalar para o design system inteiro. Primeiro, acessibilidade não vem de graça no snippet: se o seu Button exige aria-label quando é só ícone, isso precisa estar no template, senão o agente reproduz um componente inacessível com cara de aprovado. Coloque os atributos de acessibilidade obrigatórios no figma.code do próprio Code Connect, tratando-os como parte da definição de pronto. Segundo, a doc menciona conexões one-to-many na UI (um componente de design mapeado para React, SwiftUI, Vue, Compose) e recursos de mapeamento automatizado como algo que ainda está por vir. Para um time BR com web e mobile no mesmo design system, isso é o que decide se o esforço escala ou vira dívida de manutenção.

Referência para começar: Code Connect Docs.

Fonte: Figma — Code Connect Docs