O design system que se mantém: componentes, tokens e docs vivos
Todo design system nasce sincronizado e desalinha com o tempo, porque componente, token e documentação evoluem em velocidades diferentes. Um agente com acesso ao Figma, ao repositório e à doc audita esse desalinhamento continuamente, antes que ele vire bug visual em produção.
Toda empresa que cresce cria, em algum momento, um manual: a cor oficial da marca, a fonte, o espaçamento entre os elementos. No dia em que esse manual nasce, tudo bate, o documento, o produto, o material impresso, todos com o mesmo azul, a mesma fonte. Só que o tempo passa, alguém muda o azul no produto pra um tom mais escuro sem avisar ninguém, o manual continua com o azul antigo, e seis meses depois ninguém mais sabe qual é o azul de verdade da marca. Cada peça virou uma fonte própria da verdade, e elas discordam entre si sem que ninguém tenha decidido isso de propósito.
O time financeiro define a meta de margem bruta do trimestre numa planilha de modelo, 42%. O dashboard de BI que a diretoria acompanha todo dia foi configurado com essa meta há dois trimestres, e ninguém atualizou o parâmetro. O slide que vai pro board, por sua vez, foi copiado de uma versão anterior da apresentação e ainda traz 38%. Três lugares, três números pra mesma meta, e a reunião de board só descobre a divergência quando alguém pergunta, ao vivo, qual número está certo.
O escritório atualiza a cláusula padrão de reajuste do contrato de prestação de serviço depois de perder uma disputa sobre índice de correção. O modelo mestre no sistema de gestão de documentos foi corrigido. Só que o precedente salvo na base de pesquisa interna ainda cita a cláusula antiga como referência, e um contrato assinado dois meses atrás, gerado a partir de uma cópia local do modelo, também ficou pra trás. A divergência só aparece quando um cliente reclama de uma cláusula que a banca já achava superada.
O guia de marca define o azul oficial em hexadecimal, e o time atualiza esse valor depois de um reposicionamento visual. O CSS do site recebe a atualização na semana seguinte. Só que o material impresso que a distribuidora usa, um catálogo ainda em estoque, foi impresso com o azul antigo, e o slide institucional que o comercial usa em reunião também não foi atualizado. A marca falando três línguas diferentes ao mesmo tempo, sem que ninguém tenha decidido isso.
A matriz de cargos e salários define a faixa do nível pleno de engenharia. O modelo de carta de oferta que o recrutamento usa foi atualizado com a faixa nova. Só que a página de carreiras no site ainda mostra a faixa antiga, publicada há um ano, e um gestor recém-chegado, sem saber da atualização, oferece pro candidato o valor que ele lembra de uma conversa antiga. Três faixas diferentes pro mesmo cargo, circulando ao mesmo tempo dentro da própria empresa.
O PRD de uma feature nova define o critério de aceite com precisão. A feature entra em produção, mas com um ajuste de última hora que ninguém documentou de volta no PRD. O changelog que o suporte usa pra responder cliente ainda descreve o comportamento original, o que existia antes do ajuste. Quem descobre a divergência primeiro é o cliente, no chamado de suporte, não o time interno.
A tabela de preços oficial no CRM tem o valor atualizado depois do reajuste anual. A planilha de preços em PDF que um vendedor mais antigo guarda no computador ainda tem o valor do ano passado, e ele nem sabe que existe uma versão nova. Ele fecha negócio com esse preço antigo, de boa fé. A discrepância só aparece quando o financeiro concilia o contrato assinado com a tabela vigente.
O SOP (procedimento operacional padrão) do atendimento nível 2 é atualizado depois de uma revisão de processo. O material de treinamento novo entra na trilha do próximo mês, mas o time que já trabalha na operação continua seguindo o hábito antigo, porque ninguém avisou que o procedimento mudou. Três versões do jeito certo de fazer convivendo na mesma operação, e o SLA quebra silenciosamente.
A política de retenção de dados é atualizada pra bater com uma exigência nova da LGPD. O sistema que efetivamente aplica essa retenção, apagando dado depois de um prazo, continua configurado com o prazo antigo, porque a mudança de política não virou ticket de TI. O auditor confere o sistema, encontra o prazo velho, e o controle que parecia pronto no papel falha na prática.
A documentação da API descreve um campo como opcional depois de uma decisão de simplificar o contrato. O endpoint em produção, por descuido do deploy, continua exigindo esse campo como obrigatório. O SDK que os clientes usam pra integrar foi gerado a partir da documentação nova, então ele nem envia o campo, e a chamada quebra em produção pro cliente que seguiu a documentação à risca.
Terça de manhã, você abre o Figma pra desenhar uma tela nova e usa o componente Botão Primário da biblioteca. Ele está com o azul novo que o time aprovou semana passada. Só que quando o desenvolvedor implementa a tela, o componente de produção ainda usa o token antigo, porque ninguém atualizou o valor no código depois da mudança no Figma. E a documentação do design system, aquele guia que qualquer pessoa nova do time consulta, ainda mostra um print de tela de três meses atrás, com o azul mais antigo ainda. Três lugares, três versões da mesma verdade. Ninguém trapaceou, ninguém foi descuidado de propósito: cada lugar simplesmente evoluiu na sua própria velocidade, e o desalinhamento só aparece quando alguém repara que o botão tem uma cor num lugar e outra cor em outro.
O plano estratégico anual define a meta de expansão pra três novos mercados até o fim do ano. O sistema de OKR onde o time acompanha o progresso semana a semana foi configurado com essa meta no início do ano. Só que o relatório trimestral que vai pro board foi atualizado uma vez, quando a meta caiu pra dois mercados, e o OKR nunca recebeu essa correção. A reunião de revisão vira uma discussão sobre qual documento está certo, em vez de uma discussão sobre a estratégia em si.
Putz, deixa eu te contar a cena mais chata, e mais comum, de qualquer time que trabalha com design system. Você corrige o azul do botão no Figma numa terça de manhã, sente aquele alívio de resolvido, e três meses depois descobre que o produto em produção está com outro azul, e a documentação com um terceiro ainda. Ninguém mentiu. Ninguém foi desleixado de propósito. Cada lugar simplesmente seguiu o seu próprio ritmo, sem ninguém de plantão pra manter os três de mãos dadas. Esta aula é sobre esse desalinhamento que nasce sozinho, e sobre como colocar um agente pra vigiar ele antes que ele vire um bug que o seu cliente vê antes de você.
A ideia central desta aula. Todo design system nasce sincronizado: o componente do Figma, o token de design e a documentação escrita concordam entre si no dia em que você cria o sistema. O problema é que os três evoluem em velocidades diferentes, e ninguém tem tempo de manter os três atualizados ao mesmo tempo. É a entropia do design system: com o tempo, cada peça desalinha da outra, silenciosamente, até que um bug visual em produção expõe a divergência pro seu cliente. A saída não é confiar na memória de alguém pra manter tudo igual. É ter uma fonte única da verdade pro token, nome, valor e uso, e um agente com acesso ao repositório de código, ao arquivo de design e à documentação, auditando continuamente se os três ainda concordam. Você não evita o desalinhamento, ele é inevitável. Você passa a detectar antes que o cliente detecte por você.
Qual é o custo real de descobrir o desalinhamento do design system só quando ele vira bug visual em produção, em vez de detectá-lo por auditoria contínua?
Não conta nota. É para você ver o que já pensa — a aula responde logo abaixo.
01A entropia do design system: sincroniza uma vez, desalinha sempre
Pensa numa fundação recém-lançada, nivelada com precisão de milímetro no dia da concretagem. Ninguém espera que ela continue perfeitamente nivelada pra sempre sem manutenção, o solo se acomoda, a estrutura assenta, e é por isso que existe inspeção periódica de obra. Um design system funciona igual. No dia em que você cria o componente, o token e a documentação, os três nascem batendo. Mas cada um vive num lugar diferente, com um dono diferente e um ritmo diferente de atualização: o designer mexe no Figma quando redesenha uma tela, o desenvolvedor mexe no código quando entrega uma sprint, e a documentação, coitada, só é lembrada quando alguém precisa consultar e não encontra.
Ninguém decide desalinhar. É o resultado natural de três relógios correndo em velocidades diferentes. E o pior é que o desalinhamento não avisa: ele fica invisível até o dia em que alguém nota que o botão de um lugar não é o mesmo botão de outro, e nesse dia normalmente já é tarde, porque o cliente que reparou primeiro foi quem estava usando o produto, não quem estava mantendo o sistema.
02O token como fonte única da verdade
Aqui está a peça que resolve o problema pela raiz, em vez de remendar sintoma. Um token de design é o nome dado a um valor visual, "cor-primaria", "espaco-padrao", "raio-de-borda-card", junto com o valor exato que ele carrega e onde ele deve ser usado. A ideia central é simples de enunciar e difícil de manter sem ajuda: o token vive num único lugar, e Figma, código e documentação puxam desse lugar em vez de cada um guardar o próprio número separadamente.
Pensa assim: assim como um negócio precisa de uma ficha estruturada que a máquina consegue ler sem inventar, o seu design system precisa de um contrato estruturado, nome, valor, uso, que qualquer ferramenta consiga consultar sem adivinhar. Enquanto o token continuar sendo essa fonte única, mudar o azul vira um evento único, num lugar só, que se propaga. No dia em que cada peça volta a guardar o próprio número, você reabre a porta pra entropia da seção anterior.
Para o quadro. Token não é "a cor bonita que você escolheu". É o contrato: um nome estável ("cor-primaria"), um valor exato (o hexadecimal, o pixel, a escala), e uma regra de uso (onde ele deve aparecer). Se Figma, código e documentação concordam em ler esse contrato do mesmo lugar, eles não têm como discordar entre si. Se cada um guarda a própria cópia do valor, a discordância é só questão de tempo.
03O agente audita continuamente, você não precisa esperar o bug aparecer
Com o contrato definido, falta a parte que ninguém tem tempo de fazer manualmente todo mês: checar se as três pontas, Figma, repositório de código e documentação, ainda concordam com o token. É exatamente aqui que um agente com acesso às três fontes vira prático de verdade. Ele lê o valor do token no arquivo de design, lê o valor equivalente usado no código do componente em produção, lê o que a documentação afirma, e compara os três. Quando encontra divergência, ele aponta exatamente onde: "o Figma diz uma coisa, o código diz outra, a doc está desatualizada há X tempo".
Repara na virada que isso representa. Antes, você descobria o desalinhamento do jeito mais caro possível: um cliente reparando que um botão está diferente, ou um bug visual relatado em produção. Agora, a auditoria acontece antes disso, de forma rotineira, num ciclo que você define, semanal, a cada deploy, o que fizer sentido pro seu time. O agente não decide sozinho qual valor está certo, ele não sabe se o azul novo do Figma é intencional ou um erro de quem mexeu. Ele só mostra a divergência pra você decidir: atualizar o código pro valor novo, ou reverter o Figma pro valor antigo. A decisão continua sua. O trabalho de vigiar os três relógios, esse ele tira das suas costas.
04O mapa: manter é rotina, não evento único
Fecha o raciocínio desta aula com uma ideia que vale mais que qualquer ferramenta específica: manter um design system alinhado não é um projeto que termina, é uma rotina que continua. Você não "resolve" a entropia de uma vez por todas, você instala um jeito barato de detectar ela cedo, sempre. O token estruturado é a peça que dá ao agente algo objetivo pra comparar, sem isso ele estaria adivinhando igual a IA que lê um site sem schema. E a auditoria contínua é o que troca "descobrir pelo cliente" por "descobrir antes do cliente".
Isso fecha também com o que você viu nas aulas anteriores desta trilha: a pesquisa viva alimenta decisão com corpus real, o protótipo testado com usuário sintético reduz risco antes do humano de verdade, e agora o design system mantido garante que a decisão boa que você tomou continua valendo daqui a seis meses, e não vira uma exceção esquecida num canto do produto.
Agora construa
Escolha três componentes centrais de a sua tarefa real, os que aparecem em quase toda tela: por exemplo botão primário, campo de input, e card. Para cada um, confira se o nome e o valor do token batem nos três lugares:
- No Figma: abra o componente na biblioteca e veja o nome e o valor do token de cor (ou espaçamento, ou raio de borda) que ele usa.
- No código: peça a uma IA com acesso ao repositório pra localizar o componente equivalente e mostrar qual token (ou valor bruto, se não usar token nenhum) ele referencia.
- Na documentação: confira se o guia do design system, se existir, descreve o mesmo nome e o mesmo valor que você viu nos dois lugares anteriores.
Anote, pra cada um dos três componentes: bateu nos três lugares, ou você encontrou divergência? Se encontrou, essa é a sua primeira lista de pendências de manutenção, e é exatamente o tipo de checagem que um agente pode rodar rotineiramente, em vez de você repetir esse exercício manual todo mês.
Pratique
1. Por que um design system desalinha com o tempo mesmo quando ninguém foi descuidado de propósito?
2. O que faz um token de design funcionar como fonte única da verdade, em vez de mais uma cópia solta do mesmo valor?
3. Qual é o papel certo de um agente com acesso ao Figma, ao repositório de código e à documentação, na manutenção de um design system?
Beleza? Fecha comigo o recado desta aula. Todo design system nasce sincronizado e desalinha com o tempo, porque Figma, código e documentação evoluem em velocidades diferentes, e ninguém tem tempo de manter os três de mãos dadas manualmente. A saída não é vigilância heroica de uma pessoa só, é um token que funciona como fonte única da verdade, nome, valor, uso, e um agente com acesso às três pontas auditando continuamente se elas ainda concordam. Você troca "descobrir o bug pelo cliente" por "descobrir na rotina de auditoria, antes que ele chegue lá". Manter um design system não é um projeto que termina, é um hábito que você instala uma vez e repete sempre. Próxima.
Valeu pelo feedback. Isso ajuda a afiar a próxima aula.