Design systems · Passo 5 · 8 min de leitura
Code Connect e a ponte entre design e código
Um componente no Figma e um componente no código são duas coisas que deveriam ser uma só. Como manter os dois juntos: nomes compartilhados, um mapeamento escrito das propriedades do Figma para as props do código, e o Code Connect do Figma, que mostra o código real no Dev Mode. O que ele exige, em quais planos está e onde ele para.
Todo design system tem duas cópias de cada componente, e o sistema é a promessa de que elas são iguais. O Button do Figma e o Button do código foram feitos por pessoas diferentes, em ferramentas diferentes, em momentos diferentes. Sozinhos, eles se afastam: uma variante nova aqui, uma prop renomeada ali. A ponte entre os dois não é uma ferramenta. É um mapeamento que tem dono, e uma ferramenta que mostra esse mapeamento onde quem desenvolve está olhando.
O que você vai conseguir fazer depois de ler:
- Explicar por que os componentes de design e de código se afastam, e onde
- Escrever o mapeamento de propriedades entre um componente do Figma e um do código
- Descrever o que o Code Connect do Figma faz e o que ele exige
- Decidir o que conectar primeiro e quem mantém isso atualizado
1. Onde as duas cópias se afastam
O afastamento começa pequeno. Alguém do design adiciona uma variante Tertiary no Figma para uma tela. Alguém do desenvolvimento adiciona loading ao Button do código e nunca conta para o design. Seis meses depois, o Button do Figma tem onze variantes, o do código tem sete props, e um handoff vira uma negociação. Handoff para desenvolvedores mostra o que especificar para uma tela; aqui a pergunta é como impedir que o próprio sistema se divida em dois.
Três coisas mantêm as cópias juntas:
- Os mesmos nomes, sempre que der. Mesmo nome de componente, mesmos nomes de propriedade, mesmos nomes de opção.
- Um mapeamento escrito para cada lugar onde os nomes não podem ser iguais.
- Um lugar onde quem desenvolve vê o mapeamento na hora de construir, sem precisar lembrar.
2. O mapeamento, por escrito
- Variant variante: Primary · Secondary · Danger
variant'primary' · 'secondary' · 'danger' - Density variante: Comfortable · Compact
size'default' · 'compact' - Label propriedade de texto
childrenstring - Disabled propriedade booleana
disabledtrue · false - Show icon propriedade booleanasem prop própria: no código o ícone aparece quando é passado (fora deste arquivo)
// url=https://www.figma.com/design/FILE/Harbour-Components?node-id=12-34
// source=src/components/Button.tsx
// component=Button
import figma from 'figma'
const instance = figma.selectedInstance
const label = instance.getString('Label')
const disabled = instance.getBoolean('Disabled')
const variant = instance.getEnum('Variant', {
Primary: 'primary',
Secondary: 'secondary',
Danger: 'danger',
})
const size = instance.getEnum('Density', {
Comfortable: 'default',
Compact: 'compact',
})
export default {
example: figma.code`<Button variant="${variant}" size="${size}" disabled={${disabled}}>${label}</Button>`,
imports: ['import { Button } from "@tidewater/harbour"'],
id: 'harbour-button',
}
Comece com uma tabela, antes de qualquer ferramenta. Para cada componente do Harbour, liste cada propriedade do Figma, o tipo dela e a prop do código em que ela se transforma. As regras são simples:
- Propriedades de variante viram enums.
Variant: Primary→variant="primary". As mesmas opções, na mesma ordem. - Propriedades de texto viram strings ou children.
Label→ o texto do botão. - Booleanas viram booleanas, a não ser que só mostrem ou escondam uma camada, como um ícone. Aí o código pode não ter prop nenhuma: ele mostra o ícone quando um ícone é passado.
- Instance swaps viram componentes aninhados. O ícone é um componente próprio, mapeado uma vez.
- Algumas propriedades só existem de um lado.
loadingpode ser só do código; uma propriedade do Figma para "mostrar texto de exemplo" é só do design. Anote essas também, para ninguém achar que estão faltando.
Um mapeamento sem buracos é sinal de um componente saudável. Um mapeamento cheio de "só design" e "só código" é um componente que precisa de uma conversa, e provavelmente de uma mudança num dos lados.
3. O que o Code Connect faz
O Code Connect do Figma é "a bridge between your codebase and Figma's Dev Mode", uma ponte entre o repositório e o Dev Mode: ele liga componentes do repositório a componentes dos arquivos de design, e o Dev Mode passa a mostrar "the true-to-production code snippets from your design system", os trechos de código reais do seu design system, em vez de exemplos gerados automaticamente (Figma developer docs, Code Connect). Quando alguém inspeciona um Button do Harbour que o design configurou como Danger e Compact, o Dev Mode mostra <Button variant="danger" size="compact">, com o import, e não uma pilha de CSS.
Há dois jeitos de configurar (Figma developer docs, Code Connect):
- Code Connect UI, dentro do Figma, ligando componentes ao código com uma integração com o GitHub. Ele consegue mapear um componente de design para implementações em vários frameworks.
- Code Connect CLI, no repositório. Você escreve arquivos de template (
Button.figma.ts) e publica comnpx figma connect publish(Figma, Writing template files). Hoje o Figma chama os arquivos de template de "the only actively maintained way of using Code Connect", o único jeito mantido ativamente; os parsers antigos de cada framework (React, SwiftUI, Compose, a integração com o Storybook) estão marcados como legado (Figma, Connecting React components).
As conexões criadas pela CLI aparecem na UI, mas "can only be edited in the CLI", só podem ser editadas na CLI. O template da figura segue esse formato: cada getEnum, getBoolean e getString lê uma propriedade do Figma, e figma.code monta o trecho.
Plano e assento: o Code Connect está "available on a Dev or Full seat on the Professional, Organization, and Enterprise plans", disponível com assento Dev ou Full nos planos Professional, Organization e Enterprise. O Professional "can have one active library and one active framework", uma biblioteca e um framework ativos; Organization e Enterprise podem ter vários frameworks ativos (Figma developer docs, Code Connect). O próprio Dev Mode também é pago (veja Handoff para desenvolvedores).
4. A ponte também alimenta as ferramentas de IA
O Figma diz que as conexões "enhance the Figma MCP server's ability to guide AI agents with more precise implementation details", melhoram a capacidade do servidor MCP do Figma de orientar agentes de IA com detalhes de implementação mais precisos (Figma developer docs, Code Connect). Em palavras simples: quando alguém pede a uma ferramenta de IA de programação para construir uma tela a partir de um frame do Figma, um Button do Harbour conectado volta como o <Button> do Harbour, e não como um botão novo inventado a partir dos pixels. Um componente não conectado é exatamente onde a IA vai chutar. Esse é um motivo novo para conectar primeiro os componentes mais usados.
5. O que conectar primeiro, e quem cuida
- Comece pelos dez componentes mais usados. As análises de biblioteca (Organization e Enterprise, veja Medir a adoção) ou uma olhada nos últimos projetos mostram quais são.
- O arquivo de template mora com o código, ao lado do componente, e muda no mesmo pull request que o componente. Uma mudança no Button que não atualiza
Button.figma.tsnão está pronta. - Revise pelo lado do design. Alguém do design confere se toda propriedade do Figma está no mapeamento e se os nomes das opções batem.
- As variáveis precisam do mesmo cuidado. Configure a sintaxe de código de cada variável (veja Montar uma biblioteca no Figma), para as cores no Dev Mode dizerem
var(--hb-color-action-primary)e não#1F5FAE.
6. Erros comuns
- Esperar que a ferramenta conserte nomes que não batem. Ela só mostra o mapeamento que você escreveu.
- Conectar todos os componentes no primeiro dia e depois não manter nenhum.
- Arquivos de template que ninguém atualiza quando o componente muda.
- Começar trabalho novo nos parsers legados em vez dos arquivos de template.
- Esquecer o plano e o assento: configurar tudo num arquivo cujas pessoas não têm acesso ao Dev Mode.
- Tratar propriedades só de design e só de código como bugs, sem perguntar por que existem.
7. Vocabulário
| Termo | Significado |
|---|---|
| Afastamento (drift) | As versões de Figma e de código de um componente ficando diferentes aos poucos |
| Mapeamento de propriedades | A tabela que diz qual propriedade do Figma vira qual prop no código |
| Code Connect | O jeito do Figma de mostrar, no Dev Mode, o código real do design system para um componente |
| Arquivo de template | Um arquivo .figma.ts que define o trecho de código de um componente do Figma |
| Dev Mode | O espaço do Figma para quem desenvolve inspecionar designs |
| Servidor MCP | A interface pela qual ferramentas de IA de programação leem arquivos do Figma |
8. Experimente (sem ferramentas)
- Escolha um componente que seu time usa todo dia.
- Escreva as propriedades dele no Figma numa coluna e, depois de perguntar a alguém do desenvolvimento, as props do código em outra.
- Ligue com uma linha as que batem. Circule as que ficaram sem par.
Perguntas para refletir: Qual propriedade circulada você tiraria, e qual acrescentaria do outro lado? Quem no seu time atualizaria o mapeamento quando o componente mudar?
9. Se você já pratica
- Coloque a tabela de mapeamento na página de documentação de cada componente (veja Documentação de componentes que as pessoas usam).
- Faça de "template atualizado" uma linha na definição de pronto do componente.
- Confira seus componentes mais usados no Dev Mode: cada um mostra código real ou CSS gerado?
- Teste uma ferramenta de IA de programação numa tela com componentes conectados e não conectados, e compare o que volta.
Checklist
Para saber mais
- Figma developer docs: Code Connect · Writing template files · Connecting React components (legado) (todos conferidos em novembro de 2026)
- Figma Help Center: Guide to Dev Mode
Livros, cursos e vídeos para ir mais fundo
Os links dos livros são de afiliado da Amazon: como associado, recebo por compras qualificadas, sem custo a mais para você.
Relacionadas
Montar uma biblioteca no Figma · Tokens do Figma ao código · Anatomia e API de um componente · Handoff para desenvolvedores · Storybook e documentação viva