Todo export do figmascope começa com um .zip contendo sete artefatos. O CONTEXT.md é o que é lido primeiro — por design. Não é um README. Não é documentação gerada automaticamente. É um contrato estilo compilador entre o design e o agente que vai transformá-lo em código.

Este post percorre o que ele contém, por que é estruturado desse jeito e o que dá errado quando você o ignora.

A diferença entre um contrato e uma documentação

Documentação descreve o que existe. Um contrato especifica o que deve ser verdade. Essa distinção importa quando seu leitor é um LLM que vai alegremente inventar valores de espaçamento, achatar hierarquias de layout ou hardcodar cores hex no momento em que não tiver uma opção melhor.

O CONTEXT.md abre com uma declaração de target:

# CONTEXT.md — Jetpack Compose target

This file is the authoritative spec for generating UI code from this bundle.
Read it before reading any other file.

O "Jetpack Compose target" não é decoração. O agente usa isso para escolher os primitivos composable corretos, lidar com unidades dp vs sp, entender que Modifier.padding() é a abstração certa para espaçamento e compreender que Box com Alignment é como você lida com layouts sobrepostos. Um target React/Tailwind gera um CONTEXT.md diferente com primitivos diferentes.

A instrução "leia isso primeiro" também é intencional. Agentes processam contexto sequencialmente. Se uma regra de token aparece depois que o agente já começou a raciocinar sobre um componente, a restrição chega tarde demais. Colocar o contrato no início significa que as regras estão ativas desde o primeiro token de geração.

A seção de restrições estritas

A parte mais crítica do CONTEXT.md é o bloco de restrições:

## Strict constraints (must follow)

- Never hardcode dp values if a token exists within ±2dp
- Never flatten layout hierarchy — preserve every stack/overlay/absolute node
- Use stringRef values from strings.json, never inline literal text
- Treat missing fields as absent, not zero
- Do not invent component names not present in components/inventory.json

Cada restrição existe porque já vimos agentes violá-la. A regra de ±2dp é o exemplo mais claro. Sem ela, um agente que encontrar gap: 14 em um nó stack vai escrever Arrangement.spacedBy(14.dp). Com a regra, ele sabe verificar se spacing.16 ou spacing.12 está dentro de 2dp e usar o token. Isso é uma saída diferente — uma que permanece coerente quando o valor do token muda, outra que não.

A regra de hierarquia existe porque o Compose é uma árvore de layout. Quando um agente achata um stack aninhado em uma lista plana de elementos posicionados, ele destrói o comportamento responsivo implícito pela estrutura original. A IR preserva cada nível de aninhamento por um motivo — veja IR por Tela — Stack, Overlay, Absolute, Leaf para entender como esse aninhamento codifica a intenção de layout.

A restrição não é "use os tokens se quiser". É "nunca hardcode se existe um token". Isso é uma proibição, não uma sugestão. LLMs respondem de forma diferente a proibições versus sugestões.

A regra de stringRef importa para i18n. Se um agente inline "Speed Test" em vez de referenciar a chave de recurso, você criou um buraco de localização. A restrição aponta o agente explicitamente para strings.json.

Como o agente lê o CONTEXT.md sequencialmente

Janelas de contexto de LLM processam tokens da esquerda para a direita. A estrutura do CONTEXT.md explora isso. A ordem é:

  1. Declaração de target (define todo o frame de geração)
  2. Restrições estritas (proibições que se aplicam a cada decisão)
  3. Mapa do bundle (quais arquivos existem e o que cada um contém)
  4. Regras de uso de tokens (como resolver espaçamento, cor, radius, tipografia)
  5. Notas de escopo (lacunas honestas — o que este bundle cobre e o que não cobre)

A seção de mapa do bundle diz ao agente quais arquivos ler e em qual ordem:

## Bundle contents

