DesignsystemqueagentesdeIAseguem

No design system de um produto jurídico que construí com IA, uma equipe de 13 agentes aplicou o sistema, um agente por tela. Zero classe nova foi criada. Os 53 bloqueios que eles relataram convergiram para um único arquivo de componentes compartilhados. O que fez isso funcionar não foi o componente. Foi a regra estar escrita no lugar que o agente lê antes de mexer na interface.

A lição vem de antes. A Eduzz não é um produto, é um ecossistema: checkout, área de membros, painel do produtor, ferramentas de marketing, apps. Cada um nasceu num momento diferente, com um time diferente, e carregava as próprias escolhas de botão, cor e espaçamento. Para quem usava, parecia que cada parte era de uma empresa. Para quem construía, era o mesmo componente desenhado e implementado várias vezes.

Atuei como product designer num projeto que desenvolvi para a Eduzz: o Houston, o design system criado para resolver isso. A primeira decisão não foi de componente. Antes de desenhar qualquer coisa, o projeto alinhou com o time da Eduzz para que o sistema existia, e escreveu seis objetivos: reduzir o tempo para lançar, facilitar a manutenção global, padronizar a consistência, apoiar decisões de produto, engenharia e design, valorizar o aprendizado e oferecer um ecossistema de componentes. Eles viraram a primeira página da documentação e o critério do que entrava. Cada componente precisava servir a pelo menos um.

A lição que eu levei não foi o componente mais bonito. Foi que um design system é um produto interno, e o usuário dele é o time. Depois do Houston, apliquei isso em sistemas bem menores, em produtos que construí com agentes de IA. A escala mudou, e o usuário também: quem consome o sistema passou a ser, em boa parte, um agente escrevendo telas. Um agente não pergunta no corredor. Ele lê o que está escrito e segue. Se a regra não estiver lá, ele inventa. As regras do Houston continuaram valendo, com uma exigência a mais: estar onde a IA lê.

Objetivos como filtro

Um sistema sem objetivo cresce por acúmulo. Cada pedido vira componente, e logo existem três variações de card e ninguém sabe qual usar.

No Houston, o objetivo servia de filtro: um pedido que não servia a nenhum dos seis não entrava, e havia um motivo escrito para dizer isso. No Glint, a mesma função foi cumprida por um contrato de design, um arquivo de regras que todo agente lia antes de mexer em interface. Uma das regras era de sentido, não de estética: a cor principal significa ação e navegação; a secundária, identidade e dados. Aplicada nos componentes compartilhados, essa regra valia em todas as telas sem ninguém precisar lembrar dela.

Camadas: onde cada decisão mora

O Houston foi organizado em quatro camadas. É o organograma que mais importa num design system, porque diz onde uma mudança acontece.

• Houston
  • Tokens globaiscor, tipografia, espaçamento, raio, sombra
  • Tokens de marcauma paleta por produto, mesma estrutura
  • Componentesbotões, formulários, feedback, navegação
  • Conteúdodiretrizes de escrita e tom

Os tokens são o que torna a camada acionável. Quando cor e espaçamento são variáveis nomeadas, uma mudança acontece num lugar e se propaga. Vi isso funcionar de forma quase brutal nos meus produtos:

• No Glint, o design system escuro por padrão tem cerca de 17 componentes e foi aplicado a umas 50 telas. A regra era nunca usar cor fixa no código, só token, e o tema claro e o escuro saem das mesmas variáveis.
• No Kitnets, o visual passou por dois redesenhos. O segundo trocou um índigo genérico por um tom editorial quente, com títulos serifados e ação principal em preto. Como tudo era variável, a troca chegou a todas as telas de uma vez, e ajustar o tom do laranja passou a ser uma linha.

Governança: quem decide

Nathan Curtis, da EightShapes, descreveu modelos de time que viraram referência, entre eles o centralizado e o federado. Muitos times acabam num híbrido.

	Centralizado	Federado	Híbrido
Quem mantém	Um time dedicado	Pessoas dos times de produto, em parte do tempo	Um núcleo pequeno, com contribuidores dos produtos
Ponto forte	Consistência e decisões rápidas	Proximidade com a necessidade real	Curadoria do núcleo com o conhecimento dos produtos
Ponto fraco	Vira gargalo e se afasta dos produtos	A prioridade do produto sempre vence	Exige processo de contribuição claro

O que os meus projetos mostram é o modelo mais simples: um mantenedor e times que consomem. No Houston, o mantenedor era o time de design system da Eduzz; os consumidores, os times dos produtos do ecossistema. Nos meus produtos, o mantenedor era eu, e os consumidores eram os agentes que implementavam as telas, um por tela, com fronteiras de arquivo que não se cruzavam.

• Mantenedor do sistemadecide o que entra, pelos objetivos
  • O que ele mantém
    • Tokens e componentes
    • Documentação com as mesmas abas
    • Contrato de regras escrito
  • Quem consome
    • Times de produtono Houston
    • Agentes que montam telasnos produtos próprios
  • Rota de contribuiçãorecomendado: problema, triagem, desenho, código, documentação

Com agentes como consumidores, uma coisa fica evidente: o sistema só é seguido se a regra estiver escrita onde o consumidor lê. Foi o que aconteceu no produto jurídico, com os 13 agentes. A fronteira de arquivo não só evitou colisão: produziu um relatório de onde o sistema não atendia, porque cada bloqueio apontava para o mesmo lugar.

Regras escritas onde a IA lê

