Design systems para agentes de código de IA

Peça a qualquer agente de código para "construir uma landing page" e você terá a mesma coisa: um hero quase preto, um gradiente violeta, Inter, três cards de funcionalidades com cantos arredondados. É competente e completamente genérico, porque o modelo não tem memória da sua marca entre os prompts. Adicione uma segunda página e a estilização começa a variar: espaçamentos diferentes, um azul ligeiramente diferente, um novo formato de botão. Não há uma fonte da verdade para o visual, portanto, não há consistência.

Vale a pena ser preciso sobre o porquê, pois a razão determina a solução. O modelo não está falhando no design. Ele está fazendo exatamente o que foi solicitado: produzindo a interface mais provável dado o pedido. Na ausência de uma restrição, a interface mais provável é o centro de tudo o que ele já viu, e qualquer pessoa que faça prompts sem restrições chega ao mesmo centro.

Isso reformula a solução. Você não está tentando tornar o agente mais criativo. Você está tentando tirá-lo do centro e mantê-lo em um lugar específico, o que requer declarar qual é esse lugar e o que está fora dele.

Amostramos 299 arquivos DESIGN.md publicados em repositórios e diretórios públicos (arquivos reais, escritos por equipes reais para dar orientações de design aos agentes) e medimos o que eles contêm, em vez do que alegam conter. 72 eram especificamente arquivos de design visual. O padrão é consistente o suficiente para ser diagnóstico.

A última linha é a prova. A tipografia é mencionada em 83% dos arquivos, e 44% desses mesmos arquivos não contêm nenhum valor de tamanho concreto. "Use uma hierarquia tipográfica clara" é uma menção. Não é uma instrução, e o modelo a satisfaz com qualquer hierarquia que seja mais comum em seus dados de treinamento.

Os dois números mais importantes são a cifra de proibições e a de papéis semânticos, e ambos falham da mesma maneira. Um arquivo que lista #3b82f6 como "primary" sem proibir nada disse ao modelo que um azul específico existe, mas deixou todas as decisões sobre onde usá-lo abertas. O agente então o utiliza em cabeçalhos, links, preenchimentos de ícones, bordas e gradientes, porque todos esses são usos plausíveis de uma cor primária.

Um design system que sobreviva a ser lido por um modelo, aplicado em vinte arquivos e retomado na sessão seguinte precisa de seis partes. Cada uma delas resolve uma falha específica.

A linha do dark mode é a que as equipes subestimam. Derivar o dark mode invertendo o light mode é o que um modelo faz quando nada diz o contrário, e isso falha de formas previsíveis: as sombras param de funcionar contra superfícies escuras, os cinzas médios perdem contraste tanto com o texto quanto com o fundo, e um destaque saturado que parecia confiante no branco torna-se cansativo no quase-preto. Defini-lo custa um segundo conjunto de tokens e elimina toda uma classe de retrabalho.

Um kit é um sistema completo, não apenas uma paleta. Abaixo está uma prévia ao vivo do kit gratuito ambient-sage: os mesmos tokens, fontes e tratamentos que um agente recebe ao aplicá-lo. Tudo nesta página poderia ser repintado apenas trocando o kit.

Independentemente de como você o instale, o conteúdo são as mesmas três coisas:

1. Um DESIGN.md: o briefing escrito: a intenção do design, o sistema tipográfico, regras de espaçamento e layout, tratamentos de componentes, motivos distintivos e o que fazer e o que não fazer. É isso que impede o agente de recorrer ao genérico. O que é um DESIGN.md e como gerar um.
2. Design tokens de cores semânticas: 28 papéis (background, foreground, primary, muted, card, border, chart-1…5, e mais) tanto para light quanto para dark mode. O agente estiliza com base nos nomes dos papéis, não em hexadecimais puros, para que os temas permaneçam coerentes. Design tokens de cores semânticas explicados.
3. Exportações de framework: o mesmo sistema como variáveis CSS, @theme do Tailwind v3/v4, um item de registro do shadcn ou JSON DTCG/W3C. O agente conecta aquele que for compatível com a sua stack.

