# Criando um design system no Figma com o Claude Code

> Guia passo a passo para criar um design system completo no Figma usando o Claude Code: tokens, componentes, variáveis e interfaces prontas.

![Ilustração 1](/api/guides-media/automation/figma-design-system-with-claude-code/images/figma-design-system-with-claude-code-step-01.webp)

## 1. O que é necessário para trabalhar

O Claude Code pode ser conectado diretamente ao Figma para criar um sistema de design completo do zero: variáveis, tokens, componentes e telas prontas. Neste guia, analisaremos todo o processo passo a passo — da instalação à tela final de login.

Antes de começar, certifique-se de que você possui:

- **Claude Code desktop app** — aplicativo com três modos: Chat, Code e Agentic.
- **Assinatura ativa do Claude** — uma conta gratuita não é adequada para este fluxo de trabalho.
- **Conta Figma** — com pelo menos um arquivo de trabalho aberto.
- **Tempo** — 30–45 minutos sem distrações para percorrer o fluxo de trabalho completo.

> [!WARNING]
> Este fluxo de trabalho consome os limites de uso do Claude. A montagem de um componente complexo, como um botão com mais de 120 variantes, pode consumir uma parte significativa do seu limite horário. Comece com tarefas mais simples para entender o processo antes de abordar grandes projetos.

![O que é necessário para trabalhar — Ilustração 2](/api/guides-media/automation/figma-design-system-with-claude-code/images/figma-design-system-with-claude-code-step-02.webp)

## 2. Instalando o Claude Code

