Como documentar um design system para que uma IA realmente o siga

O instinto é direcionar o agente para o site do design system. Isso raramente ajuda, por quatro razões estruturais que não têm nada a ver com a qualidade do site.

A linha de organização é a que as pessoas ignoram. Um site organizado por componente é perfeito para alguém que já sabe que precisa de um Button. Um agente prestes a construir uma tela ainda não decidiu quais componentes usar — suas primeiras decisões são sobre densidade, hierarquia e layout, e isso é exatamente o que um site organizado por componentes nunca cobre.

A linha de completude é a mais consequente. A documentação descreve o que existe porque é para isso que a documentação serve. Mas a diferença entre a sua interface e uma genérica é, principalmente, um conjunto de coisas que você nunca faz, e nenhuma página de componente jamais mencionará isso.

Amostramos 299 arquivos DESIGN.md publicados em repositórios e diretórios públicos — arquivos escritos deliberadamente para dar orientações de design a agentes de IA — e medimos seus conteúdos. 72 eram especificamente arquivos de visual design. O padrão é consistente o suficiente para ser usado como um checklist do que evitar.

Compare as duas últimas linhas. A tipografia é mencionada em 83% dos arquivos, mas 44% não contêm nenhum valor de tamanho concreto. Essa lacuna resume todo o problema em uma única estatística: os arquivos falam de tipografia sem nunca dizer o tamanho de nada.

O dado sobre adjetivos é a outra metade. "Clean" aparece em 39% desses arquivos, "modern" em 36%. Ambas são palavras que um modelo satisfaz produzindo o centro de sua distribuição de treinamento, que é precisamente o visual genérico que o arquivo foi escrito para evitar.

Cada uma delas corresponde a uma falha medida acima. Aplicadas em conjunto, transformam uma descrição em algo executável.

1. 1

   Atribua um papel a cada cor, não apenas um valor

   #6b7280 é um valor que um modelo usará para texto de corpo, bordas, ícones, placeholders e estados desativados indiscriminadamente. --text-muted, descrito apenas como texto secundário e de apoio, tem uma única função. Cinco papéis superam um hex, e permitem que você altere as bordas posteriormente sem alterar as legendas.

   Copy

   --text-muted: #6b7280   /* secondary and supporting text only */
   --border-subtle: #e5e7eb /* structural edges, dividers */
   --text-disabled: #9ca3af /* disabled controls only */

2. 2

   Substitua cada adjetivo por um número ou uma regra

   "Espaçamento generoso" torna-se "gap de seção 64px, padding de card 24px". "Tipografia clean" torna-se uma escala. Se uma frase não puder ser verificada em uma tela renderizada, ela é apenas decoração.

3. 3

   Escreva as proibições

   A seção de maior impacto individual, e a que 76% dos arquivos omitem completamente. Cinco linhas são suficientes para começar.

   Copy

   ## Never
   
   - No gradients
   - No drop shadows — elevation is a surface step plus a 1px border
   - No font-weight above 600
   - No colour value outside the token set
   - No border-radius above 12px

4. 4

   Defina o dark mode, não deixe que ele seja derivado

   Se deixado indefinido, o modelo inverte o light mode, e o resultado falha previsivelmente: as sombras param de funcionar, cinzas médios perdem contraste em ambas as extremidades e um destaque saturado que parecia confiante no branco causa glare no quase-preto. Um segundo conjunto de tokens custa uma hora de trabalho e elimina toda uma categoria de retrabalho.

5. 5

   Declare a decisão de densidade explicitamente

   Saber se esta é uma ferramenta densa ou uma superfície de marketing espaçosa altera cada escolha subsequente, e esta é a decisão que a maioria dos arquivos nunca toma. Se seu produto possui ambos os tipos de superfície, isso requer dois arquivos, e não um único arquivo ambíguo.

