Uma tela gerada por IA pode parecer pronta e ainda assim quebrar o padrão visual do sistema. Em projetos com IA, DESIGN.md entra para impedir que cada botão, card, sombra e regra de dark mode nasça com uma interpretação visual diferente.

Esse ponto transforma a decisão em algo concreto.md em projetos com IA ganha importância. O arquivo transforma design system em referência legível dentro do repositório, para que pessoa revisora e agente de código trabalhem com a mesma referência.

Eu não vejo DESIGN.md como decoração de documentação. Vejo como contrato visual do frontend: ele diz quais tokens existem, quais componentes devem ser usados, quais padrões são proibidos e como a interface deve ser revisada antes do merge.

Direto ao ponto

Use DESIGN.md para registrar tokens, tipografia, espaçamento, componentes, dark mode, responsividade, estados de tela e restrições visuais. Em projetos com IA, esse arquivo reduz improviso porque o agente consulta uma regra textual antes de escrever frontend, e a pessoa revisora ganha critério objetivo para avaliar o PR.

Como usar DESIGN.md para orientar frontend

Design system fora do repositório ajuda na conversa visual, mas nem sempre chega ao momento em que o agente escreve código. O DESIGN.md aproxima a regra da implementação. Ele não substitui Figma, componente real ou revisão humana; ele organiza a referência que todos precisam consultar.

Eu gosto desse formato porque agente de código trabalha melhor com instrução explícita. Se o arquivo diz que cores vêm de tokens, que botões usam componente existente e que todo fundo claro precisa de par escuro, a IA tem menos espaço para inventar estilo.

Esse raciocínio conversa com o post sobre como usar UX para orientar Vibe Coding. UX ajuda a definir fluxo, estado e comportamento. DESIGN.md ajuda a transformar essas decisões em regra visual aplicável no frontend.

Também existe vínculo com o artigo sobre começar pela interface antes do banco de dados. A interface mostra o uso. O arquivo de design system explica como esse uso deve aparecer com consistência no código.

O que um DESIGN.md precisa deixar claro

Um bom DESIGN.md não precisa virar tratado visual. Ele precisa registrar as decisões que afetam implementação e revisão. Se uma regra não ajuda o agente, a pessoa revisora ou o componente, talvez ela esteja no lugar errado.

Eu começaria por seis grupos:

• Tokens de cor: quais escalas existem e onde cada uma entra.
• Tipografia: tamanhos, pesos, hierarquia e limites de uso.
• Espaçamento: regras para gap, padding, margin e ritmo visual.
• Componentes: botões, cards, inputs, modais, tabs e estados esperados.
• Responsividade: comportamento mobile-first, breakpoints e limites de largura.
• Dark mode: pares de fundo, texto, borda e superfície.

Esse nível de regra reduz variação sem engessar criação. A pessoa ainda pode desenhar uma tela boa, mas precisa usar peças compatíveis com o sistema.

Figma continua útil, mas a IA precisa de texto

O Figma continua útil para protótipo, revisão visual e conversa com quem desenha interface. O problema aparece quando a implementação depende de o agente interpretar uma imagem, uma lembrança ou uma descrição vaga.

DESIGN.md traduz parte da decisão visual para texto. Ele explica que um botão primário usa determinado componente, que a cor vem de token, que o card tem raio definido e que a seção não deve criar wrapper próprio se já existe primitivo de layout.

Essa tradução importa em projetos com Astro, Tailwind CSS e componentes reutilizáveis. A IA pode gerar código válido, mas ainda precisa respeitar a gramática visual do projeto.

Eu não pediria para um agente “criar uma tela bonita”. Eu pediria para criar a tela usando os componentes permitidos, os tokens definidos, os estados previstos e o padrão de responsividade registrado.

Como usar o arquivo na revisão de PR

O melhor momento de cobrar DESIGN.md é no pull request. Se o PR mexe em frontend, a revisão deve perguntar quais regras visuais foram usadas e quais componentes existentes foram reutilizados.

Eu olharia quatro pontos antes de aprovar:

