Como AI Coding Agents Leem Seu Design System (E Por Que a Maioria Erra)

ai-agents design-systems agents workflow design-md

Você tira screenshot do Figma. Cola no Claude Code. Digita “faz igual a isso.” Não fica igual.

O card vem com border-radius errado. Spacing 4px fora em tudo. O azul é #3B82F6 quando seu sistema usa #2563EB. Parecido o suficiente pra parecer proposital. Errado o suficiente pra incomodar.

Pergunta como eu sei.

Faz mais de um ano que eu shipo UI de produção com ai coding agents todo dia — Claude Code, Cursor, Kiro, Copilot. Todos têm o mesmo problema fundamental: eles não veem seu design system a menos que você entregue num formato que eles consigam parsear.

Não é burrice do modelo. É como context windows funcionam. E quando você entende isso, o fix leva sessenta segundos.

Como AI Coding Agents Processam Contexto

Quando você aperta Enter, o agent carrega tudo numa context window de tamanho fixo — sua mensagem, o arquivo aberto, arquivos referenciados, system prompts, definições de tools. Tudo compete pelo mesmo token budget.

Claude Code tem ~200K tokens. Cursor varia. Kiro tem budget próprio. Parece muito. Não é.

Um componente React médio consome 200-400 tokens. Seu tailwind.config.ts inteiro, 800-1200. O system prompt do agent sozinho come 3-5K. Adiciona uns arquivos de contexto e já queimou 15-20K antes do agent escrever uma linha sequer.

Prioridade importa. Agents leem arquivos mais ou menos nessa ordem:

  1. System instructions e config do agent (CLAUDE.md, .cursorrules, .kiro/)
  2. Arquivo aberto ou referenciado diretamente
  3. Arquivos mencionados no prompt
  4. Arquivos descobertos via imports ou estrutura do projeto

Se suas decisões de design moram num Figma, numa page do Notion, ou na sua cabeça — o agent nunca vê. Ponto.

Três Formas de Comunicar Design (Duas Falham)

Vi esse padrão se repetir em dezenas de projetos. Devs tentam três abordagens. Só uma sobrevive.

1. Screenshots e Imagens

Você cola um screenshot. O agent vê pixels por um vision model. Identifica “tem um card com shadow e um botão azul.” Não consegue extrair box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1). Não diferencia font-weight 600 de 700. Chuta.

Vision models aproximam. Não medem. Cada componente gerado vira uma interpretação livre em vez de implementação fiel.

Resultado: parece “similar” no primeiro olhar, reprova em toda revisão visual.

2. Colar CSS Cru ou Tailwind Config

Ideia melhor, execução pior. Você despeja o globals.css inteiro (3K tokens), o tailwind.config.ts (1.2K tokens), talvez um arquivo de componente como referência (600 tokens). São 5K tokens de contexto só pra design — e nenhum tem significado semântico.

O agent vê --color-primary: #2563EB mas não sabe quando usar em vez de --color-accent. Vê que rounded-lg existe mas não conhece sua regra: “cards usam rounded-xl, buttons rounded-lg, inputs rounded-md.”

CSS cru é dado sem intenção.

3. DESIGN.md — Estruturado, Leve, Semântico, Persistente

Um único arquivo Markdown na raiz do repo. Blocos YAML com valores exatos de tokens. Seções em prosa com regras e racional. 2-5K tokens no total. O agent lê automaticamente porque está onde agents olham primeiro.

Isso funciona. Não por ser sofisticado — por casar com a forma que agents consomem informação.

Por Que DESIGN.md Funciona Especificamente pra AI Coding Agents

Quatro propriedades. Todas importam.

YAML é parseável. Quando o agent lê primary: "#2563EB" num bloco YAML, ambiguidade zero. Não tá interpretando screenshot. Não tá chutando a partir de um nome de variável CSS. Tem o hex exato, o valor exato, o nome do token exato. Agents são modelos de linguagem — texto estruturado é o input nativo deles.

Prosa em Markdown fornece raciocínio. Entre os blocos YAML, você escreve regras: “Nunca use preto puro pra texto. Use gray-900 pra headings, gray-700 pra body.” O agent raciocina sobre essas regras do mesmo jeito que raciocina sobre comentários de código. Sabe por que escolher um valor em vez de outro.

~2-5K tokens é leve. Seu design system inteiro cabe em 2% da context window. Tá sempre ali. Nunca é truncado. Nunca compete com o código que o agent precisa escrever. Compara com colar um export do Figma ou design doc — 20K+ tokens que empurram o contexto de código pra fora.

Raiz do repo significa auto-discovery. Claude Code lê CLAUDE.md e qualquer arquivo referenciado. Cursor lê .cursorrules. Kiro lê config em .kiro/. Todos podem apontar pro DESIGN.md com uma única linha. Sem colar manual. Sem workflow de copy-paste. O agent encontra em toda sessão, em todo prompt, automaticamente.

Mesmo Prompt, Resultados Diferentes

O prompt: “Cria um componente de pricing card com três tiers — Free, Pro, Enterprise.”

Sem DESIGN.md: O agent improvisa. Escolhe um azul que parece “bonito” — provavelmente o blue-500 default do Tailwind. Cards ganham qualquer border-radius que pareça ok. Spacing segue os dados de treino do modelo, que é uma mistura de milhares de design systems diferentes. O resultado parece um template genérico de SaaS. Profissional o suficiente. Completamente irreconhecível como seu produto.

Com DESIGN.md: O agent lê seus tokens primeiro. Sabe que seu primary é #2563EB, cards usam rounded-2xl com shadow-sm, escala de spacing começa em incrementos de 4px, headings usam Inter weight 700, body usa 16px/24px. O pricing card sai parecendo que pertence ao seu app. Porque o agent tinha o mesmo documento de referência que seu time humano usa.

A diferença não é sutil. É a distância entre “quase, vou ajustar na mão” e “manda pro PR.”

Setup em 60 Segundos

Não é força de expressão. Literalmente um minuto.

  1. Vai na biblioteca de DESIGN.md. Pega um template que bata com seu stack (Tailwind, vanilla CSS, shadcn, tanto faz).

  2. Copia pra raiz do projeto. Edita os valores dos tokens pra bater com seu design system real. Cores, fontes, spacing, border-radius — o que você já sabe.

  3. Aponta o config do agent:

    • Claude Code: adiciona Read DESIGN.md before generating any UI component no seu CLAUDE.md
    • Cursor: referencia no .cursorrules
    • Kiro: adiciona no config .kiro/

Pronto. Próxima vez que pedir pro agent montar UI, ele lê seu design system antes. Toda vez. Automaticamente.

O Padrão Daqui Pra Frente

AI coding agents melhoram na geração de código todo mês. Não melhoram em adivinhar suas decisões de design. Isso não é problema de capacidade do modelo — é problema de contexto. E problemas de contexto têm soluções de contexto.

Entrega pro agent um arquivo estruturado que ele consiga parsear. Coloca onde o agent já olha. Mantém pequeno o suficiente pra nunca competir com contexto de código.

Isso é o que DESIGN.md é. Um formato de design system leve e agent-native.

Navega pela biblioteca pra templates prontos. Lê os guias de setup pro Claude Code, Cursor, ou Kiro. Você vai gastar mais tempo discutindo sua cor primária do que configurando isso.