design.md da Vercel ensina agentes a criar páginas on-brand

O problema: conhecimento de design preso no repositório

A Vercel usa agentes de codificação para criar páginas que precisam manter a identidade visual da empresa - tipografia, cor e composição com o mesmo critério das páginas feitas internamente. Para isso, a empresa já mantinha a skill product-design, que vive nos repositórios e ensina os agentes a encontrar e entender o design system e as diretrizes de produto. O problema surgiu com relatórios, propostas e páginas avulsas produzidas em ferramentas que não têm acesso a esses arquivos.

A resposta foi o design.md: um arquivo público, acessível por URL, que qualquer agente pode carregar. O time definiu dois requisitos: uma URL pública única que funcione em qualquer ambiente e uma orientação tão abrangente quanto a skill original, cobrindo marca, layout, escrita, design system, responsividade e arquitetura de informação.

Por que a abordagem simples falhou

A primeira tentativa foi portar product-design para um prompt público único. O resultado: modelos diferentes interpretavam a mesma descrição de formas muito distintas, gerando páginas bastante divergentes. Parte disso vem da subjetividade da linguagem de design - frases como "mantenha o layout limpo" significam qualquer coisa. Além disso, dentro dos repositórios, o agente lê a skill cercado por componentes reais e exemplos publicados; um prompt público não oferece nada disso, deixando cada modelo reconstruir o estilo apenas com palavras.

O sistema em três partes

O arquivo final evoluiu para três componentes:

1. design.md fornece orientação sobre como enquadrar a tarefa do leitor, estruturar evidências e escolher composições - de como preparar uma página para leitura executiva e auditoria detalhada até como publicar como a Vercel, incluindo regras para o wordmark e o logo triangular. O arquivo também nomeia padrões recorrentes de design gerado que nunca devem aparecer, o que ajuda os agentes a reconhecê-los e evitá-los.
2. Uma folha de estilos pública define um vocabulário limitado e documentado de classes e tokens - cabeçalhos, tabelas, stat strips e estilos de gráficos. Como os agentes continuavam inventando tipografia, espaçamento e layout próprios, essas decisões foram retiradas do modelo. O agente nem lê o CSS: ele carrega quando a página renderiza no navegador, economizando contexto.
3. Um laço de avaliação transforma feedback humano repetido em orientações melhores e verificações determinísticas.

O laço de evals

O time escreveu sete prompts de avaliação baseados em casos reais - relatório de uso e performance, proposta de renovação, relatório de benchmark, página de planejamento interativa, análise de build-versus-buy, brief de governança de segurança e deck de apresentação. Os prompts ficam congelados com entradas simuladas e configurações de viewport; só o design.md muda entre execuções. Rodadas completas cobrem os sete cenários no Claude Opus 4.8 e no Codex com GPT-5.5.

Um teste inicial mostrou que, sem o arquivo, o modelo gerava um painel SaaS genérico; com ele, a página de renovação passou a liderar com a recomendação, agrupar as evidências comerciais em um grid e colocar valores comparáveis na mesma escala - mudando estrutura e hierarquia, não só estilo.

Cada correção registrada em revisão vai para o lugar mais estreito que puder aplicá-la de forma consistente: mudanças de julgamento viram prosa no design.md, mecânicas reutilizáveis vão para a folha de estilos, e problemas verificáveis mecanicamente viram checagens em código. Falhas exclusivas de um modelo ficam de fora das regras até se repetirem. Um exemplo: tabelas de evidências espremidas na largura do texto geraram uma regra no arquivo e uma checagem determinística em código.

Resultados medidos, com ressalvas

O arquivo levou mais de 200 execuções para ficar pronto. Num teste final, três cenários de desktop gerados pelo Codex com GPT-5.5, com e sem o arquivo, mostraram 39 falhas conhecidas com design.md contra 91 sem - 57% menos. Os autores ressalvam: as checagens só capturam falhas já conhecidas e escritas; seis páginas é amostra pequena demais para afirmar qualidade; e todas as páginas, com ou sem o arquivo, ainda tinham ao menos uma falha grave o suficiente para bloquear a publicação. O teste mostra apenas que, quando uma falha é nomeada e codificada, ela tende a não voltar.

Manutenção pelo uso real

Internamente, o uso acontece via @design-agent, um agente construído sobre a plataforma eve no Slack, que carrega o design.md atual e devolve capturas de tela e URLs de deployment em threads. Semanalmente, o feedback do Slack, de revisões no GitHub e do Figma é agregado; reclamações repetidas viram propostas de mudança revisadas por pessoas, que decidem onde o ajuste pertence. A métrica é a frequência de cada tipo de reclamação ao longo do tempo: após codificar uma correção, a contagem deve cair.

Como replicar

O artigo fecha com um guia em seis passos: escolher um artefato recorrente com leitor e entradas reais; salvar a linha de base sem contexto de design; reescrever as últimas dez correções como critérios observáveis; publicar uma folha de estilos para mecânicas repetíveis; rodar uma comparação pareada cega; e codificar a correção no lugar certo, atualizando a orientação em vez de ajustar a página gerada à mão. Recomenda-se manter revisão humana nas mudanças finais e medir se cada tipo de reclamação de fato diminui na produção.