Os nomes dos papéis no segundo item fazem mais trabalho do que parece. --color-muted-foreground diz ao modelo tanto qual é o valor quanto onde ele pertence; --gray-400 diz apenas o valor, e o agente então decide por conta própria qual cinza uma legenda deve ter. É nessa decisão que a consistência se perde, arquivo por arquivo.

A mecânica difere por ferramenta: agentes de código executam um servidor MCP local, construtores web utilizam o registro do shadcn ou o DESIGN.md exportado. Escolha sua ferramenta:

• Dê um design system ao Claude Code: MCP via .mcp.json ou identityforge apply.
• Dê um design system ao Cursor: MCP via .cursor/mcp.json, além de como estruturar os arquivos de regras.
• Dê um design system ao Windsurf: configuração manual de MCP para o Cascade, além do caminho da CLI.
• Dê um design system ao v0: o registro do shadcn + DESIGN.md como o brief.
• Dê um design system ao Lovable: conhecimento do projeto + shadcn add no repositório.
• Dê um design system ao Bolt: execute shadcn add diretamente no terminal do Bolt.

Ambos, e por razões diferentes. Vale a pena entender a distinção, pois instalar um servidor MCP esperando que o resultado visual seja melhor é uma decepção comum.

Proibições são o caso mais claro para o uso de arquivos. Um agente prestes a adicionar uma sombra projetada não tem motivo para perguntar "sombras projetadas são permitidas?", portanto, uma restrição que vive atrás de uma chamada de ferramenta é uma restrição que nunca é ativada. As restrições devem estar presentes antes da decisão. Mais sobre onde cada um se encaixa.

Navegue por kits por estilo visual para ver sistemas completos em contexto: tipografia, cor, superfícies e regras de construção. Cada kit possui um ID permanente e um slug legível; assim que você conhece um dos dois, o agente pode pular a busca e aplicá-lo diretamente. Slugs podem ser renomeados, mas o antigo continua resolvendo, então um identificador armazenado não fica obsoleto. Se você já possui cores de marca, a ferramenta MCP match_palette encontra os kits com a maior proximidade perceptual.

Instalar um design system e presumir que funcionou é como as equipes acabam sendo surpreendidas três semanas depois. Quatro verificações, em ordem crescente de esforço:

1. 1

   Grep por valores literais de cores

   O sinal mais rápido possível. Se o agente estiver seguindo design tokens semânticos, não deve haver hexadecimais fora do seu arquivo de tokens.

   Copy

   # any hex outside the token definitions
   grep -rn --include='*.tsx' --include='*.css' -E '#[0-9a-fA-F]{3,8}\b' src \
     | grep -v 'tokens\|globals.css'

2. 2

   Verifique os pesos de fonte

   O peso é onde a hierarquia silenciosamente retorna ao padrão. Se o seu sistema define apenas 400 e 600, qualquer outra coisa é desvio.

   Copy

   grep -rn --include='*.tsx' -E 'font-(bold|extrabold|black|semibold)' src | head -30

3. 3

   Peça a mesma tela duas vezes, em sessões separadas

   A consistência entre sessões é o teste real. Se duas execuções produzem espaçamentos, raios ou hierarquias significativamente diferentes, o sistema não está restringindo o que deveria.

4. 4

   Construa primeiro uma tela em modo escuro

   Se o modo escuro foi derivado em vez de definido, é aqui que isso aparece: sombras mortas, cinzas médios turvos, um destaque que ofusca. É mais barato descobrir agora do que depois de vinte telas.

As duas primeiras verificações valem a pena ser executadas no CI. Uma regra que detecta um valor hex bruto em um pull request faz mais pela consistência a longo prazo do que qualquer quantidade de documentação, que é a mesma conclusão que a Salesforce alcançou com o linter do SLDS.