Vercel usa arquivo DESIGN.md para agentes gerarem páginas on-brand

A Vercel usa agentes de programação para projetar e construir páginas com o mesmo julgamento visual das que publica - tipografia, cor e composição incluídas. Dentro dos repositórios, o skill product-design, que vive junto do código, orienta esses agentes. Para relatórios, propostas e páginas avulsas feitas em ferramentas que não leem esses arquivos, a resposta foi o design.md, um arquivo público que qualquer agente pode carregar.

Por que um prompt público não bastou

O arquivo precisava de uma URL pública única para apontar os agentes e orientação tão completa quanto a do skill. A primeira tentativa portou o product-design para um prompt público, mas cada modelo interpretava a mesma descrição de forma diferente e gerava páginas muito distintas: a linguagem de design é subjetiva (“mantenha o layout limpo” pode significar qualquer coisa), e o prompt não reproduzia o ambiente do repositório, onde a orientação convive com componentes reais e exemplos publicados.

A saída foi escrever o design.md do zero, testando cada mudança contra sete prompts fixos com dados simulados de casos reais - de relatórios de desempenho a apresentações. Numa primeira comparação, a mesma proposta de renovação sem o arquivo virou um dashboard genérico de SaaS; com ele, a página abriu com a recomendação e reuniu as evidências comerciais em uma grade comparável - mudando estrutura e hierarquia, não só o estilo.

Três camadas

O design.md concentra o julgamento: moldar a página para a leitura executiva rápida e para a auditoria detalhada, escrever copy com afirmações concretas e ressalvas honestas, compor hierarquia, tipografia e cor e publicar como a Vercel. Ele também nomeia padrões recorrentes de design gerado que a empresa nunca quer ver, para que os agentes os reconheçam e evitem.

A folha de estilos pública surgiu porque os agentes inventavam tipografia, espaçamento e layout: ela empacota primitivos do design system, como cabeçalhos, tabelas e gráficos, em CSS com classes e tokens documentados. O agente nunca lê o CSS, que carrega só na renderização e não ocupa contexto do modelo.

O ciclo de avaliação sustenta as demais camadas: checagens determinísticas pegam falhas mecânicas, como tabelas que ignoram a largura disponível, e pessoas julgam hierarquia, composição e se a página entrega o que o leitor veio buscar.

Correções e medições

Cada rodada gera uma página nova por cenário; as rodadas completas cobrem os sete em Claude Opus 4.8 e no Codex com GPT-5.5. Um aplicativo local de renders de página inteira e comparações A/B cegas virou o harness de revisão. Cada correção vai para o lugar mais estreito capaz de aplicá-la: julgamento vira prosa no design.md, mecânica reutilizável vira CSS e o que pode ser checado mecanicamente vira verificação em código. Uma tabela espremida na largura do texto, por exemplo, gerou regra e checagem, e as propostas seguintes saíram com tabelas em largura total.

O arquivo exigiu mais de 200 execuções. Para medir o efeito, três cenários de desktop foram gerados pelo Codex com GPT-5.5, com e sem o design.md e mantendo só a primeira tentativa: 39 falhas conhecidas nas checagens com o arquivo contra 91 sem ele - 57% menos neste teste. As ressalvas: as checagens só capturam falhas já anotadas, seis páginas são amostra pequena demais para afirmar qualidade e todas ainda tinham ao menos uma falha grave a ponto de bloquear a publicação. O que o teste mostra é que uma falha nomeada e codificada tende a não voltar.

Manutenção e replicação

Para manter o arquivo atualizado, a Vercel usa o @design-agent, construído sobre o eve: mencionado no Slack, ele carrega o design.md vigente, constrói a página e devolve captura e URL de deploy na thread. Toda semana, feedback de Slack, GitHub e Figma é agrupado por automação; reclamações repetidas viram propostas revisadas por pessoas, e cada tipo de reclamação deve ficar menos frequente depois que o ajuste é codificado.

O guia final ensina a replicar o ciclo: escolher um artefato recorrente com leitor real, salvar a linha de base sem o novo contexto, reescrever as últimas dez correções como regras observáveis, restringir a mecânica repetível em CSS e codificar cada correção na orientação, não na página gerada - sempre com revisão humana das mudanças finais. Os exemplos da Vercel são públicos; o design.md é carregado diariamente em v0, Codex e Claude.