Figma para Claude Code — Contexto de Design Estruturado para a CLI da Anthropic

A instrução "não reimplemente componentes que já existem" importa quando o inventário de componentes é compartilhado. O Claude Code pode ler design/components/inventory.json para identificar quais componentes já estão implementados e importá-los em vez de regenerá-los.

Conectando os tokens de design

O tokens.json exportado pelo figmascope usa uma estrutura aninhada inspirada no W3C com campos $value e $type:

{
  "color": {
    "surface":    { "$value": "#f6f2ea", "$type": "color" },
    "ink":        { "$value": "#1f1d1a", "$type": "color" },
    "accent":     { "$value": "#d96a3a", "$type": "color" }
  },
  "spacing": {
    "1": { "$value": "4px",  "$type": "dimension" },
    "2": { "$value": "8px",  "$type": "dimension" },
    "4": { "$value": "16px", "$type": "dimension" },
    "8": { "$value": "32px", "$type": "dimension" }
  },
  "typography": {
    "body": {
      "fontFamily": { "$value": "Inter",  "$type": "fontFamily" },
      "fontSize":   { "$value": "14px",   "$type": "dimension" },
      "lineHeight": { "$value": 1.45,     "$type": "number" }
    }
  }
}

Peça ao Claude Code para gerar um bloco de extensão de tema no tailwind.config.ts a partir desse arquivo como primeiro passo, antes de implementar qualquer tela. Assim, todas as implementações de telas subsequentes podem usar os aliases de token do Tailwind de forma consistente:

claude --print "Read design/tokens.json and generate a tailwind.config.ts
theme.extend block. Map color tokens to theme.extend.colors,
spacing tokens to theme.extend.spacing, and typography to
theme.extend.fontFamily / fontSize. Output only the config object."

Veja Design Token Export para Agentes de IA para uma análise aprofundada do formato de tokens e o fallback de inferência por frequência que o figmascope usa quando Figma Variables não estão configuradas.

Lidando com a camada de strings

Cada nó de texto no arquivo do Figma recebe uma entrada em strings.json. As chaves usam notação de ponto derivada da hierarquia de frames:

{
  "home.hero.title":        "Everything you need",
  "home.hero.subtitle":    "Ship faster with structured context",
  "home.cta.primary":      "Get started",
  "settings.account.heading": "Account settings"
}

Instrua o Claude Code a usar essas chaves como identificadores de i18n. Em vez de codificar a string "Everything you need" diretamente no JSX, o componente gerado chama t('home.hero.title') (ou o equivalente da sua biblioteca de i18n). O arquivo de recursos já está em strings.json — você só precisa importá-lo ou conectá-lo à sua configuração de i18n.

Se o figmascope detectar uma colisão — dois nós que resultam na mesma chave — ele emite um aviso strings-collision em _meta.json e acrescenta um sufixo numérico para desambiguar. Verifique _meta.json antes de iniciar uma sessão para saber o que esperar.

Integração com CLAUDE.md

Se você usa um arquivo de contexto de projeto CLAUDE.md, adicione uma seção curta apontando o agente para o diretório de design. Isso combina bem com a abordagem descrita em AI Design Handoff e complementa por que o figmascope difere dos plugins de inspeção do Figma.

Adicione uma seção de design como esta:

## Design context

Design tokens, layout IR, reference renders, and strings live in `design/`.
Always read `design/CONTEXT.md` before implementing any screen.
Token values are in `design/tokens.json` — never hardcode color or spacing.
Component canonical names are in `design/components/inventory.json`.

Isso significa que cada sessão do Claude Code no projeto terá automaticamente o contexto de design como parte do seu conhecimento de trabalho, sem que você precise repeti-lo em cada prompt.

O que o agente realmente acerta

Com contexto estruturado, o Claude Code acerta consistentemente:

• Valores de espaçamento — porque estão em tokens.json como spacing.4 → 16px, não estimados de uma captura de tela
• Cores — valores hex exatos, não "parece um laranja quente"
• Tipografia — família de fonte, tamanho, peso, altura de linha, todos tipados
• Direção de layout — nós stack têm um campo explícito de direction e gap
• Nomenclatura de componentes — inventory.json é a fonte canônica, sem nomes inventados
• Textos — strings.json impede que o agente parafraseie ou invente textos de placeholder