Um time de pessoas tolera documentação incompleta. Alguém pergunta, alguém lembra, alguém olha a tela ao lado. Um agente não faz nada disso. O que não está escrito no caminho dele não existe.

Nos meus produtos, isso virou três hábitos:

• Um contrato antes da tela. No Glint, um arquivo de regras que todo agente lia antes de mexer em interface. Ele dizia o sentido das cores, e não só o valor: a principal é ação e navegação; a secundária, identidade e dados.
• Uma regra de mudança curta e absoluta. No Kitnets, nada renomeado, só valores e acréscimos. Cabe numa linha, e um agente consegue obedecer sem interpretar.
• As armadilhas junto do componente. No produto jurídico, cada classe perigosa foi descoberta por uma tela quebrada. Hoje eu escrevo o “não use assim” ao lado do “use assim”.

O mesmo vale para quem automatiza qualquer operação com IA. A IA só segue a regra do negócio que está escrita onde ela lê. O resto ela preenche do jeito dela.

Contribuição: começar pelo problema

Se qualquer um adiciona componentes, o sistema vira gaveta. Se ninguém pode, vira gargalo. O processo de contribuição é o meio-termo.

1. 01Proposta

   O problema e as telas onde ele aparece, não o componente pronto.

2. 02Triagem

   Já existe algo? Serve a qual objetivo? Aparece em mais de um produto?

3. 03Desenho

   Variantes, estados, anatomia e acessibilidade.

4. 04Código

   Implementação, testes e revisão da API.

5. 05Documentação

   Uso, quando não usar, exemplos. Sem isso, não publica.

O critério de “mais de um produto” é o que mais uso: um padrão que só uma tela usa pode continuar local. Quando a segunda precisa, é hora de promovê-lo.

Mudar sem quebrar

Os times só confiam no sistema se a atualização for previsível. O padrão comum é o versionamento semântico: correção, adição compatível e mudança incompatível, com changelog escrito para pessoas, depreciação antes da remoção e guia de migração.

Em sistema pequeno, a versão conta menos que a disciplina. No Kitnets, a regra do design system era nada renomeado, só valores e acréscimos. Num dos redesenhos, o cabeçalho de página passou a renderizar o novo componente de destaque por dentro, sem mudar a interface dele. As 22 páginas ganharam o cabeçalho novo mudando um arquivo, e nenhuma quebrou.

Documentação com as mesmas abas

No Houston, a página de cada componente tem as abas Design, Uso, Código, Acessibilidade e Como testar. Quem chega de design ou de engenharia encontra a mesma fonte da verdade. Quando os dois leem páginas diferentes, cada um constrói uma versão do componente.

A documentação também é onde moram as armadilhas, e elas precisam estar escritas. No design system do produto jurídico, eu paguei por cada uma:

• Uma classe chamada .pagina nascia invisível por padrão, porque servia de roteador no catálogo do sistema. Usá-la numa tela real deixava a tela em branco, sem erro nenhum.
• A classe de tabela impunha cabeçalho em caixa alta. Aplicada ao texto gerado pelo agente, distorcia o conteúdo; foi preciso uma variante própria.
• Uma classe tinha três referências no código e nunca tinha sido definida.

Nomes genéricos como esses são convite ao uso errado. O nome de uma classe é documentação, e uma que parece servir para tudo vai ser usada para tudo.

Métricas de adoção

Se é produto, precisa de métrica, e de uso, não de produção:

• Cobertura: quantas telas usam o sistema.
• Desvios: valores soltos no lugar de token. No Kitnets, um pente-fino com agentes varredores achou 42 desvios depois do redesenho, de títulos soltos a cores fixas.
• Resíduo do padrão antigo: depois do redesenho do Kitnets, o critério de pronto incluía a cor antiga não aparecer em nenhum lugar do código publicado.
• Perguntas recorrentes e tempo de contribuição: se demora demais, os times constroem por fora.

“Número de componentes” fica de fora, de propósito. Muitos componentes com pouca adoção é catálogo, não sistema.

O que eu faria diferente

• Escrever as armadilhas no próprio sistema. No produto jurídico, cada uma foi descoberta por uma tela quebrada. Uma lista de “não use assim” na documentação teria poupado todas.
• Decidir a fronteira do sistema. No Kitnets, o site público ficou fora do segundo redesenho porque não consumia os estilos do pacote de componentes. Um sistema que não cobre todas as superfícies do produto deixa uma delas com cara de outra empresa, que é exatamente o problema que o Houston existia para resolver.
• Validar a direção antes do rollout. No Kitnets, eu mesmo recusei o primeiro cabeçalho novo, com ícone, depois de vê-lo aplicado. Como era um componente só, voltar foi barato; num sistema sem essa camada, teria sido retrabalho em todas as telas.

Checklist do design system como produto

• Os usuários do sistema, pessoas ou agentes, estão identificados?
• Existem objetivos escritos, usados como critério do que entra?
• As camadas (tokens globais, de marca, componentes, conteúdo) estão separadas?
• Há um mantenedor claro e uma rota de contribuição que começa pelo problema?
• Mudanças seguem uma regra que não quebra quem já usa?
• Design e código documentam cada componente na mesma página, com as mesmas abas?
• As armadilhas e os nomes perigosos estão escritos?
• As métricas medem adoção e desvio, e não quantidade de componentes?

Um design system que ninguém consulta não padroniza nada. O trabalho começa quando o componente é publicado, porque é aí que alguém, pessoa ou agente, tenta usá-lo.