Aider + Figma — Programação em Dupla de UI a partir de um Bundle de Contexto

O Aider é um programador de par com IA baseado no terminal. Ele lê os arquivos que você especifica, gera edições como diffs unificados e os aplica diretamente na sua base de código. Cada mudança é revisável antes de entrar. Esse fluxo de trabalho centrado em diffs combina bem com o handoff de design token-aware — você pode ver exatamente se o código gerado está usando spacing.16 do arquivo de tokens ou se derivou para um 16px hardcoded.

Este guia cobre o pipeline completo Aider + figmascope: geração do bundle, carregamento em uma sessão do Aider, uso do modo Architect para o scaffold inicial e iteração com prompts de edição direcionados.

Pré-requisitos

Instale o Aider se ainda não tiver:

pip install aider-chat
# ou
brew install aider

O Aider suporta múltiplos backends de modelo. Os exemplos aqui usam Claude Sonnet via API da Anthropic, mas o fluxo de trabalho é idêntico com OpenAI ou modelos locais.

export ANTHROPIC_API_KEY=sk-ant-...
# ou OPENAI_API_KEY para GPT-4o

Passo 1: Gerar o bundle

Acesse o figmascope.dev, cole o URL do seu arquivo do Figma e clique em Export Agent Context. O exportador roda no seu navegador — seu token de acesso pessoal do Figma fica no localStorage e nunca sai da sua máquina.

O download chega como context-bundle.zip.

Passo 2: Descompactar no seu projeto

unzip ~/Downloads/context-bundle.zip -d ./design/

ls design/
# CONTEXT.md  _meta.json  components/  screens/  strings.json  tokens.json

Passo 3: Iniciar o Aider com os arquivos do bundle no escopo

Passe os arquivos do bundle que você precisa na linha de comando. O Aider os carrega como contexto de leitura — o modelo pode referenciá-los, mas não os editará a menos que você use explicitamente /add para promovê-los a arquivos editáveis.

aider \
  --read design/CONTEXT.md \
  --read design/tokens.json \
  --read design/strings.json \
  design/screens/home.json \
  src/screens/HomeScreen.kt

O padrão: --read para arquivos do bundle (apenas contexto, não editáveis), args posicionais para os arquivos de código que você quer que o Aider modifique. Isso mantém o bundle limpo — o mecanismo de diff do Aider não tentará editar tokens.json.

Se quiser que o Aider crie um novo arquivo em vez de editar um existente, basta nomear o caminho de destino que ainda não existe. O Aider o criará.

Passo 4: Adicionar PNGs de referência

O Aider pode incluir imagens como contexto para modelos multimodais. Use o comando /add após a inicialização:

/add design/screens/home.png

O PNG é um render 2× do Figma. Com um modelo multimodal (Claude Sonnet, GPT-4o), o Aider o inclui como referência visual. Use-o para verificações de sanidade durante a revisão — a spec canônica é o JSON, não a imagem.

Passo 5: Modo Architect — scaffold inicial

O comando /architect do Aider usa um modelo em dois passos: um passo para planejar, outro para implementar. Este é o ponto de partida certo para uma tela inteira, onde você quer uma estrutura coerente antes de editar partes individuais.

/architect Implement design/screens/home.json as a Jetpack Compose screen.

Context:
- Read CONTEXT.md for framework constraints and target conventions.
- All spacing, color, and radius values come from tokens.json.
  Map token keys directly: spacing.16 → 16.dp, color.7f5cfe → Color(0xFF7F5CFE).
- Use string keys from strings.json via stringResource() with the fallback field as the literal fallback.
- IR node kinds: stack(vertical)→Column, stack(horizontal)→Row, overlay→Box,
  absolute→Box+Modifier.offset, leaf(text)→Text, leaf(rect)→Box+Modifier.background.
- Do not hardcode any value that has a token equivalent.

Output to: src/screens/HomeScreen.kt

O Aider gera um plano primeiro, mostra a você e depois produz o diff. Revise o plano — se o mapeamento de nós parecer errado, corrija-o antes que o passo de implementação seja executado.

Passo 6: Editar arquivos específicos com referências de tokens

Depois que o scaffold estiver no lugar, use prompts /edit direcionados para corrigir problemas específicos. É aqui que o fluxo de trabalho de diff do Aider brilha — cada edição é uma mudança pequena e revisável, não uma regeneração completa.

The card component in HomeScreen.kt uses hardcoded 12dp for corner radius.
Check tokens.json for the correct radius token and replace it.

O Aider produz um diff mínimo: uma ou duas linhas alteradas, nada mais tocado. Você pode ver exatamente o que mudou.

Para uma auditoria de espaçamento em todo o arquivo:

Audit every .dp value in src/screens/HomeScreen.kt against the spacing tokens in design/tokens.json.
Produce a diff that replaces any hardcoded value with its token equivalent where one exists.
Leave a // TODO comment for any value that doesn't match a spacing token.

Passo 7: Revisar diffs contra a spec

A visualização de diff do Aider é a superfície de revisão. Antes de aceitar qualquer mudança, verifique:

As linhas adicionadas referenciam chaves de tokens, não valores literais?
Os literais de string aparecem em strings.json, ou são cópia de UI hardcoded?
O aninhamento de nós no código gerado corresponde à ordem pai-filho no JSON da IR?

Se um diff parecer errado, rejeite-o com n no prompt e diga ao Aider o que corrigir. O ciclo de feedback curto — prompt, diff, aceitar/rejeitar, refinar — significa que você detecta desvios imediatamente, em vez de depois que um grande bloco de código já entrou.

Por que o fluxo de diff do Aider combina bem com o bundle

O desvio de tokens é visível nos diffs. Se uma linha gerada diz color = Color(0xFF7F5CFE) em vez de color = tokens.colorPrimary, você vê isso antes de fazer o merge. Não há "verificar depois" — a revisão acontece inline.

O refinamento iterativo é barato. Você não está regenerando a tela inteira a cada mudança. Cada prompt de acompanhamento produz um diff direcionado. O bundle fornece o contexto estável; o Aider fornece a edição cirúrgica.

O bundle é versionado junto com o código. Quando o design atualiza, re-exporte o bundle do figmascope, faça diff em relação à versão anterior e peça ao Aider para aplicar apenas os nós alterados. O fluxo de trabalho escala em múltiplas iterações de design sem reimplementação completa.

Padrões comuns e armadilhas

Não adicione todas as telas de uma vez. Passe um JSON de tela por vez. Mais contexto nem sempre é melhor — o Aider (e o modelo subjacente) tem melhor desempenho com contexto focado do que com um dump de todas as telas do arquivo.

Use --read para o bundle, não args posicionais. Se você passar tokens.json como arg posicional, o Aider pode tentar editá-lo. Use --read para marcá-lo como contexto somente leitura.

Verifique _meta.json antes do primeiro prompt. O array warnings lista preenchimentos e efeitos que o exportador não conseguiu resolver completamente. Informe o Aider sobre eles antecipadamente para que ele não os aproxime silenciosamente:

cat design/_meta.json | python3 -c "import sys,json; w=json.load(sys.stdin).get('warnings',[]); print('\n'.join(w))"

Inclua quaisquer avisos no seu prompt de architect: "Skip hero-background fill — gradient not supported. Leave a TODO comment."

Prefira o Aider para edições cirúrgicas e revisáveis — e use Cursor ou Claude Code quando precisar de contexto de sessão completa em muitos arquivos. Os três fluxos de trabalho começam da mesma forma: o app principal do figmascope cuida do export no seu navegador.