• Token: verificar cor, fonte e espaçamento contra a escala documentada.
• Componente: confirmar reuso de peça existente antes de criar uma nova.
• Estado: revisar carregamento, vazio, erro e sucesso.
• Tema: testar leitura em claro e escuro quando o projeto usa os dois.

Esse checklist deixa a conversa menos subjetiva. Em vez de “não gostei do visual”, a revisão aponta regra, componente, estado ou token. O resultado costuma ser ajuste mais direto e PR mais fácil de manter.

O post sobre quando criar skill para agente de código ajuda a fechar o raciocínio. Se revisão de frontend se repete, faz sentido criar uma instrução de agente para consultar DESIGN.md antes de editar interface.

IA não substitui design system aplicado

Um erro comum é achar que o arquivo resolve tudo por conta própria. Documento sem componente real vira referência fraca. Componente sem regra documentada vira memória de quem já conhece o projeto. O valor aparece quando os dois caminham juntos.

Eu prefiro uma combinação simples: DESIGN.md registra a regra, os componentes implementam a regra, o PR mostra a aplicação e a revisão confirma se a interface respeitou o contrato.

Isso vale ainda mais em Vibe Coding. A IA ajuda a escrever, ajustar e revisar, mas precisa de limite claro. Sem limite visual, ela tende a completar lacunas com padrões genéricos. Com limite documentado, a mudança nasce mais próxima da identidade do projeto.

No Co-work da Formação IA Makers, esse ponto aparece quando alguém pede uma tela inteira para a IA e recebe algo visualmente aceitável, mas desalinhado do restante do sistema. A correção não começa no pixel. Começa no cenário que faltou antes da geração. Quando menciono Co-work, estou falando do encontro ao vivo de trabalho acompanhado da Promovaweb; ele serve para tirar dúvidas e revisar problemas reais, e ajuda o leitor a comparar seu caso com exemplos práticos antes de avançar.

Perguntas frequentes sobre DESIGN.md em projetos com IA

O que é um DESIGN.md?

É um arquivo Markdown que documenta regras visuais do projeto para consulta no repositório. Ele pode registrar tokens, tipografia, espaçamento, componentes, responsividade, dark mode, estados de interface e restrições de estilo.

DESIGN.md substitui Figma?

Não. Figma ajuda a desenhar, prototipar e revisar visualmente. DESIGN.md ajuda a implementar e auditar no código. Os dois funcionam melhor quando cada um cumpre seu papel.

Quando vale criar DESIGN.md em um projeto pequeno?

Vale quando a IA gera frontend, quando mais de uma pessoa mexe na interface ou quando o projeto já tem componentes reutilizáveis. O arquivo evita que cada tela nasça com uma interpretação visual diferente.

O que não deve entrar no DESIGN.md?

Preferencia solta, paleta paralela, regra que ninguém aplica e texto promocional. O arquivo deve orientar implementação e revisão. Se a informação não ajuda o código ou o PR, ela provavelmente pertence a outro lugar.

Como fazer a IA seguir o DESIGN.md?

Inclua a leitura do arquivo na instrução do agente, no prompt ou na skill de frontend. Depois, peça que a mudança explique quais componentes, tokens e estados foram usados. A revisão humana fecha a validação.

Como medir se o DESIGN.md está funcionando?

Observe se novos PRs reutilizam componentes, evitam cor solta, tratam dark mode e reduzem retrabalho visual. O sinal bom é revisão mais objetiva, não quantidade de texto no arquivo.

O próximo passo é transformar regra em revisão

DESIGN.md funciona melhor quando participa do fluxo de desenvolvimento. Ele precisa orientar o prompt, o componente, o PR e a revisão visual.

Eu começaria com um arquivo curto, ligado aos componentes reais do projeto. Depois, ampliaria conforme a interface amadurece: tokens, tipografia, dark mode, estados, ícones, grids e padrões de página.

Para quem está criando software com IA e quer aprender a combinar interface, especificação, agentes e revisão técnica, a Formação IA Makers é o caminho natural dentro da Promovaweb.

Se o seu projeto já acumula telas inconsistentes, componentes duplicados e revisão visual subjetiva, faz sentido agendar uma conversa comercial com a Promovaweb para organizar design system, frontend e uso de agentes no repositório.