6. 6

   Nomeie pelo menos dois motivos

   Os elementos específicos e recorrentes que tornam o design único: uma linha de destaque de 2px à esquerda dos cabeçalhos de seção, colunas numéricas sempre tabulares e alinhadas à direita, uma maneira particular de desenhar estados vazios. 57% dos arquivos não possuem nenhum, e é por isso que a saída deles é correta, porém sem personalidade.

7. 7

   Aponte para o arquivo de tokens; nunca o repita

   Assim que um valor hex existe tanto no arquivo de design quanto no arquivo de tokens, um será atualizado e o outro não, e o modelo usará confiantemente o valor desatualizado. Faça referência, não copie.

O que as sete mudanças produzem, ao final, é um arquivo cujos valores um agente consegue resolver sem inventar nada. Esta é a mesma informação renderizada em vez de escrita — útil aqui como um checklist do que seu próprio arquivo deve ser capaz de responder:

Nem todas as proibições funcionam da mesma forma. Três propriedades separam aquelas que alteram a saída daquelas que são ignoradas.

A terceira linha é a que costuma ser ignorada. Uma proibição sem alternativa cria uma lacuna que o modelo precisa preencher, e ele a preenche com a mesma distribuição de treinamento da qual você estava tentando escapar. Todo "nunca X" deve ser seguido por "em vez disso, Y".

O arquivo precisa caber no contexto junto com a tarefa real, o que impõe um limite concreto. Cerca de 400 linhas é uma meta viável; além disso, regras individuais começam a perder a atenção para a tarefa.

A ordem também importa. Coloque a intenção e as proibições logo no início. Um modelo que lê de cima para baixo encontra a regra geral antes do caso especial, que é a mesma ordenação que a Stripe usa em sua Appearance API — primeiro o tema, depois as variáveis e, então, as regras específicas.

# DESIGN.md

## Intent            <- who reads this product, and what it is for
## Never             <- the prohibitions, early and unmissable
## Colour            <- roles for light and dark, referencing tokens
## Type              <- scale with real numbers, weight band, tracking
## Spacing & density <- the scale, and which surface uses which step
## Elevation         <- the strategy, stated once
## Composition       <- how components sit together
## Motifs            <- what makes this design specifically ours

Nem tudo deve estar no arquivo, e tentar encaixar tudo é o que o torna extenso demais para ser útil. A linha divisória é se o agente precisa da informação antes de decidir ou apenas sob demanda.

O servidor MCP do Carbon da IBM é um bom modelo para a primeira coluna: ele expõe a busca de documentação, exemplos de código de componentes, gráficos e componentes experimentais como ferramentas. Notavelmente, nada disso são proibições — porque uma ferramenta de recuperação apenas traz o que o agente pensou em consultar. Mais sobre a divisão.

Escrever o arquivo e assumir que funcionou é como as equipes descobrem o problema três semanas depois. Quatro verificações, em ordem crescente de esforço.

1. 1

   Use grep para buscar valores de cores literais

   Se o agente estiver seguindo as funções semânticas, não deve haver nenhum hex fora do seu arquivo de tokens.

   Copy

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

2. 2

   Use grep para buscar os pesos que você proibiu

   O peso é onde a hierarquia silenciosamente retorna ao padrão, e é o sinal mais rápido de que uma proibição não está sendo aplicada.

   Copy

   grep -rn --include='*.tsx' -E 'font-(bold|extrabold|black)' 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 diferirem significativamente em espaçamento, raio ou hierarquia, o arquivo não está restringindo o que deveria — e o diff dirá exatamente qual seção está faltando.

4. 4

   Construa primeiro uma tela em dark mode

   Se o dark mode foi derivado em vez de definido, é aqui que isso aparece. É muito mais barato descobrir na tela um do que na tela vinte.

As duas primeiras etapas devem estar no CI. Uma verificação que reprova um pull request contendo um valor hex bruto faz mais pela consistência a longo prazo do que qualquer documentação, que é a conclusão a que a Salesforce chegou com o linter do SLDS e a Stripe chegou ao remover a funcionalidade inteiramente.