Seu design system não está pronto para agentes
Design systems escritos só para humanos quebram quando viram contexto para IA. O próximo passo é tornar componentes, tokens e decisões legíveis por agentes.
Um design system pode estar organizado no Figma, bonito na documentação e ainda assim ser inútil para um agente.
Isso acontece porque a maior parte dos sistemas foi escrita para humanos. Um designer olha um componente, entende o contexto, lembra de uma conversa antiga, sabe quando abrir exceção e percebe quando uma combinação "fica estranha".
A IA não tem esse repertório interno. Se a decisão não está codificada, ela inventa.
E quando ela inventa, quase sempre volta para a interface genérica: card com sombra, botão azul, espaçamento médio, texto educado e nenhuma opinião de produto.
A IA é um novo usuário do design system
Tratar IA como usuário muda a conversa.
Se um usuário humano precisa de contraste, foco visível e mensagens claras, o usuário IA precisa de outra coisa: contratos.
Ela precisa saber:
- quais props existem;
- quais variantes podem combinar;
- quais tokens são semânticos;
- quais estados são obrigatórios;
- quais padrões são proibidos;
- quando deve sugerir e quando deve parar.
Documentação em prosa ajuda, mas não basta. Prosa explica. Contrato limita.
JSON para contrato, Markdown para julgamento
Uma divisão simples funciona bem:
- JSON para informação que não deveria variar: props, variantes, tamanhos, estados, tokens, relações entre componentes.
- Markdown para orientação: princípios, exemplos, critério de uso, tom de voz, erros comuns e decisões de produto.
O erro é jogar um monte de MDX em um MCP e chamar isso de design system pronto para agentes.
MCP busca contexto. Ele não transforma documentação confusa em critério de design. Se o material de origem é ambíguo, o agente só encontra ambiguidade mais rápido.
O que precisa ficar explícito
Um componente pronto para agentes precisa responder perguntas que normalmente ficam na cabeça do time:
- Identidade: o que esse componente é, e o que ele não é.
- Uso: quando usar, quando evitar, quando trocar por outro.
- Estados: loading, disabled, hover, focus, error, success, empty.
- Acessibilidade: semântica, labels, foco, contraste, teclado.
- Composição: com quais componentes ele pode aparecer.
- Tokens: nomes semânticos, não valores soltos.
- Risco: o que exige revisão humana.
Sem isso, a IA consegue montar uma tela que parece plausível. Mas plausível não é o mesmo que correto.
O papel do AGENTS.md
O AGENTS.md vira a porta de entrada do sistema.
Ele não deveria ser um manifesto gigante. Deveria responder:
- onde ficam tokens e componentes;
- quais comandos validam a mudança;
- quais arquivos não podem ser tocados;
- quais padrões devem ser reutilizados;
- quais decisões exigem revisão humana;
- quais critérios bloqueiam a entrega.
Esse arquivo é menos sobre "prompt" e mais sobre governança. Ele diz ao agente como trabalhar dentro da casa.
A parte invisível é a mais importante
O design system que o usuário vê é uma camada. O que o agente precisa entender inclui a parte invisível: critérios, relações, histórico de decisão, exceções e limites.
Por exemplo: um token chamado red-500 diz uma cor. Um token chamado danger.background diz uma função.
Para um humano experiente, isso parece detalhe. Para a IA, é a diferença entre repetir pixels e entender intenção.
Comece pequeno
Não precisa construir um servidor MCP completo no primeiro dia.
Comece com sementes:
- padronize nomes de tokens;
- escreva descrições de componentes com intenção, não só especificação;
- liste estados obrigatórios por componente;
- crie um JSON simples para cinco componentes críticos;
- escreva regras sempre ativas para cor, spacing, tipografia e foco;
- rode uma comparação: IA com documentação solta vs IA com contrato estruturado.
Se a segunda saída vier mais consistente, você tem evidência. Se não vier, o problema pode estar no próprio sistema.
A pergunta real
A pergunta não é "a IA consegue gerar interface?".
Consegue.
A pergunta é: ela consegue gerar uma interface que respeita o seu produto, o seu código, a sua acessibilidade e as decisões que seu time já tomou?
Se a resposta for não, o problema não é só da IA. É do sistema que você deu para ela ler.
Design systems sempre foram sobre consistência. Agora também são sobre legibilidade para agentes.
Quem entender isso antes vai ter uma vantagem muito prática: menos retrabalho, menos handoff quebrado, menos interface genérica e mais tempo para decidir o que realmente importa.
Referências
- Agentic Design Systems, Into Design Systems
- Design Systems MCP, Into Design Systems
- Towards an Agentic Design System, Into Design Systems
- Why design.md and skills.md aren't working, Evangeline Ng