O que ainda precisa de revisão humana: estados de interação (hover, focus, active) que não estão visíveis em frames estáticos do Figma, timing de animações e breakpoints responsivos que não foram explicitamente projetados no arquivo. A IR captura layout estático; comportamento dinâmico está fora do escopo.

Usando --dangerously-skip-permissions em ambientes controlados

Para pipelines automatizados onde você quer que o Claude Code opere sem prompts de aprovação interativos — por exemplo, em uma etapa de CI que gera stubs de componentes após uma atualização de design — você pode usar --dangerously-skip-permissions. Adequado apenas em ambientes com sandbox e sem credenciais de produção.

claude --dangerously-skip-permissions --print "$(cat <<'EOF'
Read design/CONTEXT.md. Generate component stub files for any components
in design/components/inventory.json that don't already exist in src/components/.
Use TypeScript + React functional component format. Include a TODO comment
for each component referencing the relevant screen JSON.
EOF
)"

Em workflows de desenvolvedores em produção, deixe as permissões interativas. Os prompts existem por um bom motivo — o Claude Code pode e vai escrever arquivos, e você quer saber quais antes que ele o faça.

Verificando os avisos de exportação antes de enviar o prompt

O figmascope emite avisos em _meta.json para condições que podem afetar a qualidade do output. Verifique-os antes de iniciar uma sessão do Claude Code:

python3 -c "
import json
meta = json.load(open('design/_meta.json'))
for w in meta.get('warnings', []):
    print(f\"{w['code']}: {w['message']}\")
print(f\"Frames exported: {meta['frameCount']}\")
print(f\"Tokens source: {meta.get('tokensSource', 'variables')}\")
"

Dois avisos para prestar atenção:

• layout-mode-none-inferred — um frame não tinha auto-layout definido. O figmascope inferiu o layout a partir das posições absolutas dos filhos, o que é menos confiável. Sinalize a tela relevante no seu prompt: "Esta tela usa posicionamento absoluto; gere de acordo."
• strings-collision — dois nós de texto produziram a mesma chave de recurso. O figmascope desambigua com um sufixo numérico, mas você deve verificar se as strings em strings.json estão corretas antes de o agente gerar chamadas de i18n.

Workflows para Android e iOS

O Claude Code não está limitado a frameworks web. O bundle de contexto é agnóstico de framework — a IR de layout e os tokens são dados, não CSS. Para Jetpack Compose:

claude --print "$(cat <<'EOF'
Read design/CONTEXT.md and design/tokens.json.

Implement design/screens/Home.json as a Jetpack Compose screen.
- Map color tokens to a MaterialTheme ColorScheme
- Map spacing tokens to Dp values (strip 'px' suffix, use .dp)
- Map typography tokens to MaterialTheme.typography
- Use the component names from design/components/inventory.json as Composable names
- Reference design/screens/Home.png for visual accuracy
EOF
)"

Os nós stack da IR mapeiam naturalmente para Column (direction: vertical) e Row (direction: horizontal) no Compose. Nós leaf com type: "text" se tornam composables Text; type: "image" se torna Image ou um placeholder. Veja Jetpack Compose from Figma para o padrão completo.

Versionando o bundle de design

Trate o diretório design/ como qualquer outra dependência do projeto. Quando o design mudar significativamente, re-exporte do figmascope.dev, faça commit e anote a mudança no PR:

# Check when the bundle was last exported vs when Figma file was last modified
python3 -c "
import json
from datetime import datetime
meta = json.load(open('design/_meta.json'))
exported = datetime.fromisoformat(meta['exportedAt'].replace('Z', '+00:00'))
modified = datetime.fromisoformat(meta['figmaLastModified'].replace('Z', '+00:00'))
delta = modified - exported
if delta.total_seconds() > 0:
    print(f'WARNING: Figma file was modified {delta} after last export')
else:
    print('Bundle is current')
"

Um bundle desatualizado significa que o agente está trabalhando com um design obsoleto. A verificação de timestamp detecta isso antes de você gastar tempo em uma sessão de geração de código baseada em especificações superadas.