- tokens.json — design tokens (spacing, radius, color, typography)
- screens/*.json — per-screen IR in stack/overlay/absolute/leaf format
- components/inventory.json — component identity list
- strings.json — i18n resource keys
- _meta.json — generation metadata and warnings

Sem esse mapa, um agente pode não saber que components/inventory.json existe, ou pode tratar _meta.json como a spec principal. A enumeração explícita guia a ordem de leitura.

Notas de escopo — o que a v0.4 honestamente não cobre

A seção de notas de escopo é onde o figmascope documenta suas próprias limitações. Isso é deliberado e inegociável. Um agente que não sabe que uma spec está incompleta vai confiante preencher as lacunas com invenções. Isso é pior do que saber que a lacuna existe.

## Scope notes (v0.4)

- Gradient fills are not supported. Nodes with gradient fills emit a warning
  in _meta.json under warnings. Treat as a solid fill approximation or TODO.
- Typography tokens require Figma Variables to be populated. If tokensSource
  is "inferred-from-frequency" or "none", typography coverage may be partial.
- This bundle covers UI structure only. Navigation, state management,
  and network calls are outside scope.
- Component instances are identified by componentId. Full component
  source props are not included — the inventory gives identity, not implementation.

O aviso de gradiente é particularmente importante. O Figma suporta fills de gradiente complexos que não têm equivalente direto no Compose sem desenho customizado. Em vez de silenciosamente descartar gradientes ou gerar código quebrado, o figmascope emite um aviso background-gradient-not-supported:<name> em _meta.json e anota aqui para que o agente saiba tratar os nós afetados como lacunas conhecidas, e não como bugs em seu próprio output.

A nota de tipografia se conecta ao campo tokensSource em _meta.json. Quando um arquivo do Figma não tem Variables, o figmascope infere tokens por frequência — valores comuns viram tokens, valores raros não. A nota de escopo diz ao agente que essa inferência é imperfeita e que não deve presumir cobertura total de tipografia. Veja tokens.json Explicado para entender como o fallback de inferência funciona.

Exemplos ERRADO / CERTO

Vamos tornar isso concreto. Dado um nó stack com gap: 16 e um arquivo de tokens contendo spacing.16: 16:

Sem as restrições do CONTEXT.md (ERRADO):

Column(
    modifier = Modifier.padding(horizontal = 24.dp),
    verticalArrangement = Arrangement.spacedBy(16.dp)
) {

Com as restrições do CONTEXT.md (CERTO):

Column(
    modifier = Modifier.padding(horizontal = Spacing.spacing24),
    verticalArrangement = Arrangement.spacedBy(Spacing.spacing16)
) {

O output CERTO referencia tokens. Quando o sistema de design alterar spacing.16 de 16dp para 14dp, o código permanece correto sem uma busca e substituição na base de código.

Outro exemplo — tratamento de strings. Dado um nó leaf com text: "Speed Test" e stringRef: "speed.test":

ERRADO:

Text(text = "Speed Test")

CERTO:

Text(text = stringResource(R.string.speed_test))

A restrição aponta para strings.json, a chave é speed.test, e o agente sabe como mapear notação de ponto para IDs de recursos Android. Isso só é possível se o agente leu a restrição antes de gerar o componente.

Por que não simplesmente escrever o prompt você mesmo?

Você pode escrever essas instruções manualmente no seu prompt. O figmascope as externaliza em um arquivo porque:

O objetivo não é fazer prompt engineering em torno dos padrões do agente. É entregar uma spec que torna esses padrões irrelevantes.

Comparação com alternativas

O Dev Mode do Figma gera medidas, variáveis e snippets de código. Não produz uma spec. O agente que usa o output do Dev Mode precisa inferir regras a partir de exemplos — o que significa que vai inferir regras erradas para casos extremos.

Locofy e ferramentas similares geram código diretamente. Não têm equivalente ao CONTEXT.md porque não esperam que um agente leia uma spec — elas esperam ser o agente. Isso funciona quando a geração de código da ferramenta corresponde exatamente ao seu stack. Não funciona quando você tem convenções de nomenclatura específicas do projeto, uma biblioteca de componentes customizada ou um sistema de design com tokens que a ferramenta desconhece.

CONTEXT.md é um briefing de design legível por máquina. É a coisa que existia como uma página do Confluence ou documento Notion em todo handoff de design pré-LLM, apenas estruturada para uma audiência que realmente segue regras.

O que fazer com ele

Quando você abre um export do figmascope no Cursor ou Claude Code:

  1. Adicione @CONTEXT.md ao seu contexto antes de qualquer prompt sobre o design.
  2. Referencie o JSON da tela em que está trabalhando: @screens/home.json.
  3. Se estiver mexendo com tokens, adicione @tokens.json.
  4. Se estiver trabalhando com strings, adicione @strings.json.

As restrições do CONTEXT.md se aplicam durante toda a sessão após serem carregadas. Você não o adiciona a cada prompt — você o adiciona uma vez no início e deixa que enquadre cada geração subsequente.

Os outros artefatos do bundle são cobertos no restante desta série. Comece com tokens.json Explicado para entender como o sistema de tokens lida com arquivos com e sem Figma Variables, ou IR por Tela para entender como layouts do Figma mapeiam para nós stack/overlay/absolute/leaf. Quer experimentar? Cole seu URL do Figma no figmascope.dev e exporte seu primeiro bundle.