Contexto
A Tradeverifyd tem dois produtos na mesma plataforma: o portal do cliente e uma ferramenta interna de admin. O time trabalhava com IA como parte essencial do processo.
Cada produto tinha o seu Button, Badge, Card, Table, Modal e empty state. Cada par nasceu de um momento real, em que alguém precisou de uma peça e a que existia estava no lugar errado. As regras de design viviam em documentos e na cabeça das pessoas, então cada tela ia se desviando um pouco: um tom novo aqui, um botão feito à mão ali.
O time não usava Figma. A plataforma mudava tão rápido que qualquer arquivo no Figma ficava defasado em relação ao que estava no ar, e uma designer trabalhando lá vira gargalo. Então eu desenhava direto no produto com o Claude Code, o que também me deixava consertar o sistema onde ele de fato vive.
O problema
Em 15 de outubro a gente percorreu o Storybook publicado, o catálogo de componentes do time, e anotou tudo que estava errado: 26 problemas de limpeza separados, três seletores de país diferentes (dois quebrados no Windows) e um catálogo em que o maior grupo, 23%, era um app de demonstração no meio dos componentes reais.
Olhar o uso real primeiro
Mapeei os dois sistemas por onde cada componente era usado de verdade. O Button próprio do portal do cliente tinha 29 usos, o compartilhado 24. Números assim transformaram um "vamos consolidar" vago numa lista que dava pra pôr em ordem.
Uma regra, 41 passos
Essa foi a regra que o time fechou, e eu escrevi a limpeza em volta dela, em 41 passos, 39 deles comigo. Quando a versão do admin fazia algo que a do cliente não fazia, essa capacidade era levada antes, pra ninguém perder nada.
Reestruturei o catálogo pelo que um componente é, não pelo produto de onde ele vem: Brand Book, Foundations, Components. O app de demonstração foi pra trás de uma chave, escondido mas não apagado. A página de Cores lê os estilos ao vivo, então não tem como ficar desatualizada.
Juntar, peça por peça
A ferramenta de admin agora usa o tema do cliente. Três seletores de país viraram uma família só. As listas do admin ganharam o empty state compartilhado, conferido no claro, no escuro e em tela estreita. Os estados de botão e os ícones batem nos dois produtos.
Cada mudança chegou primeiro pra mim como antes e depois, com telas reais, antes de qualquer outra pessoa ver.
Tipografia e cor
Levei o produto pra Inter e entreguei uma escala tipográfica de nove passos como tokens, cada passo com tamanho, entrelinha, peso e espaçamento, pra toda tela herdar.
Pra cor, levei contraste medido em vez de gosto, e registrei o que estava falhando: uma combinação de aviso em 1,85:1, um azul de ação abaixo do AA no tema escuro, nove controles sem nenhum hover. Com isso na mesa, o time decidiu: azul virou a cor de ação, pra uma ação nunca ser confundida com risco; o laranja da marca ficou só como identidade; o amarelo de aviso ficou mais vivo, com texto escuro em vez de branco.
Regras que se checam sozinhas
Um design system só se sustenta se alguma coisa continua checando ele. Então coloquei as regras onde toda mudança já é revisada: no pull request. O DS Police começou com 7 checagens automáticas: usar os tokens de cor, usar os componentes de verdade, nada de valor avulso. Antes de ligar, corrigi todos os lugares que já quebravam essas regras, 139 em 56 arquivos, pra o time começar do zero.
Descobrir o que ficava de fora
A contagem de cor ficava em zero, mas só porque cor era a única coisa que as regras olhavam. Então auditei 13 telas no ar do jeito que uma pessoa vê, não o código:
| Tela | Cores fora da paleta | Botões feitos à mão |
|---|
| Assistente, busca, monitoramento, perfil e ajuda | 0 | 0 |
| Mapa de fornecedores | 0 | 3 |
| Alertas | 0 | 20 de 48 |
| Documentação, umas 30 subpáginas | 0 | 12 a 15 por página |
Ensinar o design system real ao revisor
O revisor com IA comparava cada mudança com uma lista escrita à mão dos componentes. A lista estava desatualizada.
21componentes que o revisor conhecia
123componentes que existiam de verdade
Fiz a lista se montar sozinha a partir do produto. Depois criei as checagens do que o time tinha decidido mas nada garantia: a escala tipográfica, onde tinham se acumulado 408 tamanhos de fonte avulsos, e cores com nomes diferentes mas o mesmo valor, que é como 58 estados de hover não mudavam nada. Toda regra nova começou como aviso, com a condição pra virar erro escrita do lado.
Levar as decisões de design pra revisão
As instruções do revisor foram de 9 pra 19 regras, levando o que as nossas reuniões de design decidiram:
- "Pill" é a única palavra pra indicador de status. Badge, tag e chip saíram de uso.
- Uma pill é chapada e nunca é clicável.
- Navegação é link. Ação na mesma tela é botão.
- Componente novo precisa de uma story no catálogo.
Fazer valer
Por quatro meses as checagens só comentavam, e dava pra fazer o merge mesmo assim. Em 6 de outubro de 2026, a pedido do product owner, quebrar o design system passou a barrar o merge.
Resultado
Dois design systems mapeados em 41 passos, 39 deles comigo, a maioria entregue ou em revisão no fim de outubro. Três duplicatas já viraram uma só. Um catálogo organizado pelo que as coisas são, com as lacunas à vista: 48 de 123 componentes documentados.
E uma revisão que mantém tudo assim: cerca de 2.950 pull requests passaram pelo DS Police em cinco meses, 12 engenheiros citaram ele no próprio trabalho, e as violações foram de 139 pra 0 e ficaram lá.