Acesse [claude.ai/download](https://claude.ai/download) e baixe o Claude Code desktop app para o seu SO (macOS ou Windows).

Após a instalação, o aplicativo solicitará autenticação — faça login com os dados da sua assinatura do Claude. Em seguida, será aberta a interface com três modos:

- **Chat** — o Claude conversacional padrão.
- **Code** — para tarefas de escrita de código.
- **Agentic** — onde ocorre o trabalho principal com o Figma.

Para trabalhar com o Figma, utiliza-se o modo **Agentic**: é ele que permite ao Claude executar ações autônomas, incluindo o trabalho direto no seu canvas do Figma.

![O que é necessário para trabalhar — Ilustração 3](/api/guides-media/automation/figma-design-system-with-claude-code/images/figma-design-system-with-claude-code-step-03.webp)

## 3. Conectando o Claude ao Figma via MCP

Este é o passo crucial que torna todo o fluxo de trabalho possível. O Claude conecta-se ao Figma através de um servidor MCP (Model Context Protocol).

**Ordem de conexão:**

1. No aplicativo Claude Code, vá para **Settings**.
2. Abra a seção **MCP Servers**.
3. Clique em **«Add MCP Server»**.
4. Selecione **Figma** na lista de integrações disponíveis.
5. Autentique-se através da sua conta Figma (fluxo OAuth).
6. Após a conexão, o Figma aparecerá na lista de servidores MCP ativos.

**Como verificar se tudo está funcionando:**

Abra qualquer arquivo do Figma no navegador e faça uma pergunta simples ao Claude:

```text
Can you see my current Figma file? What's on the canvas?
```

Se o Claude descrever o conteúdo do seu arquivo — a conexão foi estabelecida. Caso contrário — verifique a configuração do servidor MCP e certifique-se de que o arquivo do Figma esteja aberto.

> [!TIP]
> Antes de começar a trabalhar, crie um arquivo separado no Figma ou uma página destacada dentro de um existente. Isso isola os experimentos dos materiais de produção.

![Passo 3 — Criando um sistema completo de variáveis com IA — Ilustração 4](/api/guides-media/automation/figma-design-system-with-claude-code/images/figma-design-system-with-claude-code-step-04.webp)

## 4. Criando um sistema completo de variáveis com IA

Em vez de criar manualmente dezenas de variáveis de cor, tipografia e espaçamento, o Claude monta toda a arquitetura de tokens por conta própria.

**Prompt para criar o sistema de variáveis:**

```text
In my Figma file, create a complete design token system with the following structure:

1. Primitive Colors — create a full range of colours: grays (50–900), primary blue (50–900), secondary green (50–900), error red (50–900), warning amber (50–900), and success green (50–900). Use industry-standard hex values.
2. Semantic Colors — create a semantic layer that references the primitive colours: background-primary, background-secondary, text-primary, text-secondary, text-disabled, icon-primary, icon-secondary, border-default, border-strong. Also add hover and active state variants for interactive elements.
3. Primitive Dimensions — create a spacing scale: 0, 2, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80. And a radius scale: 0, 2, 4, 8, 12, 16, 9999 (full round).
4. Semantic Typography — create a typography token system for: display-large, display-medium, heading-1 through heading-4, body-large, body-medium, body-small, caption, and overline. Include font family, font size, line height, and font weight as separate tokens. Also create Figma text styles and map the typography variables to them.
```

**O que o Claude cria como resultado:**

O Claude começa a trabalhar autonomamente no arquivo do Figma. Após alguns minutos, o painel Variables exibe:

- **Primitive Colors** — um conjunto completo de escalas de cores, organizado corretamente por coleções.
- **Semantic Colors** — todos referenciando corretamente a coleção primitiva (não valores hex hardcoded, mas vínculos reais).
- **Tokens de Interface** — fundo, texto, ícones e bordas com estados hover e active.
- **Sistema Tipográfico** — estilos de texto vinculados às variáveis correspondentes.
- **Tokens de Dimensão** — escalas de espaçamento e raio, prontos para uso.

Os tokens semânticos estão corretamente aliasados aos primitivos — isso significa que alterar uma cor primitiva propaga automaticamente por todo o sistema. É assim que se constrói um sistema de design robusto manualmente, só que aqui leva minutos, não horas.

> [!TIP]
> Após a geração, verifique os valores de cor conforme as diretrizes da sua marca. A IA escolhe defaults inteligentes, mas provavelmente o tom específico da sua marca difere do gerado. Altere os primitivos — e toda a camada semântica será atualizada automaticamente.

## 5. Criando um componente de botão complexo: 120+ variantes

O verdadeiro teste de estresse do fluxo de trabalho é um componente de botão não simplificado, mas com todo o rigor de um sistema de design.

**Prompt para criar o componente:**

```text
Create a button component in my Figma file with the following specifications:

Variants:
- Type: Primary, Secondary, Tertiary, Danger
- Size: Small (32px height), Medium (40px height), Large (48px height)
- State: Default, Hover, Active, Disabled
- Layout: Label only, Label + Leading icon, Label + Trailing icon, Icon only, Label + Leading icon + Trailing icon

Requirements:
- Use the variable tokens we just created for all colours, spacing, and radius
- Apply proper auto-layout with appropriate padding and gap values from our dimension tokens
- Use the correct text styles from our typography system
- For icons, use a simple placeholder icon (16x16 for small, 20x20 for medium, 24x24 for large)
- Make sure component properties are properly set up for easy variant switching
- Add proper naming convention: Button/[Type]/[Size]/[State]/[Layout]
```

A geração leva consideravelmente mais tempo e consome uma parte significativa do limite de uso. O resultado é um conjunto completo de componentes com mais de 120 variantes.

**O que funciona muito bem:**

- **Estrutura de auto-layout correta:** padding e gap adequados, tudo vindo dos tokens de dimensão.
- **Cores atribuídas precisamente:** botões primary usam cores primary, danger usa error-reds, tudo vindo dos tokens semânticos.
- **Estilos de texto:** aplicados corretamente a todas as variantes.
- **Propriedades do componente:** configuradas para alternância conveniente de estados.
- **Convenção de nomenclatura:** totalmente respeitada.

**O que exigirá ajustes manuais:**

- **Ícones:** O Claude tem dificuldade em criar ícones reais. São geradas formas placeholder, mas nem sempre precisas. É melhor especificar uma forma simples concreta («use a star shape» ou «use an arrow») ou substituir o vetor manualmente.
- **Estado de carregamento (Loading state):** o posicionamento do spinner pode ficar desalinhado devido ao posicionamento absoluto — requer um ajuste manual rápido.
- **Pequenas divergências no padding:** algumas variantes podem ter valores de espaçamento diferentes (a correção leva 2–3 minutos).

Para um componente cuja montagem manual do zero normalmente leva 2–3 horas — com variantes, tokens e auto-layout — o Claude executa cerca de 85% do trabalho corretamente. Os 15% restantes são um refinamento manual rápido.

## 6. Montando uma tela baseada no sistema de design

Teste final: o Claude conseguirá montar uma tela completa usando o sistema de design que acabou de criar? A condição chave — não gerar tudo novamente, mas usar os componentes e variáveis existentes.

**Prompt para criar a tela de login:**

```text
Design a login screen in my Figma file using the design system we've created.

Use the following specifications:
- Frame: 1440x900 desktop size
- Layout: Split screen — left side with a branded visual/illustration area, right side with the login form
- Right side form includes: Logo placeholder at top, "Welcome back" heading (use heading-2 text style), email input field, password input field with show/hide toggle, "Forgot password?" text link, primary login button (use our button component — large size, primary type), "Or continue with" divider, social login buttons (Google, Apple), "Don't have an account? Sign up" text at bottom
- Use our variable tokens for all colours, spacing, and typography
- Apply proper auto-layout throughout
- Left side: Use background-secondary colour with a centered placeholder for illustration
```

**O que o Claude monta como resultado:**

Uma tela de login pronta com estrutura correta. O layout geral é consistente — split-screen adequado, formulário bem organizado, design-tokens utilizados em toda a tela.

**O que impressiona:**

- **Reutilização do sistema:** O Claude usa exatamente o componente de botão criado, em vez de desenhar um novo retângulo estilizado como botão.
- **Hierarquia tipográfica:** heading styles, body text, caption — tudo retirado do sistema de tokens.
- **Espaçamentos consistentes:** alinhados exatamente pela escala de dimensões.
- **Composição geral:** profissional e pronta para handoff para desenvolvimento.
- **Auto-layout aplicado corretamente:** tornando a tela responsiva.

**O que exigirá refinamento:**

- Polimento visual dos botões de login social.
- O placeholder da ilustração no painel esquerdo é básico (isso é esperado).
- Pequenos ajustes de alinhamento nos espaçamentos internos do formulário.

O resultado não é um protótipo descartável, mas uma base sólida para o desenvolvimento futuro do produto.

## 7. Análise honesta: onde a IA brilha e onde falha

**Onde Claude + Figma funciona excepcionalmente bem:**

- **Sistemas de variáveis e tokens:** Aqui a IA mostra seu melhor. Uma arquitetura completa de tokens, que levaria horas manualmente, é montada em minutos, e a estrutura sai correta.
- **Scaffolding de componentes:** A geração do esqueleto de componentes complexos com auto-layout correto, properties configuradas e tokens economiza uma enorme quantidade de tempo.
- **Composição de telas:** A criação de layouts estruturados que utilizam componentes existentes e tokens do sistema de design gera resultados realmente úteis.
- **Consistência do sistema de design:** Como as regras são definidas previamente no prompt, o Claude mantém a consistência de forma mais rígida do que a maioria dos designers faz manualmente.

**Onde a IA ainda não atinge o nível:**

- **Nuances visuais:** A IA não possui gosto artístico. Os resultados são estruturalmente corretos, mas carecem das sutilezas que tornam o design verdadeiramente sofisticado.
- **Ícones e ilustrações:** O Claude lida mal com a geração de ícones decentes. Sempre forneça ícones de referência ou use plugins especializados.
- **Limites de uso:** Componentes complexos esgotam rapidamente os limites do Claude. Planeje suas sessões com antecedência.
- **Posicionamento:** absolute positioning e tratamento de overflow às vezes necessitam de limpeza manual.

> [!NOTE]
> **Resumo:** este workflow não substitui o pensamento de design. Mas comprime radicalmente a fase de execução. O Claude assume 70–85% do trabalho mecânico de montagem do sistema de design, liberando tempo para decisões que realmente importam: estratégia, cenários de usuário, edge cases e polimento visual.

## 8. Dicas de prompts: padrões que funcionam

Após praticar com este workflow, foram identificados padrões que consistentemente trazem melhores resultados:

- **Indique explicitamente o uso de tokens:** Escreva sempre «use the variable tokens we created», caso contrário o Claude pode hardcodar valores diretamente.
- **Defina a convenção de nomenclatura:** O Claude segue qualquer padrão de nomeação que você definir. Seja específico, senão obterá nomes inconsistentes.
- **Divida tarefas complexas em etapas:** Não peça para criar variáveis, componentes e telas em um único prompt. Faça isso sequencialmente.
- **Referencie elementos existentes:** Escreva «use our button component», em vez de «create a button», se quiser reutilizar o que já foi criado.
- **Defina dimensões explicitamente:** «40px height with 12px vertical padding and 16px horizontal padding» funciona melhor do que «medium size».
- **Sempre verifique o resultado:** Revise o Variables panel, Layers panel e propriedades dos componentes. A IA constrói a estrutura corretamente, mas os detalhes precisam do olhar humano.